[GH-ISSUE #2401] docs: organize existing documentation and preserve public guide URLs (URGENT) #807

New issue

Open

opened 2026-10-15 18:28:38 +00:00 by bsakaguchi · 1 comment

bsakaguchi commented

2026-10-15 18:28:38 +00:00

Owner

Originally created by @matbrgz on GitHub (Oct 12, 2026).
Original GitHub issue: https://github.com/morluto/rea/issues/2401

Problem

The docs/ root mixes installation, investigation workflows, provider configuration, contracts, development guidance and release migrations. The site sidebar exposes only some of the existing guides, while documentation checks and release tooling depend on physical paths. Organizing only the Markdown files would leave repository links and automated checks behind.

Proposed result

Group the existing authored documents into getting-started, domain guides, providers, reference, development, architecture and migration directories, preserving substantive content.
Keep every current public guide URL through VitePress source rewrites; update repository-relative links and path consumers together.
Provide a complete documentation directory and navigation, including previously omitted guides.
Document the canonical specification model: one feature/domain under docs/specs/<domain>/<feature-slug>/, with spec.md, one plan.md, and tasks.md; isolated architectural decisions under docs/adr/<domain>/<decision-slug>.md; broad specification roadmaps only index their child specifications.
Keep generated catalog/evidence/schema and release manifests at their existing owned paths, with explicit source/regeneration guidance.

Acceptance

All existing authored guides remain available and categorized.
Repository links resolve after moves; existing public URLs and anchors remain available.
Documentation fact checks, relevant path-consumer tests and production site build pass.
No provider, target execution, analysis result or runtime contract changes.

This is a documentation organization change within existing contribution boundaries. Its feature specification precedes the migration under docs/specs/documentation/organization/.

Implementation and validation

Implemented in PR #2403: all 55 existing authored guides are categorized, all 55 existing public routes are emitted by the production build, and 340 local Markdown links resolve. Documentation checks, the complete static checks and 40 affected path-consumer tests passed. Spec/plan/tasks live under docs/specs/documentation/organization/; numeric prefixes are replaced with domain/feature slugs to avoid concurrent numbering collisions.

Generated catalog/evidence/schema and durable release manifest paths stay with their current owners. Historical release messages remain unchanged. PR #2400 independently edits the moved native guide; its runtime implementation is not part of this change.

Originally created by @matbrgz on GitHub (Oct 12, 2026). Original GitHub issue: https://github.com/morluto/rea/issues/2401 [![Type: Community / Governance](https://img.shields.io/badge/type-community_%2F_governance-lightgrey.svg?style=flat-square)](https://github.com/morluto/rea) [![Status: Proposed](https://img.shields.io/badge/status-proposed-blue.svg?style=flat-square)](https://github.com/morluto/rea) [![Ecosystem: REA](https://img.shields.io/badge/ecosystem-morluto%2Frea-8A2BE2.svg?style=flat-square)](https://github.com/morluto/rea) ## Problem The `docs/` root mixes installation, investigation workflows, provider configuration, contracts, development guidance and release migrations. The site sidebar exposes only some of the existing guides, while documentation checks and release tooling depend on physical paths. Organizing only the Markdown files would leave repository links and automated checks behind. ## Proposed result - Group the existing authored documents into getting-started, domain guides, providers, reference, development, architecture and migration directories, preserving substantive content. - Keep every current public guide URL through VitePress source rewrites; update repository-relative links and path consumers together. - Provide a complete documentation directory and navigation, including previously omitted guides. - Document the canonical specification model: one feature/domain under `docs/specs/<domain>/<feature-slug>/`, with `spec.md`, one `plan.md`, and `tasks.md`; isolated architectural decisions under `docs/adr/<domain>/<decision-slug>.md`; broad specification roadmaps only index their child specifications. - Keep generated catalog/evidence/schema and release manifests at their existing owned paths, with explicit source/regeneration guidance. ## Acceptance - [x] All existing authored guides remain available and categorized. - [x] Repository links resolve after moves; existing public URLs and anchors remain available. - [x] Documentation fact checks, relevant path-consumer tests and production site build pass. - [x] No provider, target execution, analysis result or runtime contract changes. This is a documentation organization change within existing contribution boundaries. Its feature specification precedes the migration under `docs/specs/documentation/organization/`. ## Implementation and validation Implemented in PR #2403: all 55 existing authored guides are categorized, all 55 existing public routes are emitted by the production build, and 340 local Markdown links resolve. Documentation checks, the complete static checks and 40 affected path-consumer tests passed. Spec/plan/tasks live under `docs/specs/documentation/organization/`; numeric prefixes are replaced with domain/feature slugs to avoid concurrent numbering collisions. Generated catalog/evidence/schema and durable release manifest paths stay with their current owners. Historical release messages remain unchanged. PR #2400 independently edits the moved native guide; its runtime implementation is not part of this change.

bsakaguchi added the

area: build

documentation

labels

2026-10-15 18:28:38 +00:00

bsakaguchi commented

2026-10-15 18:28:39 +00:00

Author

Owner

@matbrgz commented on GitHub (Oct 12, 2026):

@N0zoM1z0 @morluto sorry to bother you. When you have a chance, could you please review #2403?

This is an important docs reorganization that preserves all existing public URLs, links, and tooling paths, so I’d really appreciate a second pair of eyes before merging. Thanks!

@matbrgz commented on GitHub (Oct 12, 2026): @N0zoM1z0 @morluto sorry to bother you. When you have a chance, could you please review #2403? This is an important docs reorganization that preserves all existing public URLs, links, and tooling paths, so I’d really appreciate a second pair of eyes before merging. Thanks!

bsakaguchi referenced this issue

2026-10-16 21:16:19 +00:00

[PR #807] [CLOSED] fix(native): retain nm-proven literal export names #2254

bsakaguchi referenced this issue

2026-10-16 21:16:23 +00:00

[PR #812] [CLOSED] fix(native): project Mach-O evidence into container file offsets #2259

bsakaguchi referenced this issue

2026-10-16 21:16:27 +00:00

[PR #815] [MERGED] fix: integrate 24 reviewed browser/native/semantics corrections #2262