Add Documentation module & spec diff

.claude/settings.local.json

@@ -35,7 +35,11 @@
       "Bash(/root/.dotnet/dotnet sln:*)",
       "Bash(./docflow-dev.sh:*)",
       "Bash(rm:*)",
-      "Bash(grep:*)"
+      "Bash(grep:*)",
+      "Bash(mkdir -p /tmp/diff-demo)",
+      "Bash(cp samples/integration-demos/petstore.json /tmp/diff-demo/old.json)",
+      "Bash(cp samples/integration-demos/petstore.json /tmp/diff-demo/new.json)",
+      "Bash(sed -i 's/\"placeOrder\"/\"placeOrderV2\"/' /tmp/diff-demo/new.json)"
     ]
   }
 }

CLAUDE.md

@@ -14,6 +14,8 @@ DocFlow is an intelligent documentation and modeling toolkit. Current implementa
 | Whiteboard Scanner | **Complete** | Claude Vision API integration |
 | CLI | **Complete** | System.CommandLine + Spectre.Console |
 | Integration Module | **Complete** | OpenAPI parsing, CDM mapping, SLA validation, code generation |
+| API Docs Generation | **Complete (Phases 1–5)** | OpenAPI → Markdown or HTML with class/ER/sequence/C4-context/endpoint-flow diagrams, synthesised JSON examples, dedicated security page, cross-linked entities, `--watch` regeneration, and pluggable `IApiSpecParser`s (`integrate docs`) |
+| API Spec Diff | **Complete (Phase 5)** | `integrate diff` produces a breaking / non-breaking Markdown changelog across two specs |
 | IMS Learning | Designed | Pattern learning system (not implemented) |
 | Document Pipeline | Planned | PDF/Word conversion |
 
@@ -73,6 +75,12 @@ docflow integrate sla <url> --expected <duration> [--samples 10] [--interval 5s]
 
 # Generate integration code (DTOs, AutoMapper, HTTP client, validators)
 docflow integrate generate <spec.json> --cdm <path> -o <dir> [-n namespace]
