> ## Documentation Index
> Fetch the complete documentation index at: https://docs.suchi.page/llms.txt
> Use this file to discover all available pages before exploring further.

# Web app

> Navigation, setup, account settings, and everyday document actions in Suchi.

The web app opens on the working archive. This guide describes its current
controls; [Frontend architecture](/spa-architecture) covers implementation.

## Current filing system

Before the [first prefixed taxonomy import](/jd), there is no system selector.
That import can name the original archive or preserve it under another code and
create the incoming system separately. Preview explains the destination and
initial access; Apply selects the result.

After introduction, one accessible system gets a code/name label; multiple systems
get a switcher. Unqualified collection links select the accessible original,
otherwise the first accessible system, before loading data. An explicitly
unavailable system never falls back. Without membership, Suchi offers account/
sign-out controls and asks an administrator to grant access.

Switching clears displayed data, selections, Reveal, research, import previews and
share/pairing/OAuth dialogs. Late responses cannot refill the new screen. Accepted
upload batches retain their starting destination without showing receipts in the
new system. [Permissions](/permissions) explains the server-enforced boundary.

## Main navigation

| Label           | Opens                                                                                   |
| --------------- | --------------------------------------------------------------------------------------- |
| **Dashboard**   | Archive totals, Inbox/Approvals counts, failed jobs, recent documents, and saved views. |
| **Documents**   | Search, filters, list/grid display, selections, bulk actions and filing.                |
| **Inbox**       | Documents awaiting filing in the protected system Inbox.                                |
| **Views**       | Saved document searches and shortcuts.                                                  |
| **Calendar**    | Document dates for admins, members with **Manage document dates**, and demo visitors.   |
| **Approvals**   | Human decisions, rescan proposals and **Dead jobs — needs attention**.                  |
| **Automations** | Filing/metadata rules; admins can edit, members have read-only access.                  |
| **Trash**       | Deleted documents, restoration and confirmed permanent deletion.                        |

The **Index** lists normal filing areas/categories after a tree is chosen. The
protected Inbox appears only in its dedicated navigation item. Password-unlocked
documents show an open-padlock icon in lists and **Password unlocked** in detail.
This includes manual and saved-password unlocks without identifying a password;
Suchi uses an unlocked working copy while preserving the protected original.

The top bar provides search, **Upload** and theme controls. The search menu matches
**Commands** and **Pages**; **Search everything for** submits its complete text.
Query suggestions appear in Search/Documents fields, separately from this menu.

Drop files on Upload or anywhere on an available archive page to open per-file
results. New uploads wait until the selected system is available. Each drop
uploads once and refreshes visible lists after success. In Upload, focus the drop
area to paste a screenshot; **Upload image** confirms sending and **Discard**
removes the local preview. Ordinary text-field pasting stays unchanged.

Results distinguish new, duplicate, restored and failed files. **Text extracted**
or **No text found** appears after processing; errors stay explicit. Automatic
checks pause after about 100 seconds; **Check again** resumes them. Accepted
batches continue through navigation while the same account remains signed in;
closing the browser can interrupt them.

Document/selection sharing displays the created link. **Copy link** retries without
creating another; blocked clipboard access leaves the URL selectable. **Show QR
code** locally encodes that same link, retaining expiry/password/revocation.
Document sharing's **Show link** reopens an existing active link.

**Open on my phone** displays a live document's private browser URL/QR without
publishing it or issuing credentials. The phone needs network access and an
account authorized for the document. A `localhost` link works only on the original
computer; open Suchi through its network address first.

## Extracted text

Detail previews 2,000 characters. **Read all** expands the complete text; **Show
less** collapses it. **Copy text** copies the whole extraction and offers a
selectable field if copying fails. Confidential/Restricted text requires **Reveal**.
These controls do not change stored extraction.

## Dashboard behavior

**Total documents**, **Inbox**, **Approvals** and **Failed jobs** share one status
request. Loading/unavailable counts show `—`, not zero or a healthy status.
**Recently added** shows six newest visible documents. **Views** shows up to four
shortcuts with live counts, including at least one shared view when available.
**New view** starts creation; the empty message is **No saved views yet.** Read
failures show **Retry** rather than an empty archive.

## Document URLs and filters

| Filter                                   | Browser parameter        | Example                                  |
| ---------------------------------------- | ------------------------ | ---------------------------------------- |
| Filing system                            | `system`                 | `#/documents?system=S01`                 |
| Text                                     | `q`                      | `#/documents?q=paris`                    |
| Filing category database ID              | `jd`                     | `#/documents?jd=6`                       |
| Tag                                      | `tags__id__in`           | `#/documents?tags__id__in=4`             |
| Correspondent                            | `correspondents__id__in` | `#/documents?correspondents__id__in=3`   |
| Document type                            | `document_type__id`      | `#/documents?document_type__id=2`        |
| Sensitivity                              | `sensitivity`            | `#/documents?sensitivity=confidential`   |
| Sort order                               | `ordering`               | `#/documents?ordering=title`             |
| Page                                     | `page`                   | `#/documents?page=3`                     |
| Added on/after (Unix seconds)            | `created_at__gte`        | `#/documents?created_at__gte=1788220800` |
| Added on/before (inclusive Unix seconds) | `created_at__lte`        | `#/documents?created_at__lte=1790812799` |

