@magic-spells/constellation 0.1.0 → 0.2.0

package/dist/mcp/server.js

@@ -1,15 +1,18 @@
-import { rm } from 'node:fs/promises';
+import { readFile, rm } from 'node:fs/promises';
+import path from 'node:path';
+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.
@@ -25,10 +28,46 @@ 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.
 
-Change tracking is git: diff_plan reports per-card changes since the sync marker (or
-HEAD); traverse the changed handles for blast radius; set_sync_point after reconciling
-code (commit the plan first — it warns if the plan is uncommitted). Never stamp dirty
-flags into cards.
+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.
+
+"Sync the plan" / "sync the plan to the code" = bring the CODE up to match the plan (the
+plan is the source of truth — behavior changes in the plan FIRST, then in code, never the
+reverse). It is NOT merely stamping the marker. The loop: diff_plan (base = marker) for what
+changed → traverse the changed handles (detail: "full") for blast radius → update the
+application code to match those cards → run the build/tests and bump card status → commit,
+then set_sync_point to advance the marker (commit the plan first — it warns if the plan is
+uncommitted). When the diff is large and the affected areas don't share files, act as the
+ORCHESTRATOR rather than editing it all yourself: partition the blast radius into
+independent, non-overlapping neighborhoods (split on file boundaries so no two agents touch
+the same file, AND assign each plan card to exactly one agent — two agents calling
+update_card on the same card race, and the later write silently clobbers the earlier) and
+fan out a sub-agent per neighborhood in parallel; use one agent when the change is small or
+files overlap. Delegating keeps your context clean and lets you hold the
+macro view. ALWAYS verify the sub-agents' work yourself after they have all finished — re-read
+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
@@ -40,11 +79,106 @@ The plan folder is found by walking up from the working directory, BOUNDED by th
 root (it never adopts another repo's plan). If no plan exists in this repo (tools return
 NO_PLAN_FOUND), call init_plan once — create_card works immediately after.
 
+When building or auditing a plan, act as a senior engineer and architect advising the user,
+not a scribe taking dictation: don't assume they know everything — bring expertise, name
+trade-offs and risks, propose what's missing, and explain the why so they can decide. Hold
+the bar high and with integrity: do it right, be honest about built-vs-planned and
+verified-vs-assumed, and surface uncertainty rather than papering over it. But don't
+over-engineer — there's elegance in simplicity: calibrate to the project's scope, recommend
+the smallest change that most improves the plan, and don't manufacture gaps to look thorough.
+The aim is a plan the user would be proud to ship. Hold it to one bar above all: if every
+line of code were deleted, the app could be rebuilt from the plan alone — aim for that
+coverage (not volume), and whatever you couldn't rebuild is the gap.
+
+Work macro→micro: orient (manifest, routes, folder
+layout) and seed PLAN-PROJECT + a system DIAGRAM — propose a human-readable project name
+and confirm it with the user (it's plan.md's name: and the viewer's title; change it
+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. 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,
+observability, rate limits, pagination, migrations, testing). The mechanical checks
+(check_integrity orphans, dangling refs, code-without-cards) are just hygiene. Give a
+short, prioritized list of recommendations and ask about the judgment calls. For the full
+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
 back to the user as a clickable link, e.g. http://localhost:4747/, and tell them the port.
 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.
+// 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) {
+        methodologyCache = await readFile(METHODOLOGY_PATH, 'utf8');
+    }
+    return methodologyCache;
+}
+/** A prompt body = a one-line mode intro followed by the shared methodology. */
+async function planPromptBody(intro) {
+    try {
+        return `${intro}\n\n${await methodologyText()}`;
+    }
+    catch {
+        return (`${intro}\n\n(Could not read the methodology file; follow the macro→micro summary ` +
+            `in the server instructions: orient, follow the data, follow the user/auth, follow ` +
+            `the edges, zoom in, ask only what the code can't answer, find gaps, recommend.)`);
+    }
+}
 function ok(data) {
     return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
 }
@@ -54,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,
@@ -81,25 +234,87 @@ 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.0' }, { instructions: INSTRUCTIONS });
+    const server = new McpServer({ name: 'constellation', version: '0.2.0' }, { 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.',
+    }, async () => ({
+        messages: [
+            {
+                role: 'user',
+                content: {
+                    type: 'text',
+                    text: await planPromptBody('Bootstrap (or extend) the Constellation plan for THIS repository by analyzing its code. If no plan exists, call init_plan first. Work the method below end to end, then report the gaps you found and a short, prioritized list of recommendations.'),
+                },
+            },
+        ],
+    }));
+    server.registerPrompt('audit_plan', {
+        title: 'Audit the plan against the code',
+        description: 'Reconcile the existing plan with the codebase: find gaps, orphans, stale or missing cards, and dangling refs; verify card statuses against the real code; and make tasteful recommendations.',
+    }, async () => ({
+        messages: [
+            {
+                role: 'user',
+                content: {
+                    type: 'text',
+                    text: await planPromptBody('Audit the existing Constellation plan for THIS repository against its code. Lean on Steps 7–8 (find gaps, recommend) and on verifying statuses against real code, but use the whole method as a checklist. Report what is missing, stale, or orphaned, then a short, prioritized list of recommendations.'),
+                },
+            },
+        ],
+    }));
     async function planRoot() {
         return options.planRoot ?? resolvePlanDir();
     }
     // 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));
