@graphit/cli 0.2.379 → 0.2.384

package/scripts/show-query-result.mjs

@@ -31,6 +31,27 @@ function isGraphitQuery(command) {
   return /(?:graphit|index\.js)\s+query\b/.test(command);
 }
 
+// Issue #1025: a query whose stdout is piped (`|`) or sent to a file (`>`) never
+// reaches this Bash call's output, so any JSON there belongs to another command.
+// Formats only when at least one query invocation writes to the call's stdout.
+// `2>` / `2>&1` redirect stderr only and do not count.
+function queryReachesStdout(command) {
+  const invocation = /(?:graphit|index\.js)\s+query\b/g;
+  for (const match of command.matchAll(invocation)) {
+    const tail = command.slice(match.index).split(/\n|;|&&|\|\||(?<![|&])&(?![&>])/)[0];
+    const withoutStderr = tail.replace(/\d?>&\d|2>>?\s*\S+/g, "");
+    if (!/(?<!\|)\|(?!\|)|>/.test(withoutStderr)) return true;
+  }
+  return false;
+}
+
+// Issue #1025: every CLI command prints JSON, and some carry `row_count`
+// (`ds create`, `ds re-upload`). Only a query result has a `rows` array together
+// with its `columns` or `provenance`.
+function isQueryResult(parsed) {
+  return Array.isArray(parsed.rows) && ("columns" in parsed || "provenance" in parsed);
+}
+
 // The CLI prints verbose SQL before and a provenance footer after the JSON, so
 // we extract the first complete top-level JSON object (string-aware brace match).
 function extractFirstJsonObject(text) {
@@ -166,7 +187,7 @@ function main() {
   if (payload.tool_name !== "Bash") return;
 
   const command = payload.tool_input?.command ?? "";
-  if (!isGraphitQuery(command)) return;
+  if (!isGraphitQuery(command) || !queryReachesStdout(command)) return;
 
   // tool_response may be an object ({stdout,stderr,...}) or a raw string.
   const resp = payload.tool_response;
@@ -188,9 +209,7 @@ function main() {
     emit(`### Graphit query failed\n\n\`${clean(parsed.error)}\``);
     return;
   }
-  if (!("rows" in parsed) && !("data" in parsed) && !("row_count" in parsed)) {
-    return;
-  }
+  if (!isQueryResult(parsed)) return;
   emit(buildMarkdown(parsed));
 }
 

package/scripts/sync-plugin-marketplace.sh

@@ -20,6 +20,10 @@ sync_marketplace() {
   # Project #298: the copied hook manifest must not reference absent scripts.
   cp cli/scripts/plugin-status.mjs cli/scripts/block-legacy-setup.mjs \
     cli/scripts/show-query-result.mjs "$target/scripts/"
+  # Feature #1042: plugin-status.mjs imports its modules from this folder; verify
+  # follows each hook script's relative imports, so a missing module fails there.
+  mkdir -p "$target/scripts/plugin-status"
+  rsync -a --delete cli/scripts/plugin-status/ "$target/scripts/plugin-status/"
 
   # Project #246: the public plugin ships wrappers that invoke the current CLI.
   mkdir -p "$target/bin"
@@ -98,6 +102,20 @@ for (const groups of Object.values(config.hooks)) {
     }
   }
 }
