Filing systems and document addresses
Before the first taxonomy file with a top-levelsystem header is applied, Suchi
has one hidden original system. Unprefixed files keep the existing archive and
paths; there is no enable-systems toggle or prerequisite configuration.
The first prefixed import, for example system = "S01", offers two destinations:
- Use this archive: name the original archive S01 and import into its existing tree, retaining documents, IDs, memberships and document grants.
- Create separately: preserve the original under a distinct code (for example A00) and create S01 for the incoming tree. The preserved archive keeps its name.
^[A-Z][0-9]{2}$ (A00–Z99) and become immutable. Display names
are editable, nonblank and at most 80 Unicode characters. First adoption or
creation uses the file’s name; reimport preserves a locally edited system name.
New systems initially admit only active instance administrators. Administrators
grant direct user memberships separately from document permissions. There are
no system roles, deletion, merge or document-transfer controls.
Official SYS.AC.ID notation
uses an assigned, category-local ID folder.
Suchi deliberately uses the existing installation-global document number
as .ID, not a folder counter, authored seed ID or new per-system counter.
Assuming an upload has returned document 147 in S01/category 13, its address is
S01.13.147. Refiling it to category 14 gives S01.14.147; the number and numeric
document URL remain stable, while the old address no longer resolves. New versions
and split children receive their own document IDs. There is no 99-document limit.
Automatic allocation does not reuse IDs allocated after the taxonomy upgrade.
Surviving beta.2 IDs are preserved, but numbers purged before the upgrade have no
retained allocation history and may be reused.
Canonical addresses require a two-digit category and an unpadded positive decimal
document ID in the signed 64-bit range. Spaces, signs, lowercase codes and padded
IDs such as S01.13.0147 are invalid. A syntactically valid address still needs an
existing live document in that exact current location and permission to view it.
Selecting a system is Suchi’s simple “choose a filing cabinet” model, not a claim
to reproduce every upstream JD convention. System entry and existing document
ACLs are required; even admins cannot escape an explicit request or token system.
Shared server administrators, host operators and backups remain trusted. This is
application isolation over shared SQLite/CAS/FTS, not independent infrastructure,
per-system encryption or evidence of professional independence. See
Permissions for membership and delegated credentials.
Choose a tree
Setup recommendssolo, household, freelance or smb_billing from your
intent. Compare the built-in cards or choose Import a file. blank contains
no user categories and needs explicit confirmation. Settings offers the same
import under Archive configuration > Filing tree.
Choose a .huml or .toml file, or paste content and select its serialization.
Custom files can contain starter automations and category-keyword filing rules;
Include starter rules from this file applies only to those supplied by the file. A tree-only
file adds no rules. Preview shows the name, story, content revision, user tree,
generated structure, category/rule additions, preserved
rules, skips and collisions. Changing input, format, seed choice or remaps
requires another preview. If relevant destination state changes before Apply,
Suchi preserves your input and asks you to preview again; unrelated system edits
do not invalidate a preview.
Validation checks supported structure, not domain suitability or reliable
classification. Review imported keywords and rules against your documents.
Suchi never fetches remote taxonomy files or requires a catalog service.
Safe import and reimport
Only initial unconfigured setup can replace a bootstrap tree, and only when no filed documents (including recoverable Trash) or dependent user configuration would be orphaned. Later imports merge additively; an empty archive alone is not permission to reset a chosen tree.- Same category code and name preserves the row and local description.
- Different names at one code need explicit skip or an unused same-decade remap.
- Existing rule names are preserved, including disabled preset originals and user-owned edited forks. Reimport does not restore disabled rules.
- Skipping a category skips its entire dependent starter rule, not just one action.
- System destination, tree, supported starters, last-import provenance and required jobs commit together; unresolved references leave no partial import.
Authoring v1
HuML and TOML are co-equal. YAML, unknown/duplicate keys, unsupported formats, wrong types and unsupported actions are errors. Validation is offline and bounded to 1 MiB. The entire file is checked even when seeds are skipped.format, id, positive integer version, nonempty name,
market, language, story. Author IDs match [a-z0-9][a-z0-9_-]*. Optional
system names exactly one filing system; optional metadata is maintainer and
license. Importing or exporting never implicitly licenses your configuration.
Names are at most 80 Unicode characters, story 500, descriptions 240;
each category allows at most 20 literal keywords of at most 40 characters.
Tree form requires explicit areas; areas = [] is a blank tree. Flat authoring
shorthand uses flat = true and 1–9 categories instead of areas. Codes are
11–19 in order; explicit codes must match. Parsing expands it into an area tree;
it does not select the separate runtime flat rendering mode. Database export may
spell the tree as explicit areas rather than preserve the original shorthand.
Never repurpose a category code within an author’s ID or call reordering compatible.
User area starts are 10, 20, 30, 50, 60, 70, 80, 90. Categories belong to
their area’s decade and never end in zero. Do not declare inbox, category-level
protected system flags, 00–09 or 40–49: Suchi generates reserved structure after
raw validation. The optional top-level system = "S01" is distinct and valid.
Both reserved decades are forbidden remap destinations. The index is not a
category or a selectable filing destination.
Optional starters
Onlyseeds.automations is supported. Existing trigger types and filters use
the runtime’s glob/regex validation; category keywords remain literal matching,
not regex. Starters need unique names, nonempty actions and exact parameters:
Keyword-generated names include the authoring ID and effective category code/name.
If two rules to be added have the same name, Preview rejects the proposal with the
conflicting name. Rename the explicit starter or remove the category keywords
before previewing again. Existing local rules still win, and skipped rules do not
participate in this collision check. Metadata references resolve trimmed exact
names first, then canonical slugs; Preview and Apply use the same normalization.
No instance row IDs or arbitrary action parameters. Sensitivity defaults,
review_after_days, custom fields, standalone tag/type/correspondent seeds,
link vocabulary/endpoints, access grants, secrets, provider configuration and
trust state are unsupported. New schema capabilities require a new format;
adding a runtime action does not automatically make it portable in v1.
Export and provenance
--system S01 to select an existing system for unprefixed import or export.
It must agree with a prefixed file. Only the first prefixed import accepts
--existing-system-code A00 to preserve the original separately.
Export creates a validated current snapshot with id = "archive", version = 1,
not a claim that a merged archive equals its last imported file. Source
identity/revision/byte SHA-256 remain separate provenance. Equivalent HuML and
TOML can have different hashes; schema version, content revision, source hash
and Suchi release version have different meanings.
Default export includes representable preset-owned starters, not all archive
automations. Keyword-generated rules export as named explicit starters to retain
their distinct identity and order, not collapsed category keywords. Disabled or
otherwise unrepresentable starters cause an error, never silent loss or
re-enabling. Choose tree-only export explicitly to omit both keywords and
starters. User-owned forks, permissions, review history and documents need a
complete backup.
Only validated generated System/49 is removed from raw output. Legacy custom
reserved categories, renamed system rows or a different Inbox produce an
actionable error; Suchi does not hide or automatically renumber those records.
Generated filing index and paths
Before introduction the map isrendered/00-09 System index/00.00 archive.huml; afterwards each system has
rendered/<SYS>/00-09 System index/00.00 archive.huml. It contains the current
system code/name and tree/descriptions, with snapshot id = "archive" and
version = 1, but no keywords/automations. Generated System/49 is implicit.
It is a managed area/category map, not the original authoring starter file,
the upstream JD register of assigned ID folders, a document inventory or backup.
Do not edit it in place.
Committed filing-tree changes queue a durable taxonomy_index refresh. Server
startup also queues a refresh per system to recover missing/stale indexes. Jobs
build current state when they run and replace the file atomically. Failure preserves
the last complete index and uses normal retries/dead-job reporting. A successful
import with pending work does not mean the physical file has refreshed; CLI-only
imports need the server to process jobs. No document row or CAS blob is created.
After introduction, document projections are rooted at rendered/<SYS>/ using
the immutable code, not the editable display name. Default JD layout is, for an
illustrative already-returned document:
undated, title, and the full address suffix after introduction. Explicit templates
retain relative behavior with jd.system.code, jd.system.name and jd.address
available, but cannot escape the enforced system root or occupy a managed index.
Renaming a system does not move its root.
First introduction queues render-only moves for existing live documents. Durable
move journals recover interrupted publication at the current target; cleanup removes
only a verified document CAS link or proved-managed legacy index, never arbitrary
user files. Only the original system’s index writer removes the old root index,
after publishing its named replacement. Startup does not rewrite the whole filesystem.
Use suchi refile --system S01 --skip-automations for render-only work without
rerunning OCR or classification.
Category API
GET /api/jd/categories/ lists ordinary categories with area labels and optional
q and area filters within the selected system. Category system remains a
protected-row boolean; system_code identifies its filing system. Set a document’s
category with {"jd_category_id":17}: the row must belong to that document’s
system, and runtime row IDs differ from portable category codes. Full addresses
resolve through GET /api/jd/resolve?address=S01.13.147; numeric IDs are unchanged.
Mobile uses ordinary bound-system APIs; taxonomy administration is session-admin web/CLI.
See API and Automations.
Johnny.Decimal is a trademark of Coruscade Pty Ltd. Suchi is independent and
is not affiliated with or endorsed by them.