morluto
959af004df
* docs: refuse literal tool counts in living prose docs:check now refuses a count of ten or more tools in README, AGENTS, CONTRIBUTING, docs/ (except dated releases, specs, verification and ADR records), the authored skill and the public website. The catalog owns that number and every hand-written copy goes stale when a tool is added. The three current statements (240, 172 and 254 tools, all measured on earlier builds) now refer to the catalog of the measured build instead. * fix(docs): exclude generated pages from prose checks * fix(docs): rerun the tool-count check when any scanned prose changes The docs:check:built cache inputs and the CI docs lane did not cover AGENTS.md, CONTRIBUTING.md, every .agents/skills tree or website/public, so an edit there could reuse a cached pass or skip the docs job. The scanner now owns one isLivingProsePath predicate; the CI plan selects the docs lane with it, and a test binds the turbo inputs to the scanned roots.
5.0 KiB
Documentation ownership and authoring
Use the documentation directory to find existing material before adding another guide. Preserve one canonical owner for each contract or workflow; link to that owner instead of copying its claims into several guides.
Choose a destination
| Document | Destination |
|---|---|
| Installation, client setup and first CLI/MCP steps | docs/getting-started/ |
| Analyst workflows and evidence interpretation | docs/guides/<domain>/ |
| Analysis-engine configuration and format prerequisites | docs/providers/ |
| Shared runtime contracts and evidence semantics | docs/reference/ |
| Development, testing, release and authoring instructions | docs/development/ |
| Composition diagrams | docs/architecture/ |
| Compatibility changes for a released version | docs/migrations/ |
| One feature specification, plan and tasks | docs/specs/<domain>/<feature-slug>/ |
| One architectural decision | docs/adr/<domain>/<decision-slug>.md |
Use meaningful, lowercase domain and feature slugs. Global numeric prefixes are unnecessary: different domains can add features independently, and branches do not compete for the next sequence number. Check the existing domain directory and linked issues before creating a feature with the same slug.
Guides describe existing behavior and limitations. Specs define one proposed
feature or domain change; an existing guide does not become a specification by
moving it into specs/.
Feature lifecycle
Create the specification before implementation. Each feature directory contains:
spec.md: problem, desired behavior, requirements, acceptance and non-goals.plan.md: the single implementation plan, contracts and architectural choices.tasks.md: incremental, testable steps linked to requirements and verification.
Split independent domains or separately reviewable features before writing their
specs. A broad ROADMAP.md, when useful, only lists child specifications, order
and dependencies; requirements and implementation tasks belong to each child.
Cross-repository contracts have one producer-owned specification. Consumers link
to that contract instead of maintaining competing copies.
Record an isolated architectural decision separately in
docs/adr/<domain>/<decision-slug>.md, with Status, Context,
Decision and Consequences. Link the ADR from affected specifications.
Do not create decision records for routine file moves or invent past decisions.
Specs do not replace the contribution-scope decision required for a new provider or expanded execution authority. Follow contribution scope.
Links and public routes
Use relative links to physical Markdown files so GitHub readers can follow them.
Link repository files outside docs/ with their full GitHub URLs. Preserve
existing heading anchors when moving a guide.
documentation.ts
owns categorized site navigation and the existing guides' stable public routes.
Update it when adding or moving a guide. VitePress rewrites categorized sources
to the existing public paths; its Markdown hook resolves repository links from
the physical source and renders them against those public routes. Keep basenames
and route assignments unique. Edit links use the physical source file.
For a move, search for both the basename and its old full path. Update README translations, authored skills, verification instructions, documentation-fact readers and release configuration when they consume that path. Preserve historical release records and references bound to earlier commits or tags.
Generated ownership and checks
The documentation directory identifies the machine-owned outputs and their producers. Their existing paths are retained because scripts, package consumers and release history depend on them. Change canonical sources and regenerate; do not fix a generated projection by hand.
Do not write the number of tools in living prose; link the generated catalog
instead. docs:check refuses a count of ten or more tools outside dated
records (docs/releases/, docs/specs/, docs/verification/, docs/adr/).
Run npm run docs:check for documentation facts and generated consistency, and
npm run verify:docs:routes to build the complete production site and check local
links, anchors and physical edit targets.
When a physical path moves, also run the tests that read it. Follow
development checks before requesting review.