@dforge-core/dforge-mcp 0.1.13 → 0.2.0

package/CHANGELOG.md

@@ -4,6 +4,237 @@ All notable changes to `@dforge-core/dforge-mcp`. This project uses semver-ish
 `0.1.0-rc.N` pre-release tags; the published version is set at publish time via
 the release workflow, so committed `package.json` versions are placeholders.
 
+## 0.2.0
+
+Tools go from 27 → 34; the single wizard skill splits into a router plus three
+stage skills; `dforge_module_validate` grows the checks that previously only
+surfaced at install.
+
+### Fixed
+
+- **`dforge_module_inspect` reported nothing useful about actions.** It read
+  `entity` / `mode` / `background`, but `dforge_action_add` has always written
+  `entityCode` / `executionMode` / `isAsync` (matching the installer and the
+  canonical example), so every action inspected as `entity: "?"`. Since the
+  skill makes inspect the pre-patch source of truth, agents were planning
+  against wrong data. Legacy key names are still read as a fallback.
+- **`dforge_module_inspect` listed `["jobs"]` as the job list** — `logic/jobs.json`
+  is `{ jobs: [...] }`, not a code-keyed map, so `Object.keys` returned the
+  wrapper key. Jobs, triggers and webhooks are now reported properly, alongside
+  queries, print templates, domains and `supportedLocales`.
+- **Every entity's `toString` was reported as an inherited function.** `toString`
+  comes from `Object.prototype`, so reading `entity.toString` never yields
+  `undefined`; `JSON.stringify` then dropped it silently. Now read as an own
+  property.
+- **Freshly scaffolded entities shipped a dangling `toString`.** dforge-cli's
+  `buildEntity` emits `"{id}"`, but the `identity` trait names the PK
+  `{entity}_id` — so the template referenced a column that never existed.
+  Normalized to `{<entity>_id}` on the way out of `module_create` / `entity_add`.
+- **Phase labels in the tool descriptions had drifted** from the skill: entity
+  and field tools claimed Phase 2 (they're Phase 1); views and reports claimed
+  Phase 4 (they're Phase 3). Tool descriptions are always in context and the
+  skill table isn't, so the wrong one was winning.
+- **Resource descriptions never reached the client.** The deprecated
+  `server.resource()` signature dropped them; `registerResource` carries them.
+
+### Added — composite entity tools
+
+Three dForge concepts each span several coordinated keys, and hand-assembling
+them from `entity_field_add` is the top source of broken modules. These take the
+intent and emit the whole shape, so the broken variants aren't representable:
+
+- **`dforge_entity_reference_add`** — a relation as all three of its parts:
+  hidden FK (`cuid` / `EM` / no `fieldTypeCd`), visible Reference (`R` /
+  `lookup` / `link`), and the `references` entry. Also *completes* a half-built
+  relation by reusing an FK column an import already created.
+- **`dforge_entity_rollup_add`** — a child total as a **Generated** (`G`) column,
+  creating the parent's Set column when needed, and refusing to aggregate a
+  virtual `F`/`R`/`S` child (the `column old.<field> does not exist` failure).
+- **`dforge_entity_status_add`** — a dropdown with `params.options` objects and
+  the initial value as a `formula`, never the `defaultValue` key the entity
+  schema rejects.
+
+### Added — DSL static checking
+
+- **`dforge_action_check`** — check a draft `dslBody` before committing to
+  `action_add`, or an `actionCode` already on disk (its execution mode and job
+  bindings are read from the module). Catches `TODAY()`/`NOW()` inside
+  `execute:`, `[field]` record-context in batch mode or a job-invoked action,
+  block order/duplication, top-level `return`, `:param` SQL placeholders, and
+  unknown host functions.
+- `dforge_action_add` now runs the same checker and rejects errors, replacing
+  the single hard-coded `TODAY()` grep.
+- `dforge_module_validate` runs it over every action body in the module.
+
+### Added — the element tools that were missing
+
+- **`dforge_menu_add`** — menus had a reference doc and a schema but no tool, so
+  agents hand-wrote the JSON and hit the same three documented mistakes. Now
+  `dataViewCode` is validated against `data_views.json`, `itemType` lands on
+  leaves only, and icons are normalized to the bare form menus require.
+- **`dforge_translation_sync`** — generates every install-required key from the
+  module's own contents (entities + trait-provided fields, views, menus, roles,
+  actions, folders, settings), never overwriting existing translated text.
+  "Missing translation key" was a documented install-failure mode with no tool
+  behind it, and role labels are completeness-enforced.
+- **`dforge_seed_add`** — enforces the four documented seed traps: numeric
+  `{entity}_id` PKs, parent-before-child load order, `audit-full` System-user
+  columns, and FKs pointing at seeded parents.
+
+### Added — `apply: true`
+
+Every patch tool accepts `apply`. It writes the file map to disk and returns the
+paths instead of the contents — cutting the full-file round trip through context
+on routine patches, and guaranteeing the `deletes` half of a rename/delete is
+applied. Refuses to write outside `moduleDir`; never writes report payloads.
+
+### Added — full-lifecycle phase ledger
+
+`docs/phase.json` now records Phases 1-6, not just Phase 0.
+`dforge_module_plan({ action: "check" })` returns `currentPhase`, `nextSkill`
+and `gaps` derived from the ledger **plus** evidence read from the module
+(entities without fields, without a view, without a Select grant).
+`complete_phase` records a phase as done or deliberately skipped. Previously a
+resumed session had to guess the phase by cross-referencing inspect output,
+which can't distinguish "skipped deliberately" from "not started".
+
+### Fixed — follow-ups from review
+
+- **`dbDatatype: "number"` produced a suggestion with unbalanced quotes.** The
+  alias table smuggled quote characters into its value to fake a list, so the
+  rendered message depended on the surrounding template. Multi-option
+  suggestions are now real arrays formatted by one helper — `use 'int' /
+  'bigint' / 'numeric'.`
+- **Folder codes were only checked among siblings.** A folder is addressed flat
+  and path-less outside the tree — `folder:<code>` in role rights,
+  `folders.<code>.label` in translations — so the same code in two branches was
+  ambiguous in the rights matrix and let one folder's label silently overwrite
+  the other's in a synced translation file. `dforge_folder_add` now refuses a
+  code used anywhere in the tree, `dforge_module_validate` errors on duplicates,
+  and `dforge_translation_sync` refuses to generate colliding keys.
+- **`apply: true` without `moduleDir` silently degraded to a preview** — a
+  client relying on apply semantics got a success response and no write. It now
+  errors.
+- **Raw NUL bytes were being used as composite-key separators** (the validator's
+  view+entity keys and `dforge_translation_sync`'s keep/prune path keys). Beyond
+  being invisible in a diff and unreadable in debug output, a NUL makes `grep`
+  classify the whole source file as BINARY and stop reporting matches in it — so
+  the usual "search the codebase" check came back clean while the problem sat
+  right there. Both now use a shared, exported `compositeKey()` / `KEY_SEP =
+  "::"`, and a `source-hygiene` test fails the build on any raw NUL or other
+  invisible control character in `src/` or `test/`.
+- **`dforge_entity_reference_add` reused an existing FK column without checking
+  its shape.** An import commonly emits the FK as a visible numeric column;
+  reusing it as-is produced a pair that looked complete and failed at install.
+  The column is now normalized to the hidden-FK shape (`cuid` / `EM`, no
+  `fieldTypeCd`, no `columnType`), preserving author metadata like `orderNum`
+  and `description`, and the response reports exactly what changed.
+- **`dforge_module_plan` was registered through the ToolResult envelope with a
+  cast**, which would have absorbed a real shape mismatch — most of its actions
+  return lifecycle state with no `files` at all. It now has an explicit
+  `PlanResult` type and a `serialize()` envelope that makes no ToolResult
+  assumption. (The envelope was also renamed off `readOnly`: read-only-ness is
+  declared by the tool `annotations`, and some tools it wraps do return files.)
+- **`applyToDisk` would throw an opaque error if `deletes` ever contained a
+  directory.** `deletes` is a file-only contract, so it now says so: directories
+  are refused by name rather than removed recursively (silently deleting a
+  subtree would be the worst response to a tool bug), and symlinks are unlinked
+  rather than followed.
+
+### Fixed — second review pass
+
+- **`dforge_seed_add` hard-coded a list of "trait-provided columns" that was
+  wrong on almost every entry.** The registry's real names are `created_date` /
+  `last_updated` (audit), `order_num` (sorting), `active` (soft-delete) — not
+  `created_at` / `updated_at` / `sort_order` / `is_deleted`, and `audit-full`'s
+  `created_by_user` / `last_updated_by_user` and the whole `period` set were
+  missing. Seeding a legitimate `created_date` was rejected as an unknown
+  column. Now derived from `expandTraits` for the entity's actual trait list.
+- **Unknown trait codes were silently dropped, not rejected.** `expandTraits`
+  returns only the codes it recognizes, so a typo'd trait doesn't fail — its
+  columns just vanish, and every downstream check then reports them as "not a
+  column". `dforge_module_validate` now flags the cause, and `seed_add` /
+  `translation_sync` refuse to run against one.
+- **`dforge_translation_sync` silently skipped unreadable entity files**,
+  producing an incomplete skeleton while reporting success — the gap would only
+  surface later as a missing-label install failure. A missing or malformed
+  entity file named in the manifest is now fatal, and names the path.
+- **The SQL-literal scan used a regex that stopped at the first escaped quote**,
+  so `query('... \' ... :cid')` truncated mid-statement and the placeholder
+  check missed what followed. Replaced with an escape-aware string scanner;
+  concatenation is now detected after the literal rather than inside it.
+- `dforge_module_plan`'s `complete_phase` cast its own check result back to an
+  untyped bag, discarding the `PlanResult` typing; `buildPhaseCheck` now returns
+  a declared `BuildPhaseCheck` and the fields are destructured.
+- Renamed the control-character guard test to match what it scans (whole source,
+  not only string literals).
+
+### Changed — validation is now the single choke point
+
+Field rules lived only in the `entity_field_add` zod schema, so anything
+entering via `module_import`, `dbml_import`, the scaffolder or a hand edit
+bypassed them entirely. They now live in one place and run in both. New checks
+in `dforge_module_validate`:
+
+- every field re-checked against the full rule set, module-wide
+- Formula (`F`) and Generated (`G`) column shape; Reference (`R`) column shape
+- `dbDatatype` values that are really `fieldTypeCd`s
+- `toString` present, and its `{braces}` resolving to real columns
+- an `F` column carrying a set aggregate; a `G` aggregate over a virtual child
+- action `script` files missing from disk, or not bare filenames
+- triggers/jobs firing actions that don't exist; job actions using `[field]`
+- DSL static checks on every action body
+- translation completeness: a file per `supportedLocales` entry, and a
+  `roles.<code>.label` in every locale file including the en-US base
+
+### Fixed — the skills installer did not work on Windows
+
+`scripts/install-skills.sh` was bash-only, so it could not run in cmd.exe or
+PowerShell at all — and `npm run install-skills` invoked `bash`, which fails
+there too. Under WSL it appeared to work but resolved `$HOME` to the *Linux*
+home, silently installing to `/home/you/.claude` while a Windows Claude Code
+read `C:\Users\you\.claude`. `scripts/` was also absent from package.json
+`files`, so the script did not ship at all.
+
+The installer is now **`scripts/install-skills.mjs`** (Node), behaving
+identically on Windows/macOS/Linux/Git Bash/WSL:
+
+- exposed as a `dforge-install-skills` bin, so
+  `npx -y -p @dforge-core/dforge-mcp dforge-install-skills` needs no clone and
+  no bash (npm shims it as `.cmd` on Windows)
+- destination resolves `DEST` → `CLAUDE_CONFIG_DIR/skills` →
+  `os.homedir()/.claude/skills`, so Windows gets `%USERPROFILE%` regardless of
+  the invoking shell
+- `--from-npm` uses `npm pack` + `tar` (built into Windows 10 1803+), which
+  fetches only this package rather than its ~35 MB native CLI dependency
+- handles `EPIPE` so piping into `head`/`less` doesn't dump a stack trace
+- `scripts/install-skills.mjs` added to package.json `files`
+
+`scripts/install-skills.sh` is kept as a thin wrapper that execs the Node
+script, so the documented `curl … | bash` one-liner still works.
+
+### Changed — skills split by lifecycle stage
+
+`dforge-mcp-author` becomes a thin router; `dforge-module-design` (Phase 0),
+`dforge-module-build` (Phases 1-5) and `dforge-module-ship` (Phase 6) own the
+instructions. Each stage needs a different half of the knowledge base, and the
+488-line monolith was resident for all of it. Handoff is deterministic via
+`dforge_module_plan`'s `nextSkill`. The router directory still carries the
+shared `references/` + `examples/` the MCP server serves as resources.
+
+`scripts/install-skills.sh` installs all four (`--from-npm` to pull the
+published package).
+
+### Changed — internal
+
+- Migrated from the deprecated `server.tool()` / `server.resource()` to
+  `registerTool` / `registerResource`, adding titles and annotations
+  (`readOnlyHint` on inspect/validate/action_check, `destructiveHint` on the
+  delete/rename refactors and install, `openWorldHint` on pack/install).
+- Tests: 80 → 161, including an end-to-end suite that drives a module through
+  the real tool surface on a temp directory and asserts it validates clean. That
+  suite is what caught the inspect key mismatch and the scaffolder's `{id}`.
+
 ## 0.1.12
 
 > Release prerequisite: publish `@dforge-core/metadata@0.0.10` first (adds the

package/README.md

@@ -1,8 +1,8 @@
 # @dforge-core/dforge-mcp
 
-MCP server for dForge module authoring. Exposes 27 composable tools and the canonical schemas so AI agents (Claude Code, Cursor, Zed, etc.) can drive the full module lifecycle — scaffold → entities → actions → views → security → install — through structured tool calls instead of free-form JSON generation.
+MCP server for dForge module authoring. Exposes 34 composable tools and the canonical schemas so AI agents (Claude Code, Cursor, Zed, etc.) can drive the full module lifecycle — scaffold → entities → actions → views → security → install — through structured tool calls instead of free-form JSON generation.
 
-Ships with a wizard Skill (`skills/dforge-mcp-author/`) that walks the AI through six phases with explicit backtrack support when later phases expose earlier gaps. The skill bundle includes 23 detailed reference files (field types, flags, traits, formulas, DSL, security, etc.) and an annotated `simple-todo` example module.
+Ships with **four Claude Skills** (`skills/`): a router plus one skill per lifecycle stage — design (Phase 0), build (Phases 1-5), and ship (Phase 6). The router directory carries 25 reference files (field types, flags, traits, formulas, DSL, security, etc.) and two annotated example modules.
 
 **New here?** Start with **[docs/creating-modules.md](docs/creating-modules.md)** — three ways to scaffold a module (terminal CLI, VS Code sidebar, AI wizard) and when to pick each.
 
@@ -74,7 +74,7 @@ claude mcp list
 # Should show: dforge — npx -y @dforge-core/dforge-mcp — connected
 ```
 
-Or inside a Claude Code session, type `/mcp` to see all connected servers + their tools. The 27 `dforge_*` tools should be listed.
+Or inside a Claude Code session, type `/mcp` to see all connected servers + their tools. The 34 `dforge_*` tools should be listed.
 
 ### Cursor / Zed
 
@@ -82,7 +82,7 @@ Same `command + args` config shape; check their docs for the file location. Veri
 
 ## What it exposes
 
-### Tools (27)
+### Tools (34)
 
 Grouped by typical phase in the wizard flow. All "return" tools emit `{ summary, files: { '<relPath>': '<contents>' } }`; the client decides whether to write — lets the AI preview diffs with the user before committing.
 
@@ -91,11 +91,11 @@ Phase 0 (identity → requirements → design → validation) is orchestrated by
 **Module-level**
 | Tool | Behavior |
 |---|---|
-| `dforge_module_plan` | **Phase 0 orchestrator** — drives identity → requirements → design → validation, returning the next step each call; gates `dforge_module_create` until `readyToScaffold: true`. Call first in any session (`action: "check"`) |
+| `dforge_module_plan` | **Lifecycle orchestrator** — drives Phase 0 (identity → requirements → design → validation), gates `dforge_module_create` until `readyToScaffold: true`, then tracks Phases 1-6 via a ledger in `docs/phase.json`. `action: "check"` returns `currentPhase` + `nextSkill`; `complete_phase` records a phase done or skipped. Call first in any session |
 | `dforge_module_create` | New module scaffold (blocked until Phase 0 passes) |
 | `dforge_module_import` | Import a normalized **table-spec** (tables → columns → relationships) into an existing module as entities. Infers `fieldTypeCd` from SQL type / sample values / name (metadata-validated, `dbDatatype` derived) and builds the FK+Reference pair per relationship. Fed by DBML/SQL, Excel/CSV, or a hand-authored spec |
 | `dforge_module_inspect` | Read current module state. Full structured data is in `files["_inspect.json"]`; `summary` is one-line stats |
-| `dforge_module_validate` | Offline cross-reference check (run before pack): dangling FK targets, missing hidden-FK columns, view/menu/role refs to non-existent things, uncovered entities. Errors + warnings in `files["_validate.json"]` |
+| `dforge_module_validate` | Offline check (run before pack): dangling FK targets, missing hidden-FK columns, view/menu/role refs to non-existent things, uncovered entities, **field-spec rules re-run across every field**, `toString` templates, Formula-vs-Generated set aggregates, missing action DSL files, triggers/jobs firing non-existent actions, DSL static checks, and translation completeness. Errors + warnings in `files["_validate.json"]` |
 | `dforge_module_pack` | Shells to `dforge-cli module pack` via bundled CLI, PATH fallback, or `DFORGE_CLI_BINARY`. Returns tarball path + size |
 | `dforge_module_install` | Shells to `dforge-cli module install`. Args: `pathOrTarball`, optional `tenantUrl` / `token` / `tenantCode` — fall back to `DFORGE_URL` / `DFORGE_TOKEN` env. Returns `ok`, `exitCode`, `command`, and raw CLI `output` so the AI can fix install-time module defects and retry |
 
@@ -110,23 +110,41 @@ Phase 0 (identity → requirements → design → validation) is orchestrated by
 | `dforge_entity_field_rename` | **Refactor-safe rename** — propagates the new name to the paired Reference, formulas, view columns + order, seed data, and other entities' FKs |
 | `dforge_entity_field_remove` | **Refactor-safe remove** — cascade-cleans paired Reference, view columns + order, seed keys; warns on formula/cross-entity dependents |
 
+**Composite entity tools (Phase 1) — one call per concept, prefer these**
+
+Each of these spans several coordinated keys that hand-assembly gets wrong. They exist so the broken shapes aren't expressible.
+
+| Tool | Emits |
+|---|---|
+| `dforge_entity_reference_add` | A whole relation: hidden FK (`cuid`/`EM`) **+** Reference column (`R`/`lookup`/`link`) **+** the `references` entry. The documented #1 source of broken modules, in one call. Also completes a half-built relation by reusing an FK an import already created |
+| `dforge_entity_rollup_add` | A child total as a **Generated** (`G`) column — never a Formula, whose set-aggregates silently render empty — creating the parent's Set column if needed, and refusing to aggregate a virtual `F`/`R`/`S` child (`column old.<field> does not exist`) |
+| `dforge_entity_status_add` | A dropdown with `params.options` objects and the initial value as a `formula` — entity fields have no `defaultValue` key |
+
 The field/entity tools validate against the `@dforge-core/metadata` registry: an unknown `fieldTypeCd` (e.g. `integer`, `reference`), `columnType`, or trait code is rejected at authoring time with a "did you mean" hint, and `dbDatatype` is auto-derived from the field type (currency → `numeric(18,2)`, text → `varchar`; reference/formula columns get none) unless you set it explicitly.
 
 **Behavior (Phase 2 — optional)**
 | Tool | Behavior |
 |---|---|
-| `dforge_action_add` | DSL script + `ui/actions.json` entry |
+| `dforge_action_add` | DSL script + `ui/actions.json` entry. Runs the DSL static checker first — errors reject the call |
+| `dforge_action_check` | Statically check a **draft** `dslBody` before committing, or an `actionCode` already on disk. Catches `TODAY()` in `execute:`, `[field]` in batch/job context, block order, top-level `return`, `:param` placeholders, unknown host functions |
 | `dforge_trigger_add` | DB-event trigger in `logic/triggers.json` (entity event + optional condition → action) |
 | `dforge_job_add` | Scheduled job in `logic/jobs.json` (5-field cron + timeout + action) |
 | `dforge_webhook_add` | Outbound webhook in `logic/webhooks.json` (entity event → POST to endpoint) |
 
-**Views + reports (Phase 3)**
+**Views, menus + reports (Phase 3)**
 | Tool | Behavior |
 |---|---|
 | `dforge_view_add` | Add a data view |
 | `dforge_view_modify` | Replace a view's spec |
+| `dforge_menu_add` | Add a menu leaf or section. Validates `dataViewCode` against `data_views.json`, emits `itemType: "V"` on leaves only, and normalizes icons to the bare form menus require (strips `bi-`) |
 | `dforge_report_add` | Add a report |
+
+**Polish (Phase 4)**
+| Tool | Behavior |
+|---|---|
 | `dforge_setting_add` | Configurable module-level setting |
+| `dforge_translation_sync` | Generate/refresh `translations/<locale>.json` from the module's own contents. Never overwrites existing translated text; fills the role labels that are **completeness-enforced at install**. Defaults to en-US + every `supportedLocales` entry |
+| `dforge_seed_add` | Write a seed file for one entity. Enforces numeric `{entity}_id` PKs, parent-before-child load order, `audit-full` System-user columns, and FKs that point at seeded parents |
 
 **Security (Phase 5)**
 | Tool | Behavior |
@@ -141,23 +159,33 @@ The field/entity tools validate against the `@dforge-core/metadata` registry: an
 | `dforge_dependency_add` | Add a dep on another dForge module |
 | `dforge_dbml_import` | **DBML front-end** to `module_import` — parses DBML (Table blocks, typed columns, inline + top-level refs) into the table-spec, drops the source PK (identity provides `{entity}_id`), and imports. Pass `module` for a greenfield import |
 
-### Resources (13)
+### Writing files: preview vs `apply`
+
+Every patch tool returns `{ summary, files, deletes? }` for the client to write, so the agent can preview a diff with the user first. Passing **`apply: true`** instead writes the files (and honours `deletes`) directly and returns only the paths touched.
 
-| URI | Content |
+```jsonc
+// preview (default) — full file contents come back through the model's context
+{ "moduleDir": "/path/to/mod", "entityName": "order", "fieldName": "note", "field": { ... } }
+
+// apply — writes to disk, returns { applied: true, written: [...], deleted: [...] }
+{ "moduleDir": "/path/to/mod", "entityName": "order", "fieldName": "note", "field": { ... }, "apply": true }
+```
+
+Use `apply` for routine patches inside an already-approved plan, and for every `rename`/`delete` refactor — it guarantees the `deletes` half is applied, which is easy to drop by hand. It refuses to write outside `moduleDir`, and never writes the `_inspect.json` / `_validate.json` / `_action_check.json` report payloads, which only reuse the file-map shape for transport.
+
+### Resources
+
+Served over MCP with descriptions and mime types, so the agent can tell what a URI is for before pulling it.
+
+| URI pattern | Content |
 |---|---|
-| `dforge://schema/manifest` | manifest.json JSON Schema |
-| `dforge://schema/entity` | entity files |
-| `dforge://schema/data-views` | ui/data_views.json |
-| `dforge://schema/folders` | ui/folders.json |
-| `dforge://schema/menus` | ui/menus.json |
-| `dforge://schema/roles` | security/roles.json |
-| `dforge://schema/jobs` | logic/jobs.json |
-| `dforge://schema/seed-data` | seed-data/*.json |
-| `dforge://schema/reports` | ui/reports.json |
-| `dforge://schema/settings` | settings.json |
-| `dforge://schema/traits` | entity trait codes |
-| `dforge://schema/webhooks` | ui/webhooks.json |
+| `dforge://schema/<name>` | JSON Schemas: `manifest`, `entity`, `domains`, `data-views`, `folders`, `menus`, `roles`, `jobs`, `seed-data`, `traits`, `webhooks`, `triggers`, `print-templates`, `settings`, `reports` |
+| `dforge://reference/<name>` | 25 per-element authoring references — schema shape + worked example + common-mistakes list for one element type |
+| `dforge://example/<path>` | Files from the canonical `simple-todo` module (mandatory structure validators) |
+| `dforge://example/matrix-budget/<path>` | Files from the `matrix` (pivot) view example |
 | `dforge://docs/conventions` | MODULE_CONVENTIONS.md |
+| `dforge://docs/dsl` | Full action-DSL grammar, built-ins, patterns, anti-patterns |
+| `dforge://script/xlsx-to-model` | Stdlib Python `.xlsx` → table-spec extractor |
 
 Schemas + conventions are vendored at build time from `iash44/dForge-core`'s `docs/`. The published npm tarball ships them under `resources/`, and jsdelivr serves them at:
 
@@ -167,70 +195,76 @@ https://cdn.jsdelivr.net/npm/@dforge-core/dforge-mcp@latest/resources/schemas/<n
 
 **Compatibility:** schemas vendored for this release came from `iash44/dForge-core` `main` as of the publish date stamped in `package.json`. If the platform adds new entity properties / field types after this release, generated modules using those features may validate locally but be rejected at install time. Bump the dforge-mcp version when the platform schemas change materially.
 
-## Claude Skill — the wizard
+## Claude Skills — router + three stage skills
 
-The skill bundle lives at `skills/dforge-mcp-author/` and contains:
+Authoring guidance ships as **four** skills, split by lifecycle stage. Each stage needs a different half of the knowledge base — Phase 0 needs none of the field-type/DSL detail, Phase 6 needs none of the intake guardrails — so loading only the active stage is what keeps a full module build inside one context window.
+
+| Skill | Phases | Owns |
+|---|---|---|
+| `dforge-mcp-author` | — | **Router. Start here.** Calls `dforge_module_plan` to find the current phase and hands off. Also carries the shared `references/` + `examples/`. |
+| `dforge-module-design` | 0a–0d | Identity, intake guardrails, design doc, pre-scaffold validation. Ends at `readyToScaffold: true`. |
+| `dforge-module-build` | 1–5 | Entities, behavior, views/menus, polish, security. Loading-policy table, core-rules cheat sheet, backtrack protocol. |
+| `dforge-module-ship` | 6 | Validate → pre-pack review → version audit → pack → install-fix loop. |
+
+The handoff is deterministic rather than vibes-based: `dforge_module_plan({ action: "check" })` returns `currentPhase` **and** `nextSkill`, derived from the Phase 0 artifacts, the phase ledger in `docs/phase.json`, and evidence read from the module itself (entities without fields, entities without a view, entities without a Select grant).
+
+The router directory also holds the shared assets:
 
 | Path | Contents |
 |---|---|
-| `SKILL.md` | Six-phase co-pilot wizard |
-| `references/*.md` | 23 detailed reference files (field types, flags, traits, formulas, DSL, security, views, menus, translations, …) |
+| `references/*.md` | 25 reference files (field types, flags, traits, formulas, DSL, security, views, menus, translations, …) |
 | `examples/simple-todo/` | Annotated reference module showing all core patterns |
+| `examples/matrix-budget/` | Worked example for the `matrix` (pivot) view type |
+| `scripts/xlsx_to_model.py` | Stdlib Python `.xlsx` → table-spec extractor |
+
+**Skills are NOT auto-installed by `npm install`** — they ship in the npm tarball, but Claude Code looks in `~/.claude/skills/`, not `node_modules`. Use the installer, which is a Node script so it behaves identically on **Windows (cmd.exe / PowerShell), macOS, Linux, Git Bash and WSL**:
+
+```bash
+# Straight from the published package — no clone needed:
+npx -y -p @dforge-core/dforge-mcp dforge-install-skills
+
+# From a local checkout:
+npm run install-skills
 
-**It is NOT auto-installed by `npm install`** — the skill ships in the npm tarball but Claude Code looks for skills in `~/.claude/skills/`, not in `node_modules`. Sync the whole bundle manually:
+# Equivalently, without npm:
+node scripts/install-skills.mjs [--from-npm]
+```
+
+Destination resolution, in order: `DEST` → `CLAUDE_CONFIG_DIR/skills` → `<home>/.claude/skills`. The home directory comes from Node's `os.homedir()`, so on Windows it's `%USERPROFILE%` no matter which shell invoked it.
 
 ```bash
-# Resolve the actual latest published version from the npm registry,
-# then pin the jsdelivr URL to it. We don't use jsdelivr's `@latest`
-# alias directly — that CDN endpoint caches aggressively (6-12h lag
-# after a new publish), which silently serves stale Skill content.
-VERSION=$(npm view @dforge-core/dforge-mcp version)
-BASE="https://cdn.jsdelivr.net/npm/@dforge-core/dforge-mcp@${VERSION}/skills/dforge-mcp-author"
-
-# Wizard
-mkdir -p ~/.claude/skills/dforge-mcp-author
-curl -fsSL "$BASE/SKILL.md" -o ~/.claude/skills/dforge-mcp-author/SKILL.md
-
-# Reference files (23 guides — load on demand per the table in SKILL.md)
-mkdir -p ~/.claude/skills/dforge-mcp-author/references
-for f in action-dsl column-types conventions data-migration data-views \
-          field-types filters flags formulas jobs manifest menus \
-          number-sequences print-templates queries reports schema-import \
-          security settings traits translations validation-checklist; do
-  curl -fsSL "$BASE/references/${f}.md" \
-    -o ~/.claude/skills/dforge-mcp-author/references/${f}.md
-done
-
-# simple-todo example
-mkdir -p ~/.claude/skills/dforge-mcp-author/examples/simple-todo/{entities,logic/actions,ui,security,seed-data}
-for f in README.md manifest.json; do
-  curl -fsSL "$BASE/examples/simple-todo/$f" \
-    -o ~/.claude/skills/dforge-mcp-author/examples/simple-todo/$f
-done
-# … entity, ui, security, seed-data files follow the same pattern
-
-# Or, straight from GitHub main (always fresh, but pre-release content):
-# curl -fsSL https://raw.githubusercontent.com/dforge-core/dforge-mcp/main/skills/dforge-mcp-author/SKILL.md \
-#   -o ~/.claude/skills/dforge-mcp-author/SKILL.md
+DEST=/path/to/skills npm run install-skills
 ```
 
-> **Note on CLAUDE.md:** Every module gets a `CLAUDE.md` in its root, authored during Phase 0a by the `dforge-mcp-author` skill (the AI drafts it; you write it) and kept current as later phases complete. It tells Claude Code that the directory is a dForge module, instructs it to use the `dforge-mcp-author` skill, describes the module layout, and carries a live **Module status** tracker (which phase is done) so future sessions resume accurately.
+<details>
+<summary>Windows notes</summary>
+
+- **cmd.exe / PowerShell**: `npm run install-skills` works directly. There is no bash requirement.
+- **WSL**: run it from *Windows*, not inside WSL — inside WSL, `os.homedir()` is the Linux home (`/home/you`), so the skills would land where a Windows Claude Code never looks. If you deliberately run Claude Code inside WSL, then installing from WSL is correct.
+- `--from-npm` shells out to `tar`, built into Windows 10 1803+ (and macOS/Linux). Without it, clone the repo and run the installer without `--from-npm`.
+- `scripts/install-skills.sh` still exists and works (it just execs the Node script), so the older `curl … | bash` one-liner keeps working on macOS/Linux/Git Bash.
+
+</details>
 
-Re-run after every dforge-mcp upgrade — the skill version isn't checked at runtime, so a stale skill against new tools will misroute calls.
+It replaces each skill directory wholesale — a stale reference file left behind is worse than a missing one, because the agent will happily author against it.
+
+**Re-run after every dforge-mcp upgrade.** The skill version isn't checked at runtime, so stale skills against new tools will misroute calls.
+
+> **Note on CLAUDE.md:** Every module gets a `CLAUDE.md` in its root, authored during Phase 0a (the AI drafts it; you write it) and kept current as later phases complete. It tells Claude Code that the directory is a dForge module, points at the skills, describes the module layout, and carries a live **Module status** tracker so future sessions resume accurately.
 
 The phases:
 
-| Phase | Required? | Tools used |
-|---|---|---|
-| 0. Identity / requirements / design / validation | yes | (docs authored directly) |
-| 1. Domain | yes | `module_create`, `entity_add`, `entity_field_*` |
-| 2. Actions | optional | `action_add` |
-| 3. Views + Reports | views yes, reports optional | `view_*`, `report_add`, `setting_add` |
-| 4. Polish (translations, seed) | optional | (file map authored directly) |
-| 5. Security | roles required, folders optional | `role_add`, `role_right_set`, `folder_add` |
-| 6. Verify | yes | `module_pack`, `module_install` |
-
-Key principles encoded in the Skill: inspect-before-patch, one-at-a-time, deterministic backtrack on earliest-phase-first rule, tool-failure protocol that distinguishes auth/connectivity from module defects, end-of-session cleanup user-driven.
+| Phase | Required? | Skill | Tools used |
+|---|---|---|---|
+| 0. Identity / requirements / design / validation | yes | design | `module_plan` |
+| 1. Domain | yes | build | `module_create`, `entity_add`, `entity_field_*`, `entity_reference_add`, `entity_rollup_add`, `entity_status_add`, `module_import`, `dbml_import` |
+| 2. Behavior | optional | build | `action_add`, `action_check`, `trigger_add`, `job_add`, `webhook_add` |
+| 3. Views + menus, reports | 3a yes, rest optional | build | `view_*`, `menu_add`, `report_add` |
+| 4. Polish | optional | build | `setting_add`, `translation_sync`, `seed_add` |
+| 5. Security | 5a yes, folders optional | build | `role_add`, `role_right_set`, `folder_add` |
+| 6. Verify | yes | ship | `module_validate`, `module_pack`, `module_install` |
+
+Key principles encoded in the skills: inspect-before-patch, one-at-a-time, composite-tools-first, deterministic backtrack on the earliest-phase-first rule, a tool-failure protocol that distinguishes auth/connectivity from module defects, and user-driven end-of-session cleanup.
 
 ## For maintainers