@graphit/cli 0.1.36 → 0.1.39

package/scripts/plugin-status.mjs

@@ -0,0 +1,285 @@
+#!/usr/bin/env node
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const REGISTRY_URL = "https://registry.npmjs.org/@graphit/cli/latest";
+const TTL_MS = 24 * 60 * 60 * 1000;
+const args = new Set(process.argv.slice(2));
+const hookIndex = process.argv.indexOf("--hook");
+const hookEvent = hookIndex >= 0 ? process.argv[hookIndex + 1] : null;
+const pluginRoot =
+  process.env.CLAUDE_PLUGIN_ROOT ??
+  process.env.CODEX_PLUGIN_ROOT ??
+  process.env.GRAPHIT_PLUGIN_ROOT ??
+  dirname(dirname(fileURLToPath(import.meta.url)));
+const cacheRoot =
+  process.env.CLAUDE_PLUGIN_DATA ??
+  process.env.CODEX_PLUGIN_DATA ??
+  process.env.GRAPHIT_PLUGIN_DATA ??
+  join(homedir(), ".graphit");
+
+function readJson(path) {
+  return JSON.parse(readFileSync(path, "utf-8"));
+}
+
+function tryReadJson(path) {
+  try {
+    if (!existsSync(path)) return null;
+    return readJson(path);
+  } catch {
+    return null;
+  }
+}
+
+function readFrontmatterVersion(path) {
+  try {
+    const content = readFileSync(path, "utf-8");
+    return content.match(/^skill_version:\s*["']?([^"'\n]+)["']?\s*$/m)?.[1] ?? null;
+  } catch {
+    return null;
+  }
+}
+
+function compareVersions(left, right) {
+  const leftParts = left.split(".").map(Number);
+  const rightParts = right.split(".").map(Number);
+
+  for (let index = 0; index < 3; index += 1) {
+    const leftPart = leftParts[index] ?? 0;
+    const rightPart = rightParts[index] ?? 0;
+    if (leftPart > rightPart) return 1;
+    if (leftPart < rightPart) return -1;
+  }
+
+  return 0;
+}
+
+function copiedSkillTargets(home = homedir(), cwd = process.cwd()) {
+  return [
+    { kind: "claude-code", label: "Claude Code global", scope: "global", path: join(home, ".claude", "skills", "graphit", "SKILL.md") },
+    { kind: "codex", label: "Codex global", scope: "global", path: join(home, ".codex", "skills", "graphit", "SKILL.md") },
+    { kind: "cursor", label: "Cursor global", scope: "global", path: join(home, ".cursor", "rules", "graphit.mdc") },
+    { kind: "claude-code", label: "Claude Code project", scope: "project", path: join(cwd, ".claude", "skills", "graphit", "SKILL.md") },
+    { kind: "codex", label: "Codex project", scope: "project", path: join(cwd, ".codex", "skills", "graphit", "SKILL.md") },
+    { kind: "cursor", label: "Cursor project", scope: "project", path: join(cwd, ".cursor", "rules", "graphit.mdc") },
+  ];
+}
+
+function isPluginManagedKind(kind) {
+  return kind === "claude-code" || kind === "codex";
+}
+
+function readCopiedSkillVersion(path) {
+  if (!existsSync(path)) return null;
+  const versionJson = path.endsWith("SKILL.md")
+    ? tryReadJson(join(dirname(path), "VERSION.json"))
+    : null;
+  return versionJson?.version ?? readFrontmatterVersion(path);
+}
+
+function readCache(path) {
+  try {
+    if (!existsSync(path)) return null;
+    return readJson(path);
+  } catch {
+    return null;
+  }
+}
+
+function writeCache(path, entry) {
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(entry), "utf-8");
+  } catch {
+    // Cache writes should never break startup hooks.
+  }
+}
+
+async function getLatestVersion(currentVersion) {
+  if (args.has("--skip-network")) return null;
+
+  const cachePath = join(cacheRoot, "plugin-status.json");
+  const cache = readCache(cachePath);
+  if (cache?.latestVersion && Date.now() - cache.checkedAt < TTL_MS) {
+    return cache.latestVersion;
+  }
+
+  try {
+    const response = await fetch(REGISTRY_URL, { signal: AbortSignal.timeout(1500) });
+    if (!response.ok) return cache?.latestVersion ?? null;
+    const data = await response.json();
+    if (data && typeof data.version === "string") {
+      writeCache(cachePath, { latestVersion: data.version, checkedAt: Date.now() });
+      return data.version;
+    }
+  } catch {
+    return cache?.latestVersion ?? null;
+  }
+
+  return currentVersion;
+}
+
+function shouldRunForPrompt() {
+  if (hookEvent !== "UserPromptSubmit") return true;
+
+  let input = "";
+  try {
+    input = readFileSync(0, "utf-8");
+  } catch {
+    return false;
+  }
+
+  const parsed = tryParseJson(input);
+  const prompt = String(parsed?.prompt ?? parsed?.user_prompt ?? input).toLowerCase();
+  return (
+    prompt.includes("graphit") &&
+    /\b(update|version|status|doctor|plugin|stale|staleness)\b/.test(prompt)
+  );
+}
+
+function tryParseJson(value) {
+  try {
+    return JSON.parse(value);
+  } catch {
+    return null;
+  }
+}
+
+async function collectStatus() {
+  const packageJson = readJson(join(pluginRoot, "package.json"));
+  const currentVersion = packageJson.version;
+  const findings = [];
+  const metadata = [];
+  const claudePlugin = tryReadJson(join(pluginRoot, ".claude-plugin", "plugin.json"));
+  const codexPlugin = tryReadJson(join(pluginRoot, ".codex-plugin", "plugin.json"));
+  const marketplace = tryReadJson(join(pluginRoot, ".claude-plugin", "marketplace.json"));
+  const marketplacePlugin = marketplace?.plugins?.find((plugin) => plugin.name === "graphit");
+
+  const versionChecks = [
+    [".claude-plugin/plugin.json", claudePlugin?.version],
+    [".codex-plugin/plugin.json", codexPlugin?.version],
+    [".claude-plugin/marketplace.json metadata", marketplace?.metadata?.version],
+    [".claude-plugin/marketplace.json plugin", marketplacePlugin?.version],
+    ["skills/graphit/VERSION.json", tryReadJson(join(pluginRoot, "skills", "graphit", "VERSION.json"))?.version],
+    ["skills/graphit/SKILL.md", readFrontmatterVersion(join(pluginRoot, "skills", "graphit", "SKILL.md"))],
+    ["skills/graphit/graphit.mdc", readFrontmatterVersion(join(pluginRoot, "skills", "graphit", "graphit.mdc"))],
+  ];
+
+  for (const [label, version] of versionChecks) {
+    if (version !== currentVersion) {
+      findings.push({
+        type: "metadata-drift",
+        message: `${label} is ${version ?? "missing"}, expected ${currentVersion}`,
+        remediation: "Run `npm run sync:version` before publishing @graphit/cli.",
+      });
+    }
+    metadata.push({ label, version: version ?? null });
+  }
+
+  const marketplaceSource = marketplacePlugin?.source;
+  const sourceMatches =
+    marketplaceSource?.source === "npm" &&
+    marketplaceSource.package === packageJson.name &&
+    marketplaceSource.version === currentVersion;
+  metadata.push({
+    label: ".claude-plugin/marketplace.json source",
+    version: marketplaceSource?.version ?? null,
+    source: marketplaceSource ?? null,
+  });
+  if (!sourceMatches) {
+    findings.push({
+      type: "metadata-drift",
+      message: `.claude-plugin/marketplace.json source is ${
+        marketplaceSource ? JSON.stringify(marketplaceSource) : "missing"
+      }, expected npm source ${packageJson.name}@${currentVersion}`,
+      remediation: "Run `npm run sync:version` before publishing @graphit/cli.",
+    });
+  }
+
+  const latestVersion = await getLatestVersion(currentVersion);
+  if (latestVersion && compareVersions(latestVersion, currentVersion) > 0) {
+    findings.push({
+      type: "package-update",
+      message: `@graphit/cli update available: ${currentVersion} -> ${latestVersion}`,
+      remediation: "Update Graphit through your assistant's plugin manager. Claude Code users can run `claude plugin update graphit`; Codex plugin users should use the Codex plugin update command. Standalone npm users can run `npm update -g @graphit/cli`.",
+    });
+  }
+
+  for (const target of copiedSkillTargets()) {
+    const { label, path } = target;
+    if (!existsSync(path)) continue;
+    const version = readCopiedSkillVersion(path);
+    if (isPluginManagedKind(target.kind)) {
+      findings.push({
+        type: "legacy-copied-skill-present",
+        message: `${label} legacy copied skill exists at ${path} (${version ?? "unversioned"})`,
+        remediation: "Claude Code and Codex should use the Graphit plugin bundle. Remove legacy copied snapshots with `graphit setup --remove-legacy-copies` after confirming the plugin is installed.",
+      });
+      continue;
+    }
+
+    if (!version || compareVersions(version, currentVersion) < 0) {
+      findings.push({
+        type: "copied-skill-stale",
+        message: `${label} copied skill is ${version ?? "unversioned"}, expected ${currentVersion}`,
+        remediation: "Cursor currently uses copied rules; refresh them with `graphit setup --editor cursor --update`.",
+      });
+    }
+  }
+
+  return {
+    packageName: packageJson.name,
+    sourceOfTruth: "plugin-bundle",
+    currentVersion,
+    latestVersion,
+    metadata,
+    findings,
+  };
+}
+
+function formatPlain(status) {
+  if (status.findings.length === 0) {
+    return `Graphit plugin status OK (${status.currentVersion}).`;
+  }
+
+  return [
+    `Graphit plugin status needs attention (${status.currentVersion}):`,
+    ...status.findings.map((finding) => `- ${finding.message}\n  ${finding.remediation}`),
+  ].join("\n");
+}
+
+function formatHookContext(status) {
+  if (status.findings.length === 0) return null;
+
+  return [
+    "Graphit plugin status check found actionable update/version information.",
+    ...status.findings.map((finding) => `- ${finding.message}. ${finding.remediation}`),
+  ].join("\n");
+}
+
+if (hookEvent && !shouldRunForPrompt()) {
+  process.exit(0);
+}
+
+const status = await collectStatus();
+
+if (args.has("--json")) {
+  console.log(JSON.stringify(status, null, 2));
+} else if (hookEvent) {
+  const additionalContext = formatHookContext(status);
+  if (additionalContext) {
+    console.log(JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: hookEvent,
+        additionalContext,
+      },
+    }));
+  }
+} else if (!args.has("--quiet") || status.findings.length > 0) {
+  console.log(formatPlain(status));
+}
+
+process.exit(status.findings.length > 0 && args.has("--fail-on-findings") ? 1 : 0);

