@pukujan/create-modular-monolith 2.0.0 → 2.1.0

package/template/docs/architecture/PLATFORM_ARCHITECTURE.md

@@ -0,0 +1,221 @@
+# Platform architecture — built for agents and engineering at scale
+
+This starter is designed so **Cursor agents, CI, and humans** share the same map of the repository. Business features are added as modules; the **platform layer** stays stable.
+
+---
+
+## Design goals
+
+| Goal | Mechanism |
+|------|-----------|
+| **Agents know where files go** | `REPO_ARTIFACT_LAYOUT.md`, `file-exchange/`, contract manifest |
+| **Agents know what changed** | Pre-push dev log: Part I summary (mermaid, tables) + Part II detail + full tree |
+| **Agents know which APIs exist** | `docs/API.md` registry + `api-inventory` in every dev log |
+| **No silent drift** | `lint:contracts`, `lint:api-docs`, `lint:repo-artifacts` |
+| **Handoff without chaos** | Dated `file-exchange/imports/{stamp}/` — never process from `Downloads/` |
+| **Onboarding in one read** | `condense:all` → consolidated models, prompts, file tree in `exports/` |
+
+---
+
+## System map
+
+```mermaid
+flowchart TB
+  subgraph human [Human workflow]
+    import[npm run import:file-exchange]
+    code[Implement in modules]
+    devlog[npm run dev-log:pre-push]
+    push[git push]
+  end
+
+  subgraph artifacts [Canonical artifacts]
+    fx[file-exchange/]
+    wl[work-log/dev-logs/]
+    docs[docs/architecture/contracts/]
+    api[docs/API.md]
+  end
+
+  subgraph agent [Agent reads first]
+    agentJson[work-log/dev-logs/agent/*.json]
+    consolidated[file-exchange/exports/consolidated-*.json]
+  end
+
+  import --> fx
+  code --> api
+  devlog --> wl
+  devlog --> agentJson
+  condense[npm run condense:all] --> consolidated
+  agentJson --> code
+  consolidated --> code
+  push --> devlog
+```
+
+---
+
+## Modular monolith core
+
+```text
+backend/src/core/          module-loader → register(app)
+backend/src/modules/*      one feature = one folder
+frontend/src/core/         App shell + moduleRegistry
+frontend/src/modules/*     one route module per feature
+```
+
+**Rules** (enforced by `lint:boundaries`, `lint:layers`):
+
+- Modules import `shared/`, not other modules.
+- Backend: routes → services → repositories/domain.
+- Every new route appears in `docs/API.md`.
+
+Scaffold: `npm run new:module -- my-feature --label "My Feature"`
+
+---
+
+## Contract pipeline
+
+See [CONTRACTS_OVERVIEW.md](./CONTRACTS_OVERVIEW.md).
+
+1. **Register** in `contracts/manifest.json`
+2. **Document** in `contracts/*.contract.md`
+3. **Implement** in `*.contract.js` when code needs constants
+4. **Changelog** in `contracts/changelog.jsonl`
+5. **Lint** with `npm run lint:contracts`
+
+Contracts version independently (e.g. `fileExchange` v001, `prePushDevLog` v001).
+
+---
+
+## File exchange (agent inbox)
+
+```text
+file-exchange/imports/2026-05-23_15-59-43Z/    ← inbound only
+file-exchange/exports/2026-05-23_16-00-00Z/    ← session outputs
+file-exchange/exports/consolidated-*.json      ← repo snapshots
+```
+
+Stamp format: `YYYY-MM-DD_HH-MM-SSZ` via `formatExchangeTimestamp()`.
+
+**Cursor rule** (`.cursor/rules/file-exchange-inbox.mdc`, `alwaysApply: true`) makes import mandatory before processing user files.
+
+---
+
+## Pre-push dev log (audit trail)
+
+**Before every push:**
+
+```bash
+npm run dev-log:pre-push -- --slug <kebab-topic>
+```
+
+| File | Audience | Contents |
+|------|----------|----------|
+| `human/*_dev-log_*.md` | Humans | Part I: TOC, mermaid, API/version/test/git tables, condensed tree. Part II: decisions, iterations, full tree |
+| `agent/*_dev-log-agent_*.json` | Agents | Same facts in structured JSON — read this first when resuming |
+
+Tree capture ignores: `node_modules`, `.git`, `dist`, `build` (equivalent to `tree -I "node_modules|.git|dist|build"`).
+
+Works **without git** until `git init`; then git sections auto-fill.
+
+---
+
+## Consolidated exports (repository X-ray)
+
+```bash
+npm run condense:all
+```
+
+| Output | Purpose |
+|--------|---------|
+| `consolidated-models.json` | Schema inventory (model-condenser) |
+| `consolidated-prompts.json` | All prompt templates + manifests |
+| `consolidated-file-structure.json` | Full file tree + stats |
+
+Primary handoff path: `file-exchange/exports/`. Mirror: `models/` for API compatibility.
+
+---
+
+## Automation scripts reference
+
+### Governance (run in CI)
+
+| Command | Script |
+|---------|--------|
+| `npm run lint:contracts` | `scripts/lint-contracts.mjs` |
+| `npm run lint:repo-artifacts` | `scripts/lint-repo-artifacts.mjs` |
+| `npm run lint:api-docs` | `scripts/check-api-docs.mjs` |
+| `npm run lint:architecture` | boundaries + layers + api-docs |
+
+### Agent / session workflow
+
+| Command | Script |
+|---------|--------|
+| `npm run import:file-exchange` | `scripts/import-to-file-exchange.mjs` |
+| `npm run dev-log:pre-push` | `scripts/write-pre-push-dev-log.mjs` |
+| `npm run dev-log:verify` | `scripts/verify-dev-log.mjs` |
+| `npm run condense:all` | condense-prompts + file-structure + condense-models |
+
+### Scaffolding
+
+| Command | Script |
+|---------|--------|
+| `npm run new:module` | `scripts/new-module.mjs` |
+
+---
+
+## Scaling to many modules
+
+```mermaid
+flowchart LR
+  m1[module-a]
+  m2[module-b]
+  m3[module-n]
+  core[core + shared]
+  contracts[contracts/manifest]
+  m1 --> core
+  m2 --> core
+  m3 --> core
+  contracts --> m1
+  contracts --> m2
+  contracts --> m3
+```
+
+Adding a module does **not** change the platform contracts. You:
+
+1. Run `new:module`
+2. Add rows to `docs/API.md`
+3. Register prompts in `prompts/manifest.json`
+4. Run `dev-log:pre-push` before push
+
+The condenser and dev-log scripts scan the **whole repo** — new modules appear automatically in the next tree and API inventory.
+
+---
+
+## Cursor integration
+
+| File | Role |
+|------|------|
+| `AGENTS.md` | Mandatory workflows for agents |
+| `.cursor/commands/pre-push-dev-log.md` | How to fill dev logs |
+| `.cursor/commands/planning-study-log.md` | Planning-only study logs |
+| `.cursor/rules/file-exchange-inbox.mdc` | alwaysApply import discipline |
+| `.cursor/rules/api-documentation.mdc` | Keep API docs in sync |
+
+---
+
+## What to read first (agents)
+
+1. `work-log/dev-logs/agent/` — latest `*_dev-log-agent_*.json`
+2. `file-exchange/exports/consolidated-file-structure.json` — layout
+3. `docs/architecture/CONTRACTS_OVERVIEW.md` — contract index
+4. `docs/API.md` — HTTP surface
+5. `AGENTS.md` — required commands
+
+---
+
+## Related docs
+
+- [CONTRACTS_OVERVIEW.md](./CONTRACTS_OVERVIEW.md)
+- [REPO_ARTIFACT_LAYOUT.md](./REPO_ARTIFACT_LAYOUT.md)
+- [ARCHITECTURE_GUARDRAILS.md](./ARCHITECTURE_GUARDRAILS.md)
+- [MODULE_INTERNAL_CONTRACT.md](./MODULE_INTERNAL_CONTRACT.md)
+- [../STARTER_PACK.md](../STARTER_PACK.md)

