20260910-0459-documentation-organization Improve documentation navigation and consistency

• status: completed
• createdAt: 2026-09-10 04:59
• approvedAt: 2026-09-10 05:52
• relatedTask: 20260910-0455-documentation-organization

Context

The repository contains 225 tracked paths, including 173 Markdown paths, 19 PDFs, 21 CSVs, and two Python analysis scripts. Product documents already use one directory per product line. The site uses Chinese entry pages, directory indexes, breadcrumbs, and local search; the English business plan and English project records are deliberate exceptions.

Investigation findings against the existing source and rendered site:

• 428 unresolved explicit relative paths in inline code across 28 business/product/research files. Of these, 413 resolve after accounting for the added product-directory level; 15 refer to removed PLAN-025, PLAN-029, and PLAN-030 files. Their decision history remains in docs/changelog.md.
• 27 product documents retain a self-referencing English-original header after the Chinese-first migration.
• 52 rendered links have missing fragment targets across five files: the PPT guide (33), English business plan (9), Chinese business plan (8), global PDM supplier report (1), and S32K314/LVDS review (1). There are 35 distinct source-page/target combinations. VitePress heading IDs differ from the hand-written fragments.
• Two rendered PDF links in the yacht circuit source catalog point to files deliberately omitted from publication by the existing 25 MiB asset-copy limit. The Bertram 43 and Bertram 700 originals remain in the repository, and the catalog already contains their publisher links.
• The research index labels translated reports and catalogs as English. It says 27 PDM suppliers, but there are 26 supplier detail files plus the index.
• The product package index and Air/Key catalog duplicate document/product rows maintained in child indexes. The Air/Key overview has no direct links to its three category index pages.
• Current research, superseded architecture proposals, and supporting evidence have equal prominence in the research index. Existing report notices already distinguish those states, but the index does not carry them through.
• Repository architecture and AGENTS site facts describe removed locale rewrites, sidebars, and link helpers. The business index describes the internal PPT guide as an external-material guide.
• Three completed plan detail files still have pending markers in the plan index. Their task details and completion changelog entries agree that they are completed.
• No byte-identical Markdown documents were found in the scanned corpus. Similar research titles alone do not justify merging their evidence.

Baseline verification: installed the existing locked dependencies locally with bun install --frozen-lockfile; bun run docs:build completed in 10.27 seconds. It reported the existing large-chunk warning and skipped the two oversized PDFs. A local scan of 173 rendered HTML pages found the broken fragments and asset links above. Source inspection and git diff --check passed; no external source claims were revalidated.

Proposal

1. Organize the reading routes through the existing indexes

Keep current filenames and directory URLs. Use the existing structure as the navigation hierarchy:

Home
  Business and product planning -> business plan, product plan, models, evidence, open questions
  Product package -> product directory -> specification and design appendix
  Research -> current proposals, supporting research, historical alternatives, source evidence
  Supplier catalogs -> PDM suppliers or Air/Key category -> supplier detail
  Project tracking -> tasks, plans, changelog, repository architecture

Add a short reader-oriented starting route to the business and product indexes. Reduce the product package index to a compact product-directory catalog and shared guidance; keep individual document inventories in each product directory. Reduce the Air/Key parent catalog to category links and coverage notes; keep supplier tables and cross-category references in the existing category indexes. Correct the internal PPT guide description and obsolete language/count labels.

2. Make document references usable

Correct the 413 mechanically resolvable relative paths and render those document references as clickable Markdown links, preserving surrounding section labels and technical claims. Replace the 15 paths to removed plan files with their plan IDs linked to the appropriate surviving changelog entries. Remove the 27 obsolete English-original headers and link the specification/design companion headers to their existing destinations where unambiguous. Do not expand this into rewriting every bare filename mention.

Repair the 52 broken rendered fragment links using actual generated heading IDs and verify the destination section. For the two oversized PDFs, keep an explicit repository archive path as text and the existing publisher download link; explain the publication omission in the source catalog. Do not alter archived PDFs, CSVs, checksums, or the build size policy.

3. Distinguish current research from historical alternatives

Reorder and annotate the research index based on existing document notices. Separate the selected vehicle split-module direction, the marine 24-output/125 A capacity proposal, evidence/review documents, and superseded comparison studies. Link each historical alternative to its stated successor. Preserve the marine/vehicle distinction and the boundary between research proposals and controlled product specifications.

4. Reconcile repository guidance and tracking

Rewrite the short repository architecture description against the current file tree and site configuration. Correct AGENTS site facts and the English business-plan exception in the tracking entry page. Synchronize the three completed plan index markers with their already-completed details and recorded delivery evidence; preserve historical plan prose and the ownership/status of the ongoing yacht research task.

