| 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
- 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.
- 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
- 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
- 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.
- 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.
- 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
- 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.
- 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.
