@papi-ai/server 0.6.2 → 0.7.0

package/README.md

@@ -6,7 +6,7 @@
 
 **Takes about 2 minutes.**
 
-1. **Get your config** — Sign up at [PAPI](https://papi-web-three.vercel.app/landing) and copy your `.mcp.json` snippet
+1. **Get your config** — Sign up at [PAPI](https://getpapi.ai/landing) and copy your `.mcp.json` snippet
 2. **Add to your project** — paste it into `.mcp.json` in your project root
 3. **Restart Claude Code** — it will detect the PAPI server automatically
 4. **In Claude Code:** say `run setup`, then `run plan`
@@ -31,7 +31,7 @@ That's it. You're planning.
 
 ## Links
 
-- **Dashboard** — [PAPI](https://papi-web-three.vercel.app/landing)
+- **Dashboard** — [PAPI](https://getpapi.ai/landing)
 - **GitHub** — [cathalos92/papi-ui](https://github.com/cathalos92/papi-ui)
 - **Install guide** — [docs/install-guide.md](https://github.com/cathalos92/papi-ui/blob/main/docs/install-guide.md)
 

package/dist/index.js

@@ -7381,6 +7381,13 @@ ${newParts.join("\n")}` : newParts.join("\n");
       UPDATE strategy_recommendations
       SET status = 'actioned', actioned_cycle = ${cycleNumber}, updated_at = now()
       WHERE id = ${id} AND project_id = ${this.projectId}
+    `;
+      }
+      async dismissRecommendation(id, reason) {
+        await this.sql`
+      UPDATE strategy_recommendations
+      SET status = 'actioned', dismissal_reason = ${reason}, updated_at = now()
+      WHERE id = ${id} AND project_id = ${this.projectId}
     `;
       }
       // -------------------------------------------------------------------------
@@ -8138,6 +8145,20 @@ var init_proxy_adapter = __esm({
           } catch {
             message = errorBody;
           }
+          if (response.status === 401) {
+            throw new Error(
+              `Auth: Invalid API key \u2014 PAPI_DATA_API_KEY was rejected by the proxy.
+Check PAPI_DATA_API_KEY in your .mcp.json config. You can regenerate it from the PAPI dashboard.
+(${response.status} on ${method}: ${message})`
+            );
+          }
+          if (response.status === 403 || response.status === 404) {
+            throw new Error(
+              `Auth: Project not found or access denied \u2014 PAPI_PROJECT_ID may be wrong.
+Check PAPI_PROJECT_ID in your .mcp.json config. Find your project ID in the PAPI dashboard settings.
+(${response.status} on ${method}: ${message})`
+            );
+          }
           throw new Error(`Proxy error (${response.status}) on ${method}: ${message}`);
         }
         const body = await response.json();
@@ -8161,6 +8182,27 @@ var init_proxy_adapter = __esm({
           return false;
         }
       }
+      /**
+       * Validate API key and project access against the proxy.
+       * Returns HTTP status so callers can distinguish 401 (bad key) from 403/404 (bad project).
+       * Status 0 means a network error occurred.
+       */
+      async probeAuth(projectId) {
+        try {
+          const response = await fetch(`${this.endpoint}/invoke`, {
+            method: "POST",
+            headers: {
+              "Content-Type": "application/json",
+              "Authorization": `Bearer ${this.apiKey}`
+            },
+            body: JSON.stringify({ projectId, method: "projectExists", args: [] }),
+            signal: AbortSignal.timeout(5e3)
+          });
+          return { ok: response.ok, status: response.status };
+        } catch {
+          return { ok: false, status: 0 };
+        }
+      }
       // --- Planning & Health ---
       readPlanningLog() {
         return this.invoke("readPlanningLog");
@@ -8411,6 +8453,9 @@ var init_proxy_adapter = __esm({
       projectExists() {
         return this.invoke("projectExists");
       }
+      getBuildReportCountForTask(taskId) {
+        return this.invoke("getBuildReportCountForTask", [taskId]);
+      }
       // --- Atomic plan write-back ---
       planWriteBack(payload) {
         return this.invoke("planWriteBack", [payload]);
@@ -8919,7 +8964,15 @@ var init_git = __esm({
 });
 
 // src/index.ts
+import { readFileSync as readFileSync4 } from "fs";
+import { dirname as dirname2, join as join11 } from "path";
+import { fileURLToPath as fileURLToPath2 } from "url";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { Server as Server2 } from "@modelcontextprotocol/sdk/server/index.js";
+import {
+  CallToolRequestSchema as CallToolRequestSchema2,
+  ListToolsRequestSchema as ListToolsRequestSchema2
+} from "@modelcontextprotocol/sdk/types.js";
 
 // src/config.ts
 import path from "path";
@@ -9067,7 +9120,7 @@ async function createAdapter(optionsOrType, maybePapiDir) {
     }
     case "proxy": {
       const { ProxyPapiAdapter: ProxyPapiAdapter2 } = await Promise.resolve().then(() => (init_proxy_adapter(), proxy_adapter_exports));
-      const dashboardUrl = process.env["PAPI_DASHBOARD_URL"] || "https://papi-web-three.vercel.app";
+      const dashboardUrl = process.env["PAPI_DASHBOARD_URL"] || "https://getpapi.ai";
       const projectId = process.env["PAPI_PROJECT_ID"];
       const dataApiKey = process.env["PAPI_DATA_API_KEY"];
       if (!dataApiKey) {
@@ -9089,13 +9142,33 @@ Already have an account? Make sure PAPI_DATA_API_KEY is set in your .mcp.json en
         projectId: projectId || void 0
       });
       const connected = await adapter2.probeConnection();
-      if (connected) {
-        _connectionStatus = "connected";
-        console.error("[papi] \u2713 Data proxy connected");
-      } else {
+      if (!connected) {
         _connectionStatus = "degraded";
         console.error("[papi] \u2717 Data proxy unreachable \u2014 running in degraded mode");
         console.error("[papi] Check your PAPI_DATA_ENDPOINT configuration.");
+      } else if (projectId) {
+        const auth = await adapter2.probeAuth(projectId);
+        if (!auth.ok) {
+          if (auth.status === 401) {
+            throw new Error(
+              "PAPI_DATA_API_KEY is invalid \u2014 authentication failed.\nCheck the key in your .mcp.json config. You can generate a new key from the PAPI dashboard."
+            );
+          } else if (auth.status === 403 || auth.status === 404) {
+            throw new Error(
+              `PAPI_PROJECT_ID "${projectId}" was not found or you don't have access.
+Check PAPI_PROJECT_ID in your .mcp.json config. Find your project ID in the PAPI dashboard settings.`
+            );
+          } else if (auth.status !== 0) {
+            _connectionStatus = "degraded";
+            console.error(`[papi] \u26A0 Auth check returned ${auth.status} \u2014 running in degraded mode`);
+          }
+        } else {
+          _connectionStatus = "connected";
+          console.error("[papi] \u2713 Data proxy connected");
+        }
+      } else {
+        _connectionStatus = "connected";
+        console.error("[papi] \u2713 Data proxy reachable \u2014 project will be auto-provisioned");
       }
       if (!projectId && connected) {
         try {
@@ -11691,7 +11764,7 @@ ${cleanContent}`;
     pendingRecIds = pending.map((r) => r.id);
   } catch {
   }
-  const handoffs2 = (data.cycleHandoffs ?? []).map((h) => {
+  const handoffs = (data.cycleHandoffs ?? []).map((h) => {
     const parsed = parseBuildHandoff(h.buildHandoff);
     if (parsed && !parsed.createdAt) {
       parsed.createdAt = (/* @__PURE__ */ new Date()).toISOString();
@@ -11730,8 +11803,8 @@ ${cleanContent}`;
   } catch {
   }
   const effortMapLegacy = { XS: 1, S: 2, M: 3, L: 5, XL: 8 };
-  const legacyTaskCount = handoffs2.length;
-  const legacyEffortPoints = handoffs2.reduce((sum, h) => sum + (effortMapLegacy[h.handoff.effort] ?? 3), 0);
+  const legacyTaskCount = handoffs.length;
+  const legacyEffortPoints = handoffs.reduce((sum, h) => sum + (effortMapLegacy[h.handoff.effort] ?? 3), 0);
   const payload = {
     cycleNumber: newCycleNumber,
     cycleLog: {
@@ -11781,7 +11854,7 @@ ${cleanContent}`;
       body: ad.body
     })),
     pendingRecommendationIds: pendingRecIds,
-    handoffs: handoffs2,
+    handoffs,
     cycle,
     reviewedTaskIds
   };
@@ -11830,8 +11903,12 @@ async function writeBack(adapter2, _mode, cycleNumber, data, contextHashes) {
 
 ${cleanContent}`;
   const effortMap = { XS: 1, S: 2, M: 3, L: 5, XL: 8 };
-  const cycleTaskCount = handoffs.length;
-  const cycleEffortPoints = handoffs.reduce((sum, h) => sum + (effortMap[h.handoff.effort] ?? 3), 0);
+  const legacyHandoffs = (data.cycleHandoffs ?? []).map((h) => {
+    const parsed = parseBuildHandoff(h.buildHandoff);
+    return { taskId: h.taskId, handoff: parsed ?? { effort: "M" } };
+  });
+  const cycleTaskCount = legacyHandoffs.length;
+  const cycleEffortPoints = legacyHandoffs.reduce((sum, h) => sum + (effortMap[h.handoff.effort] ?? 3), 0);
   const cycleLogPromise = adapter2.writeCycleLogEntry({
     uuid: randomUUID7(),
     cycleNumber: newCycleNumber,
@@ -12233,7 +12310,7 @@ async function preparePlan(adapter2, config2, filters, focus, force, handoffsOnl
     const [decisions, reports, brief] = await Promise.all([
       adapter2.getActiveDecisions(),
       adapter2.getRecentBuildReports(10),
-      adapter2.getProductBrief()
+      adapter2.readProductBrief()
     ]);
     const northStar = await adapter2.getCurrentNorthStar?.() ?? "";
     const userMessage2 = buildHandoffsOnlyUserMessage({
@@ -12971,6 +13048,27 @@ async function assembleContext2(adapter2, cycleNumber, cyclesSinceLastReview, pr
     adapter2.searchDocs?.({ status: "active", limit: 10 })?.catch(() => []) ?? Promise.resolve([])
   ]);
   const tasks = [...activeTasks, ...recentDoneTasks];
+  const existingAdIds = new Set(decisions.map((d) => d.id));
+  const survivingPendingRecs = [];
+  for (const rec of pendingRecs) {
+    const isOrphaned = (() => {
+      if (rec.target && /^AD-\d+$/.test(rec.target) && !existingAdIds.has(rec.target)) return true;
+      if (rec.type === "ad_update") {
+        const adMatch = rec.content.match(/^(?:delete|resolve|confidence_change|supersede|modify):\s*(AD-\d+)/i);
+        if (adMatch && !existingAdIds.has(adMatch[1])) return true;
+      }
+      return false;
+    })();
+    if (isOrphaned) {
+      try {
+        await adapter2.dismissRecommendation?.(rec.id, "target AD no longer exists");
+        console.error(`[strategy_review] Swept orphaned pending rec ${rec.id} (target: ${rec.target ?? rec.content.slice(0, 50)})`);
+      } catch {
+      }
+    } else {
+      survivingPendingRecs.push(rec);
+    }
+  }
   const recentLog = log;
   let buildPatternsText;
   let reviewPatternsText;
@@ -13076,7 +13174,7 @@ ${lines.join("\n")}`;
   try {
     const plansDir = join2(homedir(), ".claude", "plans");
     if (existsSync(plansDir)) {
-      const lastReviewDate = previousStrategyReviews?.[0]?.date ? new Date(previousStrategyReviews[0].date) : /* @__PURE__ */ new Date(0);
+      const lastReviewDate = previousStrategyReviews?.[0]?.createdAt ? new Date(previousStrategyReviews[0].createdAt) : /* @__PURE__ */ new Date(0);
       const planFiles = readdirSync(plansDir).filter((f) => f.endsWith(".md")).map((f) => {
         const fullPath = join2(plansDir, f);
         const stat2 = statSync(fullPath);
@@ -13320,7 +13418,7 @@ ${cleanContent}`;
       } else {
         await adapter2.updateActiveDecision(ad.id, ad.body, cycleNumber, ad.action);
       }
-      const eventType = ad.action === "delete" ? "deleted" : ad.action === "confidence_change" ? "confidence_changed" : ad.action === "supersede" ? "superseded" : ad.action === "new" ? "created" : "modified";
+      const eventType = ad.action === "delete" ? "invalidated" : ad.action === "confidence_change" ? "confidence_changed" : ad.action === "supersede" ? "superseded" : ad.action === "new" ? "created" : "modified";
       try {
         await adapter2.appendDecisionEvent({
           decisionId: ad.id,
@@ -13381,7 +13479,25 @@ ${cleanContent}`;
   try {
     const recs = extractRecommendations(data, cycleNumber);
     if (recs.length > 0) {
-      await Promise.all(recs.map((rec) => adapter2.writeRecommendation(rec)));
+      const existingAds = await adapter2.getActiveDecisions().catch(() => []);
+      const existingAdIds = new Set(existingAds.map((ad) => ad.id));
+      const filteredRecs = recs.filter((rec) => {
+        if (rec.target && /^AD-\d+$/.test(rec.target)) {
+          if (!existingAdIds.has(rec.target)) {
+            console.error(`[strategy_review] Skipped ghost recommendation for non-existent ${rec.target}: "${rec.content.slice(0, 80)}"`);
+            return false;
+          }
+        }
+        if (rec.type === "ad_update") {
+          const adMatch = rec.content.match(/^(?:delete|resolve|confidence_change|supersede|modify):\s*(AD-\d+)/i);
+          if (adMatch && !existingAdIds.has(adMatch[1])) {
+            console.error(`[strategy_review] Skipped ghost recommendation for non-existent ${adMatch[1]}: "${rec.content.slice(0, 80)}"`);
+            return false;
+          }
+        }
+        return true;
+      });
+      await Promise.all(filteredRecs.map((rec) => adapter2.writeRecommendation(rec)));
     }
   } catch {
   }
@@ -13463,6 +13579,17 @@ async function processReviewOutput(adapter2, rawOutput, cycleNumber) {
   let slackWarning;
   let writeBackFailed;
   let phaseChanges;
+  if (!data) {
+    const marker = "<!-- PAPI_STRUCTURED_OUTPUT -->";
+    const hasMarker = rawOutput.includes(marker);
+    if (hasMarker) {
+      const afterMarker = rawOutput.slice(rawOutput.indexOf(marker) + marker.length, rawOutput.indexOf(marker) + marker.length + 300).trim();
+      writeBackFailed = `Structured output marker found but JSON block was missing or malformed. Content after marker (first 300 chars): "${afterMarker}". Ensure your output includes a valid \`\`\`json block after <!-- PAPI_STRUCTURED_OUTPUT -->.`;
+    } else {
+      const preview = rawOutput.slice(0, 200).trim();
+      writeBackFailed = `No structured output marker found. Expected "<!-- PAPI_STRUCTURED_OUTPUT -->" followed by a \`\`\`json block. Received (first 200 chars): "${preview}". Re-run strategy_review apply with the complete output including both parts.`;
+    }
+  }
   if (data) {
     try {
       phaseChanges = await writeBack2(adapter2, cycleNumber, data, displayText);
@@ -13686,8 +13813,8 @@ async function formatHierarchyForReview(adapter2, currentCycle, prefetchedTasks)
   let phases = [];
   try {
     [horizons, stages, phases] = await Promise.all([
-      adapter2.readHorizons(),
-      adapter2.readStages(),
+      adapter2.readHorizons?.() ?? [],
+      adapter2.readStages?.() ?? [],
       adapter2.readPhases()
     ]);
   } catch {
@@ -13820,7 +13947,7 @@ ${cleanContent}`;
           } else {
             await adapter2.updateActiveDecision(ad.id, ad.body, cycleNumber, ad.action);
           }
-          const eventType = ad.action === "delete" ? "deleted" : ad.action === "confidence_change" ? "confidence_changed" : ad.action === "supersede" ? "superseded" : ad.action === "new" ? "created" : "modified";
+          const eventType = ad.action === "delete" ? "invalidated" : ad.action === "confidence_change" ? "confidence_changed" : ad.action === "supersede" ? "superseded" : ad.action === "new" ? "created" : "modified";
           try {
             await adapter2.appendDecisionEvent({
               decisionId: ad.id,
@@ -13933,7 +14060,7 @@ async function captureDecision(adapter2, input) {
       decisionId: adId,
       eventType: adAction === "created" ? "created" : "modified",
       cycle: cycleNumber,
-      source: "strategy_capture",
+      source: "strategy_change",
       sourceRef: `cycle-${cycleNumber}-capture`,
       detail: `Captured: ${input.text.slice(0, 200)}`
     });
@@ -14434,10 +14561,10 @@ function formatBoard(result) {
     t.title,
     t.status,
     t.cycle != null ? String(t.cycle) : "-",
-    t.phase,
-    t.module,
-    t.epic,
-    t.complexity,
+    t.phase ?? "-",
+    t.module ?? "-",
+    t.epic ?? "-",
+    t.complexity ?? "-",
     t.createdAt ?? "-"
   ]);
   const widths = headers.map(
@@ -17828,15 +17955,15 @@ async function prepareReconcile(adapter2) {
     const misaligned = allTasks.filter((t) => {
       const mapping = phaseStageMap.get(t.phase ?? "");
       if (!mapping) return false;
-      return mapping.stage.status === "Not Started" || mapping.horizon.status === "Not Started";
+      return mapping.stage.status === "deferred" || mapping.horizon.status === "deferred";
     });
     if (misaligned.length > 0) {
-      lines.push("### Hierarchy Misalignment (tasks in Not Started stages/horizons)");
+      lines.push("### Hierarchy Misalignment (tasks in deferred stages/horizons)");
       for (const t of misaligned) {
         const mapping = phaseStageMap.get(t.phase ?? "");
         const stageLabel = mapping?.stage.label ?? "unknown";
         const horizonLabel = mapping?.horizon.label ?? "unknown";
-        lines.push(`- **${t.id}:** ${t.title} \u2014 phase "${t.phase}" belongs to **${stageLabel}** (${horizonLabel}), which is Not Started. Consider deferring or reassigning.`);
+        lines.push(`- **${t.id}:** ${t.title} \u2014 phase "${t.phase}" belongs to **${stageLabel}** (${horizonLabel}), which is deferred. Consider deferring or reassigning.`);
       }
       lines.push("");
     }
@@ -18006,7 +18133,7 @@ async function prepareRetriage(adapter2) {
   lines.push(`**${allTasks.length} tasks** to reassess priority and complexity.`);
   lines.push("");
   try {
-    const ads = await adapter2.readActiveDecisions();
+    const ads = await adapter2.getActiveDecisions();
     if (ads.length > 0) {
       lines.push("### Active Decisions (strategic context)");
       for (const ad of ads.slice(0, 10)) {
@@ -19368,37 +19495,84 @@ Path: ${mcpJsonPath}`
       }
     }
   }
-  const projectId = randomUUID14();
-  const mcpConfig = {
-    mcpServers: {
-      papi: {
-        command: "npx",
-        args: ["-y", "@papi-ai/server"],
-        env: {
-          PAPI_PROJECT_DIR: projectRoot,
-          PAPI_ADAPTER: "pg",
-          DATABASE_URL: "<YOUR_DATABASE_URL>",
-          PAPI_PROJECT_ID: projectId
+  const existingApiKey = process.env.PAPI_DATA_API_KEY;
+  const existingProjectId = process.env.PAPI_PROJECT_ID;
+  const isProxyUser = Boolean(existingApiKey) || config2.adapterType === "proxy";
+  const isDatabaseUser = Boolean(process.env.DATABASE_URL) || config2.adapterType === "pg";
+  if (isProxyUser && existingApiKey && existingProjectId) {
+    const mcpConfig = {
+      mcpServers: {
+        papi: {
+          command: "npx",
+          args: ["-y", "@papi-ai/server"],
+          env: {
+            PAPI_PROJECT_ID: existingProjectId,
+            PAPI_DATA_API_KEY: existingApiKey
+          }
         }
       }
-    }
-  };
-  await writeFile4(mcpJsonPath, JSON.stringify(mcpConfig, null, 2) + "\n", "utf-8");
-  await ensureGitignoreEntry(projectRoot, ".mcp.json");
+    };
+    await writeFile4(mcpJsonPath, JSON.stringify(mcpConfig, null, 2) + "\n", "utf-8");
+    await ensureGitignoreEntry(projectRoot, ".mcp.json");
+    return textResponse(
+      `# PAPI Initialised \u2014 ${projectName}
+
+**Config:** \`${mcpJsonPath}\`
+
+Your existing API key and project ID have been saved to .mcp.json.
+
+## Next Steps
+
+1. **Restart your MCP client** to pick up the new config.
+2. **Run \`setup\`** \u2014 this scaffolds your project with a Product Brief and CLAUDE.md.
+`
+    );
+  }
+  if (isDatabaseUser) {
+    const projectId = randomUUID14();
+    const mcpConfig = {
+      mcpServers: {
+        papi: {
+          command: "npx",
+          args: ["-y", "@papi-ai/server"],
+          env: {
+            PAPI_PROJECT_DIR: projectRoot,
+            PAPI_ADAPTER: "pg",
+            DATABASE_URL: process.env.DATABASE_URL || "<YOUR_DATABASE_URL>",
+            PAPI_PROJECT_ID: projectId
+          }
+        }
+      }
+    };
+    await writeFile4(mcpJsonPath, JSON.stringify(mcpConfig, null, 2) + "\n", "utf-8");
+    await ensureGitignoreEntry(projectRoot, ".mcp.json");
+    const output2 = [
+      `# PAPI Initialised \u2014 ${projectName}`,
+      "",
+      `**Project ID:** \`${projectId}\``,
+      `**Config:** \`${mcpJsonPath}\``,
+      "",
+      "## Next Steps",
+      "",
+      ...process.env.DATABASE_URL ? ["1. **Restart your MCP client** to pick up the new config."] : ["1. **Set your DATABASE_URL** \u2014 replace `<YOUR_DATABASE_URL>` in `.mcp.json` with your Supabase connection string."],
+      "2. **Run `setup`** \u2014 this scaffolds your project with a Product Brief, Active Decisions, and CLAUDE.md."
+    ].join("\n");
+    return textResponse(output2);
+  }
   const output = [
-    `# PAPI Initialised \u2014 ${projectName}`,
+    `# PAPI \u2014 Account Required`,
+    "",
+    `PAPI needs an account to store your project data.`,
     "",
-    `**Project ID:** \`${projectId}\``,
-    `**Project directory:** \`${projectRoot}\`${usingCwdDefault ? " *(detected from current directory)*" : ""}`,
-    `**Config:** \`${mcpJsonPath}\``,
+    "## Get Started in 3 Steps",
     "",
-    "## Next Steps",
+    "1. **Sign up** at https://getpapi.ai/login",
+    "2. **Complete the onboarding wizard** \u2014 it generates your `.mcp.json` config with your API key and project ID",
+    "3. **Download the config**, place it in your project root, and restart your MCP client",
     "",
-    "1. **Set your DATABASE_URL** \u2014 replace `<YOUR_DATABASE_URL>` in `.mcp.json` with the connection string provided to you.",
-    "2. **Restart Claude Code** \u2014 it will detect the new MCP server on restart.",
-    "3. **Run `setup`** \u2014 this scaffolds your project with a Product Brief, Active Decisions, and CLAUDE.md.",
+    "The onboarding wizard generates everything you need \u2014 no manual configuration required.",
     "",
-    "> `.mcp.json` uses `npx @papi-ai/server` \u2014 no local paths to maintain. See `docs/install-guide.md` for multi-client configs."
+    `> Already have an account? Make sure both \`PAPI_PROJECT_ID\` and \`PAPI_DATA_API_KEY\` are set in your .mcp.json.`
   ].join("\n");
   return textResponse(output);
 }
@@ -19536,15 +19710,15 @@ function formatOrientSummary(health, buildInfo, hierarchy, latestTag, projectRoo
 async function getHierarchyPosition(adapter2) {
   try {
     const [horizons, stages, phases, allTasks] = await Promise.all([
-      adapter2.readHorizons(),
-      adapter2.readStages(),
+      adapter2.readHorizons?.() ?? [],
+      adapter2.readStages?.() ?? [],
       adapter2.readPhases(),
       adapter2.queryBoard()
     ]);
     if (horizons.length === 0) return void 0;
-    const activeHorizon = horizons.find((h) => h.status === "Active") || horizons[0];
+    const activeHorizon = horizons.find((h) => h.status === "active") || horizons[0];
     const activeStages = stages.filter((s) => s.horizonId === activeHorizon.id);
-    const activeStage = activeStages.find((s) => s.status === "Active") || activeStages[0];
+    const activeStage = activeStages.find((s) => s.status === "active") || activeStages[0];
     if (!activeStage) return void 0;
     const stagePhases = phases.filter((p) => p.stageId === activeStage.id);
     const activePhases = stagePhases.filter((p) => p.status === "In Progress");
@@ -19814,6 +19988,9 @@ async function handleHierarchyUpdate(adapter2, args) {
         const available = phases.map((p) => p.label).join(", ");
         return errorResponse(`Phase "${name}" not found. Available phases: ${available || "none"}`);
       }
+      if (!status) {
+        return errorResponse("status is required for phase updates.");
+      }
       if (phase.status === status) {
         return textResponse(`Phase "${phase.label}" is already "${status}". No change made.`);
       }
@@ -19867,6 +20044,9 @@ async function handleHierarchyUpdate(adapter2, args) {
       const available = horizons.map((h) => h.label).join(", ");
       return errorResponse(`Horizon "${name}" not found. Available horizons: ${available || "none"}`);
     }
+    if (!status) {
+      return errorResponse("status is required for horizon updates.");
+    }
     if (horizon.status === status) {
       return textResponse(`Horizon "${horizon.label}" is already "${status}". No change made.`);
     }
@@ -19930,8 +20110,8 @@ async function assembleZoomOutContext(adapter2, cycleNumber, projectRoot) {
   let hierarchyText = "";
   try {
     const [horizons, stages, phases] = await Promise.all([
-      adapter2.readHorizons(),
-      adapter2.readStages(),
+      adapter2.readHorizons?.() ?? [],
+      adapter2.readStages?.() ?? [],
       adapter2.readPhases()
     ]);
     if (horizons.length > 0) {
@@ -20579,8 +20759,8 @@ function createServer(adapter2, config2) {
     { capabilities: { tools: {}, prompts: {} } }
   );
   const __filename = fileURLToPath(import.meta.url);
-  const __dirname = dirname(__filename);
-  const skillsDir = join10(__dirname, "..", "skills");
+  const __dirname2 = dirname(__filename);
+  const skillsDir = join10(__dirname2, "..", "skills");
   function parseSkillFrontmatter(content) {
     const match = content.match(/^---\n([\s\S]*?)\n---/);
     if (!match) return null;
@@ -20681,7 +20861,7 @@ function createServer(adapter2, config2) {
         return {
           content: [{
             type: "text",
-            text: `No project found for PAPI_PROJECT_ID \`${config2.projectId}\`. Run \`setup\` first to initialise your project.`
+            text: `No project found for PAPI_PROJECT_ID \`${process.env.PAPI_PROJECT_ID ?? "(not set)"}\`. Run \`setup\` first to initialise your project.`
           }]
         };
       }
@@ -20815,15 +20995,88 @@ function createServer(adapter2, config2) {
 }
 
 // src/index.ts
+var __dirname = dirname2(fileURLToPath2(import.meta.url));
+var pkgVersion = "unknown";
+try {
+  const pkg = JSON.parse(readFileSync4(join11(__dirname, "..", "package.json"), "utf-8"));
+  pkgVersion = pkg.version;
+} catch {
+}
+var cliArgs = process.argv.slice(2);
+if (cliArgs.includes("--help") || cliArgs.includes("-h")) {
+  console.log(`papi-server v${pkgVersion} \u2014 PAPI MCP server
+
+Usage: npx @papi-ai/server [options]
+
+Options:
+  --help, -h       Show this help message
+  --version, -v    Show version number
+  --project <dir>  Set the project directory
+
+Getting started:
+  1. Sign up at https://getpapi.ai/login
+  2. Complete the onboarding wizard to get your API key
+  3. Add the generated config to your MCP client
+  4. Say "run setup" in your AI tool
+
+Docs: https://getpapi.ai/docs
+`);
+  process.exit(0);
+}
+if (cliArgs.includes("--version") || cliArgs.includes("-v")) {
+  console.log(pkgVersion);
+  process.exit(0);
+}
 process.on("unhandledRejection", (err) => {
   console.error("[papi] unhandledRejection (swallowed):", err instanceof Error ? err.message : err);
 });
 var config = loadConfig();
-var adapter = await createAdapter({
-  adapterType: config.adapterType,
-  papiDir: config.papiDir,
-  papiEndpoint: config.papiEndpoint
-});
-var server = createServer(adapter, config);
+var adapter;
+var setupError;
+try {
+  adapter = await createAdapter({
+    adapterType: config.adapterType,
+    papiDir: config.papiDir,
+    papiEndpoint: config.papiEndpoint
+  });
+} catch (err) {
+  setupError = err instanceof Error ? err.message : String(err);
+  process.stderr.write(`[papi] Startup error: ${setupError}
+`);
+}
+var server;
+if (adapter && !setupError) {
+  server = createServer(adapter, config);
+} else {
+  server = new Server2(
+    { name: "papi", version: pkgVersion },
+    { capabilities: { tools: {} } }
+  );
+  const errorMessage = setupError || "Unknown startup error";
+  server.setRequestHandler(ListToolsRequestSchema2, async () => ({
+    tools: [{
+      name: "setup",
+      description: "PAPI is not connected \u2014 run this tool for setup instructions.",
+      inputSchema: { type: "object", properties: {}, required: [] }
+    }]
+  }));
+  server.setRequestHandler(CallToolRequestSchema2, async () => ({
+    content: [{
+      type: "text",
+      text: `# PAPI Connection Error
+
+${errorMessage}
+
+## Quick Fix
+
+If you haven't set up PAPI yet:
+1. Go to https://getpapi.ai/login and sign up
+2. Complete the onboarding wizard \u2014 it generates your config
+3. Copy the config to your project and restart your AI tool
+
+If you already have an account, check that both **PAPI_PROJECT_ID** and **PAPI_DATA_API_KEY** are set in your .mcp.json env config.`
+    }]
+  }));
+}
 var transport = new StdioServerTransport();
 await server.connect(transport);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@papi-ai/server",
-  "version": "0.6.2",
+  "version": "0.7.0",
   "description": "PAPI MCP server — AI-powered sprint planning, build execution, and strategy review for software projects",
   "license": "Elastic-2.0",
   "type": "module",