update-the-docs

name	update-the-docs
description	Regenerate the Acorn website documentation by running the Acorn CLI docs generator, especially the auto-generated library reference under docs/library, from the adjacent acornlib checkout. Use when working in the acornprover.org repository and the user asks to update, refresh, regenerate, or publish docs generated by acorn docs.

Update The Docs

Overview

Update generated documentation for the acornprover.org Docusaurus site by delegating to acorn docs. Treat the adjacent ../acornlib checkout as the source input for generated library docs, and leave the generated Markdown plus provenance ready for review.

How acorn docs Works

The command shape is:

acorn --lib ../acornlib docs ./docs/library

The Acorn CLI uses --lib as the Acorn project root, loads all src targets, and writes documentation into the positional docs directory. It does the real regeneration work:

• Requires the output directory to already exist.
• Requires _category_.json in the output directory.
• Deletes existing top-level *.md files in the output directory before writing new ones.
• Leaves _category_.json and non-Markdown files, such as generated.json, in place.
• Generates one <Name>.md file for each documented top-level type or typeclass.
• Uses canonical or authoritative type/typeclass names and errors on documentation conflicts.
• Emits warnings for missing doc comments.
• Prints <count> files generated in <dir> on success and exits nonzero on load or generation errors.

Because the command deletes existing *.md files before writing replacements, a failure can leave docs/library partially regenerated. Do not manually edit generated docs/library/*.md files to work around generator output. If generation fails, report the exact error, note any partial generated-docs diff, and fix the source library, generator version, or selected acornlib commit before rerunning.

Workflow

1. Inspect repository state.

Run git status --short --branch. Do not overwrite unrelated user changes. If .agents/skills/update-the-docs itself has local edits, preserve them unless the user asked to edit this skill.

2. Ensure the adjacent library input exists.

The source is the adjacent checkout at ../acornlib, which normally resolves to /home/lacker/acornlib when working in /home/lacker/acornprover.org.

If ../acornlib is missing, stop and say that the adjacent checkout is required. Do not add a submodule or silently clone into the website repo.

test -d ../acornlib

3. Update the adjacent checkout only when appropriate.

If the user specifies a branch, tag, or commit, check out that ref in ../acornlib. If the user simply asks to update docs, use the current state of ../acornlib; do not pull, fetch, merge, or switch branches unless the user asks for that.

Before generating, require a clean ../acornlib worktree unless the user explicitly asks to generate from dirty local changes:

git -C ../acornlib status --short

4. Generate library docs.

Prefer the bundled helper, which validates the expected inputs, runs acorn docs, and writes provenance:

python3 .agents/skills/update-the-docs/scripts/update_docs.py

If the user requests a specific Acorn binary, pass it explicitly so provenance records the actual generator:

python3 .agents/skills/update-the-docs/scripts/update_docs.py --acorn-bin /home/lacker/acorn/target/release/acorn

Equivalent manual command:

acorn --lib ../acornlib docs ./docs/library

If acorn is unavailable, find whether the adjacent ../acorn repo can build or run it, but do not install tooling globally without user approval.

5. Handle generation failures.

Common failures:

• Directory ... does not exist: create or restore docs/library.
• missing required _category_.json file: restore docs/library/_category_.json; acorn docs intentionally will not create it.
• Documentation conflict for type ...: fix the selected acornlib commit or Acorn generator behavior; do not hand-edit generated Markdown.
• warning: no doc comments for ...: generation may still succeed, but report the warning so the source doc comments can be improved.

After a failed run, inspect git status --short docs/library. Since acorn docs may have deleted and rewritten Markdown before failing, leave the partial diff visible unless the user asks you to restore generated docs.

6. Record provenance.

The update helper writes docs/library/generated.json after successful generation. If running manually, use:

python3 .agents/skills/update-the-docs/scripts/write_provenance.py

7. Verify the site.

Run a focused verification:

npm run build

Check the built files for generator anchor artifacts that Docusaurus might expose in page titles, sidebar labels, or category descriptions:

rg -n "entity-[a-z]|<!-- #entity|\{#entity" build/docs/category/library-reference/index.html build/docs/library

If a local dev server is running, use Playwright to inspect the generated library reference page in a browser DOM:

node .agents/skills/update-the-docs/scripts/check_library_reference.js

The Playwright check defaults to http://127.0.0.1:3010/docs/category/library-reference/. If the server is on a different URL, pass it explicitly:

node .agents/skills/update-the-docs/scripts/check_library_reference.js http://127.0.0.1:3000/docs/category/library-reference/

If Playwright's bundled Chromium cannot launch in the current sandbox, rerun the same command with the appropriate browser permission. If Playwright is unavailable, fall back to google-chrome --headless screenshots plus targeted rg checks of built HTML.

If dependency installation is missing or stale, ask for approval before networked install commands.

8. Summarize the diff.

Report the acornlib commit used, Acorn CLI version, whether the adjacent acornlib checkout had local changes, whether docs/library changed, and which verification commands passed or failed. Do not commit unless the user asks.

Guardrails

• Never manually edit files under docs/library as a substitute for regeneration.
• Do not add or rely on vendor/acornlib; use the adjacent ../acornlib checkout.
• Do not discard user changes in this repo or in ../acornlib.
• Keep generated docs and provenance together in the same change.
• Record the exact adjacent acornlib commit in docs/library/generated.json.