package/template/docs/architecture/REPO_ARTIFACT_LAYOUT.md

@@ -0,0 +1,76 @@
+# Repository artifact layout
+
+Canonical paths for runtime data, golden fixtures, and human↔agent exchange.
+
+## Roots
+
+| Root | Env override | Writable at runtime |
+|------|----------------|---------------------|
+| `data/case-filing-ai/batches/` | `CASE_FILING_BATCH_DIR` | Yes (pipeline) |
+| `evals/golden/{caseId}/` | `GOLDEN_DATASET_DIR` | No (fixtures) |
+| `data/court-rules/fixtures/` | — | No |
+| `eval-bundles/` | `EVAL_BUNDLE_ROOT_DIR` | Yes (export API) |
+| `case-exports/` | `CASE_EXPORT_ROOT_DIR` | Yes (export API) |
+| `file-exchange/imports\|exports/` | — | Yes (human triage) |
+| `work-log/dev-logs/human\|agent/` | — | Yes (pre-push audit) |
+| `models/consolidated-*.json` | — | Yes (condenser mirror) |
+| `work-log/` | — | Yes (docs only) |
+
+## Batch folder (`batches/batch-NNN/`)
+
+```text
+uploads/
+parsed-documents/doc-NNN/    # v2+ parsed cache
+outputs/doc-NNN.json
+evals/doc_NNN.eval-report.json
+rule/
+case-snapshot.json
+processing-log.jsonl
+```
+
+## Golden (`evals/golden/case_001/`)
+
+```text
+case_001.golden-dataset.json
+doc_NNN.expected.json
+parsed/doc-NNN/              # optional parse golden (v2)
+```
+
+## File exchange
+
+Imports: `file-exchange/imports/{2026-05-23_15-59-43Z}/`  
+Session exports: `file-exchange/exports/{stamp}/`  
+Consolidated snapshots: `file-exchange/exports/consolidated-*.json`
+
+See [file-exchange/README.md](../../file-exchange/README.md) and [contracts/fileExchange.contract.md](./contracts/fileExchange.contract.md).
+
+## Pre-push dev logs
+
+```text
+work-log/dev-logs/human/{NNN}_{date}_{time}_dev-log_{slug}.md
+work-log/dev-logs/agent/{NNN}_{date}_{time}_dev-log-agent_{slug}.json
+```
+
+`npm run dev-log:pre-push` — see [contracts/prePushDevLog.contract.md](./contracts/prePushDevLog.contract.md).
+
+## Consolidated exports
+
+`npm run condense:all` → [contracts/consolidatedExports.contract.md](./contracts/consolidatedExports.contract.md).
+
+## Contracts
+
+**Overview (start here):** [CONTRACTS_OVERVIEW.md](./CONTRACTS_OVERVIEW.md)  
+Manifest: [contracts/manifest.json](./contracts/manifest.json) · Changelog: [contracts/changelog.jsonl](./contracts/changelog.jsonl)
+
+| Contract | Doc |
+|----------|-----|
+| File exchange | [fileExchange.contract.md](./contracts/fileExchange.contract.md) |
+| Consolidated exports | [consolidatedExports.contract.md](./contracts/consolidatedExports.contract.md) |
+| Pre-push dev log | [prePushDevLog.contract.md](./contracts/prePushDevLog.contract.md) |
+| API registry | [apiDocumentationRegistry.contract.md](./contracts/apiDocumentationRegistry.contract.md) |
+| Case filing storage | `backend/src/modules/case-filing-ai/contracts/storageLayout.contract.js` |
+| Parsed artifacts | `parsedDocumentArtifacts.contract.js` |
+| Pipeline versions | `pipelineVersions.js` |
+| Rule authority | `court-rules/contracts/ruleAuthority.contract.js` |
+
+Human storage doc: [docs/case-filing-ai/STORAGE.md](../case-filing-ai/STORAGE.md)