+
+# Generate a design-documentation bundle (Markdown or HTML + Mermaid diagrams)
+docflow integrate docs <spec.json> -o <dir> [--format markdown|html] [--diagrams class,er,sequence,context,flow,all,none] [--group-by tag|path] [--title "My API"] [--with-examples] [--watch] [-v]
+
+# Produce a breaking / non-breaking Markdown changelog between two specs
+docflow integrate diff <old-spec> <new-spec> -o <changelog.md>
 ```
 
 ## Architecture Overview
@@ -236,6 +244,21 @@ API keys can be configured via:
 | `src/DocFlow.Integration/Mapping/CdmMapper.cs` | CDM mapping with confidence |
 | `src/DocFlow.Integration/Validation/SlaValidator.cs` | SLA data freshness validation |
 | `src/DocFlow.Integration/CodeGen/IntegrationCodeGenerator.cs` | Integration code generation |
+| `src/DocFlow.Core/CanonicalModel/ApiSurface.cs` | Canonical API-surface records (operations, params, responses, security) |
+| `src/DocFlow.Documentation/Abstractions/IDocumentationGenerator.cs` | Documentation generator contract |
+| `src/DocFlow.Documentation/Markdown/MarkdownDocumentationGenerator.cs` | Phase 1 Markdown doc generator |
+| `src/DocFlow.Documentation/Markdown/Sections/` | Per-section builders (Overview/DomainModel/Endpoint/Index) |
+| `src/DocFlow.Diagrams/Mermaid/MermaidErDiagramGenerator.cs` | ER diagram from SemanticModel (Composition/Aggregation/Association) |
+| `src/DocFlow.Diagrams/Mermaid/MermaidSequenceDiagramGenerator.cs` | Per-operation sequence diagram from ApiOperation |
+| `src/DocFlow.Diagrams/Mermaid/MermaidC4ContextGenerator.cs` | C4-style system-context diagram (flowchart-LR fallback) |
+| `src/DocFlow.Diagrams/Mermaid/MermaidEndpointFlowchartGenerator.cs` | Per-operation request-lifecycle flowchart |
+| `src/DocFlow.Documentation/Examples/ExampleSynthesizer.cs` | Schema-driven JSON example synthesis (spec examples preferred) |
+| `src/DocFlow.Documentation/Html/StaticSiteRenderer.cs` | Markdown bundle → self-contained static HTML site (Markdig) |
+| `src/DocFlow.Documentation/Html/Assets/theme.css` | Embedded HTML theme (dark/light) |
+| `src/DocFlow.Documentation/Diff/SpecDiffer.cs` | Computes a breaking / non-breaking SpecDiff between two SemanticModels |
+| `src/DocFlow.Documentation/Diff/ChangelogGenerator.cs` | Renders a SpecDiff as a grouped Markdown changelog |
+| `src/DocFlow.Core/Abstractions/IApiSpecParser.cs` | Pluggable spec-parser strategy interface |
+| `src/DocFlow.Core/Abstractions/SpecParserRegistry.cs` | Picks the first registered parser whose CanParse matches |
 | `src/DocFlow.CLI/Program.cs` | CLI entry point |
 
 ## Sample Files

README.md

@@ -17,7 +17,7 @@ Transform whiteboard sketches into working code. Generate diagrams from source f
 [![.NET](https://img.shields.io/badge/.NET-8.0-512BD4)](https://dotnet.microsoft.com/)
 [![License](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
 [![Build](https://img.shields.io/badge/build-passing-brightgreen)]()
-[![Tests](https://img.shields.io/badge/tests-72%20passing-brightgreen)]()
+[![Tests](https://img.shields.io/badge/tests-152%20passing-brightgreen)]()
 
 ---
 
@@ -117,8 +117,43 @@ docflow integrate sla https://api.example.com/data --expected 30s --samples 10
 
 # Generate integration code (DTOs, AutoMapper, HTTP client, validators)
 docflow integrate generate petstore.json --cdm Models/ -o Generated/ -n MyApp.Integration
+
+# Generate a navigable design-docs bundle (Markdown + Mermaid + HTML)
+docflow integrate docs petstore.json -o docs/api -v
+
+# Watch the spec and regenerate on change (debounced)
+docflow integrate docs petstore.json -o docs/api --watch
+
+# Emit a breaking / non-breaking Markdown changelog between two specs
+docflow integrate diff old.json new.json -o CHANGELOG.md
+```
+
+#### Docs Bundle Contents
+
+Running `docflow integrate docs` produces:
+
+```
+docs/api/
+├── index.md                  # TOC
+├── overview.md               # API title, servers, auth summary
+├── architecture.md           # C4-style system-context diagram + deployments table
+├── domain-model.md           # Mermaid class + ER diagrams + entity table (with anchors)
+├── security.md               # Scheme table, OAuth2 flow diagrams, per-operation requirements
+├── endpoints/<tag>.md        # One page per tag (or path segment); sequence + flowchart embedded
+├── sequences/<opId>.md       # Standalone per-operation sequence diagrams
+├── diagrams/context.mmd      # Standalone Mermaid context diagram
+└── assets/openapi.json       # Verbatim copy of the source spec
 ```
 
+The default `--diagrams` set is `all` (class, ER, sequence, context, flow). Entity references on
+endpoint pages link into `domain-model.md` via stable `#entity-<kebab>` anchors. Passing
+`--with-examples` adds synthesized JSON request/response examples (spec-provided examples take
+precedence when present).
+
+Passing `--format html` converts the bundle into a self-contained static site: one `.html` per
+`.md`, an embedded dark/light CSS theme (`assets/theme.css`), a sidebar nav, and Mermaid.js via
+CDN. See [Documentation module design](docs/design/documentation-module.md).
+
 #### Generate Options
 
 | Option | Description |