# Automatic filing

New indexable uploads outside pinned branches receive a durable filing job. Parsing and indexing finish first; the document stays usable if filing fails. Filing is enabled by default and can be turned off in Organization settings → Connections. Existing documents are not reorganized on startup. Filing and organization reviews use the organization’s selected decision model, TypeSafe or Cloudflare Clef, configured in Connections.

Right-click a writable folder and choose **Pin** to lock its branch against automatic filing. Pinned folders and their descendants are excluded from destinations, new branches, and upload-driven reviews; documents inside stay in place. Uploads into a pinned branch still parse and build their document outline, but skip filing, organization reviews, and all TypeSafe or Clef calls for organization. Workers also skip filing if the branch is pinned while parsing or before a queued filing job starts. This also applies to **Organize** and filing retries. Pinning is shared folder state and survives reloads. Choose **Unpin** to make the branch available again; previously skipped uploads stay in place. Manual uploads and moves remain available. Workers recheck pins before committing a placement, including jobs that started before a folder was pinned.

JEV receives the document name, a bounded heading outline, and up to twelve evenly spaced samples of original source passages. It compares existing writable folders at each level, plus choices to stay in an actual parent folder or request a new branch. The library root is a container and cannot be selected as an existing filing category. A clear existing match leads into that folder and its subfolders. An uncertain child choice keeps the document in the closest actual parent folder reached. At the root, an uncertain match triggers a new branch proposal. When the library has no available folders, the naming model proposes its first branch and JEV validates it before creation. Uploading into a chosen folder restricts all placement to that folder and its descendants.

A choice must receive at least 0.65 probability and lead the next choice by at least 0.2. These are conservative defaults, not calibrated accuracy guarantees. Large sibling sets are grouped into bounded routing menus; these groups are not physical folders. Very long documents are sampled, so filing may miss topics outside those samples.

When Cloudflare Clef is selected, placement, branch validation, and placement-review decisions also receive up to four original PDF page images, prioritizing the opening page, pages with figures, and the closing page. Uploaded images are sent as a single image. Rendering is permission-checked, images are resized and compressed within the hosted API limits, and render failures stop the decision instead of silently falling back to captions. Other document formats use extracted text. The separate folder-naming model continues to receive text; TypeSafe requests are unchanged.

When JEV clearly finds no suitable placement, one short generation request proposes one or two new levels beneath the current parent. An administrator can select a separate inexpensive model in Connections. The provider default is used when no naming model is selected; pricing depends on the configured provider and model. Output is capped at 600 tokens and must contain only folder names and generic descriptions. No document summaries are generated. Without a configured naming model, the document stays in the current parent.

JEV compares the proposed branch with existing choices and rejects unnecessary or unsuitable branches. The backend validates the JSON and names, checks permissions again, and creates or reuses folders inside the existing serialized transaction. Matching sibling names are normalized before reuse, preventing concurrent proposals from creating duplicate accessible branches. The folder hierarchy then participates in normal JEV retrieval; parsed document sections remain unchanged.

After an upload is filed into a path, a durable event asks whether related older documents could fit that path better. Pending events from a batch share a folder-path set. JEV traverses the cached folder, document, and section hierarchy to shortlist candidates; it does not classify every document or reparse the library. This lookup scores at most 24 source passages and returns at most eight passages, so at most eight documents can receive full placement review per event. Unrelated branches can be rejected during routing. Bounded retrieval can miss related documents; this is a conservative incremental improvement, not a guarantee of a globally optimal taxonomy.

Each shortlisted document receives a separate current-versus-upload-path comparison. Only a clear improvement with at least 0.8 probability queues full classification. The final destination must also beat its current placement with at least 0.8 probability before moving. Reviews use existing parsed content, never generate new branches, and never enqueue another review event. Manual placements, shared documents, another user's documents, and destinations outside the original upload scope are excluded. Documents already in the affected destination need no review. There is no periodic classification or reindexing schedule.

Filing acts as the uploader. Inaccessible folder metadata never enters a provider request. Documents must still be private and have no explicit grants. A manual move cancels the job, and changes to sharing, source content, folder metadata, or permissions stop stale work. New root folders are private to their creator; nested folders inherit their parent's access. Documents retain private access when moved. Folder definitions are requested to be generic and checked by JEV, but their wording still depends on model judgments.

Jobs use pg-boss claims, heartbeats, bounded retries, and attempt fencing. They wait for a missing JEV connection and record completion or failure independently of indexing. Restoring the JEV connection requeues waiting jobs. Owners can retry failed filing from the document's Index view. Turning filing back on does not retroactively move uploads skipped while it was off. Each committed placement is audited without source text.

Selecting documents and choosing **Organize** queues classification with HTTP 202. The full selection is validated before jobs are committed. Workers classify up to three documents concurrently per process. This explicit action can reconsider manual placements across the writable library even when automatic filing is disabled. Provider calls run outside database transactions, and permission checks run before requests and placement. The toast confirms admission; document filing state shows processing or failure. Successful placements are preserved when another document fails.


An uncertain root match also triggers a new branch proposal, which must pass the same JEV validation against existing folders before creation. If the proposal cannot be validated, the unresolved root match is not counted as organized. The explicit action preserves the original location and reports the lack of a confident folder match instead of moving an already-filed document back to the root.