package/template/docs/architecture/contracts/apiDocumentationRegistry.contract.md

@@ -0,0 +1,40 @@
+# Contract: API documentation registry
+
+**Version:** `v001`  
+**Registry:** [docs/API.md](../../API.md)  
+**Lint:** `npm run lint:api-docs` (`scripts/check-api-docs.mjs`)  
+**Dev-log inventory:** `scripts/lib/api-inventory.mjs`
+
+## Purpose
+
+Single **endpoint registry** for all mounted Express routes. Pre-push dev logs and agents read this for active / stub / deprecated HTTP surfaces.
+
+## Registry sections (docs/API.md)
+
+| Section | Use |
+|---------|-----|
+| **Endpoint registry** | Method, full path, module, description |
+| **Module index** | Active vs stub modules |
+
+## Route classification (dev-log / agents)
+
+| Class | Rule |
+|-------|------|
+| **active** | Documented route, not stub/deprecated in description |
+| **stub** | Description contains `stub` or `health only` |
+| **deprecated** | Description contains `deprecated` |
+
+Do not remove deprecated rows from the registry until the route is removed from code ([API_DOCUMENTATION_CONTRACT.md](../API_DOCUMENTATION_CONTRACT.md)).
+
+## Versioned surfaces (not HTTP)
+
+Captured in dev-log `apis.versioned` from:
+
+- `backend/src/modules/case-filing-ai/contracts/pipelineVersions.js`
+- `backend/src/modules/case-filing-ai/prompts/promptVersions.js`
+- `MASTER_PROMPT_VERSION` env (`v1` \| `compact` \| `v2` \| `v001`)
+
+## Related
+
+- [API_DOCUMENTATION_CONTRACT.md](../API_DOCUMENTATION_CONTRACT.md)
+- [prePushDevLog.contract.md](./prePushDevLog.contract.md)

