@overscore/cli 0.6.1 → 0.8.0

package/dist/index.js

@@ -629,6 +629,394 @@ 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;
+}
+/**
+ * Recursively copies a template directory to a target directory, substituting
+ * `{{KEY}}` placeholders in text files. Mirrors directory structure.
+ *
+ * Substitutions are applied to .md, .html, .json, .yml, .yaml files. Other
+ * file types are copied byte-for-byte.
+ */
+function scaffoldFromTemplate(templateDir, targetDir, substitutions) {
+    const TEXT_EXTENSIONS = new Set([".md", ".html", ".json", ".yml", ".yaml"]);
+    function substitute(content) {
+        let out = content;
+        for (const [key, value] of Object.entries(substitutions)) {
+            out = out.replace(new RegExp(`\\{\\{${key}\\}\\}`, "g"), value);
+        }
+        return out;
+    }
+    function walk(srcDir, destDir) {
+        fs.mkdirSync(destDir, { recursive: true });
+        for (const entry of fs.readdirSync(srcDir, { withFileTypes: true })) {
+            const srcPath = path.join(srcDir, entry.name);
+            const destPath = path.join(destDir, entry.name);
+            if (entry.isDirectory()) {
+                walk(srcPath, destPath);
+            }
+            else if (entry.isFile()) {
+                const ext = path.extname(entry.name).toLowerCase();
+                if (TEXT_EXTENSIONS.has(ext)) {
+                    const content = fs.readFileSync(srcPath, "utf8");
+                    fs.writeFileSync(destPath, substitute(content));
+                }
+                else {
+                    fs.copyFileSync(srcPath, destPath);
+                }
+            }
+        }
+    }
+    walk(templateDir, targetDir);
+}
+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);
+    }
+    // Scaffold from the template tree shipped with the package.
+    // __dirname after build is dist/, so the templates dir is one level up.
+    const distDir = path.dirname(new URL(import.meta.url).pathname);
+    const pkgRoot = path.resolve(distDir, "..");
+    const templateDir = path.join(pkgRoot, "templates", "analysis");
+    if (!fs.existsSync(templateDir)) {
+        console.error(`\n  Error: Bundled analysis template not found at ${templateDir}\n`);
+        process.exit(1);
+    }
+    fs.mkdirSync(targetDir, { recursive: true });
+    fs.mkdirSync(path.join(targetDir, ".overscore"), { recursive: true });
+    // Write analysis.json metadata (not part of the template — has dynamic id)
+    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));
+    // Walk the template tree, substituting placeholders
+    const today = new Date().toISOString().slice(0, 10);
+    scaffoldFromTemplate(templateDir, targetDir, {
+        TITLE: data.title,
+        SLUG: data.slug,
+        PROJECT_SLUG: data.project_slug,
+        DATE: today,
+    });
+    // Pull project's company-context.md and any project-level rule overrides
+    // (best-effort, non-fatal — the template defaults are still in place if
+    // the network is down or the hub is unreachable).
+    const baseUrl = cfg.apiUrl.replace(/\/api$/, "");
+    const authHeader = { Authorization: `Bearer ${cfg.apiKey}` };
+    // Company context
+    try {
+        const ctxRes = await fetch(`${baseUrl}/api/projects/${data.project_slug}/context`, { headers: authHeader });
+        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
+    }
+    // SQL style override — if the project has a custom version, replace the
+    // template default. If null/missing, the template default stays in place.
+    try {
+        const sqlRes = await fetch(`${baseUrl}/api/projects/${data.project_slug}/sql-style`, { headers: authHeader });
+        if (sqlRes.ok) {
+            const sqlData = (await sqlRes.json());
+            if (sqlData.sql_style_md) {
+                fs.writeFileSync(path.join(targetDir, ".claude", "rules", "sql-style.md"), sqlData.sql_style_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 +1032,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();
@@ -694,7 +1111,9 @@ 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/cli list
@@ -707,5 +1126,9 @@ else {
     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,14 @@
 {
   "name": "@overscore/cli",
-  "version": "0.6.1",
-  "description": "CLI for deploying Overscore dashboards",
+  "version": "0.8.0",
+  "description": "CLI for deploying Overscore dashboards and publishing analyses",
   "bin": {
     "overscore": "dist/index.js"
   },
   "files": [
-    "dist"
+    "dist",
+    "skills",
+    "templates"
   ],
   "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.

package/templates/analysis/.claude/CLAUDE.md

@@ -0,0 +1,51 @@
+# Overscore Analysis: {{TITLE}}
+
+This is an **Overscore Analysis** — a one-off, frozen investigation that produces a single self-contained `report.html` you can share in Slack and reopen later to refresh.
+
+Analyses are NOT dashboards. No React, no `package.json`, no `useQuery`, no scheduled refreshes. The numbers are baked into `report.html` at publish time.
+
+## First steps — interview before you query
+
+**Before running any SQL, check `analysis-log.md`.** If it has no queries logged yet (this is a fresh analysis), invoke the **`start-analysis`** skill to interview the user first. Do NOT query data blindly — the user almost always knows things about the data that will save you 80% of the exploration work.
+
+The interview takes 2 minutes and gives you:
+- The real question (often different from the title)
+- Which BigQuery tables matter (so you don't probe them all)
+- What success looks like (a number? a chart? a go/no-go?)
+- 1–3 hypotheses to test
+- Time window and filters
+
+After the interview, draft an initial entry in `analysis-log.md` and propose a query plan for the user to approve.
+
+## Always maintain analysis-log.md
+
+`analysis-log.md` is the **recoverable session state** for this analysis. Future sessions (including yourself, weeks from now, after the user runs `analysis pull`) read it to know what's been done. **Append to it as you work**, not at the end.
+
+Every meaningful exploration step is a new entry: the question being investigated, the SQL you ran (paste it verbatim), what you observed, the conclusion you drew, and any open questions for the next pass.
+
+## 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.
+
+## 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`, the `.claude/` tree, etc.) to Overscore. The analysis becomes available at `https://<project>.overscore.dev/analysis/{{SLUG}}`. Re-publishing overwrites the previous version. **Always preview `report.html` in a browser and get the user's approval before publishing.**
+
+## When the user wants to turn this into a dashboard
+
+Analyses are static. 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** — it would corrupt the artifact. Use the global `scaffold-overscore-artifact` skill to route them to a fresh dashboard scaffold that lives as a sibling of this analysis.
+
+## See also
+
+The following files in `.claude/rules/` load automatically when you touch matching files — you don't need to read them now:
+
+- **`sql-style.md`** — BigQuery dialect and SQL formatting (loads when editing SQL or `analysis-log.md`)
+- **`report-html.md`** — Self-contained HTML rules and dark-theme spec (loads when editing `report.html`)
+- **`analysis-methodology.md`** — Investigation loop, when to ask vs query (loads when editing `analysis-log.md`)
+- **`company-context.md`** — Project-level data context (loaded every session)

package/templates/analysis/.claude/rules/analysis-methodology.md

@@ -0,0 +1,63 @@
+---
+paths:
+  - "analysis-log.md"
+---
+
+# Analysis methodology
+
+These rules apply when you're updating `analysis-log.md` — i.e., when you're actively investigating. They exist to keep you from drifting into "let me just run more queries" mode and to make sure every query you run actually moves the analysis forward.
+
+## The investigation loop
+
+Every analysis is a loop, not a straight line:
+
+1. **Hypothesis** — write down what you think you'll find before running the query. One sentence.
+2. **Query** — write the SQL, log it in `analysis-log.md` with the hypothesis.
+3. **Observe** — read the result. Note the actual outcome, not just "the query ran."
+4. **Revise** — was the hypothesis right? If yes, you've moved one step. If no, what does the surprise tell you? Update your mental model.
+5. **Repeat** — pick the next hypothesis from what you just learned, not from a fixed list.
+
+If you're running queries without a hypothesis attached, you're probing, not investigating. Stop and ask the user what they actually want to know.
+
+## Ask before you query
+
+**Always ask the user, don't guess, when:**
+
+- The question is ambiguous ("what's our churn?" — over what time window? by cohort or overall? for which product?)
+- A time window isn't stated (last 7 days? last quarter? all time?)
+- The data shape suggests multiple interpretations (does "active user" mean "logged in" or "performed an action"?)
+- A filter could go multiple ways (include or exclude trial users? include or exclude test accounts?)
+- You're about to run a query that will scan a lot of data (>100GB)
+
+The 30-second cost of asking is always cheaper than the 5-minute cost of running the wrong query and having to redo it.
+
+## One hypothesis per query batch
+
+Don't run 8 exploratory queries to "see what's there." Pick one hypothesis, run the 1-3 queries that test it, log them, observe, and then pick the next hypothesis based on what you learned. Batching by hypothesis keeps `analysis-log.md` readable and keeps you from accumulating noise.
+
+## Escalation: summary → detail
+
+Always start with summary queries before detail queries:
+
+1. **Sizing pass:** `SELECT COUNT(*), MIN(date), MAX(date) FROM table` — how big is it, what time range does it cover?
+2. **Distribution pass:** `SELECT category, COUNT(*) FROM table GROUP BY 1 ORDER BY 2 DESC LIMIT 50` — what are the top values?
+3. **Trend pass:** `SELECT DATE_TRUNC(date, WEEK), COUNT(*) FROM table GROUP BY 1` — what's the shape over time?
+4. **Detail pass:** `SELECT * FROM table WHERE specific_thing LIMIT 100` — only after you know what to look for.
+
+Jumping straight to detail queries before you understand the shape is the most common way to waste an investigation.
+
+## When to stop
+
+You're done investigating when:
+
+- You've answered the user's original question with enough confidence to act on it
+- You've documented the answer in `analysis-log.md` and you can write `report.html` from the log alone
+- Further queries are returning increasingly marginal information
+
+You're NOT done when:
+
+- You've found "interesting things" but haven't answered the original question
+- Your conclusion is "more analysis needed" — that means you stopped too early; pick a hypothesis and keep going
+- The user is going to ask "but what about X?" and you don't have an answer
+
+When you think you're done, re-read the original question (it's at the top of `analysis-log.md`) and ask yourself: "If I sent this report to the user right now, would they have what they need?" If no, keep going. If yes, write `report.html`.

package/templates/analysis/.claude/rules/report-html.md

@@ -0,0 +1,83 @@
+---
+paths:
+  - "report.html"
+---
+
+# report.html — self-contained HTML report
+
+`report.html` is the deliverable. It's what gets shared in Slack, opened by stakeholders, and reopened weeks later. It must work standalone with **no network requests at view time**.
+
+## Hard rules
+
+- **Inline all CSS.** No `<link rel="stylesheet">`, no Tailwind CDN, no Google Fonts. Use a single `<style>` block in the `<head>`.
+- **Bake the data into the HTML.** No `fetch()`, no `XMLHttpRequest`, no API calls. The numbers must be visible to anyone who opens the file with no logins, no tokens, no broken external dependencies.
+- **Charts are inline.** Inline SVG is the safest option. Embedded base64 PNGs are OK. A self-contained chart library (Recharts/D3 from CDN) is acceptable **only if the data is already baked into the page** and the script tag is inline-loaded — but inline SVG is preferred because it survives indefinitely.
+- **No `useQuery`, no `@overscore/client`, no React.** This is a static HTML file, not a React app.
+
+## Dark theme — Overscore brand
+
+Match the Overscore visual style:
+
+- **Background:** `#0a0a0f` (near-black)
+- **Cards:** `rgba(255,255,255,0.03)` background with `1px solid rgba(255,255,255,0.06)` border, generous padding, `border-radius: 16px`
+- **Text:** `#fff` for headlines and numbers, `rgba(255,255,255,0.6)` for body, `rgba(255,255,255,0.4)` for secondary
+- **Accents:** violet `#8b5cf6`, blue `#3b82f6`, emerald `#10b981`, amber `#f59e0b`
+- **Font:** `-apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif`
+- **Spacing:** generous — `padding: 4rem 2rem` on the body, `max-width: 900px`, `margin: 0 auto` to center
+
+## Structure
+
+A good analysis report has these sections in order:
+
+1. **Title** — the question being answered, not just the topic
+2. **Executive summary** — 2-3 sentences with the headline finding
+3. **KPI cards** — 3-5 of the most important numbers, each with context (% change, comparison, etc.)
+4. **Primary chart** — the main visualization that tells the story
+5. **Supporting charts** — 1-3 secondary visuals that drill into the why
+6. **Detail tables** — only if the reader needs precise numbers
+7. **Conclusions** — what the data says, in plain language
+8. **Methodology footer** — date generated, time window analyzed, any caveats
+
+## Skeleton
+
+```html
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <title>The headline finding goes here</title>
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <style>
+    body {
+      background: #0a0a0f;
+      color: #fff;
+      font-family: -apple-system, BlinkMacSystemFont, sans-serif;
+      max-width: 900px;
+      margin: 0 auto;
+      padding: 4rem 2rem;
+      line-height: 1.6;
+    }
+    .card {
+      background: rgba(255,255,255,0.03);
+      border: 1px solid rgba(255,255,255,0.06);
+      border-radius: 16px;
+      padding: 1.5rem;
+      margin: 1.5rem 0;
+    }
+    .kpi { font-size: 2.5rem; font-weight: 600; }
+    .label { color: rgba(255,255,255,0.4); font-size: 0.875rem; text-transform: uppercase; letter-spacing: 0.05em; }
+    h1, h2, h3 { font-weight: 600; }
+    h1 { font-size: 2rem; margin-bottom: 0.5rem; }
+    .footer { margin-top: 4rem; color: rgba(255,255,255,0.3); font-size: 0.75rem; }
+  </style>
+</head>
+<body>
+  <h1>Headline finding here</h1>
+  <p style="color: rgba(255,255,255,0.6);">Executive summary in 2-3 sentences.</p>
+  <!-- KPI cards, charts, conclusions, etc. -->
+  <div class="footer">Generated YYYY-MM-DD · {{TITLE}}</div>
+</body>
+</html>
+```
+
+**Always preview `report.html` in a browser and get the user's approval before publishing.**

package/templates/analysis/.claude/rules/sql-style.md

@@ -0,0 +1,43 @@
+---
+paths:
+  - "analysis-log.md"
+  - "*.sql"
+  - "**/*.sql"
+---
+
+# SQL style — BigQuery
+
+These rules apply when you're drafting SQL queries to paste into `analysis-log.md` or to test against the warehouse. Every query you run should also be logged verbatim in `analysis-log.md`.
+
+## Dialect — BigQuery Standard SQL
+
+- Backtick fully-qualified table refs: `` `project.dataset.table` ``. Always use the project name when querying — it's explicit and unambiguous.
+- Cast safely: `SAFE_CAST(col AS INT64)`, `SAFE_CAST(col AS DATE)`. A bad cast in vanilla SQL kills the query; `SAFE_CAST` returns `NULL`.
+- Parse dates with `PARSE_DATE("%Y-%m-%d", col)` and timestamps with `PARSE_TIMESTAMP("%Y-%m-%d %H:%M:%S", col)`. Don't trust automatic coercion.
+- For window functions, prefer `QUALIFY` over a subquery wrapper: `SELECT ... QUALIFY ROW_NUMBER() OVER (...) = 1`.
+- Use `COUNTIF(condition)` instead of `SUM(CASE WHEN condition THEN 1 ELSE 0 END)`.
+- Date arithmetic: `DATE_ADD(date, INTERVAL 7 DAY)`, `DATE_DIFF(d1, d2, DAY)`, `DATE_TRUNC(date, MONTH)`.
+
+## Formatting
+
+- Uppercase keywords: `SELECT`, `FROM`, `WHERE`, `GROUP BY`, `ORDER BY`, `WITH`, `JOIN`, `ON`, `QUALIFY`.
+- One clause per line. Don't cram `SELECT a, b FROM t WHERE x = 1` onto one line if it has more than ~3 columns.
+- Trailing commas in column lists are fine in BigQuery and make diffs cleaner.
+- Use CTEs (`WITH name AS (...)`) for any query with more than one logical step. Easier to read, easier to debug, easier to log.
+- Two-space indentation inside parens and CTEs.
+- Inline comments with `--` for non-obvious filters: `-- exclude test users`.
+
+## Safety on exploratory queries
+
+- **Always include `LIMIT`** on initial exploratory queries unless you're aggregating. `SELECT * FROM big_table LIMIT 100` lets you see the shape without burning a query slot.
+- For aggregations, use `GROUP BY ... ORDER BY count DESC LIMIT 50` to find the top contributors before you go wide.
+- When you're scanning a table for the first time, run `SELECT COUNT(*), MIN(date_col), MAX(date_col) FROM ...` to learn the size and time range before doing anything else.
+
+## Logging discipline
+
+**Every query you run goes into `analysis-log.md`** with:
+1. A one-line description of what it was investigating
+2. The exact SQL (paste it inside a fenced code block — don't paraphrase)
+3. A one-line summary of what you observed in the result
+
+If you ran a query and didn't log it, you wasted the query — future-you can't reproduce or learn from it.

package/templates/analysis/.claude/skills/start-analysis/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: start-analysis
+description: Use at the start of any new Overscore analysis BEFORE querying data. Interviews the user about the question, known data sources, success criteria, and hypotheses, then writes an initial analysis-log.md entry and proposes a query plan for approval. Trigger when analysis-log.md has no queries logged yet.
+---
+
+# Starting an analysis the right way
+
+Most analyses fail because Claude jumps straight into querying every BigQuery table to "see what's there." That wastes 80% of the time on exploration the user could have skipped with a 2-minute conversation.
+
+This skill exists to make sure that conversation happens before any SQL runs.
+
+## When to invoke this
+
+- The user has just scaffolded a fresh analysis (`analysis-log.md` only has the seed entry, no queries logged)
+- The user is asking you to "look at" or "investigate" something for the first time on this analysis
+- You're about to write your first query and you're not sure what tables matter
+
+Do NOT invoke this on a re-pull of an existing analysis with prior queries logged — that's a continuation, not a fresh start, and the prior log already has the context.
+
+## The interview — 6 questions, 2 minutes
+
+Read `interview-template.md` for the literal prompts. The interview covers:
+
+1. **Restate the question** — confirm you understand what the user actually wants to know. The analysis title is often a shorthand; the real question is usually more specific.
+2. **Known tables** — ask what BigQuery tables the user already knows are relevant. Most users know at least 1-3 tables that matter. This saves you from probing every dataset.
+3. **Success criteria** — ask what "done" looks like. A single number? A chart? A go/no-go decision? Knowing this shapes everything downstream.
+4. **Hypotheses** — ask the user for 1-3 things they suspect might be true. Even rough hypotheses give you a query plan to test against.
+5. **Time window and filters** — ask what time range, what cohort, what to include/exclude. These are the most common sources of wasted queries when wrong.
+6. **Anything else weird** — ask "is there anything I should know about this data?" Users usually surface 1-2 known quirks ("dates before 2024 are unreliable," "we have a test_user flag we exclude").
+
+Ask these one or two at a time conversationally — don't dump all 6 at once like a form. The user will respond more openly to a real conversation.
+
+## After the interview
+
+1. **Read `.claude/rules/company-context.md`** to cross-reference what the user said against what's already documented about the project's data.
+2. **Draft an initial entry in `analysis-log.md`** with:
+   - The clarified question (not the original title)
+   - The tables the user named, with what each contains
+   - The success criteria (literally — quote the user)
+   - The hypotheses (numbered)
+   - The time window and any filters
+   - Any quirks the user mentioned
+3. **Propose a prioritized query plan** — 3-5 queries that test the highest-priority hypothesis first. For each query, write the SQL, what hypothesis it tests, and what result would confirm or refute it. Do NOT run any of them yet.
+4. **Get approval.** Show the user the plan and ask them to confirm or revise before you run anything.
+
+## What this skill does NOT do
+
+- It does not run any SQL. Querying happens after the user approves the plan.
+- It does not write `report.html`. That happens at the end of the investigation, not the beginning.
+- It does not skip the interview because the analysis title looks "obvious." Even obvious-sounding analyses benefit from the 2-minute conversation.
+
+## If the user resists the interview
+
+Some users will say "just look at the data, I'll tell you if it's wrong." That's a trap — you'll spend 30 minutes probing tables and still need the interview at the end. Push back once: "I can save us a lot of time if you tell me what tables matter and what success looks like — it's a 2-minute conversation." If they still refuse, do a single sizing pass on the parent project's known tables (from `company-context.md`), then come back and ask narrower questions based on what you found.

package/templates/analysis/.claude/skills/start-analysis/interview-template.md

@@ -0,0 +1,31 @@
+# Interview prompts
+
+These are the literal questions to ask the user during the start-analysis interview. Ask them one or two at a time, conversationally — don't dump them all at once. Wait for an answer before moving to the next.
+
+## 1. Restate the question
+
+> Before I touch any data — let me make sure I understand what you actually want to know. The analysis title is "{{TITLE}}" — is the real question more specific than that? For example, are you looking at a particular time window, a particular cohort, or trying to make a specific decision?
+
+## 2. Known tables
+
+> Which BigQuery tables do you already know are relevant here? Even if you only know one or two, that's a huge head start — I won't have to probe everything.
+
+## 3. Success criteria
+
+> What does "done" look like for this analysis? Are we trying to land on a single number, build a chart, or make a go/no-go decision? Knowing the shape of the answer helps me know when to stop digging.
+
+## 4. Hypotheses
+
+> What do you suspect might be true here? Even rough guesses help — I'd rather test 2-3 specific hypotheses than wander around looking for patterns. What's your gut telling you?
+
+## 5. Time window and filters
+
+> What time window should we be looking at? And are there any filters I should apply by default — like excluding test users, internal accounts, or specific products?
+
+## 6. Anything weird about this data
+
+> Last one: is there anything about this data I should know upfront? Quirks, known issues, things that look suspicious but are actually fine, conventions you use? Those are the things that bite if I find out about them three queries in instead of right now.
+
+---
+
+After all 6 answers, summarize back what you heard and ask the user to confirm. Then write the initial entry in `analysis-log.md` and propose the query plan.

package/templates/analysis/analysis-log.md

@@ -0,0 +1,17 @@
+# {{TITLE}}
+
+## {{DATE}} — Initial exploration
+
+**Question:** {{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)_

package/templates/analysis/report.html

@@ -0,0 +1,17 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<title>{{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>{{TITLE}}</h1>
+  <p>This analysis is empty. Have Claude do the work and regenerate this file.</p>
+</body>
+</html>