Combine `system=CODE` with other filters after introduction. Reload, Back/Forward,
copied links and new tabs retain it. An old unqualified numeric document URL first
resolves its authorized document, then updates system context. Full addresses such
as `S01.13.147` use the resolver; stale addresses are not aliases or broad searches.
The API/saved-view field `jd_category_id` translates to browser `jd`; it is not a
supported browser parameter itself.

Documents/Inbox keep pagination in the URL. Opening detail and using Back restores
the page and filters. The compact footer provides nearby pages, first/last and
Previous/Next; page one may omit `page`. Changing a filter/sort starts at page one;
explicit historical URLs restore their page. Invalid values become page one and
out-of-range values become the last page without adding history. Only the newest
request updates the screen.

Mouse/trackpad devices have hover quick actions; on touchscreens open the document
for filing/Trash actions. Search and Documents share the [query language](/query-language):
suggestions appear while typing, validation occurs on Apply, and rejected queries
remain visible with their error. [Search architecture](/search) covers retrieval.

## Document tags

Select **Edit** beside **Tags** to add an existing tag or remove one with ×.
Changes save immediately; **Done** closes the editor. Failures preserve current
tags and show an error; Trash remains read-only. Create tags under
**Settings > Archive configuration > People and metadata > Metadata**.

## Approvals

Cards show decisions, confidence, evidence and deadlines. Rescan document links
are under **Affected documents**. Internal workflow identifiers are omitted.
See [Approvals](/approvals) for workflow behavior and [Document dates](/document-dates)
for date review.

## Trash

Open a Trash row to use its normal document URL in read-only recovery mode.
Within an enterable system, owners/admins can preview/download, read metadata/text,
restore within 30 days or confirm permanent deletion. Sensitive content still
requires **Reveal**; public shares cannot serve trashed documents.

**Document in Trash** shows the deletion deadline and hides editing, filing,
sharing, access, versions and similarity until restoration. Restore keeps the
document open; **Back to Trash** returns to the list. On phones, row titles/deadlines
sit above **Restore** and **Delete permanently**.

## Saved views

**New view** opens **Create a view** with optional Query, category, tag,
correspondent, document type, sensitivity and date filters. Empty choices mean all
values. Select a view's name to open its documents; **Edit** is available only for
your views. **Save changes** updates in place; **Cancel**/Escape discards the draft.

