@magic-spells/constellation 0.1.1 → 0.2.1

package/dist/mcp/server.js

@@ -4,14 +4,15 @@ import { fileURLToPath } from 'node:url';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
-import { isHandleShaped, isKnownHandle, typeForHandle } from '../core/handles.js';
+import { isHandleShaped, isKnownHandle, TYPE_FOLDERS, typeForHandle, } from '../core/handles.js';
 import { loadPlan } from '../core/indexer.js';
 import { lintPlan } from '../core/lint.js';
 import { resolvePlanDir } from '../core/resolve.js';
 import { TYPE_NAMES } from '../core/types.js';
-import { diffPlan, planDirty, planLog, writeSyncPoint } from './git.js';
+import { diffPlan, planDirty, planLog, writeSyncPoint } from '../core/git.js';
 import { searchCards } from './search.js';
 import { applyCardPatch, createCardFile, deepMerge, relPathForHandle, reservedFieldKeys, updateCardFile, } from '../core/writer.js';
+import { connectedRepoToFm, listConnectedRepos, readConnectedRepos, removeConnectedRepoEntry, resolveConnectedRepo, upsertConnectedRepo, } from '../core/repos.js';
 const INSTRUCTIONS = `# Constellation MCP
 
 The project's architecture plan lives as markdown files in a constellation/ folder.
@@ -27,6 +28,11 @@ Writes are validated: every write tool lints and returns issues for the file it
 update_card patch.fields deep-merges (arrays replace, null deletes); body replaces.
 Body-only updates never reformat frontmatter.
 
+describe_type is the type reference, served by this server: call it with no args for the
+catalog of all 17 card types, or with a type (e.g. describe_type PAGE) for that type's
+frontmatter schema + a golden example. Consult it before authoring a type you haven't used
+this session — you don't need the authoring skill loaded to get the fields right.
+
 Change tracking is git: diff_plan reports per-card changes since the sync marker (or HEAD).
 Never stamp dirty flags into cards.
 
@@ -47,6 +53,22 @@ macro view. ALWAYS verify the sub-agents' work yourself after they have all fini
 each change against its cards and run the build/tests; never trust their reports alone — then
 set the sync point once.
 
+Plan-first when changing code: when asked to build a feature or change behavior in an area
+this plan covers, do NOT edit code first. The plan you make leads with Constellation — read
+the affected neighborhood (get_card / traverse / search, connected: "full"), then add or
+update the cards so they describe the desired END STATE (work that isn't built yet is
+status: planned), wiring every connection between the affected cards. Show that set of card
+changes as the proposal; on approval, bring the CODE up to match via the sync loop above.
+FINISH by reconciling — re-read the touched cards against the code, run check_integrity so
+no affected card is left an orphan and every connection is set, bump status (planned →
+building → built → verified), commit, and set_sync_point. In plan mode the write tools are
+unavailable by design (the read tools — get_card, list_cards, search, traverse,
+describe_type, check_integrity, diff_plan, plan_log — are marked read-only and stay
+available), so spend plan mode READING: pull in as much of the relevant plan as you can
+(traverse from the entry points, connected: "full") to build a strong model of the project
+fast, fold the intended card edits into the plan you present, and write them to
+Constellation first, before any code, once the user approves.
+
 For migrations or large scaffolds, use create_cards and add_connections (batched, one
 lint pass) instead of many single calls — connections between cards in the same batch
 resolve without transient "does not resolve" errors. A card is created even when issues
@@ -74,7 +96,7 @@ and confirm it with the user (it's plan.md's name: and the viewer's title; chang
 anytime via update_card on PLAN-PROJECT); then follow the DATA (DB → DATATYPE →
 API → PAGE, with FLOW/STATE for paths and lifecycles) and the USER (ROLE + auth FLOW
 first, then PAGE/COMPONENT and key journeys) and the EDGES (EXTERNAL/JOB/EVENT); then zoom
-into central or complex areas. Read before you ask — ask the user only for intent,
+into central or complex areas. For a non-trivial plan, after the macro pass act as the ORCHESTRATOR here too: partition the build into independent neighborhoods (the DATA, the USER, the EDGES) and fan out a sub-agent per neighborhood in parallel — but assign each card to exactly one agent (two agents calling update_card on the same card race, later write wins) and have them return card specs you write via batched create_cards/add_connections, then verify each agent's work and lint once; use one agent for a small plan. Read before you ask — ask the user only for intent,
 priorities, and history the code can't reveal. Then find gaps IN THE PLAN: step back and
 hunt blind spots the user may not have considered — missing unhappy paths and lifecycle
 states, auth/permission gaps, and cross-cutting concerns plans forget (security, privacy,
@@ -84,6 +106,21 @@ short, prioritized list of recommendations and ask about the judgment calls. For
 method use the bootstrap_plan or audit_plan prompt. Status is planned → building → built →
 verified; verify only against real code.
 
+Connected repos (multi-repo work): a project can declare sibling repos in PLAN-PROJECT
+connected_repos (name + on-disk path + description) — list_connected_repos shows them with
+reachability, add_connected_repo links one (reciprocate:true also writes the reverse link
+into the other repo, with the user's OK). These are REPO-level links only: cards never connect
+across repos, and each repo's plan stays self-contained and lints alone. To work on a connected
+repo, pass repo: "<name>" to any read or write tool (get_card, search, traverse, update_card,
+…) and it reads/writes THAT repo's plan; omit repo for the current one. To answer a question
+about a connected repo, first read its plan with repo:; if you need the real code (or its plan
+can't answer), spawn a sub-agent scoped to that repo's path to investigate and report back —
+and if its plan had the gap, fill it. For one change spanning repos: examine each repo's area,
+write the per-repo card updates with repo: set on EVERY write (never omit it cross-repo, or the
+write lands in the wrong place), then fan out a per-repo implementer sub-agent (each runs in
+plain single-repo mode, blind to the others) and reconcile + set_sync_point per repo. Inside a
+single repo, repo is unnecessary and everything behaves exactly as before.
+
 To let the user browse the plan visually, start_viewer launches a local web server that
 renders the plan as an editable site and returns its URL (it scans forward from port 4747
 for a free port, so always read the actual port from the response). ALWAYS post that URL
@@ -92,7 +129,38 @@ The viewer runs until stop_viewer or until this server process exits.`;
 // The full plan-from-code playbook lives in one file (skill/methodology.md), shared by the
 // skill and the MCP prompts so the two can't drift. Resolve it relative to this module:
 // from dist/mcp/server.js (or src/mcp/server.ts) '../..' is the package/repo root.
