specs/docs: system documentation as a declared .t27 document (7 chapters) + docs/system bodies + i18n docs-ru

docs/README.md

@@ -25,6 +25,12 @@ First-party docs follow the **27-agent trinity alphabet** grouping: **three nona
 | [`coordination/ROLLING-INTEGRATION-PLAN-SEED-TO-QUEEN.md`](coordination/ROLLING-INTEGRATION-PLAN-SEED-TO-QUEEN.md) | Phased plan: seed → tests → Queen brain (`tri`/`t27c`, conformance, codegen gap). |
 | [`coordination/inter-agent-handoff/`](coordination/inter-agent-handoff/) | Portable handoff bundle. |
 
+## [`system/`](system/) — system documentation bodies (rendered at `t27.ai/#/docs`)
+
+| Path | Role |
+|---|---|
+| [`system/project.md`](system/project.md) .. [`system/evidence.md`](system/evidence.md) | English canonical prose of the seven chapters declared in [`specs/docs/`](../specs/docs/); sections are checked against `SECTIONS` at site build. |
+
 ## [`nona-01-foundation/`](nona-01-foundation/) — agents **A–I**
 
 Architecture, seed rings, brain charter, language purge, sandbox.

docs/now/2026-09-09-system-documentation-as-a-declared-t27-document.md

@@ -0,0 +1,13 @@
+# NOW -- System documentation as a declared .t27 document (2026-09-09)
+
+## System documentation as a declared .t27 document (Closes #3550)
+
+- `specs/docs/system.t27` (module `docs_system`, `KIND = "docs"`) declares the system documentation of t27.ai (`#/docs`) as one document: CHAPTERS (7 ids in reading order), SOURCES (the four catalogs, `specs/i18n`, `SOUL.md`, `AGENTS.md`, `CLAUDE.md`, `docs/agents/AGENTS_ALPHABET.md`, `docs/T27-CONSTITUTION.md`), DIAGRAMS (6 figures the site draws from data: `ladder`, `agent-ring`, `phase-cycle`, `law-hierarchy`, `skills-crons-agents`, `tools-map`), LOCALES (`en`, `ru`), ENABLED. One `specs/docs/chapters/<id>.t27` per chapter (`docs_chapter_<id>`, `KIND = "docs-chapter"`: DOCUMENT, ORDER, TITLE, SOURCES, SECTIONS, DIAGRAM, TABLE, BODY_EN, ENABLED). Schema in `specs/docs/README.md`.
+- Chapters: 1 `project` (what t27 and Trinity are, claims with status tags, boundaries: no silicon, FPGA AX7203 only, 83 formats declared, hardware axes as measured in the trinity-fpga v0.2 transcription, no ranking words), 2 `rules` (constitutional stack, SOUL Articles I-VIII, laws L1-L7 with priority, AGENTS.md non-negotiables, TASK protocol, issue gate and TDD mandate -- quoted, not paraphrased into stronger rules), 3 `layers` (Specs -> Skills -> Crons -> Agents -> Tools; how specs generate the site, how crons name skills, how agents hold skills and tools, how experience is logged), 4 `alphabet` (three nonas; table generated from `spec-agents.json`), 5 `queen` (6-phase cycle + Phase 7 git from the alphabet document; cell, seal, verdict), 6 `tooling` (tri CLI + MCP from `spec-tools.json`), 7 `evidence` (measured / declared / external, witness labels, wasm verdicts, CI gates, how to reproduce, published record: `README-ZENODO.md`, `docs/reports/TNF-ARTICLE-AUDIT-W845.md`, `docs/reports/TNF-ARTICLE-RECONCILIATION.md` -- cited by path, no new scientific claim).
+- English canonical prose lives in Markdown named by BODY_EN (`docs/system/<id>.md`, 7 files, ASCII only), not inside the `.t27` (LANG-EN). Every SECTIONS entry is a level-2 heading in the body, in order; the site's generator checks this. `docs/README.md` gains the `system/` row (Article DOCS-TREE).
+- Russian travels through a new translation contract `specs/i18n/docs-ru.t27` (module `i18n_docs_ru`: SCOPE `specs/docs`, `specs/docs/chapters`; FIELDS `TITLE`, `BODY`; bundle `trinity:apps/website/i18n/docs.ru.json` keyed by ID; FALLBACK `en`; COVERAGE_REQUIRED false; ORPHANS_ALLOWED false). Not a word of Cyrillic in this repository.
+- Measured under the vendored compiler wasm (sha256 `4d9c0447b5ca2887...`): **9/9** typecheck ok (system, 7 chapters, i18n), nothing discarded. `typecheck.ok` is lenient; the site's generator (`scripts/docs-from-specs.mjs`, gHashTag/trinity) checks the field schema, that every SOURCES path exists in the vendored tree or the checkout, that every generated table is non-empty, and that no ranking word appears in EN or RU prose (`check:docs`).
+- Three canon discrepancies are recorded in the prose, not resolved: `AGENTS.md` section 5 says "L1-L8" while its own table and `docs/T27-CONSTITUTION.md` define L1-L7 and no L8 exists; the alphabet document's PLAN / ASSIGN / RUN / TEST & BENCH / VERDICT / EVOLVE + GIT WORKFLOW cycle differs from `CLAUDE.md`'s AEL v2.0 loop (OBSERVE / PLAN / DELEGATE / VERIFY / SYNTHESIZE / LEARN); the `tri git` of Phase 7 has no variant in the clap enum of `cli/tri/src/main.rs` at this commit, so the tool catalog has no card for it.
+- No absolute developer home path appears in any file; the t27 checkout is referred to as `T27_ROOT` or `git rev-parse --show-toplevel`.
+- Not claimed: the bootstrap compiler on `master` was not run against these files; whether SOUL Article II applies to declarative catalog modules is not ruled here; `gate-topology` and `untrusted-input` still fail on `master` for already-merged PRs and are not addressed.
+- `specs/OWNERS.md` gains the row `docs/` -> **Z-Zeta** (with **T-Queen** for `chapters/queen.t27`).

