@dforge-core/dforge-mcp 0.1.1 → 0.1.3

package/CHANGELOG.md

@@ -4,6 +4,67 @@ 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.1.3
+
+### Added
+- **Cross-source report metrics & charts (schema).** `reports.schema.json` now
+  lists `kpi` as a `vizType` (was `metric`) and documents the two config shapes
+  module authors can now write:
+  - **Formula KPI metrics** — a metric can be `{ formula, inputs: [{ alias, column,
+    agg, source? }], format? }` instead of a single `{ column, agg }`, for ratios /
+    derived numbers / win-rate percentages. `format` Auto (omit `style`) inherits the
+    first input column's own formatter.
+  - **Cross-source inputs & overlay series** — a formula input (`inputs[].source`) or
+    a chart overlay series (`config.series`, a single object or array of `{ source?,
+    categoryCol, valueCol, agg, label? }`) can aggregate over a **sibling dataset** by
+    its code (omit = the panel's own). Chart overlays share one category axis
+    (outer-joined; bar fills 0, line/area gaps with null).
+
+### Skill
+- `dforge-mcp-author`: **reconciled `references/reports.md` to the real report
+  format.** Corrected long-standing drift — `layout` is `{ panels: [...] }` (not a
+  bare array); chart panels are `vizType: "chart"` with the kind in
+  `config.chartType` (not `vizType: "bar"`); datasets use `datasetType` + nested
+  `query.entityCd`/`columns` (not top-level `entityCode`/`groupBy`/`aggregations`,
+  which don't exist — aggregation is viz-side); SP datasets use `spCd` (+ multi-set
+  via `parentDatasetCd`/`parentRef`), not `sp`/`spCursor`; KPI is
+  `config.metrics: [...]` (not `{ valueCol, format }`). Added the formula-KPI,
+  cross-dataset-KPI, and chart-overlay sections.
+
+## 0.1.2
+
+### Fixed
+- **Windows CLI resolution & argument quoting (`native-shell`).** The PATH
+  fallback now routes a bare command name through `cmd.exe` so `PATHEXT`
+  resolves the `dforge-cli.cmd` shim that `npm install -g` drops on PATH —
+  previously `spawnSync` without a shell matched only an exact file and
+  `ENOENT`'d. Arguments are now quoted before the shell sees them (`shell:true`
+  performs no escaping), so a path with spaces no longer splits into multiple
+  args and a metacharacter (`&`, `|`, `>`, …) can't inject a second command;
+  `quoteWinArg` follows the `CommandLineToArgvW` rules. Spawn logic is
+  centralized in a single `spawnCli` helper shared by `run()` and
+  `installModule()`, with coverage in `test/native-shell.test.ts`.
+
+### Changed
+- **`dforge_module_install` always returns raw CLI output.** The tool now
+  surfaces the raw CLI output, `exitCode`, and `command` on every call so the
+  agent can read a server-side validation failure and fix-and-retry instead of
+  getting a swallowed error.
+- **`dforge_module_pack` description.** Clarified that it uses the bundled
+  `dforge-cli` package, then the PATH fallback, then the `DFORGE_CLI_BINARY`
+  override (was "Requires the dforge-cli native binary on PATH").
+
+### Added
+- **Matrix data-view support.** Data-view guidance and schemas document matrix
+  views with `rangeControl` and per-column select values, alongside the
+  register/budgeting examples.
+
+### Skill
+- `dforge-mcp-author`: reworked the Phase 6 flow into an explicit
+  **validate → pack → install → fix** retry loop (SKILL.md,
+  `validation-checklist.md`, `docs/creating-modules.md`), and refreshed the
+  module naming conventions in the manifest schema.
+
 ## 0.1.0-rc.13
 
 Single source of truth: the authoring tools now validate against

package/README.md

@@ -35,6 +35,8 @@ 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.
 
+For AI-assisted module repair, Phase 6 is intentionally tool-driven: the skill runs `dforge_module_validate`, `dforge_module_pack`, and `dforge_module_install` itself. If install fails because the module is invalid, the install tool returns the raw CLI/server output plus `exitCode` and `command`; the AI reads that output, fixes the referenced module files, and repeats validate → pack → install. User action is needed only for environment failures such as missing CLI, missing/expired credentials, an unreachable tenant/API, permissions, or an invalid path.
+
 ## Install + wire into Claude Code
 
 ### Recommended — via `claude mcp add` (writes ~/.claude.json for you)
@@ -94,8 +96,8 @@ Phase 0 (identity → requirements → design → validation) is orchestrated by
 | `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_pack` | Shells to `dforge-cli module pack`. 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. `tenantCode` is an optional `--code` sanity check the server cross-references against the JWT |
