{% extends "base.html" %}

{% block content %}
<div class="row g-0 help-container border rounded shadow-sm bg-white overflow-hidden">
    <!-- Sidebar: Table of Contents -->
    <div class="col-md-3 border-end bg-light help-sidebar">
        <div class="p-4 sticky-top" style="top: 0;">
            <!-- Desktop-only Logo -->
            <div class="d-none d-md-block text-center mb-4">
                <img src="{{ url_for('static', filename='img/archivum.png') }}" 
                     alt="Archivum Logo" 
                     class="img-fluid help-logo rounded shadow-sm">
            </div>

            <h5 class="fw-bold mb-4 text-primary">Documentation</h5>
            
            <!-- In-page Search -->
            <div class="mb-4">
                <div class="search-wrapper">
                    <input type="text" id="help-search" class="form-control form-control-sm border-2" placeholder="Search help..." onkeyup="searchHelp()">
                    <i class="bi bi-x-circle clear-input" onclick="document.getElementById('help-search').value=''; searchHelp();"></i>
                </div>
            </div>

            <nav id="help-toc" class="nav flex-column small fw-medium">
                <a class="nav-link py-1 px-0 text-dark active" href="#intro">Introduction</a>
                <a class="nav-link py-1 px-0 text-dark" href="#architecture">Architecture</a>
                <a class="nav-link py-1 px-0 text-dark" href="#query">Query Syntax</a>
                <a class="nav-link py-1 px-0 text-dark ps-3 border-start ms-2" href="#query-simple">Simple Filters</a>
                <a class="nav-link py-1 px-0 text-dark ps-3 border-start ms-2" href="#query-advanced">Advanced Querexfuzz</a>
                <a class="nav-link py-1 px-0 text-dark" href="#bibtex">BibTeX Format</a>
                <a class="nav-link py-1 px-0 text-dark" href="#screens">Screen Guide</a>
                <a class="nav-link py-1 px-0 text-dark ps-3 border-start ms-2" href="#screen-query">Query Page</a>
                <a class="nav-link py-1 px-0 text-dark ps-3 border-start ms-2" href="#screen-network">Network & Discovery</a>
                <a class="nav-link py-1 px-0 text-dark ps-3 border-start ms-2" href="#screen-ripgrep">Ripgrep (Full-Text)</a>
                <a class="nav-link py-1 px-0 text-dark ps-3 border-start ms-2" href="#screen-reports">Report Studio</a>
                {% if is_admin %}
                <a class="nav-link py-1 px-0 text-dark ps-3 border-start ms-2" href="#screen-ingest">Ingest (Admin)</a>
                <a class="nav-link py-1 px-0 text-dark ps-3 border-start ms-2" href="#screen-edit">Editor (Admin)</a>
                {% endif %}
                <a class="nav-link py-1 px-0 text-dark" href="#regex">Regular Expressions</a>
            </nav>
        </div>
    </div>

    <!-- Main Content Area -->
    <div class="col-md-9 help-content p-5 overflow-auto">
        <section id="intro" class="mb-5">
            <h2 class="fw-bold mb-3">Introduction</h2>
            <p class="lead text-muted">Archivum is a personal document and reference management system designed for high-performance indexing and retrieval of academic papers, books, and technical documents.</p>
            <p>Unlike traditional managers, Archivum prioritizes <strong>identity over location</strong>. Documents are tracked by their cryptographic content hash, ensuring that your library remains intact even if files are moved, renamed, or synced across different devices.</p>
        </section>

        <section id="architecture" class="mb-5">
            <h3 class="fw-bold mb-3">Architecture</h3>
            <p>The library is built on a three-tier database structure stored as high-performance <code>.feather</code> files:</p>
            <div class="row g-3 mb-4">
                <div class="col-md-4">
                    <div class="p-3 border rounded bg-light h-100">
                        <h6 class="fw-bold text-primary"><i class="bi bi-journal-text me-2"></i>Ref</h6>
                        <p class="small mb-0"><strong>Bibliographic Metadata</strong><br>Tags, authors, titles, journals, and years. Synchronized with an external BibTeX file.</p>
                    </div>
                </div>
                <div class="col-md-4">
                    <div class="p-3 border rounded bg-light h-100">
                        <h6 class="fw-bold text-success"><i class="bi bi-file-earmark-pdf me-2"></i>Doc</h6>
                        <p class="small mb-0"><strong>Physical Files</strong><br>Path, size, creation date, and content hash. Managed in a sharded directory structure.</p>
                    </div>
                </div>
                <div class="col-md-4">
                    <div class="p-3 border rounded bg-light h-100">
                        <h6 class="fw-bold text-warning"><i class="bi bi-link-45deg me-2"></i>Ref-Doc</h6>
                        <p class="small mb-0"><strong>Junction Table</strong><br>The bridge that links high-level tags to physical content hashes.</p>
                    </div>
                </div>
            </div>
            <div class="row g-3 mb-4">
                <div class="col-md-4">
                    <div class="p-3 border rounded bg-light h-100">
                        <h6 class="fw-bold text-info"><i class="bi bi-clock-history me-2"></i>Read</h6>
                        <p class="small mb-0"><strong>Read History</strong><br>Tracks timestamps, view counts, and origin URLs (referrers) for every document opened.</p>
                    </div>
                </div>
                <div class="col-md-4">
                    <div class="p-3 border rounded bg-light h-100">
                        <h6 class="fw-bold text-success"><i class="bi bi-cpu me-2"></i>Semantic Cache</h6>
                        <p class="small mb-0"><strong>Embedding Cache</strong><br>Stores high-dimensional vectors for papers, enabling instant re-analysis and galaxy mapping without re-encoding.</p>
                    </div>
                </div>
            </div>
            <h5 class="fw-bold">Full-Text Extraction</h5>
            <p>When documents are imported, Archivum automatically extracts their text content. This text is sharded into a separate directory, enabling blazing-fast full-text searches across thousands of documents using the integrated <a href="https://github.com/BurntSushi/ripgrep" target="_blank"><strong>Ripgrep</strong></a> engine.</p>
        </section>

        <section id="query" class="mb-5">
            <h3 class="fw-bold mb-3">Query Syntax</h3>
            <p>The primary search bar on the <strong>Query</strong> page is powered by <code>querexfuzz</code>. A small live status line below the input shows the exact expression that will be run.</p>
            
            <div id="query-simple" class="mb-4">
                <h5 class="fw-bold text-primary">1. Live Query Interpretation</h5>
                <p>For quick lookups, plain text becomes a fuzzy <code>#</code> search. Explicit querexfuzz syntax is limited to the 50 most recent published matches by default.</p>
                <table class="table table-sm table-bordered bg-white small mb-3">
                    <thead class="bg-light">
                        <tr>
                            <th style="width: 30%;">Syntax</th>
                            <th>Description</th>
                        </tr>
                    </thead>
                    <tbody>
                        <tr>
                            <td><code>keyword</code></td>
                            <td>Runs as <code># keyword</code> for fast fuzzy matching.</td>
                        </tr>
                        <tr>
                            <td><code>!AuthorName</code></td>
                            <td>Runs as <code>recent top 50 !AuthorName</code>.</td>
                        </tr>
                        <tr>
                            <td><code>field ~ pattern</code></td>
                            <td>Runs as <code>recent top 50 field ~ pattern</code>.</td>
                        </tr>
                        <tr>
                            <td><code>year &gt; 2020</code></td>
                            <td>Runs as <code>recent top 50 year &gt; 2020</code>.</td>
                        </tr>
                        <tr>
                            <td><code>q top 20 recent</code></td>
                            <td>Runs exactly as <code>top 20 recent</code>.</td>
                        </tr>
                    </tbody>
                </table>
                <p class="small text-muted"><i class="bi bi-info-circle me-1"></i> Querex symbols are <code>#</code>, <code>~</code>, <code>=</code>, <code>&lt;</code>, <code>&gt;</code>, and <code>!</code>. Use <code>q</code> when you do not want automatic <code>recent top 50</code> wrapping.</p>
            </div>

            <div id="query-advanced" class="mb-4">
                <h5 class="fw-bold text-primary">2. Full Querexfuzz (Prefix: <code>q</code>)</h5>
                <p>Prefix your query with <code>q</code> to pass an expression through unchanged.</p>
                <div class="bg-dark text-light p-3 rounded font-monospace small mb-3">
                    q select year, author, title author ~ /Wang, R/ and year > 2019 order by -year
                </div>
                <ul class="small">
                    <li><strong>Fuzzy Search</strong>: Use <code>#</code> for fast skimmatch fuzzy matching. <code>q # machine learning</code></li>
                    <li><strong>Projection</strong>: Control which columns are returned using <code>select col1, col2</code>.</li>
                    <li><strong>Sorting</strong>: Use <code>order by field</code> or <code>order by -field</code> for descending.</li>
                    <li><strong>Limits</strong>: Add <code>top 50</code> to restrict result size.</li>
                </ul>
                <p class="small">For the complete grammar, visit the <a href="https://github.com/mynl/querexfuzz_project" target="_blank">Querexfuzz Project</a>.</p>
            </div>
        </section>

        <section id="bibtex" class="mb-5">
            <h3 class="fw-bold mb-3">BibTeX Format</h3>
            <p>Archivum stores bibliographic metadata in a deliberately narrow BibTeX-compatible shape. Keeping entry types and fields normalized makes imports safer, keeps Feather tables predictable, and reduces BibTeX synchronization noise.</p>

            <div class="mb-4">
                <h5 class="fw-bold text-primary">Entry Types</h5>
                <p class="small text-muted">Use one of these types for new or edited records:</p>
                <div class="bg-light border rounded p-3 font-monospace small">
                    article, book, techreport, misc, incollection, unpublished,
                    inproceedings, phdthesis
                </div>
            </div>

            <div class="mb-4">
                <h5 class="fw-bold text-primary">Supported Fields</h5>
                <p class="small text-muted">Restrict BibTeX fields to the following set unless a specific import requires a temporary exception:</p>
                <div class="bg-light border rounded p-3 font-monospace small">
                    tag, type, title, year, author, journal, volume, number,
                    month, pages, booktitle, editor, edition, doi, isbn,
                    publisher, institution, address, url, archivePrefix,
                    arxivId, eprint
                </div>
            </div>

            <div class="mb-4">
                <h5 class="fw-bold text-primary">Conventions</h5>
                <ul class="small">
                    <li><strong>Tag</strong>: The BibTeX key is the Archivum tag. Keep it stable after import because links, citations, reports, and document mappings use it as the reference identity.</li>
                    <li><strong>Type</strong>: Store the entry type without the leading <code>@</code> in editable metadata, for example <code>article</code> rather than <code>@article</code>.</li>
                    <li><strong>Authors and editors</strong>: Use BibTeX <code>and</code> between names. Prefer canonical names that match the library's author normalization.</li>
                    <li><strong>Dates</strong>: Keep <code>year</code> as a four-digit year when known. Use <code>month</code> only when it is bibliographically meaningful.</li>
                    <li><strong>Identifiers</strong>: Prefer DOI, ISBN, URL, and arXiv fields over embedding identifiers in titles or notes.</li>
                    <li><strong>Document paths</strong>: Do not add Mendeley-style file fields manually; Archivum maintains document links through the ref-doc table and importer workflow.</li>
                </ul>
            </div>

            <div class="bg-dark text-light p-3 rounded font-monospace small">