package/template/docs/architecture/contracts/changelog.jsonl

@@ -0,0 +1,12 @@
+{"time":"2026-05-23T15:45:00Z","contract":"repoArtifactLayout","from":null,"to":"v001","reason":"Initial REPO_ARTIFACT_LAYOUT and file-exchange","author":"agent"}
+{"time":"2026-05-23T15:45:00Z","contract":"fileExchange","from":null,"to":"v001","reason":"file-exchange/ imports and exports dated folders","author":"agent"}
+{"time":"2026-05-23T15:46:00Z","contract":"caseFilingStorageLayout","from":null,"to":"v001","reason":"storageLayout.contract.js and storagePaths.js","author":"agent"}
+{"time":"2026-05-23T15:46:00Z","contract":"parsedDocumentArtifacts","from":null,"to":"v001","reason":"parsed-documents artifact names and audit events","author":"agent"}
+{"time":"2026-05-23T17:00:00Z","contract":"pipelineVersions","from":"case_001-v0-wiped","to":"case_001-v1-parsed-synthetic","reason":"Ingested synthetic golden parsed baseline (14 docs)","author":"agent"}
+{"time":"2026-05-23T17:00:00Z","contract":"ruleAuthority","from":null,"to":"v001","reason":"Court rules services and authority rank enum","author":"agent"}
+{"time":"2026-05-23T18:00:00Z","contract":"pipelineVersions","from":"case_001-v1-parsed-synthetic","to":"case_001-v2-full-expected","reason":"Ingested full doc/snapshot golden from bundle ground_truth.json","author":"agent"}
+{"time":"2026-05-23T19:00:00Z","contract":"fileExchange","from":"v001","to":"v001","reason":"AGENTS.md + alwaysApply file-exchange-inbox rule; import:file-exchange script","author":"agent"}
+{"time":"2026-05-23T20:00:00Z","contract":"consolidatedExports","from":null,"to":"v001","reason":"file-exchange/exports consolidated-*.json + models/ mirror; condense:all","author":"agent"}
+{"time":"2026-05-23T20:00:00Z","contract":"prePushDevLog","from":null,"to":"v001","reason":"Paired human MD + agent JSON pre-push logs; API/tree/test audits","author":"agent"}
+{"time":"2026-05-23T20:00:00Z","contract":"apiDocumentationRegistry","from":null,"to":"v001","reason":"docs/API.md registry contract for dev-log api inventory","author":"agent"}
+{"time":"2026-05-23T20:01:00Z","contract":"fileExchange","from":"v001","to":"v001","reason":"Human-readable stamps; consolidated exports at exports root; contract doc","author":"agent"}

