a67525cdf1
* docs: organize canonical documentation layout (URGENTE) Group all existing authored guides by domain and ownership, expose complete navigation, and preserve their public routes. Update physical path consumers and release configuration while retaining historical records. Document domain-based specs and ADR slugs without global numbering. Co-Authored-By: Codex <[email protected]> * fix(docs): honor home layout in all-page route verification * style: format reviewed source changes * fix(docs): preserve routes and navigation cache inputs * fix: repair the static-check failures on the default branch (#2895) * fix: repair the static-check failures on the default branch The default branch fails its own required `Static checks` job three ways, so every pull request reports that job as failed regardless of its own change. - `npm run format:check` reports `src/domain/functionComparison.test.ts` and `src/ida/IdaOperationRunner.ts`. - `npm run lint` reports a duplicate `import { join } from "node:path"` in `tests/boundary/mcp/ghidraInventoryMcp.test.ts` (lines 4 and 17). - `npm run typecheck` reports `format: "devin"` missing from the client format union in `src/application/SupportedClients.ts`, and an unchecked index in `tests/boundary/cli/clientProfileLifecycle.test.ts`, whose pair array is inferred as `string[][]`. Apply the pinned formatter, drop the duplicate import, list the `"devin"` format that its own definition already uses, and mark the pair array `as const`. Validation: `npm run check:fast` and `npm run format:check` pass. * fix(setup): keep Devin on the JSON configuration dialect --------- Co-authored-by: 吴佳浩 <[email protected]> Co-authored-by: morluto <[email protected]> * fix(docs): update links after guide relocation * docs: correct verified documentation route counts * fix(docs): update browser capture guide link after move (#2820) Refresh gettext protected-link comments alongside the authored href. Co-authored-by: Codex <[email protected]> * fix(docs): include http3 lab in stable routes * fix(docs): preserve historical release evidence and links * fix(ghidra): restore Windows verifier identity import * docs(wakaru): preserve pinned upstream policy link * docs(index): retain recently added guide links * docs(mcp): preserve parent retention clarification * fix(cli): preserve standalone import guidance * fix(test): preserve translated guide link drift coverage --------- Co-authored-by: Matheus Breguêz <[email protected]> Co-authored-by: Codex <[email protected]> Co-authored-by: morluto <[email protected]> Co-authored-by: 吴佳浩Alben <[email protected]> Co-authored-by: 吴佳浩 <[email protected]>
4.8 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.
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.