[PR #2403] [CLOSED] docs: organize canonical documentation layout (URGENT) #5203

New issue

Closed

opened 2026-10-31 01:04:47 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-31 01:04:47 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/2403
Author: @matbrgz
Created: 10/12/2026
Status: ❌ Closed

Base: main ← Head: docs/urgente-canonical-layout

📝 Commits (4)

ea504fa docs: organize canonical documentation layout (URGENTE)
3bb92db merge: integrate upstream documentation and preserve published routes
b8f8d39 merge: reconcile current guides and require published-page regressions
51aa6ee merge: preserve current MCP paging contracts in organized documentation

📊 Changes

127 files changed (+1838 additions, -925 deletions)

View changed files

📝 .agents/skills/rea-changelog-update/SKILL.md (+1 -1)
📝 .agents/skills/rea-tool-design/SKILL.md (+2 -2)
📝 .agents/skills/reverse-engineer-anything/SKILL.md (+11 -11)
📝 .agents/skills/reverse-engineer-anything/references/javascript-applications.md (+1 -1)
📝 .agents/skills/reverse-engineer-anything/references/native-and-artifacts.md (+6 -6)
📝 .github/ISSUE_TEMPLATE/documentation.yml (+1 -1)
📝 .github/pull_request_template.md (+1 -1)
📝 .github/workflows/ci.yml (+2 -0)
📝 .github/workflows/pages.yml (+1 -1)
📝 AGENTS.md (+9 -3)
📝 CHANGELOG.md (+2 -2)
📝 CONTRIBUTING.md (+11 -7)
📝 README.md (+46 -46)
📝 README_ar.md (+35 -35)
📝 README_de.md (+35 -35)
📝 README_es.md (+35 -35)
📝 README_fa.md (+35 -35)
📝 README_fr.md (+36 -36)
📝 README_id.md (+39 -39)
📝 README_it.md (+36 -36)

...and 80 more files

📄 Description

The documentation root mixes workflow guides, provider setup, contracts and contributor instructions, and the sidebar omits existing material. This change organizes all 56 authored guides by domain and ownership, adds a complete documentation directory, and preserves their public guide URLs through VitePress rewrites.

Specs use docs/specs/<domain>/<feature-slug>/{spec.md,plan.md,tasks.md} and isolated decisions use docs/adr/<domain>/<decision-slug>.md, without a global numeric counter. The authoring guide defines the single-feature/single-plan contract and generated ownership. The implementation follows docs/specs/documentation/organization/.

Repository links, translated READMEs, skills, diagnostics, documentation readers, release configuration and affected tests follow the moved files. Generated catalog/evidence/schema paths and historical release records retain their owners. Historical release validation accepts the previous installation-guide path.

An independent built-HTML verifier now checks 56 published routes, 56 physical source-edit links and 507 distinct internal file/anchor targets. It caught a doubled catalog base path and a missing historical managed/native anchor; both are corrected. Documentation CI and manual builds run the verifier. An actual CI-planner regression ensures changes to that verifier select the documentation lane.

Validation: npm run docs:check, npm run verify:docs:routes, npm run check, 167 relevant tests across ten files, and a subsequent 14-test MCP pagination/replay/framing selection passed. The actual Worker-URL CLI cases passed outside the restricted sandbox, which blocks process-table inspection with spawn EPERM; timeouts and assertions were retained. Earlier 19 process/PTY checks also passed outside that restriction. External network links and provider-specific tools are outside this documentation verification scope.

Integrated current upstream c462a4ebd, preserving the new signal guide, managed summaries and list_unknowns pagination section in docs/reference/mcp-contracts.md. GitHub reports the updated head as mergeable. Commits use Matheus Breguêz's identity and validated GPG signatures.

Related work: #2400 edits the native guide moved to docs/guides/native/native-investigation.md; the EVM guide moves to docs/guides/evm/evm-bytecode.md. Those feature implementations are separate.

Closes #2401.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/morluto/rea/pull/2403 **Author:** [@matbrgz](https://github.com/matbrgz) **Created:** 10/12/2026 **Status:** ❌ Closed **Base:** `main` ← **Head:** `docs/urgente-canonical-layout` --- ### 📝 Commits (4) - [`ea504fa`](https://github.com/morluto/rea/commit/ea504fac973ca5ee36791d6819e82c96b59263f0) docs: organize canonical documentation layout (URGENTE) - [`3bb92db`](https://github.com/morluto/rea/commit/3bb92dbee800ed8e689d5a6bf7b0a1e4ac2030ac) merge: integrate upstream documentation and preserve published routes - [`b8f8d39`](https://github.com/morluto/rea/commit/b8f8d39cb585345fab3249a440e47cd193a4d7f1) merge: reconcile current guides and require published-page regressions - [`51aa6ee`](https://github.com/morluto/rea/commit/51aa6eeca3380c11b306e67c1dbcf81c0d016d13) merge: preserve current MCP paging contracts in organized documentation ### 📊 Changes **127 files changed** (+1838 additions, -925 deletions) <details> <summary>View changed files</summary> 📝 `.agents/skills/rea-changelog-update/SKILL.md` (+1 -1) 📝 `.agents/skills/rea-tool-design/SKILL.md` (+2 -2) 📝 `.agents/skills/reverse-engineer-anything/SKILL.md` (+11 -11) 📝 `.agents/skills/reverse-engineer-anything/references/javascript-applications.md` (+1 -1) 📝 `.agents/skills/reverse-engineer-anything/references/native-and-artifacts.md` (+6 -6) 📝 `.github/ISSUE_TEMPLATE/documentation.yml` (+1 -1) 📝 `.github/pull_request_template.md` (+1 -1) 📝 `.github/workflows/ci.yml` (+2 -0) 📝 `.github/workflows/pages.yml` (+1 -1) 📝 `AGENTS.md` (+9 -3) 📝 `CHANGELOG.md` (+2 -2) 📝 `CONTRIBUTING.md` (+11 -7) 📝 `README.md` (+46 -46) 📝 `README_ar.md` (+35 -35) 📝 `README_de.md` (+35 -35) 📝 `README_es.md` (+35 -35) 📝 `README_fa.md` (+35 -35) 📝 `README_fr.md` (+36 -36) 📝 `README_id.md` (+39 -39) 📝 `README_it.md` (+36 -36) _...and 80 more files_ </details> ### 📄 Description The documentation root mixes workflow guides, provider setup, contracts and contributor instructions, and the sidebar omits existing material. This change organizes all 56 authored guides by domain and ownership, adds a complete documentation directory, and preserves their public guide URLs through VitePress rewrites. Specs use `docs/specs/<domain>/<feature-slug>/{spec.md,plan.md,tasks.md}` and isolated decisions use `docs/adr/<domain>/<decision-slug>.md`, without a global numeric counter. The authoring guide defines the single-feature/single-plan contract and generated ownership. The implementation follows `docs/specs/documentation/organization/`. Repository links, translated READMEs, skills, diagnostics, documentation readers, release configuration and affected tests follow the moved files. Generated catalog/evidence/schema paths and historical release records retain their owners. Historical release validation accepts the previous installation-guide path. An independent built-HTML verifier now checks 56 published routes, 56 physical source-edit links and 507 distinct internal file/anchor targets. It caught a doubled catalog base path and a missing historical managed/native anchor; both are corrected. Documentation CI and manual builds run the verifier. An actual CI-planner regression ensures changes to that verifier select the documentation lane. Validation: `npm run docs:check`, `npm run verify:docs:routes`, `npm run check`, 167 relevant tests across ten files, and a subsequent 14-test MCP pagination/replay/framing selection passed. The actual Worker-URL CLI cases passed outside the restricted sandbox, which blocks process-table inspection with `spawn EPERM`; timeouts and assertions were retained. Earlier 19 process/PTY checks also passed outside that restriction. External network links and provider-specific tools are outside this documentation verification scope. Integrated current upstream `c462a4ebd`, preserving the new signal guide, managed summaries and `list_unknowns` pagination section in `docs/reference/mcp-contracts.md`. GitHub reports the updated head as mergeable. Commits use Matheus Breguêz's identity and validated GPG signatures. Related work: #2400 edits the native guide moved to `docs/guides/native/native-investigation.md`; the EVM guide moves to `docs/guides/evm/evm-bytecode.md`. Those feature implementations are separate. Closes #2401. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-31 01:04:47 +00:00