docs/system/alphabet.md

@@ -0,0 +1,63 @@
+# The 27-agent alphabet
+
+## Twenty-seven letters, three nonas
+
+`docs/agents/AGENTS_ALPHABET.md` (v3.0, 2026-04-07) is the canon: "The Trinity system
+employs 27 named agents -- corresponding to the 27 registers in `isa/registers.t27`
+(Coptic / Trinity alphabet)." Each agent is bound to a letter and a register, has a domain
+(physics, numeric, compiler, graph, experience, verdict, bench, DePIN, UI and so on), logs
+to `.trinity/experience/` and is linked to nodes in `graph_v2.json`.
+
+The alphabet is read in three layers of nine, which the document also calls nonas:
+
+- **Archetypal, A-I (1-9)** -- "pure concept -- foundation: soul, base, types". A is the
+  architecture and `SOUL.md` as primary cause; C the compiler; E the experience; I the ISA.
+- **Spiritual, J-R (10-18)** -- "inner process -- life of the system: tasks, language,
+  numbers, physics". L is the language; M the metrics; N the numeric formats; P the physics
+  constants; Q the queue.
+- **Physical, S-27th (19-27)** -- "manifestation -- proof: standards, verdict, deploy,
+  gift". S is the specs; T the Queen, who "puts the final seal on everything"; V the
+  verdict; W the workflow and tri cell ("double hash-seal"); Z the zero-touch UX and docs;
+  the 27th letter, Ti, is security.
+
+The same three-by-nine layout organises the documentation tree of the repository
+(`docs/nona-01-foundation/`, `docs/nona-02-organism/`, `docs/nona-03-manifest/`, Article
+DOCS-TREE of the constitution) and the ring on the site next to this chapter, where each
+letter sits at its ordinal and is coloured by its layer.
+
+## The table
+
+The table the site renders next to this chapter is generated from
+`public/agents/spec-agents.json`, which is itself generated from the 27 files
+`specs/agents/<letter>.t27` through the compiler wasm -- it is not typed here. Per letter it
+shows the ordinal, the letter name, the domain, the archetype, the register, the layer, and
+the skills and tools the agent holds with their evidence. The FULL TABLE of the alphabet
+document (letter, domain, archetype, key files, entry invariant, exit invariant, CLARA role)
+is the source each spec was transcribed from; the spec's header names the row.
+
+Two conventions of the table are worth stating. A letter's register comes from the schema
+section of the alphabet document (for example T is R19, V is R21, W is R22); the ordinal is
+the position in the alphabet, 1..27, so T is 20 and the 27th letter is 27. Where the
+alphabet document names two agents with the same Greek letter name (C and G are both
+written "Gamma"), the spec keeps the document's spelling and the ID stays unambiguous
+because it is the Latin letter, `t27/C` and `t27/G`.
+
+## What a card carries
+
+Beyond the alphabet row, an agent card on the site carries what the other layers say about
+the letter:
+
+- **Skills** -- IDs from `specs/skills` the agent holds, bound only where a source names the
+  skill. At the commit this documentation was generated from one letter holds skills: T,
+  from `.claude/agents/trinity.md`, which names `phi-loop` and `tri-pipeline` in its Phase 2
+  and Phase 4. The other 26 carry an empty list and a note saying which sources were read.
+- **Tools** -- IDs from `specs/tools` the agent holds, bound in both directions (the tool
+  spec names the letter back). Five commands are bound today: `tri gen` (C, T), `tri test`
+  (T, V), `tri verdict` (V), `tri experience` (E), `tri cell` (W); the sources are the phase
+  descriptions of the alphabet document and the `.claude/agents/*.md` files.
+- **Crons** -- jobs whose `RUNS` names a skill the agent holds; empty while every `RUNS` is
+  empty.
+- **Experience** -- episodes attributed to the letter in `.trinity/experience/`; none is
+  attributed today, and the card says so rather than showing a number it cannot source.
+- **Sources** -- the three binding documents (`SOUL.md`, `AGENTS.md`, the alphabet) at the
+  pinned commit, and the spec file itself.

