@papi-ai/server 0.7.26 → 0.7.27

package/dist/index.js

@@ -15950,13 +15950,23 @@ ${result.userMessage}
 }
 
 // src/services/strategy.ts
-init_dist2();
 import { randomUUID as randomUUID8, createHash as createHash2 } from "crypto";
 import { execFileSync as execFileSync2 } from "child_process";
 import { existsSync, readdirSync, statSync } from "fs";
 import { join as join2 } from "path";
 import { homedir } from "os";
 
+// src/lib/hosted-mode.ts
+function isHostedTransport() {
+  return Boolean(process.env.PORT || process.env.PAPI_HTTP_PORT);
+}
+function hasLocalWorkspace() {
+  return !isHostedTransport();
+}
+
+// src/services/strategy.ts
+init_dist2();
+
 // src/lib/value-report.ts
 var MIN_SNAPSHOTS = 5;
 var MAX_SNAPSHOTS = 10;
@@ -16433,7 +16443,7 @@ ${lines.join("\n")}`;
   let unregisteredDocsText;
   try {
     const docsDir = join2(projectRoot, "docs");
-    if (existsSync(docsDir)) {
+    if (hasLocalWorkspace() && existsSync(docsDir)) {
       const registeredPaths = new Set(
         (registeredDocs ?? []).map((d) => d.path).filter(Boolean)
       );
@@ -18786,6 +18796,56 @@ Run \`orient\` at the start of every session to get cycle state, in-progress tas
 - After build_execute completes: run \`review_submit\` with the verdict before presenting for human review
 `;
 
+// src/lib/files-to-write.ts
+function sanitiseProjectPath(path7) {
+  if (!path7 || typeof path7 !== "string") {
+    throw new Error("files_to_write: path must be a non-empty string");
+  }
+  if (path7.startsWith("/") || /^[A-Za-z]:[\\/]/.test(path7)) {
+    throw new Error(`files_to_write: absolute path rejected: ${path7}`);
+  }
+  const segments = path7.split(/[\\/]/);
+  if (segments.some((s) => s === "..")) {
+    throw new Error(`files_to_write: path traversal rejected: ${path7}`);
+  }
+  return segments.filter((s) => s.length > 0).join("/");
+}
+var FileWriteCollector = class {
+  entries = [];
+  add(entry) {
+    this.entries.push({ ...entry, path: sanitiseProjectPath(entry.path) });
+  }
+  isEmpty() {
+    return this.entries.length === 0;
+  }
+  list() {
+    return this.entries;
+  }
+};
+function formatFilesToWriteSection(collector) {
+  if (collector.isEmpty()) return "";
+  const json = JSON.stringify(collector.list(), null, 2);
+  return [
+    "",
+    "---",
+    "",
+    "**SCAFFOLDING FILES \u2014 WRITE THESE LOCALLY**",
+    "",
+    "This MCP connection is remote \u2014 the server cannot write files to your project directory.",
+    "Use your Write tool to materialise each entry below into the user's project root (your current working directory).",
+    "",
+    "```json files_to_write",
+    json,
+    "```",
+    "",
+    "Apply each entry in order. Semantics:",
+    '- `mode: "create"` \u2014 create the file with `content`. If `skip_if_exists: true`, skip when the file already exists.',
+    '- `mode: "overwrite"` \u2014 replace the file fully with `content`.',
+    '- `mode: "append"` \u2014 append `content` to the existing file (create it first if missing).',
+    ""
+  ].join("\n");
+}
+
 // src/services/setup.ts
 var FILE_TEMPLATES = {
   "PLANNING_LOG.md": PLANNING_LOG_TEMPLATE,
@@ -18809,7 +18869,7 @@ function substitute(template, vars) {
   }
   return result;
 }
