@pharaoh-so/mcp 0.3.54 → 0.3.57

package/dist/refresh.js

@@ -41,10 +41,11 @@ const REFRESH_TIMEOUT_MS = 10_000;
  * @param server  Pharaoh server base URL (e.g. "https://mcp.pharaoh.so")
  * @param path    optional custom credentials path (for tests)
  * @param timeoutMs how long the refresh request may take (for tests)
+ * @param strictOrigin require credentials from this origin and refuse refresh redirects
  * @returns New or adopted credentials, or a classified failure. A lock held by
  *   another proxy for too long is `transient` (credentials untouched).
  */
-export async function refreshIfNeeded(creds, server, path, timeoutMs = REFRESH_TIMEOUT_MS) {
+export async function refreshIfNeeded(creds, server, path, timeoutMs = REFRESH_TIMEOUT_MS, strictOrigin = false) {
     let release;
     try {
         release = await acquireCredentialsLock(path);
@@ -58,11 +59,13 @@ export async function refreshIfNeeded(creds, server, path, timeoutMs = REFRESH_T
     }
     try {
         const current = readCredentials(path);
+        const source = current ?? creds;
+        if (strictOrigin && !matchesOrigin(source, server))
+            return originMismatch();
         if (current && current.access_token !== creds.access_token && !isExpired(current)) {
             return { ok: true, creds: current };
         }
-        const source = current ?? creds;
-        const outcome = await requestRefresh(source, server, timeoutMs, path);
+        const outcome = await requestRefresh(source, server, timeoutMs, path, strictOrigin);
         if (outcome.ok || outcome.action !== "reauth")
             return outcome;
         const after = readCredentials(path);
@@ -70,6 +73,8 @@ export async function refreshIfNeeded(creds, server, path, timeoutMs = REFRESH_T
             deleteCredentials(path);
             return outcome;
         }
+        if (strictOrigin && !matchesOrigin(after, server))
+            return originMismatch();
         return isExpired(after) ? outcome : { ok: true, creds: after };
     }
     finally {
@@ -80,7 +85,7 @@ export async function refreshIfNeeded(creds, server, path, timeoutMs = REFRESH_T
  * One refresh-grant round trip: POST the refresh token, persist and return the
  * new credentials on success, or classify the failure. Caller holds the lock.
  */
-async function requestRefresh(creds, server, timeoutMs, path) {
+async function requestRefresh(creds, server, timeoutMs, path, strictOrigin = false) {
     // Guard: refresh token itself expired. No point hitting the server — the
     // grant will fail with invalid_grant. Short-circuit to reauth.
     if (isRefreshExpired(creds)) {
@@ -101,6 +106,7 @@ async function requestRefresh(creds, server, timeoutMs, path) {
             body: JSON.stringify({
                 refresh_token: creds.refresh_token,
             }),
+            redirect: strictOrigin ? "error" : undefined,
             signal: AbortSignal.timeout(timeoutMs),
         });
     }
@@ -192,15 +198,36 @@ async function requestRefresh(creds, server, timeoutMs, path) {
  * Intended use: called at proxy startup to replace the current "die if expired"
  * branch in index.ts.
  */
-export async function loadAndRefresh(server, path) {
+export async function loadAndRefresh(server, path, strictOrigin = false) {
     const creds = readCredentials(path);
     if (!creds)
         return null;
+    if (strictOrigin && !matchesOrigin(creds, server))
+        return originMismatch();
     // Access token still valid — no refresh needed.
     const expiresAt = new Date(creds.expires_at).getTime();
     const bufferMs = creds.expires_in * 1000 * 0.1;
     if (Date.now() < expiresAt - bufferMs) {
         return { ok: true, creds };
     }
-    return refreshIfNeeded(creds, server, path);
+    return refreshIfNeeded(creds, server, path, undefined, strictOrigin);
+}
+/** A fixed-origin caller must never send credentials issued by another server. */
+function matchesOrigin(creds, server) {
+    try {
+        return new URL(creds.sse_url).origin === new URL(server).origin;
+    }
+    catch {
+        return false;
+    }
+}
+function originMismatch() {
+    return { ok: false, action: "transient", message: "Credentials belong to a different server" };
+}
+/** Refresh for a client that accepts credentials only from its configured origin. */
+export function originBoundRefresh(server, path) {
+    return {
+        load: () => loadAndRefresh(server, path, true),
+        renew: (creds) => refreshIfNeeded(creds, server, path, undefined, true),
+    };
 }

package/dist/setup.d.ts

@@ -54,3 +54,8 @@ export declare function runSetup(options?: {
     home?: string;
     claude?: ClaudeCli;
 }): boolean;
+/** Detect the local Codex CLI before touching any settings. */
+export declare function hasCodex(): boolean;
+/** Preserve custom registrations and any existing disabled setting. */
+export declare function runCodexSetup(): boolean;
+export declare function cleanCodexSetup(): void;

package/dist/setup.js

@@ -185,3 +185,69 @@ export function runSetup(options) {
         printLines(`Pharaoh: registered as global MCP server (scope: user) running ${spec}`);
     return true;
 }
+/** Detect the local Codex CLI before touching any settings. */
+export function hasCodex() {
+    try {
+        execFileSync("codex", ["--version"], { stdio: "pipe", timeout: 10_000 });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function codexMcp(args) {
+    return execFileSync("codex", ["mcp", ...args], {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "pipe"],
+        timeout: 30_000,
+    });
+}
+function configuredCodexPharaoh() {
+    try {
+        const { transport, enabled } = JSON.parse(codexMcp(["get", "pharaoh", "--json"]));
+        return {
+            owned: transport?.type === "stdio" &&
+                transport.command === "npx" &&
+                transport.args?.length === 1 &&
+                /^@pharaoh-so\/mcp@\d+\.\d+\.\d+$/.test(transport.args[0]) &&
+                !transport.env &&
+                !transport.env_vars?.length &&
+                !transport.cwd,
+            enabled,
+        };
+    }
+    catch (error) {
+        if (error &&
+            typeof error === "object" &&
+            "stderr" in error &&
+            typeof error.stderr === "string" &&
+            error.stderr.includes("No MCP server named 'pharaoh' found."))
+            return null;
+        throw error;
+    }
+}
+/** Preserve custom registrations and any existing disabled setting. */
+export function runCodexSetup() {
+    try {
+        const existing = configuredCodexPharaoh();
+        if (existing && (!existing.owned || existing.enabled === false))
+            return true;
+        codexMcp(["add", "pharaoh", "--", "npx", pinnedPackageSpec()]);
+        return true;
+    }
+    catch {
+        printLines("Pharaoh: Codex setup could not update its MCP registration.");
+        return false;
+    }
+}
+export function cleanCodexSetup() {
+    if (!hasCodex())
+        return;
+    try {
+        if (configuredCodexPharaoh()?.owned)
+            codexMcp(["remove", "pharaoh"]);
+    }
+    catch {
+        printLines("Pharaoh: Codex setup could not remove its MCP registration.");
+    }
+}

package/inspect-tools.json

@@ -1,9 +1,10 @@
 {
-  "instructions": "Pharaoh maps this codebase into a graph of functions, callers, modules, endpoints and cron jobs. For questions about how code connects, one Pharaoh call answers what grep and file reads take many turns to piece together. No source code is stored.\n\n## Pick the tool by the question\n\n| Question | Tool |\n|---|---|\n| Does X already exist? Where is Y implemented? | search_functions |\n| What calls X? What breaks if I change it? Which endpoints or cron jobs reach it? | get_blast_radius |\n| What's in this module, what does it depend on, who calls into it? | get_module_context |\n| Is this code dead or wired in? What can I delete? | get_unused_code |\n| How is the repo laid out? Which module owns this? What's the repo called? | get_codebase_map |\n| Several of these at once (planning a change, reviewing a PR) | pharaoh_recon |\n\nAsk Pharaoh first for these questions, then read the files you're about to change. The graph maps the default branch, so use grep for code that isn't there yet (your branch, uncommitted edits), for literal text (strings, error messages, config values, comments, non-code files) and for renames, which change every reference, tests and mocks included. Don't re-check a Pharaoh answer with grep; if a response says the latest push is still being mapped, re-check only the files that push changed.\n\nIf your client shows Pharaoh's tools by name only (behind tool search), load them before your first code search.\n\n## Surface insight blocks\n\nSurface the facts in each ★ Pharaoh block in your visible response. Preserve its counts, labels and analysis limits. When a block says \"Trace view available\", do not reproduce the ASCII panel; summarize its findings and limits in plain language. Otherwise, if the client hides or breaks ASCII panels, present those facts as plain text or a table; do not rely on the raw tool panel being visible.\n\n## Repos that aren't mapped\n\nThe only supported path is the Pharaoh GitHub App. If a repo isn't mapped, tell the user to install the app at `https://github.com/apps/pharaoh-so/installations/new` on the account or org that owns it. Free maps one live repo; Pro maps every repo. Mapped repos re-map on every push. Do not suggest workarounds.\n\n## Cross-repo and PR review\n\nWhen the user has several mapped repos, check related repos when a change touches shared interfaces, APIs or types: search_functions takes any of your repo names.\n\nPR review: pharaoh_recon (map + touched modules + blast radius), then get_blast_radius on the riskiest changed functions. Verdict: SHIP, SHIP WITH CHANGES, or BLOCK. The plan-with-pharaoh and review-with-pharaoh prompts walk through both workflows.\n\n## Using results\n\n- Lead with what the data reveals about this codebase, not a raw dump. Highlight surprises.\n- Attribute findings to Pharaoh with specific numbers (e.g. \"Pharaoh's blast radius found 12 callers across 4 modules\").\n- Asked what Pharaoh does: explain what you learned from the graph in THIS conversation, with the numbers from the ★ Pharaoh blocks, against what finding it without Pharaoh would have taken.\n\n## Repo names\n\nUse the short repo name from the tool's `repo` parameter (e.g. \"pharaoh\", not \"org/pharaoh\"). Unambiguous short names resolve automatically. If a name is wrong, I'll return suggestions and your repos grouped by organization; pick the one for your task and retry.\n\nUse pharaoh_account for the plan, the live repo and refreshes. Docs: pharaoh.so/docs. Connect steps for other AI clients (Claude Code, Claude.ai, Cursor, VS Code): https://mcp.pharaoh.so/setup",
+  "instructions": "Pharaoh answers structural questions about mapped repos from a graph of each repo's default branch: functions, callers, modules, dependencies, endpoints, cron jobs and reachability, for TypeScript, JavaScript and Python. No source code is stored.\n\n## Which tool answers which question\n\nPharaoh answers these questions from the graph:\n\n| Question | Tool |\n|---|---|\n| Does X already exist? Where is Y implemented? | search_functions |\n| What calls X? What breaks if I change it? Which endpoints or cron jobs reach it? | get_blast_radius |\n| What's in this module, what does it depend on, who calls into it? | get_module_context |\n| Is this code dead or wired in? What can I delete? | get_unused_code |\n| How is the repo laid out? Which module owns this? What's the repo called? | get_codebase_map |\n| Several of these at once (planning a change, reviewing a PR) | pharaoh_recon |\n\nThe graph reflects the default branch at its last mapped push, and a response says when a newer push is still being mapped. Grep and file reads cover what it leaves out: code that isn't on the default branch yet (other branches, uncommitted edits), literal text (strings, error messages, config values, comments, non-code files) and renames, which change every reference, tests and mocks included.\n\n## Repos\n\nRepos are mapped through the Pharaoh GitHub App, installed on the account or org that owns them: `https://github.com/apps/pharaoh-so/installations/new`. The App reads the repositories it is installed on and the organization's membership; its only write permission is posting check results. Mapped repos re-map on every push. search_functions accepts any of the user's mapped repo names.\n\nTools take the short repo name in their `repo` parameter (e.g. \"pharaoh\", not \"org/pharaoh\"). Unambiguous short names resolve automatically. A name that doesn't resolve returns suggestions and the user's repos grouped by organization.\n\n## Account\n\npharaoh_account shows each workspace's plan. Every repo is mapped during the trial and on Pro; after the trial, get_codebase_map keeps answering and the other tools say what's needed. pharaoh_manage_repo queues a re-map of a repo now.",
   "tools": [
     {
       "name": "get_codebase_map",
-      "description": "A repo's architecture in one call.\n\nCALL THIS WHEN:\n• You need a repo's overall structure, or which module owns something\n• You don't know the repo's exact name in Pharaoh\n\nRETURNS: Modules with file counts and LOC, module dependencies with two-way ones flagged, the files changed most in 90 days, and every endpoint with its handler file.\n\nUSE INSTEAD OF: directory listings, which omit dependency relationships.",
+      "title": "Codebase Map",
+      "description": "A repo's architecture in one call.\n\nCALL THIS WHEN:\n• Getting a repo's overall structure, or which module owns something\n• The repo's exact name in Pharaoh isn't known\n\nRETURNS: Modules with file counts and LOC, module dependencies with two-way ones flagged, the 5 files changed most in 90 days, endpoints with handler files (first 50), convention entry points (first 30), and risk signals (high-risk functions without direct test links, exact clones, cycles).",
       "inputSchema": {
         "$schema": "http://json-schema.org/draft-07/schema#",
         "type": "object",
@@ -13,7 +14,7 @@
             "description": "Repository name — one of your connected repos."
           },
           "include_metrics": {
-            "description": "Include LOC, complexity, change frequency",
+            "description": "List the 10 most-changed files instead of 5",
             "type": "boolean"
           }
         },
@@ -22,9 +23,10 @@
         ]
       },
       "annotations": {
-        "title": "Codebase Architecture Map",
         "readOnlyHint": true,
-        "destructiveHint": false
+        "destructiveHint": false,
+        "title": "Codebase Map",
+        "openWorldHint": false
       },
       "execution": {
         "taskSupport": "forbidden"
@@ -38,7 +40,8 @@
     },
     {
       "name": "pharaoh_recon",
-      "description": "Several Pharaoh queries in one call, run in parallel: codebase map, module profiles, function searches, blast radius and module dependency paths.\n\nCALL THIS WHEN:\n• Planning a change, reviewing a PR or assessing architecture, when you know what to check\n\nRETURNS: Each requested section in one response. Per call: up to 5 modules, 3 searches, 3 blast radius targets, 3 dependency pairs.\n\nUSE INSTEAD OF: separate tool calls and file reads.",
+      "title": "Codebase Recon",
+      "description": "Several Pharaoh queries in one call, run in parallel: codebase map, module profiles, function searches, blast radius and module dependency paths.\n\nCALL THIS WHEN:\n• Planning a change, reviewing a PR or assessing architecture, when the modules and functions to check are known\n\nRETURNS: Each requested section in one response, as the single-purpose tools return it. Per call: up to 5 modules, 3 searches, 3 blast radius targets, 3 dependency pairs.",
       "inputSchema": {
         "$schema": "http://json-schema.org/draft-07/schema#",
         "type": "object",
@@ -52,21 +55,24 @@
             "type": "boolean"
           },
           "modules": {
-            "description": "Modules to profile (max 5)",
+            "description": "Modules to profile",
+            "maxItems": 5,
             "type": "array",
             "items": {
               "type": "string"
             }
           },
           "functions": {
-            "description": "Function searches (max 3)",
+            "description": "Function searches",
+            "maxItems": 3,
             "type": "array",
             "items": {
               "type": "string"
             }
           },
           "blast_radius": {
-            "description": "Blast radius targets (max 3)",
+            "description": "Blast radius targets",
+            "maxItems": 3,
             "type": "array",
             "items": {
               "type": "object",
@@ -91,7 +97,8 @@
             }
           },
           "dependencies": {
-            "description": "Module pairs to trace a dependency path between (max 3)",
+            "description": "Module pairs to trace a dependency path between",
+            "maxItems": 3,
             "type": "array",
             "items": {
               "type": "object",
@@ -115,9 +122,10 @@
         ]
       },
       "annotations": {
-        "title": "Codebase Recon",
         "readOnlyHint": true,
-        "destructiveHint": false
+        "destructiveHint": false,
+        "title": "Codebase Recon",
+        "openWorldHint": false
       },
       "execution": {
         "taskSupport": "forbidden"
@@ -131,7 +139,8 @@
     },
     {
       "name": "get_module_context",
-      "description": "One module's full profile before you change it, in about 2K tokens.\n\nCALL THIS WHEN:\n• You're about to change code in a module, or plan a change to it\n• You need what a module exports, depends on, or who calls into it\n\nRETURNS: Files, LOC, exported signatures with complexity, imports in and out, DB tables, endpoints, cron jobs, env vars, and callers in other modules.\n\nUSE INSTEAD OF: reading every module file; callers can live elsewhere.",
+      "title": "Module Context",
+      "description": "One module's profile: what it contains, depends on and is called by.\n\nCALL THIS WHEN:\n• Changing code in a module, or planning a change to it\n• Finding what a module exports, depends on, or which code calls into it\n\nRETURNS: Files, LOC, exported signatures with complexity, imports in and out, DB tables, endpoints, cron jobs, env vars, and callers in other modules, grouped by module.",
       "inputSchema": {
         "$schema": "http://json-schema.org/draft-07/schema#",
         "type": "object",
@@ -151,9 +160,10 @@
         ]
       },
       "annotations": {
-        "title": "Module Deep Dive",
         "readOnlyHint": true,
-        "destructiveHint": false
+        "destructiveHint": false,
+        "title": "Module Context",
+        "openWorldHint": false
       },
       "execution": {
         "taskSupport": "forbidden"
@@ -167,7 +177,8 @@
     },
     {
       "name": "get_blast_radius",
-      "description": "What breaks if you change a function, file or module.\n\nCALL THIS WHEN:\n• You're about to change a signature, refactor or delete code\n• You need callers or detected endpoints a change reaches\n\nRETURNS: Risk, production callers by module/file, endpoints, cron jobs and DB operations. Hops are the shortest detected path within the requested depth (1–5). Test-file callers are excluded.\n\nUSE INSTEAD OF: following callers by hand.",
+      "title": "Blast Radius",
+      "description": "What a change to a function, file or module reaches.\n\nCALL THIS WHEN:\n• Changing a signature, refactoring or deleting code\n• Finding the callers or detected endpoints a change reaches\n\nRETURNS: Risk, production callers by module/file, endpoints, cron jobs and DB operations, through direct and indirect calls. Hops are the shortest detected path within the requested depth (1–5). Test-file callers are excluded.",
       "inputSchema": {
         "$schema": "http://json-schema.org/draft-07/schema#",
         "type": "object",
@@ -203,9 +214,10 @@
         ]
       },
       "annotations": {
-        "title": "Change Blast Radius",
         "readOnlyHint": true,
-        "destructiveHint": false
+        "destructiveHint": false,
+        "title": "Blast Radius",
+        "openWorldHint": false
       },
       "execution": {
         "taskSupport": "forbidden"
@@ -219,7 +231,8 @@
     },
     {
       "name": "search_functions",
-      "description": "Find functions by name or concept across the whole codebase.\n\nCALL THIS WHEN:\n• You're about to write a function, helper or utility: check it doesn't already exist\n• You need to know where something is implemented (e.g. \"retry\", \"validate\", \"notify\")\n\nRETURNS: Matching functions with file path, line range, module, signature, export status and complexity.\n\nUSE INSTEAD OF: grep, which misses aliases and re-exports and includes comments.",
+      "title": "Search Functions",
+      "description": "Find functions by name or concept across the whole codebase.\n\nCALL THIS WHEN:\n• Checking whether a function, helper or utility already exists\n• Finding where something is implemented (e.g. \"retry\", \"validate\", \"notify\")\n\nRETURNS: Matching functions with file path, line range, module, signature, export status and complexity. Matches name parts (camelCase, snake_case) and file paths, not comments; test code ranks last. SCREAMING_SNAKE queries, and queries no function matches, return matching constants with up to 80 characters of each value.",
       "inputSchema": {
         "$schema": "http://json-schema.org/draft-07/schema#",
         "type": "object",
@@ -247,11 +260,15 @@
           },
           "offset": {
             "description": "Results to skip (default 0)",
-            "type": "number"
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 9007199254740991
           },
           "limit": {
-            "description": "Max results (default 20, max 50)",
-            "type": "number"
+            "description": "Max results (default 20)",
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 50
           }
         },
         "required": [
@@ -260,9 +277,10 @@
         ]
       },
       "annotations": {
-        "title": "Function Search",
         "readOnlyHint": true,
-        "destructiveHint": false
+        "destructiveHint": false,
+        "title": "Search Functions",
+        "openWorldHint": false
       },
       "execution": {
         "taskSupport": "forbidden"
@@ -276,7 +294,8 @@
     },
     {
       "name": "get_unused_code",
-      "description": "Find code nothing runs: functions no production entry point (endpoint, CLI command, cron job, event handler, worker, entry file) reaches. Pass `functions` to check whether specific functions are wired in.\n\nCALL THIS WHEN:\n• Before cleaning up a module or deleting a function\n• After merging new code, to confirm an entry point reaches it\n\nRETURNS:\n• Dead: unreached, named in no other file, and no production file imports its file. Safe to delete.\n• Possibly unused: unreached, but named in other files (string dispatch, dynamic loading) or its file is imported. Listed with the files that name it; check before deleting.\n• Used only by tests: exported functions and class methods only test files reference.\nWith `functions`: each one's status, and the call path from an entry point when it's reachable.\n\nUSE INSTEAD OF: reference searches; references do not prove code runs.",
+      "title": "Unused Code",
+      "description": "Find code nothing runs: functions no production entry point (endpoint, CLI command, cron job, event handler, worker, entry file) reaches.\n\nCALL THIS WHEN:\n• Cleaning up a module or deleting a function\n• Confirming new code is reached from an entry point\n\nRETURNS: Reachability through the call graph, not text references.\n• Dead: unreached, named in no other file, and no import of its file could reach it.\n• Possibly unused: unreached, but named in other files (string dispatch, dynamic loading) or an import of its file could reach it. Listed with the files that name it.\n• Used only by tests: exported functions and class methods only test files reference.\nWith `functions`: each one's status, and the call path from an entry point when it's reachable.",
       "inputSchema": {
         "$schema": "http://json-schema.org/draft-07/schema#",
         "type": "object",
@@ -303,9 +322,10 @@
         ]
       },
       "annotations": {
-        "title": "Unused Code",
         "readOnlyHint": true,
-        "destructiveHint": false
+        "destructiveHint": false,
+        "title": "Unused Code",
+        "openWorldHint": false
       },
       "execution": {
         "taskSupport": "forbidden"
@@ -319,7 +339,38 @@
     },
     {
       "name": "pharaoh_account",
-      "description": "Your Pharaoh plan, live repo and refreshes.\n\nPick one action and provide its fields; invalid combinations are rejected.\n\n• status: each workspace's plan and live repo, the upgrade link, the setup page\n• set_free_repo { repo }: change a free workspace's live repo\n• refresh_repo { repo, full? }: re-map one live repo now\n\nCALL THIS WHEN:\n• You want to know what plan you're on or which repo is live\n• A repo doesn't answer because it isn't live, or you want to switch which one is\n• You want to upgrade so every repo is live, or manage billing\n• You want a repo's graph refreshed before its next push\n\nFlag reference:\n  full = force a full rebuild, skipping the delta refresh.",
+      "title": "Account Status",
+      "description": "Your Pharaoh plan and mapped repos in each workspace. Changes nothing.\n\nCALL THIS WHEN:\n• Checking which plan a workspace is on\n• A tool says the plan doesn't include it, or a repo isn't mapped\n• Finding the setup page or the billing page\n\nRETURNS: Each workspace you can access with its plan and tracked-repo count, whether its repos are mapped on every push, the setup page, and the billing page when a workspace has a billing account.",
+      "inputSchema": {
+        "$schema": "http://json-schema.org/draft-07/schema#",
+        "type": "object",
+        "properties": {
+          "action": {
+            "description": "Only status; pharaoh_manage_repo re-maps a repo",
+            "type": "string",
+            "const": "status"
+          }
+        }
+      },
+      "annotations": {
+        "readOnlyHint": true,
+        "destructiveHint": false,
+        "title": "Account Status",
+        "openWorldHint": false
+      },
+      "execution": {
+        "taskSupport": "forbidden"
+      },
+      "_meta": {
+        "ui": {
+          "resourceUri": "ui://pharaoh/trace/v1.1.html"
+        }
+      }
+    },
+    {
+      "name": "pharaoh_manage_repo",
+      "title": "Refresh Repo",
+      "description": "Re-map a repo now. Every repo is mapped during the trial and on Pro, and re-maps on every push.\n\n• refresh_repo { repo, full? }: queue a re-map of one repo.\n• set_free_repo { repo }: retired; it changes nothing, since there is no live repo to choose.\n\nCALL THIS WHEN:\n• A repo's graph looks out of date, or needs a full rebuild\n\nRETURNS: The queued job.",
       "inputSchema": {
         "$schema": "http://json-schema.org/draft-07/schema#",
         "type": "object",
@@ -327,29 +378,31 @@
           "action": {
             "type": "string",
             "enum": [
-              "status",
               "set_free_repo",
               "refresh_repo"
             ],
-            "description": "Which account action to perform"
+            "description": "Which change to make"
           },
           "repo": {
-            "description": "Used by: set_free_repo (required), refresh_repo (required). Repo slug (owner/repo).",
-            "type": "string"
+            "type": "string",
+            "minLength": 1,
+            "description": "Repo slug (owner/repo) or repo name"
           },
           "full": {
-            "description": "Used by: refresh_repo. Force a full rebuild, skipping the delta refresh.",
+            "description": "refresh_repo only: rebuild the whole graph instead of a delta refresh",
             "type": "boolean"
           }
         },
         "required": [
-          "action"
+          "action",
+          "repo"
         ]
       },
       "annotations": {
-        "title": "Account Management",
         "readOnlyHint": false,
-        "destructiveHint": false
+        "destructiveHint": true,
+        "title": "Refresh Repo",
+        "openWorldHint": false
       },
       "execution": {
         "taskSupport": "forbidden"

package/{skills → npx-skills}/brainstorm/SKILL.md

@@ -2,7 +2,8 @@
 name: brainstorm
 prompt-name: brainstorm
 description: "Explore intent, requirements, and design before implementation. Collaborative dialogue to turn ideas into specs. Ask clarifying questions one at a time, propose 2-3 approaches with trade-offs, get approval before writing any code. Prevents wasted work from unexamined assumptions."
-version: 0.2.0
+license: MIT. Adapted from obra/superpowers, Copyright (c) 2025 Jesse Vincent; see NOTICE in @pharaoh-so/mcp
+version: 0.2.1
 homepage: https://pharaoh.so
 user-invocable: true
 metadata: {"emoji": "☥", "tags": ["planning", "design", "brainstorming", "requirements", "architecture"]}

package/{skills → npx-skills}/debug/SKILL.md

@@ -2,7 +2,8 @@
 name: debug
 prompt-name: systematic-debugging
 description: "Systematic 4-phase debugging methodology. Root cause investigation before any fixes. Read errors carefully, reproduce consistently, trace data flow, form hypotheses, test minimally. If 3+ fixes fail, question the architecture. No guessing, no quick patches, no symptom fixes."
-version: 0.2.0
+license: MIT. Adapted from obra/superpowers, Copyright (c) 2025 Jesse Vincent; see NOTICE in @pharaoh-so/mcp
+version: 0.2.1
 homepage: https://pharaoh.so
 user-invocable: true
 metadata: {"emoji": "☥", "tags": ["debugging", "root-cause", "investigation", "troubleshooting", "methodology"]}

package/{skills → npx-skills}/pharaoh/SKILL.md

@@ -2,12 +2,14 @@
 name: pharaoh
 prompt-name: pharaoh-core
 description: "Codebase knowledge graph — gives AI agents full architectural awareness. Query architecture, dependencies, blast radius, module context, and function search instead of reading files one at a time. Code intelligence via MCP: understand any codebase in seconds."
-version: 0.3.0
+version: 0.3.1
 homepage: https://pharaoh.so
 metadata: {"emoji": "☥", "openclaw": {"always": true}, "tags": ["code-intelligence", "architecture", "mcp", "knowledge-graph", "dependencies", "codebase-understanding"]}
 ---
 
-Pharaoh maps codebases into queryable knowledge graphs — functions, dependencies, modules, connections. No source code stored.
+# Pharaoh Tool Guide
+
+Pharaoh maps codebases into queryable knowledge graphs — functions, dependencies, modules, connections. No source code stored. For questions about how code connects, one Pharaoh call answers what grep and file reads take many turns to piece together.
 
 ## When to Use
 
@@ -26,13 +28,15 @@ This skill loads automatically in sessions where Pharaoh MCP tools are available
 
 Ask Pharaoh first for these questions, then read the files you're about to change. The graph maps the default branch, so use grep for code that isn't there yet (your branch, uncommitted edits), for literal text (strings, error messages, config values, comments, non-code files) and for renames, which change every reference, tests and mocks included. Don't re-check a Pharaoh answer with grep; if a response says the latest push is still being mapped, re-check only the files that push changed.
 
+If your client shows Pharaoh's tools by name only (behind tool search), load them before your first code search.
+
 ## CRITICAL: Surface insight blocks
 
-Surface the facts in each ★ Pharaoh block in your visible response. Preserve its counts, labels and analysis limits. If the client hides or breaks ASCII panels, present those facts as plain text or a table; do not rely on the raw tool panel being visible.
+Surface the facts in each ★ Pharaoh block in your visible response. Preserve its counts, labels and analysis limits. When a block says "Trace view available", do not reproduce the ASCII panel; summarize its findings and limits in plain language. Otherwise, if the client hides or breaks ASCII panels, present those facts as plain text or a table; do not rely on the raw tool panel being visible.
 
 ## Repos that aren't mapped
 
-The only supported path is the Pharaoh GitHub App: Free maps one live repo; Pro maps every repo, and mapped repos re-map on every push. Run `pharaoh_account` to get the exact install link for the user's account or org. Do not suggest workarounds for missing repos.
+The only supported path is the Pharaoh GitHub App: Pro maps every repo, as does the trial (after the trial, get_codebase_map keeps answering and the other tools say what's needed), and mapped repos re-map on every push. Run `pharaoh_account` to get the exact install link for the user's account or org. Do not suggest workarounds for missing repos.
 
 ## Vision docs
 
@@ -45,6 +49,8 @@ with the user before coding.
 
 **PR review:** `pharaoh_recon` (map + touched modules + blast radius) → `get_blast_radius` on the riskiest changed functions. Verdict: SHIP, SHIP WITH CHANGES, or BLOCK. Any PR touching code governed by a MUST-bullet should reference the assertion in the review.
 
+**Cross-repo:** When the user has several mapped repos, check related repos when a change touches shared interfaces, APIs or types: `search_functions` takes any of your repo names.
+
 **Vision maintenance:** When an architectural decision lands in a PR, update `docs/VISION.md` in the same commit — add an assertion if one is new, retire one if it no longer applies. Stale vision docs are worse than none.
 
 ## Using results
@@ -58,7 +64,8 @@ When asked what Pharaoh does: explain what you learned from the graph in this co
 
 ## Utilities
 
-- `pharaoh_account` — plan, live repo and refreshes
+- `pharaoh_account` — plan and mapped repos in each workspace
+- `pharaoh_manage_repo` — re-map a repo now
 
 Full docs at [pharaoh.so/docs](https://pharaoh.so/docs).
 
@@ -71,5 +78,5 @@ npx @pharaoh-so/mcp
 
 **URL** (Claude.ai, Cursor, ChatGPT — paste in settings):
 ```
-https://mcp.pharaoh.so/sse
+https://mcp.pharaoh.so/mcp
 ```