USM

Appearance

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

Intent ​

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.

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

Flows ​

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

Contracts ​

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

Tests ​

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