@article{Wang2024,<br>
&nbsp;&nbsp;author = {Wang, Ruodu and Smith, Jane},<br>
&nbsp;&nbsp;title = {Spectral Risk Measures},<br>
&nbsp;&nbsp;year = {2024},<br>
&nbsp;&nbsp;journal = {Insurance Mathematics and Economics},<br>
&nbsp;&nbsp;doi = {10.0000/example}<br>
}
            </div>
        </section>

        <section id="screens" class="mb-5">
            <h3 class="fw-bold mb-3">Screen Guide</h3>
            
            <div id="screen-query" class="mb-4">
                <h5 class="fw-bold"><i class="bi bi-search me-2"></i>Query Page</h5>
                <p>The default landing page for searching your library.</p>
                <ul>
                    <li><strong>Search Bar</strong>: Supports history (Up/Down arrows). Results appear instantly as you type, and the live status line shows the interpreted querexfuzz expression.</li>
                    <li><strong>Quick Actions</strong>:
                        <ul>
                            <li><strong>Recent</strong>: Dropdown to quickly view the last 50, 100, or 250 items added.</li>
                            <li><strong>Read</strong>: Quick access to your reading history, ordered by most recent.</li>
                            <li><strong>Random</strong>: Discovers papers using a random 2-digit hex hash prefix.</li>
                        </ul>
                    </li>
                    <li><strong>View Modes</strong>: Toggle between <strong>List</strong>, <strong>Verbose</strong> (all metadata), and <strong>Table</strong>.</li>
                    <li><strong>Exports</strong>: Download the current result set as CSV, BibTeX, or BibTeX+ from the Export menu. BibTeX+ adds Archivum document hashes and Mendeley-style <code>file</code> fields when a matched document path is available.</li>
                </ul>
            </div>

            <div id="screen-network" class="mb-4">
                <h5 class="fw-bold"><i class="bi bi-share me-2"></i>Network & Discovery</h5>
                <p>Advanced visualization modes for exploring connections and thematic clusters.</p>
                
                <h6 class="fw-bold text-primary small">1. Social Graph (Co-Authorship)</h6>
                <p class="small">Maps the "Social Network" of your library. Nodes represent authors, and edges represent papers they have co-authored.</p>
                <ul class="small">
                    <li><strong>Weighting</strong>: Author nodes are sized by the total number of papers they have in the current search universe.</li>
                    <li><strong>Connectivity</strong>: Edges connect authors who appear on the same paper. Edge thickness indicates the number of collaborations.</li>
                    <li><strong>Interaction</strong>: Click an author to see their papers. Double-click to "Rebase" the graph onto that author.</li>
                    <li><strong>Ripgrep Universe</strong>: Searches using <code>rg</code> are case insensitive by default, matching the Ripgrep page behavior. Use <strong>Options &rarr; Case sensitive rg</strong> when exact case matters.</li>
                    <li><strong>Live Interpretation</strong>: The status box shows whether the current text is a raw query universe, a <code>q</code> querex universe, an <code>rg</code> full-text universe, or a combined <code>q ... rg ...</code> universe.</li>
                </ul>

                <h6 class="fw-bold text-success small">2. Semantic Galaxy (Thematic Clustering)</h6>
                <p class="small">Uses Machine Learning to project your papers into a 2D "Galaxy" where distance represents semantic similarity.</p>
                <ul class="small">
                    <li><strong>Embedding</strong>: Papers are converted into high-dimensional vectors (384-D) using the <code>all-MiniLM-L6-v2</code> transformer model.</li>
                    <li><strong>Cache</strong>: Embeddings are cached per library and source, so repeated runs usually reuse existing vectors. First runs, new documents, or longer full-text windows may need to encode missing papers.</li>
                    <li><strong>Projection (UMAP)</strong>: These vectors are flattened into 2D coordinates using <strong>UMAP</strong>, preserving local and global structures while using available CPU cores.</li>
                    <li><strong>Clustering (HDBSCAN)</strong>: <strong>HDBSCAN</strong> automatically identifies dense "Constellations" of related papers.</li>
                    <li><strong>Lone Stars</strong>: Points colored grey represent "Noise"-papers that don't statistically fit into any specific cluster.</li>
                    <li><strong>Sources</strong>: Analysis can be run against <strong>Title &amp; Metadata</strong>, the first 2,000 characters of <strong>Full Text</strong>, or the first 4,000 characters of <strong>Full Text</strong>.</li>
                    <li><strong>Verbose Logs</strong>: Verbose mode reports timing spans for universe resolution, embedding cache lookup, model load, missing embedding generation, UMAP, clustering, serialization, and browser rendering. When an <code>rg</code> clause is used, it also shows the ripgrep command and cache hit/miss.</li>
                </ul>
            </div>

            <div id="screen-ripgrep" class="mb-4">
                <h5 class="fw-bold"><i class="bi bi-terminal me-2"></i>Ripgrep (Full-Text)</h5>
                <p>Search inside the actual text of your PDF collection.</p>
                <ul>
                    <li><strong>Streaming Results</strong>: Matches are streamed to the browser in real-time.</li>
                    <li><strong>Regex Feedback</strong>: The small status line below the input checks whether the typed pattern is valid JavaScript regex syntax before running ripgrep.</li>
                    <li><strong>Context Control</strong>: Specify how many lines of context to show before and after matches.</li>
                    <li><strong>Summary Mode</strong>: Groups matches by year and author to provide statistical insights into your library's content.</li>
                    <li><strong>Exports</strong>: Send the top hash-limited matches to Query, or download all matches as CSV, BibTeX, or BibTeX+ from the Export menu.</li>
                </ul>
            </div>

            <div id="screen-reports" class="mb-4">
                <h5 class="fw-bold"><i class="bi bi-journal-richtext me-2"></i>Report Studio</h5>
                <p>A specialized workflow for synthesizing research findings into persistent journals.</p>
                <ul>
                    <li><strong>Integrated View</strong>: Research reports are rendered as HTML fragments using <strong>Pandoc</strong> and embedded directly within the Archivum interface.</li>
                    <li><strong>Archival PDFs</strong>: (Admin only) Generate professional-grade PDFs using <strong>Quarto + Tectonic</strong> with <code>scrartcl</code> styling (A4, 10pt font).</li>
                    <li><strong>Markdown Support</strong>: Add introductions and research notes to your reports using standard Markdown syntax.</li>
                    <li><strong>Smart Caching</strong>: Rendered HTML, PDF artifacts, and report images are cached in the library's <code>exports/</code> directory. If a report is viewed or downloaded again, Archivum serves the cached version instantly unless the source <code>.qmd</code> file has been modified.</li>
                    <li><strong>Raw Source</strong>: Access the raw <code>.qmd</code> file for manual editing or custom publication workflows.</li>
                </ul>
            </div>

            {% if is_admin %}
            <div id="screen-ingest" class="mb-4">
                <h5 class="fw-bold text-danger"><i class="bi bi-plus-circle me-2"></i>Ingest (Admin Mode)</h5>
                <p>Import new documents or BibTeX entries into the library.</p>
                <ul>
                    <li><strong>Source</strong>: Paste BibTeX, provide a local path, or enter a URL (including Arxiv/DOI support).</li>
                    <li><strong>Workbench</strong>: Edit the source BibTeX while viewing the staged document and metadata candidates.</li>
                    <li><strong>Import Preview</strong>: The preview runs the real BibTeX importer without saving. It shows the BibTeX that will be produced after author Trie normalization and tag allocation.</li>
                    <li><strong>Tag Allocation</strong>: Previewed tags are advisory. The final tag is recomputed when you click <strong>GO: Archive Document</strong> and is locked down only when the library update is saved.</li>
                    <li><strong>Duplicate Detection</strong>: Archivum warns on matching hashes and blocks unsafe duplicate or merge-warning imports before committing.</li>
                    <li><strong>Commit</strong>: Archive Document reruns the same import path, shards the document into the library store, writes import audit files, updates the Feather data, and extracts text for new PDFs.</li>
                </ul>
            </div>

            <div id="screen-edit" class="mb-4">
                <h5 class="fw-bold text-danger"><i class="bi bi-pencil-square me-2"></i>Editor (Admin Mode)</h5>
                <p>A high-density interface for bulk metadata management.</p>
                <ul>
                    <li><strong>Tag Sidebar</strong>: Live-filterable list of every tag in your library.</li>
                    <li><strong>Direct Edit</strong>: Edit the underlying BibTeX source directly and save with <code>Ctrl+S</code> or the Save button.</li>
                </ul>
            </div>
            {% endif %}
        </section>

        <section id="regex" class="mb-5">
            <h3 class="fw-bold mb-3">Regular Expressions</h3>
            <p>Most search fields in Archivum support standard regular expressions. Here are common patterns:</p>
            <table class="table table-sm table-bordered bg-white small">
                <thead class="bg-light">
                    <tr>
                        <th style="width: 20%;">Symbol</th>
                        <th>Meaning</th>
                        <th>Example</th>
                    </tr>
                </thead>
                <tbody>
                    <tr>
                        <td><code>.</code></td>
                        <td>Any single character</td>
                        <td><code>n.t.re</code> matches Nature</td>
                    </tr>
                    <tr>
                        <td><code>^</code></td>
                        <td>Start of string</td>
                        <td><code>^Smith</code> matches Smith but not Goldsmith</td>
                    </tr>
                    <tr>
                        <td><code>$</code></td>
                        <td>End of string</td>
                        <td><code>2023$</code> matches only tags ending in 2023</td>
                    </tr>
                    <tr>
                        <td><code>*</code></td>
                        <td>Zero or more of previous</td>
                        <td><code>ba*n</code> matches bn, ban, baan</td>
                    </tr>
                    <tr>
                        <td><code>+</code></td>
                        <td>One or more of previous</td>
                        <td><code>ba+n</code> matches ban, baan, etc.</td>
                    </tr>
                    <tr>
                        <td><code>?</code></td>
                        <td>Zero or one of previous (optional)</td>
                        <td><code>cats?</code> matches cat or cats</td>
                    </tr>
                    <tr>
                        <td><code>|</code></td>
                        <td>Logical OR</td>
                        <td><code>Nature|Science</code> matches either journal</td>
                    </tr>
                    <tr>
                        <td><code>\d</code></td>
                        <td>Any digit</td>
                        <td><code>\d{4}</code> matches a 4-digit year</td>
                    </tr>
                    <tr>
                        <td><code>\w</code></td>
                        <td>Any word character (alnum + underscore)</td>
                        <td><code>\w+</code> matches a whole word</td>
                    </tr>
                    <tr>
                        <td><code>\s</code></td>
                        <td>Any whitespace (space, tab)</td>
                        <td><code>Wang\s+R</code> matches "Wang, R" if space exists</td>
                    </tr>
                    <tr>
                        <td><code>[ ]</code></td>
                        <td>Character class / set</td>
                        <td><code>[aeiou]</code> matches any vowel</td>
                    </tr>
                    <tr>
                        <td><code>( )</code></td>
                        <td>Capturing group</td>
                        <td><code>(Auto|Machine)</code> groups for priority or repetition</td>
                    </tr>
                </tbody>
            </table>
        </section>
    </div>
