usm/gen-docs-split [built]

Split generated docs into help docs (public-facing, for visitors and new users) and developer docs (full technical detail, for the team). Adds visibility field to schema, --audience flag to docs serve/build, and filtered output for help docs.

Status: built

Why this exists

Currently USM generates one combined doc set that serves both visitors and developers. Visitors see implementation details, test expectations, and deployment secrets they don't need. Developers see everything, which is correct. By splitting into help docs (public, simplified) and developer docs (full), each audience gets the right view from the same .usm source.

Design decisions

post-process-filtering [accepted]

Decision: Generate full docs first, then filter for help audience

Rationale: Rather than modifying the core markdown generator with audience-aware logic, generate the full docs as usual then post-process for the help audience. This keeps the generator simple and puts audience filtering in the VitePress integration layer (docs.ts) where it belongs.

Alternatives considered:

• Audience-aware generator (pass audience through to all render functions) — rejected: Touches every render function, complex, hard to maintain
• Separate generator functions for help vs developer — rejected: Duplicates rendering logic, drifts over time

Consequences: Full docs generated first (slight overhead), then filtered — but filtering is fast and the full docs are useful anyway

visibility-field-optional [accepted]

Decision: Add optional visibility field (public/internal) to features and services

Rationale: Default visibility is internal (safe — nothing leaks unless explicitly marked public). Features marked public appear in help docs. Features with no visibility field appear in help docs only if status is built.

Consequences: Authors must opt-in features to public docs by setting visibility: public

help-docs-simplified-features [accepted]

Decision: Help docs show summary + intent + flows only, not contracts/tests/implementation

Rationale: Visitors don't need acceptance criteria checklists or Given/When/Then test cases. They need to understand what the feature does (summary), why it exists (intent), and how it works (flows as steps). Contracts and tests are developer concerns.

Consequences: Help docs are shorter and more readable for non-developers

docs-audience-model [accepted]

Decision: Help docs = user journey only (USM adopters + downstream end users); developer docs = contributors and James (everything). Help excludes internal tooling pages (code-navigator, orphan-files, spec-coverage) and the entire design/ section; keeps getting-started, agent setup, CLI/MCP/schema/config references, roadmap, language-support, feedback, and composed guides. Dev docs unchanged (full detail).

Rationale: Confirmed with the human 2026-09-26: help audience is BOTH adopters of USM and end users of downstream products; the user journey is the contract for help content. Internal tooling (code navigator, orphan files, spec coverage) and architecture deep-dives (design/) are contributor material and live only in developer docs. Statuses: help shows roadmap with shipped_in so adopters see direction; planned/in-progress features stay excluded per help-docs-only-built-features.

How it works

Generate both help and developer docs (generate-both-doc-sets)

usm generate produces full docs in .usm-workspace/docs/ (developer). usm docs build --audience help copies and filters into .usm-workspace/help-docs/ with simplified content and a public-oriented sidebar.

1. Generate — full developer docs into .usm-workspace/docs/ (existing behaviour)
2. Copy — docs to .usm-workspace/help-docs/ when audience is help
3. Filter — remove non-built features, deployment, operations, TOGAF, ArchiMate
4. Simplify — trim feature docs to summary + intent + flows only
5. Generate — help-oriented sidebar (no deployment, no planned features)
6. Build — VitePress build for the help docs directory

Serve help docs locally (serve-help-docs)

usm docs serve --audience help serves the filtered help docs on a local VitePress dev server for review.

1. Check — .usm-workspace/docs/ exists (run usm generate first)
2. Copy-and-filter — into .usm-workspace/help-docs/
3. Generate — help-oriented VitePress config
4. Serve — VitePress dev server

Guarantees

help-docs-only-built-features

Help docs only include features with status built (or visibility public)

Acceptance criteria:

• [ ] Features with status planned or in-progress are excluded from help docs
• [ ] Features with visibility: public are included regardless of status
• [ ] Features with visibility: internal are excluded from help docs

help-docs-simplified-content

Help docs feature pages show summary + intent + flows only

Acceptance criteria:

• [ ] No contracts section in help docs
• [ ] No tests section in help docs
• [ ] No implementation section in help docs
• [ ] No decisions section in help docs (or simplified to decision + rationale only)

help-docs-no-sensitive-info

Help docs exclude deployment details and operations runbooks

Acceptance criteria:

• [ ] No deployment.md in help docs
• [ ] No operations section
• [ ] No build commands or secrets in help docs

developer-docs-unchanged

Developer docs remain exactly as before (full detail)

Acceptance criteria:

• [ ] All features included (planned, in-progress, built)
• [ ] Full contracts, tests, decisions, implementation
• [ ] Deployment and operations pages

help-docs-user-journey-only

Help docs contain the user journey only — internal tooling pages (code-navigator, orphan-files, spec-coverage) and the design/ architecture section are contributor material and live exclusively in developer docs.

Acceptance criteria:

• [ ] code-navigator.md, orphan-files.md, spec-coverage.md absent from help docs
• [ ] design/ section absent from help docs (sidebar group too)
• [ ] getting-started, agent-setup-guide, CLI/MCP/schema/config references, roadmap, language-support, feedback present in help docs
• [ ] composed user-docs guides present in help docs sidebar
• [ ] developer docs keep all of the above (full detail, unchanged)

Test specifications

help-docs-exclude-planned

Given:

• feature_with_status_planned: true

Then:

• assertion: feature not present in help-docs/features/

help-docs-include-built

Given:

• feature_with_status_built: true

Then:

• assertion: feature present in help-docs/features/
• assertion: feature doc has summary and intent
• assertion: feature doc has no contracts section
• assertion: feature doc has no tests section

help-docs-include-public-visibility

Given:

• feature_with_visibility_public_and_status_planned: true

Then:

• assertion: feature present in help-docs/features/ (visibility overrides status)

help-docs-no-deployment

Given:

• system_with_deployment_info: true

Then:

• assertion: no deployment.md in help-docs/

developer-docs-unchanged

Given:

• generate_run: true

Then:

• assertion: .usm-workspace/docs/ has all features
• assertion: .usm-workspace/docs/ has deployment.md
• assertion: .usm-workspace/docs/ has full feature docs with contracts and tests

Implementation

• Primary: src/cli/docs.ts
• Test code status: none

See Also

• usm/cli-docs
• usm/gen-markdown
• usm/gen-feature-review