@overscore/cli 0.10.2 → 0.11.1

package/dist/index.js

@@ -1,9 +1,11 @@
 #!/usr/bin/env node
 import fs from "fs";
 import path from "path";
+import http from "http";
+import net from "net";
 import { execSync } from "child_process";
 import { createInterface } from "readline";
-import { createHash } from "crypto";
+import { createHash, randomBytes } from "crypto";
 import yauzl from "yauzl";
 // ── Shared helpers ──────────────────────────────────────────────────
 function parseEnv(content) {
@@ -266,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}`,
@@ -294,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
@@ -641,11 +613,43 @@ async function pull(slug) {
     const versionParam = versionIndex !== -1 && process.argv[versionIndex + 1]
         ? process.argv[versionIndex + 1]
         : null;
-    // Interactive prompts for credentials
-    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);
+    // Resolve API key: device token → auto-create os_ key, else prompt
+    let apiKey = "";
+    const configPath = path.join(process.env.HOME || "", ".overscore", "config");
+    if (fs.existsSync(configPath)) {
+        const cfg = parseEnv(fs.readFileSync(configPath, "utf-8"));
+        const deviceToken = cfg.OVERSCORE_DEVICE_TOKEN;
+        if (deviceToken) {
+            try {
+                const keyRes = await fetch(`${HUB_URL}/api/projects/${slug}/api-keys`, {
+                    method: "POST",
+                    headers: {
+                        Authorization: `Bearer ${deviceToken}`,
+                        "Content-Type": "application/json",
+                    },
+                    body: JSON.stringify({ name: `${slug} pull key` }),
+                });
+                if (keyRes.status === 401 || keyRes.status === 403) {
+                    console.error("\n  Error: Device token is invalid or expired. Run 'npx @overscore/cli auth login' to re-authenticate.\n");
+                    process.exit(1);
+                }
+                if (keyRes.ok) {
+                    const keyData = (await keyRes.json());
+                    apiKey = keyData.raw_key || "";
+                }
+            }
+            catch {
+                // Network error — fall through to prompt
+            }
+        }
+    }
+    if (!apiKey) {
+        console.log("  Tip: Run 'npx @overscore/cli auth login' to authenticate once and skip this step.");
+        apiKey = await prompt("API key (from the Hub):");
+        if (!apiKey || !apiKey.startsWith("os_")) {
+            console.error("\n  Error: API key should start with os_\n");
+            process.exit(1);
+        }
     }
     const apiUrl = "https://overscore.dev/api";
     const baseUrl = apiUrl.replace(/\/api$/, "");
@@ -667,10 +671,10 @@ async function pull(slug) {
         console.error(`\n  Error: ${errorMsg}\n`);
         process.exit(1);
     }
-    const projectSlug = res.headers.get("X-VD-Project-Slug") || "";
-    const dashboardSlug = res.headers.get("X-VD-Dashboard-Slug") || slug;
-    const version = res.headers.get("X-VD-Version") || "?";
-    const commitMsg = res.headers.get("X-VD-Commit-Message") || "";
+    const projectSlug = res.headers.get("X-OS-Project-Slug") || "";
+    const dashboardSlug = res.headers.get("X-OS-Dashboard-Slug") || slug;
+    const version = res.headers.get("X-OS-Version") || "?";
+    const commitMsg = res.headers.get("X-OS-Commit-Message") || "";
     // Download the zip
     const zipBuffer = Buffer.from(await res.arrayBuffer());
     // Extract to ./<slug>/
@@ -695,68 +699,97 @@ async function pull(slug) {
         fs.mkdirSync(targetDir, { recursive: true });
     }
     await extractZip(zipBuffer, targetDir);
-    // Generate .env (only overscore config — user adds their own API keys)
+    // Generate .env (no API key — 'npx @overscore/cli dev' injects it at runtime)
     const envContent = `# Overscore Configuration
 VITE_OVERSCORE_PROJECT_SLUG=${projectSlug}
 VITE_OVERSCORE_DASHBOARD_SLUG=${dashboardSlug}
-VITE_OVERSCORE_API_KEY=${apiKey}
 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}
     npm install
-    code .
-    claude
-
-  Note: If this dashboard uses third-party APIs, add your
-  API keys to .env before running.
+    npx @overscore/cli dev   # starts dev server with auth injected
 
   When ready to deploy:
 
@@ -1758,67 +1791,122 @@ function analysisPreview() {
         process.exit(1);
     }
 }
