IF Commons GitHub

Documentation

0011Draft

0011-documentation · owner if · domain commons

The generator

FR-001checkpassing

The generator MUST be kept in commons/docs/, as the library Docs (docs 0001-docs, which is where its package, its command and its publication are specified): its sources in src/, its package @intellectual-frontiers/docs, and dependencies that are exactly typescript at 7.1.0-beta (the first release with a programmatic API since 7.0, which the generator uses when it runs), shiki (which colours code when the site is built, FR-037) and beautiful-mermaid (which draws diagrams when the site is built, FR-037), the root package's dependencies carrying the same, pinned exactly with the lockfile bun.lock holding the integrity of each. Nothing outside commons/docs/ MUST import a file of it but commons' own configuration, commons/docs.config.ts (FR-023); another repository installs the package from npm and runs its command ifc-docs (docs 0001-docs FR-003).

Enforced (check): .github: cd commons/docs && bun run verify — conventions.test.ts: the name and ./docs, the dependencies exact and the root package's, no IFC TypeScript dependency, and nothing outside commons/docs but commons/docs.config.ts imports it

Proved by: docs/suite/conventions.test.ts

Tests: passed: suite/conventions.test.ts nothing outside commons/docs imports a file of it but commons' configuration; passed: suite/conventions.test.ts the package's name, exports and command, TypeScript 7.1.0-beta, Shiki and the diagram rend

FR-002checkpassing