package/scripts/sync-plugin-version.mjs

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const CHECK_FLAG = "--check";
+const cliRoot =
+  process.env.GRAPHIT_CLI_ROOT ??
+  join(fileURLToPath(new URL(".", import.meta.url)), "..");
+const checkOnly = process.argv.includes(CHECK_FLAG);
+
+function readJson(path) {
+  return JSON.parse(readFileSync(path, "utf-8"));
+}
+
+function formatJson(value) {
+  return `${JSON.stringify(value, null, 2)}\n`;
+}
+
+function writeOrReport(path, nextContent, changes) {
+  const previous = existsSync(path) ? readFileSync(path, "utf-8") : "";
+  if (previous === nextContent) return;
+
+  changes.push(path);
+  if (!checkOnly) {
+    writeFileSync(path, nextContent, "utf-8");
+  }
+}
+
+function upsertFrontmatterField(content, field, value) {
+  if (!content.startsWith("---\n")) {
+    throw new Error(`Expected frontmatter in file with ${field}`);
+  }
+
+  const closeIndex = content.indexOf("\n---", 4);
+  if (closeIndex === -1) {
+    throw new Error(`Could not find closing frontmatter marker for ${field}`);
+  }
+
+  const frontmatter = content.slice(4, closeIndex);
+  const body = content.slice(closeIndex);
+  const line = `${field}: "${value}"`;
+  const pattern = new RegExp(`^${field}:.*$`, "m");
+
+  if (pattern.test(frontmatter)) {
+    return `---\n${frontmatter.replace(pattern, line)}${body}`;
+  }
+
+  return `---\n${line}\n${frontmatter}${body}`;
+}
+
+function updatePluginManifest(path, version, changes) {
+  const manifest = readJson(path);
+  manifest.version = version;
+  writeOrReport(path, formatJson(manifest), changes);
+}
+
+function updateMarketplace(path, version, packageName, changes) {
+  const marketplace = readJson(path);
+  marketplace.metadata = {
+    ...(marketplace.metadata ?? {}),
+    version,
+  };
+
+  for (const plugin of marketplace.plugins ?? []) {
+    if (plugin.name !== "graphit") continue;
+    plugin.version = version;
+    plugin.source = {
+      source: "npm",
+      package: packageName,
+      version,
+    };
+  }
+
+  writeOrReport(path, formatJson(marketplace), changes);
+}
+
+function updateVersionJson(path, packageName, version, changes) {
+  writeOrReport(
+    path,
+    formatJson({
+      package: packageName,
+      version,
+      source: "cli/package.json",
+    }),
+    changes,
+  );
+}
+
+function updateFrontmatterVersion(path, version, changes) {
+  const content = readFileSync(path, "utf-8");
+  writeOrReport(path, upsertFrontmatterField(content, "skill_version", version), changes);
+}
+
+const packageJson = readJson(join(cliRoot, "package.json"));
+const version = packageJson.version;
+const packageName = packageJson.name;
+const changes = [];
+
+updatePluginManifest(join(cliRoot, ".claude-plugin", "plugin.json"), version, changes);
+updatePluginManifest(join(cliRoot, ".codex-plugin", "plugin.json"), version, changes);
+updateMarketplace(join(cliRoot, ".claude-plugin", "marketplace.json"), version, packageName, changes);
+updateVersionJson(join(cliRoot, "skills", "graphit", "VERSION.json"), packageName, version, changes);
+updateFrontmatterVersion(join(cliRoot, "skills", "graphit", "SKILL.md"), version, changes);
+updateFrontmatterVersion(join(cliRoot, "skills", "graphit", "graphit.mdc"), version, changes);
+
+if (changes.length > 0) {
+  const rel = (path) => path.startsWith(`${cliRoot}/`) ? path.slice(cliRoot.length + 1) : path;
+  if (checkOnly) {
+    console.error(
+      `Plugin version metadata is out of sync with package.json ${version}:\n` +
+        changes.map((path) => `  - ${rel(path)}`).join("\n") +
+        "\nRun `npm run sync:version` in cli/.",
+    );
+    process.exit(1);
+  }
+
+  console.log(`Synced Graphit plugin metadata to ${version}:`);
+  for (const path of changes) {
+    console.log(`  - ${rel(path)}`);
+  }
+}

