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

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@dforge-core/dforge-mcp",
-	"version": "0.1.0-rc.3",
+	"version": "0.1.0-rc.4",
 	"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",
@@ -27,7 +27,7 @@
 		"typecheck": "tsc --noEmit"
 	},
 	"dependencies": {
-		"@dforge-core/dforge-cli": "^0.1.0",
+		"@dforge-core/dforge-cli": "^0.1.2",
 		"@modelcontextprotocol/sdk": "^1.29.0",
 		"zod": "^4.4.3"
 	},

package/resources/schemas/entity.schema.json

@@ -33,8 +33,7 @@
 			"description": "SQL SELECT statement for view-backed entities (isView=true). Executed as CREATE OR REPLACE VIEW during module install."
 		},
 		"toString": {
-			"type": "string",
-			"description": "Display pattern using column placeholders, e.g. \"{first_name} {last_name}\""
+			"description": "Display pattern using column placeholders, e.g. \"{first_name} {last_name}\". Optional in extension entities (with `extends`). No `type` constraint here because `toString` collides with Object.prototype.toString in JSON validators — they read the inherited function and reject it, even when the property is absent from the JSON."
 		},
 		"traits": {
 			"type": "array",

package/resources/schemas/folders.schema.json

@@ -2,15 +2,11 @@
 	"$schema": "http://json-schema.org/draft-07/schema#",
 	"$id": "https://dforge.dev/schemas/folders.schema.json",
 	"title": "dForge Folders",
-	"description": "Folder definitions for a dForge module",
-	"type": "object",
-	"additionalProperties": {
-		"$ref": "#/$defs/folder"
-	},
+	"description": "Folder tree for a dForge module. The file IS the root folder (not a map keyed by code). Sub-folders live under `children`, keyed by folder code.",
+	"$ref": "#/$defs/folder",
 	"$defs": {
 		"folder": {
 			"type": "object",
-			"required": ["label"],
 			"properties": {
 				"label": {
 					"type": "string",
@@ -18,19 +14,19 @@
 				},
 				"description": {
 					"type": "string",
-					"description": "Optional description text (shown in breadcrumb/header area)"
+					"description": "Optional description text (shown in breadcrumb / header area)"
 				},
 				"parentCode": {
 					"type": ["string", "null"],
-					"description": "Parent folder code (null for root folders)"
+					"description": "Parent folder code. Usually omitted: nested folders go under `children` of their parent. Only used by sparse-tree imports."
 				},
 				"folderPath": {
 					"type": "string",
-					"description": "URL-friendly folder path"
+					"description": "URL-friendly folder path override"
 				},
 				"color": {
 					"type": "string",
-					"description": "Folder accent color (hex)"
+					"description": "Folder accent color (hex, e.g. '#2196F3')"
 				},
 				"icon": {
 					"type": "string",
@@ -38,14 +34,21 @@
 				},
 				"inheritSecurity": {
 					"type": "boolean",
-					"description": "Whether to inherit security from parent folder"
+					"description": "Whether to inherit security rights from the parent folder. Default: true."
 				},
 				"entities": {
 					"type": "object",
-					"description": "Entity code → folder-entity config",
+					"description": "Entity code → folder-entity binding (which view to show, quick-add, row-level filter).",
 					"additionalProperties": {
 						"$ref": "#/$defs/folderEntity"
 					}
+				},
+				"children": {
+					"type": "object",
+					"description": "Nested folders keyed by sub-folder code. Recursive — children can have their own children.",
+					"additionalProperties": {
+						"$ref": "#/$defs/folder"
+					}
 				}
 			},
 			"additionalProperties": false
@@ -55,14 +58,48 @@
 			"properties": {
 				"viewName": {
 					"type": "string",
-					"description": "Entity view name to use in this folder"
+					"description": "Entity view name (data view code) to use in this folder. Common values include 'default'."
 				},
 				"quickAdd": {
 					"type": "boolean",
-					"description": "Enable quick-add for this entity in this folder"
+					"description": "Enable the quick-add (+) button for this entity in this folder"
 				},
 				"rowFilter": {
-					"description": "Row-level filter criteria for this entity in this folder"
+					"description": "Row-level filter. Either a SQL expression string (e.g. \"is_customer = true\") or a canonical filter object (`{c,o,v}` for one condition, `{g,i:[]}` for a group).",
+					"oneOf": [
+						{ "type": "string" },
+						{ "$ref": "#/$defs/filter" }
+					]
+				}
+			},
+			"additionalProperties": false
+		},
+
+		"filter": {
+			"description": "Canonical dForge filter expression — same shape as in data_views.json. Either `{c, o, v}` or `{g, i: [...]}`.",
+			"oneOf": [
+				{ "$ref": "#/$defs/filterCondition" },
+				{ "$ref": "#/$defs/filterGroup" }
+			]
+		},
+		"filterCondition": {
+			"type": "object",
+			"required": ["c", "o"],
+			"properties": {
+				"c": { "type": "string" },
+				"o": { "type": "string" },
+				"v": {}
+			},
+			"additionalProperties": false
+		},
+		"filterGroup": {
+			"type": "object",
+			"required": ["g", "i"],
+			"properties": {
+				"g": { "type": "string", "enum": ["and", "or"] },
+				"i": {
+					"type": "array",
+					"items": { "$ref": "#/$defs/filter" }
 				}
 			},
 			"additionalProperties": false

package/resources/schemas/manifest.schema.json

@@ -21,6 +21,12 @@
 			"pattern": "^[a-z][a-z0-9_-]*$",
 			"description": "Human-readable module code (becomes schema name and module_cd in DB)"
 		},
+		"kind": {
+			"type": "string",
+			"enum": ["module", "pack"],
+			"default": "module",
+			"description": "Package kind. 'module' (default) — a regular module with its own entities/views/actions. 'pack' — a dependency bundle: installs a curated set of other modules via `dependencies` in order, owns no entities itself."
+		},
 		"version": {
 			"type": "string",
 			"pattern": "^\\d+\\.\\d+\\.\\d+",
@@ -68,12 +74,37 @@
 		},
 		"dependencies": {
 			"type": "object",
-			"description": "Module dependencies: module code → semver range",
+			"description": "Module dependencies: module code → semver range OR { version, entities? } object for partial deps that only import specific entities from the dependency.",
 			"additionalProperties": {
-				"type": "string",
-				"description": "Semver version range (e.g. '>=1.0.0')"
+				"oneOf": [
+					{
+						"type": "string",
+						"description": "Semver version range (e.g. '>=1.0.0')"
+					},
+					{
+						"type": "object",
+						"required": ["version"],
+						"properties": {
+							"version": {
+								"type": "string",
+								"description": "Semver version range"
+							},
+							"entities": {
+								"type": "array",
+								"items": { "type": "string" },
+								"description": "Entity codes from the dependency that this module needs. If omitted, all entities are accessible."
+							}
+						},
+						"additionalProperties": false
+					}
+				]
 			}
 		},
+		"auditHistory": {
+			"type": "string",
+			"enum": ["none", "minimal", "full"],
+			"description": "Default audit history mode for entities in this module ('full' captures every field change; 'minimal' captures only inserts/deletes; 'none' disables). Individual entities can override."
+		},
 		"entities": {
 			"type": "object",
 			"description": "Entity definitions and extensions: entity code → relative path to entity JSON file. Dotted keys (e.g. 'fin.invoice') indicate extensions of other modules' entities (the entity file must have an 'extends' property).",

package/resources/schemas/menus.schema.json

@@ -37,7 +37,7 @@
 		},
 		"menuItem": {
 			"type": "object",
-			"required": ["orderNum", "label"],
+			"required": ["label"],
 			"properties": {
 				"itemType": {
 					"type": ["string", "null"],

package/resources/schemas/reports.schema.json

@@ -159,10 +159,27 @@
 					"description": "Field type code (see settings.schema.json for the common list)"
 				},
 				"label": { "type": "string" },
-				"required": { "type": "boolean", "default": false },
+				"required": {
+					"type": "boolean",
+					"default": false,
+					"description": "Whether the user must provide a value (older modules also use `isRequired`)"
+				},
+				"isRequired": {
+					"type": "boolean",
+					"description": "Alternate spelling of `required` used by some modules. Prefer `required` for new code."
+				},
 				"default": {
 					"description": "Default value applied if the user doesn't provide one"
 				},
+				"link": {
+					"type": "object",
+					"description": "Entity link for lookup-type params (alternative to nesting under `params.link`). Shape: { entity: '<code>', otherKey?: '<column>' }.",
+					"properties": {
+						"entity": { "type": "string" },
+						"otherKey": { "type": "string" }
+					},
+					"additionalProperties": false
+				},
 				"params": {
 					"type": "object",
 					"description": "Field-type-specific params (e.g. lookup → { link: { entity, otherKey } })"

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

@@ -1,116 +1,227 @@
 ---
 name: dforge-mcp-author
-description: Author dForge modules using the dforge-mcp tool surface. Use when the user has the @dforge-core/dforge-mcp MCP server connected and asks to scaffold, extend, pack, or install a dForge module. Replaces hand-writing JSON files with structured tool calls that produce schema-valid output on the first try.
+description: Co-pilot for authoring dForge modules via the dforge-mcp tool surface. Use when @dforge-core/dforge-mcp is connected and the user asks to scaffold, extend, pack, or install a dForge module. Drafts and proposes; the user approves at named gates. Walks the user through six phases with explicit gates for confirmation, a deterministic backtrack protocol, a tool-failure protocol, and resume-from-partial-state support.
 ---
 
-# dForge Module Author (MCP-driven)
+# dForge Module Author — Co-pilot
 
-You're authoring a dForge module via the `dforge-mcp` MCP server. dForge is a metadata-driven, multi-tenant business platform — modules are JSON metadata + DSL scripts.
+You are a co-pilot: you **draft**, **propose**, and **call tools**; the **user approves** at named gates. Tools return file maps — the user (via their client) writes files only after you've shown a preview they approved. Never write without confirmation.
 
-**Your edge here** is that you have *tools*, not just text generation. Always prefer a tool call over writing a file by hand. Every tool either returns a file map (so the user can preview before commit) or shells out to the validated native CLI.
+## Tool reference
 
----
-
-## Tool surface
+The phase column below indicates the **typical** use. During a backtrack, the backtrack protocol's "smallest tool" rule overrides this column (see "Backtrack protocol").
 
-| Tool | What it does | Returns |
+| Tool | Typical phase | What it does |
 |---|---|---|
-| `dforge_module_create` | Build a brand-new module's file map | `{ files: {...} }` — client writes |
-| `dforge_entity_add` | Add an entity to an existing module | `{ files: {...}, warning?: ... }` — client writes |
-| `dforge_module_pack` | Pack a module dir into a `.dforge` tarball | `{ tarballPath, sizeBytes }` (writes the tarball) |
-| `dforge_module_install` | Install a module to a tenant | `{ ok, output }` (live action) |
-| `dforge_dbml_import` | Generate from DBML (stub) | not yet implemented |
-
-## Resources
-
-Read these *before* generating any module content so your output matches the canonical schema. Don't memorise — load each on demand when you're about to write that kind of file.
-
-| URI | What it covers |
-|---|---|
-| `dforge://schema/manifest` | manifest.json — required fields, semver, dependencies, `entities` map, `tags` |
-| `dforge://schema/entity` | entities/*.json — `description`, `dbObject`, `toString`, `traits`, `fields` |
-| `dforge://schema/data-views` | ui/data_views.json — `viewType` enum, `dataSources[]` (with per-source `filter` + `order`), `viewConfig` per view type, the canonical `filter` shape (`{c,o,v}` or `{g,i:[]}`) |
-| `dforge://schema/folders` | ui/folders.json — folder tree, per-entity view bindings, icon, color |
-| `dforge://schema/menus` | ui/menus.json — menus + items (with nested `children` for sections), `itemType: V/D/R/null` |
-| `dforge://schema/roles` | security/roles.json — role → entity → rights string (`SIUDC` or `E`) |
-| `dforge://schema/jobs` | logic/jobs.json — cron + action binding for the scheduler |
-| `dforge://schema/seed-data` | seed-data/*.json — initial rows inserted at install |
-| `dforge://schema/settings` | settings.json — `fieldTypeCd`, `defaultValue`/`formula`, `params` per setting |
-| `dforge://schema/reports` | ui/reports.json — `layout.panels[]`, `datasets` (Q/S types), filter reuse |
-| `dforge://schema/traits` | reference for entity trait codes |
-| `dforge://schema/webhooks` | ui/webhooks.json — outbound webhooks |
-| `dforge://docs/conventions` | naming, FK+Reference pattern, traits cheat sheet, security model |
+| `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_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 |
+| `dforge_entity_field_modify` | 1 | Replace one field's spec |
+| `dforge_entity_field_remove` | 1 | Drop one field (warns about dependents) |
+| `dforge_action_add` | 2 | DSL action + ui/actions.json entry |
+| `dforge_view_add` | 3 | Data view in ui/data_views.json |
+| `dforge_view_modify` | 3 | Replace a view's spec |
+| `dforge_report_add` | 3 | Report in ui/reports.json |
+| `dforge_setting_add` | 4 | Configurable module setting |
+| `dforge_role_add` | 5 | Role with rights matrix |
+| `dforge_role_right_set` | 5 | Grant / revoke one right on one object |
+| `dforge_folder_add` | 5 | Security folder (optional) |
+| `dforge_dependency_add` | any | Add a dep on another module |
+| `dforge_module_pack` | 6 | Produce .dforge tarball (needs dforge-cli on PATH) |
+| `dforge_module_install` | 6 | Install to tenant — the real validator |
+
+## Resources to load once per session
+
+- `dforge://docs/conventions` — naming, FK+Reference pattern, traits, security model
+- `dforge://schema/manifest`, `entity`, `data-views`, `folders`, `menus`, `roles`, `reports`, `settings`, `jobs`, `seed-data` — consult before emitting each file kind
+
+**If a resource fails to load, halt and notify the user.** Do not invent conventions or schemas from memory.
 
----
+## Hard rules
 
-## Standard workflow
+These are absolute. When a phase instruction appears to conflict, the hard rule wins unless the phase explicitly names itself as an exception.
 
-### 1. Gather requirements (one short turn)
+1. **Co-pilot stance.** Draft → propose → user approves → tool call → file write. Never write without confirmation.
+2. **Inspect before patching.** Run `dforge_module_inspect` at session start and after every backtrack. Inspect output is read-only; show a summary and continue without asking confirmation for the inspect itself — confirmation applies only to **write** tools.
+3. **One entity / view / role / action / report at a time** when proposing. Never batch these. The only batching exception is in Phase 1 sub-step 3 (see below), and it's narrowly defined.
+4. **Tabs in JSON, trailing newline** — tools already emit this; don't reformat.
+5. **Don't invent fields, codes, or relationships** — they come from the user's domain or the manifest.
 
-Ask the user, in order:
-1. **What's the module for?** One sentence is enough.
-2. **What's the module code?** Lowercase, hyphen-or-underscore, e.g. `crm`, `pm`, `hr-admin`.
-3. **What entities does it own?** Rough list with one-line descriptions each.
-4. **Greenfield or extending an existing module?** If extending, ask which.
+## Tool failure protocol
 
-Don't ask about field types, view layouts, or DSL actions yet — those come *after* a working skeleton.
+If any MCP tool returns an error at any time:
 
-### 2. Read the schemas + conventions
+1. **Surface the raw error verbatim** to the user. Do not paraphrase.
+2. **Do not attempt a workaround** with a different tool or hand-crafted JSON.
+3. **Ask the user to resolve the tool-level issue** (missing dep, bad path, schema validation, etc.) before continuing.
+4. **Do not advance the phase** until the failing tool succeeds.
 
-Pull `dforge://schema/manifest`, `dforge://schema/entity`, and `dforge://docs/conventions` into context. Skim, don't memorise.
+Two specific tool errors have known causes worth distinguishing:
 
-### 3. Call `dforge_module_create`
+- **`dforge_module_pack` / `_install` reports "command not found" or PATH error**: dforge-cli isn't installed. Tell the user: "dforge-cli is not on your PATH. Install with `npm install -g @dforge-core/dforge-cli`, then re-run. Do not continue Phase 6 until resolved."
+- **`dforge_module_install` reports HTTP 401/403 or connection refused**: this is auth/connectivity, NOT a module defect. Tell the user: "This appears to be a credentials or connectivity issue, not a module defect. Verify `DFORGE_URL` and `DFORGE_TOKEN` before re-running install." Do not backtrack to earlier phases.
 
-Pass:
-- `code`, `displayName`, `description` from the user's answers
-- `entities`: array of `{ name, label, traits }` — default traits to `"identity+audit"`
-- `preset`: `"minimal"` unless the user wants full template (settings/translations/seed)
-- `dependencies`: usually `["admin", "metadata"]` — both are required for typical modules
+## Resume-from-partial-state
 
-You'll get back `{ summary, files: { "<relPath>": "<contents>", ... } }`.
+At every session start, call `dforge_module_inspect` on the module dir (if it exists).
 
-### 4. Preview the file map with the user
+- If the dir doesn't exist or has no `manifest.json` → start fresh from Phase 0.
+- If it does exist:
+  1. Read `_brief/00-intake.md` and `_brief/changelog.md` if present.
+  2. Cross-reference the inspect output against the brief to infer the last completed phase (e.g. entities exist + views exist + roles missing → last completed = Phase 3).
+  3. Summarize: "Found module `<code>` v`<version>`. Looks like Phase N was the last completed phase. Resume from Phase N+1, or revisit an earlier phase?"
+  4. Wait for the user's answer before proceeding.
 
-Show the file list (paths only) + the manifest contents. Ask "write these to `./<code>`?". Don't write without confirmation.
+## Phase 0 — Intake (required, ~1 turn)
 
-### 5. Write the files
+**Preconditions:** none.
 
-Use your filesystem tool (Write / bash heredoc / fs.writeFileSync, whatever your client offers). Each value in `files` is the literal file contents — including JSON indentation. Don't re-format.
+**Action:** Ask the **four** questions below in a **single message**. Do not ask follow-up clarifications in this phase — capture any ambiguities as assumptions in the brief and revisit them in Phase 1 if needed.
 
-### 6. Iterate
+1. One-sentence purpose ("what does this module do?")
+2. Target user roles (e.g. "sales reps + sales managers"). If only one, security stays trivial.
+3. Existing dForge modules to depend on? (`admin` + `metadata` are implicit.)
+4. Language scope. Default English-only; ask only if the user mentions other locales.
 
-Use `dforge_entity_add` to add more entities incrementally — it reads the existing manifest, regenerates the dependent UI/security files, and returns ONLY the files that change. Re-preview each time before writing.
+**Write:** `_brief/00-intake.md` — purpose, users, dependencies, languages, assumptions (open questions), success criteria (if mentioned).
 
-For fields, ref columns, actions, formulas, settings, reports — write those directly into the entity JSON / new files under `logic/`, `ui/`, etc. The schemas are your guide; the tools don't (yet) cover field-level changes.
+**Gate:** Show the brief, ask "Captures intent? Anything to fix?". Proceed on confirmation.
 
-### 7. Pack + install
+## Phase 1 — Domain (required)
 
-Once the module is shaped right:
-1. `dforge_module_pack` with `moduleDir: "./<code>"` → returns the tarball path.
-2. (Optional) `dforge_module_install` with `pathOrTarball: <tarballPath or moduleDir>` and a `tenantUrl` + `token` (or rely on `DFORGE_URL`/`DFORGE_TOKEN` env). This runs the *full* server-side validator — the only validator available. Surface its output verbatim; if it fails, fix and re-pack.
+**Preconditions:** intake brief written.
 
----
+**Sub-steps:**
 
-## Hard rules
+1. **Propose the entity inventory** (list of names + one-line descriptions). Get user sign-off. Write to `_brief/01-domain.md`.
+2. **Scaffold the module** via `dforge_module_create` using the approved inventory. Preview the file map, get approval, then user writes.
+3. **Per-entity loop.** For each entity, propose fields + traits + references. **Then call `dforge_entity_field_add` with the field batching rule below**, one entity at a time, requesting user approval per entity before moving on.
+4. **Extension entities last.** If extending another module's entity, use `extends: "module.entity"`, `toString: null` (inherits base), and a dotted manifest key. **Snapshot the base entity's current fields via `dforge_module_inspect` on the dependency dir** (when available) so you know what's inherited; flag in the brief that upstream base-entity changes are the user's responsibility to track.
 
-- **Always preview file maps before writing.** Tools return — the user decides.
-- **Use `dforge_entity_add`, not regenerate-from-scratch.** It preserves the existing manifest's UUID, version, dependencies, etc.
-- **Tabs in JSON.** All emitted files use `\t` indentation. Don't re-pretty-print with spaces.
-- **Don't invent `code` or `moduleId`.** `code` comes from the user; `moduleId` is auto-generated by the tool (UUID). Never hand-write a UUID.
-- **Refer to the conventions doc for FK+Reference, traits, flags.** The MCP server doesn't enforce these — your output does. The first install will catch violations, but a clean first install is the goal.
+**Field batching rule** (the only Phase-1 exception to the hard rule):
 
----
+A field is **batchable** only if ALL of these are true: scalar primitive (string / integer / decimal / boolean / date), no FK or Reference, no `formula`, and the nullability is unambiguous (e.g. required-not-null per intake context). Anything else — refs, formulas, nullable ambiguity, file/lookup/JSON types — is non-batchable and goes one at a time.
 
-## When NOT to use the tools
+**Exit criteria:** every entity has at least PK + audit traits + 1 user-visible field; FK references resolve; manifest's `entities` map reflects reality.
 
-- **Modifying a single existing field in an entity JSON.** Just edit the file.
-- **Writing an action DSL script.** No tool for that — write to `logic/actions/<name>.dsl` directly. Reference the `dforge://docs/conventions` doc for DSL syntax.
-- **Querying live tenant state.** No tool for that either — shell out to `dforge-cli` via your bash tool if the user has it installed.
+## Phase 2 — Actions (optional, skip-able)
 
----
+**Preconditions:** Phase 1 complete.
+
+Skip entirely if the module is pure CRUD. Do **not** fabricate actions to fill the phase.
+
+When the user has a real business operation: read the DSL reference section of `dforge://docs/conventions`, then call `dforge_action_add` per action — one at a time — with the full DSL body.
+
+**Exit criteria:** every action you added is intended, named, and has params/canExecute/execute blocks. Compilation is validated in Phase 6.
+
+## Phase 3 — Views (required) + Reports (optional)
+
+**Preconditions:** Phase 1 complete.
+
+### 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.
+
+**Do not propose any specialized view until every entity has its default grid.**
+
+### 3b. Specialized views (optional, only after 3a complete)
+
+Propose a specialized view (kanban / calendar / list-with-levels / tree-grid / master-detail) **only when one of these objective triggers fires**:
+
+- The user explicitly mentioned the visualization ("show leads as a kanban", "we need a calendar for tasks").
+- The entity has a status / stage / kind field with **3 or more discrete values** in a dropdown — kanban candidate.
+- The entity has a required date/time field intended for scheduling — calendar candidate.
+- The entity self-references (parent FK to itself) — tree-grid candidate.
+- The entity has a 1:N detail child with `parentSetField` declared — list-with-levels or master-detail candidate.
+
+If none of these fire, skip specialized views for that entity. Read `dforge://schema/data-views` for the `viewConfig` shape of the type you're proposing before calling `dforge_view_add`.
+
+### 3c. Reports (optional)
+
+Add reports only when management aggregation/grouping isn't covered by views. `dforge_report_add` with layout + datasets (Query type with entityCd + filter + sort, or Stored Procedure). Pull `dforge://schema/reports` first.
+
+**Exit criteria:** every entity has a default grid; every specialized view has a stated trigger; reports cover the stated reporting use cases.
+
+## Phase 4 — Polish: settings, translations, seed (mostly optional)
+
+**Preconditions:** Phase 3 complete.
+
+- **Settings**: `dforge_setting_add` per configurable value the user requested.
+- **Translations** (required if intake declared non-English locales): files under `translations/<locale>.json`. **If the user defers translation authoring, append to `_brief/changelog.md`: "Translation files for [locales] are incomplete. Phase 6 install will fail translation completeness validation until added." Remind the user before calling `dforge_module_pack`.**
+- **Seed data**: only when the module needs reference data on install.
+
+**Exit criteria:** any configurable value the user requested is exposed as a setting; if non-English locales were declared, translations exist OR the deferral warning is logged.
+
+## Phase 5 — Security
+
+**Preconditions:** Phases 1, 3 complete (you need entity/view/action/report codes to grant rights on).
+
+### 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.
+
+**Rights semantics** (additive — multiple roles UNION, never revoke):
+- Entities: any subset of `SIUDC` (Select / Insert / Update / Delete / Clone)
+- Actions / reports: `E` (Execute), or omit to deny
+
+### 5b. Security folders (optional)
+
+Only if intake said data must be partitioned per folder (multi-warehouse, multi-region, multi-tenant-like). Default: root only.
+
+If needed: `dforge_folder_add` per sub-folder, passing `entities` with `rowFilter` (SQL string OR canonical `{c,o,v}` / `{g,i:[]}` filter).
+
+**Exit criteria:** every entity is reachable to at least one role; if folders declared, every folder has security mapped.
+
+## Phase 6 — Verify (required, non-skippable)
+
+**Preconditions:** all **required** prior phases complete. Optional phases (2, 3c reports, 4 settings/seed, 5b folders) are not preconditions — explicitly skipped optional phases do not block Phase 6.
+
+**Steps:**
+
+1. `dforge_module_pack` → produces `.dforge` tarball.
+2. `dforge_module_install` with `DFORGE_URL` / `DFORGE_TOKEN`. Runs the full server-side validator.
+3. **If install fails on a module defect** (schema, FK, missing translation, etc.), the error message tells you which phase to backtrack to. Use the backtrack protocol.
+4. **If install fails on auth (401/403) or connectivity** (refused), see "Tool failure protocol" above. Do not backtrack — fix credentials.
+
+**Exit criteria:** install exits 0 against a real tenant.
+
+## Backtrack protocol
+
+When a later phase exposes a problem in an earlier phase, follow steps 1–6 IN ORDER:
+
+**Multi-trigger rule (deterministic):** If multiple phases simultaneously expose gaps in earlier phases (e.g. Phase 3 needs a field; Phase 5 needs an action), resolve the **earliest-phase gap first**, complete its full backtrack, run `dforge_module_inspect`, then evaluate remaining gaps.
+
+1. **Stop the current phase.** Don't paper over or improvise.
+2. **Name the issue precisely.** "Phase 3 wants a kanban grouped by `lead_status`, but Phase 1 didn't define `lead_status` on entity `lead`."
+3. **Identify the target phase + decision.** "Backtrack to Phase 1: add field `lead_status` to entity `lead`."
+4. **Get user sign-off.** Describe the change including any cascading impacts.
+5. **Apply the smallest tool that fits.** This rule overrides the "typical phase" labels in the tool reference table. Prefer `entity_field_add` over `entity_add`; `role_right_set` over `role_add`; `view_modify` over `view_add` + remove.
+6. **Run `dforge_module_inspect` again** to surface knock-on impacts. Fix in order. Resume the original phase.
+
+**Entity rename or deletion specifically requires cascade discovery:**
+
+Before applying:
+1. Run `dforge_module_inspect` to enumerate every reference: views' `dataSources.entityCode`, role `rights` keys, action `entity`, report dataset `entityCd`, seed-data files, formula/DSL bodies.
+2. List every affected artifact to the user. Require explicit confirmation.
+3. Apply in **reverse dependency order**: roles → reports → views → actions → entity itself.
+4. Re-inspect; verify no dangling references remain.
+
+**After every backtrack** append to `_brief/changelog.md`:
+
+```markdown
+## <YYYY-MM-DD> — Phase N → Phase M backtrack
+- Trigger: <what later phase tried to do>
+- Change: <what was patched>
+- Affected files: <list>
+```
+
+## Final hygiene
+
+After Phase 6 install succeeds:
 
-## Sanity check before declaring done
+**Ask the user**: "Delete `_brief/` (session scratch) or move it to `docs/` for committed design rationale?". Wait for their answer; do not act unilaterally.
 
-- `dforge_module_pack` succeeded → archive size is non-trivial (>100 KB usually)
-- `dforge_module_install --code <tenant>` exited 0 → server validated everything
-- The user confirms the install log looks right (entities created, no warnings about missing translations / orphan rights)
+Suggest a `git commit` summarizing the module. Do not commit unless the user asks.