@pukujan/create-modular-monolith 2.0.0 → 2.1.0

package/README.md

@@ -1,43 +1,112 @@
 # @pukujan/create-modular-monolith
 
-CLI for a **scalable modular monolith** starter: feature modules with strict boundaries, internal MVC layers, prompts, evals, tests, and automated architecture lint. Domain-agnostic — use it for any platform that should grow without rewrite.
-
-## Create a project
+**npm create** scaffold for a modular monolith built for **human + agent** engineering at scale.
 
 ```bash
 npm create @pukujan/modular-monolith@2 my-platform
 cd my-platform
-cd backend && npm install && cd ../frontend && npm install
+npm install --prefix backend && npm install --prefix frontend
 ```
 
-Options:
+Published package: `@pukujan/create-modular-monolith`  
+Product reference implementation: [litigation-prompt-engineering](https://github.com/Pukujan/litigation-prompt-engineering)
 
-```bash
-npm create @pukujan/modular-monolith@2 my-platform -- --install --git
+---
+
+## What you get
+
+This is **not** a minimal Express/React demo. It is an **architecture platform**:
+
+| Layer | Purpose |
+|-------|---------|
+| **Module contract** | Backend `register(app)` + frontend route modules — add features without rewriting core |
+| **Architecture contracts** | Versioned manifest (`docs/architecture/contracts/`) — paths, APIs, exports, dev logs |
+| **File exchange** | Dated `imports/` / `exports/` for human↔agent file handoff |
+| **Pre-push dev logs** | Paired **human markdown** (summary + detail, mermaid, TOC) + **agent JSON** audit |
+| **Consolidated snapshots** | `condense:all` → models, prompts, file tree in `file-exchange/exports/` |
+| **Lint automation** | Boundaries, layers, contracts, repo artifacts, API registry |
+| **Cursor-native** | `AGENTS.md`, `.cursor/rules`, `.cursor/commands` for repeatable agent workflows |
+
+Domain business logic is **yours to add** via `npm run new:module`. The repo ships with `_reference` and `model-condenser` only.
+
+---
+
+## Why this architecture exists
+
+Modern products are built as much by **agents** as by humans. This template encodes:
+
+1. **Discoverability** — Agents read JSON audits and contract manifests instead of guessing folder layout.
+2. **Repeatability** — Every push can produce the same artifact set (dev log pair, tree, API inventory, test results).
+3. **Scale** — New modules plug in under `backend/src/modules/` and `frontend/src/modules/` with enforced boundaries.
+4. **Governance** — `lint:contracts` fails CI if a contract path is missing; `lint:api-docs` keeps routes documented.
+
+Read **`template/docs/architecture/PLATFORM_ARCHITECTURE.md`** (in this repo) for the full narrative. After scaffold, start at **`docs/architecture/CONTRACTS_OVERVIEW.md`** in your project.
+
+---
+
+## Repository layout (this GitHub repo)
+
+```text
+create-modular-monolith/
+  README.md              ← you are here (npm package docs)
+  package.json           ← @pukujan/create-modular-monolith
+  index.js               ← copies template/ into target directory
+  template/              ← full starter app (architecture only)
 ```
 
-| Flag | Effect |
-| --- | --- |
-| `--install` | Run `npm install` in backend and frontend |
-| `--git` | `git init` and initial commit |
+---
 
-## What you get
+## Architecture scripts (in every scaffolded project)
+
+These live under `template/scripts/` and are copied into new projects:
+
+| Script | npm command | Role |
+|--------|-------------|------|
+| `lint-contracts.mjs` | `npm run lint:contracts` | Verify `manifest.json` paths exist |
+| `lint-repo-artifacts.mjs` | `npm run lint:repo-artifacts` | Verify exchange, dev-log, contract docs |
+| `check-api-docs.mjs` | `npm run lint:api-docs` | Routes ⊆ `docs/API.md` registry |
+| `write-pre-push-dev-log.mjs` | `npm run dev-log:pre-push` | Human + agent pre-push audit pair |
+| `verify-dev-log.mjs` | `npm run dev-log:verify` | Validate latest dev-log structure |
+| `condense-file-structure.mjs` | `npm run condense-file-structure` | Repo tree → `exports/consolidated-file-structure.json` |
+| `condense-prompts.mjs` | `npm run condense-prompts` | All prompts → consolidated JSON |
+| `import-to-file-exchange.mjs` | `npm run import:file-exchange` | Inbound bundles → `imports/{stamp}/` |
+| `new-module.mjs` | `npm run new:module` | Scaffold backend + frontend module |
+
+Supporting libraries: `scripts/lib/repo-tree.mjs`, `api-inventory.mjs`, `dev-log-human-format.mjs`, `git-snapshot.mjs`, `run-tests.mjs`.
+
+---
+
+## Contract catalog (v001)
 
-- **Modular monolith** — auto-loaded backend modules + frontend route discovery
-- **Internal contract** — routes → services → repositories / domain / adapters
-- **AI-ready** — versioned `prompts/` and `evals/` per feature module
-- **Lint** — cross-module boundaries + layer direction (`lint:architecture`)
+Registered in `template/docs/architecture/contracts/manifest.json`:
 
-## Publish (maintainers)
+- **fileExchange** — dated imports/exports, human-readable stamps
+- **consolidatedExports** — snapshot JSON in `file-exchange/exports/`
+- **prePushDevLog** — paired human MD + agent JSON before push
+- **apiDocumentationRegistry** — `docs/API.md` as HTTP source of truth
+- **repoArtifactLayout** — canonical data roots
 
-From repo root on branch `v2`:
+Module-level contracts (storage layout, pipeline versions) are added when you build domain modules.
+
+---
+
+## Publishing this package
 
 ```bash
-npm run sync:cli-template
-cd packages/create-modular-monolith
+cd packages/create-modular-monolith   # or repo root if package.json is here
+npm version patch|minor|major
 npm publish --access public
 ```
 
-## Source
+Users install with:
+
+```bash
+npm create @pukujan/modular-monolith@2 <folder-name>
+```
+
+---
+
+## Version
 
-[litigation-workflow-application](https://github.com/Pukujan/litigation-workflow-application) branch `v2` (originated for legal workflows; architecture is industry-agnostic).
+Package version tracks **architecture platform** releases (contracts, agent tooling, template layout).  
+See `package.json` and git tags. Domain app code lives in separate product repos.

package/index.js

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+/**
+ * npm create @pukujan/modular-monolith
+ * Copies template/ into the target directory.
+ */
+import { cpSync, existsSync, mkdirSync } from "fs";
+import { join, resolve } from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = fileURLToPath(new URL(".", import.meta.url));
+const templateDir = join(__dirname, "template");
+
+const targetArg = process.argv[2];
+if (!targetArg || targetArg === "--help" || targetArg === "-h") {
+  console.log(`
+Usage: npm create @pukujan/modular-monolith@2 <project-directory>
+
+Scaffolds a modular monolith with architecture contracts, file-exchange,
+pre-push dev logs (human + agent), and consolidated export tooling.
+
+Docs: https://github.com/Pukujan/create-modular-monolith
+`);
+  process.exit(targetArg ? 0 : 1);
+}
+
+const target = resolve(process.cwd(), targetArg);
+
+if (existsSync(target) && existsSync(join(target, "package.json"))) {
+  console.error(`Target already exists and looks like a project: ${target}`);
+  process.exit(1);
+}
+
+mkdirSync(target, { recursive: true });
+cpSync(templateDir, target, { recursive: true });
+
+console.log(`
+Created modular monolith at ${target}
+
+Next steps:
+  cd ${targetArg}
+  npm install --prefix backend
+  npm install --prefix frontend
+  npm run lint:contracts
+
+Read docs/architecture/PLATFORM_ARCHITECTURE.md and AGENTS.md before adding modules.
+`);
+console.log(`  npm run new:module -- my-feature --label "My Feature"\n`);

package/package.json

@@ -1,39 +1,36 @@
 {
   "name": "@pukujan/create-modular-monolith",
-  "version": "2.0.0",
-  "description": "Scaffold a scalable modular monolith: strict module boundaries, MVC layers, prompts, evals, and architecture lint",
+  "version": "2.1.0",
+  "description": "Scaffold a modular monolith with architecture contracts, file-exchange, agent dev logs, and lint automation for Cursor-scale engineering.",
   "type": "module",
   "bin": {
-    "create-modular-monolith": "bin/create-modular-monolith.js"
+    "create-modular-monolith": "index.js"
   },
   "files": [
-    "bin",
+    "index.js",
     "template"
   ],
-  "engines": {
-    "node": ">=18"
-  },
   "keywords": [
     "modular-monolith",
-    "monolith",
+    "express",
+    "react",
+    "vite",
+    "cursor",
     "architecture",
     "scaffold",
-    "create-app",
-    "platform",
-    "microservices-ready",
-    "legal-tech"
+    "create-app"
   ],
+  "author": "Pukujan",
   "license": "MIT",
-  "publishConfig": {
-    "access": "public"
-  },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/Pukujan/litigation-workflow-application.git",
-    "directory": "packages/create-modular-monolith"
+    "url": "git+https://github.com/Pukujan/create-modular-monolith.git"
   },
   "bugs": {
-    "url": "https://github.com/Pukujan/litigation-workflow-application/issues"
+    "url": "https://github.com/Pukujan/create-modular-monolith/issues"
   },
-  "homepage": "https://github.com/Pukujan/litigation-workflow-application#readme"
+  "homepage": "https://github.com/Pukujan/create-modular-monolith#readme",
+  "engines": {
+    "node": ">=20"
+  }
 }

package/template/.cursor/commands/planning-study-log.md

@@ -0,0 +1,25 @@
+# Planning study log
+
+Append a **planning-only** study log entry under `work-log/study-docs/`.
+
+## Rules
+
+1. **No sensitive content** — fixtures, APIs, folder layout, architecture only. No party names or filing text.
+2. **User messages** — verbatim in blockquotes under `### {UTC} · You`.
+3. **Assistant** — short bullet summary under `### {UTC} · Cursor`.
+4. **Filename** — `work-log/study-docs/{NNN}_{YYYY-MM-DD}_{HH-MM}_study-log_{slug}.md` using UTC from `formatWorkLogTimestamp` in `backend/src/shared/utils/formatExchangeTimestamp.js`.
+5. **Append vs new file** — append to the latest log for the same program id if under ~400 lines; otherwise create a new file with `Continues from: [previous](./previous.md)`.
+6. **Index** — add a row to `work-log/INDEX.md` when creating a new file.
+7. **Scope** — default planning-only unless the user says to include implementation.
+
+## Steps
+
+1. Read the current conversation turns since the last logged entry (or the whole session if new).
+2. Determine program id (e.g. `006`) and slug from the topic.
+3. Write or append turns with ISO-8601 UTC timestamps per turn.
+4. Confirm the file path in your reply.
+
+## Optional tags on user turns
+
+- `Program` — pipeline / feature scope (v2)
+- `Architecture` — layout / contracts (v3)

package/template/.cursor/commands/pre-push-dev-log.md

@@ -0,0 +1,52 @@
+# Pre-push dev log (human + agent audit)
+
+Create **two** dev logs before every push: one for humans, one structured JSON for agents.
+
+## When to run
+
+- Before `git push` (or when the user asks to “write dev log” / “pre-push log”).
+- After a meaningful slice of work — same session as the push.
+
+## Steps
+
+1. **Generate skeletons** (auto-fills git, tests, full repo tree):
+   ```bash
+   npm run dev-log:pre-push -- --slug <kebab-topic> --program 005
+   ```
+   Use `--no-tests` only if tests were already run and recorded manually.
+   Use `--title "Readable title"` if the slug is too terse.
+
+2. **Fill the agent log first** (`work-log/dev-logs/agent/*_dev-log-agent_*.json`):
+   - Replace every `FILL` string with concrete facts.
+   - `decisions[]` — id, decision, rationale, alternativesRejected, tradeoff.
+   - `iterations[]` — each attempt in order.
+   - `changes.narrative`, `improvements`, `tradeoffs`, `regressions`, `risks`, `followUps`.
+   - `summary` — dense paragraph an agent can scan in one pass.
+   - Keep `apis`, `repositoryTree.treeText`, and `git` as-is unless stale; update `apis` if you added/deprecated routes.
+   - `apis.http` = active / stub / deprecated; `apis.versioned` = pipeline + prompt versions.
+
+3. **Fill the human log** (`work-log/dev-logs/human/*_dev-log_*.md`):
+   - **Part I (top):** fill **I.1 At a glance** only; leave auto audit tables and mermaid as-is unless APIs changed.
+   - **Part II (bottom):** decisions, iterations, changes, outcomes — mirror the agent JSON in prose.
+   - Do **not** remove Part I audit tables, mermaid blocks, or Part II full tree/git sections.
+
+4. **Index** — add two rows to `work-log/INDEX.md` (human + agent).
+
+5. **Verify** (optional):
+   ```bash
+   npm run dev-log:pre-push -- --check
+   ```
+
+## Rules
+
+- **No secrets** — no `.env` values, API keys, or real party/filing text.
+- **Pair required** — every human log must have a sibling agent JSON with the same `{NNN}_{date}_{time}` prefix.
+- **Agent log is the audit source of truth** for the next session; human log is the readable narrative.
+- Schema: `work-log/dev-logs/schemas/dev-log-agent.v1.schema.json`
+
+## Filename convention
+
+| Audience | Path | Pattern |
+|----------|------|---------|
+| Human | `work-log/dev-logs/human/` | `{NNN}_{YYYY-MM-DD}_{HH-MM}_dev-log_{slug}.md` |
+| Agent | `work-log/dev-logs/agent/` | `{NNN}_{YYYY-MM-DD}_{HH-MM}_dev-log-agent_{slug}.json` |

package/template/.cursor/rules/api-documentation.mdc

@@ -0,0 +1,21 @@
+---
+description: Document every new HTTP route in module API.md and docs/API.md registry
+globs: backend/src/modules/**/routes/**/*.js,backend/src/modules/**/index.js,docs/**/API.md,docs/API.md
+alwaysApply: false
+---
+
+# API documentation contract
+
+When you add or change an Express route under `backend/src/modules/<module>/routes/`:
+
+1. **Append** to `docs/<module>/API.md`:
+   - `## Endpoint quick reference` table: Method | Path | Description
+   - Detailed `### \`METHOD /path\`` section if non-trivial
+2. **Append** to `docs/API.md` → `## Endpoint registry`:
+   - Full path `/api/<module-id>/...`, module label, short description
+3. Run `npm run lint:api-docs` and fix failures before finishing.
+
+Path in module doc = route relative to base (`/health`, not `/api/module/health`).
+Registry path = full path including `/api/<module-id>`.
+
+Read [docs/architecture/API_DOCUMENTATION_CONTRACT.md](docs/architecture/API_DOCUMENTATION_CONTRACT.md) for the full checklist.

package/template/.cursor/rules/file-exchange-inbox.mdc

@@ -0,0 +1,29 @@
+---
+description: Mandatory file-exchange inbox before processing inbound bundles or PDFs
+alwaysApply: true
+---
+
+# File exchange inbox (mandatory)
+
+**Always apply** when the user provides files, bundles, PDFs, golden datasets, or asks to run `process-batch`, ingest golden, or import from Downloads.
+
+## Before any processing
+
+1. Run **`npm run import:file-exchange -- "<source-path>"`** unless files are already under `file-exchange/imports/{UTC-stamp}/`.
+2. Use **`formatExchangeTimestamp()`** from `backend/src/shared/utils/formatExchangeTimestamp.js` for the folder name — never ad-hoc slug folders.
+3. Record the stamp in your reply (e.g. `imports/2026-05-23_15-59-43Z/`) so exports can use a matching `exports/{stamp}/`.
+
+## Then
+
+- Ingest golden from that stamp: `npm run ingest:golden-parsed`, `npm run ingest:golden-expected`.
+- Point `process-batch` / `curl` uploads at PDFs **inside** `file-exchange/imports/{stamp}/`, not `Downloads/` or repo root.
+- Copy deliverables to `file-exchange/exports/{stamp}/` when done.
+- Consolidated repo snapshots: `file-exchange/exports/consolidated-*.json` (`npm run condense:all`).
+
+## Do not
+
+- Skip import to save time.
+- Process from `~/Downloads/...` directly.
+- Create `imports/synthetic-case-001-.../` without a UTC stamp.
+
+See [AGENTS.md](../../AGENTS.md), [file-exchange/README.md](../../file-exchange/README.md), and [REPO_ARTIFACT_LAYOUT.md](../../docs/architecture/REPO_ARTIFACT_LAYOUT.md).

package/template/AGENTS.md

@@ -0,0 +1,41 @@
+# Agent instructions (Cursor / automation)
+
+Repo-wide rules for AI agents. Module-specific rules live under `.cursor/rules/`.
+
+## Mandatory: file-exchange before processing inbound files
+
+Copy user bundles into a dated import folder before processing:
+
+```bash
+npm run import:file-exchange -- "/path/to/bundle"
+```
+
+Stamp format: `2026-05-23_15-59-43Z` via `formatExchangeTimestamp` in `backend/src/shared/utils/formatExchangeTimestamp.js`.
+
+Deliverables → `file-exchange/exports/{stamp}/`. Consolidated snapshots → `file-exchange/exports/consolidated-*.json` (`npm run condense:all`).
+
+See [file-exchange/README.md](file-exchange/README.md) and [docs/architecture/CONTRACTS_OVERVIEW.md](docs/architecture/CONTRACTS_OVERVIEW.md).
+
+## Pre-push dev log
+
+Before each push:
+
+```bash
+npm run dev-log:pre-push -- --slug <topic>
+npm run dev-log:verify
+```
+
+Paired logs: `work-log/dev-logs/human/` + `work-log/dev-logs/agent/`. See `.cursor/commands/pre-push-dev-log.md`.
+
+## Architecture checks
+
+```bash
+npm run lint:architecture
+npm run lint:contracts
+npm run lint:repo-artifacts
+npm run lint:api-docs
+```
+
+## Work log
+
+Handoffs and dev-logs under `work-log/` per [work-log/README.md](work-log/README.md).

package/template/README.md

@@ -1,52 +1,12 @@
-# Modular Monolith Platform Starter (v2)
+# Modular monolith platform (scaffolded)
 
-A **scalable modular monolith** boilerplate: strict feature-module boundaries, internal MVC layers, prompts/evals for AI workflows, and automated architecture lint. Built for platforms that should grow toward services **without** a rewrite.
+Architecture-first Express + React starter for products that scale with **human + agent** engineering.
 
-Domain-agnostic — use it for legal tech, ops, marketplaces, or any multi-feature product. (This repo started as a litigation workflow; the architecture is not limited to that.)
+**Read first:** [docs/architecture/PLATFORM_ARCHITECTURE.md](docs/architecture/PLATFORM_ARCHITECTURE.md)  
+**Contracts:** [docs/architecture/CONTRACTS_OVERVIEW.md](docs/architecture/CONTRACTS_OVERVIEW.md)  
+**Agents:** [AGENTS.md](AGENTS.md)
 
-> **v1 (minimal)** — branch [`main`](https://github.com/Pukujan/litigation-workflow-application/tree/main). **v2 (platform)** — this branch + npm CLI.
-
-**Documentation:** [docs/README.md](./docs/README.md) · [DEVLOG v2](./docs/DEVLOG_V2.md) · [guardrails](./docs/architecture/ARCHITECTURE_GUARDRAILS.md) · [internal contract](./docs/architecture/MODULE_INTERNAL_CONTRACT.md)
-
-**Repository:** [github.com/Pukujan/litigation-workflow-application](https://github.com/Pukujan/litigation-workflow-application)
-
-## What is included
-
-- Backend module auto-loader + frontend route discovery
-- **Inter-module** guardrails (no cross-feature imports; event bus + HTTP)
-- **Intra-module** contract (routes → services → repositories / domain / adapters)
-- Prompts + evals colocated per feature module
-- `lint:architecture`, `npm test`, `npm run test:evals`
-- `_reference` example module (documentation only; not loaded at runtime)
-
-## Create a new project (npm CLI)
-
-```bash
-npm create @pukujan/modular-monolith@2 my-platform
-cd my-platform
-cd backend && npm install && cd ../frontend && npm install
-```
-
-Publish first: `@pukujan/create-modular-monolith` — see [docs/PUBLISHING.md](./docs/PUBLISHING.md).
-
-Local (without publish):
-
-```bash
-node packages/create-modular-monolith/bin/create-modular-monolith.js ../my-platform
-```
-
-## Repo structure
-
-```text
-modular-monolith-starter/
-├── backend/src/{core,shared,modules}/
-├── frontend/src/{core,shared,modules}/
-├── docs/architecture/
-├── scripts/new-module.mjs
-└── packages/create-modular-monolith/   # npm CLI
-```
-
-## Run locally (this repo)
+## Quick start
 
 ```bash
 cd backend && npm install && npm run dev
@@ -54,20 +14,21 @@ cd backend && npm install && npm run dev
 cd frontend && npm install && npm run dev
 ```
 
-## Create your first module
+## Architecture commands
 
 ```bash
-npm run new:module -- billing --label "Billing"
+npm run lint:contracts          # contract manifest paths
+npm run lint:architecture       # module boundaries + layers + API docs
+npm run import:file-exchange -- ./my-bundle
+npm run dev-log:pre-push -- --slug initial-setup
+npm run condense:all            # consolidated snapshots → file-exchange/exports/
+npm run new:module -- my-feature --label "My Feature"
 ```
 
-Restart backend; refresh frontend.
-
-## Architecture checks
+## What ships in this template
 
-```bash
-npm run lint:architecture
-npm test
-npm run test:evals
-```
+- `_reference` + `model-condenser` modules (no domain logic)
+- File exchange, work-log dev logs (human + agent), contract manifest v001
+- Lint and condense tooling for trees, prompts, and schemas
 
-See `backend/src/modules/_reference/` for the full internal layout.
+Built with [@pukujan/create-modular-monolith](https://github.com/Pukujan/create-modular-monolith).

package/template/backend/.env.example

@@ -0,0 +1,38 @@
+# Backend — copy to backend/.env
+PORT=3001
+
+# OpenRouter (https://openrouter.ai/keys)
+OPENROUTER_API_KEY=your_openrouter_api_key_here
+MODEL_TEXT_REASONING=google/gemini-2.0-flash-001
+MODEL_VISION_OCR=qwen/qwen2.5-vl-7b-instruct
+OPENROUTER_SITE_URL=http://localhost:5173
+OPENROUTER_APP_NAME=Case Filing AI
+
+# Optional batch storage override
+CASE_FILING_BATCH_DIR=
+CASE_FILING_MAX_UPLOAD_MB=25
+
+# Model condenser (optional output override)
+MODEL_CONDENSER_OUTPUT_DIR=
+MODEL_CONDENSER_OUTPUT_FILE=consolidated-models.json
+
+# Golden dataset eval (default: evals/golden/case_001)
+GOLDEN_DATASET_DIR=
+GOLDEN_CASE_ID=case_001
+
+# Eval report bundles copied to repo root (default: eval-bundles/)
+# Case bundle: eval-bundles/{name}/golden/ + runs/{batchId}/
+EVAL_BUNDLE_ROOT_DIR=
+
+# Full case export (uploads, outputs, evals, rules, snapshots)
+CASE_EXPORT_ROOT_DIR=
+
+# Master prompt (default v1 — same template as before)
+MASTER_PROMPT_VERSION=v1
+MASTER_PROMPT_JSON_RETRY=true
+MASTER_PROMPT_OMIT_AUDIT_NOTES=true
+MASTER_PROMPT_MAX_AUDIT_NOTES=20
+MASTER_PROMPT_MAX_DOC_CHARS=120000
+# compact or v2: compact prompt + structured snapshot merge
+# OPENROUTER_JSON_OBJECT_MODE=true
+OPENROUTER_JSON_OBJECT_MODE=false

package/template/backend/package.json

@@ -1,5 +1,5 @@
 {
-  "name": "modular-monolith-starter-backend",
+  "name": "legal-prmpt-eng-backend",
   "private": true,
   "version": "1.0.0",
   "type": "module",
@@ -8,13 +8,23 @@
     "start": "node src/core/server.js",
     "lint:boundaries": "node scripts/check-module-boundaries.mjs",
     "lint:layers": "node scripts/check-module-layers.mjs",
-    "lint:architecture": "npm run lint:boundaries && npm run lint:layers",
+    "lint:api-docs": "node ../scripts/check-api-docs.mjs",
+    "lint:architecture": "npm run lint:boundaries && npm run lint:layers && npm run lint:api-docs",
     "test": "node --test 'src/modules/**/tests/**/*.test.js'",
+    "condense-models": "node ../scripts/condense-models.mjs",
+    "condense-prompts": "node ../scripts/condense-prompts.mjs",
+    "condense-file-structure": "node ../scripts/condense-file-structure.mjs",
     "test:evals": "node ../scripts/run-module-evals.mjs"
   },
   "dependencies": {
+    "@napi-rs/canvas": "^1.0.0",
     "cors": "^2.8.5",
     "dotenv": "^16.4.5",
-    "express": "^4.19.2"
+    "express": "^4.19.2",
+    "mammoth": "^1.12.0",
+    "multer": "^2.1.1",
+    "pdf-parse": "^2.4.5",
+    "pdfjs-dist": "^4.10.38",
+    "word-extractor": "^1.0.4"
   }
-}
+}

package/template/backend/src/modules/model-condenser/README.md

@@ -0,0 +1,7 @@
+# Model condenser
+
+Scans the repo and writes `models/consolidated-models.json` (JSON schema inventory).
+
+**HTTP API:** [docs/model-condenser/API.md](../../../docs/model-condenser/API.md) · [All modules](../../../docs/API.md)
+
+**CLI:** `npm run condense-models` (from `backend/`)

package/template/backend/src/modules/model-condenser/config/index.js

@@ -0,0 +1,20 @@
+import { join } from "path";
+import { fileURLToPath } from "url";
+
+const repoRoot = join(fileURLToPath(new URL(".", import.meta.url)), "../../../../..");
+
+export function getModuleConfig() {
+  const modelsDir =
+    process.env.MODEL_CONDENSER_OUTPUT_DIR || join(repoRoot, "models");
+  return {
+    name: "model-condenser",
+    label: "Model Condenser",
+    repoRoot,
+    modelsDir,
+    consolidatedFileName:
+      process.env.MODEL_CONDENSER_OUTPUT_FILE || "consolidated-models.json"
+  };
+}
+
+/** @deprecated Prefer getModuleConfig() */
+export const moduleConfig = getModuleConfig();

package/template/backend/src/modules/model-condenser/events/index.js

@@ -0,0 +1 @@
+export function registerModuleEvents(_context) {}

package/template/backend/src/modules/model-condenser/index.js

@@ -0,0 +1,12 @@
+import { createModuleRouter } from "./routes/index.js";
+import { registerModuleEvents } from "./events/index.js";
+import { getModuleConfig } from "./config/index.js";
+import { createModelCondenserFacade } from "./services/modelCondenser.facade.js";
+
+export function register(app, context) {
+  const config = getModuleConfig();
+  const modelCondenser = createModelCondenserFacade({ config });
+  const router = createModuleRouter({ config, modelCondenser });
+  app.use("/api/model-condenser", router);
+  registerModuleEvents(context);
+}

package/template/backend/src/modules/model-condenser/routes/health.routes.js

@@ -0,0 +1,10 @@
+import { Router } from "express";
+import { getHealth } from "../services/health.service.js";
+
+export function createHealthRoutes({ config }) {
+  const router = Router();
+  router.get("/health", (_req, res) => {
+    res.json(getHealth(config));
+  });
+  return router;
+}

package/template/backend/src/modules/model-condenser/routes/index.js

@@ -0,0 +1,10 @@
+import { Router } from "express";
+import { createHealthRoutes } from "./health.routes.js";
+import { createModelCondenserRoutes } from "./modelCondenser.routes.js";
+
+export function createModuleRouter({ config, modelCondenser }) {
+  const router = Router();
+  router.use(createHealthRoutes({ config }));
+  router.use(createModelCondenserRoutes({ config, modelCondenser }));
+  return router;
+}