@overscore/cli 0.6.0 → 0.7.0

package/dist/index.js

@@ -295,7 +295,7 @@ async function queryList() {
     if (data.queries.length === 0) {
         console.log("  No queries registered yet.\n");
         console.log("  Add one with:");
-        console.log('    npx overscore query add <name> "SELECT ..."\n');
+        console.log('    npx @overscore/cli query add <name> "SELECT ..."\n');
         return;
     }
     for (const q of data.queries) {
@@ -311,7 +311,7 @@ async function queryList() {
 }
 async function queryShow(name) {
     if (!name) {
-        console.error("\n  Usage: npx overscore query show <name>\n");
+        console.error("\n  Usage: npx @overscore/cli query show <name>\n");
         process.exit(1);
     }
     const { dashboardSlug } = loadEnv();
@@ -356,9 +356,9 @@ function resolveSql(sqlOrNext) {
 async function queryAdd(name, sql) {
     const resolvedSql = resolveSql(sql);
     if (!name || !resolvedSql) {
-        console.error('\n  Usage: npx overscore query add <name> "<sql>"\n');
+        console.error('\n  Usage: npx @overscore/cli query add <name> "<sql>"\n');
         console.error("  Or with a file:");
-        console.error("    npx overscore query add <name> --file query.sql\n");
+        console.error("    npx @overscore/cli query add <name> --file query.sql\n");
         process.exit(1);
     }
     if (!/^[a-z][a-z0-9_]*$/.test(name) || name.length > 100) {
@@ -374,9 +374,9 @@ async function queryAdd(name, sql) {
 async function queryUpdate(name, sql) {
     const resolvedSql = resolveSql(sql);
     if (!name || !resolvedSql) {
-        console.error('\n  Usage: npx overscore query update <name> "<sql>"\n');
+        console.error('\n  Usage: npx @overscore/cli query update <name> "<sql>"\n');
         console.error("  Or with a file:");
-        console.error("    npx overscore query update <name> --file query.sql\n");
+        console.error("    npx @overscore/cli query update <name> --file query.sql\n");
         process.exit(1);
     }
     const { dashboardSlug } = loadEnv();
@@ -386,7 +386,7 @@ async function queryUpdate(name, sql) {
 }
 async function queryRemove(name) {
     if (!name) {
-        console.error("\n  Usage: npx overscore query remove <name>\n");
+        console.error("\n  Usage: npx @overscore/cli query remove <name>\n");
         process.exit(1);
     }
     const yes = await confirm(`Delete query "${name}"? This cannot be undone.`);
@@ -400,9 +400,9 @@ async function queryRemove(name) {
 }
 async function queryTest(sql) {
     if (!sql) {
-        console.error('\n  Usage: npx overscore query test "<sql>"\n');
+        console.error('\n  Usage: npx @overscore/cli query test "<sql>"\n');
         console.error("  Example:");
-        console.error('    npx overscore query test "SELECT * FROM dataset.table LIMIT 10"\n');
+        console.error('    npx @overscore/cli query test "SELECT * FROM dataset.table LIMIT 10"\n');
         process.exit(1);
     }
     const { dashboardSlug } = loadEnv();
@@ -449,9 +449,9 @@ function formatCell(value) {
 }
 async function pull(slug) {
     if (!slug) {
-        console.error("\n  Usage: npx overscore pull <dashboard-slug> [--version N]\n");
+        console.error("\n  Usage: npx @overscore/cli pull <dashboard-slug> [--version N]\n");
         console.error("  Example:");
-        console.error("    npx overscore pull my-dashboard\n");
+        console.error("    npx @overscore/cli pull my-dashboard\n");
         process.exit(1);
     }
     // Parse --version flag
@@ -558,7 +558,7 @@ VITE_OVERSCORE_API_URL=https://overscore.dev/api
 
   When ready to deploy:
 
-    npx overscore deploy --message "your changes"
+    npx @overscore/cli deploy --message "your changes"
 `);
 }
 async function versions() {
@@ -583,7 +583,7 @@ async function versions() {
         const by = v.deployed_by ? `  by ${v.deployed_by}` : "";
         console.log(`  v${v.version_number}  ${date}  ${v.file_count} files  ${size}  ${source}${msg}${by}`);
     }
-    console.log(`\n  Pull a version: npx overscore pull ${dashboardSlug} --version N\n`);
+    console.log(`\n  Pull a version: npx @overscore/cli pull ${dashboardSlug} --version N\n`);
 }
 async function listDashboards() {
     const { apiUrl, apiKey } = loadEnv();
@@ -629,6 +629,458 @@ function collectFiles(dir, prefix) {
     }
     return files;
 }
+// ── Analysis commands ──────────────────────────────────────────────
+const HUB_URL = "https://overscore.dev";
+function slugify(input) {
+    return input
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 80);
+}
+/**
+ * Resolve API config for analysis commands.
+ *
+ * Priority:
+ *   1. Local .env in cwd (e.g. running from inside an existing dashboard project)
+ *   2. ~/.overscore/config (set by install-skills or a previous analysis new run)
+ *   3. Interactive prompt (asks for API key, project slug)
+ *
+ * Analysis commands work from anywhere — they don't require being inside a project folder.
+ */
+async function loadAnalysisConfig() {
+    // (1) Local .env
+    const envPath = path.resolve(process.cwd(), ".env");
+    if (fs.existsSync(envPath)) {
+        const env = parseEnv(fs.readFileSync(envPath, "utf-8"));
+        const apiUrl = env.VITE_OVERSCORE_API_URL;
+        const apiKey = env.VITE_OVERSCORE_API_KEY;
+        const projectSlug = env.VITE_OVERSCORE_PROJECT_SLUG;
+        if (apiUrl && apiKey && projectSlug) {
+            return { apiUrl, apiKey, projectSlug };
+        }
+    }
+    // (2) ~/.overscore/config
+    const configDir = path.join(process.env.HOME || "", ".overscore");
+    const configPath = path.join(configDir, "config");
+    if (fs.existsSync(configPath)) {
+        const cfg = parseEnv(fs.readFileSync(configPath, "utf-8"));
+        if (cfg.OVERSCORE_API_KEY && cfg.OVERSCORE_PROJECT_SLUG) {
+            return {
+                apiUrl: cfg.OVERSCORE_API_URL || `${HUB_URL}/api`,
+                apiKey: cfg.OVERSCORE_API_KEY,
+                projectSlug: cfg.OVERSCORE_PROJECT_SLUG,
+            };
+        }
+    }
+    // (3) Interactive
+    console.log("\n  No Overscore config found. Let's set one up.\n");
+    const apiKey = await prompt("API key (from the Hub):");
+    if (!apiKey || !apiKey.startsWith("os_")) {
+        console.error("\n  Error: API key should start with os_\n");
+        process.exit(1);
+    }
+    const projectSlug = await prompt("Project slug:");
+    if (!projectSlug) {
+        console.error("\n  Error: Project slug is required\n");
+        process.exit(1);
+    }
+    // Save for next time
+    fs.mkdirSync(configDir, { recursive: true });
+    fs.writeFileSync(configPath, `OVERSCORE_API_URL=${HUB_URL}/api\nOVERSCORE_API_KEY=${apiKey}\nOVERSCORE_PROJECT_SLUG=${projectSlug}\n`, { mode: 0o600 });
+    console.log(`\n  Saved to ~/.overscore/config\n`);
+    return { apiUrl: `${HUB_URL}/api`, apiKey, projectSlug };
+}
+async function analysisApiRequest(cfg, method, urlPath, body) {
+    const baseUrl = cfg.apiUrl.replace(/\/api$/, "");
+    const url = `${baseUrl}${urlPath}`;
+    const headers = {
+        Authorization: `Bearer ${cfg.apiKey}`,
+    };
+    if (body !== undefined)
+        headers["Content-Type"] = "application/json";
+    const res = await fetch(url, {
+        method,
+        headers,
+        body: body !== undefined ? JSON.stringify(body) : undefined,
+    });
+    const data = await res.json();
+    if (!res.ok) {
+        console.error(`\n  Error: ${data.error || `HTTP ${res.status}`}\n`);
+        process.exit(1);
+    }
+    return data;
+}
+const ANALYSIS_CLAUDE_MD = `# Overscore Analysis: {{TITLE}}
+
+This is an **Overscore Analysis** — a one-off, frozen investigation. Analyses are NOT dashboards:
+
+- **No React project, no \`package.json\`, no \`useQuery\` hook.**
+- **No scheduled refreshes.** Numbers are hard-coded into \`report.html\` at publish time.
+- The deliverable is a single self-contained HTML file that anyone can open in a browser.
+- Analyses are meant to be shared (Slack, email) and reopened later for refresh-and-republish.
+
+## CRITICAL: Always maintain analysis-log.md
+
+\`analysis-log.md\` is the **recoverable session state** for this analysis. As you work, you MUST append to it. Future sessions (including yourself, weeks from now, after the user runs \`analysis pull\`) read this file to know:
+
+- What question the analysis is investigating
+- Which BigQuery tables are involved
+- Every SQL query you ran (paste the exact SQL)
+- Conclusions reached and how you got there
+- Open questions still being chased
+
+Use this rough structure:
+
+\`\`\`markdown
+## YYYY-MM-DD — Initial exploration
+
+**Question:** <the user's question>
+
+### Tables involved
+- \`dataset.table_name\` — what it contains, key columns
+
+### Queries run
+1. <one-line description of what this query investigated>
+   \`\`\`sql
+   SELECT ...
+   \`\`\`
+
+### Conclusions
+- ...
+
+### Open questions
+- ...
+\`\`\`
+
+Update it **as you go**, not at the end. Treat every meaningful exploration step as a new entry.
+
+## Where data context lives
+
+\`.claude/rules/company-context.md\` was pulled from this analysis's parent project at scaffold time. It contains the project's table definitions, business logic, and data quirks shared across all dashboards and analyses in this project. **Read it first** before exploring blindly.
+
+## Generating report.html
+
+When the user is happy with the work, generate \`report.html\` as a **fully self-contained** static HTML file:
+
+- Inline all CSS (no external stylesheets, no Tailwind CDN at runtime).
+- Hard-code the actual numbers and chart data into the HTML — **no \`fetch()\`, no API calls, no external scripts that depend on data being available at view time.**
+- Charts: inline SVG, or embedded base64 PNG, or a self-contained chart library bundled inline. Recharts/D3 from CDN is OK only if the data is already baked into the page.
+- Dark theme to match Overscore's brand: near-black background (\`#0a0a0f\`), white text, violet/blue/emerald accents, generous spacing.
+- Title at top, executive summary, KPI cards, charts, supporting tables, conclusions.
+- Footer with the date the analysis was generated.
+
+The HTML is what gets shared in Slack and what stakeholders see. The numbers must be visible to anyone who opens the file, with no logins, no JS data fetching, no broken external dependencies.
+
+## Publishing
+
+When the analysis is ready, **tell the user to run** (do not run it yourself without asking):
+
+\`\`\`bash
+npx @overscore/cli analysis publish
+\`\`\`
+
+This uploads \`report.html\` and the entire bundle (this CLAUDE.md, \`analysis-log.md\`, etc.) to Overscore. The analysis becomes available at \`https://<project>.overscore.dev/analysis/{{SLUG}}\`. Re-publishing overwrites the previous version.
+
+## When the user wants to turn this into a dashboard
+
+Analyses are static. They have **no React project**, **no scheduled refreshes**, and **no \`useQuery\`**. If the user asks to "make this a real dashboard" or "turn this into something that updates," **do NOT add React code to this folder.** Instead:
+
+1. Tell them: "Analyses are frozen snapshots. To make this a tracked dashboard, we need to scaffold a new project — the analysis stays as the original investigation."
+2. Tell them to run, from the parent directory:
+   \`\`\`bash
+   cd .. && npx create-overscore
+   \`\`\`
+   Use the same project slug this analysis belongs to (found in \`.overscore/analysis.json\`).
+3. Once they're in the new dashboard folder, hand off a seed message that includes: this analysis's question, the tables explored (from \`analysis-log.md\`), the key queries that mattered, and the conclusions reached. The new dashboard's Claude session can use this as a starting point.
+
+## Do NOT
+
+- Add \`package.json\`, \`node_modules\`, or any React/Vite scaffolding to this folder.
+- Use \`useQuery()\` or any Overscore client hooks — they don't exist here.
+- Call BigQuery from inside \`report.html\` at view time. Bake the numbers in.
+- Publish without showing the user \`report.html\` in a browser first and getting their approval.
+- Forget to update \`analysis-log.md\` as you work.
+`;
+async function analysisNew(title) {
+    if (!title) {
+        console.error('\n  Usage: npx @overscore/cli analysis new "<title>"\n');
+        process.exit(1);
+    }
+    const cfg = await loadAnalysisConfig();
+    console.log(`\n  Creating analysis: "${title}"\n`);
+    const data = (await analysisApiRequest(cfg, "POST", "/api/analyses", {
+        title,
+    }));
+    // Scaffold the local folder
+    const folderName = data.slug;
+    const targetDir = path.resolve(process.cwd(), folderName);
+    if (fs.existsSync(targetDir)) {
+        console.error(`\n  Error: Directory "${folderName}" already exists.\n`);
+        process.exit(1);
+    }
+    fs.mkdirSync(targetDir, { recursive: true });
+    fs.mkdirSync(path.join(targetDir, ".claude", "rules"), { recursive: true });
+    fs.mkdirSync(path.join(targetDir, ".overscore"), { recursive: true });
+    // Write analysis.json metadata
+    fs.writeFileSync(path.join(targetDir, ".overscore", "analysis.json"), JSON.stringify({
+        id: data.id,
+        slug: data.slug,
+        title: data.title,
+        project_slug: data.project_slug,
+        created_at: new Date().toISOString(),
+    }, null, 2));
+    // Write CLAUDE.md from template
+    const claudeMd = ANALYSIS_CLAUDE_MD
+        .replace(/\{\{TITLE\}\}/g, data.title)
+        .replace(/\{\{SLUG\}\}/g, data.slug);
+    fs.writeFileSync(path.join(targetDir, ".claude", "CLAUDE.md"), claudeMd);
+    // Empty analysis log seeded with the question
+    const today = new Date().toISOString().slice(0, 10);
+    const analysisLog = `# ${data.title}
+
+## ${today} — Initial exploration
+
+**Question:** ${data.title}
+
+### Tables involved
+- _(populate as you explore — see \`.claude/rules/company-context.md\` for what's available)_
+
+### Queries run
+- _(append every meaningful query here, with one-line description + SQL)_
+
+### Conclusions
+- _(empty so far)_
+
+### Open questions
+- _(empty so far)_
+`;
+    fs.writeFileSync(path.join(targetDir, "analysis-log.md"), analysisLog);
+    // Empty report.html stub
+    fs.writeFileSync(path.join(targetDir, "report.html"), `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<title>${data.title}</title>
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<style>
+  body { background: #0a0a0f; color: #fff; font-family: -apple-system, BlinkMacSystemFont, sans-serif; padding: 4rem 2rem; max-width: 800px; margin: 0 auto; }
+  h1 { font-weight: 600; }
+  p { color: rgba(255,255,255,0.6); }
+</style>
+</head>
+<body>
+  <h1>${data.title}</h1>
+  <p>This analysis is empty. Have Claude do the work and regenerate this file.</p>
+</body>
+</html>
+`);
+    // Pull project's company-context.md (best-effort, non-fatal)
+    try {
+        const baseUrl = cfg.apiUrl.replace(/\/api$/, "");
+        const ctxRes = await fetch(`${baseUrl}/api/projects/${data.project_slug}/context`, { headers: { Authorization: `Bearer ${cfg.apiKey}` } });
+        if (ctxRes.ok) {
+            const ctxData = (await ctxRes.json());
+            if (ctxData.context_md) {
+                fs.writeFileSync(path.join(targetDir, ".claude", "rules", "company-context.md"), ctxData.context_md);
+            }
+        }
+    }
+    catch {
+        // Non-fatal
+    }
+    console.log(`  Analysis created: ${data.title}
+  Slug:    ${data.slug}
+  Project: ${data.project_slug}
+  Folder:  ./${folderName}/
+
+  Next steps:
+
+    cd ${folderName}
+    code .
+    claude
+
+  Then ask Claude to do the analysis. When the report.html looks good:
+
+    npx @overscore/cli analysis publish
+
+  The analysis will go live at:
+    https://${data.project_slug}.overscore.dev/analysis/${data.slug}
+`);
+}
+function loadAnalysisMetadata() {
+    const metaPath = path.resolve(process.cwd(), ".overscore", "analysis.json");
+    if (!fs.existsSync(metaPath)) {
+        console.error("\n  Error: Not in an analysis folder. Run 'npx @overscore/cli analysis new \"<title>\"' first.\n");
+        process.exit(1);
+    }
+    return JSON.parse(fs.readFileSync(metaPath, "utf-8"));
+}
+const ANALYSIS_PUBLISH_EXCLUDE = new Set([
+    "node_modules",
+    ".git",
+    ".DS_Store",
+    ".env",
+]);
+function collectAnalysisFiles(dir, prefix) {
+    const files = [];
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        if (ANALYSIS_PUBLISH_EXCLUDE.has(entry.name))
+            continue;
+        if (entry.name.startsWith(".env"))
+            continue;
+        const relativePath = prefix ? `${prefix}/${entry.name}` : entry.name;
+        if (entry.isDirectory()) {
+            files.push(...collectAnalysisFiles(path.join(dir, entry.name), relativePath));
+        }
+        else {
+            files.push(relativePath);
+        }
+    }
+    return files;
+}
+async function analysisPublish() {
+    const meta = loadAnalysisMetadata();
+    const cfg = await loadAnalysisConfig();
+    const reportPath = path.resolve(process.cwd(), "report.html");
+    if (!fs.existsSync(reportPath)) {
+        console.error("\n  Error: report.html not found in this folder. Generate it before publishing.\n");
+        process.exit(1);
+    }
+    console.log(`\n  Publishing analysis: ${meta.title}\n`);
+    const files = collectAnalysisFiles(process.cwd(), "");
+    console.log(`  Bundling ${files.length} files...`);
+    const formData = new FormData();
+    formData.append("analysis_slug", meta.slug);
+    for (const file of files) {
+        const filePath = path.join(process.cwd(), file);
+        const content = fs.readFileSync(filePath);
+        const blob = new Blob([content]);
+        formData.append(`file:${file}`, blob, file);
+    }
+    console.log("  Uploading...");
+    const baseUrl = cfg.apiUrl.replace(/\/api$/, "");
+    const res = await fetch(`${baseUrl}/api/analyses/publish`, {
+        method: "POST",
+        headers: { Authorization: `Bearer ${cfg.apiKey}` },
+        body: formData,
+    });
+    const data = (await res.json());
+    if (!res.ok) {
+        console.error(`\n  Publish failed: ${data.error}\n`);
+        process.exit(1);
+    }
+    console.log(`
+  Published successfully!
+
+  ${data.file_count} files uploaded
+  URL: ${data.url}
+`);
+}
+async function analysisPull(slug) {
+    if (!slug) {
+        console.error("\n  Usage: npx @overscore/cli analysis pull <slug>\n");
+        process.exit(1);
+    }
+    const cfg = await loadAnalysisConfig();
+    console.log(`\n  Pulling analysis: ${slug}...`);
+    const baseUrl = cfg.apiUrl.replace(/\/api$/, "");
+    const res = await fetch(`${baseUrl}/api/analyses/${slug}/source`, {
+        headers: { Authorization: `Bearer ${cfg.apiKey}` },
+    });
+    if (!res.ok) {
+        let errorMsg = `HTTP ${res.status}`;
+        try {
+            const body = await res.json();
+            errorMsg = body.error || errorMsg;
+        }
+        catch {
+            // not JSON
+        }
+        console.error(`\n  Error: ${errorMsg}\n`);
+        process.exit(1);
+    }
+    const analysisSlug = res.headers.get("X-OS-Analysis-Slug") || slug;
+    const analysisTitle = res.headers.get("X-OS-Analysis-Title") || slug;
+    const projectSlug = res.headers.get("X-OS-Project-Slug") || cfg.projectSlug;
+    const zipBuffer = Buffer.from(await res.arrayBuffer());
+    const targetDir = path.resolve(process.cwd(), analysisSlug);
+    if (fs.existsSync(targetDir)) {
+        const yes = await confirm(`Directory "${analysisSlug}" already exists. Overwrite?`);
+        if (!yes) {
+            console.log("  Cancelled.\n");
+            return;
+        }
+        fs.rmSync(targetDir, { recursive: true, force: true });
+    }
+    fs.mkdirSync(targetDir, { recursive: true });
+    await extractZip(zipBuffer, targetDir);
+    // Make sure analysis.json reflects the current project (in case the user
+    // pulled into a different machine where their default project is different)
+    const metaPath = path.join(targetDir, ".overscore", "analysis.json");
+    if (fs.existsSync(metaPath)) {
+        try {
+            const meta = JSON.parse(fs.readFileSync(metaPath, "utf-8"));
+            meta.project_slug = projectSlug;
+            meta.slug = analysisSlug;
+            fs.writeFileSync(metaPath, JSON.stringify(meta, null, 2));
+        }
+        catch {
+            // Non-fatal
+        }
+    }
+    console.log(`
+  Pulled "${analysisTitle}"
+
+  Next steps:
+
+    cd ${analysisSlug}
+    code .
+    claude
+
+  Claude will read .claude/CLAUDE.md and analysis-log.md to know what was done.
+
+  When you're ready to republish:
+
+    npx @overscore/cli analysis publish
+`);
+}
+// ── install-skills ──────────────────────────────────────────────────
+async function installSkills() {
+    // Skills ship with the npm package at <pkg-root>/skills/
+    // __dirname after build is dist/, so the skills dir is one level up.
+    const distDir = path.dirname(new URL(import.meta.url).pathname);
+    const pkgRoot = path.resolve(distDir, "..");
+    const skillsSrc = path.join(pkgRoot, "skills");
+    if (!fs.existsSync(skillsSrc)) {
+        console.error(`\n  Error: Bundled skills directory not found at ${skillsSrc}\n`);
+        process.exit(1);
+    }
+    const homeSkills = path.join(process.env.HOME || "", ".claude", "skills");
+    fs.mkdirSync(homeSkills, { recursive: true });
+    const installed = [];
+    for (const entry of fs.readdirSync(skillsSrc, { withFileTypes: true })) {
+        if (!entry.isDirectory())
+            continue;
+        const srcDir = path.join(skillsSrc, entry.name);
+        const destDir = path.join(homeSkills, entry.name);
+        fs.rmSync(destDir, { recursive: true, force: true });
+        fs.mkdirSync(destDir, { recursive: true });
+        for (const f of fs.readdirSync(srcDir)) {
+            fs.copyFileSync(path.join(srcDir, f), path.join(destDir, f));
+        }
+        installed.push(entry.name);
+    }
+    console.log(`
+  Installed ${installed.length} skill${installed.length === 1 ? "" : "s"} into ~/.claude/skills/:
+${installed.map((s) => `    - ${s}`).join("\n")}
+
+  Claude Code will auto-detect and use these skills in any session,
+  including when you switch between Overscore dashboards and analyses.
+
+  Re-run this command anytime to update.
+`);
+}
 // ── Routing ─────────────────────────────────────────────────────────
 const command = process.argv[2];
 const subcommand = process.argv[3];
@@ -644,6 +1096,35 @@ else if (command === "versions") {
 else if (command === "list") {
     listDashboards();
 }
+else if (command === "install-skills") {
+    installSkills();
+}
+else if (command === "analysis") {
+    if (subcommand === "new") {
+        analysisNew(process.argv[4]);
+    }
+    else if (subcommand === "publish") {
+        analysisPublish();
+    }
+    else if (subcommand === "pull") {
+        analysisPull(process.argv[4]);
+    }
+    else {
+        console.log(`
+  overscore analysis — Manage Overscore Analyses (frozen investigations)
+
+  Commands:
+    new "<title>"     Create a new analysis in the current directory
+    publish           Upload report.html + bundle from the current analysis folder
+    pull <slug>       Re-download an existing analysis bundle to continue working
+
+  Examples:
+    npx @overscore/cli analysis new "Why did Q1 churn spike"
+    npx @overscore/cli analysis publish
+    npx @overscore/cli analysis pull why-did-q1-churn-spike
+`);
+    }
+}
 else if (command === "query") {
     if (subcommand === "list") {
         queryList();
@@ -676,12 +1157,12 @@ else if (command === "query") {
     test "<sql>"             Test SQL without saving
 
   Examples:
-    npx overscore query list
-    npx overscore query show monthly_revenue
-    npx overscore query add monthly_revenue --file queries/revenue.sql
-    npx overscore query add monthly_revenue "SELECT ..."
-    npx overscore query update monthly_revenue --file queries/revenue.sql
-    npx overscore query test "SELECT * FROM dataset.table LIMIT 10"
+    npx @overscore/cli query list
+    npx @overscore/cli query show monthly_revenue
+    npx @overscore/cli query add monthly_revenue --file queries/revenue.sql
+    npx @overscore/cli query add monthly_revenue "SELECT ..."
+    npx @overscore/cli query update monthly_revenue --file queries/revenue.sql
+    npx @overscore/cli query test "SELECT * FROM dataset.table LIMIT 10"
 `);
     }
 }
@@ -694,18 +1175,24 @@ else {
     deploy              Build and deploy the dashboard
     pull <slug>         Pull source code from the hub
     versions            List deploy history
-    query <subcommand>  Manage dashboard queries
+    query <subcommand>     Manage dashboard queries
+    analysis <subcommand>  Manage analyses (frozen investigations)
+    install-skills         Install the Overscore skill library into ~/.claude/skills/
 
   Usage:
-    npx overscore list
-    npx overscore deploy --message "description"
-    npx overscore pull <slug>
-    npx overscore pull <slug> --version 3
-    npx overscore versions
-    npx overscore query list
-    npx overscore query add <name> "<sql>"
-    npx overscore query update <name> "<sql>"
-    npx overscore query remove <name>
-    npx overscore query test "<sql>"
+    npx @overscore/cli list
+    npx @overscore/cli deploy --message "description"
+    npx @overscore/cli pull <slug>
+    npx @overscore/cli pull <slug> --version 3
+    npx @overscore/cli versions
+    npx @overscore/cli query list
+    npx @overscore/cli query add <name> "<sql>"
+    npx @overscore/cli query update <name> "<sql>"
+    npx @overscore/cli query remove <name>
+    npx @overscore/cli query test "<sql>"
+    npx @overscore/cli analysis new "<title>"
+    npx @overscore/cli analysis publish
+    npx @overscore/cli analysis pull <slug>
+    npx @overscore/cli install-skills
 `);
 }

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@overscore/cli",
-  "version": "0.6.0",
-  "description": "CLI for deploying Overscore dashboards",
+  "version": "0.7.0",
+  "description": "CLI for deploying Overscore dashboards and publishing analyses",
   "bin": {
     "overscore": "dist/index.js"
   },
   "files": [
-    "dist"
+    "dist",
+    "skills"
   ],
   "scripts": {
     "build": "tsc"

package/skills/scaffold-overscore-artifact/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: scaffold-overscore-artifact
+description: Use when the user wants to create a new Overscore dashboard or analysis, or when they're inside one artifact type and want to switch to the other (e.g. "turn this analysis into a dashboard", "do a quick analysis on this dashboard's data", "I want to investigate why X happened", "I want to track X over time"). Follow this procedure to scaffold the new artifact in the correct location with the correct command and seed it with context from the current artifact.
+---
+
+# Scaffolding Overscore Artifacts
+
+Overscore has two artifact types. They are **parallel**, not a funnel. Knowing which one to use is the most important decision the user makes.
+
+## Dashboards vs. Analyses — the one-line difference
+
+- **Dashboard** — a question you ask **forever**. Live React project, registered queries, scheduled cache refresh, deployed to a subdomain. Use when the user wants to *track* something over time.
+- **Analysis** — a question you ask **once**. Static HTML report with numbers baked in, no React, no refreshes. Use when the user wants to *investigate* something specific and share the answer.
+
+| If the user says... | Use |
+|---|---|
+| "I want to track X over time" | Dashboard |
+| "I want to investigate why X happened" | Analysis |
+| "I need this to refresh on a schedule" | Dashboard |
+| "I want a one-page write-up to share in Slack" | Analysis |
+| "I want a recurring view of our metrics" | Dashboard |
+| "I want to do a one-off cohort analysis" | Analysis |
+
+## Analysis → Dashboard
+
+If the user is inside an **analysis folder** (look for `.overscore/analysis.json`) and says something like "let's turn this into a real dashboard" or "make this update automatically":
+
+**Do NOT** add React code, `package.json`, or any Vite scaffolding to the analysis folder. Analyses are static and that would corrupt the artifact.
+
+Instead:
+
+1. Tell the user: "Analyses are frozen snapshots — to make this a tracked dashboard, we need to scaffold a new project. The analysis stays as the original investigation."
+2. Read `.overscore/analysis.json` to find the parent project slug.
+3. Tell them to run, from the parent directory:
+   ```bash
+   cd .. && npx create-overscore
+   ```
+   And use the same project slug (from `.overscore/analysis.json`) when prompted.
+4. Once the new dashboard folder exists, prepare a seed message for the new dashboard's first Claude session that includes:
+   - The analysis's question (from `analysis-log.md`)
+   - The tables involved (from `analysis-log.md` → "Tables involved" section)
+   - The key queries that mattered (from `analysis-log.md` → "Queries run")
+   - The conclusions reached
+5. Tell the user to paste this seed into Claude when they `cd` into the new dashboard.
+
+The analysis remains intact as the original investigation. Don't delete it.
+
+## Dashboard → Analysis
+
+If the user is inside a **dashboard folder** (look for `package.json` with `@overscore/client` dependency, or `.env` with `VITE_OVERSCORE_DASHBOARD_SLUG`) and says something like "I just want to do a quick one-off investigation" or "a write-up that won't be part of this dashboard":
+
+**Do NOT** add throwaway components, ad-hoc routes, or unused queries to the dashboard. That pollutes a production artifact.
+
+Instead:
+
+1. Tell the user: "That sounds like an Analysis — a one-off investigation that won't pollute this dashboard."
+2. Tell them to run, from the parent directory:
+   ```bash
+   cd .. && npx @overscore/cli analysis new "<title of the investigation>"
+   ```
+3. The new analysis folder will be a sibling of the dashboard, in the same project. The analysis's CLAUDE.md takes over from there.
+
+## Cold start (neither folder exists)
+
+If the user is in a fresh terminal with no Overscore artifact present and says something like "I want to investigate X" or "I want to build a dashboard for Y":
+
+1. Match their intent against the table above.
+2. If it's an **analysis**: have them run `npx @overscore/cli analysis new "<title>"` (they'll be prompted for project + API key on first use).
+3. If it's a **dashboard**: have them run `npx create-overscore` and follow the prompts.
+4. Both commands scaffold a folder with a CLAUDE.md primer that takes over immediately.
+
+## Never confuse the two
+
+An analysis folder has: `.overscore/analysis.json`, `analysis-log.md`, `report.html`, no `node_modules`.
+
+A dashboard folder has: `package.json`, `node_modules`, `src/`, `vite.config.ts`, `.env` with `VITE_OVERSCORE_DASHBOARD_SLUG`.
+
+If you see one shape and the user asks for behavior that belongs to the other shape, **always** route them to the correct command rather than wedging the wrong shape into the current folder.