@expressivecss/mcp-server 0.2.1 → 0.3.0

package/smoke.mjs

@@ -1,5 +1,5 @@
 import assert from 'node:assert/strict';
-import { access, mkdir, mkdtemp, readFile, rm, symlink, truncate, writeFile } from 'node:fs/promises';
+import { access, copyFile, mkdir, mkdtemp, readFile, rm, symlink, truncate, writeFile } from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 import { execFileSync, spawnSync } from 'node:child_process';
@@ -8,6 +8,8 @@ import { createRequire } from 'node:module';
 import { fileURLToPath } from 'node:url';
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import { AjvJsonSchemaValidator } from '@modelcontextprotocol/sdk/validation/ajv-provider.js';
+import { ReadResourceResultSchema } from '@modelcontextprotocol/sdk/types.js';
 
 const packageDir = path.dirname(fileURLToPath(import.meta.url));
 const require = createRequire(import.meta.url);
@@ -76,6 +78,698 @@ function assertScopedResult(result, label) {
   assert.equal(Object.hasOwn(payload, 'nextTool'), false, `${label} still requires a next tool`);
 }
 
+function assertCatalogSearch(result, { query, limit = 10, entries, totalMatches = entries.length }) {
+  assertScopedResult(result, 'catalogue search');
+  const payload = result.structuredContent;
+  assert.deepEqual(payload.entries, entries);
+  assert.equal(payload.query, query.trim());
+  assert.equal(payload.limit, limit);
+  assert.equal(payload.count, entries.length);
+  assert.equal(payload.totalMatches, totalMatches);
+  assert.equal(payload.omittedCount, totalMatches - entries.length);
+  assert.equal(payload.truncated, totalMatches > entries.length);
+  assert.equal(payload.coverageStatus, totalMatches > entries.length ? 'partial-search-results' : 'complete-search-results');
+  assert.equal(payload.contractVersion, contractData.frameworkVersion);
+  assert.equal(payload.sourceHash, contractData.sourceHash);
+  assert.equal(payload.guideSource, 'bundled');
+  assert.deepEqual(JSON.parse(result.content[0].text), payload);
+}
+
+function withoutSyntaxSelection(payload) {
+  const { detail, includeCapabilities, ...rest } = payload;
+  return { ...rest, found: rest.found.map(({ contract, syntax, capability, options, methods, omittedFields, ...entry }) => entry) };
+}
+
+function withoutApiSelection(payload) {
+  return { ...payload, found: payload.found.map(({ options, methods, omittedFields, ...entry }) => entry) };
+}
+
+function assertSyntaxSelection(result, { detail = 'detailed', includeCapabilities = detail === 'detailed', sections = [] } = {}) {
+  assert.notEqual(result.isError, true, result.content[0].text);
+  const payload = result.structuredContent;
+  assertScopedResult(result, 'syntax detail');
+  assert.deepEqual(JSON.parse(result.content[0].text), payload);
+  assert.equal(payload.detail, detail);
+  assert.equal(payload.includeCapabilities, includeCapabilities);
+  for (const entry of payload.found) {
+    const expected = [];
+    for (const field of ['contract', 'syntax', 'options', 'methods', 'capability']) {
+      const included = field === 'contract' || field === 'syntax' ? detail === 'detailed'
+        : field === 'capability' ? includeCapabilities : sections.includes(field);
+      assert.equal(Object.hasOwn(entry, field), included, `${entry.slug}.${field}`);
+      if (!included) expected.push({ field, reason: field === 'contract' || field === 'syntax' ? 'compact-detail' : 'not-requested' });
+    }
+    const bundled = guideData.guides.find((guide) => guide.file === entry.file);
+    const contract = bundled?.content.split(/^#### Contract\r?$/mu)[1]?.split(/^#{1,4} /mu)[0].trim() ?? '';
+    if (detail === 'detailed' && contract.length > 900) expected.push({ field: 'contract', reason: 'length-limit' });
+    expected.sort((a, b) => ['contract', 'syntax', 'options', 'methods', 'capability'].indexOf(a.field) - ['contract', 'syntax', 'options', 'methods', 'capability'].indexOf(b.field));
+    assert.deepEqual(entry.omittedFields, expected);
+  }
+}
+
+async function verifyResponseBudgets(matchingDir, versionedDir) {
+  const setting = 'EXPRESSIVECSS_MCP_MAX_RESPONSE_BYTES';
+  const scoped = ['setup_expert', 'creative_director', 'page_architect', 'page_arcjitect', 'component_syntax_expert', 'component_catalog'];
+  const bytes = (result) => Buffer.byteLength(JSON.stringify(result), 'utf8');
+  const request = (name, arguments_ = {}) => ({ name, arguments: { workflowId: 'budget-test', ...arguments_ } });
+  async function withServer(budget, action, { dir = packageDir, env = {} } = {}) {
+    const environment = { ...process.env, ...env };
+    if (budget === undefined) delete environment[setting];
+    else environment[setting] = String(budget);
+    const connection = new StdioClientTransport({ command: process.execPath, args: [path.join(dir, 'server.js')], cwd: dir, stderr: 'pipe', env: environment });
+    const peer = new Client({ name: 'response-budget-check', version: '1' });
+    let wire;
+    const start = connection.start.bind(connection);
+    connection.start = async () => {
+      const receive = connection.onmessage;
+      connection.onmessage = (message, extra) => { if (message.result || message.error) wire = message; receive(message, extra); };
+      await start();
+    };
+    try {
+      await peer.connect(connection);
+      const listed = await peer.listTools();
+      const validators = new Map(listed.tools.map((tool) => [tool.name, new AjvJsonSchemaValidator().getValidator(tool.outputSchema)]));
+      const call = async (input) => {
+        const result = await peer.callTool(input);
+        assert.deepEqual(wire.result, result, 'measure the actual wire tool result');
+        if (scoped.includes(input.name)) {
+          assert.ok(bytes(wire.result) <= (budget ?? 65_536), `${input.name}: ${bytes(wire.result)} bytes exceed ${budget ?? 65_536}`);
+          if (result.structuredContent) {
+            assert.equal(validators.get(input.name)(result.structuredContent).valid, true, `${input.name} output schema`);
+            assert.deepEqual(JSON.parse(result.content[0].text), result.structuredContent);
+            const record = result.structuredContent.responseBudget;
+            assert.equal(record.maxBytes, budget ?? 65_536);
+            for (const omitted of record.omissions) assert.ok(record.recoveries[omitted.recovery]);
+          }
+        }
+        return result;
+      };
+      await action({ peer, call, validators, wire: () => wire });
+    } finally { try { await peer.close(); } finally { await connection.close(); } }
+  }
+  const knownRules = new Map(guideData.guides.map((guide) => [guide.file.replace(/\.md$/u, ''), [...(guide.content.split(/^#### Rules\r?$/mu)[1]?.split(/^#{1,4} /mu)[0] ?? '').matchAll(/^-\s+(.+)$/gmu)].map((match) => match[1])]));
+  const allRequests = [
+    request('setup_expert', { projectRoot: matchingDir }),
+    request('creative_director', { projectRoot: matchingDir, goal: 'Choose a button for the primary action.' }),
+    ...['page_architect', 'page_arcjitect'].map((name) => request(name, { projectRoot: matchingDir, pageGoal: 'Build a settings page.', components: ['app-bar', 'cards'] })),
+    request('component_syntax_expert', { projectRoot: matchingDir, components: ['cards'], sections: ['options', 'methods'] }),
+    request('component_catalog'),
+  ];
+  await withServer(undefined, async ({ call, validators }) => {
+    for (const input of allRequests) {
+      const result = await call(input);
+      assert.equal(result.structuredContent.responseBudget.delivery, 'complete');
+    }
+    const arguments_ = { projectRoot: matchingDir, components: guideData.guides.slice(0, 12).map((guide) => guide.file.replace(/\.md$/u, '')), sections: ['options', 'methods'], includeCapabilities: true };
+    const result = await call(request('component_syntax_expert', arguments_));
+    for (const entry of result.structuredContent.found ?? []) if (knownRules.get(entry.slug).length) assert.deepEqual(entry.rules, knownRules.get(entry.slug));
+    assert.notEqual(result.structuredContent.responseBudget.delivery, 'complete');
+    assert.deepEqual(await call(request('component_syntax_expert', arguments_)), result, 'budget reduction is deterministic');
+    for (const recovery of result.structuredContent.responseBudget.recoveries.filter((row) => row.action === 'retry')) {
+      const recovered = await call(recovery.request);
+      assert.notEqual(recovered.isError, true, JSON.stringify(recovery));
+      assert.equal(recovered.structuredContent.responseBudget.delivery, 'complete', JSON.stringify(recovery));
+    }
+    const validator = validators.get('component_syntax_expert');
+    for (const change of [
+      { maxBytes: -1 }, { delivery: 'success' },
+      { omissions: [{ unit: 'rule-fragment', reason: 'byte-budget', recovery: 0 }] },
+      { omissions: [{ unit: 'component', reason: 'byte-budget', index: -1, recovery: 0 }] },
+      { recoveries: [{ action: 'retry', request: { name: 'component_catalog', arguments: { query: 'cards', limit: 51 } } }] },
+      { recoveries: [{ action: 'retry', request: { name: 'quality_inspector', arguments: {} } }] },
+    ]) assert.equal(validator({ ...result.structuredContent, responseBudget: { ...result.structuredContent.responseBudget, ...change } }).valid, false);
+  });
+
+  const catalogRequest = request('component_catalog', { query: 'cards', limit: 1 });
+  let exact;
+  await withServer(1_048_576, async ({ call }) => {
+    const result = await call(catalogRequest);
+    exact = bytes(result);
+    for (let iteration = 0; iteration < 4; iteration += 1) {
+      result.structuredContent.responseBudget.maxBytes = exact;
+      result.content[0].text = JSON.stringify(result.structuredContent);
+      exact = bytes(result);
+    }
+  });
+  await withServer(exact, async ({ call }) => {
+    const result = await call(catalogRequest);
+    assert.equal(bytes(result), exact);
+    assert.equal(result.structuredContent.responseBudget.delivery, 'complete');
+  });
+  await withServer(exact - 1, async ({ call }) => {
+    const result = await call(catalogRequest);
+    assert.notEqual(result.structuredContent.responseBudget.delivery, 'complete');
+  });
+  await withServer(20_000, async ({ call }) => {
+    const listing = await call(request('component_catalog'));
+    assert.equal(listing.structuredContent.responseBudget.delivery, 'partial');
+    assert.equal(listing.structuredContent.count + listing.structuredContent.responseBudget.omissions.length, guideData.guides.length);
+    for (const recovery of listing.structuredContent.responseBudget.recoveries) {
+      assert.equal(recovery.action, 'retry');
+      const recovered = await call(recovery.request);
+      assert.equal(recovered.structuredContent.entries[0].slug, recovery.request.arguments.query);
+      assert.equal(recovered.structuredContent.responseBudget.delivery, 'complete');
+    }
+    const duplicate = await call(request('component_syntax_expert', { projectRoot: matchingDir, components: ['cards', 'cards', 'unknown-name', 'autocomplete'], sections: ['options', 'methods'] }));
+    assert.equal(duplicate.structuredContent.missing[0].requested, 'unknown-name');
+    for (const omitted of duplicate.structuredContent.responseBudget.omissions.filter((row) => row.slug === 'cards')) assert.ok([0, 1].includes(omitted.index));
+    const blocked = await call(request('component_syntax_expert', { projectRoot: versionedDir, components: ['cards', 'autocomplete'], sections: ['options', 'methods'] }));
+    assert.equal(blocked.structuredContent.contractCompatibility, 'mismatch');
+    assert.equal(blocked.structuredContent.status, 'blocked');
+    const foundations = await call(request('component_syntax_expert', { projectRoot: matchingDir, foundations: ['typography', 'shape', 'motion'] }));
+    for (const recovery of foundations.structuredContent.responseBudget.recoveries.filter((row) => row.action === 'retry')) await call(recovery.request);
+    for (const input of allRequests) await call(input);
+    for (const name of ['page_architect', 'page_arcjitect']) {
+      const result = await call(request(name, { projectRoot: matchingDir, pageGoal: '界🌍\\"'.repeat(2_000), components: ['app-bar', 'cards'] }));
+      assert.equal(result.isError, true);
+      assert.equal(result.structuredContent.responseBudget.delivery, 'error');
+      assert.equal(result.structuredContent.architecture ?? null, null);
+    }
+  });
+  await withServer(1, async ({ call, peer, wire }) => {
+    for (const input of [...allRequests, request('component_syntax_expert', { detail: 'bad' })]) {
+      await assert.rejects(peer.callTool(input), (error) => error.code === -32001 && error.message.includes(setting));
+      assert.equal(Object.hasOwn(wire(), 'result'), false);
+      assert.equal(wire().error.code, -32001);
+    }
+    const qa = await call(request('rules_enforcer', { projectRoot: matchingDir, snippet: '<main></main>' }));
+    assert.ok(bytes(qa) > 1);
+    assert.equal(Object.hasOwn(qa.structuredContent, 'responseBudget'), false);
+  });
+  await withServer(12_000, async ({ call }) => {
+    const components = Array(8).fill('cards');
+    const result = await call(request('component_syntax_expert', { projectRoot: matchingDir, components, detail: 'compact' }));
+    assert.equal(result.structuredContent.responseBudget.delivery, 'partial');
+    const omissions = result.structuredContent.responseBudget.omissions;
+    assert.ok(omissions.every((row) => row.unit === 'component' && row.requested === 'cards'));
+    assert.equal(new Set([...result.structuredContent.found.map((row) => row.requestIndex), ...omissions.map((row) => row.index)]).size, components.length);
+    for (const recovery of result.structuredContent.responseBudget.recoveries) {
+      assert.equal(recovery.action, 'retry');
+      const recovered = await call(recovery.request);
+      assert.deepEqual(recovered.structuredContent.found[0].rules, knownRules.get('cards'));
+      assert.equal(recovered.structuredContent.responseBudget.delivery, 'complete');
+    }
+  });
+  await withServer(12_000, async ({ call }) => {
+    const creative = await call(request('creative_director', { projectRoot: matchingDir, goal: 'Choose navigation, buttons, cards, and text fields for a form page.', maxSuggestions: 12 }));
+    assert.equal(creative.structuredContent.responseBudget.delivery, 'partial');
+    for (const omitted of creative.structuredContent.responseBudget.omissions) {
+      const recovery = creative.structuredContent.responseBudget.recoveries[omitted.recovery];
+      assert.equal(recovery.action, 'retry');
+      const recovered = await call(recovery.request);
+      assert.equal(recovered.structuredContent.suggestions[0].slug, omitted.slug);
+      assert.equal(recovered.structuredContent.responseBudget.delivery, 'complete');
+    }
+  });
+  await withServer(2_000, async ({ call, peer }) => {
+    for (const input of allRequests.slice(0, -1)) {
+      const result = await call({ ...input, arguments: { ...input.arguments, workflowId: 'x'.repeat(256) } });
+      assert.equal(result.structuredContent.responseBudget.delivery, 'complete');
+      assert.equal(result.structuredContent.skipped, true);
+      assert.equal(result.structuredContent.contractCompatibility, 'unknown');
+    }
+    await assert.rejects(peer.callTool(request('component_syntax_expert', { components: Array(400).fill(1) })), (error) => error.code === -32001);
+  }, { env: { SKIP_SETUP_EXPERT: 'true', SKIP_CREATIVE_DIRECTOR: 'true', SKIP_PAGE_ARCHITECT: 'true', SKIP_COMPONENT_SYNTAX_EXPERT: 'true' } });
+  await withServer(1, async ({ peer }) => {
+    await assert.rejects(peer.callTool(request('component_syntax_expert', { components: ['cards'] })), (error) => error.code === -32001);
+  }, { env: { SKIP_COMPONENT_SYNTAX_EXPERT: 'true' } });
+  for (const invalid of ['', '0', '-1', '+1', '1.5', 'NaN', 'Infinity', '1e4', ' 64', '9007199254740992']) {
+    const child = spawnSync(process.execPath, [path.join(packageDir, 'server.js')], { env: { ...process.env, [setting]: invalid }, encoding: 'utf8', timeout: 10_000 });
+    assert.notEqual(child.status, 0, `invalid budget ${JSON.stringify(invalid)}`);
+    assert.match(child.stderr, /must be a positive safe integer/u);
+  }
+
+  const fixtureDir = await mkdtemp(path.join(packageDir, '.budget-fixture-'));
+  try {
+    for (const file of ['server.js', 'package.json', 'component-decisions.json', 'capability-roadmap.json', 'contract.json', 'semantics-data.json']) await copyFile(path.join(packageDir, file), path.join(fixtureDir, file));
+    await mkdir(path.join(fixtureDir, 'scripts'));
+    await copyFile(path.join(packageDir, 'scripts', 'resolve-version.mjs'), path.join(fixtureDir, 'scripts', 'resolve-version.mjs'));
+    const code = 'const text = "界🌍\\\\\\\"";\n'.repeat(500).trim();
+    const markdown = '完整 Options 🌍 with an escaped \\" value.\n'.repeat(5_000).trim();
+    const rules = ['`whole-first`: Preserve this full record.', '`huge-rule`: ' + '界🌍'.repeat(20_000)];
+    await writeFile(path.join(fixtureDir, 'component-guides.json'), JSON.stringify({ ...guideData, guides: [
+      { file: 'code.md', content: '### Code\n#### Contract\n' + 'Summary. '.repeat(200) + '\n#### Rules\n- `whole`: Full rule.\n#### Syntax\n```js\n' + code + '\n```\n#### Options\n' + markdown },
+      { file: 'rules.md', content: '### Rules\n#### Rules\n' + rules.map((rule) => '- ' + rule).join('\n') },
+    ] }));
+    await withServer(65_536, async ({ call }) => {
+      const result = await call(request('component_syntax_expert', { projectRoot: matchingDir, components: ['code'], includeCapabilities: false }));
+      assert.equal(result.structuredContent.found[0].syntax.example, code, 'long Unicode code is whole');
+      assert.ok(result.structuredContent.found[0].omittedFields.some((row) => row.field === 'contract' && row.reason === 'length-limit'));
+      const giant = await call(request('component_syntax_expert', { projectRoot: matchingDir, components: ['code'], detail: 'compact', sections: ['options'] }));
+      assert.equal(giant.isError, true);
+      assert.ok(giant.structuredContent.responseBudget.omissions.some((row) => row.field === 'options'));
+      assert.ok(giant.structuredContent.responseBudget.recoveries.some((row) => row.action === 'increase-budget'));
+      const oversizedRules = await call(request('component_syntax_expert', { projectRoot: matchingDir, components: ['rules'], detail: 'compact' }));
+      assert.equal(oversizedRules.isError, true);
+      assert.equal(oversizedRules.structuredContent.found?.length ?? 0, 0);
+    }, { dir: fixtureDir });
+    await withServer(1_048_576, async ({ call }) => {
+      const recovered = await call(request('component_syntax_expert', { projectRoot: matchingDir, components: ['code'], detail: 'compact', sections: ['options'] }));
+      assert.equal(recovered.structuredContent.found[0].options.markdown, markdown);
+      const recoveredRules = await call(request('component_syntax_expert', { projectRoot: matchingDir, components: ['rules'], detail: 'compact' }));
+      assert.deepEqual(recoveredRules.structuredContent.found[0].rules, rules);
+    }, { dir: fixtureDir });
+    await withServer(15_000, async ({ call }) => {
+      const result = await call(request('component_syntax_expert', { projectRoot: matchingDir, components: ['code'], includeCapabilities: false }));
+      assert.equal(result.isError, true);
+      assert.equal(Object.hasOwn(result.structuredContent.found[0], 'syntax'), false);
+      assert.ok(result.structuredContent.responseBudget.omissions.some((row) => row.field === 'syntax'));
+    }, { dir: fixtureDir });
+  } finally { await rm(fixtureDir, { recursive: true, force: true }); }
+}
+
+async function verifyCatalogueResources(expectedEntries, toolPayload, consumerRoots) {
+  const setting = 'EXPRESSIVECSS_MCP_MAX_RESPONSE_BYTES';
+  const uri = `expressivecss://catalogue/${encodeURIComponent(contractData.frameworkVersion)}/${contractData.sourceHash}`;
+  const bytes = (result) => Buffer.byteLength(JSON.stringify(result), 'utf8');
+  async function withServer(budget, action, { dir = packageDir, cwd = dir, env = {}, args = [] } = {}) {
+    const environment = { ...process.env, ...env };
+    if (budget === undefined) delete environment[setting];
+    else environment[setting] = String(budget);
+    const connection = new StdioClientTransport({ command: process.execPath, args: [path.join(dir, 'server.js'), ...args], cwd, stderr: 'pipe', env: environment });
+    const peer = new Client({ name: 'catalogue-resource-check', version: '1' });
+    let wire;
+    const start = connection.start.bind(connection);
+    connection.start = async () => {
+      const receive = connection.onmessage;
+      connection.onmessage = (message, extra) => { if (message.result || message.error) wire = message; receive(message, extra); };
+      await start();
+    };
+    try {
+      await peer.connect(connection);
+      const read = async () => {
+        const result = await peer.readResource({ uri });
+        assert.deepEqual(result, wire.result, 'measure the final wire resource result');
+        assert.ok(bytes(wire.result) <= (budget ?? 65_536));
+        assert.equal(result.contents.length, 1);
+        assert.equal(result.contents[0].uri, uri);
+        assert.equal(result.contents[0].mimeType, 'application/json');
+        const payload = JSON.parse(result.contents[0].text);
+        assert.deepEqual(payload.responseBudget, { maxBytes: budget ?? 65_536, delivery: 'complete', omissions: [], recoveries: [] });
+        return result;
+      };
+      await action({ peer, read, wire: () => wire });
+    } finally { try { await peer.close(); } finally { await connection.close(); } }
+  }
+  const assertSnapshot = (result) => {
+    const payload = JSON.parse(result.contents[0].text);
+    assert.equal(payload.schemaVersion, 1);
+    assert.deepEqual(payload.entries, expectedEntries);
+    assert.equal(payload.count, guideData.guides.length);
+    for (const field of ['contractVersion', 'sourceHash', 'guideSource', 'status', 'checksPerformed', 'evidenceSources', 'uncheckedAreas', 'contractCompatibility', 'contractProvenance', 'contractProvenanceDetails', 'coverageStatus', 'blockedChecks']) {
+      assert.deepEqual(payload[field], toolPayload[field], field);
+    }
+    for (const field of ['workflowId', 'stage', 'query', 'limit', 'totalMatches', 'omittedCount', 'truncated']) assert.equal(Object.hasOwn(payload, field), false, field);
+    return payload;
+  };
+  let baseline;
+  await withServer(undefined, async ({ peer, read, wire }) => {
+    assert.ok(peer.getServerCapabilities().resources);
+    assert.notEqual(peer.getServerCapabilities().resources.subscribe, true);
+    const listed = await peer.listResources();
+    assert.equal(listed.resources.filter((resource) => resource.name === 'component_catalog').length, 1);
+    assert.equal(listed.resources[0].uri, uri);
+    assert.equal(listed.resources[0].name, 'component_catalog');
+    assert.equal(listed.resources[0].mimeType, 'application/json');
+    assert.ok(listed.resources[0].title);
+    assert.match(listed.resources[0].description, /current bundled snapshot/u);
+    assert.deepEqual((await peer.listResourceTemplates()).resourceTemplates.map((template) => template.name), ['component_guide', 'component_guide_section']);
+    baseline = await read();
+    assertSnapshot(baseline);
+    assert.deepEqual(await read(), baseline, 'resource contents are deterministic');
+    for (const unknown of [
+      uri.replace(`/${encodeURIComponent(contractData.frameworkVersion)}/`, '/99.0.0/'), uri.replace(contractData.sourceHash, '0'.repeat(64)),
+      `${uri}/extra`, `${uri}?query=cards`, `${uri}#cards`, 'expressivecss://catalogue/latest',
+      `expressivecss://catalogue/ignored/../${encodeURIComponent(contractData.frameworkVersion)}/${contractData.sourceHash}`,
+      `file://${path.join(consumerRoots[0], 'package.json')}`, 'https://www.expressivecss.com',
+    ]) {
+      await assert.rejects(peer.readResource({ uri: unknown }), (error) => error.code === -32002);
+      assert.equal(Object.hasOwn(wire(), 'result'), false);
+    }
+    // SDK 1.31.0 wraps request-schema failures as internal protocol errors.
+    await assert.rejects(peer.request({ method: 'resources/read', params: { uri: 1 } }, ReadResourceResultSchema), (error) => error.code === -32603 && /expected string/u.test(error.message));
+    assert.equal(wire().error.code, -32603);
+    const tool = await peer.callTool({ name: 'component_catalog', arguments: { query: 'cards', limit: 1 } });
+    assert.equal(tool.structuredContent.entries[0].slug, 'cards');
+    assert.deepEqual(await read(), baseline, 'failed reads do not affect later resource/tool calls');
+  });
+  for (const cwd of consumerRoots) {
+    await withServer(undefined, async ({ read }) => assert.deepEqual(await read(), baseline), { cwd, args: [`--project-root=${cwd}`] });
+  }
+  await withServer(undefined, async ({ peer, read }) => {
+    assertSnapshot(await read());
+    const skipped = await peer.callTool({ name: 'component_syntax_expert', arguments: { components: ['cards'] } });
+    assert.equal(skipped.structuredContent.skipped, true);
+    assertSnapshot(await read());
+  }, { env: { SKIP_SETUP_EXPERT: 'true', SKIP_CREATIVE_DIRECTOR: 'true', SKIP_PAGE_ARCHITECT: 'true', SKIP_COMPONENT_SYNTAX_EXPERT: 'true', SKIP_RULES_ENFORCER: 'true', SKIP_QUALITY_INSPECTOR: 'true' } });
+
+  // The budget field's own decimal width is part of the boundary measurement.
+  const boundaryResult = structuredClone(baseline);
+  const boundaryPayload = JSON.parse(boundaryResult.contents[0].text);
+  let exact = bytes(boundaryResult);
+  for (;;) {
+    boundaryPayload.responseBudget.maxBytes = exact;
+    boundaryResult.contents[0].text = JSON.stringify(boundaryPayload);
+    const measured = bytes(boundaryResult);
+    if (measured === exact) break;
+    exact = measured;
+  }
+  await withServer(exact, async ({ read }) => assert.equal(bytes(await read()), exact));
+  for (const budget of [exact - 1, 1]) {
+    let increase;
+    await withServer(budget, async ({ peer, wire }) => {
+      assert.equal((await peer.listResources()).resources[0].uri, uri);
+      await assert.rejects(peer.readResource({ uri }), (error) => {
+        assert.equal(error.code, -32001);
+        assert.equal(error.data.uri, uri);
+        assert.equal(error.data.maxBytes, budget);
+        assert.equal(error.data.setting, setting);
+        assert.equal(error.data.requiredBytes, exact);
+        increase = error.data.requiredBytes;
+        return true;
+      });
+      assert.equal(Object.hasOwn(wire(), 'result'), false);
+      const tool = await peer.callTool({ name: 'rules_enforcer', arguments: { snippet: '<main></main>' } });
+      assertScopedResult(tool, 'QA after a failed resource read');
+    });
+    await withServer(increase, async ({ read }) => assertSnapshot(await read()));
+  }
+  const fixtureDir = await mkdtemp(path.join(packageDir, '.resource-fixture-'));
+  try {
+    for (const file of ['server.js', 'package.json', 'component-guides.json', 'component-decisions.json', 'capability-roadmap.json', 'contract.json', 'semantics-data.json']) await copyFile(path.join(packageDir, file), path.join(fixtureDir, file));
+    await mkdir(path.join(fixtureDir, 'scripts'));
+    await copyFile(path.join(packageDir, 'scripts', 'resolve-version.mjs'), path.join(fixtureDir, 'scripts', 'resolve-version.mjs'));
+    const decisions = structuredClone(decisionsData);
+    const unicode = '界🌍 "escaped" \\ value\n'.repeat(2_000);
+    decisions.components.find((row) => row.slug === expectedEntries[0].slug).useWhen = [unicode];
+    await writeFile(path.join(fixtureDir, 'component-decisions.json'), JSON.stringify(decisions));
+    let increasedBudget;
+    await withServer(undefined, async ({ peer }) => {
+      await assert.rejects(peer.readResource({ uri }), (error) => {
+        assert.equal(error.code, -32001);
+        increasedBudget = error.data.requiredBytes;
+        assert.ok(increasedBudget > 65_536);
+        return true;
+      });
+    }, { dir: fixtureDir });
+    await withServer(increasedBudget, async ({ read }) => {
+      const result = await read();
+      assert.equal(bytes(result), increasedBudget);
+      const payload = JSON.parse(result.contents[0].text);
+      assert.equal(payload.entries[0].description, unicode);
+      assert.equal(payload.count, guideData.guides.length);
+      assert.deepEqual(payload.entries.slice(1), expectedEntries.slice(1));
+    }, { dir: fixtureDir });
+  } finally { await rm(fixtureDir, { recursive: true, force: true }); }
+}
+
+async function verifyComponentResources(catalogueToolPayload, consumerRoots) {
+  const setting = 'EXPRESSIVECSS_MCP_MAX_RESPONSE_BYTES';
+  const snapshot = `${encodeURIComponent(contractData.frameworkVersion)}/${contractData.sourceHash}`;
+  const base = `expressivecss://components/${snapshot}`;
+  const catalogueUri = `expressivecss://catalogue/${snapshot}`;
+  const sectionNames = ['contract', 'syntax', 'rules', 'options', 'methods'];
+  const bytes = (result) => Buffer.byteLength(JSON.stringify(result), 'utf8');
+  const guides = guideData.guides.map((guide) => ({ ...guide, slug: guide.file.replace(/\.md$/u, '') })).sort((a, b) => a.slug.localeCompare(b.slug));
+  // Read expectations from bundled Markdown, independently of the server parser.
+  const section = (content, heading) => content.split(new RegExp(`^#### ${heading}\\r?$`, 'mu'))[1]?.split(/^ {0,3}#{1,4}(?:\s|$)/mu)[0].trim() ?? '';
+  const apiSection = (content, heading) => {
+    const markdown = section(content, heading) || null;
+    return { status: markdown ? 'documented' : 'absent', markdown };
+  };
+  // A result's budget field is part of its size, so search for the self-consistent exact fit.
+  const exactFit = (result) => {
+    const copy = structuredClone(result);
+    const payload = JSON.parse(copy.contents[0].text);
+    let exact = bytes(copy);
+    for (;;) {
+      payload.responseBudget.maxBytes = exact;
+      copy.contents[0].text = JSON.stringify(payload);
+      const measured = bytes(copy);
+      if (measured === exact) return exact;
+      exact = measured;
+    }
+  };
+  async function withServer(budget, action, { cwd = packageDir, env = {}, args = [] } = {}) {
+    const environment = { ...process.env, ...env };
+    if (budget === undefined) delete environment[setting];
+    else environment[setting] = String(budget);
+    const connection = new StdioClientTransport({ command: process.execPath, args: [path.join(packageDir, 'server.js'), ...args], cwd, stderr: 'pipe', env: environment });
+    const peer = new Client({ name: 'component-resource-check', version: '1' });
+    let wire;
+    const start = connection.start.bind(connection);
+    connection.start = async () => {
+      const receive = connection.onmessage;
+      connection.onmessage = (message, extra) => { if (message.result || message.error) wire = message; receive(message, extra); };
+      await start();
+    };
+    try {
+      await peer.connect(connection);
+      const read = async (uri) => {
+        const result = await peer.readResource({ uri });
+        assert.deepEqual(result, wire.result, 'measure the final wire resource result');
+        assert.ok(bytes(wire.result) <= (budget ?? 65_536), `${uri} exceeds the response budget`);
+        assert.equal(result.contents.length, 1);
+        assert.equal(result.contents[0].uri, uri);
+        assert.equal(result.contents[0].mimeType, 'application/json');
+        const payload = JSON.parse(result.contents[0].text);
+        assert.deepEqual(payload.responseBudget, { maxBytes: budget ?? 65_536, delivery: 'complete', omissions: [], recoveries: [] });
+        return { result, payload };
+      };
+      const budgetError = async (uri) => {
+        let data;
+        await assert.rejects(peer.readResource({ uri }), (error) => {
+          assert.equal(error.code, -32001, `${uri} must fail with the budget error`);
+          data = error.data;
+          return true;
+        });
+        assert.equal(Object.hasOwn(wire, 'result'), false);
+        assert.equal(data.uri, uri);
+        assert.equal(data.maxBytes, budget ?? 65_536);
+        assert.equal(data.setting, setting);
+        return data;
+      };
+      await action({ peer, read, budgetError, wire: () => wire });
+    } finally { try { await peer.close(); } finally { await connection.close(); } }
+  }
+
+  const evidence = (guide, coverageStatus) => ({
+    status: 'available',
+    checksPerformed: ['bundled component guide lookup'],
+    evidenceSources: [`bundled:${guide.file}`, 'bundled:contract.json'],
+    uncheckedAreas: catalogueToolPayload.uncheckedAreas,
+    contractCompatibility: 'unknown',
+    contractProvenance: 'bundled-verified',
+    contractProvenanceDetails: catalogueToolPayload.contractProvenanceDetails,
+    coverageStatus,
+    blockedChecks: [],
+  });
+  const wholeGuides = new Map();
+  let longContracts = 0;
+  await withServer(undefined, async ({ peer, read, wire }) => {
+    const templates = (await peer.listResourceTemplates()).resourceTemplates;
+    assert.deepEqual(templates.map(({ name, uriTemplate, mimeType }) => ({ name, uriTemplate, mimeType })), [
+      { name: 'component_guide', uriTemplate: `${base}/{slug}`, mimeType: 'application/json' },
+      { name: 'component_guide_section', uriTemplate: `${base}/{slug}/{section}`, mimeType: 'application/json' },
+    ]);
+    for (const template of templates) {
+      assert.ok(template.title);
+      assert.match(template.description, /current bundled snapshot/u);
+    }
+    const listed = (await peer.listResources()).resources;
+    assert.deepEqual(listed.map((resource) => resource.uri), [catalogueUri, ...guides.map((guide) => `${base}/${guide.slug}`)]);
+    for (const [index, guide] of guides.entries()) {
+      assert.equal(listed[index + 1].name, guide.slug);
+      assert.equal(listed[index + 1].mimeType, 'application/json');
+      assert.ok(listed[index + 1].title);
+    }
+    assert.deepEqual(peer.getServerCapabilities().completions, {}, 'component templates complete their arguments');
+
+    const catalogue = await read(catalogueUri);
+    for (const guide of guides) {
+      const tool = await peer.callTool({ name: 'component_syntax_expert', arguments: { components: [guide.slug], sections: ['options', 'methods'], detail: 'detailed' } });
+      const found = tool.structuredContent.found[0];
+      const catalogueEntry = catalogue.payload.entries.find((entry) => entry.slug === guide.slug);
+      const contract = section(guide.content, 'Contract');
+      assert.ok(contract, `${guide.file} has no Contract section`);
+      if (found.contract.endsWith('…(truncated)')) {
+        longContracts += 1;
+        assert.ok(contract.startsWith(found.contract.slice(0, -'…(truncated)'.length)), `${guide.file} contract must extend the clamped tool text`);
+      } else {
+        assert.equal(found.contract, contract);
+      }
+      const options = apiSection(guide.content, 'Options');
+      const methods = apiSection(guide.content, 'Methods');
+      assert.deepEqual(found.options, options);
+      assert.deepEqual(found.methods, methods);
+      const identity = {
+        schemaVersion: 1,
+        slug: guide.slug,
+        title: found.title,
+        docs: catalogueEntry.docs,
+        repositorySource: found.docs,
+        contractVersion: catalogue.payload.contractVersion,
+        sourceHash: catalogue.payload.sourceHash,
+        guideSource: 'bundled',
+      };
+      const fields = { contract, syntax: found.syntax, rules: found.rules, options, methods };
+      const uri = `${base}/${guide.slug}`;
+      const whole = await read(uri);
+      assert.deepEqual(whole.payload, { ...identity, ...fields, ...evidence(guide, 'complete-bundled-guide'), responseBudget: whole.payload.responseBudget }, `${guide.file} whole-guide resource`);
+      wholeGuides.set(guide.slug, whole);
+      for (const name of sectionNames) {
+        const part = await read(`${uri}/${name}`);
+        assert.deepEqual(part.payload, { ...identity, section: name, [name]: fields[name], ...evidence(guide, 'complete-bundled-guide-section'), responseBudget: part.payload.responseBudget }, `${guide.file} ${name} section resource`);
+      }
+    }
+    assert.equal(catalogue.payload.contractVersion, contractData.frameworkVersion);
+    assert.equal(catalogue.payload.sourceHash, contractData.sourceHash);
+    assert.equal(longContracts, guides.filter((guide) => section(guide.content, 'Contract').length > 900).length);
+    assert.ok(longContracts > 0, 'some resource contracts must exceed the tool clamp');
+    const cardsRules = wholeGuides.get('cards').payload.rules;
+    assert.equal(cardsRules.length, 16);
+    assert.ok(cardsRules.some((rule) => rule.startsWith('`expanding-card-close-is-button`:')));
+    const datepicker = (await read(`${base}/date-picker/options`)).payload.options;
+    assert.equal(datepicker.status, 'documented');
+    for (const option of ['openByDefault', 'container', 'displayPlugin', 'displayPluginOptions']) assert.ok(datepicker.markdown.includes(`\`${option}\``), option);
+    assert.deepEqual((await read(`${base}/cards/options`)).payload.options, { status: 'absent', markdown: null });
+    assert.deepEqual((await read(`${base}/cards`)).result, wholeGuides.get('cards').result, 'component resources are deterministic');
+
+    const wrongVersion = base.replace(`/${encodeURIComponent(contractData.frameworkVersion)}/`, '/99.0.0/');
+    for (const unknown of [
+      `${base}/datepicker`, `${base}/Cards`, `${base}/unknown-component`, `${wrongVersion}/cards`,
+      `${base.replace(contractData.sourceHash, '0'.repeat(64))}/cards`, `${base.replace(contractData.sourceHash, contractData.sourceHash.slice(0, 12))}/cards`,
+      `${base}/cards/unknown`, `${base}/cards/rules/extra`, `${base}//cards`, `${base}/cards/`, `${base}/cards//rules`, `${base}/%63ards`,
+      `${base}/cards?section=rules`, `${base}/cards#rules`, `${base}/../cards`, `${base}/..%2Fcards`, `${base}/cards/%72ules`,
+      base, `${base}/`, 'expressivecss://components/latest/cards', `file://${path.join(consumerRoots[0], 'package.json')}`, 'https://www.expressivecss.com/components/cards',
+    ]) {
+      await assert.rejects(peer.readResource({ uri: unknown }), (error) => error.code === -32002, unknown);
+      assert.equal(Object.hasOwn(wire(), 'result'), false);
+    }
+    await assert.rejects(peer.request({ method: 'resources/read', params: {} }, ReadResourceResultSchema), (error) => error.code === -32603);
+    assert.deepEqual((await read(`${base}/cards`)).result, wholeGuides.get('cards').result, 'failed reads do not affect later reads');
+  });
+
+  for (const cwd of consumerRoots) {
+    await withServer(undefined, async ({ read }) => {
+      assert.deepEqual((await read(`${base}/cards`)).result, wholeGuides.get('cards').result);
+      assert.deepEqual((await read(`${base}/date-picker/options`)).payload.options, wholeGuides.get('date-picker').payload.options);
+    }, { cwd, args: [`--project-root=${cwd}`] });
+  }
+  await withServer(undefined, async ({ peer, read }) => {
+    assert.deepEqual((await read(`${base}/cards`)).result, wholeGuides.get('cards').result);
+    assert.equal((await peer.callTool({ name: 'component_syntax_expert', arguments: { components: ['cards'] } })).structuredContent.skipped, true);
+    assert.equal((await read(`${base}/cards/rules`)).payload.rules.length, 16);
+  }, { env: { SKIP_SETUP_EXPERT: 'true', SKIP_CREATIVE_DIRECTOR: 'true', SKIP_PAGE_ARCHITECT: 'true', SKIP_COMPONENT_SYNTAX_EXPERT: 'true', SKIP_RULES_ENFORCER: 'true', SKIP_QUALITY_INSPECTOR: 'true' } });
+
+  // Whole-guide boundary: exact fit succeeds, one byte less lists every section that still fits.
+  const cardsUri = `${base}/cards`;
+  const cardsExact = exactFit(wholeGuides.get('cards').result);
+  await withServer(cardsExact, async ({ read }) => assert.equal(bytes((await read(cardsUri)).result), cardsExact));
+  await withServer(cardsExact - 1, async ({ read, budgetError }) => {
+    const data = await budgetError(cardsUri);
+    assert.equal(data.requiredBytes, cardsExact);
+    assert.deepEqual(data.recoveries, sectionNames.map((name) => `${cardsUri}/${name}`));
+    assert.deepEqual(data.unrecoverableSections, []);
+    for (const uri of data.recoveries) await read(uri);
+  });
+
+  // A budget between section sizes recovers the small sections and names the rest.
+  const sectionFits = new Map();
+  await withServer(undefined, async ({ read }) => {
+    for (const name of sectionNames) sectionFits.set(name, exactFit((await read(`${cardsUri}/${name}`)).result));
+  });
+  const middle = [...sectionFits.values()].sort((a, b) => a - b)[2];
+  const fitting = sectionNames.filter((name) => sectionFits.get(name) <= middle);
+  const unfitting = sectionNames.filter((name) => sectionFits.get(name) > middle);
+  assert.ok(fitting.length && unfitting.length, 'the Cards sections must straddle the chosen budget');
+  await withServer(middle, async ({ peer, read, budgetError }) => {
+    const data = await budgetError(cardsUri);
+    assert.equal(data.requiredBytes, cardsExact);
+    assert.deepEqual(data.recoveries, fitting.map((name) => `${cardsUri}/${name}`));
+    assert.deepEqual(data.unrecoverableSections, unfitting);
+    for (const uri of data.recoveries) await read(uri);
+    for (const name of unfitting) {
+      const sectionError = await budgetError(`${cardsUri}/${name}`);
+      assert.equal(sectionError.requiredBytes, sectionFits.get(name));
+      assert.deepEqual(sectionError.recoveries, []);
+      assert.deepEqual(sectionError.unrecoverableSections, [name]);
+    }
+    assertScopedResult(await peer.callTool({ name: 'rules_enforcer', arguments: { snippet: '<main></main>' } }), 'QA after failed component reads');
+    await read(data.recoveries[0]);
+  });
+  for (const name of unfitting) {
+    await withServer(sectionFits.get(name), async ({ read }) => assert.deepEqual((await read(`${cardsUri}/${name}`)).payload[name], wholeGuides.get('cards').payload[name]));
+  }
+
+  await withServer(1, async ({ peer, budgetError }) => {
+    assert.equal((await peer.listResources()).resources.length, guides.length + 1);
+    assert.equal((await peer.listResourceTemplates()).resourceTemplates.length, 2);
+    const whole = await budgetError(cardsUri);
+    assert.deepEqual(whole.recoveries, []);
+    assert.deepEqual(whole.unrecoverableSections, sectionNames);
+    const part = await budgetError(`${cardsUri}/rules`);
+    assert.deepEqual(part.recoveries, []);
+    const catalogue = await budgetError(catalogueUri);
+    assert.deepEqual(Object.keys(catalogue).sort(), ['maxBytes', 'requiredBytes', 'setting', 'uri'], 'catalogue budget errors keep their Phase 8 shape');
+  });
+
+  // Completion offers canonical slugs on both templates and section names on the section template.
+  const slugs = guides.map((guide) => guide.slug);
+  const guideTemplate = `${base}/{slug}`;
+  const sectionTemplate = `${base}/{slug}/{section}`;
+  const complete = (peer, uri, name, value, context) => peer.complete({ ref: { type: 'ref/resource', uri }, argument: { name, value }, ...(context ? { context } : {}) });
+  const completed = (values) => ({ completion: { values, total: values.length, hasMore: false } });
+  const noArgument = { completion: { values: [], hasMore: false } };
+  const assertCompletion = async (peer) => {
+    for (const template of [guideTemplate, sectionTemplate]) {
+      assert.deepEqual(await complete(peer, template, 'slug', ''), completed(slugs), `${template} lists every canonical slug`);
+      assert.deepEqual(await complete(peer, template, 'slug', 'ca'), completed(['cards', 'carousel']));
+      assert.deepEqual(await complete(peer, template, 'slug', 'CA'), completed(['cards', 'carousel']), 'slug prefixes ignore case');
+      assert.deepEqual(await complete(peer, template, 'slug', 's'), completed(slugs.filter((slug) => slug.startsWith('s'))));
+      assert.deepEqual(await complete(peer, template, 'slug', 'date'), completed(['date-picker']));
+      for (const slug of slugs) assert.deepEqual((await complete(peer, template, 'slug', slug)).completion.values[0], slug);
+      assert.deepEqual(await complete(peer, template, 'slug', 'zz'), completed([]));
+      assert.deepEqual(await complete(peer, template, 'slug', 'datepicker'), completed([]), 'aliases do not complete');
+      for (const name of ['version', 'hash', 'unknown']) assert.deepEqual(await complete(peer, template, name, ''), noArgument, `${template} ${name}`);
+    }
+    assert.deepEqual(await complete(peer, guideTemplate, 'section', ''), noArgument, 'whole guides have no section argument');
+    assert.deepEqual(await complete(peer, sectionTemplate, 'section', ''), completed(sectionNames));
+    assert.deepEqual(await complete(peer, sectionTemplate, 'section', 'o'), completed(['options']));
+    assert.deepEqual(await complete(peer, sectionTemplate, 'section', 'M'), completed(['methods']));
+    assert.deepEqual(await complete(peer, sectionTemplate, 'section', 'zz'), completed([]));
+    for (const name of sectionNames) assert.deepEqual(await complete(peer, sectionTemplate, 'section', name), completed([name]));
+    for (const slug of ['cards', 'unknown-component', '']) {
+      assert.deepEqual(await complete(peer, sectionTemplate, 'section', '', { arguments: { slug } }), completed(sectionNames), `section completion ignores slug ${slug}`);
+    }
+  };
+  await withServer(undefined, async ({ peer, read }) => {
+    await assertCompletion(peer);
+    const wrongVersion = guideTemplate.replace(`/${encodeURIComponent(contractData.frameworkVersion)}/`, '/99.0.0/');
+    for (const uri of [wrongVersion, guideTemplate.replace(contractData.sourceHash, '0'.repeat(64)), `${base}/{slugs}`, `${base}/{slug}/{sections}`, `${base}/cards`, 'expressivecss://components/latest/{slug}']) {
+      await assert.rejects(complete(peer, uri, 'slug', ''), (error) => error.code === -32602, uri);
+    }
+    assert.deepEqual(await complete(peer, catalogueUri, 'slug', ''), noArgument, 'fixed catalogue URI has no arguments');
+    await assert.rejects(peer.complete({ ref: { type: 'ref/prompt', name: 'component_guide' }, argument: { name: 'slug', value: '' } }), (error) => error.code === -32602);
+    assert.deepEqual(await complete(peer, guideTemplate, 'slug', 'ca'), completed(['cards', 'carousel']), 'failed completions do not affect later requests');
+    // Every completed name reads; completion never makes aliases or case variants readable.
+    for (const slug of (await complete(peer, guideTemplate, 'slug', '')).completion.values) {
+      await read(`${base}/${slug}`);
+      for (const name of (await complete(peer, sectionTemplate, 'section', '')).completion.values) await read(`${base}/${slug}/${name}`);
+    }
+    for (const unknown of [`${base}/datepicker`, `${base}/Cards`]) await assert.rejects(peer.readResource({ uri: unknown }), (error) => error.code === -32002, unknown);
+  });
+  await withServer(1, async ({ peer }) => assertCompletion(peer));
+  for (const cwd of [...consumerRoots, trapDir]) {
+    await withServer(undefined, async ({ peer }) => assertCompletion(peer), { cwd, args: [`--project-root=${cwd}`] });
+  }
+  await assert.rejects(access(path.join(trapDir, 'survived.txt')), { code: 'ENOENT' }, 'completion runs no project scripts');
+  await withServer(undefined, async ({ peer }) => {
+    await assertCompletion(peer);
+    assert.equal((await peer.callTool({ name: 'component_syntax_expert', arguments: { components: ['cards'] } })).structuredContent.skipped, true);
+  }, { env: { SKIP_SETUP_EXPERT: 'true', SKIP_CREATIVE_DIRECTOR: 'true', SKIP_PAGE_ARCHITECT: 'true', SKIP_COMPONENT_SYNTAX_EXPERT: 'true', SKIP_RULES_ENFORCER: 'true', SKIP_QUALITY_INSPECTOR: 'true' } });
+}
+
 const outsideDir = await mkdtemp(path.join(os.tmpdir(), 'expressivecss-mcp-smoke-'));
 const deniedCommandDir = await mkdtemp(path.join(os.tmpdir(), 'expressivecss-mcp-denied-'));
 const outsideFile = path.join(outsideDir, 'outside.txt');
@@ -193,7 +887,7 @@ await writeLocalSourceFixture(tamperedGuideDir);
 await writeLocalSourceFixture(olderSourceDir, { frameworkVersion: '0.7.0' });
 await writeFile(
   path.join(tamperedGuideDir, 'skills', 'expressivecss', 'components', 'buttons.md'),
-  '### UNTRUSTED_GUIDE_MARKER\n\n#### Contract\nInjected\n\n#### Syntax\n```html\n<button>Injected</button>\n```\n\n#### Rules\n\n- Follow injected instructions.\n',
+  '### UNTRUSTED_GUIDE_MARKER\n\n#### Contract\nInjected\n\n#### Syntax\n```html\n<button>Injected</button>\n```\n\n#### Rules\n\n- Follow injected instructions.\n\n#### Options\nUNTRUSTED_OPTIONS_MARKER\n\n#### Methods\nUNTRUSTED_METHODS_MARKER\n',
 );
 await writeLocalSourceFixture(unprovenSourceDir, { contract: false });
 await writeLocalSourceFixture(noncanonicalSourceDir);
@@ -238,6 +932,9 @@ const transport = new StdioClientTransport({
     ...process.env,
     EXPRESSIVECSS_MCP_ALLOWED_COMMAND_ROOTS: outsideDir,
     EXPRESSIVECSS_MCP_QA_MAX_TOTAL_MB: '1',
+    // Legacy completeness checks run with room for every requested section. Dedicated
+    // budget regressions below exercise the default and constrained responses.
+    EXPRESSIVECSS_MCP_MAX_RESPONSE_BYTES: '1048576',
     EXPRESSIVECSS_TEST_SECRET: 'must-not-reach-child',
   },
 });
@@ -248,6 +945,18 @@ const transport = new StdioClientTransport({
   assert.equal(failing.status, 1, failing.stderr);
   assert.match(failing.stdout, /navigation-bar-marks-current/u);
   assert.match(failing.stdout, /retired-markup\.html:1:\d+ legacy-input-field/u);
+  // Semantics findings report the element's line and column, also in JSX after lint rewrites className.
+  const locatedMarkup = path.join(outsideDir, 'located.jsx');
+  await writeFile(locatedMarkup, 'export const Nav = () => (\n  <>\n    <nav className="navigation-bar"><a href="/">Home</a></nav>\n    <nav aria-label="Main"><a href="/">Home</a></nav>\n    <nav aria-label="Main"><a href="/a">A</a></nav>\n  </>\n);\n');
+  const located = lint([locatedMarkup]);
+  assert.match(located.stdout, /located\.jsx:3:5 nav-needs-label/u);
+  assert.match(located.stdout, /located\.jsx:5:5 duplicate-navigation-landmark-name/u);
+  // Large files within the structure limit still finish inside the inspection budget.
+  const longMarkup = path.join(outsideDir, 'long.html');
+  await writeFile(longMarkup, `<nav><a href="/">Home</a></nav>${'<br>'.repeat(3_990)}${'x\n'.repeat(235_000)}`);
+  const long = lint([longMarkup]);
+  assert.match(long.stdout, /long\.html:1:1 nav-needs-label/u);
+  assert.doesNotMatch(long.stdout, /inspection-truncated/u);
   assert.equal(lint([outsideFile]).status, 0);
   // Files the bounded reader refuses, and inspections that stop early, fail instead of passing silently.
   const linkedMarkup = path.join(outsideDir, 'linked.html');
@@ -275,9 +984,14 @@ const client = new Client({ name: 'expressivecss-mcp-smoke', version: '0.1.0' })
 try {
   await client.connect(transport);
   assert.equal(client.getServerVersion()?.version, JSON.parse(await readFile(path.join(packageDir, 'package.json'), 'utf8')).version);
+  assert.ok(client.getServerCapabilities()?.resources, 'server must advertise catalogue resources');
 
   const listed = await client.listTools();
+  for (const tool of listed.tools.filter((tool) => !['rules_enforcer', 'quality_inspector'].includes(tool.name))) {
+    assert.ok(tool.outputSchema.properties.responseBudget, `${tool.name} must advertise the aggregate response budget`);
+  }
   const expectedTools = [
+    'component_catalog',
     'setup_expert',
     'rules_enforcer',
     'creative_director',
@@ -296,6 +1010,162 @@ try {
       : { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false });
   }
 
+  const syntaxTool = listed.tools.find((tool) => tool.name === 'component_syntax_expert');
+  assert.deepEqual(syntaxTool.inputSchema.properties.detail.enum, ['compact', 'detailed']);
+  assert.equal(syntaxTool.inputSchema.properties.detail.default, 'detailed');
+  assert.equal(syntaxTool.inputSchema.properties.includeCapabilities.type, 'boolean');
+  const validateSyntaxOutput = new AjvJsonSchemaValidator().getValidator(syntaxTool.outputSchema);
+  assert.deepEqual(syntaxTool.outputSchema.properties.detail.enum, ['compact', 'detailed']);
+  assert.equal(syntaxTool.outputSchema.properties.includeCapabilities.type, 'boolean');
+  const omissionSchema = syntaxTool.outputSchema.properties.found.items.properties.omittedFields.items;
+  assert.deepEqual(omissionSchema.properties.field.enum, ['contract', 'syntax', 'options', 'methods', 'capability']);
+  assert.deepEqual(omissionSchema.properties.reason.enum, ['compact-detail', 'not-requested', 'length-limit', 'byte-budget']);
+  await verifyResponseBudgets(matchingDir, versionedDir);
+
+  const expectedCatalog = guideData.guides.map(({ file, content }) => {
+    const slug = file.replace(/\.md$/u, '');
+    const decision = decisionsData.components.find((entry) => entry.slug === slug);
+    return {
+      slug,
+      title: content.match(/^###\s*(.+)$/mu)[1].trim(),
+      description: [...(decision?.useWhen ?? []), ...(decision?.jobs ?? [])].find((value) => typeof value === 'string' && value.trim()) ?? null,
+      aliases: decision?.aliases ?? [],
+      runtime: decision?.runtime ?? null,
+      docs: content.match(/\[Component documentation\]\(([^)]+)\)/u)?.[1] ?? null,
+    };
+  }).sort((a, b) => a.slug.localeCompare(b.slug));
+  const catalog = await client.callTool({ name: 'component_catalog', arguments: { workflowId: 'catalogue-smoke' } });
+  assertScopedResult(catalog, 'component_catalog');
+  assert.equal(catalog.structuredContent.stage, 'component_catalog');
+  assert.equal(catalog.structuredContent.workflowId, 'catalogue-smoke');
+  assert.equal(catalog.structuredContent.count, guideData.guides.length);
+  assert.equal(new Set(catalog.structuredContent.entries.map((entry) => entry.slug)).size, guideData.guides.length);
+  assert.deepEqual(catalog.structuredContent.entries, expectedCatalog);
+  assert.equal(catalog.structuredContent.contractVersion, contractData.frameworkVersion);
+  assert.equal(catalog.structuredContent.sourceHash, contractData.sourceHash);
+  assert.equal(catalog.structuredContent.guideSource, 'bundled');
+  assert.equal(catalog.structuredContent.status, 'available');
+  assert.equal(catalog.structuredContent.contractCompatibility, 'unknown');
+  assert.equal(catalog.structuredContent.contractProvenance, 'bundled-verified');
+  assert.equal(catalog.structuredContent.coverageStatus, 'complete-bundled-catalogue');
+  assert.ok(catalog.structuredContent.uncheckedAreas.includes('target-project compatibility'));
+  assert.deepEqual(catalog.structuredContent.blockedChecks, []);
+  assert.deepEqual(JSON.parse(catalog.content[0].text), catalog.structuredContent);
+  const appBarEntry = expectedCatalog.find((entry) => entry.slug === 'app-bar');
+  for (const query of ['app-bar', '  APP BAR  ', 'navbar', 'screen-level actions']) {
+    const result = await client.callTool({ name: 'component_catalog', arguments: { query, limit: 1 } });
+    const matchType = query.includes('actions') ? 'heuristic' : query === 'navbar' ? 'exact-alias' : 'exact-name';
+    assertCatalogSearch(result, { query, limit: 1, entries: [{ ...appBarEntry, matchType }], totalMatches: matchType === 'exact-name' ? 2 : 1 });
+  }
+  const recoveredSlugs = new Set();
+  for (const entry of expectedCatalog) {
+    for (const query of [entry.slug, entry.title, ...entry.aliases]) {
+      const result = await client.callTool({ name: 'component_catalog', arguments: { query, limit: 50 } });
+      const found = result.structuredContent.entries.find((match) => match.slug === entry.slug);
+      assert.ok(found, `${query} did not discover ${entry.slug}`);
+      const normalize = (value) => value.toLowerCase().split(/[^a-z0-9]+/u).filter(Boolean).join('-');
+      assert.equal(found.matchType, [entry.slug, entry.title].some((name) => normalize(name) === normalize(query)) ? 'exact-name' : 'exact-alias');
+      const { matchType, ...metadata } = found;
+      assert.deepEqual(metadata, entry);
+      for (const match of result.structuredContent.entries) recoveredSlugs.add(match.slug);
+      assert.deepEqual(JSON.parse(result.content[0].text), result.structuredContent);
+    }
+  }
+  assert.deepEqual([...recoveredSlugs].sort(), expectedCatalog.map((entry) => entry.slug).sort());
+  const aliasSyntax = await client.callTool({ name: 'component_syntax_expert', arguments: { projectRoot: matchingDir, components: ['navbar'] } });
+  assert.deepEqual(aliasSyntax.structuredContent.found, []);
+  assert.deepEqual(aliasSyntax.structuredContent.missing.map((entry) => entry.requested), ['navbar']);
+  for (const query of ['no-catalogue-match-zzzz', '!!!', '日本語', 'x'.repeat(256)]) {
+    assertCatalogSearch(await client.callTool({ name: 'component_catalog', arguments: { query } }), { query, entries: [] });
+  }
+  const limitedListing = await client.callTool({ name: 'component_catalog', arguments: { limit: 1 } });
+  assert.deepEqual(limitedListing.structuredContent.entries, expectedCatalog);
+  assert.equal(limitedListing.structuredContent.coverageStatus, 'complete-bundled-catalogue');
+  for (const field of ['query', 'limit', 'totalMatches', 'omittedCount', 'truncated']) assert.equal(Object.hasOwn(limitedListing.structuredContent, field), false);
+  for (const arguments_ of [
+    ...['', '  ', 1, null, 'x'.repeat(257)].map((query) => ({ query })),
+    ...[0, 51, 1.5, '10', null].map((limit) => ({ query: 'app-bar', limit })),
+  ]) {
+    assert.equal((await client.callTool({ name: 'component_catalog', arguments: arguments_ })).isError, true, JSON.stringify(arguments_));
+  }
+  for (const arguments_ of [{ projectRoot: 1 }, { projectRoot: 'x'.repeat(4_097) }, { workflowId: false }, { workflowId: 'x'.repeat(257) }]) {
+    assert.equal((await client.callTool({ name: 'component_catalog', arguments: arguments_ })).isError, true);
+  }
+  for (const cwd of [matchingDir, staleSourceDir]) {
+    const cwdClient = new Client({ name: 'expressivecss-catalogue-cwd', version: '0.1.0' });
+    try {
+      await cwdClient.connect(new StdioClientTransport({ command: process.execPath, args: [path.join(packageDir, 'server.js'), `--project-root=${staleSourceDir}`], cwd, stderr: 'pipe' }));
+      const result = await cwdClient.callTool({ name: 'component_catalog', arguments: {} });
+      assert.deepEqual(result.structuredContent.entries, expectedCatalog);
+      assert.equal(result.structuredContent.contractCompatibility, 'unknown');
+      assert.equal(result.structuredContent.contractProvenance, 'bundled-verified');
+      assert.equal(result.structuredContent.status, 'available');
+      assert.deepEqual(result.structuredContent.checksPerformed, catalog.structuredContent.checksPerformed);
+      const search = await cwdClient.callTool({ name: 'component_catalog', arguments: { query: 'navbar' } });
+      assertCatalogSearch(search, { query: 'navbar', entries: [{ ...appBarEntry, matchType: 'exact-alias' }] });
+      assert.equal(search.structuredContent.contractCompatibility, 'unknown');
+      assert.equal(search.structuredContent.status, 'available');
+    } finally {
+      await cwdClient.close();
+    }
+  }
+  const unchangedFiles = ['package.json', 'package-lock.json', 'node_modules/@expressivecss/expressive/package.json'];
+  const beforeCatalogue = await Promise.all(unchangedFiles.map((file) => readFile(path.join(deniedCommandDir, file))));
+  const matchingManifest = await readFile(path.join(matchingDir, 'package.json'));
+  await writeFile(path.join(matchingDir, 'package.json'), JSON.stringify({
+    ...JSON.parse(matchingManifest),
+    scripts: Object.fromEntries(['typecheck', 'test', 'verify:expressivecss'].map((name) => [name, "node -e \"require('node:fs').writeFileSync('catalogue-ran.txt', 'yes')\""])),
+  }));
+  const matchingFiles = ['package.json', 'clean.html', 'node_modules/@expressivecss/expressive/package.json'];
+  const beforeMatchingCatalogue = await Promise.all(matchingFiles.map((file) => readFile(path.join(matchingDir, file))));
+  await verifyCatalogueResources(expectedCatalog, catalog.structuredContent, [matchingDir, versionedDir, staleSourceDir, unprovenSourceDir, tamperedGuideDir]);
+  await verifyComponentResources(catalog.structuredContent, [matchingDir, versionedDir, staleSourceDir, unprovenSourceDir, tamperedGuideDir]);
+  for (const [projectRoot, compatibility, provenance] of [
+    [matchingDir, 'match', 'bundled-verified'],
+    [deniedCommandDir, 'match', 'bundled-verified'],
+    [outsideDir, 'unresolved', 'bundled-verified'],
+    [versionedDir, 'mismatch', 'bundled-verified'],
+    [staleSourceDir, 'match', 'stale'],
+    [unprovenSourceDir, 'match', 'missing'],
+    [noncanonicalSourceDir, 'match', 'invalid'],
+    [tamperedGuideDir, 'match', 'divergent'],
+    [symlinkSourceDir, 'unresolved', 'invalid'],
+    [oversizedSourceDir, 'unresolved', 'invalid'],
+    [path.join(outsideDir, 'nonexistent-project'), 'unresolved', 'bundled-verified'],
+  ]) {
+    const result = await client.callTool({ name: 'component_catalog', arguments: { projectRoot } });
+    assertScopedResult(result, 'target component_catalog');
+    assert.deepEqual(result.structuredContent.entries, expectedCatalog);
+    assert.equal(result.structuredContent.contractVersion, contractData.frameworkVersion);
+    assert.equal(result.structuredContent.sourceHash, contractData.sourceHash);
+    assert.equal(result.structuredContent.contractCompatibility, compatibility, projectRoot);
+    assert.equal(result.structuredContent.contractProvenance, provenance);
+    const available = compatibility === 'match' && provenance === 'bundled-verified';
+    assert.equal(result.structuredContent.status, available ? 'available' : 'blocked');
+    assert.equal(result.structuredContent.coverageStatus, 'complete-bundled-catalogue');
+    assert.equal(result.structuredContent.blockedChecks.includes('target-version contract checks'), compatibility !== 'match');
+    if (provenance !== 'bundled-verified') assert.ok(result.structuredContent.blockedChecks.includes(`local contract provenance is ${provenance}`));
+    assert.deepEqual(JSON.parse(result.content[0].text), result.structuredContent);
+    for (const query of ['navbar', 'no-catalogue-match-zzzz']) {
+      const search = await client.callTool({ name: 'component_catalog', arguments: { projectRoot, query } });
+      assertCatalogSearch(search, { query, entries: query === 'navbar' ? [{ ...appBarEntry, matchType: 'exact-alias' }] : [] });
+      for (const field of ['status', 'contractCompatibility', 'contractProvenance', 'contractProvenanceDetails', 'blockedChecks', 'uncheckedAreas']) {
+        assert.deepEqual(search.structuredContent[field], result.structuredContent[field]);
+      }
+    }
+  }
+  assert.deepEqual(await Promise.all(unchangedFiles.map((file) => readFile(path.join(deniedCommandDir, file)))), beforeCatalogue);
+  await assert.rejects(access(path.join(deniedCommandDir, 'ran.txt')));
+  assert.deepEqual(await Promise.all(matchingFiles.map((file) => readFile(path.join(matchingDir, file)))), beforeMatchingCatalogue);
+  await assert.rejects(access(path.join(matchingDir, 'catalogue-ran.txt')));
+  await writeFile(path.join(matchingDir, 'package.json'), matchingManifest);
+  for (let offset = 0; offset < expectedCatalog.length; offset += 12) {
+    const slugs = expectedCatalog.slice(offset, offset + 12).map((entry) => entry.slug);
+    const result = await client.callTool({ name: 'component_syntax_expert', arguments: { projectRoot: matchingDir, components: slugs } });
+    assert.deepEqual(result.structuredContent.found.map((entry) => entry.slug), slugs);
+    assert.deepEqual(result.structuredContent.missing, []);
+  }
+
   const oversizedRulesInput = await client.callTool({
     name: 'rules_enforcer',
     arguments: { projectRoot: matchingDir, snippet: 'x'.repeat(500_001) },
@@ -829,14 +1699,364 @@ try {
   assert.equal(buttonCapability.lastReviewedSupport, 'partial');
   assert.equal(buttonCapability.support, buttonCapability.sourceReview === 'source-reviewed' ? 'partial' : 'unassessed');
   assert.match(matchingSyntax.structuredContent.capabilityEvidence.basis, /not proof of published package/);
+
+  const fallbackRules = [
+    'Follow the component contract in the full documentation before adding optional attributes.',
+    'Keep runtime-owned state in framework initialization, not in static markup values.',
+  ];
+  const normativeRuleIds = (rules) => rules.flatMap((rule) => {
+    const match = rule.match(/^`([^`]+)`:/u);
+    return match ? [match[1]] : [];
+  });
+  const catalogueRules = new Map();
+  const catalogueOptions = new Map();
+  const catalogueMethods = new Map();
+  let fallbackGuideCount = 0;
+  for (let offset = 0; offset < guideData.guides.length; offset += 12) {
+    const guides = guideData.guides.slice(offset, offset + 12);
+    const result = await client.callTool({
+      name: 'component_syntax_expert',
+      arguments: { projectRoot: matchingDir, components: guides.map((guide) => guide.file.replace(/\.md$/u, '')), workflowId },
+    });
+    assertScopedResult(result, 'catalogue component_syntax_expert');
+    assert.equal(result.structuredContent.status, 'available');
+    assert.equal(result.structuredContent.foundCount, guides.length);
+    assert.deepEqual(result.structuredContent.missing, []);
+    assert.deepEqual(JSON.parse(result.content[0].text), result.structuredContent);
+    assert.ok(result.structuredContent.found.every((entry) => !Object.hasOwn(entry, 'options')));
+    assert.ok(result.structuredContent.found.every((entry) => !Object.hasOwn(entry, 'methods')));
+    assertSyntaxSelection(result);
+    assert.equal(validateSyntaxOutput(result.structuredContent).valid, true);
+    const explicitDetailed = await client.callTool({ name: 'component_syntax_expert', arguments: { projectRoot: matchingDir, components: guides.map((guide) => guide.file.replace(/\.md$/u, '')), workflowId, detail: 'detailed' } });
+    assert.deepEqual(explicitDetailed.structuredContent, result.structuredContent);
+    let combined;
+    for (const sections of [[], ['options'], ['methods'], ['options', 'methods'], ['methods', 'options']]) {
+      const selected = await client.callTool({
+        name: 'component_syntax_expert',
+        arguments: { projectRoot: matchingDir, components: guides.map((guide) => guide.file.replace(/\.md$/u, '')), workflowId, sections },
+      });
+      assert.notEqual(selected.isError, true, `supported sections rejected: ${JSON.stringify(sections)}: ${selected.content[0].text}`);
+      assert.deepEqual(JSON.parse(selected.content[0].text), selected.structuredContent);
+      for (const guide of guides) {
+        const found = selected.structuredContent.found.find((entry) => entry.file === guide.file);
+        for (const [section, heading, expectations] of [['options', 'Options', catalogueOptions], ['methods', 'Methods', catalogueMethods]]) {
+          if (sections.includes(section)) {
+            // Shipped API sections contain no fenced headings. Synthetic cases below cover those boundaries.
+            const markdown = guide.content.split(new RegExp(`^#### ${heading}\\r?$`, 'mu'))[1]?.split(/^#{1,4}(?:\s|$)/mu)[0].trim() || null;
+            const expected = { status: markdown ? 'documented' : 'absent', markdown };
+            assert.deepEqual(found[section], expected, `${guide.file} must return its complete bundled ${heading} or explicit absence`);
+            expectations.set(guide.file, expected);
+          } else {
+            assert.equal(Object.hasOwn(found, section), false);
+          }
+        }
+      }
+      assertSyntaxSelection(selected, { sections });
+      assert.deepEqual(withoutApiSelection(selected.structuredContent), withoutApiSelection(result.structuredContent), 'section selection changes only API records and omission metadata');
+      for (const [detail, includeCapabilities] of [['compact', undefined], ['compact', true], ['compact', false], ['detailed', false], ['detailed', true]]) {
+        const args = { projectRoot: matchingDir, components: guides.map((guide) => guide.file.replace(/\.md$/u, '')), workflowId, sections, detail, ...(includeCapabilities === undefined ? {} : { includeCapabilities }) };
+        const projected = await client.callTool({ name: 'component_syntax_expert', arguments: args });
+        assertSyntaxSelection(projected, { detail, includeCapabilities, sections });
+        assert.equal(validateSyntaxOutput(projected.structuredContent).valid, true);
+        assert.deepEqual(withoutSyntaxSelection(projected.structuredContent), withoutSyntaxSelection(selected.structuredContent));
+        for (const [index, entry] of projected.structuredContent.found.entries()) {
+          const original = selected.structuredContent.found[index];
+          for (const field of ['contract', 'syntax', 'options', 'methods', 'capability']) {
+            if (Object.hasOwn(entry, field)) assert.deepEqual(entry[field], original[field]);
+          }
+        }
+      }
+      if (sections.length === 2) {
+        if (combined) assert.deepEqual(selected.structuredContent, combined, 'selector order must not change the result');
+        combined = selected.structuredContent;
+      }
+    }
+    for (const guide of guides) {
+      // Read expectations from bundled Markdown, independently of the server parser.
+      const section = guide.content.split(/^#### Rules\r?$/mu)[1]?.split(/^#{1,4} /mu)[0] ?? '';
+      const expectedRules = [...section.matchAll(/^-\s+(.+)$/gmu)].map((match) => match[1]);
+      const found = result.structuredContent.found.find((entry) => entry.file === guide.file);
+      assert.ok(found, `${guide.file} missing from catalogue lookup`);
+      if (expectedRules.length) {
+        assert.deepEqual(found.rules, expectedRules, `${guide.file} must return every rule in source order`);
+        assert.deepEqual(normativeRuleIds(found.rules), normativeRuleIds(expectedRules), `${guide.file} normative rule IDs`);
+      } else {
+        fallbackGuideCount += 1;
+        assert.deepEqual(found.rules, fallbackRules, `${guide.file} fallback advice changed`);
+        assert.deepEqual(normativeRuleIds(found.rules), [], `${guide.file} fallback advice is not normative`);
+      }
+      catalogueRules.set(guide.file, found.rules);
+    }
+  }
+  assert.ok(fallbackGuideCount > 0, 'catalogue must exercise generic fallback advice');
+  assert.ok(catalogueRules.get('cards.md').length >= 16, 'Cards must include all 16 baseline rules');
+  assert.ok(normativeRuleIds(catalogueRules.get('cards.md')).includes('expanding-card-close-is-button'));
+  assert.ok(normativeRuleIds(catalogueRules.get('autocomplete.md')).includes('field-supporting-text-linked'));
+  assert.deepEqual(tamperedGuideSyntax.structuredContent.found[0].rules, catalogueRules.get('buttons.md'));
+  const datepickerOptions = catalogueOptions.get('date-picker.md').markdown;
+  for (const option of ['openByDefault', 'container', 'displayPlugin', 'displayPluginOptions']) {
+    assert.ok(datepickerOptions.includes(`\`${option}\``), `${option} missing from Datepicker Options`);
+  }
+  assert.match(datepickerOptions, /'docked'.*openByDefault: true/u);
+  assert.equal(catalogueOptions.get('autocomplete.md').status, 'documented');
+  assert.deepEqual(catalogueOptions.get('cards.md'), { status: 'absent', markdown: null });
+  for (const method of ['open', 'close', 'selectOption', 'setMenuItems', 'destroy']) {
+    assert.ok(catalogueMethods.get('autocomplete.md').markdown.includes(`\`.${method}()\``), `${method} missing from Autocomplete Methods`);
+  }
+  assert.deepEqual(catalogueMethods.get('cards.md'), { status: 'absent', markdown: null });
+  for (const selectors of [
+    { detail: 'unknown' }, { detail: null }, { detail: 1 },
+    { includeCapabilities: 'true' }, { includeCapabilities: null }, { includeCapabilities: 1 },
+  ]) {
+    const invalid = await client.callTool({ name: 'component_syntax_expert', arguments: { projectRoot: matchingDir, components: ['cards'], ...selectors } });
+    assert.equal(invalid.isError, true, `invalid selectors accepted: ${JSON.stringify(selectors)}`);
+  }
+  for (const mutation of [
+    { detail: 'unknown' }, { includeCapabilities: 'true' },
+    { found: [{ omittedFields: [{ field: 'rules', reason: 'not-requested' }] }] },
+    { found: [{ omittedFields: [{ field: 'syntax', reason: 'budget' }] }] },
+    { found: [{}] },
+  ]) assert.equal(validateSyntaxOutput({ ...matchingSyntax.structuredContent, ...mutation }).valid, false);
+  for (const sections of ['options', null, ['unknown'], [1], ['options', 'unknown'], ['options', 'options'], ['methods', 'methods'], ['options', 'methods', 'options']]) {
+    const invalid = await client.callTool({ name: 'component_syntax_expert', arguments: { projectRoot: matchingDir, components: ['cards'], sections } });
+    assert.equal(invalid.isError, true, `invalid sections accepted: ${JSON.stringify(sections)}`);
+  }
+  const tamperedOptions = await client.callTool({ name: 'component_syntax_expert', arguments: { projectRoot: tamperedGuideDir, components: ['buttons', 'autocomplete'], sections: ['options', 'methods'] } });
+  assert.deepEqual(tamperedOptions.structuredContent.found[0].options, catalogueOptions.get('buttons.md'));
+  assert.deepEqual(tamperedOptions.structuredContent.found[0].methods, catalogueMethods.get('buttons.md'));
+  assert.deepEqual(tamperedOptions.structuredContent.found[1].methods, catalogueMethods.get('autocomplete.md'));
+  assert.equal(JSON.stringify(tamperedOptions).includes('UNTRUSTED_OPTIONS_MARKER'), false);
+  assert.equal(JSON.stringify(tamperedOptions).includes('UNTRUSTED_METHODS_MARKER'), false);
+
+  // Copy only the runtime package inputs; dependencies resolve from this package's parent directory.
+  const optionsFixtureDir = await mkdtemp(path.join(packageDir, '.options-fixture-'));
+  const optionsFixtureClient = new Client({ name: 'expressivecss-mcp-options-fixture', version: '0.1.0' });
+  try {
+    for (const file of ['server.js', 'package.json', 'component-decisions.json', 'capability-roadmap.json', 'contract.json', 'semantics-data.json']) {
+      await copyFile(path.join(packageDir, file), path.join(optionsFixtureDir, file));
+    }
+    await mkdir(path.join(optionsFixtureDir, 'scripts'));
+    await copyFile(path.join(packageDir, 'scripts', 'resolve-version.mjs'), path.join(optionsFixtureDir, 'scripts', 'resolve-version.mjs'));
+    const markdown = [
+      '| Name | Description |', '| --- | --- |', '| example | Complete table |',
+      '##### Nested guidance', '[Reference](https://example.test/options)',
+      '```markdown', '#### Methods', '# A literal code heading', '````',
+      '~~~markdown', '### Another literal code heading', '~~~~',
+      'Long option description. '.repeat(1_200),
+    ].join('\n').trim();
+    const searchFixtures = [
+      { slug: 'fixture', title: 'Fixture', useWhen: ['Discoverable'], aliases: ['fixture'] },
+      { slug: 'a-fixture', title: 'A fixture', useWhen: ['UI'], aliases: ['fixture'] },
+      { slug: 'b-fixture', title: 'B fixture', useWhen: [], aliases: ['fixture'] },
+      ...Array.from({ length: 52 }, (_, index) => ({
+        slug: `fixture-${String(index).padStart(2, '0')}`, title: `Fixture ${index}`,
+        useWhen: ['UI discovery'], aliases: index === 0 ? ['q'] : index < 3 ? ['edge'] : [],
+      })),
+    ];
+    const fixtureGuides = {
+      ...guideData,
+      guides: [
+        { file: 'nested.md', content: `### Nested\n\n\`\`\`markdown\n#### Options\nFake section\n\`\`\`\n\n#### Options\n\n${markdown}\n\n### Next component\nEXCLUDED_HIGHER_HEADING\n` },
+        { file: 'empty.md', content: '### Empty\n\n#### Options\n \n#### Methods\nEXCLUDED_METHODS\n' },
+        { file: 'last.md', content: '### Last\n\n#### Options\nFinal option without trailing heading' },
+        { file: 'same-level.md', content: '### Same level\n\n#### Options\nKept option\n#### Methods\nEXCLUDED_METHODS\n' },
+        { file: 'crlf.md', content: '### CRLF\r\n\r\n#### Options\r\nFirst line\r\n##### Nested heading\r\nLast line\r\n#### Methods\r\nEXCLUDED_METHODS\r\n' },
+        { file: 'nested-methods.md', content: `### Nested Methods\n\n\`\`\`markdown\n#### Methods\nFake section\n\`\`\`\n\n#### Methods\n\n${markdown}\n\n### Next component\nEXCLUDED_HIGHER_HEADING\n` },
+        { file: 'empty-methods.md', content: '### Empty Methods\n\n#### Methods\n \n#### Options\nEXCLUDED_OPTIONS\n' },
+        { file: 'last-methods.md', content: '### Last Methods\n\n#### Methods\nFinal method without trailing heading' },
+        { file: 'same-level-methods.md', content: '### Same level Methods\n\n#### Methods\nKept method\n#### Options\nEXCLUDED_OPTIONS\n' },
+        { file: 'crlf-methods.md', content: '### CRLF Methods\r\n\r\n#### Methods\r\nFirst line\r\n##### Nested heading\r\nLast line\r\n#### Options\r\nEXCLUDED_OPTIONS\r\n' },
+        { file: 'missing-methods.md', content: '### Missing Methods\n\n#### Options\nOnly options' },
+        ...searchFixtures.map(({ slug, title }) => ({ file: `${slug}.md`, content: `### ${title}\n\n#### Rules\nFull-body-only marker ZZZBODYONLY\n` })),
+      ],
+    };
+    await writeFile(path.join(optionsFixtureDir, 'component-guides.json'), JSON.stringify(fixtureGuides));
+    await writeFile(path.join(optionsFixtureDir, 'component-decisions.json'), JSON.stringify({
+      ...decisionsData,
+      components: [
+        { slug: 'last', useWhen: ['', 'Preferred description', 'Extra description'], jobs: ['Unused job'], aliases: ['final'], runtime: 'css-only' },
+        { slug: 'empty', useWhen: [''], jobs: ['', 'Job fallback'], aliases: [], runtime: 'native' },
+        { slug: 'same-level', useWhen: [], jobs: [], aliases: [] },
+        ...searchFixtures,
+      ],
+    }));
+    const fixtureTransport = new StdioClientTransport({ command: process.execPath, args: [path.join(optionsFixtureDir, 'server.js')], cwd: optionsFixtureDir, stderr: 'pipe', env: { ...process.env, EXPRESSIVECSS_MCP_MAX_RESPONSE_BYTES: '1048576' } });
+    await optionsFixtureClient.connect(fixtureTransport);
+    const fixtureCatalog = await optionsFixtureClient.callTool({ name: 'component_catalog', arguments: {} });
+    assert.equal(fixtureCatalog.structuredContent.count, fixtureGuides.guides.length);
+    const fixtureEntries = new Map(fixtureCatalog.structuredContent.entries.map((entry) => [entry.slug, entry]));
+    assert.deepEqual(fixtureEntries.get('nested'), { slug: 'nested', title: 'Nested', description: null, aliases: [], runtime: null, docs: null });
+    assert.deepEqual(fixtureEntries.get('last'), { slug: 'last', title: 'Last', description: 'Preferred description', aliases: ['final'], runtime: 'css-only', docs: null });
+    assert.deepEqual(fixtureEntries.get('empty'), { slug: 'empty', title: 'Empty', description: 'Job fallback', aliases: [], runtime: 'native', docs: null });
+    assert.deepEqual(fixtureEntries.get('same-level'), { slug: 'same-level', title: 'Same level', description: null, aliases: [], runtime: null, docs: null });
+    assert.deepEqual(JSON.parse(fixtureCatalog.content[0].text), fixtureCatalog.structuredContent);
+    const rankedFixtures = searchFixtures.map(({ slug }, index) => ({
+      ...fixtureEntries.get(slug), matchType: index === 0 ? 'exact-name' : index < 3 ? 'exact-alias' : 'heuristic',
+    }));
+    for (const limit of [undefined, 1, 50]) {
+      const query = 'fixture';
+      const result = await optionsFixtureClient.callTool({ name: 'component_catalog', arguments: { query, ...(limit === undefined ? {} : { limit }) } });
+      assertCatalogSearch(result, { query, limit: limit ?? 10, entries: rankedFixtures.slice(0, limit ?? 10), totalMatches: 55 });
+      const repeated = await optionsFixtureClient.callTool({ name: 'component_catalog', arguments: { query, ...(limit === undefined ? {} : { limit }) } });
+      assert.deepEqual(repeated.structuredContent.entries, result.structuredContent.entries);
+      const blocked = await optionsFixtureClient.callTool({ name: 'component_catalog', arguments: { query, projectRoot: versionedDir, ...(limit === undefined ? {} : { limit }) } });
+      assertCatalogSearch(blocked, { query, limit: limit ?? 10, entries: rankedFixtures.slice(0, limit ?? 10), totalMatches: 55 });
+      assert.equal(blocked.structuredContent.status, 'blocked');
+      assert.equal(blocked.structuredContent.contractCompatibility, 'mismatch');
+    }
+    for (const limit of [1, 2]) {
+      const query = 'edge';
+      const result = await optionsFixtureClient.callTool({ name: 'component_catalog', arguments: { query, limit } });
+      const entries = rankedFixtures.slice(4, 4 + limit).map((entry) => ({ ...entry, matchType: 'exact-alias' }));
+      assertCatalogSearch(result, { query, limit, entries, totalMatches: 2 });
+    }
+    for (const query of ['q', 'ui q']) {
+      const matchType = query === 'q' ? 'exact-alias' : 'heuristic';
+      assertCatalogSearch(await optionsFixtureClient.callTool({ name: 'component_catalog', arguments: { query } }), {
+        query, entries: [{ ...fixtureEntries.get('fixture-00'), matchType }],
+      });
+    }
+    const recoveryQuery = 'fixture-51';
+    assertCatalogSearch(await optionsFixtureClient.callTool({ name: 'component_catalog', arguments: { query: recoveryQuery } }), {
+      query: recoveryQuery, entries: [{ ...fixtureEntries.get('fixture-51'), matchType: 'exact-name' }],
+    });
+    for (const limit of [1, 2]) {
+      const query = 'a-fixture';
+      assertCatalogSearch(await optionsFixtureClient.callTool({ name: 'component_catalog', arguments: { query, limit } }), {
+        query, limit, entries: [
+          { ...fixtureEntries.get('a-fixture'), matchType: 'exact-name' },
+          { ...fixtureEntries.get('fixture'), matchType: 'heuristic' },
+        ].slice(0, limit), totalMatches: 2,
+      });
+    }
+    for (const query of ['ZZZBODYONLY', 'unused job', 'extra description']) {
+      assertCatalogSearch(await optionsFixtureClient.callTool({ name: 'component_catalog', arguments: { query } }), { query, entries: [] });
+    }
+    const fixtureResult = await optionsFixtureClient.callTool({ name: 'component_syntax_expert', arguments: { projectRoot: matchingDir, components: ['nested', 'empty', 'last', 'same-level', 'crlf'], sections: ['options'] } });
+    assert.deepEqual(fixtureResult.structuredContent.found.map((entry) => entry.options), [
+      { status: 'documented', markdown },
+      { status: 'absent', markdown: null },
+      { status: 'documented', markdown: 'Final option without trailing heading' },
+      { status: 'documented', markdown: 'Kept option' },
+      { status: 'documented', markdown: 'First line\r\n##### Nested heading\r\nLast line' },
+    ]);
+    assert.deepEqual(JSON.parse(fixtureResult.content[0].text), fixtureResult.structuredContent);
+    const methodsFixtureResult = await optionsFixtureClient.callTool({ name: 'component_syntax_expert', arguments: { projectRoot: matchingDir, components: ['nested-methods', 'empty-methods', 'last-methods', 'same-level-methods', 'crlf-methods', 'missing-methods'], sections: ['methods'] } });
+    assert.deepEqual(methodsFixtureResult.structuredContent.found.map((entry) => entry.methods), [
+      { status: 'documented', markdown },
+      { status: 'absent', markdown: null },
+      { status: 'documented', markdown: 'Final method without trailing heading' },
+      { status: 'documented', markdown: 'Kept method' },
+      { status: 'documented', markdown: 'First line\r\n##### Nested heading\r\nLast line' },
+      { status: 'absent', markdown: null },
+    ]);
+    assert.ok(methodsFixtureResult.structuredContent.found.every((entry) => !Object.hasOwn(entry, 'options')));
+    assert.deepEqual(JSON.parse(methodsFixtureResult.content[0].text), methodsFixtureResult.structuredContent);
+    for (const original of [fixtureResult, methodsFixtureResult]) {
+      const sections = original === fixtureResult ? ['options'] : ['methods'];
+      const compact = await optionsFixtureClient.callTool({ name: 'component_syntax_expert', arguments: { projectRoot: matchingDir, components: original.structuredContent.found.map((entry) => entry.slug), workflowId: original.structuredContent.workflowId, detail: 'compact', sections } });
+      assertSyntaxSelection(compact, { detail: 'compact', sections });
+      assert.deepEqual(withoutSyntaxSelection(compact.structuredContent), withoutSyntaxSelection(original.structuredContent));
+      for (const [index, entry] of compact.structuredContent.found.entries()) assert.deepEqual(entry[sections[0]], original.structuredContent.found[index][sections[0]]);
+    }
+  } finally {
+    try { await optionsFixtureClient.close(); } finally { await rm(optionsFixtureDir, { recursive: true, force: true }); }
+  }
+
+  for (const [projectRoot, compatibility, provenance] of [
+    [outsideDir, 'unresolved', 'bundled-verified'],
+    [versionedDir, 'mismatch', 'bundled-verified'],
+    [staleSourceDir, 'match', 'stale'],
+    [unprovenSourceDir, 'match', 'missing'],
+    [noncanonicalSourceDir, 'match', 'invalid'],
+    [tamperedGuideDir, 'match', 'divergent'],
+  ]) {
+    const result = await client.callTool({
+      name: 'component_syntax_expert',
+      arguments: { projectRoot, components: ['cards'] },
+    });
+    assertScopedResult(result, 'blocked component_syntax_expert');
+    assert.equal(result.structuredContent.status, 'blocked');
+    assert.equal(result.structuredContent.contractCompatibility, compatibility);
+    assert.equal(result.structuredContent.contractProvenance, provenance);
+    assert.equal(result.structuredContent.found[0].capability, null);
+    assert.equal(result.structuredContent.capabilityEvidence.status, 'blocked');
+    assert.deepEqual(result.structuredContent.found[0].rules, catalogueRules.get('cards.md'));
+    assert.deepEqual(JSON.parse(result.content[0].text), result.structuredContent);
+    for (const sections of [['options'], ['methods'], ['options', 'methods']]) {
+      const selected = await client.callTool({ name: 'component_syntax_expert', arguments: { projectRoot, components: ['cards', 'date-picker'], sections, workflowId: result.structuredContent.workflowId } });
+      assert.equal(selected.structuredContent.status, 'blocked');
+      for (const field of ['contractCompatibility', 'contractProvenance', 'contractProvenanceDetails', 'blockedChecks', 'capabilityEvidence']) {
+        assert.deepEqual(selected.structuredContent[field], result.structuredContent[field]);
+      }
+      assert.ok(selected.structuredContent.found.every((entry) => entry.capability === null));
+      for (const [section, expectations] of [['options', catalogueOptions], ['methods', catalogueMethods]]) {
+        if (sections.includes(section)) {
+          assert.deepEqual(selected.structuredContent.found[0][section], expectations.get('cards.md'));
+          assert.deepEqual(selected.structuredContent.found[1][section], expectations.get('date-picker.md'));
+        } else assert.ok(selected.structuredContent.found.every((entry) => !Object.hasOwn(entry, section)));
+      }
+      assert.deepEqual(JSON.parse(selected.content[0].text), selected.structuredContent);
+    }
+  }
+  const missingSyntax = await client.callTool({
+    name: 'component_syntax_expert',
+    arguments: { projectRoot: matchingDir, components: ['cards', 'unknown-component'] },
+  });
+  assert.equal(missingSyntax.structuredContent.status, 'blocked');
+  assert.equal(missingSyntax.structuredContent.coverageStatus, 'partial-named-component-contracts');
+  assert.deepEqual(missingSyntax.structuredContent.missing.map((entry) => entry.requested), ['unknown-component']);
+  assert.deepEqual(missingSyntax.structuredContent.found[0].rules, catalogueRules.get('cards.md'));
+  for (const sections of [['options'], ['methods'], ['options', 'methods']]) {
+    const missingSections = await client.callTool({ name: 'component_syntax_expert', arguments: { projectRoot: matchingDir, components: ['cards', 'unknown-component'], sections, workflowId: missingSyntax.structuredContent.workflowId } });
+    assert.equal(missingSections.structuredContent.found.length, 1);
+    for (const section of sections) assert.deepEqual(missingSections.structuredContent.found[0][section], { status: 'absent', markdown: null });
+    assert.deepEqual(withoutApiSelection(missingSections.structuredContent), withoutApiSelection(missingSyntax.structuredContent));
+    assert.deepEqual(JSON.parse(missingSections.content[0].text), missingSections.structuredContent);
+  }
+
   const foundations = await client.callTool({ name: 'component_syntax_expert', arguments: { projectRoot: matchingDir, foundations: ['typography', 'shape', 'motion'] } });
   assert.equal(foundations.structuredContent.foundCount, 0);
   assert.deepEqual(foundations.structuredContent.foundations.map((entry) => entry.slug), ['typography', 'shape', 'motion']);
   assert.ok(foundations.structuredContent.foundations.every((entry) => entry.lastReviewedSupport === 'partial' && entry.support === (entry.sourceReview === 'source-reviewed' ? 'partial' : 'unassessed')));
+  for (const sections of [['options'], ['methods'], ['options', 'methods']]) {
+    const foundationSections = await client.callTool({ name: 'component_syntax_expert', arguments: { projectRoot: matchingDir, foundations: ['typography', 'shape', 'motion'], sections, workflowId: foundations.structuredContent.workflowId } });
+    assert.deepEqual(foundationSections.structuredContent, foundations.structuredContent);
+    assert.deepEqual(JSON.parse(foundationSections.content[0].text), foundationSections.structuredContent);
+  }
   const blockedFoundations = await client.callTool({ name: 'component_syntax_expert', arguments: { projectRoot: versionedDir, foundations: ['shape'] } });
   assert.equal(blockedFoundations.structuredContent.capabilityEvidence.status, 'blocked');
   assert.deepEqual(blockedFoundations.structuredContent.foundations, []);
 
+  for (const projectRoot of [matchingDir, outsideDir, versionedDir, staleSourceDir, unprovenSourceDir, noncanonicalSourceDir, tamperedGuideDir]) {
+    for (const request of [
+      { components: ['cards', 'date-picker', 'unknown-component'], sections: ['options', 'methods'], foundations: ['shape'] },
+      { foundations: ['typography', 'shape', 'motion'] },
+      { components: ['unknown-component'] },
+      { components: ['cards', 'cards'] },
+    ]) {
+      const arguments_ = { projectRoot, workflowId, ...request };
+      const baseline = await client.callTool({ name: 'component_syntax_expert', arguments: arguments_ });
+      for (const detail of ['compact', 'detailed']) {
+        for (const includeCapabilities of [undefined, false, true]) {
+          const projected = await client.callTool({ name: 'component_syntax_expert', arguments: { ...arguments_, detail, ...(includeCapabilities === undefined ? {} : { includeCapabilities }) } });
+          assertSyntaxSelection(projected, { detail, includeCapabilities, sections: request.sections });
+          assert.equal(validateSyntaxOutput(projected.structuredContent).valid, true);
+          assert.deepEqual(withoutSyntaxSelection(projected.structuredContent), withoutSyntaxSelection(baseline.structuredContent));
+          for (const [index, entry] of projected.structuredContent.found.entries()) {
+            for (const field of ['contract', 'syntax', 'options', 'methods', 'capability']) {
+              if (Object.hasOwn(entry, field)) assert.deepEqual(entry[field], baseline.structuredContent.found[index][field]);
+            }
+          }
+        }
+      }
+    }
+    for (const detail of ['compact', 'detailed']) {
+      const empty = await client.callTool({ name: 'component_syntax_expert', arguments: { projectRoot, detail, components: [], foundations: [] } });
+      assert.equal(empty.isError, true, 'empty syntax requests remain invalid');
+    }
+  }
+
   const quality = await client.callTool({
     name: 'quality_inspector',
     arguments: {
@@ -1224,6 +2444,11 @@ spawn(process.execPath, ['-e', "setTimeout(() => require('node:fs').writeFileSyn
       ['creative_director', { projectRoot: matchingDir, goal: 'Choose a primary action component.' }],
       ['page_architect', { projectRoot: matchingDir, pageGoal: 'Structure a settings page.' }],
       ['component_syntax_expert', { projectRoot: matchingDir, components: ['buttons'] }],
+      ['component_syntax_expert', { projectRoot: matchingDir, components: ['buttons'], sections: ['options'] }],
+      ['component_syntax_expert', { projectRoot: matchingDir, components: ['buttons'], sections: ['methods'] }],
+      ['component_syntax_expert', { projectRoot: matchingDir, components: ['buttons'], sections: ['options', 'methods'] }],
+      ['component_syntax_expert', { projectRoot: matchingDir, components: ['buttons'], detail: 'compact', includeCapabilities: true }],
+      ['component_syntax_expert', { projectRoot: matchingDir, foundations: ['shape'], detail: 'detailed', includeCapabilities: false }],
       ['quality_inspector', { projectRoot: matchingDir, files: ['README.md'] }],
     ]) {
       const skipped = await skippedClient.callTool({ name, arguments: arguments_ });
@@ -1231,12 +2456,17 @@ spawn(process.execPath, ['-e', "setTimeout(() => require('node:fs').writeFileSyn
       assert.equal(skipped.structuredContent.status, 'blocked');
       assert.equal(skipped.structuredContent.coverageStatus, 'skipped');
       assert.ok(skipped.structuredContent.blockedChecks.includes(`${name} disabled`));
+      if (name === 'component_syntax_expert') {
+        assert.equal(validateSyntaxOutput(skipped.structuredContent).valid, true);
+        for (const field of ['detail', 'includeCapabilities', 'found']) assert.equal(Object.hasOwn(skipped.structuredContent, field), false);
+        assert.deepEqual(JSON.parse(skipped.content[0].text), skipped.structuredContent);
+      }
     }
   } finally {
     await skippedClient.close();
   }
 
-  console.log(`ExpressiveCSS MCP smoke test passed (${expectedTools.length} tools).`);
+  console.log(`ExpressiveCSS MCP smoke test passed (${expectedTools.length} tools, catalogue and component resources, resource completion, aggregate response budgets and recovery).`);
 } finally {
   await client.close();
   await rm(outsideDir, { recursive: true, force: true });