Generate the user documentation of the website with AI, from the last documented commit to the current commit #375

Goal

The user documentation on the public website (packages/auxiliary/website_public/docs/documentation/) is written entirely by AI. No person writes or edits a documentation page by hand.

• When a feature is added, a section for the feature appears in the documentation.
• When a feature is removed, the section of the feature disappears from the documentation.
• When a feature changes, the section of the feature changes.

The process: one command, a full check every time

The update is not live. The developer runs one command when the developer wants the documentation to be up to date:

pnpm docs:update_by_ai

Every run is a full check: the AI agent compares all the documentation with all the current rules and code. The commits since the last run are only a hint that says which sections to look at first. This way, small errors do not add up from one run to the next, and a removed feature always disappears.

1. The command reads the last documented commit from a file in the repository, for example packages/auxiliary/website_public/docs/documentation/.last_documented_commit.
2. The command reads the current commit (HEAD).
3. The command collects the hints, what changed between the two commits:
   • the list of merged pull requests, with their titles and descriptions (the package change_log_generator already finds this range);
   • the closed issues that these pull requests fix;
   • the diff of the user-facing code and of the rules in docs/agents_rules/user_interface/.
4. The command starts an AI agent (Codex, without interaction) with the hints, all the current documentation pages, all the rule files in docs/agents_rules/user_interface/, and the glossary glossary.
5. The AI agent first looks at the sections that the hints point to. Then the AI agent checks every other section against the current rules and code. For each feature, the AI agent decides:
   • add a page or a section for a new feature;
   • change the section of a changed feature;
   • remove the section of a removed feature;
   • do nothing for an internal change (refactor, test, build, developer tool).
6. The AI agent writes the pages, updates the sidebar in docs/.vitepress/config.ts, and leaves the last documented commit unchanged until validation succeeds.
7. The command runs pnpm --filter website_public test and the VitePress build. Only after generation and validation succeed, the command records the source revision as the last documented commit.
8. The command uses a separate temporary worktree, commits the checked result and opens a draft pull request with the result, and a short report: which sections were added, changed, and removed, and why. The developer reads the pull request and merges it. Deployment through ghpage:deploy remains a separate action after review and merge.

When .last_documented_commit does not exist (the first run), the command has no hints and does only the full check.

Source of truth

The AI agent writes from these sources, in this order:

1. docs/agents_rules/user_interface/ and glossary: the rules say what the application does now, so a removed feature is also removed from the rules.
2. The code of the application.
3. The pull requests and the issues between the two commits: they say what changed, and why. They are hints, not the source of truth.

The AI agent writes only what the sources show. It does not invent a feature.

Rules for the generated pages

• Every generated page has a mark, for example a comment <!-- generated by docs:update_by_ai -->, so the AI agent knows which pages it owns.
• The words of the documentation are the words of the glossary.
• The page shortcuts.md stays generated by pnpm docs:shortcuts; the AI agent does not edit it.
• Each section of a feature names the source rule file, so a removed rule file shows which section to remove.

Tests

• A test fails when .last_documented_commit is not an ancestor of HEAD.
• A test fails when a generated page has no mark.
• A test fails when a section names a source rule file that does not exist.
• A test checks the collection of hints between two known commits, with no AI agent.

Decisions confirmed on 26 October 2026

• All commits since the last documented commit count as hints, with merged pull requests adding context. Every run still checks all current documentation against the current sources.
• The command starts from a clean personal development branch, writes in a separate temporary worktree, and creates a draft pull request after generation and validation succeed. The developer reviews and merges the draft; the command does not merge or deploy.
• Screenshots are allowed when captured separately from the matching Heidrun Code Development build, with the source version and verification limits recorded. The command accepts those captures as evidence; the command does not take screenshots.
• The current glossary is the folder linked above, not the former single glossary file.

The master issue gives the order of the work:

• Doc by AI: Master issue: complete the user documentation of the website written by AI #921