@dforge-core/dforge-mcp 0.1.0-rc.4 → 0.1.0-rc.6

package/README.md

@@ -1,25 +1,51 @@
 # @dforge-core/dforge-mcp
 
-MCP server for dForge module authoring. Exposes a small set of 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 18 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/SKILL.md`) that walks the AI through six phases with explicit backtrack support when later phases expose earlier gaps.
 
-## Install
+**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.
+
+> **Two GitHub repos to know:** this MCP server lives at `dforge-core/dforge-mcp`. The dForge platform itself (entities, validator, native CLI source) lives at `iash44/dForge-core` — referenced in `homepage` because the schemas + DSL conventions come from there.
+
+## What it depends on at runtime
+
+```
+your AI editor (Claude Code / Cursor / Zed)
+    │
+    ▼ stdio JSON-RPC
+@dforge-core/dforge-mcp       ← this package; pure JS / TS
+    │
+    ▼ shells out for pack / install
+@dforge-core/dforge-cli        ← installed as a transitive dep; thin JS wrapper
+    │
+    ▼ optionalDependencies
+@dforge-core/dforge-cli-<platform>   ← native C# binary per platform (~35 MB)
+```
+
+The native binary actually talks to your tenant. The npm-CLI wrapper is just a launcher that picks the right platform binary and exec's it. **You don't need to install dforge-cli separately** — it comes along when you install dforge-mcp (or when `npx -y @dforge-core/dforge-mcp` runs cold).
+
+If you want to use a hand-built native binary instead of the npm-shipped one, point `DFORGE_CLI_BINARY` at the executable file's absolute path:
 
 ```bash
-# As an MCP server invoked by an AI editor — usually no install needed,
-# the editor runs it via npx on demand. See "Wiring it up" below.
+DFORGE_CLI_BINARY=/Users/me/projects/dForge-core/cli/bin/dForge.Cli
+```
+
+(macOS / Linux: no extension. Windows: `dForge.Cli.exe`.) If the path doesn't exist or isn't executable the server reports an error at the first pack/install call.
+
+## Install + wire into Claude Code
 
-# Local install (for development / debugging):
-npm install -g @dforge-core/dforge-mcp
-dforge-mcp                # speaks JSON-RPC over stdio; ctrl+C to quit
+### Recommended — via `claude mcp add` (writes ~/.claude.json for you)
+
+```bash
+claude mcp add dforge --scope user -- npx -y @dforge-core/dforge-mcp
 ```
 
-## Wiring it up
+This appends to `~/.claude.json` (the global config — single file in your home dir, no subdirectory). Restart Claude Code; on the first session that activates the server you'll see "Approve MCP server 'dforge'?" — accept it.
 
-### Claude Code
+### Manual — per-project
 
-Add to `~/.claude/config.json` (or the project-local `.claude/mcp.json`):
+Write `.mcp.json` at **the repo root** (not under `.claude/`):
 
 ```json
 {
@@ -28,40 +54,49 @@ Add to `~/.claude/config.json` (or the project-local `.claude/mcp.json`):
       "command": "npx",
       "args": ["-y", "@dforge-core/dforge-mcp"],
       "env": {
-        "DFORGE_CLI_BINARY": "/optional/path/to/dForge.Cli"
+        "DFORGE_CLI_BINARY": "/optional/abs/path/to/dForge.Cli"
       }
     }
   }
 }
 ```
 
-`DFORGE_CLI_BINARY` is only needed if you want `dforge_module_pack` / `dforge_module_install` to use a non-published native binary (e.g. a local C# build). Otherwise the server uses whatever `dforge-cli` is on PATH (install via `npm install -g @dforge-core/dforge-cli`, or let npx fetch it on demand).
+Restart Claude Code → approve on first prompt.
+
+### Verify it's alive
+
+```bash
+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 18 `dforge_*` tools should be listed.
 
 ### Cursor / Zed
 
