20260910-0135-product-tree-and-sidebar Reorganise product docs per product line and drop the sidebar

• status: completed
• createdAt: 2026-09-10 01:35
• approvedAt: 2026-09-10 01:40
• relatedTask: 20260910-0135-product-tree-and-sidebar

Context

bizplan/product/ is flat: 28 English files plus 28 Chinese mirrors, named P01-core.md, P01-core-design.md, X01-ybo-can-protocol.md and so on. Adding a second or third document for one product makes the folder harder to scan, which is what prompted the request.

Link survey (decisive for cost):

• Product documents reference each other as bare filenames in backticks (`P08-mate.md` appears 157 times, `X02-config-schema.md` 135 times; roughly 1450 in total), not as Markdown links. Bare mentions carry no path, so they survive a directory move as long as filenames do not change.
• Real Markdown links to product files are concentrated in bizplan/product/index.md and index.md (14 table rows each), plus 3 references from two research documents.
• Product documents contain no ../ outbound Markdown links, so the extra directory level breaks nothing.

The sidebar is built by .vitepress/sidebar.mts (130 lines) and is long because three groups render expanded: bizplan (7), bizplan/product (28) and bizplan/research (16) — 51 entries before any collapsed group. The repository already carries table-shaped index pages (product/index.md, research/vendors/index.md, air-key-vendors/index.md, docs/task/index.md, docs/plan/index.md); bizplan/ and bizplan/research/ are the two sections that lack one.

Proposal

Phase 1 — one directory per product line

Move files with git mv, keeping every filename unchanged:

bizplan/product/
├── index.md               (+ .md)   rewritten as per-product sections
├── shared/    X01-ybo-can-protocol, X02-config-schema
├── core/      P01-core, P01-core-design
├── sense/     P02-sense, P02-sense-design
├── hub/       P03-hub, P03-hub-design
├── ac/        P04-ac-interface, P04-ac-commissioning, P04-ac-board-16
├── air-gateway/  P05-air-gateway, P05-air-gateway-design
├── air-switch/   P05-air-switch, P05-air-switch-design
├── key/       P06-key, P06-key-design
├── studio/    P07-studio, P07-studio-architecture
├── mate/      P08-mate, P08-mate-data-model
├── view/      P10-view, P10-view-design
├── eye/       P11-eye, P11-eye-integration
└── tag/       P12-tag, P12-tag-design

Filenames keep their P/X identifiers so the ~1450 bare cross-references stay accurate. 56 files move.

Then repoint the real links: the two index tables and the 3 research references.

Phase 2 — remove the sidebar (option A)

1. Drop sidebar from both locales in .vitepress/config.mts and delete .vitepress/sidebar.mts.
2. Rewrite bizplan/product/index.md (+ mirror) into one section per product line, each listing that product's documents, so the index page replaces what the sidebar used to show.
3. Add bizplan/index.md and bizplan/research/index.md (+ mirrors) listing their sections in the same table style.
4. Extend the top navigation so every section is reachable: Business Plan, Products, Research, Vendors, Tracking.

Phase 3 — verify

bun run docs:build with VitePress dead-link checking (already enabled) catches every missed link. Then git diff --check, commit, dispatch the deploy workflow and smoke-test the published site.

Risks

• Removing the sidebar also removes the previous/next footer links, which VitePress derives from sidebar order. Accepted as part of option A.
• A missed Markdown link fails the build rather than shipping silently — the failure mode is safe.
• Bare filename mentions become slightly less precise (a filename no longer implies a sibling file); renaming them to paths would mean ~1450 edits and is deliberately not done.
• The language consolidation ("everything Chinese except the plan") is not part of this plan; it is sequenced after the tree is stable so the files are touched once more, not twice in parallel.

Scope

• Moved: 56 files under bizplan/product/.
• Modified: .vitepress/config.mts, bizplan/product/index.md + mirror, 2 research documents.
• Added: bizplan/index.md, bizplan/research/index.md and their Chinese mirrors.
• Deleted: .vitepress/sidebar.mts.

Alternatives

• Rename files to spec.md / design.md inside each product directory: cleaner names, but forces ~1450 cross-reference edits across the corpus. Rejected on cost and risk.
• Prefix directories with the product ID (P01-core/): keeps a fixed order, but the order now comes from the index page, so the ID adds nothing to the path.
• Options B (per-section sidebar) and C (all groups collapsed): rejected by the user in favour of A.

Execution note

The language consolidation ran first, so only 28 files moved instead of 56: the Chinese mirrors had already replaced their English originals by the time the product tree was created. product/index.md was rewritten as one section per product line, and index.zh.md no longer exists. .vitepress/links.mts was deleted alongside sidebar.mts because the same pass removed the locale machinery it served. Two relative links to .py scripts became root-absolute: VitePress treats a .py target as a page and checks it, while the ignoreDeadLinks predicate only resolves root-absolute paths (its callback receives no source-file argument in VitePress 1.6.4).