docs: clarify roots-first multi-project contract

Author: PatrickSys

CHANGELOG.md

@@ -14,8 +14,8 @@
 
 ### Documentation
 
-- simplify the setup story around three cases: default rootless setup, single-project fallback, and explicit `project` retries
-- clarify that issue #63 fixed the architecture and workspace-aware workflow, but issue #2 is not fully solved when the client does not provide enough project context
+- simplify the setup story around a roots-first contract: roots-capable multi-project sessions, single-project fallback, and explicit `project` retries
+- clarify that issue #63 fixed the architecture and workspace-aware workflow, but issue #2 is still only partially solved when the client does not provide roots or active-project context
 - remove the repo-local `init` / marker-file story from the public setup guidance
 
 ## [1.9.0](https://github.com/PatrickSys/codebase-context/compare/v1.8.2...v1.9.0) (2026-03-19)

docs/capabilities.md

@@ -105,6 +105,7 @@ Behavior matrix:
 Rules:
 
 - If the client provides workspace context, that becomes the trusted workspace boundary for the session. In practice this usually comes from MCP roots.
+- Treat seamless multi-project routing as evidence-backed only for roots-capable hosts. Without roots, explicit fallback is still required.
 - If the server still cannot tell which project to use, a bootstrap path or explicit absolute `project` path remains the fallback.
 - `project` is the canonical explicit selector when routing is ambiguous.
 - `project` may point at a project path, file path, `file://` URI, or relative subproject path.

docs/client-setup.md

@@ -18,6 +18,18 @@ npx -y codebase-context --http --port 4000
 
 Copy-pasteable templates: [`templates/mcp/stdio/.mcp.json`](../templates/mcp/stdio/.mcp.json) and [`templates/mcp/http/.mcp.json`](../templates/mcp/http/.mcp.json).
 
+## Project routing contract
+
+Automatic multi-project routing is evidence-backed only when the MCP host announces workspace roots. Treat that as the primary path.
+
+If the host does not send roots, or still cannot tell which project is active, use one of the explicit fallbacks instead:
+
+- start the server with a single bootstrap path
+- set `CODEBASE_ROOT`
+- retry tool calls with `project`
+
+If multiple projects are available and no active project can be inferred safely, the server returns `selection_required` instead of guessing.
+
 ## Claude Code
 
 ```bash
@@ -197,9 +209,9 @@ Check these three flows:
 
 1. **Single project** — call `search_codebase` or `metadata`. Routing is automatic.
 
-2. **Multiple projects, one server entry** — open two repos or a monorepo. Call `codebase://context`. Expected: workspace overview, then automatic routing once a project is active.
+2. **Multiple projects on a roots-capable host** — open two repos or a monorepo. Call `codebase://context`. Expected: workspace overview, then automatic routing once a project is active.
 
-3. **Ambiguous selection** — start without a bootstrap path, call `search_codebase`. Expected: `selection_required`. Retry with `project` set to `apps/dashboard` or `/repos/customer-portal`.
+3. **Ambiguous or no-roots selection** — start without a bootstrap path, call `search_codebase`. Expected: `selection_required`. Retry with `project` set to `apps/dashboard` or `/repos/customer-portal`.
 
 For monorepos, test all three selector forms:
 

tests/mcp-client-templates.test.ts

@@ -133,4 +133,27 @@ describe('docs/capabilities.md transport documentation', () => {
     expect(caps).toContain('Codex');
     expect(caps).toContain('Windsurf');
   });
+
+  it('states the roots-first routing fallback explicitly', () => {
+    expect(caps).toContain('roots-capable hosts');
+    expect(caps).toContain('explicit fallback is still required');
+  });
+});
+
+describe('docs/client-setup.md multi-project guidance', () => {
+  const clientSetup = readText('docs/client-setup.md');
+
+  it('documents the project routing contract', () => {
+    expect(clientSetup).toContain(
+      'Automatic multi-project routing is evidence-backed only when the MCP host announces workspace roots.'
+    );
+    expect(clientSetup).toContain(
+      'the server returns `selection_required` instead of guessing'
+    );
+  });
+
+  it('keeps the three verification flows aligned with the roots-first contract', () => {
+    expect(clientSetup).toContain('Multiple projects on a roots-capable host');
+    expect(clientSetup).toContain('Ambiguous or no-roots selection');
+  });
 });

tests/multi-project-routing.test.ts

@@ -362,6 +362,45 @@ describe('multi-project routing', () => {
     }
   });
 
+  it('triggers a background rebuild for a corrupted explicit project without falling back to cwd', async () => {
+    delete process.env.CODEBASE_ROOT;
+    delete process.argv[2];
+
+    await fs.rm(path.join(secondaryRoot, CODEBASE_CONTEXT_DIRNAME, INDEX_META_FILENAME), {
+      force: true
+    });
+
+    const { server, refreshKnownRootsFromClient } = await import('../src/index.js');
+    const typedServer = server as unknown as TestServer & {
+      listRoots: () => Promise<{ roots: Array<{ uri: string; name?: string }> }>;
+    };
+    const originalListRoots = typedServer.listRoots.bind(typedServer);
+    const handler = typedServer._requestHandlers.get('tools/call');
+    if (!handler) throw new Error('tools/call handler not registered');
+
+    typedServer.listRoots = vi.fn().mockRejectedValue(new Error('roots unsupported'));
+
+    try {
+      await refreshKnownRootsFromClient();
+      const response = await callTool(handler, 21, 'search_codebase', {
+        query: 'feature',
+        project: secondaryRoot
+      });
+      const payload = parsePayload(response) as {
+        status: string;
+        message: string;
+        index?: { action?: string; reason?: string };
+      };
+
+      expect(payload.status).toBe('indexing');
+      expect(payload.message).toContain('retry shortly');
+      expect(payload.index?.action).toBe('rebuild-started');
+      expect(String(payload.index?.reason || '')).toContain('Index meta');
+    } finally {
+      typedServer.listRoots = originalListRoots;
+    }
+  });
+
   it('returns selection_required instead of silently falling back to cwd when startup is rootless and unresolved', async () => {
     delete process.env.CODEBASE_ROOT;
     delete process.argv[2];