+// ── dev ─────────────────────────────────────────────────────────────
+async function dev() {
+    // Must be run from inside a dashboard project folder
+    const envPath = path.resolve(process.cwd(), ".env");
+    if (!fs.existsSync(envPath)) {
+        console.error("\n  Error: No .env file found. Run this from inside a dashboard project folder.\n");
+        process.exit(1);
+    }
+    const localEnv = parseEnv(fs.readFileSync(envPath, "utf-8"));
+    const projectSlug = localEnv.VITE_OVERSCORE_PROJECT_SLUG;
+    if (!projectSlug) {
+        console.error("\n  Error: VITE_OVERSCORE_PROJECT_SLUG not set in .env.\n");
+        process.exit(1);
+    }
+    // Get device token from global config
+    const configPath = path.join(process.env.HOME || "", ".overscore", "config");
+    if (!fs.existsSync(configPath)) {
+        console.error("\n  Error: Not authenticated. Run 'npx @overscore/cli auth login' first.\n");
+        process.exit(1);
+    }
+    const cfg = parseEnv(fs.readFileSync(configPath, "utf-8"));
+    const deviceToken = cfg.OVERSCORE_DEVICE_TOKEN;
+    if (!deviceToken) {
+        console.error("\n  Error: No device token found. Run 'npx @overscore/cli auth login' first.\n");
+        process.exit(1);
+    }
+    // Create a temporary dev session key
+    console.log("\n  Creating dev session key...");
+    let keyId = null;
+    let apiKey = null;
+    try {
+        const keyRes = await fetch(`${HUB_URL}/api/projects/${projectSlug}/api-keys`, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${deviceToken}`,
+                "Content-Type": "application/json",
+            },
+            body: JSON.stringify({ name: "dev session (auto-cleanup)" }),
+        });
+        if (keyRes.status === 401 || keyRes.status === 403) {
+            console.error("\n  Error: Device token is invalid or expired. Run 'npx @overscore/cli auth login' to re-authenticate.\n");
+            process.exit(1);
+        }
+        if (!keyRes.ok) {
+            const errData = await keyRes.json().catch(() => ({}));
+            console.error(`\n  Error: ${errData.error || `HTTP ${keyRes.status}`}\n`);
+            process.exit(1);
+        }
+        const keyData = (await keyRes.json());
+        keyId = keyData.id ?? null;
+        apiKey = keyData.raw_key ?? null;
+    }
+    catch {
+        console.error("\n  Error: Could not reach overscore.dev to create dev session key.\n");
+        process.exit(1);
+    }
+    if (!apiKey) {
+        console.error("\n  Error: Failed to get API key for dev session.\n");
+        process.exit(1);
+    }
+    // Best-effort cleanup: revoke the session key on exit
+    let cleaned = false;
+    async function cleanup() {
+        if (cleaned || !keyId)
+            return;
+        cleaned = true;
+        try {
+            await fetch(`${HUB_URL}/api/projects/${projectSlug}/api-keys`, {
+                method: "DELETE",
+                headers: {
+                    Authorization: `Bearer ${deviceToken}`,
+                    "Content-Type": "application/json",
+                },
+                body: JSON.stringify({ id: keyId }),
+            });
+        }
+        catch {
+            // Best effort — key will remain but that's acceptable
+        }
+    }
+    // Spawn npm run dev with the key injected into the environment
+    const { spawn } = await import("child_process");
+    const child = spawn("npm", ["run", "dev"], {
+        stdio: "inherit",
+        env: { ...process.env, VITE_OVERSCORE_API_KEY: apiKey },
+    });
+    child.on("exit", async (code) => {
+        await cleanup();
+        process.exit(code ?? 0);
+    });
+    process.on("SIGINT", async () => {
+        await cleanup();
+        process.exit(0);
+    });
+    process.on("SIGTERM", async () => {
+        await cleanup();
+        process.exit(0);
+    });
+}
 // ── auth ────────────────────────────────────────────────────────────
 async function authStatus() {
-    const configDir = path.join(process.env.HOME || "", ".overscore");
-    const configPath = path.join(configDir, "config");
-    // Check global config
+    const configPath = path.join(process.env.HOME || "", ".overscore", "config");
     if (fs.existsSync(configPath)) {
         const cfg = parseEnv(fs.readFileSync(configPath, "utf-8"));
-        const key = cfg.OVERSCORE_API_KEY;
+        const deviceToken = cfg.OVERSCORE_DEVICE_TOKEN;
         const project = cfg.OVERSCORE_PROJECT_SLUG;
-        if (key && project) {
-            // Verify the key is still valid
-            let valid = false;
-            try {
-                const hubUrl = cfg.OVERSCORE_API_URL?.replace(/\/api$/, "") || HUB_URL;
-                const res = await fetch(`${hubUrl}/api/projects/verify-key`, {
-                    method: "POST",
-                    headers: { "Content-Type": "application/json" },
-                    body: JSON.stringify({ key }),
-                });
-                if (res.ok) {
-                    const data = (await res.json());
-                    valid = true;
-                    console.log(`
+        if (deviceToken) {
+            console.log(`
   Authenticated
 
-  Key:     ${key.slice(0, 10)}...
-  Project: ${data.project_slug || project}
-  Config:  ~/.overscore/config
-  Status:  Valid
-`);
-                }
-            }
-            catch {
-                // network error
-            }
-            if (!valid) {
-                console.log(`
-  Authentication problem
-
-  Key:     ${key.slice(0, 10)}...
-  Project: ${project}
-  Config:  ~/.overscore/config
-  Status:  Invalid or expired
+  Device token: ${deviceToken.slice(0, 12)}...
+  Project:      ${project || "—"}
+  Config:       ~/.overscore/config
 
-  Run 'npx @overscore/cli auth login' to update your key.
-`);
-            }
-            return;
-        }
-    }
-    // Check local .env
-    const envPath = path.resolve(process.cwd(), ".env");
-    if (fs.existsSync(envPath)) {
-        const env = parseEnv(fs.readFileSync(envPath, "utf-8"));
-        if (env.VITE_OVERSCORE_API_KEY) {
-            console.log(`
-  Using local .env (this project only)
-
-  Key:       ${env.VITE_OVERSCORE_API_KEY.slice(0, 10)}...
-  Project:   ${env.VITE_OVERSCORE_PROJECT_SLUG || "—"}
-  Dashboard: ${env.VITE_OVERSCORE_DASHBOARD_SLUG || "—"}
+  Run 'npx @overscore/cli dev' to start the dev server.
+  Run 'npx @overscore/cli auth logout' to sign out.
 `);
             return;
         }
@@ -1826,64 +1914,126 @@ async function authStatus() {
     console.log(`
   Not authenticated
 
-  No API key found. Run 'npx @overscore/cli auth login' to set one up.
+  Run 'npx @overscore/cli auth login' to authenticate.
 `);
 }
 async function authLogin() {
     const configDir = path.join(process.env.HOME || "", ".overscore");
     const configPath = path.join(configDir, "config");
-    console.log("\n  Set up Overscore CLI authentication.\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");
+    const state = randomBytes(16).toString("hex");
+    // Find a free port in range 9876–9886
+    let chosenPort = null;
+    for (let p = 9876; p <= 9886; p++) {
+        const free = await new Promise((resolve) => {
+            const srv = net.createServer();
+            srv.once("error", () => resolve(false));
+            srv.once("listening", () => { srv.close(() => resolve(true)); });
+            srv.listen(p, "127.0.0.1");
+        });
+        if (free) {
+            chosenPort = p;
+            break;
+        }
+    }
+    if (!chosenPort) {
+        console.error("\n  Error: No free port found in range 9876–9886.\n");
         process.exit(1);
     }
-    // Auto-resolve project from key
-    let projectSlug = null;
+    // Start local callback server
+    let resolveCallback;
+    const callbackPromise = new Promise((resolve) => {
+        resolveCallback = resolve;
+    });
+    const server = http.createServer((req, res) => {
+        const reqUrl = new URL(req.url ?? "/", `http://localhost:${chosenPort}`);
+        if (reqUrl.pathname !== "/callback") {
+            res.writeHead(404);
+            res.end();
+            return;
+        }
+        const token = reqUrl.searchParams.get("token") ?? "";
+        const returnedState = reqUrl.searchParams.get("state") ?? "";
+        const project = reqUrl.searchParams.get("project") ?? undefined;
+        if (returnedState !== state || !token.startsWith("ocli_")) {
+            res.writeHead(400, { "Content-Type": "text/plain" });
+            res.end("Invalid callback");
+            return;
+        }
+        res.writeHead(200, { "Content-Type": "text/html" });
+        res.end(`<!DOCTYPE html><html><head><title>Overscore CLI</title></head>` +
+            `<body style="font-family:sans-serif;text-align:center;padding:3rem">` +
+            `<h2>Authenticated! You can close this tab.</h2></body></html>`);
+        resolveCallback({ token, project });
+    });
+    server.listen(chosenPort, "127.0.0.1");
+    const loginUrl = `${HUB_URL}/login?next=${encodeURIComponent(`/api/cli/auth/finalize?port=${chosenPort}&state=${state}`)}&mode=signin`;
+    console.log(`\n  Opening browser to authenticate...`);
+    console.log(`\n  If your browser doesn't open automatically, visit:\n  ${loginUrl}\n`);
     try {
-        const res = await fetch(`${HUB_URL}/api/projects/verify-key`, {
-            method: "POST",
-            headers: { "Content-Type": "application/json" },
-            body: JSON.stringify({ key: apiKey }),
-        });
-        if (res.ok) {
-            const data = (await res.json());
-            projectSlug = data.project_slug || null;
-            if (projectSlug) {
-                console.log(`\n  Detected project: ${projectSlug}`);
-            }
+        const platform = process.platform;
+        if (platform === "darwin") {
+            execSync(`open '${loginUrl}'`);
+        }
+        else if (platform === "win32") {
+            execSync(`start "" "${loginUrl}"`);
         }
         else {
-            console.error("\n  Error: API key is invalid or expired.\n");
-            process.exit(1);
+            execSync(`xdg-open '${loginUrl}'`);
         }
     }
     catch {
-        console.error("\n  Error: Could not reach overscore.dev to verify key.\n");
-        process.exit(1);
+        // Browser open failed — user can follow the printed URL
     }
-    if (!projectSlug) {
-        projectSlug = await prompt("  Project slug:");
-        if (!projectSlug) {
-            console.error("\n  Error: Project slug is required\n");
-            process.exit(1);
-        }
+    // Wait up to 120 seconds for the callback
+    const timeout = setTimeout(() => {
+        console.error("\n  Error: Timed out waiting for browser login (120s).\n");
+        server.close();
+        process.exit(1);
+    }, 120000);
+    const { token: deviceToken, project: projectSlug } = await callbackPromise;
+    clearTimeout(timeout);
+    server.close();
+    // Preserve any existing os_ API key so dashboard .env fallback still works
+    let existingApiKey = "";
+    if (fs.existsSync(configPath)) {
+        const existing = parseEnv(fs.readFileSync(configPath, "utf-8"));
+        existingApiKey = existing.OVERSCORE_API_KEY || "";
     }
     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 });
+    const lines = [
+        `OVERSCORE_API_URL=${HUB_URL}/api`,
+        `OVERSCORE_DEVICE_TOKEN=${deviceToken}`,
+    ];
+    if (projectSlug)
+        lines.push(`OVERSCORE_PROJECT_SLUG=${projectSlug}`);
+    if (existingApiKey)
+        lines.push(`OVERSCORE_API_KEY=${existingApiKey}`);
+    fs.writeFileSync(configPath, lines.join("\n") + "\n", { mode: 0o600 });
     console.log(`
   Authenticated!
 
-  Key:     ${apiKey.slice(0, 10)}...
-  Project: ${projectSlug}
-  Config:  ~/.overscore/config
-
-  You're ready to use the CLI.
+  Device token saved to ~/.overscore/config.
+  You won't need to copy API keys manually — create-overscore and pull
+  will authenticate automatically from now on.
 `);
 }
 async function authLogout() {
     const configPath = path.join(process.env.HOME || "", ".overscore", "config");
     if (fs.existsSync(configPath)) {
+        // Attempt server-side revocation of the device token (non-fatal)
+        try {
+            const cfg = parseEnv(fs.readFileSync(configPath, "utf-8"));
+            const deviceToken = cfg.OVERSCORE_DEVICE_TOKEN;
+            if (deviceToken) {
+                await fetch(`${HUB_URL}/api/cli/auth/revoke`, {
+                    method: "POST",
+                    headers: { Authorization: `Bearer ${deviceToken}` },
+                });
+            }
+        }
+        catch {
+            // Ignore — Hub may be unreachable
+        }
         fs.unlinkSync(configPath);
         console.log("\n  Logged out. Global config removed.\n");
     }
@@ -1930,7 +2080,10 @@ ${installed.map((s) => `    - ${s}`).join("\n")}
 // ── Routing ─────────────────────────────────────────────────────────
 const command = process.argv[2];
 const subcommand = process.argv[3];
-if (command === "deploy") {
+if (command === "dev") {
+    dev();
+}
+else if (command === "deploy") {
     deploy();
 }
 else if (command === "pull") {
@@ -2039,8 +2192,9 @@ else {
 
   Commands:
     auth                   Check authentication status
-    auth login             Set up or update your API key
+    auth login             Authenticate via browser (one time per machine)
     auth logout            Remove saved credentials
+    dev                    Start the dev server (injects auth automatically)
     list                   List all dashboards in the project
     deploy                 Build and deploy the dashboard
     pull <slug>            Pull source code from the hub
@@ -2050,6 +2204,8 @@ else {
     install-skills         Install the Overscore skill library into ~/.claude/skills/
 
   Usage:
+    npx @overscore/cli auth login
+    npx @overscore/cli dev
     npx @overscore/cli list
     npx @overscore/cli deploy --message "description"
     npx @overscore/cli pull <slug>

package/package.json

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