package/skills/graphit/SKILL.md

@@ -1,4 +1,5 @@
 ---
+skill_version: "0.1.39"
 name: graphit
 description: >
   Build HTML dashboards with Graphit. KB-aware queries, entity wrapping, cached data sources.
@@ -14,12 +15,20 @@ Build custom HTML dashboards from real data using the Graphit CLI.
 
 ## Session Start
 
-Run `graphit --version` at the start of every session to confirm the CLI is installed.
-If the output includes an "Update available" banner, tell the user to update before proceeding and explain that outdated versions may be missing commands or bug fixes.
+Run `graphit plugin status` at the start of every Graphit session and whenever the user asks about Graphit updates, plugin health, or stale instructions. This command is the source of truth for CLI, plugin-bundle, skill, ref, hook, and legacy copied-file version health; do not invent a manual version check.
+If it reports action needed, tell the user the exact remediation it prints before proceeding.
+If `graphit plugin status` fails with "command not found" or "unknown command", the CLI is too old. Tell the user to update immediately: `npm update -g @graphit/cli`. Do not proceed with an outdated CLI - commands and flags in this skill may not exist in old versions.
 
-## Error Recovery
+## Install / Update Model
 
-When any `graphit` command fails with an unexpected error (unknown command, unrecognized flag, non-zero exit with unclear message), suggest `npm update -g @graphit/cli` before investigating further. Outdated CLI versions are the most common cause of unexpected errors.
+The Graphit plugin bundle is the default and source of truth for Claude Code and Codex. It contains the CLI, skills, refs, hooks, status script, and manifests. Claude Code/Codex users should update Graphit through their assistant plugin manager, not by running copied-skill setup.
+
+`graphit setup` is only for legacy/fallback copied-file installs, mainly Cursor or environments without plugin support. If `graphit plugin status` reports Claude Code/Codex copied snapshots, tell the user to remove them with `graphit setup --remove-legacy-copies` after confirming the plugin is installed. Use `graphit setup --legacy-copy` only when the plugin path is unavailable.
+
+## CLI Health Gate
+
+ALWAYS run `graphit plugin status` before diagnosing, retrying, or inventing a workaround when Graphit CLI behavior looks wrong. This includes unknown commands, unrecognized flags, missing commands described in this skill, stale-looking output, copied-skill warnings, non-zero exits with unclear messages, or the user saying Graphit/CLI/plugin/skill is not working.
+If `graphit plugin status` reports action needed, stop and tell the user the exact remediation first. Do not continue with stale instructions unless the user explicitly asks you to proceed anyway.
 Do NOT suggest updating for normal operational failures (expired auth, bad SQL syntax, network timeout, entity not found).
 
 ## Permission Errors
