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

• status: completed
• priority: P2
• owner: docs-maintainer/session-20260910-0455
• createdAt: 2026-09-10 04:55

Description

Investigate the documentation structure and propose a focused organization pass covering entry pages, reading order, obsolete repository descriptions, local references, and task/plan consistency. Preserve the existing product and research decision boundaries.

Acceptance: record a concrete file-level proposal; after approval, make affected navigation and references resolve, reconcile completed plan markers with their details, and pass the documentation build and git diff --check.

ActiveForm

Completed documentation organization and verified the generated site.

Dependencies

• blocked by: (none; proposal approved)
• blocks: (none)

Notes

• Full-tier task spanning the business, product, research, and repository documentation entry points.

• File-based tracking is used for this task.

• The existing yacht research task remains owned by its current session; this task does not change its status or controlled product specifications.

• 2026-09-10 04:59: Investigation completed; proposal is ready for review. Baseline build passed; identified 428 unresolved explicit paths, 52 broken rendered fragment links, two unpublished PDF links, stale navigation descriptions, and three plan-marker mismatches. No content implementation has started.

• 2026-09-10 05:52: The user approved the proposed organization pass. Implementation started under the existing task claim.

• 2026-09-10 06:02: Content changes implemented. Corrected 413 relative references (412 clickable links and one plain path inside the Key diagram), redirected 15 retired-plan references to history, removed 27 mirror headers, added 55 companion-header links, and repaired 52 fragment links. Product and Air/Key overviews now use category catalogs; research distinguishes current proposals, evidence, and historical alternatives.

• 2026-09-10 06:02: Verification found one link incorrectly formatted inside a fenced diagram; changed it to a plain corrected path. Normalized content comparison now confirms unchanged prose, tables, values, and dates across all 28 reference-repair files; the five fragment-repair files differ only in link destinations. Diagram/code blocks are unchanged except that one path.

• 2026-09-10 06:02: Build and rendered-link checks passed on 174 HTML pages with no missing local destinations, missing fragments, or unreachable content pages. All 13 product/shared and three Air/Key category indexes cover their detail files; task and plan states are synchronized. Local diff review: PASS, zero outstanding findings. Final build is being refreshed after the last reference-format correction and tracking notes.

• complete: Final documentation build and rendered-link verification passed; content preservation, category inventories, tracking consistency, local diff review, and whitespace checks passed.