mirror of
https://github.com/boshu2/agentops.git
synced 2026-09-14 15:08:13 +08:00
Claude
c4166a5c51
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).