@overscore/cli 0.7.0 → 0.8.1

package/dist/index.js

@@ -711,97 +711,87 @@ async function analysisApiRequest(cfg, method, urlPath, body) {
     }
     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.
-`;
+/**
+ * Fetch hub-managed rule files (company-context, sql-style) for a project
+ * and write them into the target analysis folder, overwriting whatever's
+ * there. Best-effort and non-fatal — if the hub is unreachable, the existing
+ * files (template defaults or bundle contents) stay in place.
+ *
+ * Called from both `analysis new` (after the template walker) and `analysis
+ * pull` (after the bundle extraction) so hub overrides always reflect the
+ * latest state regardless of how the analysis was created.
+ */
+async function syncHubManagedRules(targetDir, baseUrl, projectSlug, apiKey) {
+    const authHeader = { Authorization: `Bearer ${apiKey}` };
+    const rulesDir = path.join(targetDir, ".claude", "rules");
+    fs.mkdirSync(rulesDir, { recursive: true });
+    // Company context — null means "no company context set yet"; leave any
+    // existing file alone in that case.
+    try {
+        const ctxRes = await fetch(`${baseUrl}/api/projects/${projectSlug}/context`, { headers: authHeader });
+        if (ctxRes.ok) {
+            const ctxData = (await ctxRes.json());
+            if (ctxData.context_md) {
+                fs.writeFileSync(path.join(rulesDir, "company-context.md"), ctxData.context_md);
+            }
+        }
+    }
+    catch {
+        // Non-fatal
+    }
+    // SQL style override — null means "use the CLI default"; leave the
+    // template/bundle file alone in that case.
+    try {
+        const sqlRes = await fetch(`${baseUrl}/api/projects/${projectSlug}/sql-style`, { headers: authHeader });
+        if (sqlRes.ok) {
+            const sqlData = (await sqlRes.json());
+            if (sqlData.sql_style_md) {
+                fs.writeFileSync(path.join(rulesDir, "sql-style.md"), sqlData.sql_style_md);
+            }
+        }
+    }
+    catch {
+        // Non-fatal
+    }
+}
+/**
+ * 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');
@@ -819,10 +809,18 @@ async function analysisNew(title) {
         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, ".claude", "rules"), { recursive: true });
     fs.mkdirSync(path.join(targetDir, ".overscore"), { recursive: true });
-    // Write analysis.json metadata
+    // 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,
@@ -830,65 +828,18 @@ async function analysisNew(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
+    // Walk the template tree, substituting placeholders
     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
-    }
+    scaffoldFromTemplate(templateDir, targetDir, {
+        TITLE: data.title,
+        SLUG: data.slug,
+        PROJECT_SLUG: data.project_slug,
+        DATE: today,
+    });
+    // Pull hub-managed rules (company context + sql style override). Best-effort
+    // and non-fatal — template defaults stay in place if the hub is unreachable.
+    const baseUrl = cfg.apiUrl.replace(/\/api$/, "");
+    await syncHubManagedRules(targetDir, baseUrl, data.project_slug, cfg.apiKey);
     console.log(`  Analysis created: ${data.title}
   Slug:    ${data.slug}
   Project: ${data.project_slug}
@@ -1029,6 +980,11 @@ async function analysisPull(slug) {
             // Non-fatal
         }
     }
+    // Refresh hub-managed rule files after restoring from the bundle. The
+    // bundle contains whatever was set at publish time; this overwrites them
+    // with the latest hub state so company context and SQL style stay in
+    // sync across pulls. Best-effort and non-fatal.
+    await syncHubManagedRules(targetDir, baseUrl, projectSlug, cfg.apiKey);
     console.log(`
   Pulled "${analysisTitle}"
 

package/package.json

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

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>