docs/system/evidence.md

@@ -0,0 +1,92 @@
+# Evidence and witnesses
+
+## Measured, declared, external
+
+The project separates what was measured from what was declared, and both from what was taken
+from outside. The tags are defined in the chapter "The project"; this chapter says how each tag is
+earned on the site.
+
+A **measured** number has a producer in a repository -- a script, a workflow, a test -- whose
+output is committed or published, and the page names the commit. The ladder counts, the
+`typecheck.ok` verdicts, the coverage of a translation bundle, the number of episodes in an
+experience tree are measured in this sense: the generator that produces them runs in
+`prebuild` and its inputs are pinned.
+
+A **declared** value is stated in a spec or a canon document. The catalog size of 83
+formats, the seven laws, the seven phases are declared: the site renders them from the file
+that states them and links the file at the commit, but running nothing.
+
+An **external** value is cited with its source and not reproduced. The site does not restate
+hardware figures of `gHashTag/trinity-fpga` beyond what `siliconHistory.ts` transcribes with
+its provenance note.
+
+## Witness labels
+
+Each catalog card carries a witness label that says how the card relates to the thing it
+describes:
+
+- Skills and crons: `spec+code` (spec and source both exist), `spec-only` (spec without
+  source), `code-only` (source without spec). The counts per label are in the header of the
+  Skill and Cron Explorers.
+- Tools: `source-parse` (the command list was read from the source at a recorded commit;
+  `cargo` was not run) or `help-output` (the list was diffed against `tri --help`). At the
+  commit this documentation was generated from every tri card is `source-parse`.
+- Agents: each skill and tool binding cites a source line in `SKILLS_NOTE` / `TOOLS_NOTE`, or
+  the list is empty and the note says what was read.
+- Experience: attributed only where an episode names a letter; otherwise counted as
+  unattributed, never guessed.
+
+The table the site renders next to this chapter collects these labels with their counts from
+the generated JSON of every layer.
+
+## Wasm verdicts
+
+Every `.t27` the site shows was compiled at build time by the vendored `t27_compiler.wasm`,
+and the JSON records `typecheck.ok` per file. Two limits of that verdict are stated on every
+layer README and repeated here. First, the wasm's `typecheck.ok` is necessary, not
+sufficient: it stays `true` for a wrong annotation such as `str = 5`, so the generator checks
+the field schema of every card on top of it. Second, the bootstrap compiler on `master` was
+not run against the catalog files in the commits that added them; the wasm is a build of the
+compiler at a recorded sha, and that sha is in the generated JSON.
+
+## CI gates
+
+`gHashTag/t27` gates a pull request with workflows named for what they check (issue gate,
+gate topology, conformance integrity, emit bit-exact, catalog count, now-sync, untrusted
+input, among others under `.github/workflows/`). Two of them, `gate-topology` and
+`untrusted-input`, fail on `master` for already-merged pull requests at the time of writing;
+the catalog pull requests record this and do not bless or bypass them.
+
+`gHashTag/trinity` gates the site with `npm run` checks that run in `prebuild` and in CI:
+`check:spec-catalog`, `check:skills-catalog`, `check:crons-catalog`, `check:agents`,
+`check:tools`, `check:docs`, the explorer and Queen language contracts, the Queen viewport
+contract, `typecheck:ratchet` and `eslint`. A check that fails on `main` before a change is
+reported as pre-existing, with its name, and is not counted as passing.
+
+## Reproducing a number
+
+To reproduce a count on the site, run the generator that produced it, in `apps/website` of
+a checkout of `gHashTag/trinity`, with a sibling checkout of `gHashTag/t27` (or `T27_ROOT`
+pointing to one):
+
+- `node scripts/agents-from-specs.mjs` -- skills, crons, agents, tools JSON and their counts;
+  `--check` compares against the committed JSON.
+- `node scripts/docs-from-specs.mjs` -- this documentation's JSON, including the sources with
+  their sha256 and the pinned commit.
+- `node scripts/sync-agents-experience.mjs` -- the experience snapshot.
+- `npm run check:docs` -- the chapter bodies, the sources, the generated tables, the
+  forbidden-words scan in English and Russian.
+
+Each JSON names the commit its inputs were read at. Comparing that commit with the one in
+front of you is step one of any reproduction; a number that cannot be tied to a
+commit is not a measurement.
+
+## Published record
+
+Two kinds of record exist outside the generated pages, and this documentation points to
+them without adding to their claims. The TNF manuscript audit and reconciliation reports
+live under `docs/reports/` in `gHashTag/t27` (`TNF-ARTICLE-AUDIT-W845.md`,
+`TNF-ARTICLE-RECONCILIATION.md`); they record which statements of the article were checked
+against which producer and what changed. The Zenodo README (`README-ZENODO.md`) describes
+the archived package. No scientific claim is made in this documentation that is not in those
+files or in the site's own content with its status tag.