@@ -32,9 +41,9 @@ The CLI enforces the same permission model as the platform. Three error codes to
 
 Connector create/delete are restricted to org admins (owner/admin role). Non-admin analysts get 403 on these commands.
 
-## After Setup
+## Legacy Setup
 
-After `graphit setup` completes successfully, offer to add a Graphit section to the project's CLAUDE.md (or AGENTS.md for Codex) so future sessions know Graphit is available without activating the skill. Suggested snippet:
+After an intentional legacy copied-file setup completes successfully, offer to add a Graphit section to the project instructions so future sessions know Graphit is available. Do not suggest legacy copied setup for Claude Code or Codex when the Graphit plugin is available. Suggested snippet:
 
 ```
 ## Graphit
@@ -114,6 +123,12 @@ NEVER embed query results as static JS variables. The dashboard iframe provides
 **Wrong:** Running queries at build time, embedding results as `const data = [{...}, ...]` in the HTML.
 **Right:** Using `graphit.resolve({sql, dataSourceId})` in a `<script>` block so data refreshes automatically.
 
+### 6. NEVER build a dashboard on ad-hoc SQL when KB assets are missing
+The KB-readiness gate in Workflow Step 4 is BLOCKING. When you check the KB and find it is missing metrics or dimensions the dashboard needs, you MUST create them before writing any HTML. Do not offer to skip. Do not ask "should I use ad-hoc SQL instead?" Do not frame it as the user's choice. The gate exists because ad-hoc SQL bypasses governance, breaks provenance, and produces untrustworthy graphs. The only question to ask is "here's my KB plan - approve?" not "should I follow my own instructions?"
+
+**Wrong:** "The KB has no metrics defined for caching performance. Should I build the dashboard with ad-hoc SQL or create KB assets first? Your call."
+**Right:** "The KB is missing 3 metrics this dashboard needs: RESULT_CACHE_HIT_RATE, DS_QUERY_LATENCY, QUERY_FAILURE_RATE. Creating them now - here's the plan: [tree]. Approve?"
+
 ---
 
 ## How to Work (governs both workflows below)
@@ -124,6 +139,11 @@ You are a colleague building WITH the user, not a batch job that explores in sil
 
 **Always narrate.** The user cannot see your command output: the KB you listed, the SQL you ran, the rows that came back are invisible unless you surface them. So after each step, say what you found, what it means, and what you are about to do next. The one exception: if the user says "just build it" or "go", drop the running commentary and work straight through. Match the user's mode.
 
+**Workflow gates are not optional.** When a step says BLOCKING or STOP, execute it. Do not offer to skip, do not say "your call", do not reframe it as optional. The KB-readiness gate (Step 4) is the most common one: if the KB is missing metrics or dimensions the dashboard needs, create them before writing HTML. The only question to ask is "here's my KB plan - approve?" not "should I follow the plan?"
+
+- **Wrong:** "The KB is empty. Should I skip KB creation and use ad-hoc SQL, or build assets first?"
+- **Right:** "The KB is empty. Here are the 7 metrics and 4 dimensions this dashboard needs: [tree]. Approve so I can create them?"
+
 The difference in practice:
 - **Weak (solo):** silently list the KB, silently run several queries, then save a complete dashboard and announce "Done - here's your dashboard."
 - **Strong (collaborative):** "Found a **Marketing UA** data source with `{{metric:CPI}}` and `{{metric:ROAS}}` already defined. Starting with a spend-vs-installs trend - querying now." Then, after showing the rows: "Spend tracks installs except in March. Want that as the first graph, or should I look at ROAS first?"
@@ -134,10 +154,12 @@ The numbered steps in each workflow run *inside* this loop, not instead of it.
 
 1. **Understand.** Ask what the dashboard should answer. Don't query until you know the goal - one clarifying question beats a wrong dashboard.
 2. **Scope to the domain, then work down: domain -> data source -> assets.** Start narrow, not broad. Ask the user which business domain this dashboard is about (or infer it and confirm) - that scopes everything that follows. Then `graphit kb explore domain <NAME>` to see that domain's data sources and the metrics and dimensions defined on them. Reach for broad `graphit kb search` only as a fallback - when the domain is unclear or a concept spans domains. See `kb-discovery.md` and `kb-traversal.md`. Then tell the user what you found - the data source, the metrics and dimensions you'll use (by name), and the graphs you plan - before building.
-3. **Pick the data source, and handle gaps.** Use the cached data source in that domain (~100ms, preferred over live warehouse at ~10s); use its name in SQL (`FROM MARKETING_UA_DS`). If that data source is missing something you need, first look for a connection to another data source you can join (`graphit kb list relationships`); only if the data genuinely does not exist yet, propose building a new data source rather than forcing a bad query.
-4. **Validate each query, and show the result.** Write SQL with `{{metric:NAME}}` / `{{dim:NAME}}` reference syntax for KB assets, run it with `--verbose`, and for EVERY query show the user a compact result: the reference-syntax query, a small markdown table of rows, the row count, and the trust tier. If a query returns zero rows or nulls, say so and diagnose (wrong table? filter too narrow?).
-5. **Get approval, then build.** Once the user is happy with the data and plan, assemble the HTML: `graphit.resolve()` for live data, `graphit.chart/table/kpi` for rendering, every entity wrapped (see HARD CONSTRAINTS), all CSS in `<style>`, all JS in `<script>`. For a large dashboard, add entities incrementally - build one, show it, add the next - rather than generating everything at once. Write to a local `.html` file.
-6. **Save - prefer entity updates - then hand off.** New dashboard: `graphit dashboard update-html <id> --file <path>`. Changing an existing one: prefer `graphit dashboard update-entity <id> <entity_id>`, which updates a single entity without regenerating (and destroying) the rest. If the response contains `entity_sql_warnings`, an entity's `data-graphit-sql` is missing, matches no data source, or fails the DS schema - fix the flagged entities and save again before reporting done. Confirm the save succeeded, then give the user the dashboard URL.
+3. **Understand the business question.** Before touching SQL, apply `domain-lenses.md` to classify the user's goal. Match column names and user intent against the five lens detection signals (Marketing, Finance, Product/Growth, Operational, Sales). Once the lens is identified: check its canonical metrics and clarification questions. Ask at most ONE clarifying question using collaborative phrasing - state your assumption and offer to redirect ("I'll compute ROAS as gross revenue over spend - redirect me if you need margin-adjusted"). Map the user's goal to specific metric and dimension concepts the dashboard needs - name them. Show the user: "This dashboard needs: ROAS_D7, CPI, LTV_CAC_RATIO (metrics) and MEDIA_SOURCE, CAMPAIGN_NAME (dimensions). Let me check if these exist in the KB." This concept list feeds the next step.
+4. **KB-readiness gate (BLOCKING).** Check the KB against the specific concepts from step 3 - not a vague "does the KB have stuff?" but "does the KB have the ROAS, CPI, and LTV:CAC that this marketing dashboard needs?" Show a compact gap table: which concepts exist in the KB (with their formula) and which are missing. If the KB covers the needed concepts, proceed to step 5. If the KB is missing key metrics or dimensions, STOP - do not build a dashboard on raw ad-hoc SQL. Tell the user what is missing, propose creating the assets, then route to the **KB Build / Onboarding** workflow below to define the semantic layer first. Return here only after the KB has the assets the dashboard needs. A dashboard built on ad-hoc SQL instead of `{{metric:NAME}}` / `{{dim:NAME}}` references bypasses governance, breaks provenance, and produces untrustworthy results.
+5. **Pick the data source, and handle gaps.** Use the cached data source in that domain (~100ms, preferred over live warehouse at ~10s); use its name in SQL (`FROM MARKETING_UA_DS`). If that data source is missing something you need, first look for a connection to another data source you can join (`graphit kb list relationships`); only if the data genuinely does not exist yet, propose building a new data source rather than forcing a bad query.
+6. **Validate each query, and show the result.** Write SQL with `{{metric:NAME}}` / `{{dim:NAME}}` reference syntax for KB assets, run it with `--verbose`, and for EVERY query show the user a compact result: the reference-syntax query, a small markdown table of rows, the row count, and the trust tier. If a query returns zero rows or nulls, say so and diagnose (wrong table? filter too narrow?).
+7. **Get approval, then build.** Once the user is happy with the data and plan, assemble the HTML: `graphit.resolve()` for live data, `graphit.chart/table/kpi` for rendering, every entity wrapped (see HARD CONSTRAINTS), all CSS in `<style>`, all JS in `<script>`. For a large dashboard, add entities incrementally - build one, show it, add the next - rather than generating everything at once. Write to a local `.html` file.
+8. **Save - prefer entity updates - then hand off.** New dashboard: `graphit dashboard update-html <id> --file <path>`. Changing an existing one: prefer `graphit dashboard update-entity <id> <entity_id>`, which updates a single entity without regenerating (and destroying) the rest. If the response contains `entity_sql_warnings`, an entity's `data-graphit-sql` is missing, matches no data source, or fails the DS schema - fix the flagged entities and save again before reporting done. Confirm the save succeeded, then give the user the dashboard URL.
 
 ## Workflow: KB Build / Onboarding
 
@@ -219,6 +241,7 @@ For bulk creation (10+ assets), use `--skip-validate` to avoid per-asset latency
 | `graphit kb get <type> <name>` | Full entity details by name |
 | `graphit kb search <query>` | Search across all KB types (optional `--type` filter) |
 | `graphit kb explore metric <name>` | Metric -> tables -> dimensions graph |
+| `graphit kb explore domain <name>` | Domain -> tables -> assets full tree (preferred starting point) |
 | `graphit kb create metric --name X --sql "..." --table T` | Create a metric (optional `--default-dimensions "D1,D2"`). Validates formula against real data before creation; blocks on failure (422). Use `--skip-validate` to bypass. |
 | `graphit kb create dimension --name X --expr "..." --table T` | Create a dimension (type auto-inferred from schema; override with `--type` / `--output-type`). Validates expression against real data; shows cardinality + NULL rate. Use `--skip-validate` to bypass. |
 | `graphit kb create rule --name X --sql "..." --table T` | Create a rule. Validates as WHERE clause against real data; warns if zero rows match. Use `--skip-validate` to bypass. |
@@ -232,6 +255,11 @@ For bulk creation (10+ assets), use `--skip-validate` to avoid per-asset latency
 | `graphit kb update metric NAME --secondary-tables "T1,T2"` | Reference metric onto additional tables (also dimension, rule) |
 | `graphit kb update metric NAME --parameters '<json>'` | Set parameterized metric template (JSON array, or `--parameters-file`) |
 | `graphit kb update table NAME --domain DOMAIN` | Assign domain to table (cascades to all assets on table) |
+| `graphit kb update domain NAME --color "#hex"` | Update domain color |
+| `graphit kb update synonym TERM --canonical Y` | Update synonym target |
+| `graphit kb update relationship NAME --primary-column C` | Update relationship columns |
+| `graphit kb update topic NAME --description "..."` | Update topic description |
+| `graphit kb update template NAME --file template.html` | Update template render code |
 | `graphit kb update <type> <name> --description "..."` | Update description (all types) |
 | `graphit kb delete <type> <name> --yes` | Delete any entity (all types supported) |
 | `graphit ds list` | List cached data sources (use these for fast queries) |
@@ -262,7 +290,17 @@ For bulk creation (10+ assets), use `--skip-validate` to avoid per-asset latency
 | `graphit team list` | List teams you belong to (org admins see all) |
 | `graphit dashboard export <id>` | Export dashboard as PNG (default) or PDF (`--format pdf`, `--output <path>`). Presentations export as multi-page PDF (one slide per page) automatically. For custom multi-page layouts, add `data-graphit-page="N"` (0-indexed) to each section element. |
 | `graphit metadata schemas --connection <id>` | List Snowflake schemas |
+| `graphit metadata tables --schema <name> --connection <id>` | List tables in a Snowflake schema |
 | `graphit connector list` | List active connections |
+| `graphit connector add snowflake-keypair --account X --user Y --key <path> --warehouse W` | Add Snowflake keypair connection (admin only). OAuth and GitHub connections are configured via the web app. |
+| `graphit connector test <id>` | Test a connection |
+| `graphit connector remove <id> --yes` | Remove a connection (admin only) |
+| `graphit auth login` | Authenticate with Graphit |
+| `graphit auth status` | Show current auth status |
+| `graphit auth logout` | Clear stored credentials |
+| `graphit plugin status` | Check plugin bundle, CLI, skill, refs, hooks, copied legacy files, and update health |
+| `graphit setup` | Legacy copied-file fallback for Cursor/non-plugin environments |
+| `graphit setup --remove-legacy-copies` | Remove old Claude Code/Codex copied snapshots so the plugin bundle is source of truth |
 
 ## Presenting Results to the User
 

package/skills/graphit/VERSION.json

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