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>
This commit is contained in:
@@ -0,0 +1,33 @@
|
||||
# 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.
|
||||
|
||||
## Link and route contracts
|
||||
|
||||
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.
|
||||
@@ -0,0 +1,38 @@
|
||||
# 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.
|
||||
@@ -0,0 +1,8 @@
|
||||
# Tasks
|
||||
|
||||
- [x] Inspect documentation owners, navigation and path consumers; publish #2401.
|
||||
- [x] Define this feature specification and its single implementation plan.
|
||||
- [x] Move existing authored documents into their categorized destinations.
|
||||
- [x] Update local links and physical-path consumers; preserve public routes.
|
||||
- [x] Add the documentation directory and canonical authoring conventions.
|
||||
- [x] Run documentation checks, path-consumer tests, site build and static checks.
|
||||
Reference in New Issue
Block a user