docs/system/layers.md

@@ -0,0 +1,83 @@
+# The five-layer system
+
+The site orders what the repositories ship into five layers and shows the same ladder in
+the header of every Explorer: **Specs -> Skills -> Crons -> Agents -> Tools**. Each layer
+is a directory of `.t27` files in `gHashTag/t27`, each has a README that states its schema,
+and each is rendered from those files by one generator through the compiler wasm. The
+ladder counts on the site are read from the generated JSON at build time; the table next
+to this chapter shows them for the commit the documentation was generated from.
+
+## Specs
+
+The base layer is the `.t27` corpus itself: everything under `specs/` in `gHashTag/t27`,
+from the language core and the numeric formats to the catalogs below. The site vendors a
+byte-identical copy under `apps/website/public/t27/files/` and compiles every file with the
+vendored `t27_compiler.wasm` at build time. The Spec Explorer (`#/specs`) shows each file
+with its verdict; the manifest that lists them (`public/t27/manifest.json`) is generated
+and never hand-edited.
+
+## Skills
+
+A skill is a published procedure an agent can run -- a `SKILL.md` in one of the
+repositories. `specs/skills/<id>.t27` declares each one (KIND, ID, NAME, REPO, SOURCE,
+SUMMARY_EN, COMMAND, SPECS, TAGS, ENABLED, TIMEOUT_MIN). The witness label on a skill card
+says how the card relates to the code: `spec+code` when both the spec and the `SKILL.md`
+exist, `spec-only` when only the spec does, `code-only` when a skill file has no spec yet.
+Skill Explorer: `#/skills`.
+
+## Crons
+
+A cron is a scheduled job: a workflow schedule, a Railway timer, a daemon loop.
+`specs/crons/<id>.t27` declares each (HOST, REPO, SERVICE, INTERVAL_MS, TZ, RUNS,
+RUNS_NOTE, ENABLED, NOTE, ON_FAILURE, CONTROL). `RUNS` lists the skill IDs a job invokes,
+and only where the source shows the invocation; where none is found `RUNS` is empty and
+`RUNS_NOTE` says so ("no skill invocation found in source"). The Cron Explorer (`#/crons`)
+computes the next firing from `INTERVAL_MS` and `TZ`. A job that runs no skill is a job the
+site cannot tie to the layers above; that is recorded, not hidden.
+
+## Agents
+
+The 27 letters of the alphabet, one spec each: `specs/agents/<letter>.t27` with LETTER,
+ORDINAL, LETTER_NAME, NAME, DOMAIN, ARCHETYPE, REGISTER, LAYER, SUMMARY_EN, the three
+binding documents (SOUL, AGENTS_DOC, ALPHABET), KEY_FILES, the entry and exit invariants,
+CLARA_ROLE, SKILLS with SKILLS_NOTE and TOOLS with TOOLS_NOTE. An agent holds a skill or a
+tool only where a source line binds it -- a `.claude/agents/*.md` file, the alphabet, a
+phase description -- and the note cites that line or says why the list is empty. The
+generator fails the build on an unknown skill or tool ID and on a binding stated on one
+side only. Agent Explorer: `#/agents`. The full table is the next chapter.
+
+## Tools
+
+What an agent can call: the commands of the `tri` CLI and the tools of the MCP servers.
+`specs/tools/tri/<command>.t27` is read from the clap `Commands` enum in
+`cli/tri/src/main.rs` (one card per variant, with its nested actions and arguments);
+`specs/tools/mcp/<server>.t27` from the server sources, manifests and `.mcp.json` entries of
+both repositories, with the tool names, descriptions and input-schema keys. The witness on
+every tri card is `source-parse` (the enum was read at a recorded commit) until someone
+diffs the list against `tri --help` and relabels it `help-output`. Servers whose code is a published
+package outside the repositories carry `EXTERNAL = true`. Tool Explorer: `#/tools`.
+
+## From spec to site
+
+One generator, `scripts/agents-from-specs.mjs` in `gHashTag/trinity`, reads the vendored
+`.t27` files, compiles each through the wasm, reads the constants of the compiled module,
+checks them against the schema of the layer, resolves every cross-reference (skill IDs in
+crons and agents, tool IDs in agents, agent letters in tools, spec paths in skills), and
+writes one JSON per layer under `public/`. It runs in `prebuild`, so a spec that does not
+compile or a reference that does not resolve stops the site from building. No `.t27` is
+parsed with a regular expression anywhere in that path.
+
+Translations follow the same rule. `specs/i18n/<layer>-<locale>.t27` declares which fields
+of which specs a bundle may translate and where the bundle lives; the bundle
+(`apps/website/i18n/*.json`) carries the text; the generator checks that every bundle entry
+names an existing spec and reports coverage. The specs stay English-only.
+
+## Experience
+
+Agents log what happened under `.trinity/experience/` in each repository: episodes as JSON,
+notes as Markdown. `scripts/sync-agents-experience.mjs` reads both trees at their current
+commit and writes `public/agents/experience.json` with counts per repository and, where an
+episode names an agent letter, the attribution. At the commit this documentation was
+generated from no episode is attributed to any letter -- the field the sync looks for is
+absent from every episode -- and the agent cards say so. The snapshot records the commit of
+each tree, not the path of the checkout.