The generator MAY import the libraries core, system and test of commons by package name, typescript/async (the asynchronous client of the programmatic API, whose channel to the compiler runs under Bun and under Node; the synchronous one reads Node's own stream internals), shiki and beautiful-mermaid (FR-037), and, when it runs, the configuration and the modules it documents, and nothing else. The lenses commons' configuration passes (FR-026) are kept in commons/docs/lens/, MAY import the public entry points of the libraries whose models and programs a lens shows (commons/data, commons/headless) from commons' source, import the generator only through its library entry point (mod.ts), and are reached from none of the package's entry points (., ifc-docs). It MUST be held to the rules of commons' TypeScript (0005-typescript-practice): only erasable syntax, no any, no non-null !, an expected failure as the kernel's Result, a tagged union matched by a switch that ends in absurd, @module on every file and TSDoc on every export, checked by the TypeScript compiler of the package.

Enforced (check): .github: cd commons/docs && bun run verify — the compiler of the package; conventions.test.ts: what each file imports, no any, no non-null assertion, @module and TSDoc

Proved by: docs/suite/conventions.test.ts

Tests: passed: suite/conventions.test.ts @module on every file, TSDoc on every export, no any and no non-null assertion; passed: suite/conventions.test.ts a file imports the generator and typescript/async; a lens also the libraries' entry points

FR-003checkfailing

ifc-docs build [--out DIR] [--config FILE] MUST write the site into DIR (by default the configuration's out, else _site at the repository's root, which Git ignores), and ifc-docs check [--config FILE] MUST build it into a temporary folder, report every finding of FR-018 as where: message on standard error, write nothing in the repository and exit 1 where there is one. Without --config, the configuration is the first docs.config.ts found from the working folder up to the repository's root (the first folder that holds .git). A command line or a configuration that is not valid MUST be refused with what is wrong and exit 2, before anything is read. In commons, bun main.ts build and bun main.ts check, run in commons/docs/, are the same commands from the source. The same sources MUST give the same bytes.

Enforced (check): .github: cd commons/docs && bun run verify — check.test.ts: check writes nothing in the checkout and exits 1 on a finding; two builds give the same bytes; config.test.ts: the commands, the search for docs.config.ts and exit 2 on a bad configuration

Proved by: docs/suite/check.test.ts, docs/suite/config.test.ts, docs/suite/evidence.test.ts

Tests: failed: suite/check.test.ts the site of commons builds with no finding, the same twice, with its sections, the Quality; failed: suite/check.test.ts check writes nothing in the checkout and exits 0 on commons; passed: suite/config.test.ts the command line: build with --out and --config, check with --config, and what is not one; passed: suite/config.test.ts the configuration is the first docs.config.ts from the working folder up to the repository

Cited by: build, cli, Documentation generator, site

The sources

FR-004checkfailing

Every page MUST be made from two sources alone: the repository's TypeScript, as its configuration names it (module documentation, TSDoc, About values, example files and the values of models and layouts), and its spec kits (in commons, commons/spec-kit/; FR-024 for the plain layout, whose constitution is a page). The site MUST NOT be made from a Markdown file written for it, and commons MUST NOT keep a README.md of its own, a library's README.md beside its package.json (commons/<library>/README.md, the page its package shows) being that library's, and the README.md of an acceptance kit (commons/<library>/acceptance/README.md and commons/<library>/acceptance/<kit>/README.md, 0027-commons-libraries FR-025, or the same under oat, uat or aat), a walk-through for a person that the site does not show, being that kit's; the root README.md of the repository (a short pointer to the site, kept by hand) and profile/README.md (the organization's page on GitHub) are not commons' and are not sources.

Enforced (check): .github: cd commons/docs && bun run verify — conventions.test.ts: commons has no README.md and the site reads only commons' TypeScript and the spec kit

Proved by: docs/suite/conventions.test.ts

Tests: failed: suite/conventions.test.ts commons keeps no README

Cited by: Documentation generator, sources

FR-005checkpassing

An area is a part of a library with an entry point. Each library MUST have an about.ts at its root that exports about, a value of the About type of the library core (@intellectual-frontiers/core/about): its title, a summary, the specification it implements, its folders with what each may import, its commands, its rules with what enforces each, and its areas, each with its entry points, its specification, its phases and its examples. No entry point MUST export about.ts, and commons as a whole MUST have commons/about.ts, with its summary and its folders. Another repository MAY keep about.ts files the same way, or give each package's About value in its configuration (FR-027).

Enforced (check): .github: cd commons/docs && bun run verify — about.test.ts: every package has about.ts naming its areas, no entry point exports it, and --check holds its folders, commands and rules to the code

Proved by: docs/suite/check.test.ts

Tests: passed: suite/check.test.ts an about that names what is not there is a finding of each kind

Cited by: about, Core, Documentation generator, sources

FR-006checkpassing

The documentation of a module MUST be TSDoc: the module's comment (which says @module) begins with what the module is, and MAY go on with @remarks (the longer account), @example, @see and @limits, this repository's own block tag, which says plainly what the module does not do or does only in part. An export's comment MAY carry @param, @returns, @example, @see and @deprecated. Prose in TSDoc and in specifications is the Markdown of FR-016.

Enforced (check): .github: cd commons/docs && bun run verify — api.test.ts: the module comment, @remarks, @example, @see, @limits and the tags of an export, read from a fixture

Proved by: docs/suite/api.test.ts

Tests: passed: suite/api.test.ts TSDoc read into its summary, parameters, what it returns and examples; a module comment's ; passed: suite/api.test.ts a page for each source file, an anchor for each export, the module's limits

Cited by: Documentation generator, tsdoc

FR-007reviewno test run

A limit, a guarantee or an account of how a part works MUST be written in the module of the code it is about, not in another file. A change to code MUST change its documentation in the same commit.

Enforced (review): 0011-documentation FR-006 — A reviewer checks that a change to code changes the documentation of its module in the same commit (AGENTS.md says so)

FR-008reviewno test run

A fact with a shape (a table of folders, of commands, of rules, of phases, of what a dialect's catalog compares) MUST be a typed value, in about.ts or in the module that uses it, not a table written in prose, so that a test can hold it to the code.

Enforced (review): 0011-documentation FR-006 — A reviewer checks that a fact with a shape is a typed value; about.test.ts holds the ones about.ts keeps

Cited by: about, Core

The pages

FR-009checkfailing

The site MUST have four sections, and leaves out one that has no page (Models, where the configuration passes no lens). Overview: a home page from the configuration's home (in commons, commons/about.ts) with a card for each capability (its specification's title, **Input:** and **Part of:**), and a page for each area from its entry point's module comment and its about, with the limits of the area's modules gathered from their @limits. Specifications: FR-015. API: FR-010 to FR-012. Models: FR-013, FR-014, FR-029 and FR-030. Libraries: FR-031 and FR-033. Guides: FR-032. Code and diagrams: FR-037.

Enforced (check): .github: cd commons/docs && bun run verify — site.test.ts: the four sections, the capability cards and an area's limits on the site made from commons

Proved by: docs/suite/check.test.ts

Tests: failed: suite/check.test.ts the site of commons builds with no finding, the same twice, with its sections, the Quality

Cited by: Documentation generator, model, pages/overview, site

FR-010checkpassing

The API of an area MUST be read through the TypeScript 7.1 programmatic API (typescript/async) from the area's entry points: every export, an alias followed to what it names, a namespace walked into, with its kind (function, constant, type, interface, class or namespace), its signature as the checker prints it, and its TSDoc. The area MUST have a page for each source file its exports come from, in the order the entry point exports them, with an anchor for each export.

Enforced (check): .github: cd commons/docs && bun run verify — api.test.ts: exports, aliases, namespaces, kinds, signatures and pages by source file, from a fixture

Proved by: docs/suite/api.test.ts

Tests: passed: suite/api.test.ts a page for each source file, an anchor for each export, the module's limits; passed: suite/api.test.ts every export with its kinds, a namespace walked into, in the order the entry point exports; passed: suite/api.test.ts signatures as the checker prints them, and types as their source writes them

Cited by: extract/api, Documentation generator

FR-011checkpassing

A citation in documentation MUST become a link to the specification's page: the repository's own prefix and a specification of its spec kit (commons NNNN-slug in commons), a bare id of the repository's own form (a number of the digits its configuration gives, four in commons and three in Stolos, then a slug: 096-bun-runtime), FR-nnn after either, and a bare FR-nnn in an area, which names a requirement of the area's specification. A specification of a repository the configuration lists as linked MUST become a link to its page on that repository's site (FR-025); a specification of any other repository (in commons, erga 009-machine-bootstrap) MUST be shown as text and never linked: a site may be public where the others are not.

Enforced (check): .github: cd commons/docs && bun run verify — links.test.ts: commons, bare and FR citations become links; another repository's stays text

Proved by: docs/suite/links.test.ts

Tests: passed: suite/links.test.ts a specification or requirement commons does not have is a finding; passed: suite/links.test.ts a link to a file goes to its page, a specification's file to its page, anything else to Gi; passed: suite/links.test.ts commons, bare and FR citations become links; another repository's stays text; passed: suite/links.test.ts a repository's own form, a linked repository's site, a text-only one, and a possessive qua

Cited by: Documentation generator, links

FR-012checkpassing

{@link name} MUST become a link to the export of that name in the same area, or to the export of an area that is named ({@link data!table}), or, where no area is named and the same area has no such export, to the one export of that name in any area; a name that is unknown, or that more than one other area exports, is a finding.

Enforced (check): .github: cd commons/docs && bun run verify — links.test.ts: {@link} in an area and across areas, and an unknown name found

Proved by: docs/suite/links.test.ts

Tests: passed: suite/links.test.ts {@link} goes to an export of the area or of a named area; an unknown name is a finding; passed: suite/links.test.ts {@link} with no area named goes to the one export of that name elsewhere; two of them is a

Cited by: Documentation generator, links

FR-013checkpassing

A lens MUST be a typed value (the package's Lens type, FR-026) that a configuration passes, which reads what is its library's and makes its pages in the Models section after the order it is given; a lens that has nothing to show makes none. Commons passes the guides lens (FR-032), the releases lens (FR-035), the layered-model lens for the data models (FR-029) and the program lens for ergonex (FR-030).

Enforced (check): .github: cd commons/docs && bun run verify — lenses.test.ts: a lens is a value of Lens that reads what is its library\'s and makes its pages after the order it is given

Proved by: docs/suite/lenses.test.ts

Tests: passed: suite/lenses.test.ts a lens is a value of Lens: it reads what is its library's and makes its pages after the or

Cited by: Documentation generator, lens

FR-014checkpassing

What a lens cannot describe (an entity with no description) MUST be a finding of the build that names the entity.

Enforced (check): .github: cd commons/docs && bun run verify — lenses.test.ts: what a lens cannot describe is a finding of the build, which names the entity

Proved by: docs/suite/lenses.test.ts

Tests: passed: suite/lenses.test.ts what a lens cannot describe is a finding of the build, which names the entity

FR-015checkpassing

The spec kit MUST give a page for each specification in force, with its title, status, owner, domain and part (where its layout has them), an anchor for each requirement and each success criterion, beside each requirement its row of enforcement.tsv (mechanism and who) or, in the plain layout, of its reviewed.tsv (FR-024), each edge case linked to the requirements it cites, and for each requirement the pages that cite it; a page of the register; and a matrix of every requirement with its mechanism and who enforces it.

Enforced (check): .github: cd commons/docs && bun run verify — specs.test.ts: a specification's page, its anchors and enforcement, the register and the matrix

Proved by: docs/suite/plain-kit.test.ts, docs/suite/specs.test.ts

Tests: passed: suite/plain-kit.test.ts the fixture's kit: its specifications in order, their reviews, the constitution, and their; passed: suite/specs.test.ts every specification in force has a page with an anchor and the enforcement of each require; passed: suite/specs.test.ts a requirement cited by another page says so; passed: suite/specs.test.ts a specification is read into its header, input and requirements

Cited by: extract/specs, Documentation generator

The output

FR-016checkpassing

The generator MUST turn the Markdown of TSDoc and of specifications into its own page model, a tagged union of blocks and inlines, and MUST read only this subset: paragraphs, headings, lists, emphasis, code, fenced code with its language, links, and tables. Anything else is shown as its text.

Enforced (check): .github: cd commons/docs && bun run verify — markdown.test.ts: every construct of the subset, and anything else shown as its text

Proved by: docs/suite/markdown.test.ts

Tests: passed: suite/markdown.test.ts a snake_case word is not emphasis, and a pipe inside code does not split a cell; passed: suite/markdown.test.ts code, strong, emphasis, links, autolinks and {@link} become inlines; the rest stays text; passed: suite/markdown.test.ts paragraphs, headings, lists, fences and tables become blocks

Cited by: Documentation generator, model

FR-017checkpassing

Every page MUST be a static HTML file whose links are relative, so that the site works under any path (it is published at https://intellectual-frontiers.github.io/.github/). A page MUST NOT request anything from another host: its stylesheet, its one script and the search index are files of the site, and a diagram is drawn into the page. The text people read MUST be on white (#ffffff) in the light theme (FR-034 gives the dark one); the navigation is on a neutral grey; it MUST be read on a screen 360 pixels wide with nothing scrolling sideways but code and wide tables; code is highlighted when the site is built; a search over titles, headings, exports, tables, columns and requirements is opened with /.

Enforced (check): .github: cd commons/docs && bun run verify — html.test.ts: relative links only, nothing from another host, the white reading area; the layout at 360 pixels is reviewed on the published site

Proved by: docs/suite/html.test.ts

Tests: passed: suite/html.test.ts a page asks nothing of another host, draws a diagram into the page with no script of its o; passed: suite/html.test.ts every case of the page model is written, text escaped and links relative to the page

Cited by: Documentation generator, site

FR-018checkpassing

check MUST find: an export of an area with no TSDoc; a package with no about.ts, or whose about names a folder that does not exist, a command that is not a script of its package.json, or a rule enforced by a test or lint rule that does not exist; a citation of a specification or requirement that is not in the spec kit; a {@link} to an unknown name; a table or view of a model with no description; a module of a lens that cannot be imported; a specification two spec kits both hold; and a link or anchor of the site that leads nowhere.

Enforced (check): .github: cd commons/docs && bun run verify — check.test.ts: each finding broken in a fixture and named

Proved by: docs/suite/check.test.ts, docs/suite/links.test.ts, docs/suite/plain-kit.test.ts

Tests: passed: suite/check.test.ts an about that names what is not there is a finding of each kind; passed: suite/check.test.ts a link to a page or an anchor that is not there is a finding; passed: suite/links.test.ts a specification or requirement commons does not have is a finding; passed: suite/plain-kit.test.ts a specification two kits both hold is a finding, and the first is kept

Cited by: check, Documentation generator, site

FR-019checkpassing

The generator's tests MUST cover the Markdown subset, the highlighter, every case of the page model as HTML, the API reader on a fixture module, each lens on a fixture, the configuration's validation, the plain spec kit's reader, the citation rules of a configuration, and the build of a fixture repository (a package with no about.ts and a plain spec kit), and MUST compare the fixtures' HTML with HTML committed under commons/docs/suite/golden/, written again with IFCDOCS_UPDATE_GOLDEN=1.

Enforced (check): .github: cd commons/docs && bun run verify — golden.test.ts: the fixtures' HTML is the committed HTML

Proved by: docs/suite/fixture-repo.test.ts, docs/suite/html.test.ts

Tests: passed: suite/fixture-repo.test.ts the fixture repository builds with no finding, from its configuration alone; passed: suite/html.test.ts the fixture's pages are what is committed

FR-020checkpassing

A workflow, .github/workflows/site.auto.yml, MUST run the generator's tests and check on every pull request and push that touches commons or the workflow, and on a push to main MUST build the site and publish it to GitHub Pages with GitHub's own actions (actions/upload-pages-artifact, actions/deploy-pages). The site MUST NOT be committed.

Enforced (check): .github: cd commons/docs && bun run verify — workflow.test.ts: docs.yml tests and checks on pull requests and publishes from main with GitHub's Pages actions

Proved by: docs/suite/workflow.test.ts

Tests: passed: suite/workflow.test.ts site.yml tests and checks on pull requests and pushes, and publishes from main with GitHub

The package

FR-021checkpassing

The generator MUST be consumed as the package @intellectual-frontiers/docs (docs 0001-docs FR-002 to FR-005): its entry exports the configuration's types, Lens, what a lens uses, loadConfig, buildSite, writeSite and main, and its command ifc-docs runs on Bun and, where Node 26 reads the configuration, on Node. In this repository the command is commons/docs/ifc-docs.mjs, which runs src/cli.ts as it is (Node 26 strips its types); the packed package is proved by installing it into an empty project (docs 0001-docs FR-005).

Enforced (check): .github: cd commons/docs && bun run verify — package.test.ts: the root package's ./docs and ifc-docs, the command registers the hook before cli.ts; consumer.test.ts: the packed package builds a repository

Proved by: docs/suite/package.test.ts

Tests: passed: suite/package.test.ts the package has the command ifc-docs, which runs cli.ts as it is, and the root package is

Cited by: Documentation generator

FR-022checkfailing

No workflow MUST make a GitHub release or attach a tarball of the generator, and the write permission to the contents is the tag job's of the workflow a library is published by, which makes the tag of the version it published, and the job keep-findings of each workflow, which adds the findings of a run to the history branch on the default branch only and never after a pull request (commons 0038-build-policy FR-012); the generator is published to npm by the release of the libraries, like every library of commons that has npm in its distribution.

Enforced (check): .github: cd commons/docs && bun run verify — workflow.test.ts: ifc-typescript.yml's git-dependency job runs the smoke test of IFC TypeScript on three systems with Bun and Node 26, and no workflow makes a release

Proved by: docs/suite/workflow.test.ts

Tests: failed: suite/workflow.test.ts no workflow makes a GitHub release, and the write permission is the release job's alone

The configuration

FR-023checkpassing

A repository MUST configure its site with a TypeScript module (docs.config.ts) whose default export, or export config, is a value of the package's DocsConfig type: the site's name, how its prose names the repository, its root (from the configuration's folder), its address on GitHub and branch, its home (a folder and its About), its packages (each a folder, a name in the site's addresses and an About: the path of its about.ts, about.ts by default, or the value itself), its spec kits and the layout of each (FR-024), its citations (FR-025), its lenses (FR-026), the folder of its lint rules, and where the site is written. The value MUST be checked once, when it is loaded, into a resolved configuration (paths made absolute or relative to the root, defaults filled), and every problem with it named; nothing else reads the raw value. Commons' configuration is commons/docs.config.ts, and the site it makes MUST be the one commons had before the configuration.

Enforced (check): .github: cd commons/docs && bun run verify — config.test.ts: a configuration checked into its resolved form, every problem named, found from the working folder up to the repository's root; check.test.ts: commons' configuration builds commons' site

Proved by: docs/suite/config.test.ts

Tests: passed: suite/config.test.ts defaults are filled, folders made relative to the root, and an About value kept; passed: suite/config.test.ts a configuration that is not valid names every problem; passed: suite/config.test.ts commons' configuration resolves: its root, its packages, its spec kits, its citations, its

Cited by: build, cli, config, Documentation generator, site

FR-024checkpassing

A spec kit MUST be read in one of two layouts. Commons' layout: registry.tsv, enforcement.tsv and specs/NNNN-slug/spec.md, the specifications in force in the register's order (FR-015). The plain layout of Spec Kit: every folder specs/NNN-slug/ that holds a spec.md, in the order of their names; the title from its first heading (after Feature Specification: or NNN: , where it has one); its status and input from the lines **Status**: and **Input**: where it has them; requirements written as - **FR-001** text or - **FR-001**: text, on one line or more, and numbered with a letter after the number where one was inserted (FR-005a); an optional reviewed.tsv beside the specification, whose rows (a requirement, a tab, a reason; # begins a comment) are the requirements proven by review; and, where it exists, the constitution (.specify/memory/constitution.md by default), shown as a page of the Specifications section.

Enforced (check): .github: cd commons/docs && bun run verify — plain-kit.test.ts: both requirement forms, a requirement over two lines, reviewed.tsv, the constitution's page, and a specification two kits hold

Proved by: docs/suite/plain-kit.test.ts

Tests: passed: suite/plain-kit.test.ts the fixture's kit: its specifications in order, their reviews, the constitution, and their; passed: suite/plain-kit.test.ts a specification two kits both hold is a finding, and the first is kept; passed: suite/plain-kit.test.ts a plain specification: its title, status, input, and requirements in both forms, on one li; passed: suite/plain-kit.test.ts reviewed.tsv: a requirement and its reason, bare or with its specification; comments are s

Cited by: config, extract/specs, Documentation generator

FR-025checkpassing

The configuration's citations MUST give the repository's own prefix (commons, stolos) and the number of digits of its specifications' numbers, the repositories whose specifications MAY be linked (each by its name, the address of its site and the digits of its numbers: a public repository built with this generator, whose pages are specs/<id>.html with an anchor fr-nnn for each requirement; such a link is not checked), and the repositories whose citations are only shown as text. A qualifier is matched whatever its case and with a possessive 's or ' taken off; a qualifier the configuration does not name is read as a word before a bare citation. A number of the repository's digits alone, after spec or before a requirement (spec 004, 038 FR-014), MUST become a link to the specification with that number where there is one, and the requirement after it is that specification's; where there is none, it and the requirement after it stay text.

Enforced (check): .github: cd commons/docs && bun run verify — links.test.ts: the own prefix and digits, a linked repository's citation to its site, a text-only one, and a possessive qualifier

Proved by: docs/suite/links.test.ts

Tests: passed: suite/links.test.ts a repository's own form, a linked repository's site, a text-only one, and a possessive qua; passed: suite/links.test.ts a number alone after spec or before a requirement names the specification with that number

Cited by: config, Documentation generator, links

FR-026checkpassing

The package MUST depend on no library it shows: a lens is a value of its Lens type that the configuration passes (its name, and a function that reads the areas and their API, registers the pages its entities are shown on, and returns what makes its pages once every other page is registered). The package ships no lens; commons' configuration passes none (FR-013), and another repository passes the lenses it has, or none.

Enforced (check): .github: cd commons/docs && bun run verify — conventions.test.ts: what ./docs and ifc-docs reach imports no data library and no lens; lenses.test.ts: the lenses as values of Lens

Proved by: docs/suite/conventions.test.ts, docs/suite/fixture-repo.test.ts, docs/suite/lenses.test.ts

Tests: passed: suite/conventions.test.ts the package depends on no library it shows: what ./docs and ifc-docs reach imports no data; passed: suite/fixture-repo.test.ts the fixture repository builds with no finding, from its configuration alone; passed: suite/lenses.test.ts a lens is a value of Lens: it reads what is its library's and makes its pages after the or

Cited by: config, evidence, Documentation generator, lens, site

FR-027checkpassing

A repository with no about.ts MUST still be documented: its configuration gives each package's About value (its title, summary and areas, each area with its entry points), and the home's, and the pages are made from them as from an about.ts; a finding about such a value names the configuration's file.

Enforced (check): .github: cd commons/docs && bun run verify — fixture-repo.test.ts: a fixture repository with no about.ts and a plain spec kit builds with no finding

Proved by: docs/suite/config.test.ts, docs/suite/fixture-repo.test.ts

Tests: passed: suite/config.test.ts defaults are filled, folders made relative to the root, and an About value kept; passed: suite/fixture-repo.test.ts the fixture repository builds with no finding, from its configuration alone

Cited by: config, Documentation generator, pages/overview, sources

FR-028checkpassing

Every page of the site MUST also be written as Markdown beside its HTML, with the same path and .md, made from the same page model (every case of a block and an inline has a form in Markdown, matched with an exhaustive switch; a link to a page goes to its Markdown twin), and the site MUST have llms.txt at its root: its name and every page by section, as a link to its Markdown twin with its description, and the files a lens adds (the JSON of a model), so that a program reads the words and the structure and not the markup. The same sources give the same bytes.

Enforced (check): .github: cd commons/docs && bun run verify — twins.test.ts: every block and inline has a Markdown form, links go to twins, the same page gives the same text; the index for a program; a site is written with a .md beside each .html and llms.txt

Proved by: docs/suite/twins.test.ts

Tests: passed: suite/twins.test.ts a site is written with a .md beside each .html, llms.txt at the root, and the files a lens; passed: suite/twins.test.ts every block and inline has a Markdown form, links to pages go to their twins, and the same; passed: suite/twins.test.ts the index for a program lists every page by section with its description and the files a l

Cited by: emit/markdown, Documentation generator, lens

FR-029checkfailing

The package MUST ship, beside the lenses of commons' configuration, a layered-model lens (commons/docs/lens/layered.ts) that knows no library: given a function that makes LayeredModel values (the package's types-only contract, layered.ts: layers, elements with a stable id, kind, name, definition, source location and properties, trace edges from an element of one layer to what it is made into, and findings) and the files that export the values the models are made of, it MUST make, in the Models section, a page of the layers (what each is for, which code writes it, what may be edited, how to change a model and regenerate what follows, and what an agent reads), a page for each model with a diagram of its concepts, a page for each concept (its definition, where it is written as a link to the file and line, its attributes and relationships, what it projects to and what it is written as), a page for each code list, and registers of what the models annotate; and it MUST add the JSON of each model and of the list of models to the site. It MUST find where an element is written from the identity of the values the given files export, so that a project's own models are documented the same way, and it MUST name in a finding a file that it cannot read.

Enforced (check): .github: cd commons/docs && bun run verify — layered-lens.test.ts: the layers page, a page for each model, concept and code list, registers and JSON; links resolve and sources are links to lines; the data models are on commons' own site with no finding

Proved by: docs/suite/layered-lens.test.ts

Tests: passed: suite/layered-lens.test.ts a file that is told to export models and cannot be read is a finding that names it, and th; failed: suite/layered-lens.test.ts commons' own site has the data models: the layers, each model, each concept with its SQL a; passed: suite/layered-lens.test.ts the JSON of each model and of the list is added to the site, and the same models give the ; passed: suite/layered-lens.test.ts the lens makes the page of the layers, a page for each model, concept and code list, and t

Cited by: Documentation generator, layered, lens/layered, model, Kanon, sql-describe

FR-030checkpassing

The package MUST ship a program lens (lens/program.ts) that is given a function making LayeredModel values for the programs of a library built on commons headless (one model for each tier of a program, with the same element ids in each) and knows nothing of headless: it MUST make a page set for each model and never merge two models by id, a page of the programs with a card for each, for each model a page of its verbs (what each does, its effect, the surfaces that draw it and the reasons it is not drawn), its plugins, problem codes, exit statuses and findings, for each verb a page of its action as governance says it, its operands, options, examples and the command, tool and route it is drawn as (or that it is drawn by no surface for the tier), and the JSON of each model and of the list, the same models giving the same pages.

Enforced (check): .github: cd commons/docs && bun run verify — pending

Proved by: docs/suite/program-lens.test.ts

Tests: passed: suite/program-lens.test.ts the JSON of each model and of the list is added to the site, and the same models give the ; passed: suite/program-lens.test.ts the lens makes a page set for each tier with the same element ids and never merges them: a

Cited by: Documentation generator, lens/program

FR-031checkfailing

Every library of commons (a folder with a manifest, a package.json and an about.ts) MUST be a package of commons' site, with one area whose entry points are the files its package.json exports and whose folder is their longest shared folder, so that the site has a page and an API reference for each library; a page of a library MUST show its manifest's facts (version, conformance level, distribution) and the specifications of its own spec kit; the register and the pages of the specifications MUST be grouped by the library whose spec kit holds them; a module comment MUST be found after any // lines (such as a // Spec: header); and a namespace export MUST count as documented by the module comment of the file it names.

Enforced (check): .github: cd commons/docs && bun run verify — library-site.test.ts: a module comment after a // header, kit and area folders, a page and an API for every library, specifications grouped by library

Proved by: docs/suite/library-site.test.ts

Tests: passed: suite/library-site.test.ts a module comment is found after `// Spec:` lines, a kit belongs to the library whose folde; failed: suite/library-site.test.ts commons' site has a page and an API for every library, shows each library's specifications

FR-032checkfailing

The package MUST ship a guides lens (lens/guides.ts) that is given Markdown files with the address, section, group and order of each, and makes a page of each, its first heading being its title, with its citations of a specification and its links to a file or a folder resolved like those of every page and a guide that cannot be read a finding; the sections of the site MUST be, in order, Start here, Concepts, Libraries, How-to, Specifications, API and Models, each shown where it has a page; and commons' site MUST have a path for each kind of reader (a new developer, a contributor, an agent, an auditor), a page for each concept the repository is built on, and the how-to pages for finding where something lives, adding a library, adding a command to the workspaces program and cutting a release.

Enforced (check): .github: cd commons/docs && bun run verify — guides.test.ts: a guide that cannot be read is a finding, the sections are in order, every section has its guides with links resolved

Proved by: docs/suite/guides.test.ts

Tests: failed: suite/guides.test.ts commons' site has the guides of every section with their citations and links resolved to p; passed: suite/guides.test.ts a guide that cannot be read is a finding, and the sections are in the order of a newcomer'

Cited by: Documentation generator, lens/guides, model

FR-033checkfailing

The site MUST have a page of the library map, with a diagram and a table of what each library of the site imports and what imports it, read from the packages its own sources (not its tests, tools or manifest) import by name, and the page of each library MUST list what it imports and what imports it.

Enforced (check): .github: cd commons/docs && bun run verify — guides.test.ts: the library map and the imports of each library are read from the sources

Proved by: docs/suite/guides.test.ts

Tests: failed: suite/guides.test.ts commons' site has the guides of every section with their citations and links resolved to p

FR-034checkpassing

The site MUST follow the reader's system between a light and a dark theme with every colour a token, MUST let the reader choose one with a button and with t and keep the choice in the reader's browser only, MUST set the theme before the page is drawn so that it does not flash, MUST have keyboard navigation (/ for the search, [ and ] for the previous and next page of the side navigation), and MUST have a print style that leaves out the navigation and prints the address of each external link.

Enforced (check): .github: cd commons/docs && bun run verify — theme.test.ts: dark tokens for the system and for a choice, the button and the script that sets the theme first, the keyboard shortcuts and the print style

Proved by: docs/suite/theme.test.ts

Tests: passed: suite/theme.test.ts every page sets the theme before it is drawn and has the theme button; the stylesheet has

FR-035checkpassing

Under each requirement of a specification the site MUST say which files prove it (the test files that name it in a quoted string) and which are written to it (the files whose // Spec: header names it), as links to the files; the page of a library built in layers MUST show its layers and the folders of each from its manifest; the package MUST ship a releases lens that reads the record of the next release and makes a page of each library it publishes, with its version, its tag and its place in the order, and a record that cannot be read is a finding; and the search MUST be filterable by the kind of what it finds.

Enforced (check): .github: cd commons/docs && bun run verify — explorers.test.ts: the trace under a requirement, the layers of a library, the releases page, and the search filter

Proved by: docs/suite/explorers.test.ts

Tests: passed: suite/explorers.test.ts a requirement says which tests name it and which files are written to it, and the page of ; passed: suite/explorers.test.ts the page of a library built in layers shows its layers in the order governance, logical, p; passed: suite/explorers.test.ts the releases page lists the record in its order, and a record that cannot be read is a fin; passed: suite/explorers.test.ts the search has a filter by kind, which the script fills from the index

Cited by: Documentation generator, lens/releases

FR-036checkpassing

A configuration MAY name retired (names that no page of the site may have) and forbiddenInGuides (words that no page of the sections Start here, Concepts and How-to may have), and a page that has one is a finding, so that the site names no library that is gone and the pages people write say what is and nothing that was; commons' configuration MUST name both, and the site MUST answer from itself, by its search and its pages, the newcomer's questions of what to run first, what a library imports, where a requirement is proved, where a command is described and how a release is made.

Enforced (check): .github: cd commons/docs && bun run verify — newcomer.test.ts: five newcomer questions answered from the site, retired names and history words found, none on commons' site

Proved by: docs/suite/newcomer.test.ts

Tests: passed: suite/newcomer.test.ts a page that names a retired library, or a page people write that uses a word of history, i; passed: suite/newcomer.test.ts five questions a newcomer asks are answered from the site alone: the front door, what a li

FR-037checkpassing

Code MUST be coloured and diagrams MUST be drawn when the site is built, so that a page shows both with no script and no request: code with Shiki, on its Oniguruma engine, for TypeScript, SQL, shell, TOML, JSON, Turtle and YAML, each run carrying its colour for the light scheme and for the dark as custom properties that the stylesheet picks between by the rule of FR-034, the same text always giving the same runs whichever grammar was read first, code longer than 6000 characters and the text of other languages left plain; and diagrams as SVG with beautiful-mermaid, in the page's own colour tokens, so that the dark scheme needs no second drawing, and, where a diagram cannot be drawn, its source in a code block; the source of every diagram stays on its page, and the Markdown twin keeps it as a Mermaid fence.

Enforced (check): .github: cd commons/docs && bun run verify — highlight.test.ts: each language cut into tokens with its colour for both schemes, the same runs every time, and the diagram drawn into the page

Proved by: docs/suite/guides.test.ts, docs/suite/highlight.test.ts

Tests: passed: suite/guides.test.ts a Mermaid fence in Markdown is a diagram block with its source, a diagram of a type the re; passed: suite/highlight.test.ts each language of the site is cut into its tokens, each with its colour in the light and in; passed: suite/highlight.test.ts the same text gives the same runs every time, so that the first reading of a grammar is no

FR-038checkfailing

The How-to section MUST have a group "With an AI assistant" of guides in files named ai-*.md: a start page, and a guide for each common task that a person asks an assistant to do. Each task guide MUST have, in order, the headings When to use it, What to give the assistant, The prompt, Check the result and Common mistakes, and The prompt MUST hold a fenced block tagged prompt. Every path in a code span of these guides MUST exist, every repoctl command MUST be one the program lists, every bun run script MUST be one of the root or of a library, and every specification cited by its number MUST exist; and each guide MUST name the command that proves the result (bun run verify, bun run dev:check or bun run repoctl check), so that a prompt guide cannot go stale without the tests saying so.

Enforced (check): .github: cd commons/docs && bun run verify — ai-guides.test.ts: the AI guides have the headings and a prompt block, and every path, repoctl command, script and specification they name exists

Proved by: docs/suite/ai-guides.test.ts

Tests: failed: suite/ai-guides.test.ts commons' site has a page for each AI guide in the group With an AI assistant; passed: suite/ai-guides.test.ts each task guide has the five headings in order and a prompt block, and each guide names th; passed: suite/ai-guides.test.ts every path, repoctl verb, bun run script and specification number the guides name exists

FR-039checkpassing

The site MUST be easy to move around in: the navigation groups its pages under collapsible headings that open on the page's own trail, the Models section groups its models by subject (a subject being named by the data library's governance), the Programs have a tab of their own, and the specification matrix is split by library into pages of at most ROW_BUDGET rows with a summary page, each table filterable.

Enforced (check): .github: cd commons/docs && bun run verify — specs.test.ts: the matrix is split by library within the row budget; guides.test.ts: the sections, Programs among them

Proved by: docs/suite/guides.test.ts, docs/suite/specs.test.ts

Tests: passed: suite/guides.test.ts a guide that cannot be read is a finding, and the sections are in the order of a newcomer'; passed: suite/specs.test.ts every specification in force has a page with an anchor and the enforcement of each require

FR-040checkpassing

Commons' configuration MUST name the five volumes of the series Commons Manuals (commons-guide, commons-api-reference, commons-data-models, commons-specifications, commons-programs), the pages of the site as the generated chapter sources of books of erga (docs 0001-docs FR-008): the data models in a part for each subject, the API and the specifications in a part for each library, and neither the specification register nor the traceability matrix, which are for the screen. Every cross reference of a volume MUST have its anchor in the volume.

Enforced (check): .github: cd commons/docs && bun run verify — book.test.ts: commons' five volumes of the Commons Manuals have chapters, anchors that resolve, and no matrix or register, and the same pages give the same files

Proved by: docs/suite/book.test.ts

Tests: passed: suite/book.test.ts commons' five volumes of the Commons Manuals have chapters, anchors that resolve, and no m

FR-041checkfailing

Commons' configuration MUST give evidence (docs 0001-docs FR-009 to FR-012): the results of the tests in _evidence/ (not committed; CI leaves them there, and a build made by hand has none, which the pages say), the snapshot of the open GitHub issues in the same folder, and the issues of commons/data, each set with its scope, read from the library. The site MUST have the Quality section and, beside each requirement, library and module, what the tests and the open issues say.

Enforced (check): .github: bun test ./tests/ — commons-site-evidence.test.ts: commons' configuration gives the evidence: the results folder, the GitHub snapshot in it, and the issues of data with their scopes; check.test.ts in commons/docs: the site of commons has the Quality section and the issues of data

Proved by: docs/suite/check.test.ts, tests/commons-site-evidence.test.ts

Tests: failed: suite/check.test.ts the site of commons builds with no finding, the same twice, with its sections, the Quality; passed: tests/commons-site-evidence.test.ts commons' configuration gives the evidence: the results folder, the GitHub snapshot in it,

FR-042checkfailing

The workflow site MUST run the tests of every library that has a suite and of the repository's own tests/ on a push to main (a job for each, in parallel), keep each run's CTRF report with tools/evidence.ts of docs, fetch the open issues of the repository, and build the site from them, and it MUST publish the site whether or not a test failed, the banner of the Quality section being how a failure is seen; a run that cannot be made for a library MUST leave that library with no run recorded and not fail the publication.

Enforced (check): .github: bun test ./tests/ — commons-site-evidence.test.ts: the workflow site runs the tests of every library and of the repository on main, keeps each report, fetches the open issues and publishes the site whether or not a test failed

Proved by: tests/commons-site-evidence.test.ts

Tests: failed: tests/commons-site-evidence.test.ts the evidence workflow runs the tests of every library by the hour and keeps each report wi

Out of scope

  • The ontology (commons/ontology/): it moves to TypeScript, and is then shown by a lens of its own.
  • A link from a type in a signature to its page, versions of the API for each tagged commit, D2 diagrams, Rust and Zod output, and languages other than TypeScript.

Edge cases

  • An export whose TSDoc was removed: --check names it, per FR-018 and FR-010.
  • A module of a model that throws when imported: --check names the module and the site is not published, per FR-018 and FR-013.
  • A documentation comment that cites a requirement of erga 009-machine-bootstrap: the page shows the text, with no link, per FR-011.
  • A comment that cites a requirement number its specification does not have: --check names it, per FR-018 and FR-011.
  • A package's about whose command was renamed in package.json: --check names it, per FR-018 and FR-005.
  • A table of a model with no description: --check names it, per FR-018 and FR-013.
  • A signature thousands of characters long (a model's computed row type): it is shown whole and folded, per FR-010 and FR-017.
  • The site published under /.github/: every link is relative, so it works there and at a custom domain alike, per FR-017.
  • A README added to commons: the tests of the layout fail, per FR-004.
  • ifc-docs check run by Node 26 from a repository's node_modules: the package ships compiled modules, so it runs as on Bun, per FR-021.
  • A lens that imported a data library from the generator's library entry point: the test of FR-026 names it, since ./docs and ifc-docs must reach no library they show, per FR-026 and FR-002.
  • A configuration that names a package with no slug, or a spec kit of an unknown layout: the command names each problem and exits 2, per FR-023 and FR-003.
  • Stolos citing commons 0011-documentation FR-003: with commons listed as linked, the citation goes to commons' published site; with commons not listed, it is text, per FR-025 and FR-011.
  • A plain spec kit whose requirement is written - **FR-001** text over two lines, or numbered FR-005a: it is one requirement, with its anchor, per FR-024.
  • Stolos's spec 004 FR-015 in the text of spec 005: the requirement is spec 004's, not 005's, per FR-025.
  • Two spec kits that both hold 001-platform: check names the second, per FR-018 and FR-024.
  • A repository with no lens: its site has no Models section, per FR-009 and FR-026.

Assumptions

  • The TypeScript 7.1 programmatic API, in beta, keeps the shape it has in 7.1.0-beta; the generator is pinned to that version and moves to the stable 7.1 when it is released.
  • GitHub Pages serves a repository named .github under /.github/; where it does not, the site is published at a custom domain with no change to it.
  • A model module only defines values when it is imported, which is how the models of commons data are written.
  • A repository that uses the package runs it where its own dependencies are installed, so that the modules it documents and its @types/node resolve as they do for its own compiler.

Open questions

OQ-1open question

Whether the root README.md should also be made from commons/about.ts once the site is the only documentation people read.

OQ-2open question

Whether the documentation of a tagged commit of commons should be kept beside the latest, under its tag.

Key entities

  • Area - a part of commons with an entry point, named by its package's about, and its pages.
  • About - the typed facts of a package: summary, specification, folders, commands, rules, and its areas with their phases and examples.
  • Page model - the tagged union of blocks and inlines every page is made of before it is HTML.
  • Lens - what the generator knows of one library: which exports are its, and the pages their values make.
  • Finding - a place and a sentence saying what check found there.
  • Configuration - the typed value a repository gives (DocsConfig), checked once into the resolved configuration the build reads.

Success criteria

SC-001success criterion

cd commons/docs && bun run verify (the compiler, the tests, then check on commons) passes.

SC-002success criterion

The published site has a page for every export of every area, for every table of Arca's party model with its diagram and its SQL for the three dialects, and for every specification in force.

SC-003success criterion

bun run smoke (FR-021) passes on Bun and on Node 26 from a git+file: URL of a commit, and Stolos's site builds from a copy of Stolos with a configuration and no about.ts.

Review & acceptance checklist

  • [x] Every requirement is testable (MUST / MUST NOT), not aspirational
  • [x] No company fact is asserted here
  • [x] Every open item is marked, not silently decided

Cited by

about, Core, build, check, cli, config, emit/markdown, evidence, extract/api, extract/specs, Documentation generator, layered, lens/guides, lens/layered, lens/program, lens/releases, lens, links, model, pages/overview, site, sources, tsdoc, model, Docs, Software supply chain, Mizan, the IF Spec Profile, Repoctl docs verbs, The ontology in TypeScript, Trust, Kanon, sql-describe

Titles, headings, exports, tables, columns and requirements. Esc closes.