[M5-D5.1/D5.2] Write Design for Extraction guide and Connection DSL reference

[NTCoding]

Deliverable: Design for Extraction guide and Connection DSL reference documentation

Context

PRD: docs/project/PRD/active/PRD-phase-12-connection-detection.md — M5 D5.1, D5.2

Documentation for users: why code design affects extraction accuracy, how to follow Golden Path conventions, and reference documentation for the configurable connection DSL.

Documentation rules: Read apps/docs/CLAUDE.md before starting — it defines user journeys, page formats, terminology rules, and cross-linking conventions for all public documentation.

Traceability

• PRD Section: M5-D5.1 (Design for Extraction guide), M5-D5.2 (Connection DSL reference)
• Functional Requirements: Guide with all sections listed in PRD, DSL reference with examples
• Success Criteria: SC-8 (guide published, no TODO/TBD placeholders), SC-9 (DSL documented)

User Journeys (from apps/docs/CLAUDE.md)

Design for Extraction guide serves: "I want repeatable, config-driven extraction that runs in CI without AI"

• This is a conceptual guide that helps users understand why code design matters before they write extraction config
• Location: apps/docs/extract/deterministic/typescript/design-for-extraction.md
• Page format: Workflow companion page (not a reference page)
• Links FROM: TypeScript workflow pages (especially Step 3) should link to this guide
• Links TO: extraction config reference, decorators reference, conventions package docs

Connection DSL reference serves: "I know what I need — show me the exact API, config field, CLI flag, or schema structure"

• This is a reference lookup page for connection extraction config options
• Location: apps/docs/reference/extraction-config/connections.md
• Page format: Must match predicates.md format — pageClass: reference frontmatter, overview table, ### per item, parameters table, --- separators, See Also section
• Links FROM: TypeScript Step 4 (Link) should link here
• Links TO: schema reference, examples page, predicates reference

Acceptance Criteria

• ✓ apps/docs/extract/deterministic/typescript/design-for-extraction.md exists with sections:
  • Why code design affects extraction accuracy
  • Golden Path conventions with examples
  • Migration guide from legacy patterns
• ✓ apps/docs/reference/extraction-config/connections.md exists matching predicates.md format:
  • Overview table of all connection config options
  • Each option as ### with parameters table
  • Examples for common frameworks (NestJS, Express, custom event emitters)
• ✓ No TODO or TBD placeholders in either document
• ✓ Both docs reference actual code examples and config syntax
• ✓ Page serves a specific user journey (stated above)
• ✓ Format matches canonical example for page type (reference → predicates.md, guide → workflow companion)
• ✓ All terms from docs/architecture/domain-terminology/contextive/definitions.glossary.yml — no invented terms
• ✓ See Also section with 3-5 cross-links using absolute paths
• ✓ Sidebar entries added to .vitepress/config.ts in correct sections
• ✓ /documentation-review passes with no ❌ items

Edge Case Scenarios

• Connection DSL reference uses a term not in the glossary → flag and add to glossary or use existing term
• Guide references a decorator or config field that doesn't exist yet → depends on [M1-D1.1/D1.2/D1.3/D1.4] Build scoped call graph with sync connection detection #237 [M1-D1.7/D1.5/D1.6] Define EventPublisherDef convention and implement async connection detection #238 [M4-D4.1/D4.2] Implement configurable connection pattern DSL with decorator matching #242 completing first

Implementation Guidelines

• Architecture: §9.1.1 (all modified packages referenced), §9.2.4 (EventPublisherDef), §9.2.5 (ConnectionPattern)
• Firm constraints: Pages go in apps/docs/ (public site), NOT docs/ (internal). File locations above.
• Flexible decisions: Documentation structure within format constraints, example selection
• Reference actual EventPublisherDef, EventHandlerDef, EventDef interfaces
• Reference actual ConnectionPattern DSL syntax from extract-config
• Include real extraction config examples from ecommerce-demo-app
• Follow page formats defined in apps/docs/CLAUDE.md

Embedded Reasoning

Why: Users need to understand how to write code that's extractable and how to configure extraction for non-standard patterns.
What: Two documents: a conceptual guide (design-for-extraction) and a reference page (connection DSL) matching existing reference format.
How: Write docs referencing implemented conventions, patterns, and real examples from the codebase. Follow apps/docs/CLAUDE.md for page formats and cross-linking.

Testing Strategy

• Unit: N/A
• Verification: Pages render, formats match, terminology valid, review passes.

Dependencies

Depends on #237 #238 #242

Verification

pnpm nx build docs                    # Pages render without errors
/documentation-review                  # All three review dimensions pass (journey, format, terminology)

[NTCoding]

Documentation Rules Applied (from new apps/docs/CLAUDE.md)

This task was created before the documentation rules were established. The following changes are needed:

File Paths

The acceptance criteria reference docs/guides/design-for-extraction.md — this is the internal docs directory. Public documentation goes in apps/docs/. The exact paths need to be determined based on which user journey these pages serve (see below).

User Journey Fit

Per apps/docs/CLAUDE.md, every page must serve a specific journey:

• Design for Extraction guide → Serves the "I want repeatable, config-driven extraction that runs in CI without AI" journey. This is a conceptual guide that helps users understand why code design matters before they write extraction config. Likely belongs at apps/docs/extract/deterministic/typescript/design-for-extraction.md or as a new step/companion page in the TypeScript workflow.

• Connection DSL reference → Serves the "I know what I need — show me the exact API, config field, CLI flag, or schema structure" journey. This is a reference page. Belongs at apps/docs/reference/extraction-config/connections.md and must match the predicates.md format (overview table → ### per item → parameters table → --- separators).

Page Format

• Design for Extraction guide: Follow workflow step format from CLAUDE.md (or a variant for conceptual guides)
• Connection DSL reference: Must match apps/docs/reference/extraction-config/predicates.md format exactly — pageClass: reference frontmatter, overview table, ### per item, parameters table, --- separators, See Also section

Additional Acceptance Criteria Needed

• ✓ Page serves a specific user journey (stated above)
• ✓ Format matches canonical example for page type
• ✓ All terms from docs/architecture/domain-terminology/contextive/definitions.glossary.yml
• ✓ See Also section with 3-5 cross-links using absolute paths
• ✓ /documentation-review passes with no ❌ items

Updated Verification

pnpm nx build docs        # Pages render without errors
/documentation-review      # All three review dimensions pass (journey, format, terminology)

Reference

See apps/docs/CLAUDE.md for the full documentation rules including page formats, cross-linking conventions, and terminology requirements.