UNOFFICIAL/EXPERIMENTAL
This directory tells agents and maintainers how to work in this repository. It is separate from the public website. The site and docs/user explain the product; this directory lists repo commands, recovery steps, and repo terms.
Doctrine
- Keep the public website written for people evaluating or using the product.
- Keep website docs focused on user tasks and product behavior.
- Put agent and operator instructions in repo Markdown, mainly here.
- Do not change catalog pages or generated chart pages as part of the AX pass.
- Treat catalog data as evidence. If a row is
watch,blocked, orrefused, do not make it green with prose. - Use the narrowest verifier that matches the file or claim you changed.
- Run live lanes only when explicitly needed, and run them serially.
Start With The Task
| Task | Open |
|---|---|
| Choose the right command for a repo task. | Task Recipes |
| Recover from stale generated files, broken links, or failed checks. | Recovery |
| Decide which proof command matches a claim. | Verification For Agents |
| Inspect catalog evidence without changing the catalog. | Catalog Read-Only Guide |
| Keep human and agent docs consistent without copying the same text. | Human And Agent Documentation Doctrine |
| Decode repo-specific terms. | Terms |
Entry Points
Use these before reading older planning prose:
- Documentation Map
- User Docs Reading Order
- NPM Test And Verification Scripts
- Generated Data Index
- Helm Render Intents
- What We Refuse To Claim
- Human And Agent Documentation Doctrine
Basic Operating Rules
- Check
git status --short --branchbefore editing. - Do not touch
site/,site/charts/,recipes/,packages/, or generateddata/unless the user explicitly asks for that generated surface. - When a generated file is stale, update the generator or source data, then regenerate the owned output. Do not hand-edit generated output.
- When editing Markdown, run
npm run docs:verify. - When editing CLI examples, also run the relevant command-surface verifier:
npm run installer:command-surface:verifyornpm run variant:command-surface:verify. - Before claiming a proof lane changed, point to the receipt or verifier that changed it.