@graphit/cli 0.1.4 → 0.1.6

package/dist/commands/setup.js

@@ -0,0 +1,173 @@
+import { existsSync, readdirSync } from "node:fs";
+import { readFile, writeFile, mkdir, copyFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join, dirname } from "node:path";
+import { execFileSync } from "node:child_process";
+import { readCredentials } from "../auth/credentials.js";
+function resolveSkillDir() {
+    const fromDist = join(dirname(new URL(import.meta.url).pathname), "..", "..", "skills", "graphit");
+    if (existsSync(join(fromDist, "SKILL.md")))
+        return fromDist;
+    return join(dirname(dirname(dirname(import.meta.url.replace("file://", "")))), "skills", "graphit");
+}
+function detectEditors() {
+    const editors = [];
+    if (existsSync(".claude") || commandExists("claude"))
+        editors.push("claude-code");
+    if (existsSync(".cursor"))
+        editors.push("cursor");
+    if (existsSync(".codex") || commandExists("codex"))
+        editors.push("codex");
+    if (existsSync(".vscode"))
+        editors.push("vscode");
+    return editors;
+}
+function commandExists(cmd) {
+    try {
+        execFileSync("which", [cmd], { stdio: "ignore" });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function getInstallTargets(editors, project, skillMd, cursorMdc) {
+    const targets = [];
+    const home = homedir();
+    for (const editor of editors) {
+        switch (editor) {
+            case "claude-code": {
+                const base = project
+                    ? join(".claude", "skills", "graphit")
+                    : join(home, ".claude", "skills", "graphit");
+                targets.push({
+                    editor,
+                    path: join(base, "SKILL.md"),
+                    content: skillMd,
+                    refsDir: join(base, "references"),
+                });
+                break;
+            }
+            case "codex": {
+                const base = project
+                    ? join(".codex", "skills", "graphit")
+                    : join(home, ".codex", "skills", "graphit");
+                targets.push({
+                    editor,
+                    path: join(base, "SKILL.md"),
+                    content: skillMd,
+                    refsDir: join(base, "references"),
+                });
+                break;
+            }
+            case "cursor":
+                targets.push({
+                    editor,
+                    path: project
+                        ? join(".cursor", "rules", "graphit.mdc")
+                        : join(home, ".cursor", "rules", "graphit.mdc"),
+                    content: cursorMdc,
+                });
+                break;
+            case "vscode":
+                if (project) {
+                    targets.push({ editor, path: "AGENTS.md", content: skillMd });
+                }
+                break;
+        }
+    }
+    return targets;
+}
+async function installReferences(sourceRefsDir, targetRefsDir, update) {
+    if (!existsSync(sourceRefsDir))
+        return [];
+    const files = readdirSync(sourceRefsDir).filter((f) => f.endsWith(".md"));
+    if (files.length === 0)
+        return [];
+    await mkdir(targetRefsDir, { recursive: true });
+    const written = [];
+    for (const file of files) {
+        const targetPath = join(targetRefsDir, file);
+        if (existsSync(targetPath) && !update)
+            continue;
+        if (existsSync(targetPath) && update) {
+            await copyFile(targetPath, `${targetPath}.bak`);
+        }
+        const content = await readFile(join(sourceRefsDir, file), "utf-8");
+        await writeFile(targetPath, content, "utf-8");
+        written.push(targetPath);
+    }
+    return written;
+}
+export function registerSetupCommand(program) {
+    program
+        .command("setup")
+        .description("Install Graphit skill for your AI coding assistant")
+        .option("--editor <name>", "Override editor detection (claude-code, cursor, codex, vscode)")
+        .option("--project", "Install at project level (in repo, committable)")
+        .option("--update", "Overwrite existing skill files")
+        .option("--dry-run", "Show what would be installed without writing")
+        .action(async function () {
+        const opts = this.opts();
+        const creds = await readCredentials();
+        if (!creds) {
+            console.log("Warning: Not logged in. Run `graphit auth login` first for full functionality.\n");
+        }
+        let editors;
+        if (opts.editor) {
+            editors = [opts.editor];
+        }
+        else {
+            editors = detectEditors();
+            if (editors.length === 0) {
+                console.error(JSON.stringify({
+                    error: "No supported editor detected. Use --editor to specify one.",
+                }));
+                process.exit(1);
+            }
+        }
+        const skillDir = resolveSkillDir();
+        const skillMd = await readFile(join(skillDir, "SKILL.md"), "utf-8");
+        const cursorMdc = await readFile(join(skillDir, "graphit.mdc"), "utf-8");
+        const sourceRefsDir = join(skillDir, "references");
+        const targets = getInstallTargets(editors, !!opts.project, skillMd, cursorMdc);
+        if (targets.length === 0) {
+            console.error(JSON.stringify({ error: "No install targets found." }));
+            process.exit(1);
+        }
+        if (opts.dryRun) {
+            console.log("Dry run - would install:\n");
+            for (const t of targets) {
+                console.log(`  ${t.editor}: ${t.path}`);
+                if (t.refsDir && existsSync(sourceRefsDir)) {
+                    const refs = readdirSync(sourceRefsDir).filter((f) => f.endsWith(".md"));
+                    refs.forEach((r) => console.log(`  ${t.editor}: ${join(t.refsDir, r)}`));
+                }
+            }
+            return;
+        }
+        for (const target of targets) {
+            if (existsSync(target.path) && !opts.update) {
+                console.log(`Skill file already exists at ${target.path}. Use --update to overwrite.`);
+                continue;
+            }
+            if (existsSync(target.path) && opts.update) {
+                await copyFile(target.path, `${target.path}.bak`);
+            }
+            await mkdir(dirname(target.path), { recursive: true });
+            await writeFile(target.path, target.content, "utf-8");
+            console.log(`Written: ${target.path}`);
+            if (target.refsDir) {
+                const refFiles = await installReferences(sourceRefsDir, target.refsDir, !!opts.update);
+                if (refFiles.length > 0) {
+                    console.log(`Written: ${refFiles.length} reference files to ${target.refsDir}/`);
+                }
+            }
+        }
+        const mode = opts.project ? "project" : "global";
+        const editorNames = editors.join(", ");
+        console.log(`\nGraphit skill installed for ${editorNames} (${mode}).`);
+        console.log('\nTry: "Explore the Graphit KB and build a revenue dashboard"');
+    });
+}
+//# sourceMappingURL=setup.js.map

package/dist/commands/setup.js.map

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

package/dist/config.d.ts

@@ -0,0 +1,4 @@
+export declare const DEFAULT_API_BASE_URL = "https://api.graphit-app.com";
+export declare const DEFAULT_FRONTEND_URL = "https://graphit-app.com";
+export declare function getApiBaseUrl(): string;
+export declare function getFrontendUrl(): string;

package/dist/config.js

@@ -0,0 +1,9 @@
+export const DEFAULT_API_BASE_URL = "https://api.graphit-app.com";
+export const DEFAULT_FRONTEND_URL = "https://graphit-app.com";
+export function getApiBaseUrl() {
+    return process.env.GRAPHIT_API_URL || DEFAULT_API_BASE_URL;
+}
+export function getFrontendUrl() {
+    return process.env.GRAPHIT_FRONTEND_URL || DEFAULT_FRONTEND_URL;
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,oBAAoB,GAAG,6BAA6B,CAAC;AAClE,MAAM,CAAC,MAAM,oBAAoB,GAAG,yBAAyB,CAAC;AAE9D,MAAM,UAAU,aAAa;IAC3B,OAAO,OAAO,CAAC,GAAG,CAAC,eAAe,IAAI,oBAAoB,CAAC;AAC7D,CAAC;AAED,MAAM,UAAU,cAAc;IAC5B,OAAO,OAAO,CAAC,GAAG,CAAC,oBAAoB,IAAI,oBAAoB,CAAC;AAClE,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { registerAuthCommands } from "./commands/auth.js";
+import { registerKBCommands } from "./commands/kb.js";
+import { registerQueryCommands } from "./commands/query.js";
+import { registerDSCommands } from "./commands/ds.js";
+import { registerDashboardCommands } from "./commands/dashboard.js";
+import { registerConnectorCommands } from "./commands/connector.js";
+import { registerSetupCommand } from "./commands/setup.js";
+import { getCurrentVersion, printUpdateBanner, fireBackgroundCheck, } from "./update-check.js";
+const program = new Command();
+program
+    .name("graphit")
+    .description("Graphit CLI - Build custom dashboards from any AI coding assistant")
+    .version(getCurrentVersion())
+    .option("--output <format>", "Output format: json (default) or table", "json");
+registerAuthCommands(program);
+registerKBCommands(program);
+registerQueryCommands(program);
+registerDSCommands(program);
+registerDashboardCommands(program);
+registerConnectorCommands(program);
+registerSetupCommand(program);
+printUpdateBanner();
+program.parse();
+fireBackgroundCheck();
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,yBAAyB,EAAE,MAAM,yBAAyB,CAAC;AACpE,OAAO,EAAE,yBAAyB,EAAE,MAAM,yBAAyB,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EACL,iBAAiB,EACjB,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,mBAAmB,CAAC;AAE3B,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;AAE9B,OAAO;KACJ,IAAI,CAAC,SAAS,CAAC;KACf,WAAW,CAAC,oEAAoE,CAAC;KACjF,OAAO,CAAC,iBAAiB,EAAE,CAAC;KAC5B,MAAM,CAAC,mBAAmB,EAAE,wCAAwC,EAAE,MAAM,CAAC,CAAC;AAEjF,oBAAoB,CAAC,OAAO,CAAC,CAAC;AAC9B,kBAAkB,CAAC,OAAO,CAAC,CAAC;AAC5B,qBAAqB,CAAC,OAAO,CAAC,CAAC;AAC/B,kBAAkB,CAAC,OAAO,CAAC,CAAC;AAC5B,yBAAyB,CAAC,OAAO,CAAC,CAAC;AACnC,yBAAyB,CAAC,OAAO,CAAC,CAAC;AACnC,oBAAoB,CAAC,OAAO,CAAC,CAAC;AAE9B,iBAAiB,EAAE,CAAC;AACpB,OAAO,CAAC,KAAK,EAAE,CAAC;AAChB,mBAAmB,EAAE,CAAC"}

package/dist/output/format.d.ts

@@ -0,0 +1,8 @@
+import { Command } from "commander";
+export type OutputFormat = "json" | "table";
+export declare function getOutputFormat(cmd: Command): OutputFormat;
+export declare function output(cmd: Command, data: unknown, opts?: {
+    columns?: string[];
+    keyValue?: boolean;
+}): void;
+export declare function errorOutput(err: unknown): void;

package/dist/output/format.js

@@ -0,0 +1,30 @@
+import { formatJson } from "./json.js";
+import { formatTable, formatKeyValue } from "./table.js";
+export function getOutputFormat(cmd) {
+    const root = cmd.parent ?? cmd;
+    const format = root.opts().output;
+    return format === "table" ? "table" : "json";
+}
+export function output(cmd, data, opts) {
+    const format = getOutputFormat(cmd);
+    if (format === "json") {
+        console.log(formatJson(data));
+        return;
+    }
+    if (opts?.keyValue && !Array.isArray(data)) {
+        console.log(formatKeyValue(data));
+        return;
+    }
+    const rows = Array.isArray(data) ? data : [data];
+    console.log(formatTable(rows, opts?.columns));
+}
+export function errorOutput(err) {
+    const message = err instanceof Error
+        ? err.message
+        : typeof err === "object" && err !== null && "detail" in err
+            ? err.detail
+            : String(err);
+    console.error(JSON.stringify({ error: message }));
+    process.exit(1);
+}
+//# sourceMappingURL=format.js.map

package/dist/output/format.js.map

@@ -0,0 +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;AAIzD,MAAM,UAAU,eAAe,CAAC,GAAY;IAC1C,MAAM,IAAI,GAAG,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC;IAC/B,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC,MAAgB,CAAC;IAC5C,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,MAAM,UAAU,WAAW,CAAC,GAAY;IACtC,MAAM,OAAO,GACX,GAAG,YAAY,KAAK;QAClB,CAAC,CAAC,GAAG,CAAC,OAAO;QACb,CAAC,CAAC,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,IAAI,QAAQ,IAAI,GAAG;YAC1D,CAAC,CAAE,GAA0B,CAAC,MAAM;YACpC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAEpB,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"}

package/dist/output/json.d.ts

@@ -0,0 +1 @@
+export declare function formatJson(data: unknown): string;

package/dist/output/json.js

@@ -0,0 +1,4 @@
+export function formatJson(data) {
+    return JSON.stringify(data, null, 2);
+}
+//# sourceMappingURL=json.js.map

package/dist/output/json.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json.js","sourceRoot":"","sources":["../../src/output/json.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,UAAU,CAAC,IAAa;IACtC,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;AACvC,CAAC"}

package/dist/output/table.d.ts

@@ -0,0 +1,2 @@
+export declare function formatTable(rows: Record<string, unknown>[], columns?: string[]): string;
+export declare function formatKeyValue(data: Record<string, unknown>): string;

package/dist/output/table.js

@@ -0,0 +1,17 @@
+export function formatTable(rows, columns) {
+    if (rows.length === 0)
+        return "(no results)";
+    const cols = columns || Object.keys(rows[0]);
+    const widths = cols.map((col) => Math.max(col.length, ...rows.map((r) => String(r[col] ?? "").length)));
+    const header = cols.map((col, i) => col.padEnd(widths[i])).join("  ");
+    const separator = widths.map((w) => "-".repeat(w)).join("  ");
+    const body = rows.map((row) => cols.map((col, i) => String(row[col] ?? "").padEnd(widths[i])).join("  "));
+    return [header, separator, ...body].join("\n");
+}
+export function formatKeyValue(data) {
+    const maxKeyLen = Math.max(...Object.keys(data).map((k) => k.length));
+    return Object.entries(data)
+        .map(([k, v]) => `${k.padEnd(maxKeyLen)}  ${v}`)
+        .join("\n");
+}
+//# sourceMappingURL=table.js.map

package/dist/output/table.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"table.js","sourceRoot":"","sources":["../../src/output/table.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,WAAW,CACzB,IAA+B,EAC/B,OAAkB;IAElB,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,cAAc,CAAC;IAE7C,MAAM,IAAI,GAAG,OAAO,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;IAC7C,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAC9B,IAAI,CAAC,GAAG,CACN,GAAG,CAAC,MAAM,EACV,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAChD,CACF,CAAC;IAEF,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACtE,MAAM,SAAS,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC9D,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAC5B,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAC1E,CAAC;IAEF,OAAO,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACjD,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,IAA6B;IAC1D,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;IACtE,OAAO,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC;SACxB,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC;SAC/C,IAAI,CAAC,IAAI,CAAC,CAAC;AAChB,CAAC"}

package/dist/update-check.d.ts

@@ -0,0 +1,3 @@
+export declare function getCurrentVersion(): string;
+export declare function printUpdateBanner(): void;
+export declare function fireBackgroundCheck(): void;

package/dist/update-check.js

@@ -0,0 +1,78 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+import { createRequire } from "module";
+const require = createRequire(import.meta.url);
+const pkg = require("../package.json");
+const REGISTRY_URL = "https://registry.npmjs.org/@graphit/cli/latest";
+const CACHE_DIR = join(homedir(), ".graphit");
+const CACHE_FILE = join(CACHE_DIR, "update-check.json");
+const TTL_MS = 24 * 60 * 60 * 1000;
+function readCache() {
+    try {
+        if (!existsSync(CACHE_FILE))
+            return null;
+        const raw = readFileSync(CACHE_FILE, "utf-8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+function writeCache(entry) {
+    try {
+        if (!existsSync(CACHE_DIR))
+            mkdirSync(CACHE_DIR, { recursive: true });
+        writeFileSync(CACHE_FILE, JSON.stringify(entry));
+    }
+    catch {
+        // silent - cache write failure is not critical
+    }
+}
+function isNewer(latest, current) {
+    const l = latest.split(".").map(Number);
+    const c = current.split(".").map(Number);
+    for (let i = 0; i < 3; i++) {
+        if ((l[i] ?? 0) > (c[i] ?? 0))
+            return true;
+        if ((l[i] ?? 0) < (c[i] ?? 0))
+            return false;
+    }
+    return false;
+}
+export function getCurrentVersion() {
+    return pkg.version;
+}
+export function printUpdateBanner() {
+    const cache = readCache();
+    if (!cache)
+        return;
+    const current = getCurrentVersion();
+    if (!isNewer(cache.latestVersion, current))
+        return;
+    process.stderr.write(`\n  Update available: ${current} → ${cache.latestVersion}\n` +
+        `  Run \`npm update -g @graphit/cli\` to update\n\n`);
+}
+export function fireBackgroundCheck() {
+    const cache = readCache();
+    if (cache && Date.now() - cache.checkedAt < TTL_MS)
+        return;
+    fetch(REGISTRY_URL, { signal: AbortSignal.timeout(3000) })
+        .then((res) => {
+        if (!res.ok)
+            return;
+        return res.json();
+    })
+        .then((data) => {
+        if (data && typeof data === "object" && "version" in data) {
+            writeCache({
+                latestVersion: data.version,
+                checkedAt: Date.now(),
+            });
+        }
+    })
+        .catch(() => {
+        // silent - network failure is not critical
+    });
+}
+//# sourceMappingURL=update-check.js.map

package/dist/update-check.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@graphit/cli",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Graphit CLI - Build custom dashboards from any AI coding assistant",
   "type": "module",
   "bin": {

package/skills/graphit/SKILL.md

@@ -88,27 +88,97 @@ NEVER embed query results as static JS variables. The dashboard iframe provides
 
 ---
 
-## Workflow
+## Workflow: Dashboard Build
 
 1. **Ask the user** what dashboard they want. Don't start querying until you know what they need.
-2. **Explore KB** to understand available metrics, dimensions, tables, and rules.
+2. **Explore KB** - use `graphit kb list domains` then `graphit kb explore domain <NAME>` to traverse existing assets. Search by concept with `graphit kb search "revenue"`. See `kb-exploration.md` for KB-first discovery, `kb-traversal.md` for tool selection.
 3. **Find a data source** (`graphit ds list`) - prefer cached data sources (~100ms) over live warehouse (~10s).
 4. **Query data to validate** - run queries via the CLI to verify SQL and preview results. Show the user what you found.
 5. **Build HTML** - write `graphit.resolve()` calls for live data + `graphit.chart/table/kpi` for rendering. All CSS in `<style>`, all JS in `<script>`. Write to a local `.html` file.
 6. **Save** with `graphit dashboard update-html <id> --file <path>`.
 7. Give the user the dashboard URL so they can open it.
 
+## Workflow: KB Build / Onboarding
+
+When the user wants to build or populate their KB (from files, schema descriptions, or scratch). Consult `kb-graph-structure.md` for the full graph model, `kb-traversal.md` for tool selection, `kb-actions.md` for the CLI command matrix, `kb-awareness.md` for when to propose asset creation, and `parameterized-metrics.md` for template metrics.
+
+**Step 1: Audit current KB state.** Before proposing anything, traverse the existing KB:
+
+1. `graphit kb list domains` - get all domains (with asset counts)
+2. For each domain: `graphit kb explore domain <NAME>` - returns all tables and assets in that domain in one traversal (see `kb-traversal.md` depth guidelines)
+3. `graphit kb list synonyms` and `graphit kb list relationships` - global assets not scoped to domains
+
+Present a tree summary of what already exists, following the Domain > Table > Topic > Asset hierarchy from `kb-graph-structure.md`.
+
+**Step 2: Analyze input.** Read the user's files, schema, or description. Classify every concept by asset type. Use `kb-explanation.md` for asset type definitions (what is a metric vs dimension vs rule). Use `kb-awareness.md` for signals (aggregation = metric, derived grouping = dimension, business constraint = rule, colloquial term = synonym).
+
+**Step 3: Present a tree-structured plan.** Show what will be created, organized by the KB hierarchy. Mark existing assets with (exists) so the user sees what's new vs what's already there:
+
+```
+KB Plan:
+
+MARKETING (domain) (exists)
+  MARKETING_UA (table) (exists)
+    ACQUISITION (topic) (exists)
+      - TOTAL_SPEND (metric) = SUM(APPSFLYER_COST) **NEW**
+      - CPI (metric) (exists)
+      - MEDIA_SOURCE (dimension) (exists)
+      - CAMPAIGN_NAME (dimension) **NEW**
+    ATTRIBUTION (topic) **NEW**
+      - ROAS_D7 (metric) = SUM(revenue_d7) / NULLIF(SUM(cost), 0) **NEW**
+      - ATTRIBUTION_WINDOW (dimension) **NEW**
+    Rules:
+      - EXCLUDE_ORGANIC (rule) (exists)
+      - ACTIVE_CAMPAIGNS_ONLY (rule) = "WHERE status = 'active'" **NEW**
+  MARKETING_UA_6MO (table) (exists)
+    (reference TOTAL_SPEND, CPI from MARKETING_UA via secondary_tables)
+
+PRODUCT (domain) **NEW**
+  EVENTS (table) (exists)
+    RETENTION (topic) **NEW**
+      - DAU (metric) = COUNT(DISTINCT user_id) **NEW**
+      - RETENTION_D7 (metric) **NEW**
+
+Global:
+  - Synonyms: GMV -> TOTAL_REVENUE (metric) **NEW**
+  - Relationships: MARKETING_UA.USER_ID -> EVENTS.USER_ID **NEW**
+
+Summary: 5 new metrics, 2 new dimensions, 1 new rule, 1 new domain, 2 new topics, 1 synonym, 1 relationship
+```
+
+For metrics with natural variant axes (D7/D30/D90, gross/net), propose parameterized templates instead of standalone metrics (see `parameterized-metrics.md`).
+
+**Step 4: Wait for user approval.** Do not create anything until the user confirms the plan.
+
+**Step 5: Execute top-down.** Create in dependency order (see `kb-actions.md` for full CLI command reference):
+1. Domains (`graphit kb create domain --name X`)
+2. Topics (`graphit kb create topic --name X`)
+3. Metrics and dimensions (`graphit kb create metric/dimension ... --topics "A,B"`)
+4. Rules (`graphit kb create rule`)
+5. Synonyms (`graphit kb create synonym --term X --canonical Y --type metric`)
+6. Relationships (`graphit kb create relationship`)
+7. Attachments: assign domains to tables (`graphit kb update table X --domain Y`), add secondary_tables for cross-table references (`graphit kb update metric X --secondary-tables "T1,T2"`)
+
+**Step 6: Verify.** Re-traverse: `graphit kb explore domain <NAME>` for each domain. Show the user the final tree and confirm counts match the plan.
+
 ## Commands
 
 | Command | Description |
 |---------|-------------|
-| `graphit kb list <type>` | List metrics, dimensions, tables, rules, domains, synonyms, templates |
+| `graphit kb list <type>` | List entities: metric, dimension, table, rule, domain, synonym, template, relationship, topic |
 | `graphit kb get <type> <name>` | Full entity details by name |
-| `graphit kb search <query>` | Search across all KB types |
+| `graphit kb search <query>` | Search across all KB types (optional `--type` filter) |
 | `graphit kb explore metric <name>` | Metric -> tables -> dimensions graph |
-| `graphit kb create template --name X --file template.html --description "..."` | Save a reusable chart template (--file or --render-code) |
-| `graphit kb update template <name> --file template.html --description "..."` | Update a template (--file or --render-code) |
-| `graphit kb delete template <name> --yes` | Delete a template |
+| `graphit kb create metric --name X --sql "..." --table T` | Create a metric |
+| `graphit kb create dimension --name X --expr "..." --table T` | Create a dimension (optional `--type categorical`) |
+| `graphit kb create rule --name X --sql "..." --table T` | Create a rule |
+| `graphit kb create synonym --term X --canonical Y --type metric` | Create a synonym (type: metric, column, table) |
+| `graphit kb create domain --name X` | Create a domain (optional `--color "#hex"`) |
+| `graphit kb create relationship --name X --primary-table T --primary-column C --related-table T2 --related-column C2` | Create a JOIN relationship |
+| `graphit kb create topic --name X` | Create a topic (business-concept tag) |
+| `graphit kb create template --name X --file template.html` | Save a reusable chart template (--file or --render-code) |
+| `graphit kb update <type> <name> --field value` | Update any entity (fields vary by type) |
+| `graphit kb delete <type> <name> --yes` | Delete any entity (all types supported) |
 | `graphit ds list` | List cached data sources (use these for fast queries) |
 | `graphit query "<sql>" --ds <id>` | Query cached data source (~100ms) |
 | `graphit query "<sql>" --warehouse --connection <id>` | Query live Snowflake (~10s) |
@@ -230,7 +300,13 @@ Detailed knowledge lives in `references/`. Consult the relevant file when you ne
 |------|-------------|
 | `dashboard-planning.md` | Building a multi-chart dashboard. Covers framing the question, picking archetype, mandatory rules, metric contracts, anti-patterns. |
 | `chart-selection.md` | Choosing chart types. Full dimension/measure defaults, perception ranking, cardinality guards, hard caps. |
-| `kb-exploration.md` | Starting a build. KB-first discovery, metric vs dimension, naming conventions, reuse patterns, formula syntax. |
+| `kb-exploration.md` | Starting a build. KB-first discovery, metric vs dimension, naming conventions, formula syntax. |
+| `kb-awareness.md` | KB-first planning. When to propose KB asset creation, reuse over reinvention, cross-table referencing, topic assignment. |
+| `kb-graph-structure.md` | KB graph model. 9 node types, 5 edge types, multi-membership semantics, domain cascade, tree rendering order. |
+| `kb-explanation.md` | Structural Q&A. What are domains, topics, tables, relationships, memory. Why assets appear where they do. |
+| `kb-traversal.md` | Graph queries. Tool selection guide (search vs explore vs read), common query patterns, depth guidelines. |
+| `kb-actions.md` | Full CRUD matrix. Asset create/edit/delete, topic management, domain assignment cascade, navigation and discovery. |
+| `parameterized-metrics.md` | Metric templates. ${PARAM:NAME} tokens, child variant auto-generation, editing templates, using variants in queries. |
 | `sql-reference.md` | Writing queries. DuckDB/Snowflake translation, formatting standards, gap-filling, JSON access, data source routing. |
 | `domain-lenses.md` | Data matches a business domain. Marketing, finance, product/growth, ops, sales - signals, key metrics, must-have charts, anti-patterns. |
 | `graphit-style.md` | Building the HTML. Design principles, typography scale, color system with usage rules, layout patterns (page structure, KPI cards, data tables). |