@@ -107,20 +322,25 @@ export function buildServer(options = {}) {
         };
     }
     server.registerTool('init_plan', {
-        description: 'Bootstrap a new plan: create a constellation/ folder with a starter plan.md. Use only when no plan exists yet (other tools return NO_PLAN_FOUND). After this, create_card works immediately.',
+        description: 'Bootstrap a new plan: create a constellation/ folder with a starter plan.md. Use only when no plan exists yet (other tools return NO_PLAN_FOUND). Pass name to set the project name (shown as the viewer title); if omitted it defaults to a title-cased folder name (pyramid-server → "Pyramid Server"). Propose a name, confirm it with the user, and change it anytime via update_card on PLAN-PROJECT. After this, create_card works immediately.',
         inputSchema: {
             path: z
                 .string()
                 .optional()
                 .describe('directory to create constellation/ in (default: cwd)'),
+            name: z
+                .string()
+                .optional()
+                .describe('project name for plan.md (default: a title-cased folder name)'),
         },
-    }, async ({ path: target }) => {
+    }, async ({ path: target, name }) => {
         try {
             const { initPlan } = await import('../core/scaffold.js');
-            const created = await initPlan(target ?? process.cwd());
+            const { root: created, name: projectName } = await initPlan(target ?? process.cwd(), { name });
             return ok({
                 created,
-                next: 'Add cards with create_card; update plan.md via update_card on PLAN-PROJECT.',
+                name: projectName,
+                next: `Plan created with project name "${projectName}" (the viewer title). Confirm the name with the user — change it anytime via update_card on PLAN-PROJECT (patch.name). Then add cards with create_card.`,
             });
         }
         catch (err) {
@@ -128,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);
@@ -144,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(),
@@ -154,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);
@@ -171,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);
@@ -191,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);
@@ -240,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(),
@@ -254,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();
@@ -312,6 +574,7 @@ export function buildServer(options = {}) {
             }))
                 .min(1)
                 .max(500),
+            repo: repoSchema,
         },
     }, withPlan(async (root, { cards }) => {
         const index = await loadPlan(root);
@@ -380,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);
@@ -406,18 +670,20 @@ export function buildServer(options = {}) {
             additions.get(f).add(t);
         }
         let added = 0;
+        const touched = new Set();
         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 });
             await updateCardFile(card.filePath, { frontmatter });
+            touched.add(card.relPath);
             added += targets.size;
         }
         const lint = await lintPlan(root);
-        return ok({ added, failed, errors: lint.errors });
+        return ok({ added, failed, issues: lint.issues.filter((i) => touched.has(i.file)) });
     }));
     server.registerTool('update_card', {
         description: 'Update a card. patch.name/kind/status set or delete (null); patch.connections replaces the list; patch.fields deep-merges into type-specific frontmatter (arrays replace, null deletes). body replaces the whole body. Body-only updates never reformat frontmatter.',
@@ -433,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);
@@ -459,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());
@@ -479,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());
@@ -497,11 +764,16 @@ export function buildServer(options = {}) {
             connections: [...existing, to.handle],
         });
         await updateCardFile(from.filePath, { frontmatter });
-        return ok({ connected: [from.handle, to.handle], declared_on: from.handle });
+        const lint = await lintPlan(root);
+        return ok({
+            connected: [from.handle, to.handle],
+            declared_on: from.handle,
+            issues: issuesForFile(lint.issues, from.relPath),
+        });
     }));
     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());
@@ -526,7 +798,8 @@ export function buildServer(options = {}) {
                 removedFrom.push(card.handle);
             }
         }
-        const after = await loadPlan(root);
+        const lint = await lintPlan(root);
+        const after = lint.index;
         const stillConnected = after.connectedHandles.get(cardA.handle)?.has(cardB.handle) ?? false;
         const remainingSources = [];
         if (stillConnected) {
@@ -542,15 +815,140 @@ export function buildServer(options = {}) {
                     remainingSources.push(`mermaid block in ${card.handle}`);
             }
         }
+        const touched = new Set(removedFrom
+            .map((h) => after.cards.get(h)?.relPath)
+            .filter((p) => Boolean(p)));
         return ok({
             removed_from: removedFrom,
             still_connected: stillConnected,
             remaining_sources: remainingSources,
+            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()]
@@ -565,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);
@@ -590,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);
@@ -652,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) });
     }));