usm/docs-ia-restructure [built]

Restructure the generated docs sidebar to a stable, audience-appropriate information architecture that renders correctly in VitePress: single-level nesting with flattened-but-labelled feature area groups, unique human labels (no 'CLI CLI…', no ambiguous 'Overview's), a dedicated Reference group, Architecture instead of Design, help docs reduced to user-journey content (no feature build specs, no decision register), and a roadmap brought current with all shipped features.

Status: built

Why this exists

The generated sidebar misleads users about what the docs contain: VitePress supports only one level of sidebar nesting, but we emit three (Project Management → Features → area → pages), so VitePress silently flattens the inner groups and titles groups after arbitrary first items — a group literally named "Roadmap" contains all 38 feature pages, another named "Source Map" contains the reference pages. Labels duplicate area prefixes ("CLI CLI Color Output"), four different pages are all labelled "Overview", and the help tree exposes feature build specs (flows/contracts/test internals) that belong to the developer audience — violating the help = user-journey-only model. Meanwhile the roadmap page renders from a system.usm roadmap that stopped tracking shipped features at 0.9.0, so the public "what's shipping next" view is stale. Users cannot form a correct mental model of the docs from the navigation as it stands.

How it works

Navigate the developer docs (find-my-way-dev)

1. Scan — sidebar top-to-bottom: orient via Getting Started → Guides → Features by area → Project Management → Reference → Architecture → Source Map → Exports
2. Open — the MCP Tools area group and find usm_update_system without scrolling past 38 unrelated pages
3. Verify — each group title says what it contains; no group is named after an arbitrary first item

Navigate the help docs as a new user (find-my-way-help)

1. Scan — help sidebar: Getting Started → Guides → Reference → Roadmap → Help — no build specs, no decision register
2. Follow — a persona guide from the Guides group and complete the task it describes
3. Verify — no clicked link lands on contract/flow/test internals; no dead links from Roadmap to removed pages

Guarantees

sidebar-single-level-nesting

The sidebar renders within VitePress's single-level nesting limit: top-level groups with item lists only. Nested group structures are flattened at generation time with boundaries preserved as prefixed labels, never lost.

Acceptance criteria:

• [ ] No group ever nests a group inside its items array — generation flattens Features sub-areas into sibling top-level collapsible groups (CLI, Generators, MCP Tools, Schema & Docs)
• [ ] Every rendered group title is intentional (never falls back to first-item text)
• [ ] Rendered sidebar verified structurally in a browser fixture: group titles match the intended IA

labels-unique-and-human

Every sidebar label is unique, human, and free of mechanical artifacts.

Acceptance criteria:

• [ ] No duplicated area prefixes ('CLI CLI Color Output') — disk-discovered features reuse system.index display names when available, else title-case slug without area prefix
• [ ] Area overview links are labelled '<Area> overview', not bare 'Overview' (no repeated labels across groups)
• [ ] Feature naming is consistent: the same feature renders the same label whether discovered from system.index or disk scan

sections-ordered-and-named

Sidebar sections have a stable, audience-appropriate order and naming.

Acceptance criteria:

• [ ] Dev order: Getting Started, Guides, Features, Project Management (Roadmap, Decision Register), Reference, Architecture, Source Map, Exports
• [ ] Help order: Getting Started, Guides, Reference (user-facing pages only), Roadmap, Help (Language Support, Report Issue)
• [ ] Reference is its own top-level group (CLI Reference, MCP Tools, Configuration, Schema Reference) — not mixed into a group titled by its first item
• [ ] Design section renders as 'Architecture' with its section labels intact

help-audience-purity

Help docs contain user-journey content only: feature build specs (flows/contracts/test internals) and the Decision Register are developer-docs content.

Acceptance criteria:

• [ ] Help tree excludes features/ area pages (all areas, including cli) and design/decision-register
• [ ] Help keeps Roadmap, reference pages, guides, getting-started, agent-setup-guide, editor setup, language support, feedback
• [ ] Roadmap links that point at excluded feature pages degrade to plain text in the help tree (same guard pattern as package docs)
• [ ] Help sidebar never shows a group containing contract/flow/test internals
• [ ] Agent Setup Guide appears in the help sidebar Getting Started group — the page renders in both audiences (universal package content) and must never be nav-orphaned in either

roadmap-current

The roadmap stays current: every shipped feature appears, and stale statuses are corrected at the spec level — the roadmap page renders from system.usm, so fixing the source fixes the docs.

Acceptance criteria:

• [ ] Features marked built in system.index have roadmap entries with shipped_in set (rules-files, docs-split, help-reference, config-outputs, mcp-write, this session's 0.9.x work)
• [ ] No roadmap item claims 'planned' for something already shipped; statuses match feature status
• [ ] The 2026-09-27/28 consumer-blocker fixes appear as shipped items once released

Test specifications

dev-sidebar-structure

Given:

• generate_run: true

When: find-my-way-dev

Then:

• assertion: sidebar JSON contains no group nested inside another group's items
• assertion: top-level groups match the intended dev order and names
• assertion: no label contains a doubled area prefix; no duplicate 'Overview' labels

help-sidebar-purity

Given:

• help_audience_generate: true

When: find-my-way-help

Then:

• assertion: help sidebar shows only Getting Started, Guides, Reference, Roadmap, Help groups
• assertion: no features/ or decision-register links appear in help sidebar
• assertion: roadmap feature links degrade to text when the target page is excluded

roadmap-covers-built

Given:

• system_usm_with_built_features: true

Then:

• assertion: every feature marked built in system.index has a roadmap entry with shipped_in
• assertion: no roadmap item is 'planned' for an already-built feature

sidebar-render-verified

Given:

• playwright_crawl: true

Then:

• assertion: second generate produces byte-identical config.mts sidebar
• assertion: browser-rendered group titles match the intended IA (no first-item fallback titles)

Implementation

• Primary: src/cli/docs.ts (generateSidebar restructure + HELP_EXCLUDE_PATHS purity); .usm/system.usm roadmap (17 shipped entries, feature refs aligned to index paths)
• Test code: tests/docsIa.test.ts
• Test code status: manual

See Also

• usm/cli-docs
• usm/gen-user-docs