@graphit/cli 0.2.208 → 0.2.242

package/dist/commands/status.js

@@ -0,0 +1,117 @@
+import { apiClient } from "../api/client.js";
+import { output, errorOutput, getOutputFormat, note } from "../output/format.js";
+import { styledIntro, styledOutro, styledMessage, styledTable, } from "../output/styled.js";
+export const DOMAIN_COLUMNS = ["domain", "query_access", "data_sources", "knowledge_base"];
+// Scopes this CLI version knows how to render in the human views. Anything else
+// the server sends still reaches the caller verbatim in --output json; the human
+// views name it without guessing at its shape (FC-4).
+const KNOWN_SCOPES = new Set(["templates"]);
+const DEFAULT_ADVISORY = "Advisory only. Every operation is re-authorized at execution time and " +
+    "other permissions may still apply.";
+/** Readable-domain rows for the table view. Tolerates a missing/!array field. */
+export function statusDomainRows(status) {
+    return Array.isArray(status.domains) ? status.domains : [];
+}
+// A capability the server did not state is UNKNOWN, not denied. Rendering an
+// absent field as "no" would invent a restriction the response never described -
+// the same forward-compatibility trap as failing on an unknown key (FC-4).
+function yesNo(value) {
+    if (value === true)
+        return "yes";
+    if (value === false)
+        return "no";
+    return "unknown";
+}
+/**
+ * Human summary lines shared by the table and styled views: identity, profile,
+ * domain counts, the Templates scope, warehouse access, and policy freshness.
+ * Renders only what the server sent - it never infers a capability the response
+ * did not state, and hidden domains stay a count.
+ */
+export function statusLines(status) {
+    const identity = status.identity ?? {};
+    const profile = status.profile ?? {};
+    const policy = status.policy ?? {};
+    const scopes = status.special_scopes ?? {};
+    const domains = statusDomainRows(status);
+    const hidden = status.summary?.inaccessible_domain_count ?? 0;
+    const lines = [];
+    lines.push(`User:         ${identity.user_id ?? "unknown"}`);
+    lines.push(`Organization: ${identity.org_id ?? "unknown"} (role: ${identity.org_role ?? "unknown"})`);
+    lines.push(profile.id
+        ? `Profile:      ${profile.name ?? profile.id}${profile.mode ? ` (${profile.mode})` : ""}`
+        : "Profile:      none assigned");
+    if (profile.not_migrated) {
+        lines.push("              Profile predates domain permissions - ask an org admin to update it.");
+    }
+    lines.push(`Domains:      ${domains.length} readable` + (hidden > 0 ? `, ${hidden} not visible` : ""));
+    const templates = scopes.templates;
+    if (templates) {
+        lines.push(`Templates:    read/use ${yesNo(templates.read_use)}, write ${yesNo(templates.write)}`);
+    }
+    if (policy.allow_direct_warehouse !== undefined) {
+        lines.push(`Warehouse:    direct queries ${policy.allow_direct_warehouse ? "allowed" : "not allowed"}`);
+    }
+    const freshness = [
+        policy.version != null ? `version ${policy.version}` : null,
+        policy.evaluated_at ? `evaluated ${policy.evaluated_at}` : null,
+        policy.max_cache_age_seconds != null ? `cached up to ${policy.max_cache_age_seconds}s` : null,
+    ].filter(Boolean);
+    if (freshness.length > 0)
+        lines.push(`Policy:       ${freshness.join(", ")}`);
+    const extra = Object.keys(scopes).filter((key) => !KNOWN_SCOPES.has(key));
+    if (extra.length > 0) {
+        lines.push(`Other scopes: ${extra.join(", ")} (see --output json)`);
+    }
+    lines.push("");
+    lines.push(typeof status.advisory === "string" && status.advisory ? status.advisory : DEFAULT_ADVISORY);
+    return lines;
+}
+export function registerStatusCommand(program) {
+    program
+        .command("status")
+        // Kept to one clause: a top-level leaf command's description is emitted TWICE
+        // in the generated table (group header + row), against a capped always-loaded
+        // file. The depth lives in references/operations.md.
+        .description("Show your effective permissions per domain (advisory; the server re-authorizes every operation)")
+        .action(async function () {
+        try {
+            const status = await apiClient.get("/api/v1/cli/status");
+            const fmt = getOutputFormat(this);
+            const rows = statusDomainRows(status);
+            if (fmt === "styled") {
+                styledIntro("graphit status");
+                // The same lines the table view prints, verbatim: any per-format
+                // reshaping here (e.g. splitting on ":") silently drops the lines that
+                // do not fit the shape, and the formats stop agreeing.
+                styledMessage(statusLines(status).join("\n"));
+                if (rows.length > 0) {
+                    styledMessage(styledTable(DOMAIN_COLUMNS, rows.map((r) => [
+                        r.domain,
+                        r.query_access ?? "",
+                        r.data_sources ?? "",
+                        r.knowledge_base ?? "",
+                    ])));
+                }
+                // The advisory already closes the summary block above - repeating it in
+                // the outro reads as two different warnings.
+                styledOutro();
+                return;
+            }
+            if (fmt === "json") {
+                // Verbatim server payload: unknown special_scopes keys and unknown
+                // top-level fields reach the caller untouched (FC-4).
+                output(this, status);
+            }
+            else {
+                output(this, rows, { columns: DOMAIN_COLUMNS });
+            }
+            for (const line of statusLines(status))
+                note(line);
+        }
+        catch (err) {
+            errorOutput(err);
+        }
+    });
+}
+//# sourceMappingURL=status.js.map

