Files
rea/docs/specs/documentation/organization/plan.md
T
Matheus BreguêzandCodex ea504fac97 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 <noreply@openai.com>
2026-10-12 18:44:55 -03:00

1.6 KiB

Implementation plan

Layout and ownership

Keep docs/index.md as the website landing page. Group authored documents under getting-started/, guides/<domain>/, providers/, reference/, development/ and migrations/. Keep the architecture map under architecture/. Add a linked directory describing every category and its files.

Leave assets/, public/, verification/, releases/, error-contract.schema.json and user-visible-errors.csv at their owned paths. The schema generator and catalog/evidence writers retain their current contracts. No root document is converted into a feature specification merely to fit a folder.

Preserve moved basenames. Convert local Markdown links using each document's old and new location, including links to assets and generated references. Update literal physical paths in documentation checks, release tooling and tests. VitePress rewrites map categorized Markdown sources to their original root route, so existing public guide links and anchors remain available. Site navigation continues using public routes; edit links use the actual source path.

Keep the independent native/Pascal work in PR #2400 mergeable by limiting changes to required links in its moved guide. The EVM guide follows the same rule.

Verification

Run documentation-fact checks and the affected README, release and filesystem boundary tests. Build the complete VitePress site with dead-link checks enabled, then compare emitted HTML routes with the pre-migration guide inventory. Inspect the diff for unintended text rewrites and retained generated ownership. Run the repository static checks before requesting review.