</div>

<script>
    // In-page search for help content
    function searchHelp() {
        const query = document.getElementById('help-search').value.toLowerCase();
        const sections = document.querySelectorAll('.help-content section');
        
        sections.forEach(section => {
            const text = section.innerText.toLowerCase();
            if (text.includes(query)) {
                section.style.display = 'block';
            } else {
                section.style.display = 'none';
            }
        });
    }

    // TOC Highlight on Scroll
    window.addEventListener('scroll', () => {
        let current = "";
        const sections = document.querySelectorAll('.help-content section, .help-content div[id]');
        
        sections.forEach(section => {
            const sectionTop = section.offsetTop;
            if (pageYOffset >= sectionTop - 150) {
                current = section.getAttribute('id');
            }
        });

        document.querySelectorAll('#help-toc .nav-link').forEach(link => {
            link.classList.remove('active', 'text-primary', 'fw-bold');
            if (link.getAttribute('href').includes(current)) {
                link.classList.add('active', 'text-primary', 'fw-bold');
            }
        });
    });
</script>

<style>
    .help-logo {
        max-height: 180px;
        width: auto;
        object-fit: contain;
    }
    .help-content section {
        scroll-margin-top: 100px;
    }
    .help-content div[id] {
        scroll-margin-top: 100px;
    }
    .help-container {
        height: calc(100vh - 120px);
    }
    .help-sidebar {
        height: 100%;
        overflow-y: auto;
    }
    .help-content {
        height: 100%;
        line-height: 1.6;
        color: #333;
    }
    .help-content h2, .help-content h3 {
        color: #2c3e50;
        border-bottom: 2px solid #eee;
        padding-bottom: 0.5rem;
    }
    .help-content h5 {
        margin-top: 1.5rem;
    }
    .nav-link {
        transition: all 0.2s ease;
    }
    .nav-link:hover {
        padding-left: 0.5rem !important;
        color: var(--primary-color) !important;
    }
    mark {
        padding: 0;
        background-color: #fff3cd;
    }
    
    @media (max-width: 767.98px) {
        .help-container { height: auto; }
        .help-sidebar { height: auto; border-bottom: 1px solid #dee2e6; }
        .help-content { height: auto; padding: 2rem !important; }
    }
</style>
{% endblock %}