package/dist/commands/status.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"status.js","sourceRoot":"","sources":["../../src/commands/status.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -5,6 +5,7 @@
 import "./ca-guard.js";
 import { Command } from "commander";
 import { registerAuthCommands } from "./commands/auth.js";
+import { registerStatusCommand } from "./commands/status.js";
 import { registerKBCommands } from "./commands/kb.js";
 import { registerQueryCommands } from "./commands/query.js";
 import { registerDSCommands } from "./commands/ds.js";
@@ -27,6 +28,7 @@ program
     .version(getCurrentVersion())
     .option("--output <format>", "Output format: json (default), table, or styled", "json");
 registerAuthCommands(program);
+registerStatusCommand(program);
 registerKBCommands(program);
 registerQueryCommands(program);
 registerDSCommands(program);

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/output/format.js

@@ -28,9 +28,15 @@ export function output(cmd, data, opts) {
 export function note(message = "") {
     console.error(message);
 }
+// Project #263: a denial reaches the caller with its machine-readable problem
+// intact, alongside the human message. The message carries only the server's own
+// safe `detail` and `next_step` - never a raw status code, a hidden resource
+// name, or a locally invented explanation - and a denial always exits nonzero,
+// so a deterministic "you cannot do this" can never read as success.
 export function errorOutput(err) {
     let message;
     let retryAfter;
+    let problem;
     if (err instanceof Error) {
         message = err.message;
     }
@@ -40,6 +46,9 @@ export function errorOutput(err) {
         if (typeof obj.retry_after_seconds === "number") {
             retryAfter = obj.retry_after_seconds;
         }
+        if (obj.problem && typeof obj.problem === "object" && !Array.isArray(obj.problem)) {
+            problem = obj.problem;
+        }
     }
     else {
         message = String(err);
@@ -47,7 +56,15 @@ export function errorOutput(err) {
     if (retryAfter !== undefined) {
         message = `${message} Retry in ${retryAfter}s.`;
     }
-    console.error(JSON.stringify({ error: message }));
+    // Read the field, never match the prose: the server owns the corrective step.
+    const nextStep = problem?.next_step;
+    if (typeof nextStep === "string" && nextStep && !message.includes(nextStep)) {
+        message = `${message} ${nextStep}`;
+    }
+    const payload = { error: message };
+    if (problem)
+        payload.problem = problem;
+    console.error(JSON.stringify(payload));
     process.exit(1);
 }
 //# sourceMappingURL=format.js.map

package/dist/output/format.js.map

@@ -1 +1 @@
-{"version":3,"file":"format.js","sourceRoot":"","sources":["../../src/output/format.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAoBzD,MAAM,UAAU,eAAe,CAAC,GAAY;IAC1C,IAAI,IAAI,GAAG,GAAG,CAAC;IACf,OAAO,IAAI,CAAC,MAAM;QAAE,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC;IACvC,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC,MAAgB,CAAC;IAC5C,IAAI,MAAM,KAAK,QAAQ;QAAE,OAAO,QAAQ,CAAC;IACzC,OAAO,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC;AAC/C,CAAC;AAED,MAAM,UAAU,MAAM,CACpB,GAAY,EACZ,IAAa,EACb,IAAiD;IAEjD,MAAM,MAAM,GAAG,eAAe,CAAC,GAAG,CAAC,CAAC;IAEpC,IAAI,MAAM,KAAK,MAAM,EAAE,CAAC;QACtB,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC;QAC9B,OAAO;IACT,CAAC;IAED,IAAI,IAAI,EAAE,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QAC3C,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,IAA+B,CAAC,CAAC,CAAC;QAC7D,OAAO;IACT,CAAC;IAED,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IACjD,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC,IAAiC,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC;AAC7E,CAAC;AAED,8EAA8E;AAC9E,iFAAiF;AACjF,+EAA+E;AAC/E,MAAM,UAAU,IAAI,CAAC,OAAO,GAAG,EAAE;IAC/B,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;AACzB,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,GAAY;IACtC,IAAI,OAAe,CAAC;IACpB,IAAI,UAA8B,CAAC;IAEnC,IAAI,GAAG,YAAY,KAAK,EAAE,CAAC;QACzB,OAAO,GAAG,GAAG,CAAC,OAAO,CAAC;IACxB,CAAC;SAAM,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;QACnD,MAAM,GAAG,GAAG,GAA8B,CAAC;QAC3C,OAAO,GAAI,GAAG,CAAC,MAAiB,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC;QAChD,IAAI,OAAO,GAAG,CAAC,mBAAmB,KAAK,QAAQ,EAAE,CAAC;YAChD,UAAU,GAAG,GAAG,CAAC,mBAAmB,CAAC;QACvC,CAAC;IACH,CAAC;SAAM,CAAC;QACN,OAAO,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;IACxB,CAAC;IAED,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;QAC7B,OAAO,GAAG,GAAG,OAAO,aAAa,UAAU,IAAI,CAAC;IAClD,CAAC;IAED,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC;IAClD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC"}
+{"version":3,"file":"format.js","sourceRoot":"","sources":["../../src/output/format.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@graphit/cli",
-  "version": "0.2.208",
+  "version": "0.2.242",
   "description": "Graphit CLI - Build custom dashboards from any AI coding assistant",
   "repository": {
     "type": "git",

package/scripts/generate-commands-doc.mjs

@@ -28,7 +28,7 @@ const END = "<!-- COMMANDS:END -->";
 
 // Mirrors index.ts registration order; groups not listed are appended alphabetically.
 const GROUP_ORDER = [
-  "auth", "kb", "query", "metadata", "ds", "dashboard",
+  "auth", "status", "kb", "query", "metadata", "ds", "dashboard",
   "connector", "governance", "team", "plugin", "setup",
 ];
 

package/skills/graphit/SKILL.md

@@ -2,10 +2,10 @@
 name: graphit
 description: >-
   Use Graphit for ANY question about the user's business or product data: metrics, KPIs, revenue, retention, spend, users, cohorts, funnels, trends, comparisons, "why did X change", "how are we doing on Y", analysis, reports, or dashboards. Activate even when the user does not say "Graphit" or name any tool: if someone wants to understand their numbers, this is the tool. Graphit answers through a governed semantic layer (computed the team's way, reusable and safe to share) and delivers the answer as a fast cached-data query or a hand-authored interactive HTML dashboard, and can create the metrics, dimensions, and rules an answer needs. Prefer Graphit over hand-rolled one-off analysis whenever the data is, or could be, the user's business data. Skip only for pure software tasks (code, logs, config, infra) or data with nothing to do with the user's business.
-skill_version: "0.2.208"
+skill_version: "0.2.242"
 ---
 
-<!-- SIZE EXEMPTION (SKILL.md): standard hard limit 12,288 chars, exempted ceiling 28,672. Always-loaded: the collaboration/pace spine, hard constraints + scope gate, the loop, and the generated command table (COMMANDS markers, scripts/generate-commands-doc.mjs) - needed every turn, cannot defer to a reference. Marker sits after the frontmatter so the loader and sync-plugin-version.mjs parse it. Reviewed 2026-07-20. -->
+<!-- SIZE EXEMPTION (SKILL.md): standard hard limit 12,288 chars, exempted ceiling 29,696. Always-loaded: the collaboration/pace spine, hard constraints + scope gate, the loop, and the generated command table (COMMANDS markers, scripts/generate-commands-doc.mjs) - needed every turn, cannot defer to a reference. Marker sits after the frontmatter so the loader and sync-plugin-version.mjs parse it. Reviewed 2026-07-20. -->
 
 # Graphit CLI
 
@@ -105,7 +105,7 @@ One loop serves both jobs. Each step names the reference to read when you need d
    - Data source. `graphit kb explore domain <NAME>` returns that domain's data sources plus their metrics, dimensions, and rules in one traversal (`graphit ds list` for the full list); present the sources, ask which one, or offer to create one if none fits.
    - Assets. Present the chosen source's metrics, dimensions, and rules as the working set and confirm it. If the user's wording doesn't match an asset, resolve it with `graphit kb search` (semantic, ranked by relevance) before assuming a mapping; for a cross-domain investigation, broaden across the whole KB. A 0-result search is not proof of absence (results are ranked and capped) - confirm a specific name with `kb get` first. Then proceed.
    Ask via the structured ask-user tool above, options pre-populated from what you listed. Read references/kb-discovery.md, references/kb-traversal.md, references/data-sources.md.
-3. KB-readiness gate (BLOCKING). Check the knowledge base has the metrics and dimensions this question needs - name them from the user's ask and the domain's real assets you just listed. If they exist, proceed. If any are missing, STOP and build the knowledge base first: identify the missing concepts, show a gap table (what is missing, the proposed definition, which rules apply), get approval, then create and verify the assets. Read references/kb-structure.md, references/kb-actions.md, and references/parameterized-metrics.md for variant axes (D7/D30, gross/net). This gate is not optional - do not reframe it as the user's choice.
+3. KB-readiness gate (BLOCKING). Check the knowledge base has the metrics and dimensions this question needs - name them from the user's ask and the domain's real assets you just listed. If they exist, proceed. If any are missing, STOP and build the knowledge base first: identify the missing concepts, show a gap table (what is missing, the proposed definition, which rules apply), get approval, then create and verify the assets. Run `graphit status` first for the domains you can write to - advisory (the server still decides). Read references/kb-structure.md, references/kb-actions.md, and references/parameterized-metrics.md for variant axes (D7/D30, gross/net). This gate is not optional - do not reframe it as the user's choice.
 4. Investigate. Write governed queries with `{{metric:NAME}}` / `{{dim:NAME}}` reference syntax, validate before you rely on them, show the rows, then propose the next cut or the first graph before building it. Ad-hoc only at the frontier, provenance-tagged. Read references/sql-reference.md, references/governance.md.
 5. Deliver. A quick query result for a one-off; a designed HTML dashboard for anything recurring or shared; or a written report artifact - insight digest, analysis one-pager, postmortem - when narrative should lead. Build and show one section at a time, not one finished deliverable at the end. Pull only the reference for the move you are making:
    - Frame and plan the dashboard (or report artifact): references/dashboard-planning.md.
@@ -148,13 +148,14 @@ Read the one that matches what you are doing now. Do not preload them. Exact com
 | designing and rendering the dashboard | dashboard-planning.md, chart-selection.md, chart-patterns.md, graphit-style.md, runtime.md, kpi.md, table.md |
 | adding interactivity (filters, parameters, saved views) | filters.md, filters-advanced.md |
 | building a slide deck | presentations.md |
+| moving an existing dashboard's queries onto its entities, or explaining a legacy-query save warning | migration.md |
 | the CLI or plugin itself (health, permission errors, local working artifacts) | operations.md |
 | installing, updating, or repairing Graphit itself | install-update.md |
 | reporting a failure or a partial result | reporting.md |
 
 ## Commands
 
-Graphit is one CLI, but how you invoke it depends on your environment. On Claude Code the plugin provides a `graphit` wrapper, so `graphit <command>` runs the current CLI. On Codex, Cursor, a terminal, or CI there is no `graphit` wrapper - invoke the CLI explicitly with `npx -y @graphit/cli@0.2.208 <command>` (a stamped version, kept current by the build; pin an exact version for a reproducible run). The table below is generated from the CLI itself - the source of truth for which commands, subcommands, and flags exist. For exact flag values and full descriptions, run `graphit <command> --help` - never guess a flag.
+Graphit is one CLI, but how you invoke it depends on your environment. On Claude Code the plugin provides a `graphit` wrapper, so `graphit <command>` runs the current CLI. On Codex, Cursor, a terminal, or CI there is no `graphit` wrapper - invoke the CLI explicitly with `npx -y @graphit/cli@0.2.242 <command>` (a stamped version, kept current by the build; pin an exact version for a reproducible run). The table below is generated from the CLI itself. For exact flags, run `graphit <command> --help` - never guess a flag.
 
 <!-- COMMANDS:START -->
 
@@ -165,6 +166,9 @@ _Generated from the CLI by `npm run gen:commands` - do not hand-edit between the
 - `auth status` - Show current authentication status
 - `auth logout` - Log out and clear stored credentials
 
+**status** - Show your effective permissions per domain (advisory; the server re-authorizes every operation)
+- `status` - Show your effective permissions per domain (advisory; the server re-authorizes every operation)
+
 **kb** - Knowledge Base operations
 - `kb list <type>` - List KB entities (metric, dimension, table, rule, domain, synonym) - the inventory verb. Parameterized metrics are collapsed: each template shows a variant_count, child variants are hidden. Use --include-variants for the full flat set, kb explore metric <name> to enumerate one template's variants, kb get for the full definition. The response carries total/truncated, so fewer rows than total means raise --limit. - `--limit --verified --unverified --include-variants`
 - `kb get <type> <name>` - Get a KB entity by name
@@ -201,10 +205,12 @@ _Generated from the CLI by `npm run gen:commands` - do not hand-edit between the
 
 **ds** - Data source management
 - `ds refresh-history <id>` - Show recent refresh runs for a data source with the Snowflake query id per run (status, time, rows, duration). Runs from before query-id capture - or a failure before any query ran - show 'not captured'. Read-only; no ds refresh-history delete. - `--limit`
+- `ds delete <id>` - Delete a data source - not available on the CLI, use the Sources Hub
+- `ds move <id>` - Move a data source between domains - not available on the CLI, use the Sources Hub
 - `ds list` - List data sources - `--limit`
 - `ds create` - Create a data source from a SQL query (--sql) or a local Excel/CSV file (--file) - `--sql --name --connection --schema --skip-scan --detect-tables --source-tables --file --domain --sheet`
 - `ds refresh [ids...]` - Refresh data sources (use --all for all, or pass one or more IDs). On a breaking schema change a refresh is paused (status 'schema_changed') and the old data keeps serving; re-run with --force to accept the new schema. - `--all --no-wait --skip-empty --force`
-- `ds verify <id>` - Scan an unverified data source's schema and review it. Warehouse/SQL sources print a verification link; add --accept-schema to accept the AI schema and activate from the CLI. File uploads activate automatically. - `--force --accept-schema`
+- `ds verify <id>` - Scan an unverified data source's schema and review it, and activate it. Warehouse/SQL sources print a verification link; add --accept-schema to accept the AI schema and activate from the CLI. File uploads activate on this command without --accept-schema, but NOT on create: `ds create --file` leaves them at pending_verification until you run this. Requires data_source_write in the source's domain. - `--force --accept-schema`
 - `ds update <id>` - Update a data source row cap - `--max-rows`
 - `ds refresh-config <id>` - Configure a data source's refresh mode (full or incremental/watermark) and settings. Sets the complete incremental config each call - omitted flags reset to server defaults (e.g. omitting --table-lookback clears existing lookback windows). - `--mode --watermark-column --watermark-type --merge-key --merge-window --table-lookback --reconciliation`
 

package/skills/graphit/VERSION.json

@@ -1,5 +1,5 @@
 {
   "package": "@graphit/cli",
-  "version": "0.2.208",
+  "version": "0.2.242",
   "source": "cli/package.json"
 }

package/skills/graphit/references/chart-patterns.md

@@ -56,7 +56,7 @@ For a custom look, draw your own SVG through the same entry: `graphit.graph(el,
 Escaping is yours: data-derived text through `ctx.esc()`, author colors through `ctx.safeColor()` - the runtime does not auto-escape your marks. Opt out per concern with `responsive: false` (render once) or `themed: false` (no dark re-draw).
 
 ```js
-const r = await graphit.resolve({ sql, dataSourceId: "ORDERS_DS", target: "#chart" });
+const r = await graphit.resolve({ target: "#chart" });
 graphit.graph("#chart", { type: "custom", draw: (ctx) => r.data.map(function (row, i) {
   var h = ctx.num(row.value) / 100 * ctx.height, x = (ctx.width / r.data.length) * i;
   return '<rect x="' + x + '" y="' + (ctx.height - h) + '" width="22" height="' + h +

package/skills/graphit/references/data-sources.md

@@ -55,7 +55,7 @@ graphit ds create --name "MY_DS" --sql "SELECT ..." --skip-scan
 
 **Warehouse connection.** `--connection` names the warehouse a `--sql` source reads from. Add BigQuery with `graphit connector add bigquery-serviceaccount --key-file <path> [--project --dataset --location]` (org admin; project defaults from the key). The pipeline routes by connection type - the same `ds create` works for either warehouse.
 
-For existing unverified sources, `graphit ds verify <id>` scans and shows the schema; add `--accept-schema` to accept the AI schema and activate a warehouse/SQL source from the CLI (file uploads activate automatically).
+For existing unverified sources, `graphit ds verify <id>` scans and shows the schema; add `--accept-schema` to accept the AI schema and activate a warehouse/SQL source from the CLI. A file upload needs `ds verify` too - it activates without `--accept-schema`, but never at create time, so it stays unqueryable until you run it.
 
 ## Refreshing data sources
 
@@ -80,7 +80,7 @@ Refreshes fire in parallel; polls to completion (large sources 30-60s), or retur
 
 ## Incremental refresh and early-filtering (advanced)
 
-Incremental mode fetches only rows past a watermark and merges them in. Three windows govern it: the **watermark column** (which output rows are new), the **merge window** (`--merge-window` - how far back each run re-fetches and upserts, healing late data; API responses call it `lookback_periods`), and per-table **lookback windows** (`--table-lookback` - how far back each source table is *read*). Set on a scanned source (creator only); each call sets the COMPLETE config - omitted flags reset to defaults (no `--table-lookback` = windows cleared).
+Incremental mode fetches only rows past a watermark and merges them in. Three windows govern it: the **watermark column** (which output rows are new), the **merge window** (`--merge-window` - how far back each run re-fetches and upserts, healing late data; API responses call it `lookback_periods`), and per-table **lookback windows** (`--table-lookback` - how far back each source table is *read*). Set on a scanned source; each call sets the COMPLETE config - omitted flags reset to defaults (no `--table-lookback` = windows cleared).
 
 When a source aggregates over a wide internal window (e.g. a multi-year rollup), incremental refresh is nearly as slow as full: the outer watermark filter can't prune the inner scan. Early-filtering fixes that - get the contract right first, or older periods silently corrupt on merge:
 
@@ -104,9 +104,15 @@ graphit ds refresh-config <id> --mode incremental \
 
 Only early-filter when an incremental source is slow for this reason; the default refresh is correct and simpler otherwise.
 
+## What needs write access
+
+Querying a source, listing sources, reading schema or refresh history, and an ordinary `graphit ds refresh` are reads - any member who can read that source's domain can run them, and a source in a domain they cannot read returns the same uniform 404 as one that does not exist. These need `data_source_write` in the source's domain: `ds create`, editing its SQL, `ds refresh-config`, a `--force` refresh or accepting a schema, `ds verify`, scanning, per-source governance settings, and deletion. Moving a source to another domain needs write in both the old and the new domain, and `ds create` must name a domain the caller can write to.
+
+Check `graphit status` for those domains before proposing a create or a config change. It is advisory - the server authorizes each operation when it runs, and a denial with `retryable: false` is a stop, not a retry (`operations.md`).
+
 ## Deleting data sources
 
-There is no `graphit ds delete` command. Deleting a data source cascades to storage and the KB table, removing all metrics, dimensions, and rules on it. Direct the user to the platform UI (Sources Hub), whose confirmation flow shows what will be affected.
+`ds delete` is not available on the CLI. Deleting a data source cascades to storage and the KB table, removing all metrics, dimensions, and rules on it. Direct the user to the platform UI (Sources Hub), whose confirmation flow shows what will be affected.
 
 ## Presenting data source results
 

package/skills/graphit/references/governance-explained.md

@@ -33,7 +33,7 @@ Enforcement is server-side and identical on every channel (agent, CLI, dashboard
 | Unenforced rule | A rule that structurally cannot act on anything |
 | Missing owner | Assets with nobody responsible for them |
 
-Fix is a guided one-click resolution: it drafts and previews the exact change, you apply it (analyst seat, same validation as a manual edit), then Graphit re-checks and clears the card. This queue lives only in the **web app's Governance page** - the CLI cannot list or fix Insights cards (`governance status` and `governance audit` report conformance only). When a user asks about a finding, explain what it means and point them to the Governance page to Fix it.
+Fix is a guided one-click resolution: it drafts and previews the exact change, you apply it (same validation as a manual edit), then Graphit re-checks and clears the card. This queue lives only in the **web app's Governance page** - the CLI cannot list or fix Insights cards (`governance status` and `governance audit` report conformance only). When a user asks about a finding, explain what it means and point them to the Governance page to Fix it.
 
 ## Relaying it
 

package/skills/graphit/references/kb-actions.md

@@ -1,6 +1,6 @@
 # KB Actions (Execute)
 
-The execute side of KB work: run approved create / update / delete through the `graphit kb` commands. The plan side - what a domain or topic is, why an asset sits where it does - lives in `kb-structure.md`. On a from-scratch build the two pair up (plan there, execute here); a normal build that reuses existing assets needs only this file.
+The execute side of KB work: run approved create / update / delete through the `graphit kb` commands. The plan side - what a domain or topic is, why an asset sits where it does - lives in `kb-structure.md`.
 
 Create only after the user approves the gap plan below. Names are stored UPPER_SNAKE_CASE. Run `graphit kb create <type> --help` for the exact flag spelling - this file teaches the recipes and policy, the CLI owns the syntax.
 
@@ -77,7 +77,18 @@ Reference a **metric or dimension** onto another table with `graphit kb update m
 
 Domain is set on the TABLE, never per asset, and cascades to every asset on it (model in `kb-structure.md`). To re-home a whole table at once: `graphit kb update table NAME --domain MARKETING`. Change it once on the table, never asset by asset.
 
-## Navigation
+## Who can write what
+
+Reads are open to every member; writes are scoped by the caller's data access profile. Check `graphit status` before presenting a gap plan, so the plan is one they can execute.
+
+| Write | Needs |
+|---|---|
+| Metric, dimension, rule, synonym, relationship, table | `kb_write` in the asset's domain |
+| Moving an asset or table to another domain | `kb_write` in BOTH domains - the one it leaves and the one it enters |
+| Domain and topic create / update / delete | Org admin; a profile never grants it |
+| Template create / update / delete | Org admin, OR `kb_write` in any one domain - never a per-template or per-domain grant |
+
+Every member can read and use templates. Status is advisory; a denial with `retryable: false` is a stop, not a retry (`operations.md`).
 
 To find what exists and how it connects, use the read recipes in `kb-traversal.md`.
 

package/skills/graphit/references/migration.md

@@ -0,0 +1,89 @@
+# Migrating a dashboard to entity-owned queries
+
+Load when the user asks to move an existing dashboard's queries onto its entities, or what a
+`legacy_query_source` save warning means. Not for authoring new dashboards: new work is canonical
+from the start (references/runtime.md).
+
+## What the old shape is
+
+Older dashboards author the same query twice. The call carries it:
+
+```js
+graphit.resolve({ sql: "SELECT ... WHERE d >= :start", dataSourceId: "MARKETING_UA_DS",
+  params: { start: pStart.get() }, sourceEntityId: "spend-trend" })
+```
+
+and the entity carries a copy in `data-graphit-sql` / `data-graphit-ds`. Both still work, and they
+drift: only the call executes, only the attribute is inspected.
+
+Canonical is the same query written once, on the entity, the call naming which entity to run:
+
+```js
+graphit.resolve({ sourceEntityId: "spend-trend", params: { start: pStart.get() } })
+```
+
+## Hard rules
+
+**NEVER migrate a dashboard the user did not ask about.** This is opt-in. An unrelated edit never
+rewires where a query lives, and "while I was in there" is not a reason.
+
+**NEVER save a partial or unverified migration.** Half-moved is worse than not moved. If you cannot
+finish and verify a query, put it back the way you found it.
+
+**MUST leave the dashboard untouched when you cannot prove equivalence.** Stop, change nothing, and
+name the exact branch you could not compare. That is a successful outcome, not a failure.
+
+## Procedure
+
+1. **Read everything first.** Get the full HTML and all its wiring before changing one call.
+   Migrating call by call misses shared queries and conditional branches.
+2. **Find the owner of each query.** One source entity owns it; any other entity rendered from the
+   same result is a target. A query feeding three graphs still has exactly one owner.
+3. **Lift the complete template onto the owner.** The whole statement in `data-graphit-sql`, the data
+   source in `data-graphit-ds`. Complete means executable and parameterized:
+   - Keep every `:named` placeholder. Do not bake current filter values in.
+   - Keep `{{metric:NAME}}` / `{{dim:NAME}}` references as they are.
+   - No ellipsis, no abbreviation, real table names, full WITH clause.
+4. **Preserve the rest exactly.** `params`, `deps`, the `render` callback, any branch that picks
+   different SQL, and `sourceEntityId` / `targetEntityIds` attribution all stay as they were.
+   Migration moves where the query lives; it does not rewrite the query, wiring, or layout.
+5. **Build the filter-state matrix.** The default state, plus every materially distinct non-default
+   or conditional branch found in step 1. A branch that selects different SQL is its own state.
+6. **Prove equivalence per state, on four signals.** For each state, compare before and after:
+
+   | Signal | Where it comes from |
+   |---|---|
+   | Effective SQL | the details panel's Current query (the server's execution receipt) |
+   | Bound parameter values | the same receipt |
+   | Row count | the resolve result |
+   | Hash of the complete result | hash all returned rows, not a sample |
+
+   All four must match. Sample rows are a sanity check, never the proof. If a result is too large to
+   hash completely, say so and treat that state as unverified.
+7. **Remove the explicit values only after that state passes.** Delete `sql` and `dataSourceId` only
+   once the entity owns the equivalent query and the comparison passed.
+8. **Save a named version,** so the migration is one recoverable step in version history.
+
+## Verifying
+
+Read the entity back rather than trusting what you wrote:
+
+```bash
+graphit dashboard get-entity <dashboard-id> <entity-id>
+```
+
+Act on `entity_sql_warnings` before reporting success. A parameterized template keeps its `:name`
+placeholders; save-time validation binds them before checking, so a warning is a real SQL problem,
+not the placeholders.
+
+## When to stop
+
+Stop, save nothing, and report the branch when:
+
+- SQL is composed by logic you cannot fully enumerate, so you cannot list every branch.
+- A code path exists that you cannot reach or trigger, so you cannot compare it.
+- A result is too large to hash completely.
+- Any state's four signals do not all match.
+
+Report which query, which branch, and which signal. The user can migrate the rest and leave that one
+query on the old shape, which is a legitimate end state.

package/skills/graphit/references/operations.md

@@ -2,14 +2,6 @@
 
 Load this when the concern is the Graphit CLI or plugin itself, not the analysis: the session-start check, a health check, a permission error (403/404/423), the output contract, or local working artifacts. Skip it on every healthy build or query turn.
 
-## Contents
-
-- [Session start](#session-start)
-- [Health gate](#health-gate)
-- [Permission errors](#permission-errors)
-- [Output contract](#output-contract)
-- [Working artifacts](#working-artifacts)
-
 Depth that lives elsewhere: installing, updating, or repairing Graphit -> references/install-update.md. Reporting a failure or a partial result -> references/reporting.md.
 
 Governance itself is enforced server-side by the query gateway: a governed query is rejected by the platform, not the CLI, so never claim to have blocked a query locally. The one local guard is a session tripwire - until this skill attests at session start (below), the CLI declines commands that change org state or that assert a governance decision (`--adhoc-reason`, `--override-rules`, `--skip-conditional`). That guard is about this session, never about the query itself, and dropping those flags does not skip governance - the server still decides.
@@ -46,10 +38,14 @@ The CLI enforces the same permission model as the platform. Three codes:
 
 | Code | Meaning | What to tell the user |
 |---|---|---|
-| 403 | Analyst seat or admin role required | Most commands need an Analyst seat. Viewer-seat users can run `graphit auth` only; everything else is blocked, so they use the platform UI. Connector create and delete also need an org owner or admin role, so a non-admin analyst gets 403 there. |
-| 404 | Not found, or no access | Returned for dashboards the user cannot reach (private ones owned by others, team dashboards they are not on). The API does not distinguish "does not exist" from "you cannot access it", to prevent ID enumeration. Do not assume the dashboard is gone. |
+| 403 | Your org role or data access profile does not allow this | Every signed-in member can use the CLI. This action needs more than the caller has: connector create/delete needs org owner or admin, and data source or knowledge-base writes are limited to the domains an admin granted on their data access profile. |
+| 404 | Not found, or no access | A permission 404 is uniform across a resource that does not exist, one the caller cannot see, and another org's id - deliberately indistinguishable, to prevent id enumeration (some older routes still name the missing entity). Never assume the thing is gone or tell the user it was deleted. |
 | 423 | Shared dashboard needs an active editing session | Catch one from the CLI: `graphit dashboard edit <id>` acquires the session and starts a draft; make the edits, then `graphit dashboard publish <id>` to go live (or `graphit dashboard release <id> --yes` to abandon). 409 = someone else is editing; 423 = locked; 403 = view-only. Private dashboards need no session. |
 
+A 403 body is structured: `code` (e.g. `domain.kb_write_required`), `required_capability`, `retryable`, `next_step`. Read those fields, never the prose. `retryable: false` is a decision, not a hiccup - stop, give the user the `next_step`, and never retry, route around it, or report the write as done. A 404 carries none of those by design.
+
+`graphit status` lists the caller's writable domains and Templates result - check it before planning writes, never reuse an older answer. Advisory only: the server re-authorizes every operation, so neither a past status nor a command's existence is permission.
+
 For the exact remediation flags on the failed command, run it with `--help`.
 
 ## Output contract