Generated docs

Every repository on the System Map has living documentation: pages generated from the map itself, refreshed when the map changes, and navigable by people and read by agents. Every row on a page cites the node, edge, file and line it came from. A model writes only the paragraphs labelled as a model's, and only from the facts listed beside them.

Where it is

The Docs tab on the System Map page, shown when a repository is chosen in the scope picker. It is on both System Map pages, the organization's and the workspace's.

At the top is the documentation set's line — which map version it was generated from, and whether it is generating, failed, or has pages still waiting for a model's prose — with the actions:

• Export as Markdown — every page as Markdown under docs/codebook/, in one ZIP, as you may see it.
• Regenerate — organization administrators. Generates the docs again for the current map version; unchanged pages are carried.
• Open a pull request — organization administrators, after a confirmation. See write-back.

On the left is the page tree — Start here, Services, Modules, Reference — with Search the docs. A page shows Generated from map version X at commit Y, the reason it was generated or carried, and its sections, each with its citation. Rows open the page a service or module has, the node sheet, or the file on the host at the page's commit. Download .md saves one page.

The version picker on the System Map page also chooses the docs: an older map version shows the docs of that version.

The pages

Page	What it holds
Overview	What this system is (prose), counts at a glance, services, modules, languages, frameworks, where to start (each service's main entry files and Dockerfile), and the repository's own docs (README and docs files)
Architecture	How it fits together (prose), services and modules, module dependencies with the import that is the evidence, external systems and queues with their flags and users, patterns, runtime (what each runtime runs and exposes, and the production incidents that affect it), and decision records
A page per service and module	Purpose (prose), public API, depends on, used by, data touched, external systems, tests, recent pull requests, known incidents, related requirements and decisions, and files
API reference	One table per exposing service or module: method, path, handler with its file and line, and the entities the handler's file reads and writes
Data model	Entities with their ORM and fields, personal-data, secret and payment flags with the column evidence, readers, and relations
Onboarding	How to set up and run it (from the README and docs headings, with their commands), the commands the repository declares (package.json, composer.json and pyproject scripts, Makefile and justfile targets, Procfile processes), testing, and containers and deployment files
Glossary	The organization's own terms — products, requirements, decisions — linked to this repository's code

The pages are a pure function of the map: the same map gives the same pages byte for byte. Nothing is summarised away silently: a section holds at most 200 rows and then says how many there were, a set holds at most 300 service and module pages and the overview names what was left out, and an empty section says why rather than disappearing.

Commands are read, never run. The onboarding page parses the scripts and targets a repository declares; CodeBook does not execute them. It reads at most 12 such files per set, through the repository's connection, at the map version's commit.

Prose written by a model, from listed facts

A prose section — What this system is, How it fits together, Purpose — is written by the organization's model from numbered facts the rules wrote from the page's own rows, and nothing else. It carries the map's own notice, "Written by a model from N facts. It is prose, not a fact; the facts are listed beside it.", with the facts under it. The facts name only nodes every member of the organization may see.

A paragraph whose facts did not change is copied, not written again. With no model, with summaries switched off in the System Map settings, or when the call fails, the section says so and its facts stand as the whole section. When a model becomes available, only the pages that had no prose are written again. A paragraph that failed is retried only when an administrator presses Regenerate.

Refreshed on push

Each new map version — a push, a merge, a rebuild — queues a documentation set. The set composes every page and compares it with the same page of the previous set:

• Unchanged pages are carried, with the reason Unchanged since map version X. A carried page keeps the version it was generated at.
• Changed or new pages are written again, and the reason says which inputs came, went or changed.

Each page records every node, edge and source it rests on, so "did this page change?" is one comparison. The last 30 finished sets are kept. Pull requests, requirements and incidents can change without a new map version; Regenerate picks those up. When the host cannot be read for the onboarding files, the previous onboarding page is carried with that reason rather than replaced by one that lost its commands.

Agents and Ask read it

In the context pack. When the context engine reaches a service or module — itself, or through a file it contains — the sections of that unit's page are candidates in the run's context pack, filtered by the run's own reach: at most 8 pages and 30 sections per run, admitted whole under the same budget as every other item and recorded on the run. Each is cited D<page>:<section>.

In Ask your system. The read_docs tool searches the documentation of the organization's repositories, or reads one page or section, each result cited D<page>:<section>. A D citation no tool returned is flagged under the answer like any other. See Ask your system.

A work snapshot records the map version a run read, and the docs set of that version is the newest finished set at or before it.

Who sees what

The docs belong to the repository's organization, like its map. Each reader sees the pages filtered for them: a row citing a node they may not see — a factory or workspace row they cannot open, a linked product's node, another organization's — is dropped and counted, and the page says how many rows were hidden. A paragraph resting on a fact they may not see is withheld the same way. A Markdown export is the reader's filtered view.

Write-back to the repository

Open a pull request is never automatic. An organization administrator confirms it, and CodeBook then:

1. creates a branch from the default branch's head, through the repository's own host connection;
2. commits docs/codebook/README.md (an index) and one file per page — overview.md, architecture.md, api-reference.md, data-model.md, onboarding.md, glossary.md, and services/<key>.md and modules/<key>.md (past 30 files, the unit pages are joined into services.md and modules.md);
3. deletes the generated files under docs/codebook/ that the set no longer has;
4. opens a pull request for a person to review, and records it on the pull requests CodeBook tracks.

The files carry only what every member of the organization may see: rows citing factory, workspace or linked-product records are left out, because the repository's readers are outside CodeBook's permissions. Links in the files point at the host at the commit each page was generated from.

Limits

• The docs are as complete as the map. A limited map gives limited docs, and a data entity's writers are not derived.
• Incident signals on cards are not listed on pages. Only incident nodes are — MadeBook violations and production incidents — because a card belongs to a factory the reader may not open, and a page is shared.
• Prose is not re-asked when only the model changed.
• Each write-back opens a new branch and pull request. An open docs pull request is not updated in place.

Next

System Map — what the pages are generated from. Production monitoring — where the runtime section and known incidents come from.