@overscore/cli 0.10.0 → 0.10.1

package/dist/index.js

@@ -261,7 +261,10 @@ async function deploy() {
     // Sync context files to Hub
     const { projectSlug } = loadEnv();
     const baseUrl = apiUrl.replace(/\/api$/, "");
-    // Sync company context (with conflict detection)
+    // Upload knowledge base (project-level, shared across all artifacts)
+    await uploadKnowledgeBase(process.cwd(), baseUrl, projectSlug, apiKey);
+    // Sync company context (with conflict detection) — legacy path for
+    // projects that haven't migrated to the knowledge base yet.
     const companyCtxPath = path.resolve(process.cwd(), ".claude/rules/company-context.md");
     if (fs.existsSync(companyCtxPath)) {
         const content = fs.readFileSync(companyCtxPath, "utf-8");
@@ -304,9 +307,11 @@ async function deploy() {
         }
     }
     // Sync dashboard context (no conflict detection needed — per-dashboard)
-    const dashCtxPath = path.resolve(process.cwd(), ".claude/rules/dashboard-context.md");
-    if (fs.existsSync(dashCtxPath)) {
-        const content = fs.readFileSync(dashCtxPath, "utf-8");
+    const dashCtxPath = path.resolve(process.cwd(), ".claude/rules/this-dashboard.md");
+    const legacyDashCtxPath = path.resolve(process.cwd(), ".claude/rules/dashboard-context.md");
+    const activeDashCtxPath = fs.existsSync(dashCtxPath) ? dashCtxPath : fs.existsSync(legacyDashCtxPath) ? legacyDashCtxPath : null;
+    if (activeDashCtxPath) {
+        const content = fs.readFileSync(activeDashCtxPath, "utf-8");
         try {
             await fetch(`${baseUrl}/api/dashboards/${dashboardSlug}/context`, {
                 method: "PUT",
@@ -329,21 +334,43 @@ async function queryList() {
     const { dashboardSlug } = loadEnv();
     const data = (await apiRequest("GET", `/api/dashboards/${dashboardSlug}/queries`));
     console.log(`\n  Dashboard: ${data.dashboard}\n`);
+    // Registered queries
     if (data.queries.length === 0) {
         console.log("  No queries registered yet.\n");
-        console.log("  Add one with:");
-        console.log('    npx @overscore/cli query add <name> "SELECT ..."\n');
-        return;
+        console.log("  Add a SQL query:  npx @overscore/cli query add <name> \"SELECT ...\"\n");
     }
-    for (const q of data.queries) {
-        const rowInfo = q.row_count !== null ? ` (~${q.row_count.toLocaleString()} rows)` : "";
-        console.log(`  ${q.query_name}${rowInfo}`);
-        console.log(`    useQuery("${q.query_name}")`);
-        if (q.sample_row) {
-            const cols = Object.keys(q.sample_row).join(", ");
-            console.log(`    columns: ${cols}`);
+    else {
+        console.log("  Registered Queries:\n");
+        for (const q of data.queries) {
+            const rowInfo = q.row_count !== null ? ` (~${q.row_count.toLocaleString()} rows)` : "";
+            const sourceTag = q.source === "dataset" ? " [dataset]" : "";
+            console.log(`  ${q.query_name}${rowInfo}${sourceTag}`);
+            console.log(`    useQuery("${q.query_name}")`);
+            if (q.sample_row) {
+                const cols = Object.keys(q.sample_row).join(", ");
+                console.log(`    columns: ${cols}`);
+            }
+            else if (q.columns && q.columns.length > 0) {
+                const cols = q.columns.map((c) => `${c.name} (${c.type})`).join(", ");
+                console.log(`    columns: ${cols}`);
+            }
+            console.log();
+        }
+    }
+    // Project datasets (always shown)
+    if (data.project_datasets && data.project_datasets.length > 0) {
+        console.log("  Project Datasets:\n");
+        for (const ds of data.project_datasets) {
+            const rowInfo = ds.row_count !== null ? ` (~${ds.row_count.toLocaleString()} rows)` : "";
+            const sampleTag = ds.is_sample ? " [sample]" : "";
+            console.log(`  ${ds.name}${rowInfo}${sampleTag}`);
+            if (ds.columns && ds.columns.length > 0) {
+                const cols = ds.columns.map((c) => `${c.name} (${c.type})`).join(", ");
+                console.log(`    columns: ${cols}`);
+            }
+            console.log(`    To use: npx @overscore/cli query add <query-name> --dataset ${ds.name}`);
+            console.log();
         }
-        console.log();
     }
 }
 async function queryShow(name) {
@@ -365,16 +392,28 @@ async function queryShow(name) {
     }
     console.log(`\n  ${query.query_name}`);
     if (query.row_count !== null) {
-        console.log(`  ~${query.row_count.toLocaleString()} rows\n`);
+        console.log(`  ~${query.row_count.toLocaleString()} rows`);
     }
-    else {
-        console.log();
+    if (query.source === "dataset" && query.dataset_name) {
+        console.log(`  source: uploaded dataset (${query.dataset_name})`);
     }
-    console.log(`  SQL:`);
-    console.log(`  ${query.sql}\n`);
-    if (query.sample_row) {
-        console.log(`  Sample row:`);
-        console.log(`  ${JSON.stringify(query.sample_row, null, 2).split("\n").join("\n  ")}\n`);
+    console.log();
+    if (query.source === "dataset") {
+        if (query.columns && query.columns.length > 0) {
+            console.log(`  Columns:`);
+            for (const col of query.columns) {
+                console.log(`    ${col.name}  (${col.type})`);
+            }
+            console.log();
+        }
+    }
+    else if (query.sql) {
+        console.log(`  SQL:`);
+        console.log(`  ${query.sql}\n`);
+        if (query.sample_row) {
+            console.log(`  Sample row:`);
+            console.log(`  ${JSON.stringify(query.sample_row, null, 2).split("\n").join("\n  ")}\n`);
+        }
     }
 }
 function resolveSql(sqlOrNext) {
@@ -391,10 +430,15 @@ function resolveSql(sqlOrNext) {
     return sqlOrNext;
 }
 async function queryAdd(name, sql) {
+    // Check for --dataset flag
+    const datasetFlagIndex = process.argv.indexOf("--dataset");
+    const datasetName = datasetFlagIndex !== -1 ? process.argv[datasetFlagIndex + 1] : undefined;
     const resolvedSql = resolveSql(sql);
-    if (!name || !resolvedSql) {
+    if (!name || (!resolvedSql && !datasetName)) {
         console.error('\n  Usage: npx @overscore/cli query add <name> "<sql>"\n');
-        console.error("  Or with a file:");
+        console.error("  Or link an uploaded dataset:");
+        console.error("    npx @overscore/cli query add <name> --dataset <dataset-name>\n");
+        console.error("  Or with a SQL file:");
         console.error("    npx @overscore/cli query add <name> --file query.sql\n");
         process.exit(1);
     }
@@ -403,7 +447,26 @@ async function queryAdd(name, sql) {
         process.exit(1);
     }
     const { dashboardSlug } = loadEnv();
-    const data = (await apiRequest("POST", `/api/dashboards/${dashboardSlug}/queries`, { query_name: name, sql_text: resolvedSql }));
+    let body;
+    if (datasetName) {
+        // Look up the dataset UUID from project_datasets in the queries endpoint
+        const listData = (await apiRequest("GET", `/api/dashboards/${dashboardSlug}/queries`));
+        const dataset = (listData.project_datasets ?? []).find((ds) => ds.name === datasetName);
+        if (!dataset) {
+            console.error(`\n  Error: Dataset "${datasetName}" not found in this project.\n`);
+            console.error("  Available datasets:");
+            for (const ds of listData.project_datasets ?? []) {
+                console.error(`    - ${ds.name}`);
+            }
+            console.error();
+            process.exit(1);
+        }
+        body = { query_name: name, dataset_id: dataset.id };
+    }
+    else {
+        body = { query_name: name, sql_text: resolvedSql };
+    }
+    const data = (await apiRequest("POST", `/api/dashboards/${dashboardSlug}/queries`, body));
     console.log(`\n  Query "${data.query_name}" created.\n`);
     console.log(`  Use it in your dashboard:`);
     console.log(`    const { data } = useQuery("${data.query_name}");\n`);
@@ -435,24 +498,34 @@ async function queryRemove(name) {
     await apiRequest("DELETE", `/api/dashboards/${dashboardSlug}/queries/${encodeURIComponent(name)}`);
     console.log(`\n  Query "${name}" deleted.\n`);
 }
-function saveQueryResult(sql, data) {
+function saveQueryResult(sql, data, sourceFile) {
     try {
         const hash = createHash("sha256").update(sql).digest("hex").slice(0, 8);
-        const snippet = sql
-            .toLowerCase()
-            .replace(/[^a-z0-9_]+/g, "_")
-            .replace(/^_|_$/g, "")
-            .slice(0, 40);
-        const filename = `${hash}_${snippet}.json`;
         const dataDir = path.resolve(process.cwd(), "data");
+        // Check for ANY existing file with this hash — handles both old and new
+        // filename formats so the same query isn't duplicated.
+        if (fs.existsSync(dataDir)) {
+            const existing = fs.readdirSync(dataDir).find((f) => f.includes(hash) && f.endsWith(".json"));
+            if (existing) {
+                return { path: `data/${existing}`, cached: true };
+            }
+        }
+        // Build filename: human-readable prefix when from a file, hash prefix otherwise
+        let filename;
+        if (sourceFile) {
+            const baseName = path.basename(sourceFile, path.extname(sourceFile));
+            filename = `${baseName}__${hash}.json`;
+        }
+        else {
+            const snippet = sql
+                .toLowerCase()
+                .replace(/[^a-z0-9_]+/g, "_")
+                .replace(/^_|_$/g, "")
+                .slice(0, 40);
+            filename = `${hash}_${snippet}.json`;
+        }
         const fullPath = path.join(dataDir, filename);
         const relPath = `data/${filename}`;
-        // Hash is content-derived from the SQL — if a file with this hash already
-        // exists, the exact same query was run before. Skip the rewrite so the
-        // data/ folder doesn't accumulate duplicates of identical queries.
-        if (fs.existsSync(fullPath)) {
-            return { path: relPath, cached: true };
-        }
         if (!fs.existsSync(dataDir)) {
             fs.mkdirSync(dataDir, { recursive: true });
         }
@@ -501,7 +574,9 @@ async function queryTest(sql) {
         process.exit(1);
     }
     const data = (await apiRequest("POST", `/api/projects/${projectSlug}/test-query`, { sql: resolvedSql }));
-    const saved = saveQueryResult(resolvedSql, data);
+    const fileIndex = process.argv.indexOf("--file");
+    const sourceFile = fileIndex !== -1 ? process.argv[fileIndex + 1] : undefined;
+    const saved = saveQueryResult(resolvedSql, data, sourceFile);
     const savedLine = saved
         ? saved.cached
             ? `  Cached (already saved earlier): ${saved.path}`
@@ -657,7 +732,7 @@ VITE_OVERSCORE_API_URL=https://overscore.dev/api
             if (dashCtxData.context_md) {
                 const rulesDir = path.join(targetDir, ".claude", "rules");
                 fs.mkdirSync(rulesDir, { recursive: true });
-                fs.writeFileSync(path.join(rulesDir, "dashboard-context.md"), dashCtxData.context_md);
+                fs.writeFileSync(path.join(rulesDir, "this-dashboard.md"), dashCtxData.context_md);
                 console.log("  Updated dashboard context from Hub.");
             }
         }
@@ -889,19 +964,23 @@ 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);
+    // Try knowledge base first — if the project has knowledge files, they
+    // replace the legacy company-context.md.
+    const hasKnowledge = await syncKnowledgeBase(targetDir, baseUrl, projectSlug, apiKey);
+    // Company context — only fetch if no knowledge files exist (legacy path).
+    if (!hasKnowledge) {
+        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
+        catch {
+            // Non-fatal
+        }
     }
     // SQL style override — null means "use the CLI default"; leave the
     // template/bundle file alone in that case.
@@ -918,6 +997,93 @@ async function syncHubManagedRules(targetDir, baseUrl, projectSlug, apiKey) {
         // Non-fatal
     }
 }
+/**
+ * Sync the project knowledge base from the Hub into .claude/knowledge/.
+ * Returns true if knowledge files were found (caller can skip legacy
+ * company-context.md in that case).
+ */
+async function syncKnowledgeBase(targetDir, baseUrl, projectSlug, apiKey) {
+    const authHeader = { Authorization: `Bearer ${apiKey}` };
+    const knowledgeDir = path.join(targetDir, ".claude", "knowledge");
+    try {
+        const res = await fetch(`${baseUrl}/api/projects/${projectSlug}/knowledge`, { headers: authHeader });
+        if (!res.ok)
+            return false;
+        const data = (await res.json());
+        if (!data.files || data.files.length === 0)
+            return false;
+        fs.mkdirSync(knowledgeDir, { recursive: true });
+        // Write each knowledge file
+        for (const file of data.files) {
+            fs.writeFileSync(path.join(knowledgeDir, file.path), file.content);
+        }
+        // Generate INDEX.md
+        const indexLines = [
+            "# Project Knowledge Base",
+            "",
+            "Read the relevant file when working on a topic. Do NOT read all files every session.",
+            "",
+        ];
+        for (const file of data.files) {
+            indexLines.push(`- **${file.title}**: \`.claude/knowledge/${file.path}\``);
+        }
+        indexLines.push("");
+        fs.writeFileSync(path.join(knowledgeDir, "INDEX.md"), indexLines.join("\n"));
+        // Store hashes for conflict detection on upload
+        const hashMap = {};
+        for (const file of data.files) {
+            hashMap[file.path] = file.content_hash;
+        }
+        fs.writeFileSync(path.join(knowledgeDir, ".knowledge-hashes"), JSON.stringify(hashMap, null, 2));
+        console.log(`  Knowledge base synced (${data.files.length} files).`);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Upload local knowledge files back to the Hub.
+ * Called from deploy/publish so knowledge learned during a session persists.
+ */
+async function uploadKnowledgeBase(targetDir, baseUrl, projectSlug, apiKey) {
+    const knowledgeDir = path.join(targetDir, ".claude", "knowledge");
+    if (!fs.existsSync(knowledgeDir))
+        return;
+    const files = [];
+    for (const entry of fs.readdirSync(knowledgeDir)) {
+        // Skip INDEX.md (auto-generated) and dotfiles (.knowledge-hashes)
+        if (entry === "INDEX.md" ||
+            entry.startsWith(".") ||
+            !entry.endsWith(".md"))
+            continue;
+        const content = fs.readFileSync(path.join(knowledgeDir, entry), "utf-8");
+        // Extract title from first H1 line, fallback to filename
+        const titleMatch = content.match(/^#\s+(.+)$/m);
+        const title = titleMatch
+            ? titleMatch[1]
+            : entry.replace(/\.md$/, "").replace(/[-_]/g, " ");
+        files.push({ path: entry, title, content });
+    }
+    if (files.length === 0)
+        return;
+    try {
+        const res = await fetch(`${baseUrl}/api/projects/${projectSlug}/knowledge`, {
+            method: "PUT",
+            headers: {
+                Authorization: `Bearer ${apiKey}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({ files }),
+        });
+        if (res.ok) {
+            console.log(`  Knowledge base synced (${files.length} files).`);
+        }
+    }
+    catch {
+        // Non-fatal
+    }
+}
 /**
  * Fetch the latest platform-owned Claude Code rules from the Hub and write
  * them into the project's .claude/ directory. This keeps rules like
@@ -925,8 +1091,8 @@ async function syncHubManagedRules(targetDir, baseUrl, projectSlug, apiKey) {
  * projects that were scaffolded months ago.
  *
  * Called from `deploy` (before uploading) and `pull` (after extracting).
- * User-owned files (company-context.md, dashboard-context.md) are NOT
- * touched — those sync via separate mechanisms.
+ * User-owned files (company-context.md, this-dashboard.md, knowledge/)
+ * are NOT touched — those sync via separate mechanisms.
  */
 async function syncPlatformRules(targetDir, baseUrl, apiKey) {
     try {
@@ -1273,6 +1439,8 @@ async function analysisPublish() {
     console.log(`\n  Published successfully!\n`);
     printBundleSummary(files, process.cwd());
     console.log(`\n    URL: ${data.url}\n`);
+    // Upload knowledge base so insights from this analysis persist
+    await uploadKnowledgeBase(process.cwd(), baseUrl, meta.project_slug, cfg.apiKey);
 }
 /**
  * Ensure analysis.json has a valid id by fetching from the Hub.
@@ -1844,7 +2012,8 @@ else if (command === "query") {
   Commands:
     list                          List all queries
     show <name>                   Show a query's SQL and sample data
-    add <name> "<sql>"            Add a new query
+    add <name> "<sql>"            Add a SQL query
+    add <name> --dataset <name>   Link an uploaded dataset as a query
     update <name> "<sql>"         Update a query's SQL
     remove <name>                 Delete a query
     run "<sql>"                   Run SQL against BigQuery

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@overscore/cli",
-  "version": "0.10.0",
+  "version": "0.10.1",
   "description": "CLI for deploying Overscore dashboards and publishing analyses",
   "bin": {
     "overscore": "dist/index.js"

package/skills/save-knowledge/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: save-knowledge
+description: Reviews data insights discovered during dashboard or analysis work and proposes additions to the project knowledge base. Use before deploying a dashboard or publishing an analysis, when the user says "save what you learned", or after discovering non-obvious data facts like timezone quirks, column semantics, dedup rules, or metric definitions.
+---
+
+# Save Knowledge
+
+Run this skill before deploying a dashboard or when explicitly asked.
+
+## When to invoke
+- Before `npx @overscore/cli deploy`
+- When the user says "save what you learned" or similar
+
+## Process
+
+1. Review the dashboard code and any exploratory queries you ran.
+
+2. Read `.claude/knowledge/INDEX.md` to see what's already documented.
+
+3. For each new insight, decide:
+   - **Project knowledge** (helps ALL future artifacts) → propose addition to `.claude/knowledge/`
+   - **Dashboard-specific** (design decision, query note) → append to `.claude/rules/this-dashboard.md`
+   - **Already known** → skip
+
+4. Present proposed additions to the user for approval before writing any files.
+
+## What qualifies as project knowledge vs dashboard-specific
+- "dates are UTC-7 no DST" → project knowledge (helps all artifacts)
+- "affiliate_id = 0 is unattributed" → project knowledge
+- "Revenue chart excludes refunds per Finance definition" → dashboard-specific
+- "Default filter is 90 days for CFO's current-quarter view" → dashboard-specific

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

@@ -1,6 +1,8 @@
 ---
 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.
+description: Routes users to the correct Overscore artifact type (Dashboard vs Analysis) and scaffolds it in the right location. Dashboards track metrics forever with live data; Analyses answer a question once with a static HTML report.
+when_to_use: Use when the user wants to create a new dashboard or analysis, or when they're inside one artifact type and want to switch to the other. Trigger phrases include "build a dashboard", "track X over time", "create an analysis", "investigate why X", "turn this into a dashboard", "do a quick analysis", "I want to monitor", "I need a report on".
+argument-hint: "[dashboard or analysis description]"
 ---
 
 # Scaffolding Overscore Artifacts

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

@@ -51,9 +51,20 @@ The CLI authenticates via `~/.overscore/config` (set up on first use). Credentia
 
 The `queries/` directory is for SQL files you want to keep around — the canonical version of each Q-numbered query in `analysis-log.md`, queries the user might want to re-run later, or anything you've iterated on enough to deserve a name. File names like `q3-cohort-halo.sql` cross-reference the Query Log. Exploratory one-offs don't need to live here; they're already saved as JSON in `data/`.
 
-## Where data context lives
+## Project Knowledge Base
 
-`.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.
+`.claude/knowledge/INDEX.md` lists all knowledge files for this project — table definitions,
+business logic, metric formulas, data quirks. **Read INDEX.md before starting any data work.**
+Only read the specific files relevant to your current task.
+
+When you discover something non-obvious (a timezone gotcha, a dedup rule, a column that means
+something unexpected), **propose adding it to the knowledge base**:
+- Create a new `.claude/knowledge/{topic}.md` file (one topic per file, 20-80 lines)
+- Or append to an existing file if the topic matches
+- Update INDEX.md when you add or remove a file
+
+Knowledge files sync to the Hub on `analysis publish` and are shared with every artifact
+in this project. Good knowledge notes help every future session.
 
 ## Previewing
 
@@ -96,4 +107,4 @@ The following files in `.claude/rules/` load automatically when you touch matchi
 - **`report-html.md`** — Self-contained HTML rules and dark-theme spec (loads when editing `report.html`)
 - **`report-components.md`** — Copy-paste HTML/SVG component snippets: KPI cards, charts, tables, heatmaps (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)
+- **`knowledge/INDEX.md`** — Project knowledge base catalog (read before data work)

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

@@ -80,4 +80,11 @@ A good analysis report has these sections in order:
 </html>
 ```
 
+**Mobile responsiveness.** Reports are often opened on phones from Slack links. The skeleton's `max-width: 900px` and viewport meta tag handle the basics, but also:
+- Use `clamp()` or media queries for KPI font sizes (`font-size: clamp(1.5rem, 5vw, 2.5rem)`) so they don't overflow on 375px screens.
+- KPI card grids should wrap: `display: grid; grid-template-columns: repeat(auto-fit, minmax(140px, 1fr))`.
+- Tables need `overflow-x: auto` on their container.
+- Padding: `2rem` is fine on desktop but use `padding: 2rem 1rem` on mobile via `@media (max-width: 480px)`.
+- Charts (SVG): set `width="100%" viewBox="..."` and let them scale, or use `max-width: 100%`.
+
 **Always preview `report.html` in a browser and get the user's approval before publishing.**

package/templates/analysis/.claude/skills/save-knowledge/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: save-knowledge
+description: Reviews data insights discovered during analysis work and proposes additions to the project knowledge base. Use before publishing an analysis, when the user says "save what you learned", or after discovering non-obvious data facts like timezone quirks, column semantics, dedup rules, or metric definitions.
+---
+
+# Save Knowledge
+
+Run this skill before publishing an analysis or when explicitly asked.
+
+## When to invoke
+- Before `analysis publish` (review what you learned first)
+- When the user says "save what you learned" or similar
+
+## Process
+
+1. Review `analysis-log.md` — look for non-obvious data facts you discovered:
+   - Column semantics that weren't obvious from the name
+   - Timezone, dedup, or join gotchas
+   - Metric definitions or business rules
+   - Data quality issues or known gaps
+
+2. Read `.claude/knowledge/INDEX.md` to see what's already documented.
+
+3. For each new insight, decide:
+   - **Project knowledge** (helps ALL future artifacts) → propose a new file or addition to `.claude/knowledge/`
+   - **Already known** (in an existing knowledge file) → skip
+   - **Analysis-specific** (only relevant to this investigation) → leave in analysis-log.md
+
+4. Present proposed additions to the user for approval before writing any files.
+
+5. After approval, write the files and update INDEX.md.
+
+## What qualifies as project knowledge
+- "unique_page_views is already COUNT(DISTINCT domain_userid)" → YES
+- "date_az is America/Phoenix UTC-7, no DST" → YES
+- "affiliate_id = 0 is unattributed, usually exclude" → YES
+- "Q1 churn spiked because of the pricing change" → NO (analysis conclusion, not data fact)
+- "I used a 90-day window for this analysis" → NO (analysis-specific decision)

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

@@ -1,6 +1,11 @@
 ---
 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.
+description: Interviews the user before querying data at the start of a new Overscore analysis. Captures the real question, known tables, success criteria, hypotheses, time window, and data quirks, then writes an initial analysis-log.md entry and proposes a query plan for approval. Use when analysis-log.md has no queries logged yet, or when the user says "investigate", "look into", or "analyze" something for the first time.
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash(npx @overscore/cli query run *)
 ---
 
 # Starting an analysis the right way
@@ -32,7 +37,7 @@ Ask these one or two at a time conversationally — don't dump all 6 at once lik
 
 ## 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.
+1. **Read `.claude/knowledge/INDEX.md`** and any relevant knowledge files to understand what previous sessions have already documented about this project's data. Cross-reference what the user said against what's already known.
 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
@@ -51,4 +56,4 @@ Ask these one or two at a time conversationally — don't dump all 6 at once lik
 
 ## 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.
+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 the knowledge base), then come back and ask narrower questions based on what you found.

package/templates/analysis/_overscoreignore

@@ -9,3 +9,4 @@
 data/
 *.draft.html
 *.email.html
+.knowledge-hashes