-Same shape — both editors take a `command + args` MCP config. Refer to their docs for the exact file path.
+Same `command + args` config shape; check their docs for the file location. Verification is via their respective tool listings.
 
 ## What it exposes
 
 ### Tools (18)
 
-Grouped by typical phase in the wizard flow. All return-not-write tools emit a `{ summary, files: { '<relPath>': '<contents>' } }` map; the client decides whether to write the files (lets the AI preview diffs with the user before committing).
+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.
 
 **Module-level**
 | Tool | Behavior |
 |---|---|
-| `dforge_module_create` | New module scaffold — file map for the client to write |
-| `dforge_module_inspect` | Read current module state from disk; returns structured summary of entities, views, roles, actions, etc. Call this BEFORE any patch |
+| `dforge_module_create` | New module scaffold |
+| `dforge_module_inspect` | Read current module state. Full structured data is in `files["_inspect.json"]`; `summary` is one-line stats |
 | `dforge_module_pack` | Shells to `dforge-cli module pack`. Returns tarball path + size |
-| `dforge_module_install` | Shells to `dforge-cli module install`. Runs the full server-side validator — the only real validator |
+| `dforge_module_install` | Shells to `dforge-cli module install`. Args: `pathOrTarball`, optional `tenantUrl` / `token` / `tenantCode` — fall back to `DFORGE_URL` / `DFORGE_TOKEN` env. `tenantCode` is an optional `--code` sanity check the server cross-references against the JWT |
 
 **Entities (Phase 1)**
 | Tool | Behavior |
 |---|---|
 | `dforge_entity_add` | Add an entity to an existing module |
-| `dforge_entity_field_add` | Patch a single field onto an existing entity |
+| `dforge_entity_field_add` | Patch a single field |
 | `dforge_entity_field_modify` | Replace a field's spec |
-| `dforge_entity_field_remove` | Drop a field (warns about dependent views / roles / formulas) |
+| `dforge_entity_field_remove` | Drop a field (warns about dependents) |
 
 **Behavior (Phase 2 — optional)**
 | Tool | Behavior |