-async function scaffoldPapiDir(adapter2, config2, input) {
+async function scaffoldPapiDir(adapter2, config2, input, collector) {
   const isPg = config2.adapterType === "pg" || config2.adapterType === "proxy";
   const vars = {
     project_name: input.projectName,
@@ -18839,31 +18899,37 @@ async function scaffoldPapiDir(adapter2, config2, input) {
     } catch {
     }
   }
-  if (config2.adapterType === "proxy") {
-    return true;
+  const useCollector = config2.adapterType === "proxy";
+  const docsRel = "docs";
+  const commandsRel = ".claude/commands";
+  const commandsDir = useCollector ? commandsRel : join5(config2.projectRoot, ".claude", "commands");
+  const docsDir = useCollector ? docsRel : join5(config2.projectRoot, "docs");
+  if (!useCollector) {
+    await mkdir(commandsDir, { recursive: true });
+    await mkdir(docsDir, { recursive: true });
   }
-  const commandsDir = join5(config2.projectRoot, ".claude", "commands");
-  const docsDir = join5(config2.projectRoot, "docs");
-  await mkdir(commandsDir, { recursive: true });
-  await mkdir(docsDir, { recursive: true });
-  const claudeMdPath = join5(config2.projectRoot, "CLAUDE.md");
+  const claudeMdPath = useCollector ? "CLAUDE.md" : join5(config2.projectRoot, "CLAUDE.md");
   let claudeMdExists = false;
-  try {
-    await access2(claudeMdPath);
-    claudeMdExists = true;
-  } catch {
+  if (!useCollector) {
+    try {
+      await access2(claudeMdPath);
+      claudeMdExists = true;
+    } catch {
+    }
   }
-  const docsIndexPath = join5(docsDir, "INDEX.md");
+  const docsIndexPath = useCollector ? `${docsRel}/INDEX.md` : join5(docsDir, "INDEX.md");
   let docsIndexExists = false;
-  try {
-    await access2(docsIndexPath);
-    docsIndexExists = true;
-  } catch {
+  if (!useCollector) {
+    try {
+      await access2(docsIndexPath);
+      docsIndexExists = true;
+    } catch {
+    }
   }
   const scaffoldFiles = {
-    [join5(commandsDir, "papi-audit.md")]: PAPI_AUDIT_COMMAND_TEMPLATE,
-    [join5(commandsDir, "test.md")]: TEST_COMMAND_TEMPLATE,
-    [join5(docsDir, "README.md")]: substitute(DOCS_README_TEMPLATE, vars)
+    [useCollector ? `${commandsRel}/papi-audit.md` : join5(commandsDir, "papi-audit.md")]: PAPI_AUDIT_COMMAND_TEMPLATE,
+    [useCollector ? `${commandsRel}/test.md` : join5(commandsDir, "test.md")]: TEST_COMMAND_TEMPLATE,
+    [useCollector ? `${docsRel}/README.md` : join5(docsDir, "README.md")]: substitute(DOCS_README_TEMPLATE, vars)
   };
   if (!docsIndexExists) {
     scaffoldFiles[docsIndexPath] = substitute(DOCS_INDEX_TEMPLATE, vars);
@@ -18880,29 +18946,42 @@ async function scaffoldPapiDir(adapter2, config2, input) {
     } catch {
     }
   }
-  for (const [dest, content] of Object.entries(planBundleInstall(config2.projectRoot, input.projectName, { skipExisting: true }))) {
-    await mkdir(dirname2(dest), { recursive: true });
+  const bundleRoot = useCollector ? "" : config2.projectRoot;
+  for (const [dest, content] of Object.entries(planBundleInstall(bundleRoot, input.projectName, { skipExisting: true }))) {
+    if (!useCollector) {
+      await mkdir(dirname2(dest), { recursive: true });
+    }
     scaffoldFiles[dest] = content;
   }
-  const cursorDir = join5(config2.projectRoot, ".cursor");
-  let cursorDetected = false;
-  try {
-    await access2(cursorDir);
-    cursorDetected = true;
-  } catch {
-  }
-  if (cursorDetected) {
-    const cursorRulesDir = join5(cursorDir, "rules");
-    const cursorRulesPath = join5(cursorRulesDir, "papi.mdc");
-    await mkdir(cursorRulesDir, { recursive: true });
+  if (useCollector) {
+    scaffoldFiles[".cursor/rules/papi.mdc"] = substitute(CURSOR_RULES_TEMPLATE, vars);
+  } else {
+    const cursorDir = join5(config2.projectRoot, ".cursor");
+    let cursorDetected = false;
     try {
-      await access2(cursorRulesPath);
+      await access2(cursorDir);
+      cursorDetected = true;
     } catch {
-      scaffoldFiles[cursorRulesPath] = substitute(CURSOR_RULES_TEMPLATE, vars);
+    }
+    if (cursorDetected) {
+      const cursorRulesDir = join5(cursorDir, "rules");
+      const cursorRulesPath = join5(cursorRulesDir, "papi.mdc");
+      await mkdir(cursorRulesDir, { recursive: true });
+      try {
+        await access2(cursorRulesPath);
+      } catch {
+        scaffoldFiles[cursorRulesPath] = substitute(CURSOR_RULES_TEMPLATE, vars);
+      }
     }
   }
-  for (const [filepath, content] of Object.entries(scaffoldFiles)) {
-    await writeFile2(filepath, content, "utf-8");
+  if (useCollector) {
+    for (const [relPath, content] of Object.entries(scaffoldFiles)) {
+      collector.add({ path: relPath, content, mode: "create", skip_if_exists: true });
+    }
+  } else {
+    for (const [filepath, content] of Object.entries(scaffoldFiles)) {
+      await writeFile2(filepath, content, "utf-8");
+    }
   }
   if (!isPg) {
     await adapter2.writePhases([{
@@ -18914,7 +18993,16 @@ async function scaffoldPapiDir(adapter2, config2, input) {
       order: 0
     }]);
   }
-  await ensurePapiPermission(config2.projectRoot);
+  if (useCollector) {
+    collector.add({
+      path: ".claude/settings.json",
+      content: JSON.stringify({ permissions: { allow: [PAPI_PERMISSION] } }, null, 2) + "\n",
+      mode: "create",
+      skip_if_exists: true
+    });
+  } else {
+    await ensurePapiPermission(config2.projectRoot);
+  }
   return true;
 }
 var PAPI_PERMISSION = "mcp__papi__*";
@@ -18943,7 +19031,7 @@ async function ensurePapiPermission(projectRoot) {
   } catch {
   }
 }
-async function applySetupOutputs(adapter2, config2, input, briefText, adSeedText, conventionsText) {
+async function applySetupOutputs(adapter2, config2, input, collector, briefText, adSeedText, conventionsText) {
   const warnings = [];
   await adapter2.updateProductBrief(briefText);
   const briefPhases = parsePhases(briefText);
@@ -19006,12 +19094,20 @@ async function applySetupOutputs(adapter2, config2, input, briefText, adSeedText
       }
     }
   }
-  if (conventionsText?.trim() && config2.adapterType !== "proxy") {
-    try {
-      const claudeMdPath = join5(config2.projectRoot, "CLAUDE.md");
-      const existing = await readFile4(claudeMdPath, "utf-8");
-      await writeFile2(claudeMdPath, existing + "\n" + conventionsText.trim() + "\n", "utf-8");
-    } catch {
+  if (conventionsText?.trim()) {
+    if (config2.adapterType === "proxy") {
+      collector.add({
+        path: "CLAUDE.md",
+        content: "\n" + conventionsText.trim() + "\n",
+        mode: "append"
+      });
+    } else {
+      try {
+        const claudeMdPath = join5(config2.projectRoot, "CLAUDE.md");
+        const existing = await readFile4(claudeMdPath, "utf-8");
+        await writeFile2(claudeMdPath, existing + "\n" + conventionsText.trim() + "\n", "utf-8");
+      } catch {
+      }
     }
   }
   return { seededAds, warnings };
@@ -19186,7 +19282,8 @@ function formatCodebaseSummary(scan, sourceContents) {
   return parts.join("\n");
 }
 async function prepareSetup(adapter2, config2, input) {
-  const createdProject = await scaffoldPapiDir(adapter2, config2, input);
+  const prepareCollector = new FileWriteCollector();
+  const createdProject = await scaffoldPapiDir(adapter2, config2, input, prepareCollector);
   let existingBrief;
   try {
     existingBrief = await adapter2.readProductBrief();
@@ -19291,11 +19388,13 @@ async function prepareSetup(adapter2, config2, input) {
     autoDetected: autoDetected && detectedCodebaseType !== "new_project",
     briefAlreadyExists: effectiveBriefAlreadyExists,
     briefWillRegenerate,
-    briefRegenReason
+    briefRegenReason,
+    filesToWrite: prepareCollector.isEmpty() ? void 0 : prepareCollector
   };
 }
 async function applySetup(adapter2, config2, input, briefText, adSeedText, conventionsText, initialTasksText) {
-  const createdProject = await scaffoldPapiDir(adapter2, config2, input);
+  const collector = new FileWriteCollector();
+  const createdProject = await scaffoldPapiDir(adapter2, config2, input, collector);
   const TEMPLATE_MARKER = "*Describe your project's core value proposition here.*";
   let effectiveBriefText = briefText;
   let briefRegenerated = false;
@@ -19320,7 +19419,7 @@ async function applySetup(adapter2, config2, input, briefText, adSeedText, conve
     } catch {
     }
   }
-  const { seededAds, warnings } = await applySetupOutputs(adapter2, config2, input, effectiveBriefText, adSeedText, conventionsText);
+  const { seededAds, warnings } = await applySetupOutputs(adapter2, config2, input, collector, effectiveBriefText, adSeedText, conventionsText);
   let createdTasks = 0;
   let tasksSkipped = 0;
   if (initialTasksText?.trim()) {
@@ -19367,29 +19466,33 @@ async function applySetup(adapter2, config2, input, briefText, adSeedText, conve
       if (msg.startsWith("100% overlap")) throw err;
     }
   }
-  if (config2.adapterType !== "proxy") {
-    try {
-      const claudeMdPath = join5(config2.projectRoot, "CLAUDE.md");
-      const existing = await readFile4(claudeMdPath, "utf-8");
-      if (!existing.includes("Dogfood Logging")) {
-        const dogfoodSection = [
-          "",
-          "## Dogfood Logging",
-          "",
-          "After each `release`, append a dogfood entry capturing observations from the cycle.",
-          "Call the adapter method with structured entries for each observation:",
-          "",
-          "- **friction** \u2014 workflow pain points, confusing flows, things that broke or slowed you down",
-          "- **methodology** \u2014 what worked or didn't in the plan/build/review cycle",
-          "- **signal** \u2014 indicators of product-market fit, user value, or growth potential",
-          "- **commercial** \u2014 cost, pricing, or business model observations",
-          "",
-          "This is autonomous plumbing \u2014 log observations after release without asking.",
-          ""
-        ].join("\n");
-        await writeFile2(claudeMdPath, existing + dogfoodSection, "utf-8");
+  {
+    const dogfoodSection = [
+      "",
+      "## Dogfood Logging",
+      "",
+      "After each `release`, append a dogfood entry capturing observations from the cycle.",
+      "Call the adapter method with structured entries for each observation:",
+      "",
+      "- **friction** \u2014 workflow pain points, confusing flows, things that broke or slowed you down",
+      "- **methodology** \u2014 what worked or didn't in the plan/build/review cycle",
+      "- **signal** \u2014 indicators of product-market fit, user value, or growth potential",
+      "- **commercial** \u2014 cost, pricing, or business model observations",
+      "",
+      "This is autonomous plumbing \u2014 log observations after release without asking.",
+      ""
+    ].join("\n");
+    if (config2.adapterType === "proxy") {
+      collector.add({ path: "CLAUDE.md", content: dogfoodSection, mode: "append" });
+    } else {
+      try {
+        const claudeMdPath = join5(config2.projectRoot, "CLAUDE.md");
+        const existing = await readFile4(claudeMdPath, "utf-8");
+        if (!existing.includes("Dogfood Logging")) {
+          await writeFile2(claudeMdPath, existing + dogfoodSection, "utf-8");
+        }
+      } catch {
       }
-    } catch {
     }
   }
   if (adapter2.writeDogfoodEntries) {
@@ -19412,12 +19515,26 @@ async function applySetup(adapter2, config2, input, briefText, adSeedText, conve
     });
   } catch {
   }
-  const gitignoreNote = config2.adapterType === "proxy" ? void 0 : await ensureMcpJsonGitignored(config2.projectRoot);
+  let gitignoreNote;
+  if (config2.adapterType === "proxy") {
+    collector.add({
+      path: ".gitignore",
+      content: "\n# PAPI: may contain credentials, do not commit\n.mcp.json\n",
+      mode: "append"
+    });
+    gitignoreNote = "Added `.mcp.json` to `.gitignore` \u2014 may contain credentials, do not commit.";
+  } else {
+    gitignoreNote = await ensureMcpJsonGitignored(config2.projectRoot);
+  }
   let cursorScaffolded = false;
-  try {
-    await access2(join5(config2.projectRoot, ".cursor", "rules", "papi.mdc"));
+  if (config2.adapterType === "proxy") {
     cursorScaffolded = true;
-  } catch {
+  } else {
+    try {
+      await access2(join5(config2.projectRoot, ".cursor", "rules", "papi.mdc"));
+      cursorScaffolded = true;
+    } catch {
+    }
   }
   return {
     createdProject,
@@ -19428,7 +19545,8 @@ async function applySetup(adapter2, config2, input, briefText, adSeedText, conve
     briefRegenerated: briefRegenerated || void 0,
     cursorScaffolded,
     gitignoreNote,
-    warnings: warnings.length > 0 ? warnings : void 0
+    warnings: warnings.length > 0 ? warnings : void 0,
+    filesToWrite: collector.isEmpty() ? void 0 : collector
   };
 }
 async function ensureMcpJsonGitignored(projectRoot) {
@@ -19580,6 +19698,7 @@ ${[created, skipped].filter(Boolean).join(", ")}.`;
 
 \u26A0\uFE0F **Setup warnings (non-blocking):**
 ${result.warnings.map((w) => `- ${w}`).join("\n")}` : "";
+  const filesToWriteSection = result.filesToWrite ? formatFilesToWriteSection(result.filesToWrite) : "";
   return textResponse(
     `${prefix}Product Brief generated and saved.${briefRegenNote}${adNote}${taskNote}${constraintsHint}${editorNote}${gitignoreNote}${warningsNote}
 
@@ -19589,7 +19708,7 @@ Tip: See \`docs/templates/example-project-brief.md\` for an example of a well-wr
 
 **Telemetry notice:** PAPI collects anonymous usage data (tool name, duration, project ID) to improve the product. No code, file contents, or personal data is collected. To opt out, add \`"PAPI_TELEMETRY": "off"\` to the \`env\` block in your \`.mcp.json\`.
 
-Next step: run \`plan\` to start your first planning cycle.`
+Next step: run \`plan\` to start your first planning cycle.${filesToWriteSection}`
   );
 }
 async function handleSetup(adapter2, config2, args) {
@@ -19750,7 +19869,9 @@ ${result.initialTasksPrompt.user}
           result.codebaseSummary
         );
       }
-      return textResponse(sections.filter(Boolean).join("\n"));
+      const responseText = sections.filter(Boolean).join("\n");
+      const filesToWriteSection = result.filesToWrite ? formatFilesToWriteSection(result.filesToWrite) : "";
+      return textResponse(responseText + filesToWriteSection);
     }
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
@@ -19773,11 +19894,11 @@ ${result.initialTasksPrompt.user}
 init_dist2();
 
 // src/services/build.ts
-init_git();
-init_git();
 import { randomUUID as randomUUID9 } from "crypto";
 import { readdirSync as readdirSync4, existsSync as existsSync4, readFileSync as readFileSync2, writeFileSync, unlinkSync, mkdirSync } from "fs";
 import { join as join6 } from "path";
+init_git();
+init_git();
 var buildStartTimes = /* @__PURE__ */ new Map();
 var taskBranchMap = /* @__PURE__ */ new Map();
 var taskStartShaMap = /* @__PURE__ */ new Map();
@@ -20191,20 +20312,37 @@ async function startBuild(adapter2, config2, taskId, options = {}) {
     phaseChanges = await propagatePhaseStatus(adapter2);
   } catch {
   }
+  const collector = new FileWriteCollector();
   try {
-    writeActiveTaskScope(config2.projectRoot, taskId, task.buildHandoff?.filesLikelyTouched);
+    writeActiveTaskScope(
+      config2.projectRoot,
+      taskId,
+      task.buildHandoff?.filesLikelyTouched,
+      config2.adapterType,
+      collector
+    );
   } catch {
   }
-  return { task, branchLines, phaseChanges };
+  return {
+    task,
+    branchLines,
+    phaseChanges,
+    filesToWrite: collector.isEmpty() ? void 0 : collector
+  };
 }
-function writeActiveTaskScope(projectRoot, taskId, filesLikelyTouched) {
+function writeActiveTaskScope(projectRoot, taskId, filesLikelyTouched, adapterType, collector) {
+  const lines = [taskId, ...filesLikelyTouched ?? []];
+  const content = lines.join("\n") + "\n";
+  if (adapterType === "proxy") {
+    collector.add({ path: ".papi/active-task-scope.txt", content, mode: "overwrite" });
+    return;
+  }
   const papiDir = join6(projectRoot, ".papi");
   if (!existsSync4(papiDir)) {
     mkdirSync(papiDir, { recursive: true });
   }
   const scopePath = join6(papiDir, "active-task-scope.txt");
-  const lines = [taskId, ...filesLikelyTouched ?? []];
-  writeFileSync(scopePath, lines.join("\n") + "\n", "utf-8");
+  writeFileSync(scopePath, content, "utf-8");
 }
 function clearActiveTaskScope(projectRoot) {
   const scopePath = join6(projectRoot, ".papi", "active-task-scope.txt");
@@ -20527,7 +20665,7 @@ async function completeBuild(adapter2, config2, taskId, input, options = {}) {
   }
   let docWarning;
   try {
-    if (adapter2.searchDocs) {
+    if (adapter2.searchDocs && hasLocalWorkspace()) {
       const docsDir = join6(config2.projectRoot, "docs");
       if (existsSync4(docsDir)) {
         const scanDir = (dir, depth = 0) => {
@@ -21037,7 +21175,8 @@ ${entries}`;
     }
     const moduleInstructions = getModuleInstructions(result.task.module);
     const moduleContext = await getModuleContext(adapter2, result.task);
-    return textResponse(header + serializeBuildHandoff(result.task.buildHandoff) + adSection + moduleInstructions + moduleContext + dogfoodSection + verificationNote + chainInstruction + phaseNote);
+    const filesToWriteSection = result.filesToWrite ? formatFilesToWriteSection(result.filesToWrite) : "";
+    return textResponse(header + serializeBuildHandoff(result.task.buildHandoff) + adSection + moduleInstructions + moduleContext + dogfoodSection + verificationNote + chainInstruction + phaseNote + filesToWriteSection);
   } catch (err) {
     if (isNoHandoffError(err)) {
       const lines = [
@@ -22186,6 +22325,7 @@ init_git();
 import { readFileSync as readFileSync3 } from "fs";
 import { join as join7 } from "path";
 function loadDocsIndex(projectRoot) {
+  if (!hasLocalWorkspace()) return "";
   try {
     const indexPath = join7(projectRoot, "docs", "INDEX.md");
     const raw = readFileSync3(indexPath, "utf8");
@@ -22924,7 +23064,15 @@ function generateChangelogSection(version, commits) {
 ${commitList}
 `;
 }
-async function writeChangelogSection(changelogPath, section, version) {
+async function writeChangelogSection(changelogPath, section, version, adapterType, collector) {
+  if (adapterType === "proxy") {
+    collector.add({
+      path: "CHANGELOG.md",
+      content: "\n" + section + "\n",
+      mode: "append"
+    });
+    return;
+  }
   let existing = "";
   try {
     existing = await readFile5(changelogPath, "utf-8");
@@ -23028,6 +23176,7 @@ async function resolveCycleToClose(adapter2, version) {
   return inferCycleFromVersion(version);
 }
 async function createRelease(config2, branch, version, adapter2, cycleNum, options) {
+  const collector = new FileWriteCollector();
   if (!isGitAvailable()) {
     throw new Error("git is not available.");
   }
@@ -23165,11 +23314,15 @@ To override, pass force=true (emits a telemetry warning).`
   const changelogPath = join9(config2.projectRoot, "CHANGELOG.md");
   if (!latestTag) {
     const initialContent = INITIAL_RELEASE_NOTES.replace("v0.1.0-alpha", version);
-    await writeFile3(changelogPath, initialContent, "utf-8");
+    if (config2.adapterType === "proxy") {
+      collector.add({ path: "CHANGELOG.md", content: initialContent, mode: "create", skip_if_exists: true });
+    } else {
+      await writeFile3(changelogPath, initialContent, "utf-8");
+    }
   } else {
     const commits = getCommitsSinceTag(config2.projectRoot, latestTag);
     const section = generateChangelogSection(version, commits);
-    await writeChangelogSection(changelogPath, section, version);
+    await writeChangelogSection(changelogPath, section, version, config2.adapterType, collector);
   }
   const commitResult = stageAllAndCommit(config2.projectRoot, `release: ${version}`);
   const commitNote = commitResult.committed ? `Committed CHANGELOG.md.` : `CHANGELOG.md: ${commitResult.message}`;
@@ -23196,7 +23349,8 @@ To override, pass force=true (emits a telemetry warning).`
     pushNotes,
     warnings: warnings.length > 0 ? warnings : void 0,
     ...groupedBranchMerges ? { groupedBranchMerges } : {},
-    cycleClosed: resolvedCycleNum
+    cycleClosed: resolvedCycleNum,
+    filesToWrite: collector.isEmpty() ? void 0 : collector
   };
 }
 
@@ -23323,7 +23477,8 @@ async function handleRelease(adapter2, config2, args) {
       }
     }
     lines.push("", `Next: cycle released! Run \`plan\` to start your next planning cycle.`);
-    return textResponse(lines.join("\n"));
+    const filesToWriteSection = result.filesToWrite ? formatFilesToWriteSection(result.filesToWrite) : "";
+    return textResponse(lines.join("\n") + filesToWriteSection);
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     const isKnownFriendly = /^(Release blocked|Working tree|gh CLI|Tag .* already exists|Branch .* not found|Cycle .* incomplete)/i.test(message);
@@ -24336,7 +24491,15 @@ async function tryAutoProvisionProject(opts) {
   }
   return { ok: true, projectId: body.project.id, projectName: body.project.name ?? opts.projectName };
 }
-async function ensureGitignoreEntry(projectRoot, entry) {
+async function ensureGitignoreEntry(projectRoot, entry, adapterType, collector) {
+  if (adapterType === "proxy") {
+    collector.add({
+      path: ".gitignore",
+      content: "\n" + entry + "\n",
+      mode: "append"
+    });
+    return;
+  }
   const gitignorePath = path5.join(projectRoot, ".gitignore");
   let content = "";
   try {
@@ -24350,6 +24513,13 @@ async function ensureGitignoreEntry(projectRoot, entry) {
   const separator = content.length > 0 && !content.endsWith("\n") ? "\n" : "";
   await writeFile4(gitignorePath, content + separator + entry + "\n", "utf-8");
 }
+async function writeMcpConfig(absPath, relPath, content, isProjectScoped, adapterType, collector) {
+  if (adapterType === "proxy" && isProjectScoped) {
+    collector.add({ path: relPath, content, mode: "overwrite" });
+    return;
+  }
+  await writeFile4(absPath, content, "utf-8");
+}
 async function handleInit(config2, args) {
   const projectRoot = config2.projectRoot;
   const force = args.force === true;
@@ -24363,6 +24533,19 @@ async function handleInit(config2, args) {
   }
   const agent = requestedAgent;
   const target = AGENT_TARGETS[agent];
+  if (config2.adapterType === "proxy" && !target.isProjectScoped) {
+    return errorResponse(
+      [
+        `Agent \`${agent}\` writes to a user-scoped config (${target.displayPath}) outside your project directory.`,
+        "This MCP connection is remote \u2014 the server cannot write outside the project root.",
+        "",
+        "Workarounds:",
+        "- Install the PAPI MCP server locally (`npx @papi-ai/server`) and run `init` over stdio.",
+        "- Manually copy the config block from the getpapi.ai install snippet for this agent."
+      ].join("\n")
+    );
+  }
+  const collector = new FileWriteCollector();
   const configFileAbsPath = target.isProjectScoped ? path5.join(projectRoot, target.configPath) : target.configPath.startsWith("~/") ? path5.join(process.env.HOME ?? "", target.configPath.slice(2)) : target.configPath;
   const mcpJsonPath = configFileAbsPath;
   let existingConfig = null;
@@ -24423,12 +24606,12 @@ Path: ${mcpJsonPath}`
       const wroteToShared = !target.isProjectScoped && !!existingConfig;
       if (wroteToShared) {
         const sep = existingConfig.endsWith("\n") ? "\n" : "\n\n";
-        await writeFile4(mcpJsonPath, existingConfig + sep + fileBody, "utf-8");
+        await writeMcpConfig(mcpJsonPath, target.configPath, existingConfig + sep + fileBody, target.isProjectScoped, config2.adapterType, collector);
       } else {
-        await writeFile4(mcpJsonPath, fileBody, "utf-8");
+        await writeMcpConfig(mcpJsonPath, target.configPath, fileBody, target.isProjectScoped, config2.adapterType, collector);
       }
       if (target.shouldGitignore) {
-        await ensureGitignoreEntry(projectRoot, target.configPath);
+        await ensureGitignoreEntry(projectRoot, target.configPath, config2.adapterType, collector);
       }
       const writeNote = wroteToShared ? `Appended to ${target.displayPath} (preserved your existing entries \u2014 review the file to confirm structure).` : `Your new project ID and existing connection token are saved to ${target.displayPath}.`;
       return textResponse(
@@ -24444,7 +24627,7 @@ ${writeNote}
 
 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.
-`
+` + formatFilesToWriteSection(collector)
       );
     }
     if (provisioned.reason === "project_limit_reached") {
@@ -24490,12 +24673,12 @@ ${writeNote}
     const wroteToShared = !target.isProjectScoped && !!existingConfig;
     if (wroteToShared) {
       const sep = existingConfig.endsWith("\n") ? "\n" : "\n\n";
-      await writeFile4(mcpJsonPath, existingConfig + sep + fileBody, "utf-8");
+      await writeMcpConfig(mcpJsonPath, target.configPath, existingConfig + sep + fileBody, target.isProjectScoped, config2.adapterType, collector);
     } else {
-      await writeFile4(mcpJsonPath, fileBody, "utf-8");
+      await writeMcpConfig(mcpJsonPath, target.configPath, fileBody, target.isProjectScoped, config2.adapterType, collector);
     }
     if (target.shouldGitignore) {
-      await ensureGitignoreEntry(projectRoot, target.configPath);
+      await ensureGitignoreEntry(projectRoot, target.configPath, config2.adapterType, collector);
     }
     const writeNote = wroteToShared ? `Appended to ${target.displayPath} (preserved your existing entries \u2014 review the file to confirm structure).` : `Your existing API key and project ID have been saved to ${target.displayPath}.`;
     return textResponse(
@@ -24510,7 +24693,7 @@ ${writeNote}
 
 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.
-`
+` + formatFilesToWriteSection(collector)
     );
   }
   if (isDatabaseUser) {
@@ -24524,12 +24707,12 @@ ${writeNote}
     const wroteToShared = !target.isProjectScoped && !!existingConfig;
     if (wroteToShared) {
       const sep = existingConfig.endsWith("\n") ? "\n" : "\n\n";
-      await writeFile4(mcpJsonPath, existingConfig + sep + fileBody, "utf-8");
+      await writeMcpConfig(mcpJsonPath, target.configPath, existingConfig + sep + fileBody, target.isProjectScoped, config2.adapterType, collector);
     } else {
-      await writeFile4(mcpJsonPath, fileBody, "utf-8");
+      await writeMcpConfig(mcpJsonPath, target.configPath, fileBody, target.isProjectScoped, config2.adapterType, collector);
     }
     if (target.shouldGitignore) {
-      await ensureGitignoreEntry(projectRoot, target.configPath);
+      await ensureGitignoreEntry(projectRoot, target.configPath, config2.adapterType, collector);
     }
     const output2 = [
       `# PAPI Initialised \u2014 ${projectName}`,
@@ -24544,7 +24727,7 @@ ${writeNote}
       ...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 \`${target.displayPath}\` with your Supabase **session pooler** connection string (port **5432**, not 6543 \u2014 the transaction pooler wedges on interrupted calls).`],
       "2. **Run `setup`** \u2014 this scaffolds your project with a Product Brief, Active Decisions, and CLAUDE.md."
     ].join("\n");
-    return textResponse(output2);
+    return textResponse(output2 + formatFilesToWriteSection(collector));
   }
   const output = [
     `# PAPI \u2014 Account Required`,
@@ -25272,6 +25455,11 @@ async function handleDocScan(adapter2, config2, args) {
   if (!adapter2.searchDocs) {
     return errorResponse("Doc registry not available on this adapter.");
   }
+  if (!hasLocalWorkspace()) {
+    return textResponse(
+      "doc_scan is unavailable on the hosted remote MCP transport \u2014 the server has no access to your local filesystem. Register docs explicitly via `doc_register` with the path/title/type you want indexed."
+    );
+  }
   const includePlans = args.include_plans ?? false;
   const registered = await adapter2.searchDocs({ limit: 500, status: "all" });
   const registeredPaths = new Set(registered.map((d) => d.path));
@@ -26070,7 +26258,7 @@ async function handleOrient(adapter2, config2, args = {}) {
         }
         let unregisteredDocsNote2 = "";
         try {
-          if (adapter2.searchDocs) {
+          if (adapter2.searchDocs && hasLocalWorkspace()) {
             const docsDir = join14(config2.projectRoot, "docs");
             const docsFiles = scanMdFiles(docsDir, config2.projectRoot);
             if (docsFiles.length > 0) {
@@ -26126,10 +26314,12 @@ ${versionDrift}` : "";
     const deliveryShapeNote = deliveryShapeOutcome.status === "fulfilled" ? deliveryShapeOutcome.value : "";
     const { reconciliationNote, unrecordedNote, unregisteredDocsNote, staleSkillsNote } = deepHousekeepingOutcome.status === "fulfilled" ? deepHousekeepingOutcome.value : { reconciliationNote: "", unrecordedNote: "", unregisteredDocsNote: "", staleSkillsNote: "" };
     let enrichmentNote = "";
+    const enrichmentCollector = new FileWriteCollector();
     try {
-      enrichmentNote = enrichClaudeMd(config2.projectRoot, healthResult.cycleNumber);
+      enrichmentNote = enrichClaudeMd(config2.projectRoot, healthResult.cycleNumber, config2.adapterType, enrichmentCollector);
     } catch {
     }
+    const enrichmentFilesSection = enrichmentCollector.isEmpty() ? "" : formatFilesToWriteSection(enrichmentCollector);
     let preBuildCheckNote = "";
     if (!cycleIsComplete) {
       const researchOrSpikeTasks = allTasks.filter((t) => {
@@ -26165,7 +26355,7 @@ ${section}`;
     tracker.mark("format-summary");
     const subAgents = await listAgents(config2.projectRoot);
     const deepHint = deepHousekeeping ? "" : "\n\n*Tip: pass `deep_housekeeping: true` to also check orphaned branches, unrecorded commits, unregistered docs, and stale skill forks.*";
-    return textResponse(projectBannerNote + formatOrientSummary(healthResult, buildInfo, hierarchy, latestTag, config2.projectRoot, environment, subAgents) + unblockNote + alertsNote + ttfvNote + reconciliationNote + unrecordedNote + unregisteredDocsNote + staleSkillsNote + researchSignalsNote + recsNote + pendingReviewNote + patternsNote + unactionedIssuesNote + skillProposalsNote + sessionGuidanceNote + versionNote + enrichmentNote + deliveryShapeNote + preBuildCheckNote + deepHint);
+    return textResponse(projectBannerNote + formatOrientSummary(healthResult, buildInfo, hierarchy, latestTag, config2.projectRoot, environment, subAgents) + unblockNote + alertsNote + ttfvNote + reconciliationNote + unrecordedNote + unregisteredDocsNote + staleSkillsNote + researchSignalsNote + recsNote + pendingReviewNote + patternsNote + unactionedIssuesNote + skillProposalsNote + sessionGuidanceNote + versionNote + enrichmentNote + deliveryShapeNote + preBuildCheckNote + deepHint + enrichmentFilesSection);
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     const isKnownFriendly = /^(Orient failed|Project not found|No project|Setup required)/i.test(message);
@@ -26182,7 +26372,20 @@ ${section}`;
     }));
   }
 }
-function enrichClaudeMd(projectRoot, cycleNumber) {
+function enrichClaudeMd(projectRoot, cycleNumber, adapterType, collector) {
+  if (adapterType === "proxy") {
+    const additions2 = [];
+    if (cycleNumber >= 6) additions2.push(CLAUDE_MD_TIER_1);
+    if (cycleNumber >= 21) additions2.push(CLAUDE_MD_TIER_2);
+    if (additions2.length === 0) return "";
+    collector.add({ path: "CLAUDE.md", content: additions2.join(""), mode: "append" });
+    const tierNames2 = [];
+    if (cycleNumber >= 6) tierNames2.push("Established (batch building, strategy reviews, AD lifecycle)");
+    if (cycleNumber >= 21) tierNames2.push("Mature (idea pipeline, doc registry, advanced patterns)");
+    return `
+
+\u{1F4DD} **CLAUDE.md enriched** \u2014 added ${tierNames2.join(" + ")} guidance for cycle ${cycleNumber}+ projects.`;
+  }
   const claudeMdPath = join14(projectRoot, "CLAUDE.md");
   if (!existsSync8(claudeMdPath)) return "";
   const content = readFileSync8(claudeMdPath, "utf-8");
@@ -26927,8 +27130,14 @@ async function runScopeBrief(adapter2, input) {
   const slug = input.taskId.replace(/[^a-z0-9-]/g, "-").toLowerCase();
   const relPath = `docs/scopes/${slug}.md`;
   const absPath = join15(input.projectRoot, relPath);
-  mkdirSync3(dirname3(absPath), { recursive: true });
-  writeFileSync4(absPath, addFrontmatter(docContent, task, input.cycleNumber), "utf-8");
+  const docBody = addFrontmatter(docContent, task, input.cycleNumber);
+  const collector = new FileWriteCollector();
+  if (input.adapterType === "proxy") {
+    collector.add({ path: relPath, content: docBody, mode: "overwrite" });
+  } else {
+    mkdirSync3(dirname3(absPath), { recursive: true });
+    writeFileSync4(absPath, docBody, "utf-8");
+  }
   const taskCount = countSubTasks(docContent);
   const summary = buildSummary(task, taskCount);
   if (!adapter2.registerDoc) {
@@ -26958,7 +27167,8 @@ ${decomposedNote}` : decomposedNote
     docPath: relPath,
     docId: entry.id,
     taskCount,
-    summary
+    summary,
+    filesToWrite: collector.isEmpty() ? void 0 : collector
   };
 }
 function buildTaskContext(task) {
@@ -27028,15 +27238,17 @@ async function handleScopeBrief(adapter2, config2, args) {
       taskId,
       apiKey,
       projectRoot: config2.projectRoot,
-      cycleNumber: health.totalCycles
+      cycleNumber: health.totalCycles,
+      adapterType: config2.adapterType
     });
+    const filesToWriteSection = result.filesToWrite ? formatFilesToWriteSection(result.filesToWrite) : "";
     return textResponse(
       `**Scope document created:** \`${result.docPath}\`
 - **Sub-tasks defined:** ${result.taskCount}
 - **Doc registry ID:** ${result.docId}
 - **Source task:** ${taskId} marked as decomposed
 
-**Next step:** Review \`${result.docPath}\` and submit each sub-task via \`idea\` with \`Reference: ${result.docPath}\` in notes. The planner will pick them up in the next cycle.`
+**Next step:** Review \`${result.docPath}\` and submit each sub-task via \`idea\` with \`Reference: ${result.docPath}\` in notes. The planner will pick them up in the next cycle.` + filesToWriteSection
     );
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
@@ -27229,7 +27441,7 @@ async function handleDiscoveredIssueResolve(adapter2, args) {
 // src/tools/project.ts
 import path6 from "path";
 function workspacePapiDir(config2) {
-  if (process.env.PORT || process.env.PAPI_HTTP_PORT) return void 0;
+  if (!hasLocalWorkspace()) return void 0;
   return config2.papiDir;
 }
 var NO_SUPPORT = "Project lifecycle tools require a hosted (proxy) or PostgreSQL (pg) adapter. The local md adapter does not support them.";

package/package.json

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