Rich filters appear in **Query** for editing/removal. Older flat filters retain
selections, multi-value scopes and ordering; exact research snapshots can be
renamed/shared without changing their document set. New views store a normalized
rich query; untouched legacy fields survive edits. Validation failures remain in
the open form. Choices load when needed, not for an empty view list. See
[Saved-view query rules](/query-language#saved-views).

Admins and members with **Share saved views** can select **Share this view**.
Shared views appear within their system and still obey document ACLs. Only the
owner can edit/delete; revoking sharing capability makes their views private
without deleting them.

## Settings

The running version stays in a footer at the bottom of Settings, outside the
scrolling content. Development builds add the source revision,
with `.dirty` for modified source or **revision unavailable** when missing.
Tagged releases show only their version. Include this offline status in bug
reports; it performs no update check.

**Settings > My account** contains Profile, Mobile app,
API tokens, Saved decryption passwords, and Mailboxes for capable members.
**Profile** saves your display name/photo; sign-in email is read-only.
Demo visitors see a read-only profile without account tools.
Profile fields sit side by side on wide screens and stack on phones. The account
pane scrolls with clearance between its content and scrollbar, while the Settings
tabs and version footer stay visible.

**Pair mobile app** generates a private, single-use QR code that expires in five
minutes. Scan it in Suchi and confirm the server address. A new code replaces the
old one; closing cancels unused codes. If scanning/copying fails, manually select
the link and use **Paste pairing link** in the app. Manual server/password/API-token
sign-in remains available. Pairing ships with the later mobile release, not beta.2.

Each successful exchange adds a separate **Mobile app** entry showing device
name, read/write access, connection and last-use dates. Updated apps let you name
the device during confirmation, replacing the browser label; older clients keep
that label. Existing entries keep their name until paired again. Matching names
do not merge connections. The list refreshes during/after pairing and on window
focus. **Revoke**, or signing out in the app, removes the connection; generating,
cancelling or expiring a code creates no device entry.

Pairing/token rows retain their system binding; changing systems requires a new
pairing. Membership removal revokes system credentials/shares permanently.
Legacy credentials without recorded pairing origin, and manual connections, stay
under **API tokens**; revoke/re-pair to move legacy devices to Mobile app.

Admins also have **Settings > Archive configuration**:

| Group                    | Sections                                 |
| ------------------------ | ---------------------------------------- |
| **Structure and access** | **Filing tree**, **People and metadata** |
| **Document intake**      | **Watched folder**, **Email intake**     |
| **Processing**           | **Classification**, **Automations**      |
| **Maintenance**          | **OCR and backups**                      |

The configuration frame fills the available screen height. Long sections scroll
inside the right pane without moving section navigation or the version footer.
On narrow screens, section navigation becomes a horizontally scrolling rail.

**People and metadata** contains Users, Groups, Metadata and Taxonomy. Metadata's
type selector covers tags, correspondents, document types, storage paths and
custom fields. Groups expands its members beside the selected group. User
capabilities are under **Additional access**; hidden member choices are not saved
when creating an admin. Setup reuses the same user-creation form.

**Taxonomy** imports/exports HuML or TOML filing-tree files. Preview precedes Apply;
export explicitly offers starter rules or tree only. **What is included?** explains
why neither replaces a [full backup](/backup-restore). Both **Automations** entry
points open the same main editor.

After introduction, **Filing system · CODE** edits a nonblank name of at most 80
characters and the complete direct membership set, including off-page people.
Codes are permanent; admin entry is implicit/read-only. New systems initially
admit admins only. Membership and document ACLs remain separate.

Filing trees, metadata, rules, views, mailboxes/password records and memberships
use the current system. Accounts/groups, global capabilities, profiles, watched
folders, OCR/models and backups are server-wide. **Classification** includes
**Use similar documents for automatic filing and suggestions** for local matching.
Admins manage system mailboxes and owners in **Email intake**; capable members
manage only their own under **My account > Mailboxes**.

## First-run setup

A fresh archive has only System/Inbox, without an implicit preset or filing Index.
Setup order is **Filing tree → People → Watched folder → Email intake →
Classification → Automations → OCR and backups**.

Filing tree is the only required step: apply a preset/import before advancing or
**Finish setup**. Starting from scratch requires explicitly confirming **Blank**.
Other steps are optional and remain available in Archive configuration.

**Import a file** sits beside preset cards and shares Settings' importer. Choose
HuML/TOML or paste content, include/exclude starter rules, Preview and Apply.
Preview separates your tree from generated System/49, explains 00.00 and shows
additions, preserved rules and collision choices. A blank tree needs confirmation;
stale previews preserve input and require re-preview. Success refreshes setup and
the sidebar. Later applications merge, without resetting existing filing.
Validation checks supported structure, not domain correctness or rule trust.
See [Filing trees](/jd) for destination, collision and export rules.

For 48 hours after first-admin creation, incomplete setup shows **Choose your
filing tree** in the sidebar/narrow Dashboard with **Continue setup**. Opening or
closing the reminder, choosing a tree, finishing setup or expiry dismisses it.
Browser dismissal is specific to user/installation start; Setup remains in Settings.

Before engagement, Settings shows **Setup is incomplete** and **Continue setup**
in place of Archive configuration sections. Retiring the prompt exposes all
sections; optional wizard steps never keep administration locked.

## Capabilities and sensitive documents

Admins have all capabilities. Grant members additional access in
**People and metadata > Users**:

| Interface label           | Stored key             |
| ------------------------- | ---------------------- |
| **Ask the archive**       | `archive_chat`         |
| **Manage document dates** | `archive_intelligence` |
| **Manage mailboxes**      | `mailboxes`            |
| **Create share links**    | `share_links`          |
| **Share saved views**     | `share_views`          |

[Permissions](/permissions) owns revocation and object-access rules.

With a model enabled, capable users see **Ask** in the Omnibox; Enter remains
search. **Archive research** opens a side drawer/full-screen mobile desk with its
current scope and cited sources. Following evidence parks it as **Research active**;
the ribbon restores it. Escape/**Close** ends the parked state; **Clear** removes
history and resets sensitive consent. Scope/provider changes reset conversation;
turning sensitive consent off clears history. The background is inert while open.

**Save retrieved documents as a view** preserves exact source IDs. Reviewable dates
link to Approvals; available dates open the retrieved documents' all-dates agenda.
Research is read-only and does not itself extract/save data. See
[Archive research](/archive-chat) for the complete workflow and contracts.

**Manage document dates** enables selection extraction, review and Calendar/query
use. Calendar's **Document view** applies a saved View through the server; research
links use exact documents with **Date role** and **Open full calendar**. Day links
open exact-day agendas, preserve View/role, and return through **Back to Month YYYY**.
Month/day/View/role survive history and reload. Partial dates appear in broader
agendas, not exact-day cells. Expand Automatic/Reviewed status for classifier
confidence. Reviewed exact-day **Add to calendar** offers a disclosed local `.ics`
export, not synchronization. [Document dates](/document-dates) owns precision,
review, filtering and export rules.

Sensitivity choices are Public, Internal, Confidential and Restricted; absent
values show **Unset**. Confidential/Restricted thumbnails blur and previews/text
require **Reveal**. **Create share links** controls share actions without bypassing
document access.

## Loading and failures

Data-dependent screens distinguish loading, empty and failure states. Failed Inbox
lookup never opens all documents; failed settings reads never expose default-filled
editable forms. Superseded route/search/autocomplete responses are discarded.
Late metadata saves cannot change another document's displayed values or Reveal
state after navigation.