package/template/docs/architecture/contracts/consolidatedExports.contract.md

@@ -0,0 +1,58 @@
+# Contract: consolidated exports
+
+**Version:** `v001`  
+**Code:** `backend/src/shared/contracts/consolidatedExports.contract.js`
+
+## Purpose
+
+Regenerable **repo snapshots** for human handoff and agent onboarding — not runtime filing data.
+
+## Primary paths (handoff)
+
+```text
+file-exchange/exports/
+  consolidated-models.json
+  consolidated-prompts.json
+  consolidated-file-structure.json
+```
+
+## Mirror paths (API / git)
+
+```text
+models/
+  consolidated-models.json      ← model-condenser API writes here first
+  consolidated-prompts.json
+  consolidated-file-structure.json
+```
+
+Every condense run writes **both** export and mirror.
+
+## Commands
+
+```bash
+npm run condense:all
+npm run condense-prompts
+npm run condense-file-structure
+npm --prefix backend run condense-models   # or POST /api/model-condenser/condense
+```
+
+## Contents
+
+| File | Source |
+|------|--------|
+| `consolidated-models.json` | Model condenser — schema inventory |
+| `consolidated-prompts.json` | All `.prompt.md` / `.prompt.js` + manifests |
+| `consolidated-file-structure.json` | Full file tree (tree ignore rules) |
+
+## File tree ignore (consolidated-file-structure)
+
+Same as pre-push dev log: `node_modules`, `.git`, `dist`, `build`.
+
+## Deprecated
+
+- `scripts/export-consolidated-models.mjs` → use `npm run condense-models` or `POST /api/model-condenser/condense`
+
+## Related
+
+- [file-exchange/README.md](../../../file-exchange/README.md)
+- [docs/model-condenser/API.md](../../model-condenser/API.md)

package/template/docs/architecture/contracts/fileExchange.contract.md

@@ -0,0 +1,47 @@
+# Contract: file exchange
+
+**Version:** `v001`  
+**Timestamp helper:** `backend/src/shared/utils/formatExchangeTimestamp.js`  
+**User doc:** [file-exchange/README.md](../../../file-exchange/README.md)
+
+## Layout
+
+```text
+file-exchange/
+  imports/{stamp}/     ← inbound bundles (mandatory before processing)
+  exports/{stamp}/     ← session deliverables (batch runs, curl logs)
+  exports/consolidated-*.json   ← see consolidatedExports contract
+```
+
+## Stamp format (human-readable UTC)
+
+```text
+YYYY-MM-DD_HH-MM-SSZ
+```
+
+Example: `2026-05-23_15-59-43Z`
+
+Legacy compact stamps (`20260523T155943Z`) are normalized by `normalizeExchangeStamp()` in the timestamp helper.
+
+## Mandatory workflow (agents)
+
+1. `npm run import:file-exchange -- "<path>"`
+2. Process only from `imports/{stamp}/`
+3. Copy deliverables to `exports/{stamp}/`
+4. `npm run condense:all` when refreshing consolidated snapshots
+
+Enforced by `AGENTS.md` and `.cursor/rules/file-exchange-inbox.mdc` (`alwaysApply: true`).
+
+## Scripts
+
+| Script | Purpose |
+|--------|---------|
+| `scripts/import-to-file-exchange.mjs` | Copy bundle → `imports/{stamp}/` |
+| `scripts/resolve-import-stamp.mjs` | Resolve human or legacy stamp folder |
+| `scripts/ingest-golden-parsed.mjs` | Parsed cache → `evals/golden/` |
+| `scripts/ingest-golden-expected.mjs` | Ground truth → `doc_NNN.expected.json` |
+
+## Related contracts
+
+- [consolidatedExports.contract.md](./consolidatedExports.contract.md)
+- [prePushDevLog.contract.md](./prePushDevLog.contract.md)