+| `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 |
 
 **Entities (Phase 1)**
 | Tool | Behavior |

package/dist/server.js

@@ -32587,8 +32587,44 @@ function dbmlImport(args) {
 
 // src/tools/native-shell.ts
 var import_node_child_process = require("child_process");
+var import_node_module = require("module");
 var fs5 = __toESM(require("fs"));
 var path5 = __toESM(require("path"));
+var require2 = (0, import_node_module.createRequire)(__filename);
+function needsWindowsCommandShell(bin) {
+  if (process.platform !== "win32") return false;
+  if (/\.(?:cmd|bat)$/i.test(bin)) return true;
+  return !bin.includes("\\") && !bin.includes("/");
+}
+function quoteWinArg(arg) {
+  if (arg.length > 0 && !/[\s"&|<>^()%!]/.test(arg)) {
+    return arg;
+  }
+  let quoted = '"';
+  let backslashes = 0;
+  for (const ch of arg) {
+    if (ch === "\\") {
+      backslashes++;
+      continue;
+    }
+    if (ch === '"') {
+      quoted += "\\".repeat(backslashes * 2 + 1) + '"';
+    } else {
+      quoted += "\\".repeat(backslashes) + ch;
+    }
+    backslashes = 0;
+  }
+  quoted += "\\".repeat(backslashes * 2) + '"';
+  return quoted;
+}
+function spawnCli(cli, args, options = {}) {
+  const fullArgs = [...cli.argsPrefix, ...args];
+  if (needsWindowsCommandShell(cli.bin)) {
+    const commandLine = [cli.bin, ...fullArgs].map(quoteWinArg).join(" ");
+    return (0, import_node_child_process.spawnSync)(commandLine, { encoding: "utf8", shell: true, ...options });
+  }
+  return (0, import_node_child_process.spawnSync)(cli.bin, fullArgs, { encoding: "utf8", shell: false, ...options });
+}
 function resolveDforgeCli() {
   const override = process.env.DFORGE_CLI_BINARY;
   if (override) {
@@ -32597,26 +32633,32 @@ function resolveDforgeCli() {
         `DFORGE_CLI_BINARY points at non-existent path: ${override}`
       );
     }
-    return override;
+    return { bin: override, argsPrefix: [], display: override };
   }
-  return "dforge-cli";
+  try {
+    const cliEntry = require2.resolve("@dforge-core/dforge-cli");
+    return {
+      bin: process.execPath,
+      argsPrefix: [cliEntry],
+      display: `node ${cliEntry}`
+    };
+  } catch {
+  }
+  return { bin: "dforge-cli", argsPrefix: [], display: "dforge-cli" };
 }
 function run(args, cwd) {
-  const bin = resolveDforgeCli();
-  const r = (0, import_node_child_process.spawnSync)(bin, args, {
-    encoding: "utf8",
-    cwd,
-    shell: false
-  });
+  const cli = resolveDforgeCli();
+  const r = spawnCli(cli, args, { cwd });
   if (r.error) {
     throw new Error(
-      `Failed to exec ${bin}: ${r.error.message}. Install with: npm install -g @dforge-core/dforge-cli (or set DFORGE_CLI_BINARY=/path/to/binary).`
+      `Failed to exec ${cli.display}: ${r.error.message}. Install with: npm install -g @dforge-core/dforge-cli (or set DFORGE_CLI_BINARY=/path/to/binary).`
     );
   }
   return {
     stdout: r.stdout ?? "",
     stderr: r.stderr ?? "",
-    code: r.status ?? 1
+    code: r.status ?? 1,
+    command: [cli.display, ...args].join(" ")
   };
 }
 var packModuleSchema = {
@@ -32682,18 +32724,19 @@ function installModule(args) {
   const env = {};
   if (args.tenantUrl) env.DFORGE_URL = args.tenantUrl;
   if (args.token) env.DFORGE_TOKEN = args.token;
-  const bin = resolveDforgeCli();
-  const r = (0, import_node_child_process.spawnSync)(bin, argList, {
-    encoding: "utf8",
-    env: { ...process.env, ...env },
-    shell: false
-  });
+  const cli = resolveDforgeCli();
+  const r = spawnCli(cli, argList, { env: { ...process.env, ...env } });
   if (r.error) {
-    throw new Error(`Failed to exec ${bin}: ${r.error.message}`);
+    throw new Error(`Failed to exec ${cli.display}: ${r.error.message}`);
   }
   const ok = r.status === 0;
   const output = (r.stdout ?? "") + (r.stderr ?? "");
-  return { ok, output };
+  return {
+    ok,
+    exitCode: r.status ?? 1,
+    command: [cli.display, ...argList].join(" "),
+    output
+  };
 }
 
 // src/tools/entity-field.ts
@@ -34381,7 +34424,7 @@ server.tool(
 );
 server.tool(
   "dforge_module_pack",
-  "Pack a module directory into a .dforge tarball. Requires the dforge-cli native binary on PATH (or set DFORGE_CLI_BINARY).",
+  "Pack a module directory into a .dforge tarball. Uses the bundled dforge-cli package, PATH fallback, or DFORGE_CLI_BINARY override.",
   packModuleSchema,
   async (args) => {
     const result = packModule(args);
@@ -34390,7 +34433,7 @@ server.tool(
 );
 server.tool(
   "dforge_module_install",
-  "PHASE 6: Install a module (directory or .dforge tarball) to a running tenant. Runs the FULL server-side validator \u2014 the only real validator. Reads DFORGE_URL / DFORGE_TOKEN env if not passed as args.",
+  "PHASE 6: Install a module (directory or .dforge tarball) to a running tenant. Runs the FULL server-side validator \u2014 the only real validator. Reads DFORGE_URL / DFORGE_TOKEN env if not passed as args. Always returns raw CLI output, exitCode, and command so the agent can fix module defects and retry.",
   installModuleSchema,
   async (args) => {
     const result = installModule(args);

package/docs/creating-modules.md

@@ -101,9 +101,10 @@ Settings (`dforge_setting_add`), translations, seed data — only if intake decl
 
 ### 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.
+1. `dforge_module_validate` → offline cross-reference validation. The AI fixes every error before packing.
+2. `dforge_module_pack` → `.dforge` tarball.
+3. `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.
+4. On module-defect failure, the AI reads the returned raw CLI `output`, fixes the referenced module files, and repeats validate → pack → install. It asks the user only for environment/tooling problems such as missing CLI, expired credentials, unreachable tenant/API, permissions, or a path outside the workspace.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@dforge-core/dforge-mcp",
-	"version": "0.1.1",
+	"version": "0.1.3",
 	"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",

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