-const METHODOLOGY_PATH = path.join(fileURLToPath(new URL('../..', import.meta.url)), 'skill', 'methodology.md');
+// Package root: from dist/mcp/server.js (or src/mcp/server.ts) '../..' is the
+// package/repo root. The skill folder, type docs, and JSON schemas all ship here.
+const PKG_ROOT = fileURLToPath(new URL('../..', import.meta.url));
+const METHODOLOGY_PATH = path.join(PKG_ROOT, 'skill', 'methodology.md');
+const SCHEMAS_DIR = path.join(PKG_ROOT, 'schemas');
+const TYPE_DOCS_DIR = path.join(PKG_ROOT, 'skill', 'types');
+/** Parsed JSON Schema for a type's frontmatter, or null if it can't be read. */
+async function readTypeSchema(folder) {
+    try {
+        return JSON.parse(await readFile(path.join(SCHEMAS_DIR, `${folder}.json`), 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+/** The authoring reference (field table + golden example) for a type, or null. */
+async function readTypeDoc(folder) {
+    try {
+        return await readFile(path.join(TYPE_DOCS_DIR, `${folder}.md`), 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+/** First sentence of a schema's top-level description — its one-line purpose. */
+function schemaPurpose(schema) {
+    const desc = schema && typeof schema === 'object' && 'description' in schema
+        ? String(schema.description ?? '')
+        : '';
+    const match = desc.match(/^.*?\.(?:\s|$)/);
+    return (match ? match[0] : desc).trim();
+}
 let methodologyCache = null;
 async function methodologyText() {
     if (methodologyCache === null) {
@@ -120,6 +188,25 @@ function fail(code, message) {
         isError: true,
     };
 }
+async function openUrl(url) {
+    try {
+        const { spawn } = await import('node:child_process');
+        const child = process.platform === 'darwin'
+            ? spawn('open', [url], { stdio: 'ignore', detached: true })
+            : process.platform === 'win32'
+                ? spawn('cmd', ['/c', 'start', '', url], {
+                    stdio: 'ignore',
+                    detached: true,
+                    windowsHide: true,
+                })
+                : spawn('xdg-open', [url], { stdio: 'ignore', detached: true });
+        child.on('error', () => { });
+        child.unref();
+    }
+    catch {
+        // Opening the browser is best-effort; callers still receive the URL.
+    }
+}
 function summary(card) {
     return {
         handle: card.handle,
@@ -147,8 +234,12 @@ function issuesForFile(issues, relPath) {
 const detailSchema = z.enum(['none', 'summary', 'full']);
 const typeSchema = z.enum(TYPE_NAMES);
 const statusSchema = z.enum(['planned', 'building', 'built', 'verified']);
+const repoSchema = z
+    .string()
+    .optional()
+    .describe('Target a connected repo by its connected_repos name (or a path). Omit to use the current repo.');
 export function buildServer(options = {}) {
-    const server = new McpServer({ name: 'constellation', version: '0.1.1' }, { instructions: INSTRUCTIONS });
+    const server = new McpServer({ name: 'constellation', version: '0.2.1' }, { instructions: INSTRUCTIONS });
     server.registerPrompt('bootstrap_plan', {
         title: 'Bootstrap a plan from the codebase',
         description: 'Analyze this repository macro→micro and build (or extend) the Constellation plan: follow the data and the user/auth journeys, capture flows, diagrams, and state machines, ask the user what the code cannot answer, and flag gaps.',
@@ -182,18 +273,48 @@ export function buildServer(options = {}) {
     }
     // A single web viewer owned by this server process; null until start_viewer runs.
     let viewer = null;
-    /** Wrap a handler with plan resolution and error reporting. */
+    const noPlanFound = () => fail('NO_PLAN_FOUND', `No constellation/ folder found by walking up from ${process.cwd()}. This MCP ` +
+        `server uses its own working directory — if that isn't your repo, set "cwd" to ` +
+        'the repo root in your MCP client config. Otherwise call init_plan (optionally ' +
+        'with { path } pointing at the repo root), or run `constellation init`.');
+    /**
+     * Resolve which plan a call targets. With no `repo`, the home plan (walk up
+     * from cwd); with `repo`, a connected repo selected by its connected_repos
+     * name or by a path. Returns the resolved root or a ready-to-return error.
+     */
+    async function resolveTarget(repo) {
+        const home = await planRoot();
+        if (!repo) {
+            return home ? { root: home } : { error: noPlanFound() };
+        }
+        if (home) {
+            const resolved = await resolveConnectedRepo(home, repo);
+            if (resolved)
+                return { root: resolved.root };
+            const names = (await readConnectedRepos(home)).map((r) => r.name);
+            return {
+                error: fail('UNKNOWN_REPO', `Connected repo "${repo}" not found. Pass a connected_repos name ` +
+                    `(${names.length ? names.join(', ') : 'none declared — add one with add_connected_repo'}) ` +
+                    'or a path to a repo that has a constellation/ plan.'),
+            };
+        }
+        // No home plan: a name can't be looked up, but a path can still resolve.
+        const byPath = await resolvePlanDir(path.isAbsolute(repo) ? repo : path.resolve(process.cwd(), repo));
+        if (byPath)
+            return { root: byPath };
+        return {
+            error: fail('UNKNOWN_REPO', `No plan found for repo "${repo}". With no plan in the current directory, pass a ` +
+                'path to a repo that has a constellation/ plan.'),
+        };
+    }
+    /** Wrap a handler with plan resolution and error reporting; `repo` selects a connected repo. */
     function withPlan(handler) {
         return async (args) => {
-            const root = await planRoot();
-            if (!root) {
-                return fail('NO_PLAN_FOUND', `No constellation/ folder found by walking up from ${process.cwd()}. This MCP ` +
-                    `server uses its own working directory — if that isn't your repo, set "cwd" to ` +
-                    'the repo root in your MCP client config. Otherwise call init_plan (optionally ' +
-                    'with { path } pointing at the repo root), or run `constellation init`.');
-            }
+            const target = await resolveTarget(args?.repo);
+            if ('error' in target)
+                return target.error;
             try {
-                return await handler(root, args);
+                return await handler(target.root, args);
             }
             catch (err) {
                 return fail('INTERNAL', err instanceof Error ? err.message : String(err));
@@ -227,10 +348,12 @@ export function buildServer(options = {}) {
         }
     });
     server.registerTool('get_card', {
+        annotations: { readOnlyHint: true },
         description: 'Fetch one card by handle, optionally with all connected cards hydrated. connected: "full" returns the complete frontmatter and body of every connected card — use it when about to work on an area.',
         inputSchema: {
             handle: z.string(),
             connected: detailSchema.optional().describe('default: summary'),
+            repo: repoSchema,
         },
     }, withPlan(async (root, { handle, connected }) => {
         const index = await loadPlan(root);
@@ -243,6 +366,7 @@ export function buildServer(options = {}) {
         });
     }));
     server.registerTool('list_cards', {
+        annotations: { readOnlyHint: true },
         description: 'Catalog of cards filtered by type, kind, status, and/or connectedness. connected:false returns orphans (cards with zero connections). Returns summaries (handle, type, kind, name, status).',
         inputSchema: {
             types: z.array(typeSchema).optional(),
@@ -253,6 +377,7 @@ export function buildServer(options = {}) {
                 .optional()
                 .describe('false = orphans only; true = connected only'),
             limit: z.number().int().min(1).max(500).optional(),
+            repo: repoSchema,
         },
     }, withPlan(async (root, { types, kind, status, connected, limit }) => {
         const index = await loadPlan(root);
@@ -270,12 +395,14 @@ export function buildServer(options = {}) {
         });
     }));
     server.registerTool('search', {
+        annotations: { readOnlyHint: true },
         description: 'Scored full-text search over handles, names, kinds, and bodies. Set connected: "full" to hydrate each match with the complete content of its connected cards — fuzzy query to working context in one call.',
         inputSchema: {
             q: z.string(),
             types: z.array(typeSchema).optional(),
             limit: z.number().int().min(1).max(100).optional(),
             connected: detailSchema.optional().describe('default: none'),
+            repo: repoSchema,
         },
     }, withPlan(async (root, { q, types, limit, connected }) => {
         const index = await loadPlan(root);
@@ -290,12 +417,14 @@ export function buildServer(options = {}) {
         });
     }));
     server.registerTool('traverse', {
+        annotations: { readOnlyHint: true },
         description: 'Breadth-first walk of the connection graph from one or more starting handles. Seed it with diff_plan output for impact analysis. detail: "full" includes frontmatter and body of every reached card.',
         inputSchema: {
             start: z.union([z.string(), z.array(z.string()).min(1)]),
             depth: z.number().int().min(0).max(5).optional().describe('default: 2'),
             types: z.array(typeSchema).optional(),
             detail: z.enum(['summary', 'full']).optional().describe('default: summary'),
+            repo: repoSchema,
         },
     }, withPlan(async (root, { start, depth, types, detail }) => {
         const index = await loadPlan(root);
@@ -339,8 +468,41 @@ export function buildServer(options = {}) {
         const connections = index.connections.filter((c) => distance.has(c.a) && distance.has(c.b));
         return ok({ cards, connections, not_found: missing });
     }));
+    server.registerTool('describe_type', {
+        annotations: { readOnlyHint: true },
+        description: 'The card-type reference, served straight from this package. Call with no args for the catalog — all 17 types with their prefix, folder, and one-line purpose. Call with a type for everything needed to author one: the frontmatter JSON Schema (fields, which are required, descriptions) plus the golden example and authoring guidance. Use it before writing a card of a type you have not authored this session — it is the contract create_card/create_cards/update_card validate against (W002/W003), so you do not need the authoring skill loaded to get the fields right.',
+        inputSchema: {
+            type: typeSchema.optional().describe('omit for the full catalog'),
+        },
+    }, async ({ type }) => {
+        if (!type) {
+            const types = await Promise.all(TYPE_NAMES.map(async (t) => {
+                const folder = TYPE_FOLDERS[t];
+                return {
+                    type: t,
+                    prefix: `${t}-`,
+                    folder,
+                    purpose: schemaPurpose(await readTypeSchema(folder)),
+                };
+            }));
+            return ok({ types });
+        }
+        const folder = TYPE_FOLDERS[type];
+        const [schema, reference] = await Promise.all([
+            readTypeSchema(folder),
+            readTypeDoc(folder),
+        ]);
+        return ok({
+            type,
+            prefix: `${type}-`,
+            folder,
+            reserved: ['name', 'kind', 'status', 'connections'],
+            schema,
+            reference,
+        });
+    });
     server.registerTool('create_card', {
-        description: 'Create a new card. The handle determines type and file location. fields = type-specific frontmatter (see the type schemas); body = markdown. The card IS created even when issues are returned — issues are the current lint state, not a failure. Set validate:false to skip linting during bulk import (then run check_integrity once at the end). For many cards at once, prefer create_cards.',
+        description: 'Create a new card. The handle determines type and file location. fields = type-specific frontmatter — call describe_type(type) first for its field schema and a golden example; body = markdown. The card IS created even when issues are returned — issues are the current lint state, not a failure. Set validate:false to skip linting during bulk import (then run check_integrity once at the end). For many cards at once, prefer create_cards.',
         inputSchema: {
             handle: z.string(),
             name: z.string().optional(),
@@ -353,6 +515,7 @@ export function buildServer(options = {}) {
                 .boolean()
                 .optional()
                 .describe('default true; false skips lint and returns no issues'),
+            repo: repoSchema,
         },
     }, withPlan(async (root, args) => {
         const handle = args.handle.toUpperCase();
@@ -411,6 +574,7 @@ export function buildServer(options = {}) {
             }))
                 .min(1)
                 .max(500),
+            repo: repoSchema,
         },
     }, withPlan(async (root, { cards }) => {
         const index = await loadPlan(root);
@@ -479,6 +643,7 @@ export function buildServer(options = {}) {
                 .array(z.object({ from: z.string(), to: z.string() }))
                 .min(1)
                 .max(1000),
+            repo: repoSchema,
         },
     }, withPlan(async (root, { connections }) => {
         const index = await loadPlan(root);
@@ -509,7 +674,7 @@ export function buildServer(options = {}) {
         for (const [src, targets] of additions) {
             const card = index.cards.get(src);
             const existingList = Array.isArray(card.frontmatter.connections)
-                ? card.frontmatter.connections
+                ? card.frontmatter.connections.filter((c) => typeof c === 'string')
                 : [];
             const merged = [...new Set([...existingList, ...targets])];
             const frontmatter = applyCardPatch(card.frontmatter, { connections: merged });
@@ -534,6 +699,7 @@ export function buildServer(options = {}) {
             })
                 .optional(),
             body: z.string().optional(),
+            repo: repoSchema,
         },
     }, withPlan(async (root, { handle, patch, body }) => {
         const index = await loadPlan(root);
@@ -560,7 +726,7 @@ export function buildServer(options = {}) {
     }));
     server.registerTool('delete_card', {
         description: 'Delete a card file. Returns the handles that referenced it (their references are now dangling) plus resulting lint issues.',
-        inputSchema: { handle: z.string() },
+        inputSchema: { handle: z.string(), repo: repoSchema },
     }, withPlan(async (root, { handle }) => {
         const index = await loadPlan(root);
         const card = index.cards.get(handle.toUpperCase());
@@ -580,7 +746,7 @@ export function buildServer(options = {}) {
     }));
     server.registerTool('add_connection', {
         description: 'Connect two cards by appending `to` to `from`’s connections list. No-op if they are already connected through any source.',
-        inputSchema: { from: z.string(), to: z.string() },
+        inputSchema: { from: z.string(), to: z.string(), repo: repoSchema },
     }, withPlan(async (root, args) => {
         const index = await loadPlan(root);
         const from = index.cards.get(args.from.toUpperCase());
@@ -607,7 +773,7 @@ export function buildServer(options = {}) {
     }));
     server.registerTool('remove_connection', {
         description: 'Remove a connection by deleting it from either card’s connections list. Reports if the cards remain connected through other sources (frontmatter fields, body links, mermaid) that must be edited manually.',
-        inputSchema: { a: z.string(), b: z.string() },
+        inputSchema: { a: z.string(), b: z.string(), repo: repoSchema },
     }, withPlan(async (root, args) => {
         const index = await loadPlan(root);
         const cardA = index.cards.get(args.a.toUpperCase());
@@ -659,9 +825,130 @@ export function buildServer(options = {}) {
             issues: lint.issues.filter((i) => touched.has(i.file)),
         });
     }));
+    server.registerTool('list_connected_repos', {
+        annotations: { readOnlyHint: true },
+        description: 'List the sibling repos declared on PLAN-PROJECT connected_repos, each with its path, description, and whether it is reachable on this machine. Use a name as the `repo` selector on other tools to read or write that repo. Repo-level links only — not card connections.',
+        inputSchema: { repo: repoSchema },
+    }, withPlan(async (root) => {
+        const repos = await listConnectedRepos(root);
+        return ok({
+            connected_repos: repos.map((r) => ({
+                name: r.name,
+                path: r.path,
+                description: r.description ?? null,
+                reachable: r.reachable,
+            })),
+        });
+    }));
+    server.registerTool('add_connected_repo', {
+        description: 'Declare a sibling repo on PLAN-PROJECT connected_repos (a repo-level link, not a card connection). name is the lowercase `repo` selector; path is relative to this repo root (e.g. ../pyramid-server). reciprocate:true also writes the reverse link into the target repo — only do this with the user’s OK, since it edits the other repo. Upserts by name.',
+        inputSchema: {
+            name: z
+                .string()
+                .describe('lowercase id used as the `repo` selector (e.g. pyramid-server)'),
+            path: z
+                .string()
+                .describe('path to the connected repo root, relative to this repo (e.g. ../pyramid-server)'),
+            description: z.string().optional(),
+            reciprocate: z
+                .boolean()
+                .optional()
+                .describe('also add the reverse link into the target repo (writes there). default false'),
+            reverse_description: z
+                .string()
+                .optional()
+                .describe('description for the reverse link when reciprocate is set; defaults to none'),
+            repo: repoSchema,
+        },
+    }, withPlan(async (root, args) => {
+        const { name, path: repoPath, description, reciprocate, reverse_description } = args;
+        if (!/^[a-z0-9][a-z0-9-]*$/.test(name)) {
+            return fail('INVALID_NAME', `"${name}" is not a valid repo name (lowercase letters, digits, and hyphens).`);
+        }
+        const index = await loadPlan(root);
+        const planCard = index.cards.get('PLAN-PROJECT');
+        if (!planCard) {
+            return fail('NO_PLAN_PROJECT', 'No plan.md (PLAN-PROJECT) at the plan root to record connected_repos on.');
+        }
+        const entry = { name, path: repoPath, description };
+        const next = upsertConnectedRepo(await readConnectedRepos(root), entry);
+        const frontmatter = applyCardPatch(planCard.frontmatter, {
+            fields: { connected_repos: next.map(connectedRepoToFm) },
+        });
+        await updateCardFile(planCard.filePath, { frontmatter });
+        let reciprocated;
+        if (reciprocate) {
+            const target = await resolveConnectedRepo(root, repoPath);
+            if (!target) {
+                reciprocated = { ok: false, reason: 'target repo not reachable (no plan found at path)' };
+            }
+            else {
+                const targetPlan = (await loadPlan(target.root)).cards.get('PLAN-PROJECT');
+                if (!targetPlan) {
+                    reciprocated = { ok: false, reason: 'target repo has no plan.md (PLAN-PROJECT)' };
+                }
+                else {
+                    const homeRepoRoot = path.dirname(root);
+                    const reverseName = path
+                        .basename(homeRepoRoot)
+                        .toLowerCase()
+                        .replace(/[^a-z0-9-]/g, '-')
+                        .replace(/^-+|-+$/g, '') || 'home';
+                    const reverseEntry = {
+                        name: reverseName,
+                        path: path.relative(target.repoRoot, homeRepoRoot) || '.',
+                        description: reverse_description,
+                    };
+                    const targetNext = upsertConnectedRepo(await readConnectedRepos(target.root), reverseEntry);
+                    await updateCardFile(targetPlan.filePath, {
+                        frontmatter: applyCardPatch(targetPlan.frontmatter, {
+                            fields: { connected_repos: targetNext.map(connectedRepoToFm) },
+                        }),
+                    });
+                    reciprocated = {
+                        ok: true,
+                        repo_root: target.repoRoot,
+                        entry: connectedRepoToFm(reverseEntry),
+                    };
+                }
+            }
+        }
+        const lint = await lintPlan(root);
+        return ok({
+            connected_repos: next.map(connectedRepoToFm),
+            reciprocated,
+            issues: issuesForFile(lint.issues, planCard.relPath),
+        });
+    }));
+    server.registerTool('remove_connected_repo', {
+        description: 'Remove a sibling repo from PLAN-PROJECT connected_repos by name. Does not touch the other repo.',
+        inputSchema: { name: z.string(), repo: repoSchema },
+    }, withPlan(async (root, { name }) => {
+        const planCard = (await loadPlan(root)).cards.get('PLAN-PROJECT');
+        if (!planCard) {
+            return fail('NO_PLAN_PROJECT', 'No plan.md (PLAN-PROJECT) at the plan root.');
+        }
+        const existing = await readConnectedRepos(root);
+        if (!existing.some((r) => r.name === name)) {
+            return ok({ removed: false, connected_repos: existing.map(connectedRepoToFm) });
+        }
+        const next = removeConnectedRepoEntry(existing, name);
+        await updateCardFile(planCard.filePath, {
+            frontmatter: applyCardPatch(planCard.frontmatter, {
+                fields: { connected_repos: next.length > 0 ? next.map(connectedRepoToFm) : null },
+            }),
+        });
+        const lint = await lintPlan(root);
+        return ok({
+            removed: true,
+            connected_repos: next.map(connectedRepoToFm),
+            issues: issuesForFile(lint.issues, planCard.relPath),
+        });
+    }));
     server.registerTool('check_integrity', {
+        annotations: { readOnlyHint: true },
         description: 'Lint the whole plan: broken handles, dangling references, wrong folders, schema violations, plus orphans (cards with zero connections). Errors break the graph; warnings and orphans are quality signals.',
-        inputSchema: {},
+        inputSchema: { repo: repoSchema },
     }, withPlan(async (root) => {
         const lint = await lintPlan(root);
         const orphans = [...lint.index.cards.keys()]
@@ -676,19 +963,23 @@ export function buildServer(options = {}) {
         });
     }));
     server.registerTool('diff_plan', {
+        annotations: { readOnlyHint: true },
         description: 'Per-card plan changes from git. base defaults to the sync marker (constellation/.sync.json) or HEAD; head defaults to the working tree. Returns added/modified/removed cards with changed frontmatter keys. Feed the handles to traverse for blast radius.',
         inputSchema: {
             base: z.string().optional(),
             head: z.string().optional(),
+            repo: repoSchema,
         },
     }, withPlan(async (root, { base, head }) => {
         return ok(await diffPlan(root, base, head));
     }));
     server.registerTool('plan_log', {
+        annotations: { readOnlyHint: true },
         description: 'Git history of one card: the commits that touched its file.',
         inputSchema: {
             handle: z.string(),
             limit: z.number().int().min(1).max(100).optional(),
+            repo: repoSchema,
         },
     }, withPlan(async (root, { handle, limit }) => {
         const index = await loadPlan(root);
@@ -701,7 +992,7 @@ export function buildServer(options = {}) {
     }));
     server.registerTool('set_sync_point', {
         description: 'Record that code has been reconciled with the plan as of a commit (default HEAD). diff_plan uses this marker as its default base. Commit the plan first: if constellation/ has uncommitted changes, the marker points at a commit that lacks them and the response includes a warning.',
-        inputSchema: { sha: z.string().optional() },
+        inputSchema: { sha: z.string().optional(), repo: repoSchema },
     }, withPlan(async (root, { sha }) => {
         const point = await writeSyncPoint(root, sha);
         const dirty = await planDirty(root);
@@ -763,13 +1054,7 @@ export function buildServer(options = {}) {
         const url = `http://localhost:${running.port}/`;
         viewer = { server: running, planRoot: root, url };
         if (open) {
-            const { spawn } = await import('node:child_process');
-            const cmd = process.platform === 'darwin'
-                ? 'open'
-                : process.platform === 'win32'
-                    ? 'start'
-                    : 'xdg-open';
-            spawn(cmd, [url], { stdio: 'ignore', detached: true }).unref();
+            await openUrl(url);
         }
         return ok({ url, port: running.port, plan_root: root, editable: !(readonly ?? false) });
     }));