@overscore/cli 0.11.0 → 0.11.1

package/dist/index.js

@@ -268,27 +268,20 @@ async function deploy() {
     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,40 +289,17 @@ 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
@@ -736,51 +706,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}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@overscore/cli",
-  "version": "0.11.0",
+  "version": "0.11.1",
   "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)