package/template/docs/architecture/contracts/manifest.json

@@ -0,0 +1,56 @@
+{
+  "repoArtifactLayout": {
+    "version": "v001",
+    "doc": "docs/architecture/REPO_ARTIFACT_LAYOUT.md",
+    "overview": "docs/architecture/CONTRACTS_OVERVIEW.md"
+  },
+  "fileExchange": {
+    "version": "v001",
+    "doc": "docs/architecture/contracts/fileExchange.contract.md",
+    "userDoc": "file-exchange/README.md",
+    "timestampHelper": "backend/src/shared/utils/formatExchangeTimestamp.js",
+    "importScript": "scripts/import-to-file-exchange.mjs"
+  },
+  "consolidatedExports": {
+    "version": "v001",
+    "doc": "docs/architecture/contracts/consolidatedExports.contract.md",
+    "file": "backend/src/shared/contracts/consolidatedExports.contract.js",
+    "utility": "backend/src/shared/utils/consolidatedExport.js"
+  },
+  "prePushDevLog": {
+    "version": "v001",
+    "doc": "docs/architecture/contracts/prePushDevLog.contract.md",
+    "file": "backend/src/shared/contracts/prePushDevLog.contract.js",
+    "schema": "work-log/dev-logs/schemas/dev-log-agent.v1.schema.json",
+    "generator": "scripts/write-pre-push-dev-log.mjs",
+    "humanFormat": "scripts/lib/dev-log-human-format.mjs",
+    "verify": "scripts/verify-dev-log.mjs",
+    "apiInventory": "scripts/lib/api-inventory.mjs",
+    "repoTree": "scripts/lib/repo-tree.mjs",
+    "workLogReadme": "work-log/dev-logs/README.md"
+  },
+  "apiDocumentationRegistry": {
+    "version": "v001",
+    "doc": "docs/architecture/contracts/apiDocumentationRegistry.contract.md",
+    "registry": "docs/API.md",
+    "lintScript": "scripts/check-api-docs.mjs",
+    "architectureDoc": "docs/architecture/API_DOCUMENTATION_CONTRACT.md"
+  },
+  "caseFilingStorageLayout": {
+    "version": "v001",
+    "file": "backend/src/modules/case-filing-ai/contracts/storageLayout.contract.js"
+  },
+  "parsedDocumentArtifacts": {
+    "version": "v001",
+    "file": "backend/src/modules/case-filing-ai/contracts/parsedDocumentArtifacts.contract.js"
+  },
+  "pipelineVersions": {
+    "version": "v001",
+    "file": "backend/src/modules/case-filing-ai/contracts/pipelineVersions.js",
+    "promptVersions": "backend/src/modules/case-filing-ai/prompts/promptVersions.js"
+  },
+  "ruleAuthority": {
+    "version": "v001",
+    "file": "backend/src/modules/court-rules/contracts/ruleAuthority.contract.js"
+  }
+}

package/template/docs/architecture/contracts/prePushDevLog.contract.md

