Files
rea/docs/specs/documentation/organization/spec.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

39 lines
1.8 KiB
Markdown

# Documentation organization
## Problem and outcome
The authored documentation root mixes user workflows, provider setup, contracts,
development instructions and release migrations. Several existing guides are
missing from site navigation. A contributor needs one documented destination for
each kind of document without breaking reader links or automated path consumers.
Tracking issue: <https://github.com/morluto/rea/issues/2401>.
## Requirements
1. Categorize every existing authored guide while preserving its basename,
substantive content and heading anchors.
2. Preserve existing public guide URLs; update physical repository links and
tests, release instructions and documentation-fact readers together.
3. Expose every existing guide through a documentation directory and categorized
site navigation.
4. Specify one feature/domain per `docs/specs/<domain>/<feature-slug>/`, with `spec.md`,
exactly one `plan.md` and `tasks.md`. Broad specification roadmaps only list
child specifications, order and dependencies. Architectural decisions use
individual Michael Nygard ADRs under `docs/adr/<domain>/<decision-slug>.md`.
5. Preserve machine-owned catalog, evidence, schema and release-manifest paths;
explain their owners and regeneration commands separately from authored guides.
## Acceptance
- Every pre-existing authored Markdown guide has a categorized destination.
- All local Markdown file references resolve after migration.
- A production VitePress build emits all pre-existing guide routes.
- Documentation facts and relevant physical-path consumer tests pass.
- The organization has one implementation plan and incremental task list.
## Out of scope
Provider integration, runtime behavior, analysis contracts, new language support,
rewriting guide claims, deployment and generated-output ownership changes.