Part 9: Reference Docs & Full Generation

You have all source types in place: TypeScript, Gherkin, and stubs. Now you will create a bespoke reference document, generate everything, and lint your annotations.

9.1 Add referenceDocConfigs to configuration

Update delivery-process.config.ts to add the referenceDocConfigs array:

import { defineConfig } from "@libar-dev/delivery-process/config";

export default defineConfig({
  preset: "libar-generic",
  sources: {
    typescript: ["src/sample-sources/**/*.ts"],
    features: ["src/specs/**/*.feature"],
    stubs: ["src/stubs/**/*.ts"],
  },
  output: {
    directory: "docs-generated",
    overwrite: true,
  },
  referenceDocConfigs: [
    {
      title: "Identity & Persistence Reference",
      conventionTags: [],
      shapeSources: ["src/sample-sources/**/*.ts"],
      behaviorCategories: ["core", "api", "infra"],
      diagramScopes: [
        {
          archContext: ["identity", "persistence"],
          direction: "LR",
          title: "System Architecture",
          diagramType: "graph",
          showEdgeLabels: true,
        },
      ],
      claudeMdSection: "reference",
      docsFilename: "IDENTITY-PERSISTENCE-REFERENCE.md",
      claudeMdFilename: "identity-persistence-reference.md",
    },
  ],
});

9.2 Reference doc config fields

Field	Purpose
`title`	Document heading
`conventionTags`	Convention tags to include (from `@libar-docs-convention`-tagged files)
`shapeSources`	Glob patterns for TypeScript shape extraction
`behaviorCategories`	Category filters — which patterns’ descriptions to include
`diagramScopes`	Scoped Mermaid diagrams with bounded context filtering
`claudeMdSection`	Target directory under `_claude-md/` for AI-consumption summary
`docsFilename`	Output filename in `docs/` for the detailed version
`claudeMdFilename`	Output filename in `_claude-md/` for the compact version

Diagram scope options:

Field	Purpose
`archContext`	Filter to patterns in these bounded contexts
`direction`	Mermaid graph direction: `TB` (top-bottom) or `LR` (left-right)
`diagramType`	`graph`, `sequenceDiagram`, `stateDiagram-v2`, `C4Context`, `classDiagram`
`showEdgeLabels`	Show relationship type labels on arrows

9.3 Generate the reference doc

npm run docs:reference

Using sources from delivery-process.config.ts...
Scanning source files...
  Found 11 patterns
Extracting patterns...
  Extracted 11 patterns

Running generator: reference-docs
  ✓ docs/IDENTITY-PERSISTENCE-REFERENCE.md
  ✓ _claude-md/reference/identity-persistence-reference.md

✅ Documentation generation complete!
   2 files written

The generated reference doc includes:

1. Architecture Diagram — A Mermaid graph scoped to identity and persistence contexts with labeled edges showing uses (solid) and depends-on (dashed) relationships.

2. API Types — TypeScript interfaces extracted from shapes: UserRecord, DomainEvent, AuthResult.

3. Behavior Specifications — Descriptions from each pattern’s JSDoc, including Gherkin feature rule blocks with invariants.

Each referenceDocConfigs entry produces two files: a detailed version in docs/ and a compact version in _claude-md/ for AI context consumption.

9.4 Generate everything

npm run docs:all

Using sources from delivery-process.config.ts...
Scanning source files...
  Found 11 patterns
Extracting patterns...
  Extracted 11 patterns

Running generator: patterns
  ✓ PATTERNS.md
  ✓ patterns/notification-service.md
  ✓ patterns/notification-config.md
  ✓ patterns/notification-result.md
  ✓ patterns/user-service.md
  ✓ patterns/user-record.md
  ✓ patterns/event-store.md
  ✓ patterns/domain-event.md
  ✓ patterns/auth-handler.md
  ✓ patterns/auth-result.md
  ✓ patterns/user-registration.md
  ✓ patterns/authentication.md

Running generator: roadmap
  ✓ ROADMAP.md
  ✓ phases/phase-01-inception.md
  ✓ phases/phase-02-elaboration.md
  ✓ phases/phase-03-session.md

Running generator: reference-docs
  ✓ docs/IDENTITY-PERSISTENCE-REFERENCE.md
  ✓ _claude-md/reference/identity-persistence-reference.md

Running generator: overview-rdm
  ✓ OVERVIEW.md

Running generator: architecture
  ✓ ARCHITECTURE.md

Running generator: business-rules
  ✓ BUSINESS-RULES.md
  ✓ business-rules/platform.md

Running generator: taxonomy
  ✓ TAXONOMY.md
  ✓ taxonomy/categories.md
  ✓ taxonomy/metadata-tags.md
  ✓ taxonomy/format-types.md

✅ Documentation generation complete!
   26 files written

Seven generators, 26 files, all derived from your annotations.

9.5 Available generators

npm run docs:list