@@ -73,81 +108,79 @@ Grouped by typical phase in the wizard flow. All return-not-write tools emit a `
 |---|---|
 | `dforge_view_add` | Add a data view |
 | `dforge_view_modify` | Replace a view's spec |
-| `dforge_report_add` | Add a report (layout + datasets + parameters) |
-| `dforge_setting_add` | Configurable module-level setting (folder-scoped at runtime) |
+| `dforge_report_add` | Add a report |
+| `dforge_setting_add` | Configurable module-level setting |
 
 **Security (Phase 5)**
 | Tool | Behavior |
 |---|---|
-| `dforge_role_add` | Add a role + per-object rights matrix |
-| `dforge_role_right_set` | Grant/revoke a single right on a single object (cheap backtrack) |
-| `dforge_folder_add` | Add a security folder under root or a parent path (optional — most modules ship with just the root) |
+| `dforge_role_add` | Add a role + rights matrix. **Fails if role already exists** — the scaffolder pre-creates `<code>.admin`, so use `role_right_set` to amend it instead |
+| `dforge_role_right_set` | Grant/revoke one right on one object (cheap backtrack) |
+| `dforge_folder_add` | Add a security folder (optional — most modules ship with just root) |
 
 **Cross-cutting**
 | Tool | Behavior |
 |---|---|
-| `dforge_dependency_add` | Add a dep on another dForge module (supports the `{ version, entities }` partial-coupling form) |
-| `dforge_dbml_import` | Stub. Returns "not yet implemented" until the underlying CLI command lands |
+| `dforge_dependency_add` | Add a dep on another dForge module |
+| `dforge_dbml_import` | Stub — not implemented yet |
 
 ### Resources (13)
 
-Read-only context. Pull these into the conversation at session start; the wizard Skill instructs the AI to consult schemas before emitting files of each kind.
-
 | URI | Content |
 |---|---|
-| `dforge://schema/manifest` | JSON Schema for manifest.json |
-| `dforge://schema/entity` | JSON Schema for entity files |
-| `dforge://schema/data-views` | JSON Schema for ui/data_views.json |
-| `dforge://schema/folders` | JSON Schema for ui/folders.json |
-| `dforge://schema/menus` | JSON Schema for ui/menus.json |
-| `dforge://schema/roles` | JSON Schema for security/roles.json |
-| `dforge://schema/jobs` | JSON Schema for logic/jobs.json |
-| `dforge://schema/seed-data` | JSON Schema for seed-data/*.json |
-| `dforge://schema/reports` | JSON Schema for ui/reports.json |
-| `dforge://schema/settings` | JSON Schema for settings.json |
-| `dforge://schema/traits` | JSON Schema for entity trait codes |
-| `dforge://schema/webhooks` | JSON Schema for ui/webhooks.json |
-| `dforge://docs/conventions` | MODULE_CONVENTIONS.md — naming, FK+Reference pattern, traits, security model |
-
-Schemas + conventions are vendored at build time from `dForge-core/docs/`. Refresh with `scripts/vendor-resources.sh`. The published npm tarball ships them under `resources/`, and jsdelivr serves them publicly at:
+| `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://docs/conventions` | MODULE_CONVENTIONS.md |
+
+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:
 
 ```
 https://cdn.jsdelivr.net/npm/@dforge-core/dforge-mcp@latest/resources/schemas/<name>.schema.json
 ```
 
-The dForge VS Code extension bundles them locally (no jsdelivr dependency at runtime).
+**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
 
-`skills/dforge-mcp-author/SKILL.md` teaches the AI how to drive the tools as a six-phase wizard:
+`skills/dforge-mcp-author/SKILL.md` teaches Claude how to drive the tools as a six-phase wizard. **It is NOT auto-installed by `npm install` — the Skill file ships in the npm tarball but Claude Code looks for Skills in `~/.claude/skills/`, not in node_modules.** Sync it manually:
+
+```bash
+# from the published npm tarball
+mkdir -p ~/.claude/skills/dforge-mcp-author
+curl -fsSL https://cdn.jsdelivr.net/npm/@dforge-core/dforge-mcp@latest/skills/dforge-mcp-author/SKILL.md \
+  -o ~/.claude/skills/dforge-mcp-author/SKILL.md
+
+# or from this repo
+mkdir -p ~/.claude/skills/dforge-mcp-author
+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
+```
+
+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.
+
+The phases:
 
 | Phase | Required? | Tools used |
 |---|---|---|
-| 0. Intake | yes | (none — captures a brief in `_brief/00-intake.md`) |
-| 1. Domain (entities) | yes | `module_create`, `entity_add`, `entity_field_*` |
+| 0. Intake | yes | (brief written manually) |
+| 1. Domain | yes | `module_create`, `entity_add`, `entity_field_*` |
 | 2. Actions | optional | `action_add` |
-| 3. Views + Reports | views yes, reports optional | `view_add`/`_modify`, `report_add`, `setting_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.** `module_inspect` is the first call in any session that touches an existing module.
-- **One thing at a time.** Loop per-entity / per-view / per-role, not batch dumps.
-- **Backtrack protocol.** When a later phase exposes a gap from earlier, the AI stops, names the issue, gets user sign-off, patches via the smallest tool that fits, propagates forward.
-- **Changelog.** Each backtrack appends to `_brief/changelog.md` so the user has a paper trail.
-- **Verify-or-it-didn't-happen.** Phase 6 install is non-skippable — it's the only true validator.
-
-**To enable the Skill in Claude Code:**
-
-```bash
-mkdir -p ~/.claude/skills/dforge-mcp-author
-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
-# or project-local:
-mkdir -p .claude/skills/dforge-mcp-author
-cp <repo>/skills/dforge-mcp-author/SKILL.md .claude/skills/dforge-mcp-author/
-```
+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.
 
 ## For maintainers
 
@@ -157,15 +190,15 @@ cp <repo>/skills/dforge-mcp-author/SKILL.md .claude/skills/dforge-mcp-author/
 pnpm install
 pnpm build          # tsup → dist/server.js (bundles SDK + zod + dforge-cli/templates)
 pnpm typecheck      # tsc --noEmit
-node dist/server.js # smoke-test via stdio JSON-RPC
+node dist/server.js # stdio JSON-RPC — pipe a request to smoke-test
 ```
 
-To iterate against an in-tree `dforge-cli`, temporarily point the dep at it:
+To iterate against an in-tree `dforge-cli`, temporarily pin the dep at the sibling path:
 
 ```bash
-sed -i '' 's|"@dforge-core/dforge-cli": "\^0.1.0"|"@dforge-core/dforge-cli": "file:../dforge-cli"|' package.json
+sed -i '' 's|"@dforge-core/dforge-cli": "\^0.1.[0-9.]*"|"@dforge-core/dforge-cli": "file:../dforge-cli"|' package.json
 rm -rf node_modules pnpm-lock.yaml && pnpm install
-# Flip back before publish, otherwise the published package.json is unresolvable for consumers.
+# Flip back before publish — file: deps don't resolve for npm consumers.
 ```
 
 ### Refresh vendored resources
@@ -177,21 +210,27 @@ scripts/vendor-resources.sh                              # auto-locate ../dForge
 DFORGE_CORE=/abs/path/to/dForge-core scripts/vendor-resources.sh
 ```
 
-This refreshes `resources/schemas/` and `resources/docs/`. Republish the npm package to update jsdelivr-served schemas. The VS Code extension vendors them at its own build time, so a separate VS Code repackage is needed for that consumer too.
+Republish to update jsdelivr-served schemas + the bundled resources.
 
-### Publishing to npm
+### Publishing
 
 ```bash
 scripts/publish.sh 0.1.0-rc.N --tag latest --otp <code>
 ```
 
-`prepublishOnly` runs `tsup` so the published tarball gets a fresh `dist/server.js`. No platform binaries to manage — one publish covers everything.
+`prepublishOnly` runs `tsup` so the tarball gets a fresh `dist/server.js`. No platform binaries to manage.
+
+**Pre-publish checklist:**
+- [ ] `@dforge-core/dforge-cli` dep is a real version (not `file:...`)
+- [ ] `pnpm typecheck` passes
+- [ ] Smoke test stdio: `tools/list` returns 18 tools
+- [ ] Skill updated for any new/changed tools (it's a SEPARATE artifact; users sync it manually after upgrades)
 
 ### Adding a new tool
 
 1. Drop it in `src/tools/<name>.ts`. Use shared helpers from `src/tools/_helpers.ts` (`loadManifest`, `readJsonOrDefault`, `jsonText`, `makeResult`, `withTodayStamp`). Return a `ToolResult`.
 2. Import + register in `src/server.ts` via the `envelope()` wrapper.
-3. Mention it in the wizard `SKILL.md` if it fits a phase.
+3. Mention it in `skills/dforge-mcp-author/SKILL.md` (which phase, which backtrack scenarios use it).
 4. Bump `package.json` version, publish.
 
 Conventions:

package/docs/creating-modules.md

@@ -0,0 +1,145 @@
+# Creating a dForge module — three paths
+
+dForge gives you three ways to scaffold and author a module. They all produce the same canonical file structure; pick by how much hand-holding you want.
+
+| Path | Driver | Best for |
+|---|---|---|
+| [1. Terminal CLI](#path-1--terminal-manual-dforge-cli-init-module) | you, typing | you know what you're building, just want the skeleton |
+| [2. VS Code sidebar](#path-2--vs-code-sidebar-manual) | you, clicking | same as #1 but launched from a button |
+| [3. AI co-pilot wizard](#path-3--ai-co-pilot-wizard-driven) | Claude Code / Cursor / Zed via `dforge-mcp` | you want help designing entities + security |
+
+## Path 1 — Terminal, manual (`dforge-cli init module`)
+
+Pure CLI. Prompts for the basics, writes a minimal scaffold, leaves you to fill in fields / views / roles in your editor.
+
+```bash
+npx -y @dforge-core/dforge-cli init module ./my-module
+```
+
+You'll be asked for:
+- module `code` (lowercase, hyphen/underscore, e.g. `feedback`)
+- display name
+- description, author, license, version, db schema version
+- dependencies (defaults to `admin` + `metadata`)
+- preset (Minimal / Minimal + add more entities interactively / Full template)
+- first entity name + label + traits (identity vs identity+audit)
+
+Output: ~10 files including `manifest.json`, `entities/<name>.json` (stub), `ui/{data_views,folders,menus,actions}.json`, `security/roles.json`, `.gitignore`, plus `.vscode/settings.json` + `.zed/settings.json` that bind the JSON schemas for inline validation.
+
+After scaffolding, open the directory in VS Code (with [the dForge extension](https://github.com/dforge-core/dforge-editor-support) installed) and start adding fields — schemas validate in real time.
+
+## Path 2 — VS Code sidebar, manual
+
+Same scaffold as Path 1, just launched from a button instead of the terminal.
+
+1. Click the dForge `d` icon in the activity bar.
+2. Click the `+` button next to "Modules" view title.
+3. Pick a parent folder + module name in the prompts.
+4. The extension shells out to `npx -y @dforge-core/dforge-cli init module …` in the dForge terminal — same questions as Path 1.
+5. Module appears in the sidebar tree once written; click any file to open it.
+
+Sidebar also gives you right-click commands: **Pack Module**, **Install Module to Tenant**, **Validate Module (schemas)** — all wrappers around `dforge-cli`.
+
+## Path 3 — AI co-pilot, wizard-driven
+
+Claude Code (or Cursor / Zed) with `dforge-mcp` connected. You describe what you want; the AI walks you through six phases via MCP tool calls, pausing at each gate for your approval.
+
+Setup once:
+
+```bash
+claude mcp add dforge --scope user -- npx -y @dforge-core/dforge-mcp
+mkdir -p ~/.claude/skills/dforge-mcp-author
+curl -fsSL https://cdn.jsdelivr.net/npm/@dforge-core/dforge-mcp@latest/skills/dforge-mcp-author/SKILL.md \
+  -o ~/.claude/skills/dforge-mcp-author/SKILL.md
+```
+
+Restart Claude Code, approve the MCP server on first prompt, then in a new conversation:
+
+```
+You: "I want a module to collect end-user feedback on app pages."
+```
+
+The wizard runs:
+
+### Phase 0 — Intake (required, ~1 turn)
+
+Four questions in one message: purpose / users / dependencies / language scope.
+You can accept defaults to move fast. Writes `_brief/00-intake.md`.
+
+### Phase 1 — Domain (required, looping)
+
+1. Proposes an entity inventory (list of names + one-liners). Get user sign-off.
+2. Calls `dforge_module_create` → previews the file map → you approve → AI writes files.
+3. Per-entity loop: proposes fields, calls `dforge_entity_field_add` per field. Batches obvious scalar fields; one-at-a-time for refs/formulas/nullable-ambiguous.
+4. Extension entities last (those with `extends: "module.entity"`).
+
+### Phase 2 — Actions (optional)
+
+Asks if any business-logic operations need a DSL script. Skipped for pure CRUD modules. When needed: `dforge_action_add` per action, full DSL body composed by the AI.
+
+### Phase 3 — Views (required) + Reports (optional)
+
+- **3a (first):** ensures every entity has a default grid via `dforge_view_add` / `view_modify`.
+- **3b (only after 3a):** proposes specialized views (kanban / calendar / list / tree-grid / master-detail) **only when an objective trigger fires** — user explicitly asked, or status field has 3+ values, or required date field for scheduling, etc.
+- **3c (optional):** reports for aggregation/grouping the views don't cover.
+
+### Phase 4 — Polish (mostly optional)
+
+Settings (`dforge_setting_add`), translations, seed data — only if intake declared a need.
+
+### Phase 5 — Security
+
+- **5a (required):** inspects scaffolded `<code>.admin` role; adds extra roles via `dforge_role_add` for each additional user group from intake; amends admin via `dforge_role_right_set` for action/report grants.
+- **5b (optional):** security folders with row-level filters via `dforge_folder_add` — only when intake says data must be partitioned per folder.
+
+### Phase 6 — Verify (required, non-skippable)
+
+1. `dforge_module_pack` → `.dforge` tarball.
+2. `dforge_module_install` against your tenant (uses `DFORGE_URL` / `DFORGE_TOKEN` env or arg fallbacks). Runs the full server-side validator — the only real validator.
+3. On failure, the AI follows the **backtrack protocol**: stops, names the issue, identifies the earliest broken phase, asks for sign-off, patches with the smallest tool that fits, re-inspects, resumes.
+
+---
+
+## Behind the scenes (same for all three paths)
+
+All three paths produce the same canonical structure:
+
+```
+my-module/
+├── manifest.json                  # module metadata
+├── entities/<entity>.json         # one file per entity
+├── ui/
+│   ├── data_views.json            # grids, kanbans, calendars, etc.
+│   ├── folders.json               # navigation + security boundaries
+│   ├── menus.json                 # left-side nav
+│   ├── actions.json               # action registry (DSL files live in logic/actions/)
+│   └── reports.json               # report definitions (only if you have any)
+├── security/
+│   └── roles.json                 # role → rights matrix
+├── logic/
+│   ├── actions/<name>.dsl         # one DSL file per action
+│   └── jobs.json                  # scheduled jobs (only if you have any)
+├── settings.json                  # module-level settings (folder-scoped at runtime)
+├── seed-data/                     # rows inserted at install time (optional)
+├── translations/<locale>.json     # i18n (only if non-English locales declared)
+├── .vscode/settings.json          # auto-binds JSON schemas → red squigglies on bad JSON
+└── .zed/settings.json             # same for Zed
+```
+
+VS Code with the [dForge extension](https://github.com/dforge-core/dforge-editor-support) installed validates every JSON file against its schema as you edit, regardless of which path created the files. Pack and install commands work the same way from any path.
+
+## Quick decision tree
+
+| Goal | Path |
+|---|---|
+| "I know what I want, give me the skeleton" | **Path 1 or 2** |
+| "I want help designing entities + the security model" | **Path 3** — the wizard |
+| "I want to extend an EXISTING module" | **Path 3** — the wizard's patch tools (`entity_field_add`, `role_right_set`, etc.) plus the backtrack protocol shine here |
+| "I'm in a terminal-only environment (SSH, remote box)" | **Path 1** |
+| "I want zero typing" | **Path 2** or **Path 3** |
+
+## Going further
+
+- [SKILL.md](../skills/dforge-mcp-author/SKILL.md) — the full wizard spec the AI follows, including the deterministic backtrack protocol, multi-trigger priority rule, tool-failure protocol, and resume-from-partial-state support
+- [README.md](../README.md) — full tool reference (18 tools, 13 resources) + maintainer docs
+- [iash44/dForge-core](https://github.com/iash44/dForge-core) — the platform itself: source of truth for the schemas + DSL conventions

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@dforge-core/dforge-mcp",
-	"version": "0.1.0-rc.4",
+	"version": "0.1.0-rc.6",
 	"description": "MCP server for dForge module authoring. Exposes scaffold/pack/install tools and schema resources so AI agents (Claude Code, Cursor, Zed) can create and ship dForge modules.",
 	"license": "MIT",
 	"homepage": "https://github.com/iash44/dForge-core",
@@ -13,6 +13,7 @@
 	},
 	"files": [
 		"dist/",
+		"docs/",
 		"resources/",
 		"skills/",
 		"README.md"

package/skills/dforge-mcp-author/SKILL.md

@@ -13,7 +13,7 @@ The phase column below indicates the **typical** use. During a backtrack, the ba
 
 | Tool | Typical phase | What it does |
 |---|---|---|
-| `dforge_module_inspect` | any | Read current module state. **Read-only** — its output does NOT require user confirmation to view; you summarize it and continue. |
+| `dforge_module_inspect` | any | Read current module state. **Read-only** — output does NOT require user confirmation. The one-line `summary` is for the user; the full structured state lives in `files["_inspect.json"]` (entities + their fields, views + their data sources, roles + rights matrix, actions, reports, settings, folders tree). Parse `_inspect.json` before planning patches — don't rely on summary text alone. |
 | `dforge_module_create` | 1 | Scaffold a new module (returns file map; user writes) |
 | `dforge_entity_add` | 1 | Add a whole entity to an existing module |
 | `dforge_entity_field_add` | 1 | Patch one field onto an existing entity |
@@ -121,7 +121,9 @@ When the user has a real business operation: read the DSL reference section of `
 
 ### 3a. Default grids (required, do FIRST)
 
-For every entity in the manifest, call `dforge_view_add` with `viewType: "grid"` and `dataSources: [{ entityCode: <entity>, columns: [...] }]`. Use `viewName: "default"` for the first grid per entity — this is **mandatory**; the platform looks for it.
+For every entity in the manifest, call `dforge_view_add` with `viewType: "grid"` and `dataSources: [{ entityCode: <entity>, columns: [...] }]`.
+
+**View naming.** View codes in `ui/data_views.json` are semantic — convention is the entity name (`feedback_item`), the plural (`invoices`), or descriptive (`invoices_kanban`, `feedback_by_status`). Do NOT use the literal code `default`. When `ui/folders.json` entities reference `viewName: "default"`, the platform resolves that to the entity's first view declared in `data_views.json` — it's a fallback alias, not a required view code. (The scaffolder already wrote a default grid keyed by entity code in Phase 1, so often you'll `view_modify` it rather than `view_add`.)
 
 **Do not propose any specialized view until every entity has its default grid.**
 
@@ -159,9 +161,10 @@ Add reports only when management aggregation/grouping isn't covered by views. `d
 
 ### 5a. Roles + rights matrix (required)
 
-1. Inventory roles. Default for simple modules: one `<code>.admin` role with full rights on everything. If intake mentioned multiple user groups, propose one role per group.
-2. Show the rights matrix as a table (rows = entities/actions/reports, columns = roles, cells = rights string). Get user sign-off.
-3. Call `dforge_role_add` per role. Use `dforge_role_right_set` for one-off edits.
+1. **Inspect first.** Run `dforge_module_inspect` and read the `roles` array. The scaffolder pre-creates `<code>.admin` with `SIUDC` on every entity declared at scaffold time. That role exists already — don't try to re-create it.
+2. Inventory roles. Default for simple modules: the existing `<code>.admin` covers admins; add one role per additional user group from intake (e.g. `<code>.user`, `<code>.viewer`).
+3. Show the rights matrix as a table (rows = entities/actions/reports, columns = roles, cells = rights string). Get user sign-off.
+4. **For new roles**: call `dforge_role_add`. **For amending existing roles** (the scaffolded admin, or grants on actions/reports added in Phases 2-3 that aren't yet in any role): call `dforge_role_right_set` per grant — it's the smallest tool and doesn't conflict with the scaffolded admin role. Calling `dforge_role_add` against an existing role code fails — use `role_right_set` to amend instead.
 
 **Rights semantics** (additive — multiple roles UNION, never revoke):
 - Entities: any subset of `SIUDC` (Select / Insert / Update / Delete / Clone)