morluto/rea

Fork 0

mirror of https://github.com/morluto/rea.git synced 2026-11-05 06:45:22 +00:00

[PR #4108] docs: route every guide through the sidebar and guide index #6063

New issue

Open

opened 2026-10-31 01:11:34 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-31 01:11:34 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/4108
Author: @MadKangYu
Created: 10/15/2026
Status: 🔄 Open

Base: main ← Head: docs/sidebar-guide-index

📝 Commits (1)

aa358b7 docs: route every guide through the sidebar and guide index

📊 Changes

5 files changed (+100 additions, -24 deletions)

View changed files

📝 docs/.vitepress/config.ts (+81 -10)
📝 docs/ghidra-nativeaot.md (+1 -1)
📝 docs/index.md (+14 -12)
📝 docs/mcp-contracts.md (+1 -1)
📝 docs/web-network-captures.md (+3 -0)

📄 Description

Summary

Refs #2401. Every authored guide in docs/ is now reachable from both the
documentation site sidebar and the guide table in docs/index.md. Two links
that broke on the built site are also fixed. No guide file moves, so every
existing page URL and anchor is unchanged.

This PR is narrower than #2401 and #2791. It changes navigation only. It can
land before or without the directory reorganization, and the entries can be
moved into #2791's layout if that PR lands first.

Problem and expected behavior

Measured on main at b3b5c8b (64 authored guides, excluding docs/index.md,
docs/readme/ and docs/specs/):

28 of 64 guides were missing from the VitePress sidebar. The built
installation.html sidebar contained 36 links. Examples: binary-diagnostics,
recorded-crashes, reverse-engineering-tools, javascript-application-graph,
web-runtime, flutter-analysis, jeb-analysis, ghidra-mips, ghidra-psp,
ghidra-riscv, pcap-analysis, frida-instrumentation, migration-6.2.
11 guides were missing from the guide table in docs/index.md:
reverse-engineering-tools, ghidra-riscv, ghidra-ppc, flutter-analysis,
sqlite-databases, packet-captures, pcap-analysis, signal-recordings,
client-configuration, reconstruction-coverage, http3-capture-lab.
docs/http3-capture-lab.md had no inbound link from any Markdown file.
In the built site, mcp-contracts.html linked to /rea/rea/product-catalog.json
because the Markdown link already included the /rea/ base. ghidra-nativeaot.html
linked to ../licenses/nativeaot-parser-MIT.txt, which is outside the site.
CONTRIBUTING.md asks for full GitHub URLs for repository files outside docs/.

Expected: a reader can reach every guide from the sidebar and from the index
table, and no internal link on the built site is broken.

Change and scope

docs/.vitepress/config.ts: the single "Investigation guides" sidebar group
is split into reader-task groups that match the index table. These groups are
Native binaries; JavaScript and Electron; Websites and browsers; Packages,
mobile and firmware; and Recordings and runtime. "Provider guides" now lists all
Ghidra profiles plus IDA, Kuna and JEB. "Reference and development" adds
obligation ledgers, reconstruction coverage, the HTTP/3 capture lab and the
6.2 migration. All 64 guides appear exactly once.
docs/index.md: adds the 11 missing guides. Adds one row, "Inspect recorded
databases, packets, or signals", for SQLite, packet captures, packet summaries
and signal recordings. Mentions the HTTP/3 lab with the development guides.
docs/web-network-captures.md: links the optional HTTP/3 capture lab after
the native mitmproxy section.
docs/mcp-contracts.md: changes the link target from /rea/product-catalog.json
to /product-catalog.json, so VitePress adds the base once. The link text is
unchanged.
docs/ghidra-nativeaot.md: the license link now uses the full GitHub URL.

Not included: moving or renaming files, editing guide content, editing README
editions, or editing generated outputs.

Contribution scope: documentation-only fix within existing boundaries. A
maintainer scope decision is not applicable.

Contract and boundary impact

Semantic owner and earliest changed stage: documentation site navigation (docs/.vitepress/config.ts, docs/index.md)
Contribution scope fit and linked maintainer decision: documentation-only; not applicable
CLI and MCP/tool-catalog contract: none
Provider, bridge, target-format, or platform compatibility: none
Evidence, artifact, provenance, or reconstruction contract: none
Target selection, authority, upstream behavior, and cleanup details (if applicable): not applicable
Generated metadata (docs/public/product-catalog.json), package, or installation impact: none. Only the link to the generated catalog changes. The file and its generation are unchanged.

Expected effects:

Read existing files or captured data.
Launch or attach to a process.
Inject instrumentation or run scripts/code.
Change process memory, registers, files, or configuration.
Contact network services.
Recover protected code or work around protections.
Documentation or usability only; no target interaction.
Not sure yet; investigation or maintainer guidance needed.

Evidence and regression coverage

Tests added or updated: none. The checks below are source and rendered-document checks.
Base reproduction or other evidence: both the base and the head were built
with VitePress 1.6.4, and every internal href and #anchor in the output
HTML was crawled.

Check (built site, `main` `b3b5c8b` → this PR)	Before	After
Sidebar links rendered in `installation.html`	36	64
Authored guides missing from sidebar	28	0
Authored guides missing from `docs/index.md` table	11	0
Guides with no inbound Markdown link	1	0
Broken internal `href`s in built HTML	2	0*
Missing `#anchor` targets in built HTML	0	0
Emitted HTML pages (same set)	74	74

* /rea/product-catalog.json resolves when docs/public/product-catalog.json
exists. I checked this with a placeholder file, and the built page linked to
/rea/product-catalog.json, which the build served. The real file is ignored and
is produced by npm run docs:generate, which predocs:build runs.

User-visible CLI/MCP output: not applicable
Remaining proof gaps: I did not run the full npm run docs:check
(check-doc-facts, generate-* checks and the README consistency test),
because it needs a full npm ci of the repository. Those checks read README
editions, docs/installation.md, AGENTS.md and the PR template, and this PR
does not change them. CI on this PR is the authoritative result.

Validation performed

vitepress build docs (vitepress 1.6.4, Node 26.7.0) on base and head: exit 0 for both.
oxfmt --check (0.72.0, repository .oxfmtrc.json) on the five changed files: "All matched files use the correct format."
tsc --noEmit --strict --skipLibCheck --module esnext --moduleResolution bundler docs/.vitepress/config.ts (TypeScript 7.0.2): exit 0
git diff --check: no whitespace errors
Built-HTML crawl of internal hrefs and #anchors for base and head: results in the table above.

Compatibility, safety, and release

Breaking changes or migration steps: none. Page URLs are unchanged.
Real Hopper/Ghidra, browser, or OS coverage: not applicable
Package or release metadata impact: none
Security, privacy, process, or containment review: not applicable

Author readiness

Human owner:

I reviewed the final diff and relevant existing code, understand the change and its edge cases, and take responsibility for the complete PR, including AI-assisted work.
I checked the evidence above, confirmed it supports the current change, and recorded meaningful validation gaps.
I declare this PR ready for initial maintainer review.

Before merge

This PR addresses a concrete problem or an agreed enhancement.
Material scope and authority questions are resolved, and any required maintainer scope decision covers the final diff.
The PR has one focused outcome and the title follows type(scope): outcome.
Related issue is linked, or the reason for not linking one is stated above.
Tests cover changed observable behavior and meaningful failure paths.
Owning docs, contracts, and generated metadata are updated where needed.
User-visible CLI/MCP changes include representative output.
I checked the final diff for secrets, unrelated cleanup, and unsupported claims.

_{🔄 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/4108 **Author:** [@MadKangYu](https://github.com/MadKangYu) **Created:** 10/15/2026 **Status:** 🔄 Open **Base:** `main` ← **Head:** `docs/sidebar-guide-index` --- ### 📝 Commits (1) - [`aa358b7`](https://github.com/morluto/rea/commit/aa358b775defd5e91a24cfd17750d65378345aec) docs: route every guide through the sidebar and guide index ### 📊 Changes **5 files changed** (+100 additions, -24 deletions) <details> <summary>View changed files</summary> 📝 `docs/.vitepress/config.ts` (+81 -10) 📝 `docs/ghidra-nativeaot.md` (+1 -1) 📝 `docs/index.md` (+14 -12) 📝 `docs/mcp-contracts.md` (+1 -1) 📝 `docs/web-network-captures.md` (+3 -0) </details> ### 📄 Description ## Summary Refs #2401. Every authored guide in `docs/` is now reachable from both the documentation site sidebar and the guide table in `docs/index.md`. Two links that broke on the built site are also fixed. No guide file moves, so every existing page URL and anchor is unchanged. This PR is narrower than #2401 and #2791. It changes navigation only. It can land before or without the directory reorganization, and the entries can be moved into #2791's layout if that PR lands first. ## Problem and expected behavior Measured on `main` at b3b5c8b (64 authored guides, excluding `docs/index.md`, `docs/readme/` and `docs/specs/`): - 28 of 64 guides were missing from the VitePress sidebar. The built `installation.html` sidebar contained 36 links. Examples: `binary-diagnostics`, `recorded-crashes`, `reverse-engineering-tools`, `javascript-application-graph`, `web-runtime`, `flutter-analysis`, `jeb-analysis`, `ghidra-mips`, `ghidra-psp`, `ghidra-riscv`, `pcap-analysis`, `frida-instrumentation`, `migration-6.2`. - 11 guides were missing from the guide table in `docs/index.md`: `reverse-engineering-tools`, `ghidra-riscv`, `ghidra-ppc`, `flutter-analysis`, `sqlite-databases`, `packet-captures`, `pcap-analysis`, `signal-recordings`, `client-configuration`, `reconstruction-coverage`, `http3-capture-lab`. - `docs/http3-capture-lab.md` had no inbound link from any Markdown file. - In the built site, `mcp-contracts.html` linked to `/rea/rea/product-catalog.json` because the Markdown link already included the `/rea/` base. `ghidra-nativeaot.html` linked to `../licenses/nativeaot-parser-MIT.txt`, which is outside the site. CONTRIBUTING.md asks for full GitHub URLs for repository files outside `docs/`. Expected: a reader can reach every guide from the sidebar and from the index table, and no internal link on the built site is broken. ## Change and scope - `docs/.vitepress/config.ts`: the single "Investigation guides" sidebar group is split into reader-task groups that match the index table. These groups are Native binaries; JavaScript and Electron; Websites and browsers; Packages, mobile and firmware; and Recordings and runtime. "Provider guides" now lists all Ghidra profiles plus IDA, Kuna and JEB. "Reference and development" adds obligation ledgers, reconstruction coverage, the HTTP/3 capture lab and the 6.2 migration. All 64 guides appear exactly once. - `docs/index.md`: adds the 11 missing guides. Adds one row, "Inspect recorded databases, packets, or signals", for SQLite, packet captures, packet summaries and signal recordings. Mentions the HTTP/3 lab with the development guides. - `docs/web-network-captures.md`: links the optional HTTP/3 capture lab after the native mitmproxy section. - `docs/mcp-contracts.md`: changes the link target from `/rea/product-catalog.json` to `/product-catalog.json`, so VitePress adds the base once. The link text is unchanged. - `docs/ghidra-nativeaot.md`: the license link now uses the full GitHub URL. Not included: moving or renaming files, editing guide content, editing README editions, or editing generated outputs. Contribution scope: documentation-only fix within existing boundaries. A maintainer scope decision is not applicable. ## Contract and boundary impact - Semantic owner and earliest changed stage: documentation site navigation (`docs/.vitepress/config.ts`, `docs/index.md`) - Contribution scope fit and linked maintainer decision: documentation-only; not applicable - CLI and MCP/tool-catalog contract: none - Provider, bridge, target-format, or platform compatibility: none - Evidence, artifact, provenance, or reconstruction contract: none - Target selection, authority, upstream behavior, and cleanup details (if applicable): not applicable - Generated metadata (`docs/public/product-catalog.json`), package, or installation impact: none. Only the link to the generated catalog changes. The file and its generation are unchanged. Expected effects: - [ ] Read existing files or captured data. - [ ] Launch or attach to a process. - [ ] Inject instrumentation or run scripts/code. - [ ] Change process memory, registers, files, or configuration. - [ ] Contact network services. - [ ] Recover protected code or work around protections. - [x] Documentation or usability only; no target interaction. - [ ] Not sure yet; investigation or maintainer guidance needed. ## Evidence and regression coverage - Tests added or updated: none. The checks below are source and rendered-document checks. - Base reproduction or other evidence: both the base and the head were built with VitePress 1.6.4, and every internal `href` and `#anchor` in the output HTML was crawled. | Check (built site, `main` b3b5c8b → this PR) | Before | After | | --- | --- | --- | | Sidebar links rendered in `installation.html` | 36 | 64 | | Authored guides missing from sidebar | 28 | 0 | | Authored guides missing from `docs/index.md` table | 11 | 0 | | Guides with no inbound Markdown link | 1 | 0 | | Broken internal `href`s in built HTML | 2 | 0* | | Missing `#anchor` targets in built HTML | 0 | 0 | | Emitted HTML pages (same set) | 74 | 74 | \* `/rea/product-catalog.json` resolves when `docs/public/product-catalog.json` exists. I checked this with a placeholder file, and the built page linked to `/rea/product-catalog.json`, which the build served. The real file is ignored and is produced by `npm run docs:generate`, which `predocs:build` runs. - User-visible CLI/MCP output: not applicable - Remaining proof gaps: I did not run the full `npm run docs:check` (`check-doc-facts`, `generate-*` checks and the README consistency test), because it needs a full `npm ci` of the repository. Those checks read README editions, `docs/installation.md`, `AGENTS.md` and the PR template, and this PR does not change them. CI on this PR is the authoritative result. ## Validation performed - `vitepress build docs` (vitepress 1.6.4, Node 26.7.0) on base and head: exit 0 for both. - `oxfmt --check` (0.72.0, repository `.oxfmtrc.json`) on the five changed files: "All matched files use the correct format." - `tsc --noEmit --strict --skipLibCheck --module esnext --moduleResolution bundler docs/.vitepress/config.ts` (TypeScript 7.0.2): exit 0 - `git diff --check`: no whitespace errors - Built-HTML crawl of internal `href`s and `#anchor`s for base and head: results in the table above. ## Compatibility, safety, and release - Breaking changes or migration steps: none. Page URLs are unchanged. - Real Hopper/Ghidra, browser, or OS coverage: not applicable - Package or release metadata impact: none - Security, privacy, process, or containment review: not applicable ## Author readiness  Human owner:  - [ ] I reviewed the final diff and relevant existing code, understand the change and its edge cases, and take responsibility for the complete PR, including AI-assisted work. - [ ] I checked the evidence above, confirmed it supports the current change, and recorded meaningful validation gaps. - [ ] I declare this PR ready for initial maintainer review. ## Before merge - [ ] This PR addresses a concrete problem or an agreed enhancement. - [ ] Material scope and authority questions are resolved, and any required maintainer scope decision covers the final diff. - [ ] The PR has one focused outcome and the title follows `type(scope): outcome`. - [ ] Related issue is linked, or the reason for not linking one is stated above. - [ ] Tests cover changed observable behavior and meaningful failure paths. - [ ] Owning docs, contracts, and generated metadata are updated where needed. - [ ] User-visible CLI/MCP changes include representative output. - [ ] I checked the final diff for secrets, unrelated cleanup, and unsupported claims. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi added the

pull-request

label

2026-10-31 01:11:34 +00:00

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

morluto/rea#6063

No description provided.

Rows
Columns