@overscore/cli 0.11.0 → 0.11.2

package/dist/index.js

@@ -23,7 +23,7 @@ function parseEnv(content) {
     }
     return env;
 }
-function loadEnv() {
+async function loadEnv() {
     // (1) Local .env (inside a dashboard project)
     const envPath = path.resolve(process.cwd(), ".env");
     if (fs.existsSync(envPath)) {
@@ -49,33 +49,32 @@ function loadEnv() {
             };
         }
     }
-    // No creds. Tailor the message based on what kind of folder we're in so the
-    // user gets pointed at the right setup command.
-    const inAnalysisFolder = fs.existsSync(path.resolve(process.cwd(), ".overscore", "analysis.json"));
-    if (inAnalysisFolder) {
-        let analysisSlug = null;
-        try {
-            const meta = JSON.parse(fs.readFileSync(path.resolve(process.cwd(), ".overscore", "analysis.json"), "utf-8"));
-            analysisSlug = typeof meta.slug === "string" ? meta.slug : null;
-        }
-        catch {
-            // Fall through to the generic message.
+    // No creds — trigger browser auth inline, then re-check
+    console.log("\n  No Overscore credentials found. Launching browser login...\n");
+    await authLogin();
+    const configPath2 = path.join(process.env.HOME || "", ".overscore", "config");
+    if (fs.existsSync(configPath2)) {
+        const cfg2 = parseEnv(fs.readFileSync(configPath2, "utf-8"));
+        if (cfg2.OVERSCORE_API_KEY) {
+            return {
+                apiUrl: cfg2.OVERSCORE_API_URL || `${HUB_URL}/api`,
+                apiKey: cfg2.OVERSCORE_API_KEY,
+                dashboardSlug: path.basename(process.cwd()),
+                projectSlug: cfg2.OVERSCORE_PROJECT_SLUG || "",
+            };
         }
-        console.error("\n  Error: No credentials found in this analysis folder.");
-        console.error("  This usually means the analysis hasn't been linked to your account yet.");
-        console.error("  Run:");
-        console.error(`    npx @overscore/cli analysis pull ${analysisSlug || "<slug>"}`);
-        console.error("  to refresh credentials and link this folder, or:");
-        console.error("    npx @overscore/cli auth login");
-        console.error("  if you've never set up the CLI on this machine.\n");
     }
-    else {
-        console.error("\n  Error: No credentials found. Run 'npx @overscore/cli auth login' to set up.\n");
-    }
-    process.exit(1);
+    // Logged in but no project API key yet — the user needs to run setup first
+    console.log(`
+  Logged in! To get your first project set up:
+
+    Create a dashboard:   npx create-overscore --dashboard <name> --project <slug>
+    Pull an analysis:     npx @overscore/cli analysis pull <slug>
+`);
+    process.exit(0);
 }
 async function apiRequest(method, urlPath, body, command) {
-    const { apiUrl, apiKey } = loadEnv();
+    const { apiUrl, apiKey } = await loadEnv();
     const baseUrl = apiUrl.replace(/\/api$/, "");
     const url = `${baseUrl}${urlPath}`;
     const headers = {
@@ -195,7 +194,7 @@ function extractZip(zipBuffer, targetDir) {
 }
 // ── Commands ────────────────────────────────────────────────────────
 async function deploy() {
-    const { apiUrl, apiKey, dashboardSlug } = loadEnv();
+    const { apiUrl, apiKey, dashboardSlug } = await loadEnv();
     // Parse --message flag
     const msgIndex = process.argv.indexOf("--message");
     const commitMessage = msgIndex !== -1 && process.argv[msgIndex + 1]
@@ -264,31 +263,24 @@ async function deploy() {
   URL: ${data.url}
 `);
     // Sync context files to Hub
-    const { projectSlug } = loadEnv();
+    const { projectSlug } = await loadEnv();
     const baseUrl = apiUrl.replace(/\/api$/, "");
     // 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");
-        const hashPath = path.resolve(process.cwd(), ".claude/rules/.context-hash");
-        const storedHash = fs.existsSync(hashPath) ? fs.readFileSync(hashPath, "utf-8").trim() : null;
-        try {
-            // Check if Hub version has changed since we pulled
-            const checkRes = await fetch(`${baseUrl}/api/projects/${projectSlug}/context`, {
-                headers: { Authorization: `Bearer ${apiKey}` },
-            });
-            const checkData = checkRes.ok ? (await checkRes.json()) : null;
-            const hubHash = checkData?.context_md_hash || null;
-            if (storedHash && hubHash && storedHash !== hubHash) {
-                console.log("  ⚠ Company context was updated in the Hub since you pulled.");
-                console.log(`    Review at: ${baseUrl}/projects/${projectSlug}/context`);
-                console.log("    Your local changes were NOT uploaded to avoid overwriting.");
-            }
-            else {
-                const putRes = await fetch(`${baseUrl}/api/projects/${projectSlug}/context`, {
+    // Sync dashboard context — skip stub files (they have no real content)
+    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").trim();
+        const isStub = !content || content.startsWith("<!--") || content === `# ${dashboardSlug}`;
+        if (!isStub) {
+            try {
+                const res = await fetch(`${baseUrl}/api/dashboards/${dashboardSlug}/context`, {
                     method: "PUT",
                     headers: {
                         Authorization: `Bearer ${apiKey}`,
@@ -296,47 +288,24 @@ async function deploy() {
                     },
                     body: JSON.stringify({ context_md: content }),
                 });
-                if (putRes.ok) {
-                    const putData = (await putRes.json());
-                    // Update stored hash
-                    if (putData.context_md_hash) {
-                        fs.mkdirSync(path.dirname(hashPath), { recursive: true });
-                        fs.writeFileSync(hashPath, putData.context_md_hash);
-                    }
-                    console.log("  Company context synced.");
+                if (res.ok) {
+                    const lines = content.split("\n").length;
+                    console.log(`  Dashboard context synced (${lines} lines).`);
                 }
             }
+            catch {
+                // Non-fatal
+            }
         }
-        catch {
-            // Non-fatal
-        }
-    }
-    // Sync dashboard context (no conflict detection needed — per-dashboard)
-    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",
-                headers: {
-                    Authorization: `Bearer ${apiKey}`,
-                    "Content-Type": "application/json",
-                },
-                body: JSON.stringify({ context_md: content }),
-            });
-            console.log("  Dashboard context synced.");
-        }
-        catch {
-            // Non-fatal
+        else {
+            console.log("  Dashboard context: stub, not synced — run save-knowledge to populate it.");
         }
     }
     // Pull latest platform rules so the local project stays up to date
     await syncPlatformRules(process.cwd(), baseUrl, apiKey);
 }
 async function queryList() {
-    const { dashboardSlug } = loadEnv();
+    const { dashboardSlug } = await loadEnv();
     const data = (await apiRequest("GET", `/api/dashboards/${dashboardSlug}/queries`, undefined, "query-list"));
     console.log(`\n  Dashboard: ${data.dashboard}\n`);
     // Registered queries
@@ -383,7 +352,7 @@ async function queryShow(name) {
         console.error("\n  Usage: npx @overscore/cli query show <name>\n");
         process.exit(1);
     }
-    const { dashboardSlug } = loadEnv();
+    const { dashboardSlug } = await loadEnv();
     const data = (await apiRequest("GET", `/api/dashboards/${dashboardSlug}/queries`));
     const query = data.queries.find((q) => q.query_name === name);
     if (!query) {
@@ -451,7 +420,7 @@ async function queryAdd(name, sql) {
         console.error("\n  Error: Query name must start with a lowercase letter and contain only lowercase letters, numbers, and underscores.\n");
         process.exit(1);
     }
-    const { dashboardSlug } = loadEnv();
+    const { dashboardSlug } = await loadEnv();
     let body;
     if (datasetName) {
         // Look up the dataset UUID from project_datasets in the queries endpoint
@@ -484,7 +453,7 @@ async function queryUpdate(name, sql) {
         console.error("    npx @overscore/cli query update <name> --file query.sql\n");
         process.exit(1);
     }
-    const { dashboardSlug } = loadEnv();
+    const { dashboardSlug } = await loadEnv();
     const data = (await apiRequest("PUT", `/api/dashboards/${dashboardSlug}/queries/${encodeURIComponent(name)}`, { sql_text: resolvedSql }));
     console.log(`\n  Query "${data.query_name}" updated.`);
     console.log("  Cache has been invalidated — fresh data on next load.\n");
@@ -499,7 +468,7 @@ async function queryRemove(name) {
         console.log("  Cancelled.\n");
         return;
     }
-    const { dashboardSlug } = loadEnv();
+    const { dashboardSlug } = await loadEnv();
     await apiRequest("DELETE", `/api/dashboards/${dashboardSlug}/queries/${encodeURIComponent(name)}`);
     console.log(`\n  Query "${name}" deleted.\n`);
 }
@@ -557,7 +526,7 @@ async function queryTest(sql) {
         console.error("    npx @overscore/cli query run --file queries/foo.sql\n");
         process.exit(1);
     }
-    const { projectSlug } = loadEnv();
+    const { projectSlug } = await loadEnv();
     if (!projectSlug) {
         const analysisMetaPath = path.resolve(process.cwd(), ".overscore", "analysis.json");
         if (fs.existsSync(analysisMetaPath)) {
@@ -736,51 +705,85 @@ VITE_OVERSCORE_DASHBOARD_SLUG=${dashboardSlug}
 VITE_OVERSCORE_API_URL=https://overscore.dev/api
 `;
     fs.writeFileSync(path.join(targetDir, ".env"), envContent, { mode: 0o600 });
-    // Fetch latest project context from Hub (may be newer than what's in the source zip)
-    try {
-        const ctxRes = await fetch(`${baseUrl}/api/projects/${projectSlug}/context`, {
-            headers: { Authorization: `Bearer ${apiKey}` },
-        });
-        if (ctxRes.ok) {
-            const ctxData = (await ctxRes.json());
-            if (ctxData.context_md) {
-                const rulesDir = path.join(targetDir, ".claude", "rules");
-                fs.mkdirSync(rulesDir, { recursive: true });
-                fs.writeFileSync(path.join(rulesDir, "company-context.md"), ctxData.context_md);
-                // Store hash for conflict detection on next deploy
-                if (ctxData.context_md_hash) {
-                    fs.writeFileSync(path.join(rulesDir, ".context-hash"), ctxData.context_md_hash);
+    const rulesDir = path.join(targetDir, ".claude", "rules");
+    fs.mkdirSync(rulesDir, { recursive: true });
+    // Sync project knowledge base (preferred) — or fall back to legacy company-context.md
+    const hasKnowledge = await syncKnowledgeBase(targetDir, baseUrl, projectSlug, apiKey);
+    if (!hasKnowledge) {
+        try {
+            const ctxRes = await fetch(`${baseUrl}/api/projects/${projectSlug}/context`, {
+                headers: { Authorization: `Bearer ${apiKey}` },
+            });
+            if (ctxRes.ok) {
+                const ctxData = (await ctxRes.json());
+                if (ctxData.context_md) {
+                    fs.writeFileSync(path.join(rulesDir, "company-context.md"), ctxData.context_md);
+                    if (ctxData.context_md_hash) {
+                        fs.writeFileSync(path.join(rulesDir, ".context-hash"), ctxData.context_md_hash);
+                    }
                 }
-                console.log("  Updated company context from Hub.");
             }
         }
+        catch {
+            // Non-fatal
+        }
     }
-    catch {
-        // Non-fatal — the version from the source zip is fine
-    }
-    // Pull dashboard context from Hub (may be newer than the source zip)
+    // Pull dashboard context from Hub
+    let dashboardContextLoaded = false;
     try {
         const dashCtxRes = await fetch(`${baseUrl}/api/dashboards/${dashboardSlug}/context`, {
             headers: { Authorization: `Bearer ${apiKey}` },
         });
         if (dashCtxRes.ok) {
             const dashCtxData = (await dashCtxRes.json());
-            if (dashCtxData.context_md) {
-                const rulesDir = path.join(targetDir, ".claude", "rules");
-                fs.mkdirSync(rulesDir, { recursive: true });
+            if (dashCtxData.context_md && dashCtxData.context_md.trim()) {
                 fs.writeFileSync(path.join(rulesDir, "this-dashboard.md"), dashCtxData.context_md);
-                console.log("  Updated dashboard context from Hub.");
+                dashboardContextLoaded = true;
             }
         }
     }
     catch {
         // Non-fatal
     }
-    // Pull latest platform rules
+    // Create a stub this-dashboard.md if none came from the Hub so Claude knows to fill it in
+    if (!dashboardContextLoaded) {
+        const stubPath = path.join(rulesDir, "this-dashboard.md");
+        if (!fs.existsSync(stubPath) || fs.readFileSync(stubPath, "utf-8").trim() === "") {
+            fs.writeFileSync(stubPath, `# ${slug}\n\n<!-- Claude: fill this in as you build. What does this dashboard answer? Who is the audience? Which queries power which charts? Any non-obvious filter logic or design decisions? -->\n`);
+        }
+    }
+    // Pull latest platform rules (includes save-knowledge skill)
     await syncPlatformRules(targetDir, baseUrl, apiKey);
+    // Print context summary so the developer knows what Claude has access to
+    const knowledgeDir = path.join(targetDir, ".claude", "knowledge");
+    const knowledgeFiles = fs.existsSync(knowledgeDir)
+        ? fs.readdirSync(knowledgeDir).filter((f) => f.endsWith(".md") && f !== "INDEX.md")
+        : [];
+    const dashCtxPath = path.join(rulesDir, "this-dashboard.md");
+    const dashCtxContent = fs.existsSync(dashCtxPath) ? fs.readFileSync(dashCtxPath, "utf-8").trim() : "";
+    const dashCtxIsStub = dashCtxContent.startsWith("<!--") || dashCtxContent === `# ${slug}`;
+    const sqlStylePath = path.join(rulesDir, "sql-style.md");
     console.log(`
   Pulled v${version}${commitMsg ? ` — "${commitMsg}"` : ""}
 
+  Context loaded:`);
+    if (knowledgeFiles.length > 0) {
+        console.log(`    Knowledge base: ${knowledgeFiles.length} file${knowledgeFiles.length !== 1 ? "s" : ""} (${knowledgeFiles.join(", ")})`);
+    }
+    else {
+        console.log(`    Knowledge base: empty — Claude will build it as you work`);
+    }
+    if (dashCtxIsStub || !dashCtxContent) {
+        console.log(`    Dashboard context: none yet — stub created, Claude will fill it in`);
+    }
+    else {
+        const lines = dashCtxContent.split("\n").length;
+        console.log(`    Dashboard context: this-dashboard.md (${lines} lines)`);
+    }
+    if (fs.existsSync(sqlStylePath)) {
+        console.log(`    SQL style: project override active`);
+    }
+    console.log(`
   Next steps:
 
     cd ${slug}
@@ -793,7 +796,7 @@ VITE_OVERSCORE_API_URL=https://overscore.dev/api
 `);
 }
 async function versions() {
-    const { dashboardSlug } = loadEnv();
+    const { dashboardSlug } = await loadEnv();
     const data = (await apiRequest("GET", `/api/dashboards/${dashboardSlug}/versions`));
     console.log(`\n  Dashboard: ${dashboardSlug}\n`);
     if (data.versions.length === 0) {
@@ -817,7 +820,7 @@ async function versions() {
     console.log(`\n  Pull a version: npx @overscore/cli pull ${dashboardSlug} --version N\n`);
 }
 async function listDashboards() {
-    const { apiUrl, apiKey } = loadEnv();
+    const { apiUrl, apiKey } = await loadEnv();
     const baseUrl = apiUrl.replace(/\/api$/, "");
     const res = await fetch(`${baseUrl}/api/dashboards`, {
         headers: { Authorization: `Bearer ${apiKey}` },
@@ -923,44 +926,80 @@ async function loadAnalysisConfig() {
             }
         }
     }
-    // (3) Interactive — only ask for the API key, resolve project automatically
-    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);
+    // (3) No valid API key — use an existing device token or trigger browser auth
+    let existingCfg = fs.existsSync(configPath)
+        ? parseEnv(fs.readFileSync(configPath, "utf-8"))
+        : {};
+    let deviceToken = existingCfg.OVERSCORE_DEVICE_TOKEN;
+    if (!deviceToken) {
+        console.log("\n  No Overscore credentials found. Launching browser login...\n");
+        await authLogin();
+        existingCfg = parseEnv(fs.readFileSync(configPath, "utf-8"));
+        deviceToken = existingCfg.OVERSCORE_DEVICE_TOKEN;
+        if (!deviceToken) {
+            console.error("\n  Error: Login did not complete. Please try again.\n");
+            process.exit(1);
+        }
     }
-    // Look up the project slug from the key
-    let projectSlug = null;
-    try {
-        const res = await fetch(`${HUB_URL}/api/projects/verify-key`, {
+    // Resolve project slug
+    let targetProjectSlug = existingCfg.OVERSCORE_PROJECT_SLUG || "";
+    if (!targetProjectSlug) {
+        targetProjectSlug = await prompt("Project slug:");
+        if (!targetProjectSlug) {
+            console.error("\n  Error: Project slug is required.\n");
+            process.exit(1);
+        }
+    }
+    // Generate an API key via device token (retry once on expired token)
+    let generatedKey;
+    for (let attempt = 0; attempt < 2; attempt++) {
+        const keyGenRes = await fetch(`${HUB_URL}/api/projects/${targetProjectSlug}/api-keys`, {
             method: "POST",
-            headers: { "Content-Type": "application/json" },
-            body: JSON.stringify({ key: apiKey }),
+            headers: {
+                Authorization: `Bearer ${deviceToken}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({ name: `cli-${Date.now()}` }),
         });
-        if (res.ok) {
-            const data = (await res.json());
-            projectSlug = data.project_slug || null;
-            if (projectSlug) {
-                console.log(`\n  Detected project: ${projectSlug}`);
+        if (keyGenRes.ok) {
+            const data = (await keyGenRes.json());
+            generatedKey = data.raw_key;
+            break;
+        }
+        if ((keyGenRes.status === 401 || keyGenRes.status === 403) && attempt === 0) {
+            console.log("\n  Session expired. Launching browser login...\n");
+            await authLogin();
+            existingCfg = parseEnv(fs.readFileSync(configPath, "utf-8"));
+            deviceToken = existingCfg.OVERSCORE_DEVICE_TOKEN;
+            if (!deviceToken) {
+                console.error("\n  Error: Login did not complete. Please try again.\n");
+                process.exit(1);
             }
+            continue;
         }
-    }
-    catch {
-        // Fall back to manual entry
-    }
-    if (!projectSlug) {
-        projectSlug = await prompt("Project slug:");
-        if (!projectSlug) {
-            console.error("\n  Error: Project slug is required\n");
-            process.exit(1);
+        if (keyGenRes.status === 403) {
+            console.error(`\n  Error: Access denied for project "${targetProjectSlug}". Make sure you have access.\n`);
+        }
+        else {
+            console.error(`\n  Error: Failed to generate API key (HTTP ${keyGenRes.status}).\n`);
         }
+        process.exit(1);
+    }
+    if (!generatedKey) {
+        console.error("\n  Error: Failed to generate API key.\n");
+        process.exit(1);
     }
-    // Save for next time
+    // Persist the new key
+    const newLines = [
+        `OVERSCORE_API_URL=${HUB_URL}/api`,
+        `OVERSCORE_DEVICE_TOKEN=${deviceToken}`,
+        `OVERSCORE_API_KEY=${generatedKey}`,
+        `OVERSCORE_PROJECT_SLUG=${targetProjectSlug}`,
+    ];
     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 });
+    fs.writeFileSync(configPath, newLines.join("\n") + "\n", { mode: 0o600 });
     console.log(`\n  Saved to ~/.overscore/config\n`);
-    return { apiUrl: `${HUB_URL}/api`, apiKey, projectSlug };
+    return { apiUrl: `${HUB_URL}/api`, apiKey: generatedKey, projectSlug: targetProjectSlug };
 }
 async function analysisApiRequest(cfg, method, urlPath, body) {
     const baseUrl = cfg.apiUrl.replace(/\/api$/, "");

package/package.json

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

package/skills/save-knowledge/SKILL.md

@@ -5,26 +5,32 @@ description: Reviews data insights discovered during dashboard or analysis work
 
 # 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
+Run before deploying a dashboard, before publishing an analysis, or whenever you discover something non-obvious about the data.
 
 ## Process
 
-1. Review the dashboard code and any exploratory queries you ran.
+1. Review the code you've written and queries you've run this session.
+
+2. **Read the existing files before proposing anything.** Read `.claude/knowledge/INDEX.md`, then read the specific knowledge files relevant to what you learned. Read `.claude/rules/this-dashboard.md` (or `analysis-log.md` for analyses) in full. You need to know what's already there before you can know what's new.
+
+3. For each insight from this session, decide what action to take:
+
+   | Situation | Action |
+   |---|---|
+   | New topic, no existing file covers it | Create a new `.claude/knowledge/{topic}.md`; add entry to INDEX.md |
+   | New fact that belongs in an existing knowledge file | Append a new line or section to that file — do not rewrite what's there |
+   | Fact that refines or corrects something already documented | Edit that specific line/section only — do not duplicate it |
+   | Already documented accurately | Skip entirely |
+   | Dashboard/analysis-specific insight not yet captured | Append to `this-dashboard.md` or `analysis-log.md` |
+   | Insight that updates something already there | Edit that specific part only |
 
-2. Read `.claude/knowledge/INDEX.md` to see what's already documented.
+   **Never overwrite a file wholesale. Never duplicate a fact that's already accurate. Only write what's genuinely new or changed.**
 
-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 changes to the user. Be specific — show the exact text you'd add or the exact edit you'd make. "I should note something about X" is not acceptable — show the line.
 
-4. Present proposed additions to the user for approval before writing any files.
+5. After the user approves, write the files. If you created a new knowledge file, update INDEX.md.
 
-## What qualifies as project knowledge vs dashboard-specific
+## What qualifies as project knowledge vs artifact-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

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

@@ -5,11 +5,7 @@ description: Reviews data insights discovered during analysis work and proposes
 
 # 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
+Run before publishing an analysis or whenever you discover something non-obvious about the data.
 
 ## Process
 
@@ -19,14 +15,21 @@ Run this skill before publishing an analysis or when explicitly asked.
    - Metric definitions or business rules
    - Data quality issues or known gaps
 
-2. Read `.claude/knowledge/INDEX.md` to see what's already documented.
+2. **Read the existing knowledge files before proposing anything.** Read `.claude/knowledge/INDEX.md`, then read the specific files relevant to what you discovered. You need to know what's already there before you can know what's new.
+
+3. For each insight, decide what action to take:
+
+   | Situation | Action |
+   |---|---|
+   | New topic, no existing file covers it | Create a new `.claude/knowledge/{topic}.md`; add entry to INDEX.md |
+   | New fact that belongs in an existing knowledge file | Append a new line or section to that file — do not rewrite what's there |
+   | Fact that refines or corrects something already documented | Edit that specific line/section only — do not duplicate it |
+   | Already documented accurately | Skip entirely |
+   | Analysis-specific (only relevant to this investigation) | Leave in analysis-log.md — don't promote to project knowledge |
 
-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
+   **Never overwrite a file wholesale. Never duplicate a fact that's already accurate. Only write what's genuinely new or changed.**
 
-4. Present proposed additions to the user for approval before writing any files.
+4. Present proposed changes to the user. Show the exact text you'd add or the exact edit you'd make — not a summary of what you intend to write.
 
 5. After approval, write the files and update INDEX.md.
 
@@ -34,5 +37,5 @@ Run this skill before publishing an analysis or when explicitly asked.
 - "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)
+- "Q1 churn spiked because of the pricing change" → NO (analysis conclusion, not a data fact)
 - "I used a 90-day window for this analysis" → NO (analysis-specific decision)