+// Feature #1042: a hook script's relative imports ship with it, so check them too.
+const importPattern = /(?:\bfrom\s+|\bimport\s*\(\s*|\bimport\s+)["'](\.{1,2}\/[^"']+)["']/g;
+const queue = [...files];
+while (queue.length > 0) {
+  const file = queue.shift();
+  if (!file.endsWith(".mjs") || !fs.existsSync(path.join("cli", file))) continue;
+  for (const match of fs.readFileSync(path.join("cli", file), "utf8").matchAll(importPattern)) {
+    const dependency = path.posix.normalize(path.posix.join(path.posix.dirname(file), match[1]));
+    if (!files.has(dependency)) {
+      files.add(dependency);
+      queue.push(dependency);
+    }
+  }
+}
 let valid = true;
 for (const file of files) {
   const destination = path.join(target, file);

package/scripts/verb-policy-source.json

@@ -300,22 +300,6 @@
       "requires_approval": true,
       "silent_retry_exempt": false
     },
-    "kb verify": {
-      "surface": "both",
-      "noun": "kb_write",
-      "is_read_only": false,
-      "mutation_class": "kb",
-      "requires_approval": true,
-      "silent_retry_exempt": false
-    },
-    "kb unverify": {
-      "surface": "both",
-      "noun": "kb_write",
-      "is_read_only": false,
-      "mutation_class": "kb",
-      "requires_approval": true,
-      "silent_retry_exempt": false
-    },
     "kb column-visibility": {
       "surface": "both",
       "noun": "kb_write",
@@ -440,6 +424,13 @@
       "requires_approval": false,
       "silent_retry_exempt": false
     },
+    "ds sql-history": {
+      "surface": "both",
+      "is_read_only": true,
+      "mutation_class": "none",
+      "requires_approval": false,
+      "silent_retry_exempt": false
+    },
     "ds usage": {
       "surface": "both",
       "is_read_only": true,
@@ -514,32 +505,60 @@
       "reason": "Not a working verb on either surface, and there is no UI action behind it (Issue #962). A source has no home of its own: it lives in the group of the semantic model bound to it, so `kb update semantic-model` with a new group is the move. The CLI registers `ds move` only to say so."
     },
     "dashboard folder spaces": {
-      "surface": "both", "noun": "dashboard", "is_read_only": true,
-      "mutation_class": "none", "requires_approval": false, "silent_retry_exempt": false
+      "surface": "both",
+      "noun": "dashboard",
+      "is_read_only": true,
+      "mutation_class": "none",
+      "requires_approval": false,
+      "silent_retry_exempt": false
     },
     "dashboard folder list": {
-      "surface": "both", "noun": "dashboard", "is_read_only": true,
-      "mutation_class": "none", "requires_approval": false, "silent_retry_exempt": false
+      "surface": "both",
+      "noun": "dashboard",
+      "is_read_only": true,
+      "mutation_class": "none",
+      "requires_approval": false,
+      "silent_retry_exempt": false
     },
     "dashboard folder get": {
-      "surface": "both", "noun": "dashboard", "is_read_only": true,
-      "mutation_class": "none", "requires_approval": false, "silent_retry_exempt": false
+      "surface": "both",
+      "noun": "dashboard",
+      "is_read_only": true,
+      "mutation_class": "none",
+      "requires_approval": false,
+      "silent_retry_exempt": false
     },
     "dashboard folder create": {
-      "surface": "both", "noun": "dashboard", "is_read_only": false,
-      "mutation_class": "dashboard", "requires_approval": true, "silent_retry_exempt": true
+      "surface": "both",
+      "noun": "dashboard",
+      "is_read_only": false,
+      "mutation_class": "dashboard",
+      "requires_approval": true,
+      "silent_retry_exempt": true
     },
     "dashboard folder update": {
-      "surface": "both", "noun": "dashboard", "is_read_only": false,
-      "mutation_class": "dashboard", "requires_approval": true, "silent_retry_exempt": true
+      "surface": "both",
+      "noun": "dashboard",
+      "is_read_only": false,
+      "mutation_class": "dashboard",
+      "requires_approval": true,
+      "silent_retry_exempt": true
     },
     "dashboard folder delete": {
-      "surface": "both", "noun": "dashboard", "is_read_only": false,
-      "mutation_class": "dashboard", "requires_approval": true, "silent_retry_exempt": true
+      "surface": "both",
+      "noun": "dashboard",
+      "is_read_only": false,
+      "mutation_class": "dashboard",
+      "requires_approval": true,
+      "silent_retry_exempt": true
     },
     "dashboard move": {
-      "surface": "both", "noun": "dashboard", "is_read_only": false,
-      "mutation_class": "dashboard", "requires_approval": true, "silent_retry_exempt": true
+      "surface": "both",
+      "noun": "dashboard",
+      "is_read_only": false,
+      "mutation_class": "dashboard",
+      "requires_approval": true,
+      "silent_retry_exempt": true
     },
     "dashboard list": {
       "surface": "both",

package/scripts/verify-kb-cutover.mjs

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+/** Bounded local fixture proof. Uses the normal CLI client/auth without modifying credentials. */
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { randomBytes } from 'node:crypto';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const FIXTURE_ORG = 'zz-test-293-kb-cutover';
+const BASE = '/api/v1/cli/kb';
+const RETIRED_KEYS = new Set(['verified', 'verified_by', 'verified_at', 'unverified']);
+const safeId = value => typeof value === 'string' && /^[a-zA-Z0-9_-]{1,128}$/.test(value);
+const statusCode = error => Number.isInteger(error?.status) ? error.status : null;
+const entityOf = response => {
+  if (response?.entity && typeof response.entity === 'object') return response.entity;
+  if (response?.rule && typeof response.rule === 'object') return response.rule;
+  return response;
+};
+function hasRetiredMetadata(entity) {
+  return Object.keys(entity ?? {}).some(k => RETIRED_KEYS.has(k)) ||
+    Object.keys(entity?.meta?.graphit ?? {}).some(k => RETIRED_KEYS.has(k));
+}
+function blocked(reason) { return {scope:'kb_authoring_and_retired_client_contract',status:'blocked',reason,created:[],checks:[],cleanup:[]}; }
+
+export async function runKBVerification({api, orgId, apiBaseUrl, runId = randomBytes(5).toString('hex')}) {
+  if (orgId !== FIXTURE_ORG) return blocked('undesignated_fixture_org');
+  let url;
+  try { url = new URL(apiBaseUrl); } catch { return blocked('invalid_api_url'); }
+  if (url.protocol !== 'http:' || !['localhost','127.0.0.1','[::1]'].includes(url.hostname) || url.username || url.password) return blocked('local_api_required');
+  if (!/^[a-z0-9]{1,16}$/.test(runId)) return blocked('invalid_run_id');
+
+  const report = {...blocked(null),status:'failed',org_id:orgId,run_id:runId};
+  report.not_run = [
+    {check:'cached_query_and_constraint_enforcement',reason:'No approved source fixture or cloud storage/KMS path supplied.'},
+    {check:'source_activation_and_breaking_schema_acceptance',reason:'No approved source fixture supplied.'},
+    {check:'scoped_non_admin_weakening_and_delete',reason:'Current CLI identity only; no separate member session supplied.'},
+    {check:'physical_tombstone_inspection',reason:'Public CRUD proves live absence only; storage inspection belongs to the cut runner.'},
+  ];
+  const owned = [];
+  report.unconfirmed_writes = [];
+  try {
+    const status = await api.get('/api/v1/cli/status');
+    if (status?.identity?.org_id !== orgId) return blocked('authenticated_org_mismatch');
+    if (!['owner','admin'].includes(status?.identity?.org_role)) return blocked('fixture_admin_required');
+    // A clean run only. Names with our prefix are not ownership evidence.
+    for (const noun of ['group','semantic-model','metric','rules','template']) {
+      const page = await api.get(`${BASE}/${noun}`);
+      if (!Array.isArray(page?.items) || page.total !== 0 || page.items.length || page.truncated || page.next_cursor) return blocked('fixture_not_empty');
+    }
+    report.checks.push({check:'authenticated_empty_visible_fixture',status:'passed'});
+    const fixtures = JSON.parse(await readFile(new URL('./fixtures/kb-cutover-project293.json',import.meta.url),'utf8'));
+    const names = Object.fromEntries(['group','semantic-model','metric'].map(noun => [noun,`zz_test_293_${noun.replaceAll('-','_')}_${runId}`]));
+    names.rule = `ZZ_TEST_293_RULE_${runId.toUpperCase()}`;
+    for (const noun of ['group','semantic-model','metric','rule']) {
+      const definition = structuredClone(fixtures[noun]);
+      definition.name = names[noun];
+      if (noun === 'metric' || noun === 'semantic-model') definition.group = names.group;
+      if (noun === 'rule') definition.apply_on = [{type:'model',name:names['semantic-model']}];
+      const body = noun === 'rule' ? definition : {definition};
+      let response;
+      try { response=await api.post(`${BASE}/${noun}`,body); }
+      catch(error) {
+        if(statusCode(error)===null || statusCode(error)>=500) report.unconfirmed_writes.push({noun,name:names[noun]});
+        throw error;
+      }
+      if(response?.detail?.applied === true && safeId(response.detail.doc_id)) {
+        const artifact={noun,name:names[noun],id:response.detail.doc_id};
+        owned.push(artifact);report.created.push({...artifact});
+        throw {status:202};
+      }
+      const created = entityOf(response);
+      if (!safeId(created?.id) || created.name !== names[noun]) throw {status:null};
+      const artifact = {noun,name:created.name,id:created.id};
+      owned.push(artifact); report.created.push({...artifact});
+      if (hasRetiredMetadata(created)) throw {status:null};
+      const readPath = noun === 'rule' ? `${BASE}/rules/${encodeURIComponent(created.id)}` : `${BASE}/${noun}/${encodeURIComponent(created.name)}`;
+      const actual = entityOf(await api.get(readPath));
+      if (actual?.id !== created.id || actual?.name !== created.name || hasRetiredMetadata(actual)) throw {status:null};
+      report.checks.push({check:`save_and_read_${noun}`,status:'passed',id:created.id});
+    }
+    const refusalCases = [
+      {check:'old_cli_unverified_false',path:`${BASE}/metric`,body:{definition:{...fixtures.metric,name:`zz_test_293_rejected_${runId}`,group:names.group},unverified:false},codes:[422]},
+      {check:'old_nested_verification',path:`${BASE}/metric`,body:{definition:{...fixtures.metric,name:`zz_test_293_rejected_${runId}`,group:names.group,meta:{graphit:{verified:false}}}},codes:[400,422]},
+      {check:'manual_verification_action',path:`${BASE}/metric/${names.metric}/verify`,body:{verified:true},codes:[404,405]},
+    ];
+    for (const scenario of refusalCases) {
+      let code = null;
+      try {
+        const accepted = entityOf(await api.post(scenario.path,scenario.body));
+        if (scenario.body.definition && safeId(accepted?.id) && accepted.name === scenario.body.definition.name) {
+          const artifact={noun:'metric',name:accepted.name,id:accepted.id};
+          owned.push(artifact);report.created.push({...artifact});
+        }
+      } catch (error) { code=statusCode(error); }
+      report.checks.push({check:scenario.check,status:scenario.codes.includes(code)?'passed':'failed',http_status:code});
+      if (!scenario.codes.includes(code)) throw {status:code};
+    }
+    report.status='passed';delete report.reason;
+  } catch (error) {
+    report.status='failed';report.reason='scenario_failed';report.http_status=statusCode(error);
+  } finally {
+    for (const artifact of owned.reverse()) {
+      const readPath = artifact.noun === 'rule' ? `${BASE}/rules/${encodeURIComponent(artifact.id)}` : `${BASE}/${artifact.noun}/${encodeURIComponent(artifact.name)}`;
+      try {
+        const current = entityOf(await api.get(readPath));
+        if (current?.id !== artifact.id || current?.name !== artifact.name) throw {status:409};
+        await api.delete(`${BASE}/${artifact.noun}/${encodeURIComponent(artifact.name)}`);
+        let absent=false;
+        try { await api.get(readPath); } catch (error) { absent=statusCode(error)===404; }
+        if (!absent) throw {status:409};
+        report.cleanup.push({...artifact,status:'deleted'});
+      } catch (error) {
+        report.cleanup.push({...artifact,status:'refused_or_failed',http_status:statusCode(error)});
+        report.status='failed';report.reason='cleanup_incomplete';
+      }
+    }
+  }
+  return report;
+}
+
+async function main() {
+  const args=process.argv.slice(2);
+  if (args.length!==4 || args[0]!=='--org-id' || args[2]!=='--output') throw new Error('Usage: --org-id <fixture-org> --output <proof.json>');
+  // Lazy loading keeps mock tests independent of persisted auth and token refresh.
+  const {apiClient}=await import('../dist/api/client.js');
+  const {getApiBaseUrl}=await import('../dist/config.js');
+  const result=await runKBVerification({api:apiClient,orgId:args[1],apiBaseUrl:getApiBaseUrl()});
+  const output=resolve(args[3]);await mkdir(dirname(output),{recursive:true});
+  await writeFile(output,JSON.stringify(result,null,2)+'\n',{mode:0o600});
+  process.stdout.write(JSON.stringify(result)+'\n');
+  if(result.status!=='passed')process.exitCode=1;
+}
+if(process.argv[1] && resolve(process.argv[1])===fileURLToPath(import.meta.url)) {
+  main().catch(()=>{process.stderr.write('KB fixture runner failed before producing evidence; no response or credential details are printed.\n');process.exitCode=1;});
+}

package/skills/graphit/SKILL.md

@@ -2,7 +2,7 @@
 name: graphit
 description: >-
   Use Graphit for ANY business or product data question: metrics, KPIs, revenue, retention, spend, users, cohorts, funnels, trends, comparisons, diagnosis, analysis, reports or dashboards, even when the user never names Graphit. This is the Graphit entry: identify the task and load graphit-explore, graphit-build or graphit-share. Use the team's governed definitions and cached data to deliver answers or interactive dashboards. Prefer Graphit over one-off analysis for the user's business numbers. Skip pure software tasks or data unrelated to their business.
-skill_version: "0.2.379"
+skill_version: "0.2.384"
 ---
 
 <!-- SIZE EXEMPTION (SKILL.md): hard limit 12,288 chars, exempted ceiling 35,072. Reviewed 2026-09-17. Always-loaded: identity, hard constraints, intent routing and the opening choice, plus the generated command table (COMMANDS markers; cli/scripts/generate-commands-doc.mjs) - needed every turn, not deferrable. Marker sits after the frontmatter so the loader and sync-plugin-version.mjs parse it. Raises pay only for command-table growth; each is recorded in docs/knowledge/prompt-engineering/sizing/SIZING.md, prose changes in docs/workflow/prompt-changes/INDEX.md. -->
@@ -113,6 +113,7 @@ Workflow rows below are generated in-app adapters; CLI hosts load the named work
 | creating, designing and rendering a dashboard | dashboard-create.md, 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, state-contract.md |
 | a graph switches metric, horizon, grain or grouping; typed query inputs | query-contract.md |
+| more than six requests on open, a query feeding another; slow open or Apply; declaring readiness | page-load.md |
 | reusing a chart across dashboards as a template, or expanding one on a host | templates.md |
 | building a slide deck | presentations.md |
 | scheduling, changing, sending or troubleshooting a scheduled report (email/Slack delivery) | scheduled-reports.md |
@@ -125,7 +126,7 @@ Workflow rows below are generated in-app adapters; CLI hosts load the named work
 
 ## Commands
 
-Claude Code supplies the `graphit` wrapper. On Codex, Cursor, terminals and CI, use `npx -y @graphit/cli@0.2.379 <command>`; pin a version for reproducibility. The table is generated from the CLI; check command help for exact flags.
+Claude Code supplies the `graphit` wrapper. If it is missing, and on Codex, Cursor, terminals and CI, use the pinned `npx -y @graphit/cli@0.2.384 <command>`. The table is generated from the CLI; check command help for exact flags.
 
 <!-- COMMANDS:START -->
 
@@ -154,14 +155,14 @@ _Generated by `npm run gen:commands`; do not hand-edit between the markers._
 - `kb repo token mint` - Mint a display-once CI machine token (org admin); scope kb:verify or kb:apply - `--scope`
 - `kb repo token list` - List CI machine tokens: metadata only, never the secret
 - `kb repo token revoke <token-id>` - Revoke a CI machine token (org admin)
-- `kb batch` - Apply many metric and semantic-model creates and updates as one Knowledge Base change (up to 50 per batch; 20 in-app). Items: {op: create, noun, definition, unverified?} or {op: update, noun, name, patch}; each passes the same checks as kb create/kb update and reports its own result, and readers rebuild once for the whole batch instead of once per edit. Groups, rules and deletes use their own verbs - `--file --json --stop-on-error`
+- `kb batch` - Apply many metric and semantic-model creates and updates as one Knowledge Base change (up to 50 per batch; 20 in-app). Items: {op: create, noun, definition} or {op: update, noun, name, patch}; each passes the same checks as kb create/kb update and reports its own result, and readers rebuild once for the whole batch instead of once per edit. Groups, rules and deletes use their own verbs - `--file --json --stop-on-error`
 - `kb template list` - List chart templates without their HTML
 - `kb template get <name>` - Fetch one chart template with its HTML. What expands in every adopting dashboard
 - `kb template create` - Create a chart template from an HTML fragment. A fragment may carry <script> and <style> and {{param}} placeholders in markup, never data-graphit-id/-sql/-ds/-label/-vocab/-state attributes: the host entity owns the query - `--name --file --json --description --params`
 - `kb template update <name>` - Update a chart template. A new fragment reaches every adopting dashboard on its next open - `--file --json --description --params`
 - `kb template delete <name>` - Delete a chart template (requires --yes). Adopting hosts render a missing marker - `--yes`
-- `kb create semantic-model` - Create a semantic model from a JSON definition (dbt shape: name, model, entities, dimensions, measures, defaults, group) - `--file --json --unverified`
-- `kb create metric` - Create a metric from a JSON definition (type: simple, ratio or derived, with type_params; advanced shapes remain unavailable). --family/--axis tag a concrete member of a metric family - `--file --json --family --axis --unverified`
+- `kb create semantic-model` - Create a semantic model from a JSON definition (dbt shape: name, model, entities, dimensions, measures, defaults, group) - `--file --json`
+- `kb create metric` - Create a metric from a JSON definition (type: simple, ratio or derived, with type_params; advanced shapes remain unavailable). --family/--axis tag a concrete member of a metric family - `--file --json --family --axis`
 - `kb create group` - Create a group (the domain analogue; admin only) - `--name --description --owner-email --access`
 - `kb create rule` - Create a retained Graphit governance rule from JSON. Targets use model:, entity:, dimension:, metric: or group: identities - `--file --json`
 - `kb update <noun> <name>` - Update an asset with a JSON patch. On semantic-model, a provided entities/dimensions/measures list replaces the stored list whole; explicit meta replaces author metadata whole - `--file --json`
@@ -175,8 +176,6 @@ _Generated by `npm run gen:commands`; do not hand-edit between the markers._
 - `kb family <family>` - Expand a metric family; with --axis constraints, resolve to the one concrete member (ambiguity answers with the still-open axes) - `--axis`
 - `kb explore <noun> <name>` - Traverse semantic reach. metric shows models, entities, dimensions and variants; semantic-model/group show bound metrics, families and rules
 - `kb usage [type] [name]` - Reverse lookup: dashboards using a semantic metric/dimension or enforcing a rule. Facets supplied by position or flags AND together - `--metric --dimension --rule`
-- `kb verify <noun> <name>` - Verify a Knowledge Base asset
-- `kb unverify <noun> <name>` - Unverify a Knowledge Base asset
 - `kb column-visibility <model> <column> <state>` - Set whether queries may read one physical column of a semantic model; hidden = masked as NULL everywhere (dashboards, exports, the AI). Unhiding a PII-detector hide takes the source's creator or an org admin, is recorded with who set it, and is for false positives only
 
 **query**
@@ -190,6 +189,7 @@ _Generated by `npm run gen:commands`; do not hand-edit between the markers._
 **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 usage [id]` - Show which canvas dashboards and graphs read a data source. With an id: each dashboard you can open and its graphs, plus a count of graphs on dashboards you cannot open. Without an id: dashboard_count and graph_count for every source you can read (0 = no graph uses it). A graph counts when its data-graphit-ds names the source, its governed metrics or dimensions come from the source's semantic model, or its SQL reads the source by name. Graphs composed only in JavaScript are not seen. Read-only; ds delete still re-checks metrics and rules.
+- `ds sql-history <id>` - Show the Source SQL versions of a data source, newest first: when, by whom, from which channel (web, cli, agent, repo) and which columns each edit added (+), removed (-) or retyped (~). --show <n> prints version n's SQL. Keeps the last 50; history starts at the first edit after it shipped. Read-only - to reuse an old version, pass its SQL to ds edit-sql. - `--show`
 - `ds move <id>` - Not a command anywhere: a source lives in its bound semantic model's group; kb update semantic-model moves it
 - `ds delete <id>` - Delete one of YOUR OWN private data sources (requires --yes). Shared sources are deleted in the Sources Hub, where the cascade is visible. - `--yes`
 - `ds re-upload <id>` - Replace an uploaded CSV/Excel source's contents in place - keeps its id, graph bindings, semantic model and history; never re-create with `ds create --file`. A changed column set needs --force - `--file --force`

package/skills/graphit/VERSION.json

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

package/skills/graphit/references/governance.md

@@ -16,7 +16,7 @@ The governed fragment path serves simple, ratio, and derived metrics. Cumulative
 
 ## Trust tiers
 
-- **governed:** verified semantic references compiled through the gateway.
+- **governed:** valid accessible semantic references compiled through the gateway.
 - **verified:** known safe stored query without semantic references.
 - **ad hoc:** raw SQL at the frontier.
 
@@ -24,7 +24,7 @@ Prefer governed. Never present ad-hoc SQL as the team's definition.
 
 ## Rules
 
-Rules target model, entity, dimension, metric, or group identities. Verified constraints enforce; verified body-only rules guide; drafts do nothing. Modes and EXPLORE behavior remain server-owned.
+Rules target model, entity, dimension, metric, or group identities. Saved constrained rules enforce according to their mode; body-only rules guide. Scope, source readiness and deprecation still apply. Modes and EXPLORE behavior remain server-owned.
 
 The gateway runs before caches, injects constraints, verifies resolved SQL, and returns a transparency receipt. Do not claim a rule applied merely because it exists.
 

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

@@ -6,7 +6,7 @@ Load when an approved gap must be authored or an existing semantic asset changed
 
 For a cached data source, first read its visible scanner-created semantic model and confirm `meta.graphit.data_source.ds_id` matches the source. Add approved entities, dimensions, or measures by updating that model. If no bound model is visible, follow the scan/verify flow in `data-sources.md`; creating a second model does not bind it.
 
-Before writing, present the missing concept, proposed root, exact definition, group/access scope, and verification state. Do not write until the user approves.
+Before writing, present the missing concept, proposed root, exact definition and group/access scope. Do not write until the user approves.
 
 ## Authoring contract
 
@@ -16,7 +16,7 @@ Before writing, present the missing concept, proposed root, exact definition, gr
 - Entities, dimensions, and measures mutate only through semantic-model update.
 - A supplied nested list replaces the stored list whole. Read first and include every sibling that must remain.
 - Explicit `meta` replaces author metadata whole. Preserve family, axes, topics, and other author fields.
-- Use dedicated verify/unverify actions. Never patch metadata merely to change verification.
+- Valid authorized saves are effective in their permitted scope. Do not send retired verification metadata or call manual verify/unverify actions.
 
 When create is refused because a model already binds that physical table, read the visible model named in the refusal and propose the needed update. Do not retry with another name or scope. If the response names no readable model, report the refusal without guessing or exposing a hidden target.
 
@@ -36,15 +36,15 @@ Constraints keep their five semantics: required predicate, forbidden column, req
 2. Preserve complete nested and metadata structures.
 3. Apply the smallest patch.
 4. Re-read immediately.
-5. Verify/unverify separately when intended.
+5. Read back the saved definition and confirm its intended scope.
 6. Inspect receipts; a degraded write may have landed and must not be retried blindly.
 
 When one task creates or changes several metrics or semantic models, send them as one `graphit kb batch` instead of one `kb create` or `kb update` each. Every item gets the same checks and its own result, and dashboards rebuild once for the whole batch instead of once per edit, so they keep serving while you author. A single edit stays `kb update`. Steps 1-2 still apply to every item; a batch changes the transport, not the patch discipline.
 
-- Shape: `{"operations": [...]}` or a bare array of `{"op": "update", "noun", "name", "patch"}` and `{"op": "create", "noun", "definition", "unverified"?}` items. Nouns are `metric` and `semantic-model` only; groups, rules and deletes keep their own verbs. Up to 50 items per batch, 20 in-app.
+- Shape: `{"operations": [...]}` or a bare array of `{"op": "update", "noun", "name", "patch"}` and `{"op": "create", "noun", "definition"}` items. Nouns are `metric` and `semantic-model` only; groups, rules and deletes keep their own verbs. Up to 50 items per batch, 20 in-app.
 - Order items so each validates against the ones before it: a semantic model before the metrics that use its measures, a metric before a derived metric over it. Use `--stop-on-error` when later items depend on earlier ones.
 - Items are not all-or-nothing: earlier items stay applied when a later one fails. Read `results` per item, fix what each `error` names, and re-send only the `failed` and `not_attempted` items as a new batch. Never replay the whole batch. An `unknown` item may have landed; read it back with `kb get` before sending it again.
-- In-app, approving the batch verifies each updated item, as approving a single update does.
+- Each successful item is saved with the same validation and authorization as a single update.
 
 ## Delete
 

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

@@ -49,4 +49,4 @@ Use `{{ Metric('revenue') }}`, `{{ Dimension('order__channel') }}`, and `{{ Meas
 
 ## Gap decision
 
-Research first, then recommend. Show which existing definitions or dashboards already cover the request, what can be reused or extended, and what is still missing. Propose authoring only for that agreed gap, with formula, grain, binding, group, rule impact and verification. Ask when a choice is unresolved; do not treat a request to investigate as permission to build.
+Research first, then recommend. Show which existing definitions or dashboards already cover the request, what can be reused or extended, and what is still missing. Propose authoring only for that agreed gap, with formula, grain, binding, group, rule impact and validation. Ask when a choice is unresolved; do not treat a request to investigate as permission to build.

package/skills/graphit/references/metric-families.md

@@ -10,7 +10,7 @@ Each member carries:
 - `meta.graphit.family`
 - axis key/value pairs in `meta.graphit.axes`
 
-Create each concrete member with the family and repeatable axis options. Tree/search/family views collapse members; `list metric` remains flat.
+Create each concrete member with the family and repeatable axis options. For several members, send one `graphit kb batch` (kb-actions.md) whose definitions carry the same metadata: `"meta": {"graphit": {"family": "arppu", "axes": {"horizon": "d7"}}}`. Tree/search/family views collapse members; `list metric` remains flat.
 
 Use family expansion to inspect members. Supply known axes to resolve. If several candidates remain, show open axes and ask—never guess a governed metric.
 

package/skills/graphit/references/onboarding.md

@@ -56,7 +56,7 @@ Shape it for the question - grain, only the columns dashboards use, low cardinal
 
 ## 4. Create the KB assets
 
-The scan supplies the bound model. Explore answers without authoring definitions; Private first Build uses it and keeps a private metric only on request. Share applies the readiness gate: show missing prerequisites and proposed definitions, obtain required approval, then create and verify via kb-structure.md and kb-actions.md. Onboarding does not override the selected workflow.
+The scan supplies the bound model. Explore answers without authoring definitions; Private first Build uses it and keeps a private metric only on request. Share applies the readiness gate: show missing prerequisites and proposed definitions, obtain required approval, then save and read back via kb-structure.md and kb-actions.md. Onboarding does not override the selected workflow.
 
 ## 5. Offer a dashboard
 

package/skills/graphit/references/page-load.md

@@ -0,0 +1,38 @@
+# Page Load: Request Graph and Readiness
+
+Load when a dashboard sends more than six requests on open (charts, option lists, bounds) or has a query feeding another (a rank feeding a series, bounds feeding a date window); when its open or Apply time is slow or measured; or when declaring readiness. `runtime.md` still owns the resolve API, the entity contract and the rate budget.
+
+Every `graphit.resolve()` and chrome call (`cascade`, `dataBounds`, `rank`) pays a fixed server cost of up to about a second, and the SDK sends at most six at once, in call order. Load time is roughly that cost times the rounds a page waits through, so shape the request graph before tuning SQL.
+
+## The request graph
+
+- **Parallel unless the rows are needed.** Start independent queries together in one `Promise.all`. Await one query before another only when the later query's SQL or params use the earlier result. A chain of awaits whose later steps ignore earlier results turns one round into many.
+- **Fold a dependency when you can.** A rank that only picks the top N for a series is usually one statement: rank in a CTE and join the series to it. Keep two steps when the first result is also shown.
+- **Visible first.** Start above-the-fold charts and KPIs before option lists, bounds for secondary controls and anything below the fold; later calls wait behind earlier ones.
+- **Hidden tabs wait** until first shown (`runtime.md`, "Declare statically, execute lazily").
+- **One first load.** `graphit.state.subscribe` calls back immediately: guard the callback with a boot flag and call `refresh()` once when init ends (`state-contract.md`, "Restore order"). An unguarded callback plus a boot refresh runs every query twice.
+- **Redraw, don't re-resolve.** Resize, highlight, legend, axis and zero-axis toggles change drawing only: keep the last result and redraw from it. Resolve again only when a filter, param or variant changes the query.
+
+## Declaring readiness
+
+Declare what "loaded" means so the page reports its open and Apply time. Readiness never delays drawing, and a missed acknowledgement only records a timeout after two minutes. Misuse does throw, so build `targets` from the same ids you pass tokens for.
+
+1. At the start of the open and of each Apply, call `graphit.readiness.begin(kind, targets)`: `kind` is `'initial'` or `'apply'`, `targets` the `data-graphit-id`s this load paints (1-128, unique). A hidden tab's entities are not targets until it opens. Each Apply supersedes the open and the previous Apply. `begin` throws on another kind or a bad list, and `ready.target(id)` on an id missing from `targets`.
+2. Pass `readiness: ready.target(id)` to each `graphit.resolve`, `dataBounds` or `rank` call for that target and to its `graphit.graph`, `table` or `kpi` render, which acknowledges the paint itself. After drawing custom DOM or options, call `ready.target(id).rendered()`. A `bind` keeps the token it was registered with, so it reports only that first load; give Apply targets through `resolve`.
+3. Call `ready.stateReady()` once the filters and params this load uses are applied, and `ready.fail()` if the load fails.
+
+```js
+function load(kind) {
+  const ready = graphit.readiness.begin(kind, ['spend-trend', 'spend-kpi']);
+  ready.stateReady(); // this page applies its state before load()
+  return Promise.all([
+    graphit.resolve({ target: '#spend-trend', readiness: ready.target('spend-trend') })
+      .then(r => graphit.graph('#spend-trend-chart', { type: 'line', data: r.data, x: 'day', y: 'spend',
+        readiness: ready.target('spend-trend') })),
+    graphit.resolve({ target: '#spend-kpi', readiness: ready.target('spend-kpi') })
+      .then(r => graphit.kpi('#spend-kpi-card', { value: r.data[0]?.spend ?? 0, readiness: ready.target('spend-kpi') })),
+  ]).catch(() => ready.fail());
+}
+```
+
+Redraw-only toggles begin nothing. Never run a query just to measure readiness.

package/skills/graphit/references/runtime.md

@@ -140,11 +140,11 @@ A resolve query following these shapes serves from a semantic cache in roughly 1
 
 `graphit.resolve()` is rate-limited per user per dashboard: 360 requests a minute, 180 of them cold executions (a cache hit is not one). Design for that budget:
 
-- **Single refresh function.** Put all queries in ONE `Promise.all` inside one `refresh()` so they share a time window. NEVER scatter `graphit.resolve()` across independent event handlers or timeouts - that turns one user action into several bursts.
-- **Count queries per interaction.** 6 charts is 6 cold executions per filter change, about 30 changes a minute of budget; 12 charts is about 15. With 10 or more charts and 3 or more filters, debounce filter changes (300ms).
-- **Reuse trend data for KPIs.** If you already fetch a weekly time series, derive the KPI total and its sparkline from that result in JS instead of a separate aggregate query. Anchor the extra graphs it feeds with `targetEntityIds` per the attribution rule above. Canonical KPI-row example: `kpi.md`.
-- **Avoid redundant refreshes.** If a filter affects only some charts, split into targeted refresh functions (`refreshKPIs()`, `refreshCharts()`).
-- **No polling.** NEVER use `setInterval(refresh, ...)`. Data sources update on their own schedule; a polling dashboard burns the entire budget.
+- **Single refresh function.** Put all queries in ONE `Promise.all` inside one `refresh()` so they share a time window. NEVER scatter `graphit.resolve()` across independent handlers or timeouts - one user action becomes several bursts.
+- **Count queries per interaction.** 6 charts cost 6 cold executions per filter change, about 30 changes a minute; 12 charts, about 15. With 10 or more charts and 3 or more filters, debounce filter changes (300ms).
+- **Reuse trend data for KPIs.** If you already fetch a weekly time series, derive the KPI total and its sparkline from that result in JS, not a separate aggregate query. Anchor the extra graphs it feeds with `targetEntityIds` per the attribution rule above. Canonical KPI-row example: `kpi.md`.
+- **Avoid redundant refreshes.** If a filter affects only some charts, split into targeted refresh functions (`refreshKPIs()`, `refreshCharts()`). Resize, highlight and axis toggles only redraw; no resolve (`page-load.md`).
+- **No polling.** NEVER use `setInterval(refresh, ...)`. Data sources refresh on their own schedule; polling burns the whole budget.
 
 ## Helper index
 

package/skills/graphit/references/semantic-authoring.md

@@ -22,7 +22,7 @@ Graphit extensions and assets:
 - topics are curated Graphit metadata, deliberately not dbt `tags`
 - rules are separate Graphit objects targeting semantic identities by name;
   never embed them in dbt metadata
-- verification attribution, provenance, and data-source bindings are
+- provenance and data-source bindings are
   server-owned; use dedicated actions instead of hand-authoring them
 
 Do not expose or depend on storage collection names, revision fields, feature
@@ -76,7 +76,7 @@ Measure identity is group/model/measure, never a bare name. A metric's measure r
 
 Explore authors no definitions. Private first Build creates a metric only on "keep": use the scanner model's exact private group (`kb-scope.md`), with no group-agreement or shared-reuse approval round. The comparisons below still apply. In Share, follow `kb-discovery.md`: agree the group, inspect assets/cross-group matches and present reuse-or-build. Before missing inputs, discover visible candidates in the target group/model. Summaries only nominate candidates; follow continuation metadata before declaring a gap. Ranked search or an incomplete page is not proof of absence.
 
-Read each plausible metric's full definition and its reached semantic models. Compare the resolved model/source binding, grain and time dimension, measure expression and aggregation parameters, metric-level and per-input filters, units/scale, verification state, ownership, and applicable rules. Similar names or identical SQL alone are insufficient. Use the existing path resolution above; never inspect hidden definitions or copy a private definition into a shared scope to make it reusable.
+Read each plausible metric's full definition and its reached semantic models. Compare the resolved model/source binding, grain and time dimension, measure expression and aggregation parameters, metric-level and per-input filters, units/scale, ownership, and applicable rules. Similar names or identical SQL alone are insufficient. Use the existing path resolution above; never inspect hidden definitions or copy a private definition into a shared scope to make it reusable.
 
 | Finding | Action |
 |---|---|
@@ -85,13 +85,13 @@ Read each plausible metric's full definition and its reached semantic models. Co
 | Different grain, filters, scale, binding or applicable policy | Keep the definitions separate; ask if the intended business meaning is unclear |
 | Repository-owned definition needs a change | Follow the repository authoring workflow; do not create a direct-write replacement to bypass ownership |
 
-A ratio still references numerator/denominator metric objects. For example, a verified total-matches metric can serve several ratios at the same grain; a country-filtered matches metric is not an interchangeable denominator for all countries. Being referenced or ending in `_num`/`_den` does not make an existing metric disposable.
+A ratio still references numerator/denominator metric objects. For example, a saved total-matches metric can serve several ratios at the same grain; a country-filtered matches metric is not an interchangeable denominator for all countries. Being referenced or ending in `_num`/`_den` does not make an existing metric disposable.
 
-After discovery, author only the approved missing prerequisites: group, data sources, semantic models with nested components, simple metrics, ratio/derived metrics, then rules after their targets exist. Execute one item at a time; do not start the next before the current receipt is terminal.
+After discovery, author only the approved missing prerequisites: group, data sources, semantic models with nested components, simple metrics, ratio/derived metrics, then rules after their targets exist. Execute in that order: metrics and semantic models as one ordered `graphit kb batch` (kb-actions.md); start any other item only after the current receipt is terminal.
 
 ## Verification
 
-Create defaults to verified on human-driven CLI paths; `--unverified` creates a draft. Promote or demote with dedicated verify/unverify actions. Never replace `meta` only to toggle verification.
+Valid authorized saves are effective within their access scope. Manual KB verification and draft status are retired; omit `unverified`, `verified`, `verified_by`, and `verified_at`. Source readiness, schema acceptance and SQL validation still apply.
 
 ## Final check