@@ -45,8 +45,8 @@ The phase column below indicates the **typical** use. During a backtrack, the ba
 | `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 |
+| `dforge_module_pack` | 6 | Produce .dforge tarball via bundled dforge-cli, PATH fallback, or `DFORGE_CLI_BINARY` |
+| `dforge_module_install` | 6 | Install to tenant — the real validator; returns raw CLI output for the install-fix loop |
 
 **Phase 0 (0a–0d) is owned by `dforge_module_plan`.** Call `dforge_module_plan({ action: "check", moduleDir })` to start or resume Phase 0. The tool returns the current state and exact next steps. Do not call `dforge_module_create` until the tool reports `readyToScaffold: true` — the tool enforces this gate programmatically.
 
@@ -128,14 +128,15 @@ Always-on cheat-sheet — enough to author inline; load the linked `references/*
 If any MCP tool returns an error at any time:
 
 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.
+2. **Classify the error before asking the user for help.** If the raw output names a module/package defect, fix the module yourself using the smallest appropriate tool or direct file edit allowed by the host agent, then re-run the required validation loop. Do not ask the user to paste the error back to you — it is already in the tool result.
+3. **Ask the user to resolve only environment/tooling issues** you cannot fix from module files: missing CLI, missing/expired credentials, unreachable tenant/API, permissions, or a bad module path outside the workspace.
 4. **Do not advance the phase** until the failing tool succeeds.
 
 Two specific tool errors have known causes worth distinguishing:
 
 - **`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.
+- **`dforge_module_install` returns `ok: false` with validation/import/compile/schema output**: this is a module defect. Treat `output` as the source of truth, fix the referenced files, and run Phase 6 again from automated validation. Keep repeating until install succeeds or the remaining error is clearly environment/tooling.
 
 ## Resume-from-partial-state
 
@@ -416,7 +417,15 @@ Get user confirmation on both version strings before packing.
 1. `dforge_module_pack` → produces `.dforge` tarball. (Blocked if any entity lacks a role granting Select — the Phase 5a gate; fix security coverage and re-run.)
 2. `dforge_module_install` with `DFORGE_URL` / `DFORGE_TOKEN`. Runs the full server-side validator.
 
-**If install fails on a module defect**, use this table to identify which phase to backtrack to, then apply the backtrack protocol, fix, re-run Steps 1–2 (validate + self-review), and re-pack:
+**Install-fix loop (mandatory):**
+
+1. Call `dforge_module_install` yourself. Do not ask the user to run the install command for you.
+2. If the result has `ok: false`, read the returned `output` in full. It is the raw CLI/server validator output and is the input for the next fix.
+3. If the failure is a module defect, fix it yourself. Use this table to identify which phase to backtrack to, then apply the backtrack protocol with the smallest suitable tool or file edit.
+4. Re-run Step 1 (`dforge_module_validate`), Step 2 (self-review for the touched area), Step 5 pack, and Step 5 install.
+5. Repeat this loop until install succeeds or the remaining failure is clearly an environment/tooling issue from the Tool failure protocol.
+
+Common module-defect patterns:
 
 | Install error pattern | Backtrack to |
 |---|---|
@@ -438,6 +447,8 @@ When a later phase exposes a problem in an earlier phase, follow steps 1–6 IN
 
 **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.
 
+**Phase 6 install exception:** when `dforge_module_install` fails with a clear module defect (schema validation, missing file/key, translation completeness, DSL compile error, dependency contract, FK/seed/import error), do not ask the user for sign-off before the corrective patch. The server validator has already rejected the package, so fix the referenced files, report what changed, and immediately re-run validate → pack → install. Keep user sign-off for product/design choices or ambiguous fixes.
+
 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`."

package/skills/dforge-mcp-author/references/data-views.md

@@ -161,9 +161,11 @@ A pivot grid. The view's primary `dataSources` entity is the **cell** entity (on
 
 **`rowAxis` / `colAxis`** — what the rows and columns are. Three `kind`s:
 
-- `"dataset"` — axis values are an entity's records. `entity` + `labelField` required; optional `keyField` (defaults to the axis entity PK — what the cell's `rowKey`/`colKey` matches), `lockedField` (boolean column → that axis value's cells are read-only), `filter` (same `{c,o,v}` grammar as everywhere — scopes which axis records load), `hideEmpty` (**column axis only** — drop columns with no cell record in any row, e.g. periods with no postings; ignored if it would blank the whole grid), `sort` (`[{ col, dir }]`).
-- `"dropdown"` — axis values are a dropdown/flags column's options. Just `kind` + `column` (an `"entity.column"` reference). Codes line up by construction.
-- `"date"` — generated date window, **column axis only** (not valid on `rowAxis`). `kind` + `grain: "day"` + `window: "week"` (v1).
+- `"dataset"` — axis values are an entity's records. `entity` + `labelField` required; optional `keyField` (defaults to the axis entity PK — what the cell's `rowKey`/`colKey` matches), `lockedField` (boolean column → that axis value's cells are read-only), `filter` (same `{c,o,v}` grammar as everywhere — scopes which axis records load), `hideEmpty` (**column axis only** — drop columns with no cell record in any row, e.g. periods with no postings; ignored if it would blank the whole grid), `rangeControl` (**column axis only** — show a From/To range control so the user can narrow the visible columns to a span; persists in view options; composes with `hideEmpty`), `sort` (`[{ col, dir }]`).
+- `"dropdown"` — axis values are a dropdown/flags column's options. `kind` + `column` (an `"entity.column"` reference); optional `values` (`[...]` of option value codes — a subset + order of columns, chosen the way kanban lanes are; omit to show every option in field order). Codes line up by construction.
+- `"date"` — generated date window, **column axis only** (not valid on `rowAxis`). `kind` + `grain: "day"` + `window: "week"` (v1). *Roadmap (designed, not built): arbitrary `range` (`{from, to}`) + `grain` (`day`/`week`/`month`/`quarter`/`year`), surfaced as a date-picker variant of the range bar — lets a time matrix generate its columns instead of needing seeded period records. Don't author against it yet.*
+
+> **The matrix is source-agnostic.** A matrix is just config over generic entities: point the cell at *any* dated/keyed entity that fits your model — a pre-aggregated registry (e.g. `gl.balance_register`, fast but period-grained), raw dated movements (any-grain, heavier), or your own table. `gl` is a regular, replaceable module, not a platform requirement; nothing about the matrix knows or needs "gl". Choosing a pre-aggregated source vs raw rows (and the grain) is a per-view config decision, with the usual perf-vs-flexibility trade.
 
 **`cell`** — the value-source record at each intersection. `entity` (must match the primary dataSource), `rowKey` / `colKey` (cell columns matching the row/column axis keys), `fields` (cell columns rendered in each cell). Optional: `cardinality: "one"` (v1 default), `editable`, `drill` (read-only cells become clickable → open the cell record and its child sets), `seedFromRow` (`{ cellField: rowAxisField }` copied into new cell records on insert), `seedCurrentUser` (cell fields set to the current user id on insert).
 

package/skills/dforge-mcp-author/references/reports.md

@@ -1,152 +1,114 @@
 # Reports Reference
 
-Reports are **query-driven visualizations** — charts, KPIs, pivot tables, grids — backed by datasets. Unlike data views (which target one entity), reports can combine multiple datasets and render any layout.
+Reports are **query-driven visualizations** — charts, KPI cards, pivot tables, tables — backed by datasets. Unlike data views (which target one entity), a report can combine **multiple datasets** and lay out several panels.
 
-Lives in: `ui/reports.json` or `ui/reports/<report_code>.json`
+Lives in: `ui/reports.json` (map of `report_code` → report). Not listed in `manifest.json` — the install pipeline picks up `ui/reports.json` automatically.
 SP files: `logic/reports/rpt_*.sql`
 
 ## Structure
 
+A report has `description`, a `datasets` map, a `layout` object (`{ panels: [...] }`), and optional `parameters`. Panels reference datasets by code via `datasetCd`.
+
 ```json
 {
     "sales_pipeline": {
         "description": "Open opportunities by stage",
         "datasets": {
-            "ds_pipeline": {
+            "pipeline": {
                 "caption": "Pipeline Data",
-                "entityCode": "opportunity",
-                "columns": ["stage", "total_amount", "account"],
-                "filter": {
-                    "g": "and",
-                    "i": [
-                        { "c": "stage", "o": "!in", "v": ["Closed Won", "Closed Lost"] }
-                    ]
-                },
-                "groupBy": ["stage"],
-                "aggregations": {
-                    "opp_count": { "func": "count", "column": "*" },
-                    "total_value": { "func": "sum", "column": "total_amount" }
+                "datasetType": "Q",
+                "query": {
+                    "entityCd": "opportunity",
+                    "columns": ["stage", "amount", "lead_source", "customer.name"],
+                    "filter": {
+                        "g": "and",
+                        "i": [ { "c": "stage", "o": "nIn", "v": ["Closed Won", "Closed Lost"] } ]
+                    },
+                    "sort": [ { "c": "amount", "d": "desc" } ]
                 }
             }
         },
-        "layout": [
-            {
-                "vizType": "bar",
-                "datasetCd": "ds_pipeline",
-                "title": "Pipeline Value by Stage",
-                "config": {
-                    "categoryCol": "stage",
-                    "valueCol": "total_value",
-                    "agg": "sum"
-                }
-            },
-            {
-                "vizType": "grid",
-                "datasetCd": "ds_pipeline",
-                "title": "Pipeline Detail"
-            }
-        ],
-        "params": {
-            "owner_filter": {
-                "fieldTypeCd": "user",
-                "label": "Filter by Owner",
-                "required": false
-            },
-            "start_date": {
-                "fieldTypeCd": "date",
-                "label": "Start Date",
-                "required": false,
-                "default": "=STARTMONTH()"
-            }
+        "layout": {
+            "panels": [
+                {
+                    "vizType": "chart",
+                    "datasetCd": "pipeline",
+                    "title": "Pipeline Value by Stage",
+                    "config": { "chartType": "bar", "categoryCol": "stage", "valueCol": "amount", "agg": "sum", "chartSize": "l" }
+                },
+                { "vizType": "table", "datasetCd": "pipeline", "title": "Pipeline Detail" }
+            ]
+        },
+        "parameters": {
+            "min_amount": { "fieldTypeCd": "number", "label": "Min Amount", "required": false, "default": 0 }
         }
     }
 }
 ```
 
+**Aggregation happens in the viz, not the dataset.** A dataset selects raw columns; the chart/KPI config aggregates them (`agg`, `metrics`). There is no dataset-level `groupBy`/`aggregations` — do not use them.
+
 ## Dataset types
 
 ### Entity query dataset (most common)
 
-Queries an entity's data using the platform's query builder. Filters use the standard JSON filter format (see `references/filters.md`).
+`datasetType: "Q"` (the default) with a `query` object using the platform query builder. Filters use the standard JSON filter format (see `references/filters.md`).
 
 ```json
-"ds_sales": {
+"sales": {
     "caption": "Sales Data",
-    "entityCode": "opportunity",
-    "columns": ["stage", "total_amount", "close_date", "account"],
-    "filter": { "c": "stage", "o": "!=", "v": "Closed Lost" },
-    "sort": [{ "column_cd": "close_date", "direction": "desc" }],
-    "groupBy": ["stage"],
-    "aggregations": {
-        "deal_count": { "func": "count", "column": "*" },
-        "total_value": { "func": "sum", "column": "total_amount" },
-        "avg_value": { "func": "avg", "column": "total_amount" }
-    }
+    "datasetType": "Q",
+    "query": {
+        "entityCd": "opportunity",
+        "columns": ["stage", "amount", "close_date", "customer.name"],
+        "filter": { "c": "stage", "o": "ne", "v": "Closed Lost" },
+        "sort": [ { "c": "close_date", "d": "desc" } ]
+    },
+    "columnsDef": { "amount": { "label": "Deal Value" }, "customer.name": { "label": "Account" } }
 }
 ```
 
-Aggregation functions: `count`, `sum`, `avg`, `min`, `max`.
+- `query.entityCd` — source entity code (**not** `entityCode`).
+- `query.columns` — column codes; supports dot navigation (`customer.name`).
+- `query.filter` — canonical filter (`{c,o,v}` or `{g,i:[...]}`); use `@param_code` to reference a parameter.
+- `query.sort` — `[{ c, d }]` where `d` ∈ `asc | desc`.
+- `columnsDef` — optional per-column display overrides (`{ label, visible, width }`).
 
 ### Stored procedure dataset (developer path)
 
-For complex SQL that the entity query can't express — window functions, CTEs, cross-schema joins, conditional aggregation, multi-result sets.
+For SQL the query builder can't express — window functions, CTEs, cross-schema joins, conditional aggregation, multi-result sets.
 
 ```json
-"aging_data": {
+"aging": {
     "caption": "AR Aging",
     "datasetType": "S",
-    "sp": "rpt_ar_aging",
+    "spCd": "rpt_ar_aging",
     "params": {
-        "as_of_date": {
-            "fieldTypeCd": "date",
-            "label": "As of Date",
-            "required": true,
-            "default": "=NOW()"
-        },
-        "customer_id": {
-            "fieldTypeCd": "lookup",
-            "label": "Customer",
-            "required": false,
-            "params": { "entityCd": "customer" }
-        }
+        "as_of_date": { "fieldTypeCd": "date", "label": "As of Date", "required": true, "default": "=NOW()" },
+        "customer_id": { "fieldTypeCd": "lookup", "label": "Customer", "required": false, "params": { "entityCd": "account" } }
     },
     "columnsDef": {
-        "customer_name": {
-            "label": "Customer",
-            "fieldTypeCd": "text",
-            "baseDatatypeCd": "string",
-            "width": 200
-        },
-        "current_amount": {
-            "label": "Current",
-            "fieldTypeCd": "number",
-            "baseDatatypeCd": "number",
-            "format": "#,##0.00",
-            "width": 120
-        },
-        "days_30": {
-            "label": "1-30 Days",
-            "fieldTypeCd": "number",
-            "baseDatatypeCd": "number",
-            "format": "#,##0.00",
-            "width": 120
-        },
-        "total": {
-            "label": "Total",
-            "fieldTypeCd": "number",
-            "baseDatatypeCd": "number",
-            "format": "#,##0.00",
-            "width": 130
-        }
+        "customer_name": { "label": "Customer", "fieldTypeCd": "text", "baseDatatypeCd": "string", "width": 200 },
+        "current_amount": { "label": "Current", "fieldTypeCd": "number", "baseDatatypeCd": "number", "width": 120 },
+        "total": { "label": "Total", "fieldTypeCd": "number", "baseDatatypeCd": "number", "width": 130 }
     }
 }
 ```
 
 Key differences from entity datasets:
-- `datasetType: "S"` (instead of default entity query)
-- `sp` — the stored procedure function name (without schema — uses the module's schema)
-- `columnsDef` — **required** — explicitly defines columns since the platform can't infer them from entity metadata
-- Params can be defined per-dataset (dataset-level) or per-report (report-level)
+- `datasetType: "S"`.
+- `spCd` — the stored-procedure code (the function name **without** the schema prefix; resolved to `sp_id` at install). (**Not** `sp` or `procedureName`.)
+- `columnsDef` — **required** — the platform can't infer columns from a function.
+- Params can be per-dataset or per-report.
+
+**Multi-result-set SPs** map extra datasets to the same function via `parentDatasetCd` (the dataset that owns the SP call) + `parentRef` (the named refcursor):
+
+```json
+"datasets": {
+    "summary":  { "caption": "Summary", "datasetType": "S", "spCd": "rpt_department_overview", "columnsDef": { } },
+    "by_role":  { "caption": "By Role", "datasetType": "S", "parentDatasetCd": "summary", "parentRef": "employee_breakdown", "columnsDef": { } }
+}
+```
 
 ### The PostgreSQL function
 
@@ -159,240 +121,154 @@ CREATE OR REPLACE FUNCTION crm.rpt_ar_aging(
     p_as_of_date date DEFAULT NULL,    -- User parameter
     p_customer_id bigint DEFAULT NULL  -- User parameter (optional)
 )
-RETURNS TABLE (
-    customer_name text,
-    current_amount numeric,
-    days_30 numeric,
-    days_60 numeric,
-    days_90 numeric,
-    over_90 numeric,
-    total numeric
-)
+RETURNS TABLE ( customer_name text, current_amount numeric, total numeric )
 LANGUAGE sql STABLE
 AS $$
-    SELECT
-        c.account_name AS customer_name,
-        SUM(CASE WHEN age <= 30 THEN i.amount_due ELSE 0 END) AS current_amount,
-        SUM(CASE WHEN age BETWEEN 31 AND 60 THEN i.amount_due ELSE 0 END) AS days_30,
-        -- ... more columns ...
-        SUM(i.amount_due) AS total
-    FROM fin.invoice i
-    JOIN crm.account c ON c.account_id = i.customer_id
-    WHERE i.status != 'Paid'
-      AND (p_customer_id IS NULL OR i.customer_id = p_customer_id)
-    GROUP BY c.account_name
-    ORDER BY total DESC;
+    SELECT c.account_name, SUM(...) , SUM(i.amount_due)
+    FROM fin.invoice i JOIN crm.account c ON c.account_id = i.customer_id
+    WHERE i.status <> 'Paid' AND (p_customer_id IS NULL OR i.customer_id = p_customer_id)
+    GROUP BY c.account_name ORDER BY 3 DESC;
 $$;
 ```
 
 **Rules for SP functions:**
-- First two params are **always** `p_folder_uid uuid` and `p_user_id bigint` — injected by the platform
-- User params come after, with `DEFAULT NULL` for optional ones
-- Use `RETURNS TABLE (...)` for single result sets
-- Use `RETURNS SETOF refcursor` for multiple result sets (advanced)
-- Use the module's schema prefix: `crm.rpt_*`, `fin.rpt_*`, etc.
-- Use `STABLE` volatility (read-only, enables PostgreSQL optimization)
-- **Security is your responsibility** — filter by `p_folder_uid` and `p_user_id` where needed
-
-### Multi-result-set SPs
-
-For reports with multiple related datasets from one query:
-
-```json
-"datasets": {
-    "summary": {
-        "caption": "Department Summary",
-        "datasetType": "S",
-        "sp": "rpt_department_overview",
-        "spCursor": "department_summary",
-        "columnsDef": { /* ... */ }
-    },
-    "by_role": {
-        "caption": "By Role",
-        "datasetType": "S",
-        "sp": "rpt_department_overview",
-        "spCursor": "employee_breakdown",
-        "columnsDef": { /* ... */ }
-    }
-}
-```
-
-Multiple datasets share the same `sp` (function called once). `spCursor` maps each dataset to a named refcursor returned by the function.
+- First two params are **always** `p_folder_uid uuid` and `p_user_id bigint` — injected by the platform.
+- User params come after, `DEFAULT NULL` for optional ones (order matches `params` declaration order).
+- `RETURNS TABLE (...)` for a single set; `RETURNS SETOF refcursor` for multi-set (mapped via `parentRef`).
+- Use the module's schema prefix (`crm.rpt_*`), `STABLE` volatility, and filter by `p_folder_uid` / `p_user_id` where needed — **security is your responsibility**.
 
 ## Parameters
 
-Parameters prompt the user for input before running the report (or action). Both reports and actions use the same parameter system.
-
-### Report-level parameters
-
-Defined in the report's `params` object:
+Parameters prompt the user before running the report. Declare them per-report (`parameters`) or per-dataset (`params`).
 
 ```json
