social-autoposter 1.6.68 → 1.6.69

package/mcp/dist/index.js

@@ -34,7 +34,8 @@ const PANEL_URI = "ui://social-autoposter/panel.html";
 const TWITTER_AUTOPILOT_LABEL = "com.m13v.social-twitter-cycle";
 const TWITTER_AUTOPILOT_PLIST = path.join(os.homedir(), "Library", "LaunchAgents", `${TWITTER_AUTOPILOT_LABEL}.plist`);
 // Daily self-updater. Enabled alongside autopilot so a hands-free (headless)
-// install keeps itself current — the interactive `version` tool only helps when
+// install keeps itself current — the interactive `runtime` tool (action:'update')
+// only helps when
 // a human-facing agent session is open, which an autopilot box never has.
 const UPDATER_LABEL = "com.m13v.social-autoposter-update";
 const UPDATER_PLIST = path.join(os.homedir(), "Library", "LaunchAgents", `${UPDATER_LABEL}.plist`);
@@ -171,13 +172,15 @@ const server = new McpServer({
         "about it. A feature nobody hears about is wasted distribution. Use judgment, suggest it for " +
         "genuinely shareable moments, not routine refactors, chores, or internal cleanup.\n\n" +
         "STAY CURRENT. At the start of a session, and again right after you help the user ship/merge/" +
-        "release, call the `version` tool (action:'status'). If `update_available` is true, tell the " +
-        "user and offer to run `version` with action:'update'. The `setup` tool's status also surfaces " +
-        "`update_available` and an `update_hint`.\n\n" +
-        "TYPICAL FLOW: `setup` (configure the project once) -> `draft_cycle` (scan + review a batch; the " +
-        "user approves / edits / skips every draft in a single form) -> `autopilot` (enable to also turn " +
-        "on hands-free background posting AND daily auto-updates) -> `get_stats` (see performance). Run " +
-        "`setup` first; the other tools refuse until a project is fully configured.\n\n" +
+        "release, call the `runtime` tool (action:'version'). If `update_available` is true, tell the " +
+        "user and offer to run `runtime` with action:'update'. The `project_config` tool's status also " +
+        "surfaces `update_available` and an `update_hint`.\n\n" +
+        "TYPICAL FLOW: `project_config` (configure OR edit the project, and connect X) -> `draft_cycle` " +
+        "(scan + review a batch; the user approves / edits / skips every draft in a single form) -> " +
+        "`autopilot` (enable to also turn on hands-free background posting AND daily auto-updates) -> " +
+        "`get_stats` (see performance). Run `project_config` first; the other tools refuse until a " +
+        "project is fully configured. To change anything about a project later, call `project_config` " +
+        "again with the project's name and just the changed fields — there is no separate config editor.\n\n" +
         "RENDER THE DASHBOARD AFTER ACTIONS. After any state-changing or results-producing tool call " +
         "(`draft_cycle`, `post_drafts`, `autopilot` enable/disable, `get_stats`), end your turn by " +
         "calling the `dashboard` tool so the user sees the updated state visually. Do NOT call " +
@@ -238,9 +241,10 @@ function blockedReasonMessage(reason) {
                 "Wait for the limit to reset, then run draft_cycle again.");
         case "no_search_topics":
             return ("This project has no search topics yet, so there was nothing to scan. Topics live in the " +
-                "DB (project_search_topics) and are seeded from your project's `search_topics` during setup. " +
-                "Re-run the `setup` tool for this project with a `search_topics` list (comma-separated keywords/" +
-                "phrases your buyers tweet about); setup seeds them automatically, then run draft_cycle again.");
+                "DB (project_search_topics) and are seeded from your project's `search_topics` when you " +
+                "configure it. Re-run the `project_config` tool for this project with a `search_topics` list " +
+                "(comma-separated keywords/phrases your buyers tweet about); it seeds them automatically, then " +
+                "run draft_cycle again.");
         case "topics_api_unreachable":
             return ("Couldn't reach the search-topics service to load this project's topics, so the cycle stopped " +
                 "before scanning. This is usually a transient backend/network issue. Try draft_cycle again in a " +
@@ -509,10 +513,10 @@ async function postApproved(batchId, plan) {
 // This is NOT a tool — the model never auto-calls it. It surfaces in clients
 // that render prompts as slash-commands / starters (e.g. Claude Desktop's "/"
 // menu). When the user picks it, it injects the message below into the chat,
-// which nudges the agent to start the real onboarding via the `setup` tool.
+// which nudges the agent to start the real onboarding via the `project_config` tool.
 // Deliberately a DUMB POINTER: it names no fields and no steps, so it can never
-// drift from REQUIRED_FIELDS / the setup tool's flow. All real logic stays in
-// `setup`; this is just a convenience handle to begin.
+// drift from REQUIRED_FIELDS / the project_config tool's flow. All real logic stays
+// in `project_config`; this is just a convenience handle to begin.
 server.registerPrompt("getting-started", {
     title: "Set up social-autoposter",
     description: "Start here. Walks you through configuring a product and connecting your X/Twitter " +
@@ -561,29 +565,36 @@ const WEBSITE_RESEARCH_INSTRUCTIONS = "PRODUCT RESEARCH (do this before saving t
     "register, vibe) while keeping every product CLAIM factual to the site. Don't invent " +
     "features, metrics, or guarantees the site doesn't state.\n" +
     "5. Save the best conservative factual draft without adding a confirmation round-trip. Call " +
-    "setup with name + the product fields (plus voice/search_topics from the profile scan). If the " +
+    "project_config with name + the product fields (plus voice/search_topics from the profile scan). If the " +
     "site is thin or unreachable, use only supported facts and leave optional detail conservative; " +
     "ask the user only if a required field is genuinely unknowable.";
-// ---- setup: per-project config (the "brain": project, website, voice) -----
+// ---- project_config: per-project config (the "brain": project, website, voice) -----
 // Run this FIRST. The action tools refuse until at least one project is ready.
 // You can set up MULTIPLE products and fill each project's fields INCREMENTALLY
 // across several calls — readiness is derived from config.json, never a stored
 // flag. Call with status:true (or just no name) to list every project this
 // install manages and what each still needs.
-tool("setup", {
-    title: "Set up a project",
-    description: "Run this FIRST, before any drafting or autopilot. A user's request to set up social-autoposter " +
-        "is a request to finish the workflow end to end, not to interview them step by step. Resume " +
-        "from current status, infer discoverable fields, and keep taking safe actions until runtime, " +
-        "project, X connection, topic seeding, and draft-only verification are complete.\n" +
+tool("project_config", {
+    title: "Configure or edit a project",
+    description: "The ONE tool for a project's whole lifecycle: create it, EDIT it later, and connect its X " +
+        "account. There is no separate raw-config editor — every project change goes through here so " +
+        "it validates, merges, and re-seeds the search-topic universe the cycle reads. To CHANGE an " +
+        "existing project (its website, voice, icp, differentiator, search_topics, guardrails, CTA " +
+        "link), call this with that project's `name` and ONLY the fields you want to change; it merges " +
+        "onto what's already saved and never clobbers untouched fields. Run it FIRST before any " +
+        "drafting or autopilot. A user's request to set up social-autoposter is a request to finish " +
+        "the workflow end to end, not to interview them step by step: resume from current status, " +
+        "infer discoverable fields, and keep taking safe actions until runtime, project, X connection, " +
+        "topic seeding, and draft-only verification are complete.\n" +
         "Two jobs:\n" +
-        "1) Configure a project this install posts for: its website, what it does (description), who " +
-        "to target (icp), and brand voice. To fill the PRODUCT fields, discover the product URL from " +
-        "config, conversation context, the connected X profile, or public research, then visit it " +
-        "with your own browser/fetch tools — read 5+ pages (home, pricing, features, about, docs/" +
-        "blog, FAQ) to learn it deeply, rather than guessing from the name. Set up MULTIPLE products " +
-        "(call once per product, identified by name); fill a project's fields INCREMENTALLY across " +
-        "several calls — pass whatever you have, it merges and tells you what's still missing.\n" +
+        "1) Configure (or edit) a project this install posts for: its website, what it does " +
+        "(description), who to target (icp), and brand voice. To fill the PRODUCT fields, discover the " +
+        "product URL from config, conversation context, the connected X profile, or public research, " +
+        "then visit it with your own browser/fetch tools — read 5+ pages (home, pricing, features, " +
+        "about, docs/blog, FAQ) to learn it deeply, rather than guessing from the name. Set up MULTIPLE " +
+        "products (call once per product, identified by name); fill or edit a project's fields " +
+        "INCREMENTALLY across several calls — pass whatever you have, it merges and tells you what's " +
+        "still missing.\n" +
         "2) Connect X/Twitter (action:'connect_x'): the autoposter posts through its OWN managed Chrome, " +
         "which needs your logged-in x.com session. This imports x.com/twitter.com cookies from your " +
         "everyday browser (Chrome/Arc/Brave/Edge, auto-detected) into that browser — nothing else is " +
@@ -655,6 +666,17 @@ tool("setup", {
             .string()
             .optional()
             .describe("Anything the posts must avoid saying / claiming"),
+        fields: z
+            .record(z.string(), z.any())
+            .optional()
+            .describe("Escape hatch to edit ANY other project field the named props above don't cover — e.g. " +
+            "weight, platform, voice_relationship, booking_link, qualification, subreddit_bans, " +
+            "short_links_host, short_links_live, content_angle, messaging, landing_pages, posthog. " +
+            "Pass {name:'<project>', fields:{<key>:<value>, ...}}; each key SHALLOW-merges onto the " +
+            "project, REPLACING that key's whole value (read the current value via status:true first if " +
+            "you only want to tweak part of a nested object, then pass the full new value). A value of " +
+            "null DELETES the key. 'name' is ignored here (can't rename through this path). This is how " +
+            "you edit advanced config without any raw whole-file overwrite."),
     },
 }, async (args) => {
     // ---- List import sources (for the panel dropdown) ---------------------
@@ -707,7 +729,7 @@ tool("setup", {
                     "Allow (or Always Allow). If you use more than one browser you may see it a couple of times, " +
                     "once per browser.",
                 how_to_proceed: "If the user explicitly requested setup or connection, relay the say_to_user line as a brief " +
-                    "heads-up and immediately call setup again with action:'connect_x', confirm:true; do not wait " +
+                    "heads-up and immediately call project_config again with action:'connect_x', confirm:true; do not wait " +
                     "for another yes/no reply. Optionally pass the recommended x_source. If the user only asked " +
                     "what connection would do, stop after this preview.",
             });
@@ -744,12 +766,12 @@ tool("setup", {
                 : undefined,
             onboarding: onboardingSnapshot(),
             next_step: r.connected
-                ? "X is connected. Next, run setup action:'profile_scan' to read this account's bio + recent " +
+                ? "X is connected. Next, run project_config action:'profile_scan' to read this account's bio + recent " +
                     "posts + replies and draft the project's voice/icp/search_topics in the user's own register " +
                     "before saving. Then run draft_cycle once the project is fully set up."
                 : r.state === "needs_login"
                     ? "The user must finish signing in to x.com in the Chrome window that just opened. Tell " +
-                        "them that single required action, then call setup action:'connect_x', confirm:true again."
+                        "them that single required action, then call project_config action:'connect_x', confirm:true again."
                     : "X is not connected yet. " + summarizeXAuth(r),
         });
     }
@@ -758,14 +780,14 @@ tool("setup", {
     // successful connect_x) to read the user's bio + recent posts + recent
     // replies. Returns the raw corpus plus grounding_instructions; synthesis of
     // voice/icp/topics happens IN THIS CONVERSATION (no nested model), then the
-    // agent confirms with the user and calls setup to persist. Read-only.
+    // agent confirms with the user and calls project_config to persist. Read-only.
     if (args.action === "profile_scan") {
         // Handle is auto-detected from the live logged-in session by the scanner.
         recordOnboardingAttempt("profile_scanned");
         const scan = await xScanProfile();
         if (!scan.ok) {
             const hint = scan.state === "browser_not_running" || scan.state === "no_handle"
-                ? " Run setup action:'connect_x' (confirm:true) first so the account is connected, then retry profile_scan."
+                ? " Run project_config action:'connect_x' (confirm:true) first so the account is connected, then retry profile_scan."
                 : "";
             blockOnboardingMilestone("profile_scanned", `profile_${scan.state || "failed"}`, scan.error || "profile scan failed", { state: scan.state || "failed" });
             return jsonContent({
@@ -838,7 +860,7 @@ tool("setup", {
             update_available: ver.update_available,
             update_hint: ver.update_available
                 ? `A newer version (${ver.latest}) is available — you're on ${ver.installed}. ` +
-                    `Tell the user and offer to run the \`version\` tool with action:'update' ` +
+                    `Tell the user and offer to run the \`runtime\` tool with action:'update' ` +
                     `(or \`npx social-autoposter@latest update\`).`
                 : undefined,
             required_fields: REQUIRED_FIELDS,
@@ -847,16 +869,16 @@ tool("setup", {
             ready_for_verification: rtReady && configured && x.connected,
             onboarding: onboardingSnapshot(),
             next_step: !rtReady
-                ? "Runtime is not ready. Call install_runtime, poll install_status to completion, then continue setup automatically."
+                ? "Runtime is not ready. Call runtime action:'install', poll runtime action:'status' to completion, then continue setup automatically."
                 : projects.length === 0
-                    ? "No projects yet. Discover the product from conversation context and the connected X profile; research its website, infer a conservative complete project, and call setup. Ask only if no product can be identified." +
+                    ? "No projects yet. Discover the product from conversation context and the connected X profile; research its website, infer a conservative complete project, and call project_config. Ask only if no product can be identified." +
                         (x.connected ? "" : " X is not connected yet either — detect_x_sources, warn about keychain prompts, then run connect_x with confirm:true without a separate permission turn.")
                     : projects.every((p) => p.ready)
                         ? (x.connected
                             ? "All configured projects are ready and X is connected. Run draft_cycle now to verify end to end without posting. After it verifies, call the `dashboard` tool so the user sees the finished setup."
                             : "All configured projects are ready, but X is NOT connected — posting needs a logged-in " +
-                                "x.com session. Detect sources and run setup action:'connect_x', confirm:true; do not ask whether to proceed.")
-                        : "Some projects are missing required fields (see each project's missing_required). Derive them from config, context, profile_scan, and website research, then call setup again. Ask only if a required field is genuinely unknowable." +
+                                "x.com session. Detect sources and run project_config action:'connect_x', confirm:true; do not ask whether to proceed.")
+                        : "Some projects are missing required fields (see each project's missing_required). Derive them from config, context, profile_scan, and website research, then call project_config again. Ask only if a required field is genuinely unknowable." +
                             (x.connected ? "" : " X is also not connected yet; detect sources and run connect_x with confirm:true."),
         });
     }
@@ -938,6 +960,17 @@ tool("setup", {
                 }
             }
         }
+        // Surface any advanced (escape-hatch) field edits in the note so the
+        // agent can confirm exactly what changed to the user.
+        let advancedNote = "";
+        if (result.fields_set.length || result.fields_removed.length) {
+            const parts = [];
+            if (result.fields_set.length)
+                parts.push(`set ${result.fields_set.join(", ")}`);
+            if (result.fields_removed.length)
+                parts.push(`removed ${result.fields_removed.join(", ")}`);
+            advancedNote = ` Advanced fields updated: ${parts.join("; ")}.`;
+        }
         return jsonContent({
             ok: true,
             project: result.project,
@@ -947,16 +980,19 @@ tool("setup", {
             topics_seeded: topicsSeeded,
             topic_count: topicCount,
             search_queries: searchQueries,
+            fields_set: result.fields_set,
+            fields_removed: result.fields_removed,
             config_path: configPath(),
             onboarding: onboardingSnapshot(),
-            note: result.ready
+            note: (result.ready
                 ? `Project '${result.project}' is fully configured.${seedNote} Next: if X is not connected, ` +
-                    `detect sources, warn about keychain prompts, and call setup with ` +
+                    `detect sources, warn about keychain prompts, and call project_config with ` +
                     `action:'connect_x', confirm:true immediately. Once X is connected, run draft_cycle to ` +
                     `verify without posting. Do not enable autopilot unless explicitly requested.`
                 : `Saved what you provided for '${result.project}'. Still need: ${result.missing_required.join(", ")}. ` +
                     `First derive those fields from existing context, profile_scan, and website research, then ` +
-                    `call setup again with name='${result.project}'. Ask only if a required field is genuinely unknowable.`,
+                    `call project_config again with name='${result.project}'. Ask only if a required field is genuinely unknowable.`) +
+                advancedNote,
         });
     }
     catch (e) {
@@ -1175,7 +1211,7 @@ tool("autopilot", {
     },
 }, async ({ action }) => {
     if (action !== "status" && !hasReadyProject()) {
-        return textContent("No project is fully set up yet, so autopilot has nothing to post. Run the `setup` tool " +
+        return textContent("No project is fully set up yet, so autopilot has nothing to post. Run the `project_config` tool " +
             "first. Note: autopilot runs the background cycle across all configured projects; it is " +
             "not scoped to one project.");
     }
@@ -1282,29 +1318,90 @@ tool("get_stats", {
     }
 });
 // ---- version: report installed version + deliver updates on demand ---------
-tool("version", {
-    title: "Version & updates",
-    description: "Report the installed social-autoposter version and check npm for a newer release. " +
-        "action:'status' (default) shows installed vs latest published and whether an update is " +
-        "available. action:'update' pulls and installs the latest release (runs " +
-        "`npx social-autoposter@latest update`); the new MCP code takes effect after the client " +
-        "reconnects / restarts (this running process keeps the old code until then). Use this when " +
-        "the user asks what version they're on, or to push the latest update to their machine.",
+// ---- runtime: install + version/update + diagnostics ----------------------
+// ONE plumbing tool for the whole local-runtime lifecycle, action-based like
+// project_config and autopilot. The pipeline runs Python locally; rather than
+// depend on the user's system Python (the #1 source of install failures), the
+// first run provisions a fully OWNED uv runtime: standalone CPython + owned venv
+// + deps + Chromium. It also reports/installs new releases and runs the Doctor.
+// Plain (non-UI) so EVERY host can drive it — the panel's Install card and
+// Update button are just skins that call action:'install' then poll
+// action:'status'. See runtime.ts for the provisioning + progress contract.
+//
+// Actions:
+//   status (default) — is the owned runtime installed? + in-progress step detail
+//   install          — start provisioning in the background; poll status to follow
+//   version          — installed vs latest published, whether an update is available
+//   update           — pull + install the latest release (npx social-autoposter@latest update)
+//   doctor           — run structured environment diagnostics (phase: pre_connect|full)
+//   doctor_status    — last persisted Doctor result without re-running checks
+tool("runtime", {
+    title: "Runtime: install, update & diagnostics",
+    description: "The ONE plumbing tool for the autoposter's local runtime lifecycle. action:'status' (default) " +
+        "reports whether the self-contained Python/Chromium runtime is installed and, mid-install, the " +
+        "per-step progress (uv, Python, venv, dependencies, Chromium) — poll it after action:'install'. " +
+        "action:'install' provisions that runtime (a private Python via uv, NOT your system Python, plus " +
+        "deps and Chromium); it runs in the background and returns immediately, is safe to call " +
+        "repeatedly, and is a no-op once installed. action:'version' shows installed vs latest published " +
+        "and whether an update is available; action:'update' pulls and installs the latest release (runs " +
+        "`npx social-autoposter@latest update`, taking effect after the client reconnects/restarts). " +
+        "action:'doctor' runs structured environment diagnostics (phase:'pre_connect' is safe at " +
+        "onboarding start and treats the missing X session/cookies as expected; phase:'full' verifies the " +
+        "completed environment after X is connected); action:'doctor_status' returns the last persisted " +
+        "Doctor result without re-running. Use this the first time the user sets up, when another tool " +
+        "reports the runtime isn't ready, when the user asks what version they're on or to update, or to " +
+        "diagnose a broken environment.",
     inputSchema: {
-        action: z.enum(["status", "update"]).optional(),
+        action: z
+            .enum(["status", "install", "version", "update", "doctor", "doctor_status"])
+            .optional(),
+        phase: z
+            .enum(["pre_connect", "full"])
+            .optional()
+            .describe("Only for action:'doctor' — which diagnostic phase to run (default pre_connect)."),
     },
-}, async ({ action }) => {
+}, async ({ action, phase }) => {
+    // ---- install: start provisioning the owned runtime --------------------
+    if (action === "install") {
+        if (runtimeReady()) {
+            completeOnboardingMilestone("runtime_ready");
+            return jsonContent({ already_installed: true, ...runtimeSnapshot() });
+        }
+        recordOnboardingAttempt("runtime_ready");
+        const progress = startProvisioning();
+        return jsonContent({
+            started: true,
+            runtime_ready: false,
+            note: "Runtime install started. Poll runtime action:'status' every ~1.5s for progress.",
+            progress,
+        });
+    }
+    // ---- version: installed vs latest published ---------------------------
+    if (action === "version") {
+        const v = await versionStatus();
+        return jsonContent({
+            installed: v.installed,
+            latest_published: v.latest,
+            update_available: v.update_available,
+            update_command: "npx social-autoposter@latest update",
+            note: v.latest == null
+                ? "Could not reach npm to check for a newer version (offline or registry error)."
+                : v.update_available
+                    ? `A newer version (${v.latest}) is available. Run this tool with action:'update' ` +
+                        "to install it, or run `npx social-autoposter@latest update` in a terminal."
+                    : "You are on the latest published version.",
+        });
+    }
+    // ---- update: pull + install the latest release ------------------------
     if (action === "update") {
-        // Pull + install the latest published release. This overwrites mcp/dist/
-        // (including this running file — safe; the loaded process keeps old code)
-        // and re-runs install.mjs to re-register the client config. npx is run
-        // non-interactively so it can't stall on a confirm prompt.
+        // Overwrites mcp/dist/ (including this running file — safe; the loaded
+        // process keeps old code) and re-runs install.mjs to re-register the
+        // client config. npx is non-interactive so it can't stall on a confirm.
         const before = VERSION;
         const res = await run("npx", ["-y", "social-autoposter@latest", "update"], {
             timeoutMs: 600_000,
         });
-        // Bust the latest-version cache so the post-update number is fresh.
-        const latest = await latestPublishedVersion();
+        const latest = await latestPublishedVersion(); // bust the cache
         return jsonContent({
             action: "update",
             ran: "npx social-autoposter@latest update",
@@ -1317,27 +1414,29 @@ tool("version", {
             output_tail: (res.stdout + "\n" + res.stderr).trim().split("\n").slice(-20).join("\n"),
         });
     }
-    const v = await versionStatus();
-    return jsonContent({
-        installed: v.installed,
-        latest_published: v.latest,
-        update_available: v.update_available,
-        update_command: "npx social-autoposter@latest update",
-        note: v.latest == null
-            ? "Could not reach npm to check for a newer version (offline or registry error)."
-            : v.update_available
-                ? `A newer version (${v.latest}) is available. Run this tool with action:'update' ` +
-                    "to install it, or run `npx social-autoposter@latest update` in a terminal."
-                : "You are on the latest published version.",
-    });
+    // ---- doctor: run structured diagnostics -------------------------------
+    if (action === "doctor") {
+        const selected = phase || "pre_connect";
+        const report = await runDoctorPhase(selected);
+        return jsonContent({ doctor: report, onboarding: onboardingSnapshot() });
+    }
+    // ---- doctor_status: last persisted Doctor result ----------------------
+    if (action === "doctor_status") {
+        return jsonContent({
+            doctor: onboardingLedger()?.doctor?.latest ?? null,
+            onboarding: onboardingSnapshot(),
+        });
+    }
+    // ---- status (default): runtime install snapshot -----------------------
+    const snapshot = runtimeSnapshot();
+    if (snapshot.runtime_ready) {
+        completeOnboardingMilestone("runtime_ready");
+    }
+    else if (snapshot.progress?.done && !snapshot.progress.ok) {
+        blockOnboardingMilestone("runtime_ready", "runtime_install_failed", snapshot.progress.error || "Runtime installation failed", { outcome: "failed" });
+    }
+    return jsonContent({ ...snapshot, onboarding: onboardingSnapshot() });
 });
-// ---- runtime installer ----------------------------------------------------
-// The pipeline runs Python locally. Rather than depend on the user's system
-// Python (the #1 source of install failures), the first run provisions a fully
-// OWNED uv runtime: standalone CPython + owned venv + deps + Chromium. These two
-// tools drive it. They are plain (non-UI) tools so EVERY host can install — the
-// panel's Install card is just a skin that calls install_runtime then polls
-// install_status. See runtime.ts for the provisioning + progress contract.
 function runtimeSnapshot() {
     const rt = readRuntime();
     const progress = readProgress();
@@ -1350,138 +1449,10 @@ function runtimeSnapshot() {
         onboarding: onboardingSnapshot(),
     };
 }
-tool("install_runtime", {
-    title: "Install the Python runtime",
-    description: "One-time setup that provisions the self-contained runtime the autoposter needs: a private " +
-        "Python (via uv, not your system Python), its dependencies, and the Chromium browser. Runs in " +
-        "the background and returns immediately; poll `install_status` for progress. Safe to call " +
-        "repeatedly; it resumes/repairs and is a no-op once everything is installed. Use this the " +
-        "first time the user sets up, or if other tools report the runtime isn't ready.",
-    inputSchema: {},
-}, async () => {
-    if (runtimeReady()) {
-        completeOnboardingMilestone("runtime_ready");
-        return jsonContent({ already_installed: true, ...runtimeSnapshot() });
-    }
-    recordOnboardingAttempt("runtime_ready");
-    const progress = startProvisioning();
-    return jsonContent({
-        started: true,
-        runtime_ready: false,
-        note: "Runtime install started. Poll install_status every ~1.5s for progress.",
-        progress,
-    });
-});
-tool("install_status", {
-    title: "Runtime install status",
-    description: "Report whether the self-contained Python/Chromium runtime is installed and, if an install is " +
-        "in progress, the per-step progress (uv, Python, venv, dependencies, Chromium). Poll this after " +
-        "install_runtime to follow the install to completion.",
-    inputSchema: {},
-}, async () => {
-    const snapshot = runtimeSnapshot();
-    if (snapshot.runtime_ready) {
-        completeOnboardingMilestone("runtime_ready");
-    }
-    else if (snapshot.progress?.done && !snapshot.progress.ok) {
-        blockOnboardingMilestone("runtime_ready", "runtime_install_failed", snapshot.progress.error || "Runtime installation failed", { outcome: "failed" });
-    }
-    return jsonContent({ ...snapshot, onboarding: onboardingSnapshot() });
-});
-// ---- doctor: structured environment diagnostics --------------------------
-// Uses the same shared engine as `npx social-autoposter doctor`. Pre-connect
-// avoids invasive keychain access and classifies not-yet-created X artifacts as
-// expected; full verifies the completed browser/session/cookie environment.
-tool("doctor", {
-    title: "Diagnose the onboarding environment",
-    description: "Run the structured social-autoposter Doctor and persist the result in the onboarding " +
-        "ledger. phase:'pre_connect' is safe at onboarding start and treats the missing X session/" +
-        "cookie artifacts as expected. phase:'full' verifies the completed environment after X is " +
-        "connected. action:'status' returns the most recent persisted result without re-running checks.",
-    inputSchema: {
-        action: z.enum(["run", "status"]).optional(),
-        phase: z.enum(["pre_connect", "full"]).optional(),
-    },
-}, async ({ action, phase, }) => {
-    if (action === "status") {
-        return jsonContent({
-            doctor: onboardingLedger()?.doctor?.latest ?? null,
-            onboarding: onboardingSnapshot(),
-        });
-    }
-    const selected = phase || "pre_connect";
-    const report = await runDoctorPhase(selected);
-    return jsonContent({
-        doctor: report,
-        onboarding: onboardingSnapshot(),
-    });
-});
-// ---- config: read / edit the raw config.json ------------------------------
-// The panel renders the full config and lets the user edit it. Writing is
-// guarded: the new content must parse as JSON, and we always drop a timestamped
-// backup next to config.json before overwriting, so a bad paste is recoverable.
-tool("config", {
-    title: "View or edit config.json",
-    description: "Read or update the autoposter's config.json (the source of truth for every project, the X/" +
-        "Reddit/LinkedIn account handles, topics, and exclusions). action:'get' (default) returns the " +
-        "full raw JSON; action:'save' validates the supplied `content` as JSON, writes a timestamped " +
-        "backup, then overwrites config.json. Use when the user asks to see, edit, or fix their config.",
-    inputSchema: {
-        action: z.enum(["get", "save"]).optional(),
-        content: z.string().optional(),
-    },
-}, async (args) => {
-    const action = args.action || "get";
-    const cfgPath = configPath();
-    if (action === "get") {
-        try {
-            const content = fs.readFileSync(cfgPath, "utf-8");
-            return jsonContent({ ok: true, path: cfgPath, bytes: content.length, content });
-        }
-        catch (e) {
-            return jsonContent({ ok: false, path: cfgPath, error: String(e?.message || e) });
-        }
-    }
-    // save
-    const content = args.content;
-    if (typeof content !== "string" || content.trim() === "") {
-        return jsonContent({ ok: false, error: "Nothing to save: `content` was empty." });
-    }
-    let parsed;
-    try {
-        parsed = JSON.parse(content);
-    }
-    catch (e) {
-        // Don't write a config that won't parse — every pipeline reads this file.
-        return jsonContent({ ok: false, error: "Invalid JSON, not saved: " + String(e?.message || e) });
-    }
-    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-        return jsonContent({ ok: false, error: "Top level of config.json must be a JSON object." });
-    }
-    try {
-        const stamp = new Date().toISOString().replace(/[:.]/g, "-");
-        const backup = `${cfgPath}.bak-panel-${stamp}`;
-        try {
-            fs.copyFileSync(cfgPath, backup);
-        }
-        catch {
-            /* first-write / missing original is non-fatal */
-        }
-        // Re-serialize the parsed object so what lands on disk is canonical,
-        // 2-space-indented JSON with a trailing newline (matches the Python
-        // writers), regardless of how the user formatted their paste.
-        const out = JSON.stringify(parsed, null, 2) + "\n";
-        fs.writeFileSync(cfgPath, out, "utf-8");
-        return jsonContent({ ok: true, path: cfgPath, bytes: out.length, backup });
-    }
-    catch (e) {
-        return jsonContent({ ok: false, error: "Write failed: " + String(e?.message || e) });
-    }
-});
 // ---- panel: MCP Apps control surface --------------------------------------
 // A self-contained HTML view rendered by hosts that support MCP Apps (Claude
 // desktop/web, etc.). It duplicates NO pipeline logic: each button calls one of
-// the tools above (draft_cycle / autopilot / setup / get_stats) through the host
+// the tools above (draft_cycle / autopilot / project_config / get_stats) through the host
 // and re-reads status. The tool itself returns the first-paint snapshot so the
 // view has data the instant it loads.
 // Is either launchd job (cycle / daily updater) currently loaded?
@@ -1641,19 +1612,39 @@ function startLocalPanel() {
             }
         });
         srv.on("error", reject);
-        srv.listen(0, "127.0.0.1", () => {
+        // Optional fixed port (SAPS_PANEL_PORT) for deterministic addressing; default
+        // is an OS-assigned ephemeral port.
+        const wantPort = Number(process.env.SAPS_PANEL_PORT) || 0;
+        srv.listen(wantPort, "127.0.0.1", () => {
             const addr = srv.address();
             const port = typeof addr === "object" && addr ? addr.port : 0;
             localPanel = { url: `http://127.0.0.1:${port}/`, server: srv };
+            writePanelUrl(localPanel.url);
             resolve(localPanel.url);
         });
     });
 }
-// Open a URL in the user's default browser, cross-platform. Honors
-// SAPS_PANEL_NO_OPEN (set on headless autopilot boxes or in tests) to skip the
-// actual open while still returning the URL to the caller.
+// Publish the loopback URL to a stable file so an out-of-process reader (the
+// Claude Code side-panel reverse proxy) can find the ephemeral port without
+// scraping `lsof`. Best-effort: a write failure never blocks the panel.
+function writePanelUrl(url) {
+    try {
+        const dir = path.join(process.env.HOME || os.homedir(), ".social-autoposter-mcp");
+        fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(path.join(dir, "panel-url"), url, "utf-8");
+    }
+    catch (e) {
+        console.error("[social-autoposter-mcp] writePanelUrl failed:", e?.message || e);
+    }
+}
+// Open a URL in the user's default browser, cross-platform. Opening is OPT-IN:
+// by default we do NOT pop a browser tab. The dashboard already surfaces in-host
+// (MCP Apps inline) or via the Claude Code side panel / returned loopback URL, so
+// auto-opening the OS browser on every dashboard call is unwanted noise. Set
+// SAPS_PANEL_OPEN_BROWSER=1 to restore the old auto-open behavior. (The URL is
+// always returned to the caller regardless, so nothing is lost when we don't open.)
 async function openInBrowser(url) {
-    if (process.env.SAPS_PANEL_NO_OPEN)
+    if (!process.env.SAPS_PANEL_OPEN_BROWSER)
         return;
     const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
     const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
@@ -1699,8 +1690,9 @@ appTool("dashboard", {
         return { content: [], structuredContent: { snapshot: JSON.stringify(snap) } };
     }
     // Host CAN'T render inline (Claude Code / Cowork today): serve the identical
-    // panel.html from a loopback HTTP server and open it in the browser, so the
-    // user still gets the visual surface instead of a wall of text.
+    // panel.html from a loopback HTTP server. We do NOT auto-open a browser tab
+    // (see openInBrowser — opt-in only); the dashboard is shown in the Claude Code
+    // side panel, and the loopback URL is returned for anyone who wants to open it.
     try {
         const url = await startLocalPanel();
         await openInBrowser(url);
@@ -1708,7 +1700,7 @@ appTool("dashboard", {
             content: [{
                     type: "text",
                     text: human +
-                        `\n\nThis host can't render the dashboard inline, so I opened it in your browser: ${url}`,
+                        `\n\nThis host can't render the dashboard inline. It's available in the side panel; loopback URL: ${url}`,
                 }],
             structuredContent: { snapshot: JSON.stringify(snap), fallback_url: url },
         };
@@ -1804,6 +1796,12 @@ async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);
     console.error(`[social-autoposter-mcp] connected. v=${VERSION} repo=${repoDir()}`);
+    // Eagerly start the loopback panel server so the Claude Code side panel (and any
+    // reverse proxy in front of it) always has a backend to hit, without waiting for
+    // a first `dashboard` call. Best-effort: a bind failure must never block boot.
+    void startLocalPanel()
+        .then((url) => console.error(`[social-autoposter-mcp] panel loopback ready at ${url}`))
+        .catch((e) => console.error("[social-autoposter-mcp] panel loopback start failed:", e?.message || e));
     // Phone home so this .mcpb install is visible in the install-lane digest
     // (parity with the npx launchd heartbeat). Once on startup, then every 15m
     // while the desktop app keeps the server alive. unref() so it never holds the