Scope

Files	Intended change
index.md, bizplan/index.md	Starting routes and accurate language/PPT-guide descriptions
bizplan/product/index.md	Compact product-directory catalog, reading order, and single-place document-list maintenance
The 27 product specification/appendix/shared documents with stale paths and headers	Reference paths, obsolete mirror headers, and companion links only
bizplan/research/index.md, bizplan/research/air-key-vendors/index.md	Research status, current/history reading order, supplier count, and category navigation
bizplan/research/air-key-vendor-landscape.md	Removed-plan reference only
bizplan/PPT-BUILD-GUIDE.md, bizplan/BUSINESS-PLAN.md, bizplan/BUSINESS-PLAN.en.md, bizplan/research/06-global-intelligent-pdm-suppliers.md, bizplan/research/s32k314-lvds-io-report-review.md	Broken fragment destinations only
bizplan/research/yacht-circuit-source-catalog.md	Accurate download availability for the two oversized PDFs
AGENTS.md, docs/architecture.md, docs/index.md	Current structure, publication behavior, navigation, and language facts
Current task/plan details, task/plan indexes, and docs/changelog.md	Proposal, approval, delivery, and status synchronization

Approximately 42 existing content/governance documents plus task/plan tracking; most edits are mechanical references. This proposal does not move directories, merge or delete research reports, revise technical values or business assumptions, change dependencies/site code/deployment configuration, publish the site, commit, or push. Existing Chinese website copy remains Chinese; the English business plan and repository tracking remain English.

Verification

1. Navigation: follow home/business/product/research/supplier entry routes; confirm every retained page is reachable and category overviews link to their child index pages.
2. References: check Markdown links and explicit relative paths, then inspect all generated internal page/asset links and fragment IDs. Acceptance is zero unresolved current document paths, zero missing local download targets, and zero missing generated fragment targets. Historical plan IDs must resolve to surviving history.
3. Content preservation: review the diff for unchanged technical values, units, evidence dates, financial figures, qualification status, and research decision boundaries. Preserve report and archive files; heading repairs must land on the intended section.
4. Tracking: assert task/plan index markers match their detail status; keep unrelated active ownership and pending architecture decisions intact.
5. Build: run bun run docs:build and git diff --check. Existing chunk-size and deliberately omitted-asset warnings are documented baseline behavior; the source catalog must describe those omissions accurately.

Risks

• Path repair can make a wrong reference look valid; validate destination identity as well as file existence.
• Historical research can be mistaken for approved specifications; derive labels only from existing notices and keep different application scopes distinct.
• Removing duplicate parent tables can hide entry points; retain every product/category link and verify child inventories.
• A successful VitePress build does not prove fragments and copied assets resolve; the rendered HTML scan is a separate acceptance check.

Alternatives

• Move research into topic directories: stronger physical grouping, but changes URLs and adds link migration work immediately after a product-directory migration. Defer unless explicitly selected.
• Merge overlapping reports and shorten long technical documents: may lose scope, evidence dates, or historical decisions. Requires a separate content decision, rather than inferring duplication from titles.
• Correct only architecture and plan markers: small, but leaves the broken references and reading-order problems unresolved.

Annotations

• The user requested documentation reorganization and optimization and approved the proposed navigation and consistency scope.
• 2026-09-10 05:52: The user approved implementation of this proposal.

Outcome

Completed at 2026-09-10 06:04. Updated 42 existing content/governance documents and the task/plan records. The product package index now has 64 lines instead of 164; the Air/Key overview has 29 instead of 76. Child indexes retain the detailed inventories, and every existing research report remains linked.

Corrected 413 relative paths (412 clickable links and one plain diagram path), redirected 15 retired-plan references, repaired 52 fragment links, removed 27 obsolete mirror headers, and added 55 companion-header links. The source catalog identifies the two oversized manuals as repository archives with publisher downloads. Reconciled the three completed plan index markers without rewriting their historical details.

Verification passed: final build in 10.65 seconds; 174 rendered HTML pages and 5,683 internal link occurrences with zero missing destinations/fragments and zero unreachable content pages; complete category inventories; consistent task/plan states; and git diff --check. Normalized comparisons verified unchanged prose, technical values, tables, and dates in the reference-repair documents. A fenced-diagram link-format issue found during verification was corrected before the final build. Local diff review: PASS, zero outstanding findings.

The existing chunk-size warning and deliberate omission of the two PDFs above 25 MiB remain documented publication behavior. Executable code, dependencies, data, archives, active research ownership, and pending architecture decisions are unchanged. No commit, push, or deployment was performed.