Available generators:
  - adrs: Architecture Decision Records
  - architecture: Architecture diagrams (component and layered views)
  - business-rules: Business rules and invariants by domain
  - changelog: Keep a Changelog format changelog
  - current: Active development work in progress
  - doc-from-decision: Generate documentation from ADR/PDR decision documents
  - milestones: Historical completed milestones
  - overview-rdm: Project architecture overview
  - patterns: Pattern registry with category details
  - planning-checklist: Pre-planning questions and Definition of Done
  - pr-changes: PR-scoped changes for review
  - remaining: Aggregate view of incomplete work
  - requirements: Product requirements by area/role
  - roadmap: Development roadmap by phase
  - session: Current session context and focus
  - session-findings: Retrospective discoveries for roadmap refinement
  - session-plan: Implementation plans for phases
  - taxonomy: Tag taxonomy configuration reference
  - traceability: Timeline to behavior file coverage
  - validation-rules: Process Guard validation rules reference

20 generators are available. The docs:all script uses 7 of them. The remaining generators (adrs, changelog, current, doc-from-decision, milestones, planning-checklist, pr-changes, remaining, requirements, session, session-findings, session-plan, traceability, validation-rules) are available for more advanced workflows.

Tip: Pass all generators as a single comma-separated value: -g patterns,roadmap,architecture. Do not use multiple -g flags — this is not supported and may cause generators to be silently skipped.

9.6 What was generated

Here is a sample of what the generated files contain:

PATTERNS.md — Pattern registry with progress bars:

Overall: [░░░░░░░░░░░░░░░░░░░░] 0/11 (0% complete)

Categories:
- API (2)
- Core (1)
- DDD (1)
- Infra (2)
- Shape (5)

ARCHITECTURE.md — Mermaid component diagram:

graph TB
    subgraph identity["Identity BC"]
        NotificationService["NotificationService[service]"]
        UserService["UserService[service]"]
        AuthHandler["AuthHandler[service]"]
    end
    subgraph persistence["Persistence BC"]
        EventStore["EventStore[infrastructure]"]
    end
    NotificationService --> AuthHandler
    UserService --> EventStore
    AuthHandler --> UserService

ROADMAP.md — Phase navigation with progress tracking:

Phases: 0/3 complete

| Phase | Progress | Complete |
| Inception  | 0/2 | 0% |
| Elaboration | 0/3 | 0% |
| Session    | 0/1 | 0% |

BUSINESS-RULES.md — Domain constraints overview:

5 rules from 2 features across 1 product areas.

| Product Area | Features | Rules | With Invariants |
| Platform     | 2        | 5     | 5               |

OVERVIEW.md — Architecture summary:

Progress: [░░░░░░░░░░░░░░░░░░░░] 0/11 (0%)

| Category | Count |
| infra    | 2     |
| shape    | 5     |
| core     | 1     |
| api      | 2     |
| ddd      | 1     |

9.7 Linting

npm run lint:patterns

  Config: /private/tmp/dp-tutorial-test/delivery-process.config.ts
/private/tmp/dp-tutorial-test/src/sample-sources/user-service.ts
  34:1  error    missing-pattern-name  Pattern missing explicit name. Add @libar-docs-pattern YourPatternName
  34:1  warning  missing-status  No @libar-docs-status found. Add: @libar-docs-status completed|active|roadmap
  34:1  warning  missing-when-to-use  No "When to Use" section found. Add ### When to Use or **When to use:** in description
  34:1  info     missing-relationships  Consider adding relationship tags: @libar-docs-uses and/or @libar-docs-used-by

/private/tmp/dp-tutorial-test/src/sample-sources/event-store.ts
  32:1  error    missing-pattern-name  Pattern missing explicit name. Add @libar-docs-pattern YourPatternName
  32:1  warning  missing-status  No @libar-docs-status found. Add: @libar-docs-status completed|active|roadmap
  32:1  warning  missing-when-to-use  No "When to Use" section found. Add ### When to Use or **When to use:** in description
  32:1  info     missing-relationships  Consider adding relationship tags: @libar-docs-uses and/or @libar-docs-used-by

/private/tmp/dp-tutorial-test/src/sample-sources/auth-handler.ts
  31:1  error    missing-pattern-name  Pattern missing explicit name. Add @libar-docs-pattern YourPatternName
  31:1  warning  missing-status  No @libar-docs-status found. Add: @libar-docs-status completed|active|roadmap
  31:1  warning  missing-when-to-use  No "When to Use" section found. Add ### When to Use or **When to use:** in description
  31:1  info     missing-relationships  Consider adding relationship tags: @libar-docs-uses and/or @libar-docs-used-by

✗ 3 errors, 6 warnings, 3 info

The 3 errors are from @libar-docs-shape annotations on interfaces (UserRecord at line 34, DomainEvent at line 32, AuthResult at line 31). These are lightweight shape entries that lack their own @libar-docs-pattern names. This is expected — the shapes are discovered through the parent pattern’s @libar-docs-extract-shapes tag, so they do not need independent pattern names.

Checkpoint: Part 9

delivery-process.config.ts has referenceDocConfigs
npm run docs:all writes 26 files to docs-generated/
docs-generated/docs/IDENTITY-PERSISTENCE-REFERENCE.md exists
docs-generated/_claude-md/reference/ has the compact version
npm run lint:patterns shows 3 errors (all expected shape warnings)

Recap: Part 9

Reference docs are custom composite documents scoped to bounded contexts
docs:all generates everything in one command — 7 generators produce 26 files
The linter validates annotation quality; shape-only warnings are expected
Two output formats per reference doc: detailed (for humans) and compact (for AI agents)