@archrad/deterministic 0.1.4 → 0.1.6

package/CHANGELOG.md

@@ -7,6 +7,38 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.1.6] - 2026-04-10
+
+### Added
+
+- **`docs/CI.md`** — exit code semantics (`--fail-on-warning`, `--max-warnings`) and copy-paste snippets for GitHub Actions, GitLab CI, Bitbucket Pipelines, Jenkins, and Azure DevOps.
+- **`scripts/generate-corpus.mjs`** — validates hand-written `corpus/*.json` pairs; `--count` mode generates weighted synthetic JSONL training pairs via the deterministic engine. Run `npm run build` first.
+- **Integration tests** — `archrad validate` exit code assertions (`src/cli-exit.integration.test.ts`).
+
+### Changed
+
+- **MCP** — Rewrote all six `registerTool` title/description blocks for agent discoverability (`src/mcp-server-tools-patch.ts`).
+- **npm package** — `corpus/` excluded from published tarball (`.npmignore` + removed from `package.json` `files`).
+
+### Fixed
+
+- **`archrad_validate_drift`** MCP schema: `target` enum is `python` | `nodejs` only, aligned with `docs/MCP.md`.
+
+### Security
+
+- `npm audit fix` applied to dev/test transitive dependencies.
+
+## [0.1.5] - 2026-04-07
+
+### Added
+
+- **`archrad-mcp`** — [Model Context Protocol](https://modelcontextprotocol.io/) server over **stdio** (same deterministic engine as the CLI). Tools: **`archrad_validate_ir`**, **`archrad_lint_summary`**, **`archrad_validate_drift`**, **`archrad_policy_packs_load`**, **`archrad_suggest_fix`** (static remediation per built-in code — **not** generated patches), **`archrad_list_rule_codes`**. IR input: inline **`ir`** or **`irPath`** (JSON file; max **25 MiB**). **`archrad_suggest_fix`** **`docsUrl`** → GitHub **`docs/RULE_CODES.md`**. Scope: **`docs/MCP.md`** (OSS: IR + local paths; no tracking params in tool responses).
+- **Docs:** **`docs/DRIFT.md`** (deterministic drift semantics), **`docs/RULE_CODES.md`** (built-in codes + anchors for MCP **`docsUrl`**), **`docs/MCP.md`** (local testing).
+
+### Fixed
+
+- **CodeQL** `js/polynomial-redos` — linear-time hyphen/underscore edge stripping for **`safeId`** / OpenAPI-derived ids (replaces ambiguous alternation regexes).
+
 ## [0.1.4] - 2026-04-06
 
 ### Added
@@ -103,8 +135,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Documented **codegen vs validation** for retry/timeout IR fields and **InkByte vs OSS** scope in README and structural/semantic doc.
 - README positioning: **deterministic compiler and linter for system architecture**; validation layers table (OSS vs Cloud); **`validate-drift`**, drift GIF / trust-loop recording docs, library **`runValidateDrift`** example.
 
-[Unreleased]: https://github.com/archradhq/arch-deterministic/compare/v0.1.3...HEAD
-[0.1.3]: https://github.com/archradhq/arch-deterministic/releases/tag/v0.1.3
-[0.1.2]: https://github.com/archradhq/arch-deterministic/releases/tag/v0.1.2
-[0.1.1]: https://github.com/archradhq/arch-deterministic/releases/tag/v0.1.1
+[Unreleased]: https://github.com/archradhq/arch-deterministic/compare/v0.1.6...HEAD
+[0.1.6]: https://github.com/archradhq/arch-deterministic/compare/v0.1.5...v0.1.6
+[0.1.5]: https://github.com/archradhq/arch-deterministic/compare/v0.1.4...v0.1.5
+[0.1.4]: https://github.com/archradhq/arch-deterministic/compare/v0.1.3...v0.1.4
+[0.1.3]: https://github.com/archradhq/arch-deterministic/compare/v0.1.2...v0.1.3
+[0.1.2]: https://github.com/archradhq/arch-deterministic/compare/v0.1.1...v0.1.2
+[0.1.1]: https://github.com/archradhq/arch-deterministic/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/archradhq/arch-deterministic/releases/tag/v0.1.0

package/README.md

@@ -2,28 +2,80 @@
 
 ![archrad validate — IR-LINT-DIRECT-DB-ACCESS-002 first, fix on the graph, clean gate](demo-validate.gif)
 
-<!-- GIFs: validate hero — `npm run build && vhs scripts/record-demo-validate.tape` → demo-validate.gif. Drift — `npm run record:demo:drift` → demo-drift.gif (terminal tape) or replay scripts + capture. For “edit → save → validate-drift” (IDE + terminal, skeptic-grade), see scripts/DEMO_GIF_STORYBOARD.md “Trust loop”. scripts/README_DEMO_RECORDING.md. package.json `files`. -->
+![Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue) ![no LLM](https://img.shields.io/badge/no%20LLM-deterministic-green) ![no account](https://img.shields.io/badge/no%20account-offline-lightgrey)
 
-**A deterministic compiler and linter for system architecture.**
+Your architecture drifts before you write a single line of code. `archrad validate` catches it — deterministically, in CI, before the PR merges.
 
-**Validate your architecture before you write code.**
+Define your system as a graph. ArchRAD compiles it, lints it against architecture rules, and tells you exactly what's wrong — with rule codes, not opinions.
 
-**For AI agents / IDE assistants:** see **`llms.txt`** in this package (llms.txt-style project summary for tools like Claude Code, Devin, etc.).
+---
+
+## Quick start (60 seconds)
+
+```bash
+npm install -g @archrad/deterministic
+archrad validate --ir fixtures/demo-direct-db-violation.json
+```
+
+You should see something like (exact wording may vary slightly by version):
+
+```
+⚠️ IR-LINT-DIRECT-DB-ACCESS-002: API node "orders-api" connects directly to datastore node "orders-db"
+   Fix: Introduce a service or domain layer between HTTP handlers and persistence.
+```
+
+For a smaller graph (single endpoint, no DB edge), try **`fixtures/minimal-graph.json`** — you will get different warnings (e.g. health/auth heuristics), not **`IR-LINT-DIRECT-DB-ACCESS-002`**.
+
+No IR file yet? Cold-start from an existing OpenAPI spec:
+
+```bash
+archrad ingest openapi --spec ./openapi.yaml --out ./graph.json
+archrad validate --ir ./graph.json
+```
+
+---
+
+## What it does
+
+ArchRAD is a blueprint compiler and governance layer. You define your architecture as an IR — nodes, edges, allowed connections — and ArchRAD validates it against a deterministic rule engine. The same IR, the same rules, the same inputs always produce the same findings.
 
-**Apache-2.0** — blueprint **IR** (JSON graph) → **FastAPI** or **Express** + **OpenAPI**, **Docker**, **Makefile** — **no LLM**, **no account**, **offline**.
+| Command | What it checks | Codes |
+|---------|---------------|-------|
+| `archrad validate` | Graph structure + architecture lint | `IR-STRUCT-*` `IR-LINT-*` |
+| `archrad validate-drift` | IR vs generated code on disk | `DRIFT-*` |
+| `archrad ingest openapi` | Derive IR from existing OpenAPI spec | — |
+| `archrad export` | Compile IR → FastAPI or Express + Docker | — |
+
+## CI integration
+
+```bash
+# Fail on any structural error (default):
+archrad validate --ir ./graph.json
+
+# Also fail on lint warnings:
+archrad validate --ir ./graph.json --fail-on-warning
 
-**OSS positioning:** *Includes structural validation + basic architecture linting (rule-based, deterministic).*
+# Machine-readable output for GitHub Actions:
+archrad validate --ir ./graph.json --json
+```
 
-> This is not only a generator: **`archrad validate`** treats your graph like source code — **IR-STRUCT-*** (shape/refs/cycles) and **IR-LINT-*** (light architecture heuristics: health routes, fan-out, sync chains, HTTP→DB coupling). Then **`archrad export`** compiles to runnable projects. After you have a tree on disk, **`archrad validate-drift`** compares it to a **fresh** export from the same IR (missing/changed files — **not** semantic code review). Generated **OpenAPI** gets a **document-shape** pass (parse + required fields — **not** Spectral-style spec lint).
+## MCP server (Cursor / Claude Desktop)
 
-**Open core (OSS):** **IR structural validation**, **basic architecture lint** (rule-based, deterministic), **OpenAPI document-shape** checks. **ArchRad Cloud** adds **policy / compliance**, deeper **architecture intelligence**, and **AI remediation** — see **`docs/STRUCTURAL_VS_SEMANTIC_VALIDATION.md`**.
+After install, `archrad-mcp` is on your PATH. Add it to your IDE:
 
-### Concept, cold start, and strategy (honest scope)
+```json
+{
+  "mcpServers": {
+    "archrad": { "command": "archrad-mcp" }
+  }
+}
+```
 
-The **core idea** is sound: **IR = what to build**, **codegen = how** — with compiler-style validation and deterministic output. **Adoption friction** is real: this repo is a **compiler with no bundled authoring UI** (JSON/graph in; you bring **ArchRad Cloud**, another tool, or hand-written IR). **Where the IR comes from** is intentionally **plural**: **manual** graph JSON/YAML today, plus **`archrad ingest openapi`** (and more ingestion surfaces over time — e.g. **IaC**). Treat **OpenAPI → IR** as a **starting lane**, not the whole roadmap: regenerate IR in CI, then **`archrad validate`** / **`archrad export`** — structural HTTP surface only, not full system semantics. Draft language for “drift / where does IR come from?” threads: **`scripts/SOCIAL_POST_DRIFT_AND_INGESTION.md`**. **Export is one-way** (no built-in round-trip from edited code back to IR)—best thought of as **scaffold + contract validation**, not full lifecycle architecture sync unless you own that workflow. Many teams will still treat the OSS layer as a **trust and CI artifact** that makes the Cloud/AI path auditable. Read **`docs/CONCEPT_ADOPTION_AND_LIMITS.md`** for the full framing and future directions (e.g. lightweight YAML/IDE ergonomics).
+Your agent can call the same engine as the CLI via **six** MCP tools (e.g. `archrad_validate_ir`, `archrad_lint_summary`, `archrad_validate_drift`, `archrad_policy_packs_load`, `archrad_list_rule_codes`, `archrad_suggest_fix`). See [docs/MCP.md](docs/MCP.md) for parameters and local testing.
 
 ---
 
+
 ## How it works (architecture)
 
 ```
@@ -67,7 +119,7 @@ IR (nodes/edges)  →  validateIrStructural (IR-STRUCT-*)  →  errors block exp
 | **AI remediation** | Repair loops, suggested edits |
 
 1. **IR structural validation:** duplicate/missing node ids, bad HTTP `config.url` / `config.method`, unknown edge endpoints, directed cycles.
-2. **Architecture lint:** Implemented as a **registry of visitor functions** on a parsed graph (`buildParsedLintGraph` → **`LINT_RULE_REGISTRY`** in **`src/lint-rules.ts`**). If the IR cannot be parsed, **`buildParsedLintGraph`** returns **`{ findings }`** (IR-STRUCT-*) instead of **`null`**; use **`isParsedLintGraph()`** or call **`validateIrLint`**, which forwards those findings. Each rule returns **`IrStructuralFinding[]`**; **`runArchitectureLinting`** / **`validateIrLint`** flatten them. **Custom org rules:** compose **`runArchitectureLinting`** with your own **`(g) => findings`** in CI (worked example: **`docs/CUSTOM_RULES.md`**), or **fork** and append to **`LINT_RULE_REGISTRY`** if the stock **`archrad validate`** CLI must emit your codes. CLI **`archrad validate`** / **`archrad export`** print lint under **Architecture lint (IR-LINT-*)** (grouped separately from structural). Codes include **IR-LINT-DIRECT-DB-ACCESS-002**, **IR-LINT-SYNC-CHAIN-001**, **IR-LINT-NO-HEALTHCHECK-003**, **IR-LINT-HIGH-FANOUT-004**, **IR-LINT-ISOLATED-NODE-005**, **IR-LINT-DUPLICATE-EDGE-006**, **IR-LINT-HTTP-MISSING-NAME-007**, **IR-LINT-DATASTORE-NO-INCOMING-008**, **IR-LINT-MULTIPLE-HTTP-ENTRIES-009**. **Sync-chain** depth counts **synchronous** edges only; mark message/queue/async hops via **`edge.metadata.protocol`** / **`config.async`** (see **`edgeRepresentsAsyncBoundary`** in **`lint-graph.ts`** and **`docs/ENGINEERING_NOTES.md`**).
+2. **Architecture lint:** Implemented as a **registry of visitor functions** on a parsed graph (`buildParsedLintGraph` → **`LINT_RULE_REGISTRY`** in **`src/lint-rules.ts`**). If the IR cannot be parsed, **`buildParsedLintGraph`** returns **`{ findings }`** (IR-STRUCT-*) instead of **`null`**; use **`isParsedLintGraph()`** or call **`validateIrLint`**, which forwards those findings. Each rule returns **`IrStructuralFinding[]`**; **`runArchitectureLinting`** / **`validateIrLint`** flatten them. **Custom org rules:** compose **`runArchitectureLinting`** with your own **`(g) => findings`** in CI (worked example: **`docs/CUSTOM_RULES.md`**), or **fork** and append to **`LINT_RULE_REGISTRY`** if the stock **`archrad validate`** CLI must emit your codes. CLI **`archrad validate`** / **`archrad export`** print lint under **Architecture lint (IR-LINT-*)** (grouped separately from structural). Codes include **IR-LINT-DIRECT-DB-ACCESS-002**, **IR-LINT-SYNC-CHAIN-001**, **IR-LINT-NO-HEALTHCHECK-003**, **IR-LINT-HIGH-FANOUT-004**, **IR-LINT-ISOLATED-NODE-005**, **IR-LINT-DUPLICATE-EDGE-006**, **IR-LINT-HTTP-MISSING-NAME-007**, **IR-LINT-DATASTORE-NO-INCOMING-008**, **IR-LINT-MULTIPLE-HTTP-ENTRIES-009**, **IR-LINT-MISSING-AUTH-010**, **IR-LINT-DEAD-NODE-011**. **Sync-chain** depth counts **synchronous** edges only; mark message/queue/async hops via **`edge.metadata.protocol`** / **`config.async`** (see **`edgeRepresentsAsyncBoundary`** in **`lint-graph.ts`** and **`docs/ENGINEERING_NOTES.md`**).
 3. **Generators** → `openapi.yaml`, handlers, deps.
 4. **Golden path** → `make run` / `docker compose up --build`.
 5. **OpenAPI document shape** on the bundle — **not** [Spectral](https://github.com/stoplightio/spectral)-level lint. Issues → **`openApiStructuralWarnings`**.
@@ -76,6 +128,8 @@ IR (nodes/edges)  →  validateIrStructural (IR-STRUCT-*)  →  errors block exp
 
 **Trust builder:** **IR-STRUCT-*** errors block export; **IR-LINT-*** warnings are visible and can **gate CI** via **`--fail-on-warning`** / **`--max-warnings`**; OpenAPI shape issues surface as export warnings.
 
+**Reference (OSS):** **[`docs/DRIFT.md`](docs/DRIFT.md)** (deterministic **`validate-drift`**), **[`docs/RULE_CODES.md`](docs/RULE_CODES.md)** (finding codes; MCP **`docsUrl`** targets GitHub anchors), **[`docs/MCP.md`](docs/MCP.md)** (MCP tools + local testing).
+
 ### Codegen vs validation (retry, timeouts, policy)
 
 Generators **may emit** retry/timeout/circuit-breaker **code** when the IR carries matching edge or node config (e.g. `retryPolicy`). That is **code generation**, not a guarantee. OSS does **not** currently **require** or **lint** “every external call must have timeout/retry” — that class of rule is **semantic / policy** and fits **ArchRad Cloud** or custom linters on top of the IR.
@@ -92,10 +146,17 @@ Generators **may emit** retry/timeout/circuit-breaker **code** when the IR carri
 | **CLI validate** | CI / pre-commit: IR structural + architecture lint, no codegen | `archrad validate --ir graph.json` |
 | **CLI validate-drift** | After export or merges: on-disk tree vs fresh deterministic export from same IR | `archrad validate-drift -i graph.json -t python -o ./out` |
 | **Library** (`@archrad/deterministic`) | IDPs / pipelines | `runDeterministicExport` → files + findings; **`runValidateDrift`** / **`runDriftCheckAgainstFiles`** for drift |
+| **MCP** (`archrad-mcp`) | Cursor / Claude Desktop / other MCP hosts | stdio server: validate IR, lint summary, drift, policy packs, static **`archrad_suggest_fix`** — see **`docs/MCP.md`** |
+
+**MCP (Cursor example):** after `npm i -g @archrad/deterministic` (or `npx`), add a server with command **`archrad-mcp`** and no args (stdio). Pass **`ir`** inline or **`irPath`** to a JSON file for large graphs. **`archrad_suggest_fix`** returns curated text for a finding code (e.g. `IR-LINT-MISSING-AUTH-010`) — not machine-generated IR patches. **Step-by-step testing** (smoke script, MCP Inspector, Cursor chat prompts): **`docs/MCP.md`**, section **Local testing**.
 
 ### CLI
 
-**Input is structured IR (JSON), not natural language.** There is no `archrad export --prompt "..."`. You pass a **graph file** (nodes/edges) like **`fixtures/minimal-graph.json`**. The **npm README GIF** uses **`fixtures/demo-direct-db-violation.json`** → **`fixtures/demo-direct-db-layered.json`**: **failure-first** **`IR-LINT-DIRECT-DB-ACCESS-002`**, fix on the graph, then a **clean** validate (no codegen in the clip). For a graph that hits **many** lint rules at once (stress test), use **`fixtures/ecommerce-with-warnings.json`**. For a **golden payment + retry** graph (edge `config.retry.maxAttempts` + payment node `config.retryPolicy`, both `3`), use **`fixtures/payment-retry-demo.json`** — export shows **`retry_policy`** / retry helpers in **`app/main.py`**. Record that path with **`scripts/record-demo-payment-retry.tape`** (→ **`demo-payment-retry.gif`**). **Drift clip:** **`scripts/record-demo-drift.tape`** / **`npm run record:demo:drift`** (→ **`demo-drift.gif`**) — export, **`tail`** before/after a one-line tamper on **`out/app/main.py`**, then **`validate-drift`**; if **VHS** fails on your machine, run **`scripts/run-demo-drift-sequence.ps1`** or **`.sh`** while screen-capturing (see **`scripts/README_DEMO_RECORDING.md`**). See **`scripts/DEMO_GIF_STORYBOARD.md`** for all tapes. **CLI:** `--target python` is the FastAPI bundle; there is no separate `fastapi` target name. To go from **plain English → IR**, use **ArchRad Cloud** or your own LLM step; this package only does **IR → files**.
+**Input is structured IR (JSON), not natural language.** There is no `archrad export --prompt "..."`. Pass a **graph file** (nodes/edges).
+
+**Fixtures** (in this repo): **`fixtures/minimal-graph.json`** (small); **`fixtures/demo-direct-db-violation.json`** / **`fixtures/demo-direct-db-layered.json`** (before/after **`IR-LINT-DIRECT-DB-ACCESS-002`**); **`fixtures/ecommerce-with-warnings.json`** (many lint rules); **`fixtures/payment-retry-demo.json`** (retry-related codegen in export). **`--target python`** is the FastAPI bundle; there is no separate `fastapi` target. To go from **plain English → IR**, use **ArchRad Cloud** or your own LLM step; this package only does **IR → files**.
+
+**Recording demos and GIFs** (VHS, storyboards, drift replay): **`scripts/README_DEMO_RECORDING.md`** only — not required to use the CLI.
 
 **OpenAPI → JSON (spec as source of truth):** each operation under `paths` becomes an `http` node (`config.url` + `config.method`). Then validate and export like any other IR:
 
@@ -117,16 +178,13 @@ archrad validate --ir ./graph.json
 
 YAML must have either top-level **`graph:`** (object) or top-level **`nodes:`** (array); bare graphs are wrapped as `{ "graph": { ... } }` automatically.
 
-After `npm run build` (required after `npm ci`; there is no `prepare` hook — see **`docs/ENGINEERING_NOTES.md`**):
+**After `npm install -g` or `npx`** (typical):
 
 ```bash
-node dist/cli.js export --ir fixtures/minimal-graph.json --target python --out ./my-api
-node dist/cli.js yaml-to-ir --yaml fixtures/minimal-graph.yaml --out /tmp/ir.json
-# After global install / npx:
 archrad export --ir ./graph.json --target node --out ./my-express-api
 
 # Validate IR (structural + architecture lint). Pretty output; exit 1 on structural errors by default:
-node dist/cli.js validate --ir fixtures/minimal-graph.json
+archrad validate --ir ./graph.json
 # Machine-readable + CI gates:
 archrad validate --ir ./graph.json --json
 archrad validate --ir ./graph.json --fail-on-warning
@@ -137,6 +195,8 @@ archrad validate --ir ./graph.json --skip-lint
 archrad validate --ir ./graph.json --policies ./policy-packs
 ```
 
+**From a git clone** (contributors): run **`npm ci && npm run build`** in the package root (there is no `prepare` hook — see **`docs/ENGINEERING_NOTES.md`**), then use **`node dist/cli.js`** the same way you would use **`archrad`** (e.g. **`node dist/cli.js validate --ir fixtures/minimal-graph.json`**).
+
 **Deterministic drift (thin, OSS):** compare an existing export tree on disk to a **fresh** export from the same IR. Detects **missing** / **changed** generated files (line endings normalized). Optional **`--strict-extra`** flags files present on disk but not in the reference export. Not semantic “does code match intent” — **ArchRad Cloud** adds builder/UI drift checks and broader governance.
 
 ```bash
@@ -149,8 +209,6 @@ archrad validate-drift -i ./graph.json -t python -o ./out --skip-host-port-check
 archrad validate-drift -i ./graph.json -t python -o ./out --strict-extra
 ```
 
-Regenerate the matching clip: **`npm run record:demo:drift`** (VHS) → **`demo-drift.gif`**, or **`scripts/run-demo-drift-sequence.ps1`** / **`.sh`** + ShareX/OBS if VHS is unavailable (see **`scripts/DEMO_GIF_STORYBOARD.md`**).
-
 #### Example: validate architecture
 
 ```bash
@@ -183,13 +241,6 @@ By default, if **8080** (or your `--host-port`) looks **busy** on localhost, the
 
 **Export** runs **IR structural validation**, then **architecture lint**, then codegen. **Structural errors** abort with **no files written**. **`irLintFindings`** contains only **`IR-LINT-*`**; **`IR-STRUCT-*`** from a failed parse always appear under **`irStructuralFindings`** (including when structural validation was skipped). **Lint warnings** print by default; use **`--fail-on-warning`** / **`--max-warnings`** to block writes for CI.
 
-### Validate the package as a developer
-
-1. `cd packages/deterministic && npm ci && npm run build && npm test`
-2. `node dist/cli.js export --ir fixtures/minimal-graph.json --target python --out ./tmp-out`
-3. `cd tmp-out && make run` then `curl` the URL shown in the generated **README** (port matches `--host-port` if you set it).
-4. Optional: `node dist/cli.js export ... --host-port 18080` if **8080** is already taken.
-
 ### Library
 
 ```typescript
@@ -224,9 +275,9 @@ Optional: `isLocalHostPortFree` / `normalizeGoldenHostPort` from the same packag
 
 ---
 
-## Golden path (~60 seconds)
+## Golden path (contributors — local clone)
 
-From the package root (after build):
+This path assumes you **cloned the repo** and ran **`npm ci && npm run build`** in the package root. If you only installed with **`npm install -g @archrad/deterministic`**, use **`archrad`** instead of **`node dist/cli.js`** (same flags).
 
 ```bash
 node dist/cli.js export --ir fixtures/minimal-graph.json --target python --out ./out
@@ -238,13 +289,9 @@ curl -sS -X POST http://localhost:8080/signup -H "Content-Type: application/json
 
 You should see **422 Unprocessable Entity** (FastAPI/Pydantic) or **400** with a clear body — proof the stack is live and validation matches the spec, not a silent 500.
 
-**Helper script** (prints the same flow; use when recording a terminal GIF):
-
-```bash
-bash scripts/golden-path-demo.sh
-```
+Quick check from a clone: **`cd packages/deterministic && npm ci && npm run build && npm test`**, then export to **`./tmp-out`**, **`cd tmp-out && make run`**, **`curl`** as above. Use **`--host-port 18080`** (or **`node dist/cli.js export ... --host-port 18080`**) if **8080** is busy.
 
-See **`scripts/README_DEMO_RECORDING.md`** for **VHS / asciinema / ttyrec** tips, **When VHS fails**, **drift** replay scripts, and the **trust loop** (IDE edit + terminal **`validate-drift`**). The hero GIF at the top is **`demo-validate.gif`**; **`demo-drift.gif`** and the **trust-loop** storyboard live in **`scripts/DEMO_GIF_STORYBOARD.md`**.
+Optional: **`bash scripts/golden-path-demo.sh`** runs the same flow. **Demo recording** (GIFs, tapes, drift replays): **`scripts/README_DEMO_RECORDING.md`**.
 
 ---
 
@@ -261,20 +308,6 @@ See **`scripts/README_DEMO_RECORDING.md`** for **VHS / asciinema / ttyrec** tips
 
 You can depend on this CLI and library **without** ArchRad Cloud. The cloud product stacks collaboration and AI on top of the same deterministic contract.
 
-**InkByte vs this package:** Deeper workflow analysis, enterprise validation routes, and LLM-assisted flows may exist in the **private InkByte monorepo** (`server/`, etc.); they are **not** part of the **`@archrad/deterministic`** npm surface unless shipped here. This README describes **only** what the OSS package proves.
-
----
-
-## Monorepo vs public OSS repo
-
-The **canonical source** for this engine may live in a **private monorepo** next to the full product; `server` can depend on `file:../packages/deterministic`. The **public** GitHub repo should contain **only** this package — canonical clone: **`https://github.com/archradhq/arch-deterministic`**. Subtree publish: **`docs/OSS_VS_PRODUCT_REPOS.md`** and **`docs/PUBLISH_DETERMINISTIC_OSS.md`** (in the product monorepo).
-
----
-
-## Publishing the public OSS repo
-
-From the private monorepo root: **`docs/PUBLISH_DETERMINISTIC_OSS.md`**. This tree includes **`.github/workflows/ci.yml`** and **Dependabot**; they run when this folder is the **git root** of the public repo.
-
 ---
 
 ## Contributing

package/biome.json

@@ -1,25 +1,32 @@
-{
-  "$schema": "https://biomejs.dev/schemas/1.9.4/schema.json",
-  "vcs": { "enabled": true, "clientKind": "git", "useIgnoreFile": true },
-  "files": {
-    "ignore": ["dist", "node_modules", "*.json", "fixtures", "schemas"]
-  },
-  "formatter": {
-    "enabled": false
-  },
-  "organizeImports": { "enabled": false },
-  "linter": {
-    "enabled": true,
-    "rules": {
-      "recommended": false,
-      "suspicious": {
-        "noDebugger": "error"
-      }
-    }
-  },
-  "javascript": {
-    "formatter": {
-      "quoteStyle": "single"
-    }
-  }
-}
+{
+	"$schema": "https://biomejs.dev/schemas/2.4.10/schema.json",
+	"vcs": { "enabled": true, "clientKind": "git", "useIgnoreFile": true },
+	"files": {
+		"includes": [
+			"**",
+			"!**/dist",
+			"!**/node_modules",
+			"!**/*.json",
+			"!**/fixtures",
+			"!**/schemas"
+		]
+	},
+	"formatter": {
+		"enabled": false
+	},
+	"assist": { "actions": { "source": { "organizeImports": "off" } } },
+	"linter": {
+		"enabled": true,
+		"rules": {
+			"recommended": false,
+			"suspicious": {
+				"noDebugger": "error"
+			}
+		}
+	},
+	"javascript": {
+		"formatter": {
+			"quoteStyle": "single"
+		}
+	}
+}

package/dist/cli.js

@@ -76,7 +76,7 @@ const program = new Command();
 program
     .name('archrad')
     .description('Validate your architecture before you write code. Deterministic compiler + linter — FastAPI / Express (no LLM, no server).')
-    .version('0.1.4');
+    .version('0.1.6');
 program
     .command('validate')
     .description('Validate your architecture before you write code — IR structural (IR-STRUCT-*) + architecture lint (IR-LINT-*)')

package/dist/mcp-server-tools-patch.d.ts

@@ -0,0 +1,29 @@
+/**
+ * MCP tool catalog metadata (title + description) for archrad-mcp discoverability.
+ * Keep in sync with registerTool handlers in mcp-server.ts.
+ */
+export declare const MCP_TOOL_ARCHRAD_VALIDATE_IR: {
+    readonly title: "Validate IR — structural (IR-STRUCT-*) + architecture lint (IR-LINT-*) + PolicyPack";
+    readonly description: "Architecture-as-code validation: run this when you need to check whether an IR graph is valid or to list violations before export or drift checks.\n\nKeywords: validate IR, architecture lint, IR-STRUCT, IR-LINT, policy pack, blueprint graph, nodes and edges.\n\nRuns in one call:\n1) Structural validation — graph shape, references, IR-STRUCT-* errors.\n2) Architecture lint — design rules (auth, dead nodes, DB access, sync chains, etc.).\n3) Optional PolicyPack rules — pass policiesDirectory to load YAML/JSON packs from disk.\n\nReturns irStructuralFindings, irLintFindings, and combined (sorted by severity). ok is false when any finding has severity \"error\".\n\nAfter results: call archrad_suggest_fix with a finding code for remediation text; use archrad_lint_summary for a short human-readable digest.\n\nInput: provide exactly one of ir (inline JSON object) or irPath (path to .json). Large graphs: prefer irPath.";
+};
+export declare const MCP_TOOL_ARCHRAD_LINT_SUMMARY: {
+    readonly title: "Lint summary — plain-text counts and top findings";
+    readonly description: "Human-readable summary of validation results: error/warning counts and up to 20 top findings (plain text).\n\nKeywords: summary, PR comment, explain violations, readable lint output.\n\nUse when you need a short narrative or comment, not structured JSON. For machine-actionable findings, use archrad_validate_ir instead.\n\nSame inputs as archrad_validate_ir: ir or irPath, optional policiesDirectory. Provide only one of ir or irPath.";
+};
+export declare const MCP_TOOL_ARCHRAD_SUGGEST_FIX: {
+    readonly title: "Suggest fix — static remediation for a built-in finding code";
+    readonly description: "Look up curated remediation steps and documentation URL for one built-in rule code (e.g. IR-LINT-MISSING-AUTH-010, IR-STRUCT-*, DRIFT-*).\n\nKeywords: remediation, how to fix, rule code, docs link, IR-LINT, IR-STRUCT.\n\nDoes not return generated code patches or IR edits — only static guidance. PolicyPack and org-specific rule ids are not covered; see your YAML packs.\n\nCall archrad_list_rule_codes to list codes that have static guidance.";
+};
+export declare const MCP_TOOL_ARCHRAD_LIST_RULE_CODES: {
+    readonly title: "List rule codes — built-in codes with static guidance";
+    readonly description: "Returns the sorted list of built-in IR-STRUCT-*, IR-LINT-*, and DRIFT-* codes that archrad_suggest_fix can explain.\n\nKeywords: catalog, all rules, rule list, documentation index.\n\nUse before suggest_fix to confirm a code exists. Excludes PolicyPack custom ids. No arguments.";
+};
+export declare const MCP_TOOL_ARCHRAD_VALIDATE_DRIFT: {
+    readonly title: "Validate drift — IR blueprint vs on-disk export (python | nodejs)";
+    readonly description: "Compare the architecture IR to generated code under exportDir and report drift (files that no longer match deterministic export).\n\nKeywords: drift, CI, codegen diff, FastAPI, Express, Node, Python, validate export, architecture vs implementation.\n\nRequires: ir or irPath, exportDir (absolute path to the export tree), and target. target must be \"python\" or \"nodejs\" (use \"nodejs\" for Node/TypeScript; do not use \"node\").\n\nOptional: policiesDirectory, skipIrLint (true to skip IR-LINT and only check drift).\n\nReturns driftFindings plus IR structural and lint findings from the same engine as CLI validate-drift.";
+};
+export declare const MCP_TOOL_ARCHRAD_POLICY_PACKS_LOAD: {
+    readonly title: "Load PolicyPack — compile and validate packs (dry run, no IR)";
+    readonly description: "Validate PolicyPack YAML/JSON without running against a graph: syntax, rule ids, and compilation.\n\nKeywords: policy pack, YAML rules, validate policies, org rules, offline check.\n\nYou usually do not need this before archrad_validate_ir or archrad_validate_drift — those accept policiesDirectory and load packs internally. Use this tool to debug pack files in isolation.\n\nProvide either directory (folder path) or files (array of { name, content }), not both.";
+};
+//# sourceMappingURL=mcp-server-tools-patch.d.ts.map

package/dist/mcp-server-tools-patch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-server-tools-patch.d.ts","sourceRoot":"","sources":["../src/mcp-server-tools-patch.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,eAAO,MAAM,4BAA4B;;;CAgB/B,CAAC;AAEX,eAAO,MAAM,6BAA6B;;;CAShC,CAAC;AAEX,eAAO,MAAM,4BAA4B;;;CAS/B,CAAC;AAEX,eAAO,MAAM,gCAAgC;;;CAOnC,CAAC;AAEX,eAAO,MAAM,+BAA+B;;;CAWlC,CAAC;AAEX,eAAO,MAAM,kCAAkC;;;CASrC,CAAC"}

package/dist/mcp-server-tools-patch.js

@@ -0,0 +1,71 @@
+/**
+ * MCP tool catalog metadata (title + description) for archrad-mcp discoverability.
+ * Keep in sync with registerTool handlers in mcp-server.ts.
+ */
+export const MCP_TOOL_ARCHRAD_VALIDATE_IR = {
+    title: 'Validate IR — structural (IR-STRUCT-*) + architecture lint (IR-LINT-*) + PolicyPack',
+    description: `Architecture-as-code validation: run this when you need to check whether an IR graph is valid or to list violations before export or drift checks.
+
+Keywords: validate IR, architecture lint, IR-STRUCT, IR-LINT, policy pack, blueprint graph, nodes and edges.
+
+Runs in one call:
+1) Structural validation — graph shape, references, IR-STRUCT-* errors.
+2) Architecture lint — design rules (auth, dead nodes, DB access, sync chains, etc.).
+3) Optional PolicyPack rules — pass policiesDirectory to load YAML/JSON packs from disk.
+
+Returns irStructuralFindings, irLintFindings, and combined (sorted by severity). ok is false when any finding has severity "error".
+
+After results: call archrad_suggest_fix with a finding code for remediation text; use archrad_lint_summary for a short human-readable digest.
+
+Input: provide exactly one of ir (inline JSON object) or irPath (path to .json). Large graphs: prefer irPath.`,
+};
+export const MCP_TOOL_ARCHRAD_LINT_SUMMARY = {
+    title: 'Lint summary — plain-text counts and top findings',
+    description: `Human-readable summary of validation results: error/warning counts and up to 20 top findings (plain text).
+
+Keywords: summary, PR comment, explain violations, readable lint output.
+
+Use when you need a short narrative or comment, not structured JSON. For machine-actionable findings, use archrad_validate_ir instead.
+
+Same inputs as archrad_validate_ir: ir or irPath, optional policiesDirectory. Provide only one of ir or irPath.`,
+};
+export const MCP_TOOL_ARCHRAD_SUGGEST_FIX = {
+    title: 'Suggest fix — static remediation for a built-in finding code',
+    description: `Look up curated remediation steps and documentation URL for one built-in rule code (e.g. IR-LINT-MISSING-AUTH-010, IR-STRUCT-*, DRIFT-*).
+
+Keywords: remediation, how to fix, rule code, docs link, IR-LINT, IR-STRUCT.
+
+Does not return generated code patches or IR edits — only static guidance. PolicyPack and org-specific rule ids are not covered; see your YAML packs.
+
+Call archrad_list_rule_codes to list codes that have static guidance.`,
+};
+export const MCP_TOOL_ARCHRAD_LIST_RULE_CODES = {
+    title: 'List rule codes — built-in codes with static guidance',
+    description: `Returns the sorted list of built-in IR-STRUCT-*, IR-LINT-*, and DRIFT-* codes that archrad_suggest_fix can explain.
+
+Keywords: catalog, all rules, rule list, documentation index.
+
+Use before suggest_fix to confirm a code exists. Excludes PolicyPack custom ids. No arguments.`,
+};
+export const MCP_TOOL_ARCHRAD_VALIDATE_DRIFT = {
+    title: 'Validate drift — IR blueprint vs on-disk export (python | nodejs)',
+    description: `Compare the architecture IR to generated code under exportDir and report drift (files that no longer match deterministic export).
+
+Keywords: drift, CI, codegen diff, FastAPI, Express, Node, Python, validate export, architecture vs implementation.
+
+Requires: ir or irPath, exportDir (absolute path to the export tree), and target. target must be "python" or "nodejs" (use "nodejs" for Node/TypeScript; do not use "node").
+
+Optional: policiesDirectory, skipIrLint (true to skip IR-LINT and only check drift).
+
+Returns driftFindings plus IR structural and lint findings from the same engine as CLI validate-drift.`,
+};
+export const MCP_TOOL_ARCHRAD_POLICY_PACKS_LOAD = {
+    title: 'Load PolicyPack — compile and validate packs (dry run, no IR)',
+    description: `Validate PolicyPack YAML/JSON without running against a graph: syntax, rule ids, and compilation.
+
+Keywords: policy pack, YAML rules, validate policies, org rules, offline check.
+
+You usually do not need this before archrad_validate_ir or archrad_validate_drift — those accept policiesDirectory and load packs internally. Use this tool to debug pack files in isolation.
+
+Provide either directory (folder path) or files (array of { name, content }), not both.`,
+};

package/dist/mcp-server.d.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+/**
+ * archrad-mcp — Model Context Protocol server (stdio) for deterministic IR validation,
+ * architecture lint, policy packs, and drift checks. Uses the same engine as `archrad` CLI.
+ */
+export {};
+//# sourceMappingURL=mcp-server.d.ts.map

package/dist/mcp-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-server.d.ts","sourceRoot":"","sources":["../src/mcp-server.ts"],"names":[],"mappings":";AACA;;;GAGG"}