-"params": {
-    "start_date": {
-        "fieldTypeCd": "date",
-        "label": "Start Date",
-        "required": true,
-        "default": "=STARTMONTH()"
-    },
-    "end_date": {
-        "fieldTypeCd": "date",
-        "label": "End Date",
-        "required": true,
-        "default": "=NOW()"
-    },
-    "region": {
-        "fieldTypeCd": "dropdown",
-        "label": "Region",
-        "required": false,
-        "params": {
-            "options": ["All", "North", "South", "East", "West"]
-        }
-    },
-    "customer": {
-        "fieldTypeCd": "lookup",
-        "label": "Customer",
-        "required": false,
-        "params": { "entityCd": "account" }
-    }
+"parameters": {
+    "start_date": { "fieldTypeCd": "date", "label": "Start Date", "required": true, "default": "=STARTMONTH()" },
+    "region": { "fieldTypeCd": "dropdown", "label": "Region", "params": { "options": ["All", "North", "South"] } },
+    "customer": { "fieldTypeCd": "lookup", "label": "Customer", "params": { "entityCd": "account" } }
 }
 ```
 
-### Parameter properties
-
 | Property | Description |
 |---|---|
-| `fieldTypeCd` | UI control type: `date`, `datetime`, `text`, `number`, `dropdown`, `lookup`, `user`, `checkbox` |
+| `fieldTypeCd` | Control type: `date`, `datetime`, `text`, `number`, `dropdown`, `lookup`, `user`, `checkbox` |
 | `label` | Display label in the parameter dialog |
 | `required` | Whether the user must fill this before running |
-| `default` | Default value — plain value or formula with `=` prefix (e.g. `"=NOW()"`, `"=STARTMONTH()"`, `"=TODAY()"`) |
-| `params` | Additional config — `options` for dropdowns, `entityCd` for lookups |
+| `default` | Plain value or `=`-prefixed formula (`"=NOW()"`, `"=STARTMONTH()"`, `"=TODAY()"`) |
+| `params` | Extra config — `options` for dropdowns, `entityCd` for lookups |
+| `orderNum` | Display order in the parameter form (falls back to declaration order) |
+
+Reference a parameter with `@param_code` inside a query filter value:
+
+```json
+"filter": { "g": "and", "i": [ { "c": "created_date", "o": "grEq", "v": "@start_date" } ] }
+```
+
+SP params are passed positionally after the two required system params, in `params` declaration order.
 
-### Using parameters in entity query filters
+## Layout
 
-Reference parameters with `@param_code` in filter values:
+`layout` is an **object** — `{ "panels": [ ... ] }` (not a bare array). Each panel binds a `vizType` to a `datasetCd`:
 
 ```json
-"filter": {
-    "g": "and",
-    "i": [
-        { "c": "created_date", "o": ">=", "v": "@start_date" },
-        { "c": "created_date", "o": "<=", "v": "@end_date" }
+"layout": {
+    "panels": [
+        { "vizType": "chart", "datasetCd": "pipeline", "title": "By Stage", "config": { "chartType": "bar", "categoryCol": "stage", "valueCol": "amount", "agg": "sum", "chartSize": "l" } },
+        { "vizType": "kpi", "datasetCd": "pipeline", "title": "Pipeline KPIs", "config": { "metrics": [ { "column": "amount", "agg": "sum", "label": "Open Pipeline" } ] } },
+        { "vizType": "table", "datasetCd": "pipeline", "title": "Detail" }
     ]
 }
 ```
 
-### Using parameters in SP datasets
+### Visualization types
 
-Parameters are passed to the PostgreSQL function as positional arguments (after the two required system params). The order matches `params` declaration order in the dataset definition.
+The panel `vizType` is one of `table` / `chart` / `kpi` / `pivot` (also `tree`, `markdown`). **Chart type is set via `config.chartType`** — the panel `vizType` is always `"chart"` for any chart.
 
-### Action parameters (DSL)
+| `vizType` | Description | Config |
+|---|---|---|
+| `table` | Tabular data with sort/filter | optional `groupRules`, `aggregations`, `colorRules` |
+| `chart` | Any chart — kind chosen by `config.chartType` | see below |
+| `kpi` | One or more metric cards | `{ metrics: [ ... ] }` — see below |
+| `pivot` | Pivot table | `rowFields`, `columnFields`, `values` |
 
-Actions declare parameters in the `params:` block of the DSL file:
+**`config.chartType`** ∈ `bar` · `horizontalBar` · `stackedBar` · `combo` · `line` · `area` · `pie` · `doughnut` · `scatter` · `bubble` · `funnel` · `heatmap`.
 
-```
-params:
-    new_stage: dropdown required "New Stage"
-    note: textarea "Note"
-    amount: number required "Amount"
-```
+Chart config: `{ chartType, categoryCol, valueCol, agg, seriesCol?, sizeCol?, chartSize? ('sm'|'m'|'l'|'xl'), clickAction?, showTrend?, series? }`. `agg` ∈ `sum|avg|min|max|count`.
 
-Access in execute block: `params[param_name]`
+### KPI config (metrics)
 
-See `references/action-dsl.md` for full syntax.
+`config.metrics` is an array; each metric is one of two modes:
 
-### Named parameter sets (saved combos)
+**Aggregation metric** — one column reduced by one aggregation:
 
-Users can save frequently-used parameter combinations for quick reuse. These are stored per-report or per-action and appear in a dropdown at the top of the parameter dialog. Defined at runtime (not in the module package).
+```json
+{ "column": "amount", "agg": "sum", "display": "value", "label": "Open Pipeline" }
+```
 
-### Cross-parameter validation
+Optional: `display` (`value|gauge|progress|sparkline|icon`), `label`, `target`/`min`/`max`, `icon`, `sparklineDimension`.
 
-Parameters can have cross-validation rules (e.g. `end_date >= start_date`). This is configured via a `validate` formula on the parameter set. For module packages, validation is typically handled by sensible defaults rather than explicit cross-validation formulas.
+**Formula metric** — an expression over named aggregation *inputs* (ratios, derived numbers):
 
-## Layout
+```json
+{
+    "label": "Avg Deal Size",
+    "formula": "[total] / [n]",
+    "inputs": [
+        { "alias": "total", "column": "amount", "agg": "sum" },
+        { "alias": "n",     "column": "amount", "agg": "count" }
+    ],
+    "format": { "style": "number", "decimals": 0 }
+}
+```
+
+- `formula` references each input by `[alias]`. Missing alias → `0`; non-finite (÷0, NaN) → blank.
+- `format.style` ∈ `number|percent`; `decimals` sets fraction digits. **Omit `format` (Auto)** to inherit the *first input column's own formatter* — a money formula then reads as money.
+
+### Cross-source metrics & overlay series
 
-The `layout` array defines how datasets are visualized:
+A report already loads **multiple datasets**, so a KPI formula input or a chart overlay series can aggregate over a **sibling** dataset — reference it by its dataset code via `source` (omit = the panel's own `datasetCd`).
+
+**Cross-dataset KPI** (pipeline vs leads):
 
 ```json
-"layout": [
-    {
-        "vizType": "bar",
-        "datasetCd": "ds_pipeline",
-        "title": "Pipeline by Stage",
-        "config": {
-            "categoryCol": "stage",
-            "valueCol": "total_value",
-            "agg": "sum",
-            "chartSize": "l"
-        }
-    },
-    {
-        "vizType": "grid",
-        "datasetCd": "ds_pipeline",
-        "title": "Detail"
-    },
-    {
-        "vizType": "kpi",
-        "datasetCd": "ds_pipeline",
-        "title": "Total Value",
-        "config": {
-            "valueCol": "total_value",
-            "format": "currency"
-        }
-    },
-    {
-        "vizType": "pie",
-        "datasetCd": "ds_pipeline",
-        "title": "Distribution",
-        "config": {
-            "categoryCol": "stage",
-            "valueCol": "opp_count"
-        }
-    }
-]
+{ "vizType": "kpi", "datasetCd": "deals", "config": { "metrics": [
+    { "label": "Total Funnel Value", "formula": "[pipeline] + [leadval]", "inputs": [
+        { "alias": "pipeline", "column": "amount", "agg": "sum" },
+        { "alias": "leadval", "column": "estimated_value", "agg": "sum", "source": "leads" }
+    ] }
+] } }
 ```
 
-### Visualization types
+**Cross-source chart overlay** — `config.series` (a single object **or** an array) adds series aggregated from other datasets, aligned on a shared category axis. Supported on `bar`/`horizontalBar`/`line`/`area`. Categories are outer-joined; a missing bucket fills `0` (bar) or gaps with `null` (line/area). Keep each series' `categoryCol` matching the primary axis unless a different axis is intended.
 
-| `vizType` | Description | Config |
-|---|---|---|
-| `grid` | Tabular data with sort/filter | — |
-| `bar` | Vertical bar chart | `categoryCol`, `valueCol`, `agg` |
-| `bar-stacked` | Stacked vertical bar | `categoryCol`, `valueCol`, `stackCol`, `agg` |
-| `h-bar` | Horizontal bar | Same as `bar` |
-| `line` | Line chart | `categoryCol`, `valueCol`, `agg` |
-| `area` | Area chart | Same as `line` |
-| `pie` | Pie chart | `categoryCol`, `valueCol` |
-| `doughnut` | Doughnut chart | Same as `pie` |
-| `scatter` | Scatter plot | `xCol`, `yCol` |
-| `combo` | Combined bar + line | `categoryCol`, `barCol`, `lineCol` |
-| `kpi` | Single value card | `valueCol`, `format` (optional: gauge, progress, sparkline, icon variants) |
-| `pivot` | Pivot table | `rowCols`, `colCols`, `valueCols`, `aggFunc` |
+```json
+{ "vizType": "chart", "datasetCd": "deals", "config": {
+    "chartType": "bar", "categoryCol": "lead_source", "valueCol": "amount", "agg": "sum",
+    "series": { "source": "leads", "categoryCol": "lead_source", "valueCol": "estimated_value", "agg": "sum", "label": "Lead Value" }
+} }
+```
 
-### Chart size
+Dashboard KPI/chart *tiles* get the same support via a `sources` map in the tile config (authored with "Add source" in the tile dialog) — not part of a module's `ui/reports.json`.
 
-Chart visualizations support an optional `config.chartSize` property to control the default display height.
+### Chart size
 
-| Field | Type | Allowed values | Description |
-|---|---|---|---|
-| `config.chartSize` | string | `sm`, `m`, `l`, `xl` | Optional size preset for chart height. When omitted, the default is `m`. |
+`config.chartSize` ∈ `sm | m | l | xl` controls the default chart height (`m` when omitted).
 
 ## Grants
 
-Report access is granted via the `E` right:
+Grant report access with the `E` right:
 
 ```json
-"rights": {
-    "report.sales_pipeline": "E"
-}
+"rights": { "report.sales_pipeline": "E" }
 ```
 
 ## Common mistakes
 
-- Mixing `entityCode` + SP fields (`datasetType`, `sp`, `columnsDef`) in the same dataset — pick one source type.
-- Forgetting `columnsDef` on SP datasets — **required** (platform can't infer columns from a function).
-- Forgetting to grant `E` access in at least one role — report becomes invisible.
-- Forgetting `p_folder_uid` and `p_user_id` as first two SP function params — call will fail.
-- Using `panels` instead of `layout` for the visualization array — use `layout`.
-- Using `widget` instead of `vizType` — use `vizType`.
+- Using a bare `"layout": [ ... ]` array — `layout` is an **object**: `"layout": { "panels": [ ... ] }`.
+- Setting the chart kind as `vizType` (`"vizType": "bar"`) — the panel `vizType` is `"chart"`; the kind goes in `config.chartType`.
+- Using `entityCode` / `groupBy` / `aggregations` on a dataset — use `query.entityCd` + `query.columns`, and aggregate in the viz (`agg`, `metrics`).
+- Using `sp` / `procedureName` for an SP dataset — the field is `spCd`.
+- Forgetting `columnsDef` on an SP dataset — **required**.
+- Forgetting to grant `E` on the report in at least one role — it becomes invisible.
+- Forgetting `p_folder_uid` / `p_user_id` as the first two SP function params — the call fails.
 - Referencing a parameter as `$param` — use `@param_code` in filters.

package/skills/dforge-mcp-author/references/validation-checklist.md

@@ -1,6 +1,6 @@
 # Validation Checklist
 
-Run through this checklist **before** declaring a module complete. Do it mentally if there's no validate CLI available; run `dforge validate .` if there is.
+Run through this checklist **before** declaring a module complete. Always start with `dforge_module_validate` when the MCP server is connected; if you are outside MCP, use the current CLI equivalent: `dforge-cli module validate <moduleDir>`.
 
 ## Top install-blockers (scan first)
 
@@ -154,10 +154,11 @@ For each action:
 
 ## After validation
 
-- [ ] If a local `dforge validate .` CLI is available, run it and fix any errors
-- [ ] Try to `dforge package .` to build the `.dforge` file — it should succeed
-- [ ] If MCP is connected, run `dry_run_install` to see the generated SQL
-- [ ] Only after dry-run looks clean, `install_module` or `install-to-dev`
+- [ ] Run `dforge_module_validate` and fix every `error` in `files["_validate.json"]`
+- [ ] Run `dforge_module_pack` to build the `.dforge` file — it should succeed
+- [ ] Run `dforge_module_install` against a real test tenant — this is the full server-side validator
+- [ ] If `dforge_module_install` returns `ok: false`, read the returned `output`, fix the module defect it reports, then repeat validate → pack → install
+- [ ] Stop and ask the user only for environment/tooling failures: missing CLI, missing/expired token, unreachable tenant/API, permissions, or a path outside the workspace
 
 ## Red flags during review
 
@@ -180,4 +181,4 @@ If you see any of these, stop and investigate:
 
 ## When the checklist passes
 
-Tell the user what you built, summarize the entity model (e.g. "7 entities: contact, account, opportunity with its line items, quote with lines, activity, product"), list the data views and actions, and describe the security roles. Then ask if they want to install it.
+Tell the user what you built, summarize the entity model (e.g. "7 entities: contact, account, opportunity with its line items, quote with lines, activity, product"), list the data views and actions, describe the security roles, and run the Phase 6 install loop. The module is not complete until `dforge_module_install` succeeds against a real tenant.