@@ -0,0 +1,69 @@
+# Contract: pre-push dev log
+
+**Version:** `v001`  
+**Code:** `backend/src/shared/contracts/prePushDevLog.contract.js`  
+**Agent schema:** `work-log/dev-logs/schemas/dev-log-agent.v1.schema.json` (`1.0.0`)
+
+## Purpose
+
+Before each git push, produce a **paired audit**:
+
+| Audience | Path | Format |
+|----------|------|--------|
+| Human | `work-log/dev-logs/human/` | Markdown — Part I summary + Part II detail |
+| Agent | `work-log/dev-logs/agent/` | JSON — machine-readable audit |
+
+## Commands
+
+```bash
+npm run dev-log:pre-push -- --slug <kebab-topic> [--program 005] [--no-tests]
+npm run dev-log:verify
+npm run dev-log:pre-push -- --check   # requires git + agent log for HEAD
+```
+
+## Human log structure (Part I + Part II)
+
+**Part I — Summary** (auto-filled):
+
+- Table of contents with anchor links
+- Mermaid: HTTP modules, pipeline versions, pre-push flow
+- Audit tables: API surface, version/prompt contracts, tests, git, repo shape
+- Condensed repository tree (link to full tree in Part II)
+
+**Part II — Detailed** (fill):
+
+- Goals, decisions, changes, iterations, outcomes, follow-ups
+- Full HTTP registry from `docs/API.md`
+- Full git porcelain + diff stat
+- Full repository tree
+
+Generator: `scripts/lib/dev-log-human-format.mjs`
+
+## Agent log (required fields)
+
+- `meta`, `summary`, `apis`, `git`, `tests`, `repositoryTree`
+- `changes`, `decisions[]`, `iterations[]`
+- `tradeoffs`, `improvements`, `regressions`, `risks`, `followUps`
+
+`apis` is built by `scripts/lib/api-inventory.mjs` from `docs/API.md` + `pipelineVersions.js` + `promptVersions.js`.
+
+## Repository tree rules
+
+Equivalent to:
+
+```bash
+tree -I "node_modules|.git|dist|build"
+```
+
+Implemented in `scripts/lib/repo-tree.mjs`. `.DS_Store` files also excluded.
+
+## Git
+
+- Works **without** git (fields show `unknown` until `git init`)
+- After git init: branch, SHA, porcelain, diff stat populate automatically
+
+## Related
+
+- [work-log/dev-logs/README.md](../../../work-log/dev-logs/README.md)
+- [AGENTS.md](../../../AGENTS.md) — pre-push section
+- `.cursor/commands/pre-push-dev-log.md`

package/template/docs/model-condenser/API.md

@@ -0,0 +1,102 @@
+# Model condenser — HTTP API
+
+**Base path:** `/api/model-condenser`
+
+Scans the repo and writes a **schema inventory** (`models/consolidated-models.json`). This is unrelated to case eval reports or `eval-bundles/`.
+
+**Routes:** [`backend/src/modules/model-condenser/routes/modelCondenser.routes.js`](../../backend/src/modules/model-condenser/routes/modelCondenser.routes.js)
+
+**Contract:** [API documentation contract](../architecture/API_DOCUMENTATION_CONTRACT.md)
+
+---
+
+## Endpoint quick reference
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/health` | Module health |
+| POST | `/condense` | Regenerate consolidated-models.json |
+| GET | `/consolidated` | Read consolidated schema inventory |
+
+---
+
+## Health
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/health` | Module health |
+
+---
+
+## Condense
+
+### `POST /condense`
+
+Regenerate `models/consolidated-models.json` from repo sources.
+
+**Body (JSON, optional):**
+
+```json
+{ "includePayload": false }
+```
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| `includePayload` | `false` | If `true`, include full consolidated document in response |
+
+**Response 201:**
+
+```json
+{
+  "status": "written",
+  "outputPath": "/abs/path/models/consolidated-models.json",
+  "outputRelativePath": "models/consolidated-models.json",
+  "modelCount": 42,
+  "exampleInstanceCount": 10,
+  "generatedAt": "2026-05-23T..."
+}
+```
+
+**CLI equivalent:** `npm run condense-models` (from `backend/`)
+
+---
+
+## Read consolidated file
+
+### `GET /consolidated`
+
+**Query:**
+
+| Param | Description |
+|-------|-------------|
+| `includePayload=true` | Return full `consolidated` object in addition to summary |
+
+**Response 200 (summary):**
+
+```json
+{
+  "status": "ready | missing",
+  "exists": true,
+  "outputPath": "...",
+  "outputRelativePath": "models/consolidated-models.json",
+  "generatedAt": "...",
+  "modelCount": 42
+}
+```
+
+**404** if file missing — run `POST /condense` first.
+
+---
+
+## Environment variables
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `MODEL_CONDENSER_OUTPUT_DIR` | `{repo}/models` | Output directory |
+| `MODEL_CONDENSER_OUTPUT_FILE` | `consolidated-models.json` | Output filename |
+
+---
+
+## Tests
+
+`backend/src/modules/model-condenser/tests/integration/modelCondenser.routes.test.js`