Alego Doc

Alego documentation

Summary

The Alego documentation standard: make every page searchable, newcomer-readable, and exact enough for agents and maintainers, and keep the documentation website a tested projection of repository Markdown. Apply repository AGENTS.md files and executed gates first, then this workflow for kind-mapped metadata, progressive detail, line-aligned bilingual pages, corpus audits, and website publication. Preserve one owner per fact: source, tests, generated catalogs, package READMEs, guides, Agent Notes, and scratch each keep their own kind of truth. The session-persistence-jsonl README pair is the reference example of the format.

Table of Contents

• Workflow
• Fact-check procedure: test, do not assume
• Kind system and templates
• Voice rules
• Quality criteria
• Audit the corpus
• Wordcount budgets
• Website publication
• Detailed references
• Validation
• Dev Note

Workflow

Follow this sequence for each requested scope. Keep the common reader path brief, but do not delete failures, ownership, limitations, or other required contracts merely to reduce words.

1. Read root and more-specific AGENTS.md, the documentation standard, the target page, its source/tests, navigation owner, and bilingual record.
2. Classify the page by one primary job and reader: product quick start, user task guide, contributor tutorial, architecture overview, package/subsystem reference, generated reference, agent instruction, decision record, or scratch.
3. Place the page at its nearest owner. Keep package contracts beside package code; use docs/ for cross-package learning, user, developer, architecture, discussion, and expiring scratch material.
4. Define the reader's starting state, observable outcome, likely failure, recovery path, and next useful depth before writing details.
5. Add or revise YAML metadata — assign the kind that maps to the template for this document's job — then write Summary, Table of Contents, user-facing content, developer-facing content, optional Further Exploration, and final Dev Note in that order where the document type permits.
6. Update the bilingual counterpart in the same pass. Keep headings, lists, tables, code, links, frontmatter layout, and physical line count aligned.
7. Verify every claim against code, tests, generators, package metadata, or a current decision owner — and run the operations the page instructs, per the fact-check procedure below. Update the owner before any derivative artifact.
8. Run focused checks, then pnpm run test:docs, pnpm run doc-sync, pnpm run lint, and git diff --check; re-read the complete diff for correctness and then for brevity and repository fit.

Fact-check procedure: test, do not assume

Documentation states how the product behaves today, and the only admissible evidence for an operation claim is having run it. This procedure is mandatory for every new document and every new paragraph that claims an operation, command, default, error, or platform difference.

1. Classify the subject before writing install guidance. Read the facts, never the folder name: package.json for an alego.bundle.patch declaration, and the entry file for the plugin shape (apply export or a default service export is a plugin; a plain module API is a library). A bundle installs with alego plugin --profile <name> add <package> and is the only package shape for which that command activates a profile layer; a plugin mounts as a cordis.yml row; a library is a dependency with no install path of its own. Packages with special status (libraries, bundles) get their own README template — never a plugin README with install guidance that does not apply.
2. Run every claimed operation against the current checkout. Execute each CLI command, config snippet, and profile or patch example exactly as the document will show it; write down only what you observed, including the exact output, warnings, and failure modes. If a claim depends on a key or a network you do not have, say so and name the verification owner instead of asserting the behavior.
3. Delete what you could not reproduce. Never carry a command, field, default value, or behavior from memory, analogy, or a neighboring package's README. When a claim fails to reproduce, fix the claim — not the test.
4. Check old docs against latest master. Before revising pre-existing pages, git fetch origin and compare the section against origin/master; the pairing sidecar recovers the last-confirmed text of either side. A stale statement on master is still wrong: correct it against the code, not against the old prose.
5. Re-record the pair after every edit. Each paired edit re-runs pnpm run verify-translation-pairing --write <pair> so the sidecar tracks the confirmed pair.

Kind system and templates

The kind frontmatter field selects exactly one README template. Every kind in the metadata reference maps to one template file in templates/, and every template backs exactly one kind; the documentation check derives the expected kind from the same mechanical facts.

• package-group → templates/package-group.md: group maps (packages/README.md, packages/<group>/README.md) — orient the family, map its direct packages, link package-owned details.
• package-reference → templates/package-reference.md: a Cordis plugin or service package — mount configuration, the config table, folded implementation, Model Experience and Known Limitations in the gate-owned forms.
• package-library → templates/package-library.md: a package with no plugin surface — consumer entry points, no profile-install path, no mount configuration.
• package-bundle → templates/package-bundle.md: a package declaring alego.bundle.patch — the verified alego plugin install path, layer semantics, patch document.
• persistence-change → templates/persistence-change.md: a dated record in docs/persistence-changes/ — acknowledge a detected type transition with per-root predecessors and generated after schemas.
• persistence-release → templates/persistence-release.md: a pinned tag in docs/persistence-changes/releases/ — compare reconstructed historical types without claiming compatibility acknowledgement.
• persistence-format → templates/persistence-format.md: a historical Session format checkpoint in docs/persistence-changes/historical-formats/, with complete schemas; the current writer uses the existing catalog.

Open the template before writing and follow its skeleton and rules; it states what the kind is, how the page is structured, and the fact checks each section owes. Add a new kind only together with a distinct template file, a documented repository position or declared owner, and a focused check that maps documents to it.

Voice rules

These rules decide what a section may say. They apply to every authored human-facing page, and to package READMEs with particular force.

• Summary says what the subject does. The opening Summary and the user-facing sections describe what a user or agent can DO with the subject — outcomes, benefits, when to choose it, main cost — never its role, type, or internal identity. In a package Summary, “what it is” means only its reader-visible capability, not its Cordis role, registrations, or internal components. Omit source identifiers unless the reader directly uses them in configuration, a command, or a public API. "The seam registers ctx.x and appends x/event records" is identity narration; "you can save a note per message and it survives restarts" is what it does.
• Developer sections explain, never enumerate. Folded implementation content covers the overall design concept, architecture, and hand-waving dataflow — enough to understand how the package works — and links code for exact detail. No full API catalogs, exhaustive column lists, event-payload enumerations, or JSDoc restatement inside the folds.
• Dev Note is the only slop zone. Partial ideas, scratches, undecided directions, measured artifacts, and working hypotheses live only in the final Dev Note, marked explicitly non-authoritative. Every other section is polished, current-state prose.
• Current state only. Ordinary documentation describes the current codebase. Dedicated persistence-change, persistence-release, and persistence-format records retain historical type evidence; release comparisons and format checkpoints describe observed history without asserting compatibility. Agent Notes and postmortems retain their own historical scope.
• Use controlled technical English. Give each sentence an explicit actor and one main action when ambiguity can change behavior. Reuse one term per concept, prefer direct verbs, split stacked instructions and conditions, and preserve modality and exceptions. Apply the non-certified, ASD-STE100-inspired discipline in the page-style reference. Do not force a shorter sentence when precision would fall.