docs: fix broken CLI links, add HOOKS/SCHEMAS/UPGRADING pages, expand GLOSSARY
Addresses a batch of documentation improvements identified in a full-docs
audit. The goal is to reduce newcomer friction from dead links and missing
canonical references, and to give skill/plugin authors explicit pages for
hooks, schemas, and version migration that were previously implied only by
source code.
Navigation fixes:
- docs/INDEX.md and docs/newcomer-guide.md pointed to the wrong path for
the CLI reference (cli/commands.md vs. the real cli/docs/COMMANDS.md).
Replace with the canonical github URL so both mkdocs and raw-GitHub
readers land on the file.
- INDEX.md Getting Started section now opens with a "pick your path"
router so evaluators, installers, contributors, and upgraders don't
have to triangulate across three overlapping entry points.
- Link docs/getting-started/index.md from INDEX.md (was previously
orphaned) and add an "Install verification" block pointing at ao doctor.
New pages:
- docs/HOOKS.md: user-facing orientation covering lifecycle events,
install/uninstall, customization env vars, and common failure modes,
pointing to cli/docs/HOOKS.md for the deep technical reference.
- docs/SCHEMAS.md: catalog of every JSON Schema under schemas/ and
lib/schemas/, grouped by manifest vs. runtime artifact vs. internal
contract, with validation commands.
- docs/UPGRADING.md: action-required version migration guide. Seeds
Unreleased (2.38.x) and 2.37.x sections covering strict delegation,
--no-lifecycle -> --no-scaffold rename, Olympus bridge removal,
swarm-evidence schema enforcement, and pre-mortem gate tightening.
Reference quality:
- GLOSSARY.md: 11 new terms (.agents/, MEMORY.md, Compact/PreCompact,
Compile, Context Window, Discovery, Dream/Overnight Run alias,
Flywheel Health, Harvest, Holdout, RPI Phase, Session Lifecycle).
- troubleshooting.md: three new failure-mode sections (pre-mortem gate,
go-test-precommit block, context-window compaction recovery).
- CONTRIBUTING.md: escalates the sync-skill-counts.sh requirement from
an easily-missed sentence to a bold callout with CI-failure rationale.
mkdocs.yml: registers the three new pages in nav so they're reachable
from the published site and pass strict build.
Validation:
- tests/docs/validate-links.sh: 1553 links checked, 0 broken.
- tests/docs/validate-doc-release.sh: PASS.
- scripts/docs-build.sh --check: new docs introduce 0 warnings (the
single remaining preexisting warning about index.md is out of scope).
2026-04-22 05:01:02 +00:00
|
|
|
# Schemas
|
|
|
|
|
|
2026-07-14 22:01:50 -04:00
|
|
|
## Core loop
|
docs: fix broken CLI links, add HOOKS/SCHEMAS/UPGRADING pages, expand GLOSSARY
Addresses a batch of documentation improvements identified in a full-docs
audit. The goal is to reduce newcomer friction from dead links and missing
canonical references, and to give skill/plugin authors explicit pages for
hooks, schemas, and version migration that were previously implied only by
source code.
Navigation fixes:
- docs/INDEX.md and docs/newcomer-guide.md pointed to the wrong path for
the CLI reference (cli/commands.md vs. the real cli/docs/COMMANDS.md).
Replace with the canonical github URL so both mkdocs and raw-GitHub
readers land on the file.
- INDEX.md Getting Started section now opens with a "pick your path"
router so evaluators, installers, contributors, and upgraders don't
have to triangulate across three overlapping entry points.
- Link docs/getting-started/index.md from INDEX.md (was previously
orphaned) and add an "Install verification" block pointing at ao doctor.
New pages:
- docs/HOOKS.md: user-facing orientation covering lifecycle events,
install/uninstall, customization env vars, and common failure modes,
pointing to cli/docs/HOOKS.md for the deep technical reference.
- docs/SCHEMAS.md: catalog of every JSON Schema under schemas/ and
lib/schemas/, grouped by manifest vs. runtime artifact vs. internal
contract, with validation commands.
- docs/UPGRADING.md: action-required version migration guide. Seeds
Unreleased (2.38.x) and 2.37.x sections covering strict delegation,
--no-lifecycle -> --no-scaffold rename, Olympus bridge removal,
swarm-evidence schema enforcement, and pre-mortem gate tightening.
Reference quality:
- GLOSSARY.md: 11 new terms (.agents/, MEMORY.md, Compact/PreCompact,
Compile, Context Window, Discovery, Dream/Overnight Run alias,
Flywheel Health, Harvest, Holdout, RPI Phase, Session Lifecycle).
- troubleshooting.md: three new failure-mode sections (pre-mortem gate,
go-test-precommit block, context-window compaction recovery).
- CONTRIBUTING.md: escalates the sync-skill-counts.sh requirement from
an easily-missed sentence to a bold callout with CI-failure rationale.
mkdocs.yml: registers the three new pages in nav so they're reachable
from the published site and pass strict build.
Validation:
- tests/docs/validate-links.sh: 1553 links checked, 0 broken.
- tests/docs/validate-doc-release.sh: PASS.
- scripts/docs-build.sh --check: new docs introduce 0 warnings (the
single remaining preexisting warning about index.md is out of scope).
2026-04-22 05:01:02 +00:00
|
|
|
|
|
|
|
|
| Schema | Purpose |
|
2026-07-14 22:01:50 -04:00
|
|
|
|---|---|
|
|
|
|
|
| [`plan-packet.v1`](../schemas/plan-packet.v1.schema.json) | One behavior, acceptance, evidence, and write scope |
|
|
|
|
|
| [`candidate-packet.v1`](../schemas/candidate-packet.v1.schema.json) | Factual implementation result bound to a Plan digest |
|
|
|
|
|
| [`subject-manifest.v1`](../schemas/subject-manifest.v1.schema.json) | Deterministic content identity without Git |
|
|
|
|
|
| [`revision-packet.v1`](../schemas/revision-packet.v1.schema.json) | Caller-authored link between separate invocations |
|
|
|
|
|
| [`verdict.v2`](../schemas/verdict.v2.schema.json) | Independent `PASS`, `FAIL`, or `NOT_PROVEN` judgment |
|
|
|
|
|
| [`rpi-report.v1`](../schemas/rpi-report.v1.schema.json) | Single-pass phase report |
|
|
|
|
|
|
|
|
|
|
Other schemas support read-only CLI observations, generic provenance, tests,
|
|
|
|
|
or repository release tooling. They do not control phase sequencing,
|
|
|
|
|
continuation, Git, delivery, or semantic validity.
|