@octanejs/mcp-server 0.2.5 → 0.2.8

package/README.md

@@ -57,11 +57,12 @@ maintainer tools):
 
 ## Tools (always available)
 
-The server initialization instructions direct coding agents to call
-`octane_engineering_plan` and load `build-octane-software` before creating or
-materially changing Octane code. This makes the correctness, performance
-evidence, adversarial self-review, and handoff requirements available even when
-the host does not automatically discover skills.
+The server initialization instructions are one orienting sentence plus a pointer
+to `octane_engineering_plan`, because they are injected into every session
+whether or not it touches Octane. The correctness, performance-evidence,
+self-review, and handoff requirements live in that tool response, so they stay
+reachable even on hosts that do not discover skills. Each tool description says
+when to call it.
 
 ### `octane_engineering_plan`
 
@@ -112,24 +113,30 @@ without registering its React-package mapping fails CI.
 
 Returns a skill by name. Bundled skills (shipped with this package):
 
-- `bridge-react-package` — the full workflow for porting a React library.
-- `build-octane-software` — production engineering, performance, validation,
+- `bridge-react-package`: the full workflow for porting a React library.
+- `build-octane-software`: production engineering, performance, validation,
   and adversarial self-review gates for Octane code.
-- `migrate-react-component` — React JSX to `.tsrx` conversion reference.
-- `react-divergences` — Octane's intentional differences from React.
-- `setup-ssr` — server rendering and hydration setup.
+- `migrate-react-component`: React JSX to `.tsrx` conversion reference.
+- `react-divergences`: Octane's intentional differences from React.
+- `setup-ssr`: server rendering and hydration setup.
 
-When running inside the octane monorepo, the maintainer skills from
-`.ai/skills` are also available: `react-library-port`, `bug-hunter`,
+When running inside the octane monorepo, the skills from `.rulesync/skills` are
+also available: `authoring-tsrx`, `react-library-port`, `bug-hunter`,
 `create-a-pr`, `handle-issue`, `octane-core-extend`, `triage`,
-`performance-audit`.
+`performance-audit`. A test compares this map against the directory in both
+directions, so a new skill cannot stay unreachable here. This tool reads the RuleSync source, and
+`pnpm rules:generate` writes the per-agent copies (`.claude/skills/`,
+`.github/skills/`, `.cursor/skills/`, `.gemini/skills/`) from the same text, so
+hosts that discover skills natively and hosts that call this tool see the same
+thing.
 
 ## Tools (octane monorepo only)
 
 ### `octane_project_map`
 
-Returns `.ai/project-map.md` with package layout, authoritative sources,
-invariants, and validation commands.
+Returns `AGENTS.md`: the RuleSync-generated root rule, covering what Octane is,
+which source owns which behavior, the intentional divergences from React, and the
+validation commands. CI fails if it drifts from its source in `.rulesync/rules/`.
 
 ### `octane_triage_paths`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@octanejs/mcp-server",
-  "version": "0.2.5",
+  "version": "0.2.8",
   "type": "module",
   "engines": {
     "node": ">=22"
@@ -36,7 +36,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "vitest": "^4.1.9"
+    "vitest": "^4.1.10"
   },
   "scripts": {
     "start": "node src/index.js",

package/skills/setup-ssr.md

@@ -66,9 +66,13 @@ hydration-stable; the client adopts server DOM instead of rebuilding it.
    self-contained SSR server at `dist/server/entry.js` (exports
    `handler`/`nodeHandler`; preview with `octane-preview`);
    `server.render: 'buffered'` switches it to the await-everything `prerender`.
-   A deploy adapter can restructure the output for a host — for example
-   `adapter: vercel()` from `@octanejs/adapter-vercel` emits Vercel's Build
-   Output API.
+   A deploy adapter prepares the output for a host: `adapter: vercel()` from
+   `@octanejs/adapter-vercel` emits Vercel's Build Output API, while
+   `adapter: cloudflare()` from `@octanejs/adapter-cloudflare` emits a module
+   Worker at `dist/server/worker.js` for Workers Static Assets. Cloudflare apps
+   keep a user-owned `wrangler.jsonc` pointing `main` at that Worker and
+   `assets.directory` at `dist/client`, with `nodejs_compat` enabled. Leave
+   `assets.not_found_handling` unset or `"none"` so navigation misses reach SSR.
 2. **Custom server**: write `entry-server.ts` exporting a function that calls
    `prerender()` (or `renderToString()`, or a streaming renderer) and splices
    the result into your HTML template, and `entry-client.ts` calling

package/src/bridge.js

@@ -1,9 +1,10 @@
 import { readdir, readFile } from 'node:fs/promises';
 import { join, resolve } from 'node:path';
 
-// React package → maintained @octanejs binding. bridge.test.js derives the
-// expected value set from the workspace manifests, so publishing a new binding
-// without registering it here fails the mcp-server tests.
+// React package → maintained @octanejs binding. Bindings with no React-package
+// equivalent live in KNOWN_NATIVE_BINDINGS below. bridge.test.js derives the
+// expected union from the workspace manifests, so publishing a new binding
+// without registering it in either catalog fails the mcp-server tests.
 export const KNOWN_BINDINGS = {
 	zustand: '@octanejs/zustand',
 	jotai: '@octanejs/jotai',
@@ -14,6 +15,9 @@ export const KNOWN_BINDINGS = {
 	'@tanstack/react-query': '@octanejs/tanstack-query',
 	'@tanstack/react-router': '@octanejs/tanstack-router',
 	'@tanstack/react-store': '@octanejs/tanstack-store',
+	'@tanstack/react-router-ssr-query': '@octanejs/tanstack-router-ssr-query',
+	'@tanstack/react-hotkeys': '@octanejs/tanstack-hotkeys',
+	'@tanstack/react-pacer': '@octanejs/tanstack-pacer',
 	'@tanstack/react-table': '@octanejs/tanstack-table',
 	'@tanstack/react-virtual': '@octanejs/tanstack-virtual',
 	'framer-motion': '@octanejs/motion',
@@ -22,6 +26,7 @@ export const KNOWN_BINDINGS = {
 	'styled-components': '@octanejs/styled-components',
 	'react-router': '@octanejs/remix-router',
 	'react-router-dom': '@octanejs/remix-router',
+	nuqs: '@octanejs/nuqs',
 	'@lexical/react': '@octanejs/lexical',
 	'@tiptap/react': '@octanejs/tiptap',
 	'lucide-react': '@octanejs/lucide',
@@ -34,6 +39,7 @@ export const KNOWN_BINDINGS = {
 	'@base-ui-components/react': '@octanejs/base-ui',
 	'@dnd-kit/react': '@octanejs/dnd-kit',
 	sonner: '@octanejs/sonner',
+	shadcn: '@octanejs/shadcn',
 	recharts: '@octanejs/recharts',
 	'@react-three/fiber': '@octanejs/three',
 	'@visx/visx': '@octanejs/visx',
@@ -93,11 +99,18 @@ export const KNOWN_BINDINGS = {
 	'dexie-react-hooks': '@octanejs/dexie',
 };
 
+// Octane-specific ecosystem packages that have no React import to rewrite.
+// Keep these out of KNOWN_BINDINGS so the React bridge never invents a source
+// package mapping for native tooling.
+export const KNOWN_NATIVE_BINDINGS = new Set(['@octanejs/devtools']);
+
 // Workspace directory names for the maintained bindings. Keep this derived
-// from KNOWN_BINDINGS so repository path routing cannot drift from the public
+// from both catalogs so repository path routing cannot drift from the public
 // binding list (aliases such as `motion` intentionally collapse to one dir).
 export const KNOWN_BINDING_PACKAGE_DIRS = new Set(
-	Object.values(KNOWN_BINDINGS).map((name) => name.slice('@octanejs/'.length)),
+	[...Object.values(KNOWN_BINDINGS), ...KNOWN_NATIVE_BINDINGS].map((name) =>
+		name.slice('@octanejs/'.length),
+	),
 );
 
 export const KNOWN_VANILLA_CORES = {

package/src/bridge.test.js

@@ -1,14 +1,16 @@
 import { describe, expect, it } from 'vitest';
-import { mkdir, mkdtemp, readdir, readFile, writeFile } from 'node:fs/promises';
+import { mkdir, mkdtemp, readFile, writeFile } from 'node:fs/promises';
 import { fileURLToPath } from 'node:url';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
+import { getBindingPackages } from '../../../scripts/workspace-packages.mjs';
 import {
 	bridgeReport,
 	bridgeReportFromSource,
 	detectVanillaCore,
 	scanSource,
 	KNOWN_BINDINGS,
+	KNOWN_NATIVE_BINDINGS,
 	KNOWN_BINDING_PACKAGE_DIRS,
 } from './bridge.js';
 
@@ -261,40 +263,14 @@ describe('KNOWN_BINDINGS', () => {
 		expect(upstreamPackages.every((name) => KNOWN_BINDINGS[name] === '@octanejs/visx')).toBe(true);
 	});
 
-	it('covers every published @octanejs binding (derived from workspace manifests)', async () => {
-		// The expected set is DERIVED from packages/*/package.json rather than
-		// hand-maintained, so publishing a new binding without registering it in
-		// KNOWN_BINDINGS fails here. Only genuinely-not-a-binding packages (the
-		// core runtime, build/deploy infrastructure, this MCP server) are
-		// excluded by name.
-		const NON_BINDINGS = new Set([
-			'octane',
-			'@octanejs/app-core',
-			'@octanejs/rspack-plugin',
-			'@octanejs/rsbuild-plugin',
-			'@octanejs/vite-plugin',
-			'@octanejs/adapter-vercel',
-			'@octanejs/mcp-server',
-		]);
-		const packagesRoot = fileURLToPath(new URL('../..', import.meta.url));
-		const bindings = [];
-		const bindingDirectories = [];
-		for (const entry of await readdir(packagesRoot, { withFileTypes: true })) {
-			if (!entry.isDirectory()) continue;
-			let manifest;
-			try {
-				manifest = JSON.parse(
-					await readFile(join(packagesRoot, entry.name, 'package.json'), 'utf8'),
-				);
-			} catch {
-				continue; // not a package dir
-			}
-			if (manifest.private || NON_BINDINGS.has(manifest.name)) continue;
-			bindings.push(manifest.name);
-			bindingDirectories.push(entry.name);
-		}
+	it('covers every published @octanejs binding (derived from workspace manifests)', () => {
+		// Use the same role classification as the generated package inventory so
+		// metaframeworks and infrastructure cannot drift into the binding catalog.
+		const bindings = getBindingPackages();
 		expect(bindings.length).toBeGreaterThan(0);
-		expect(new Set(Object.values(KNOWN_BINDINGS))).toEqual(new Set(bindings));
-		expect(KNOWN_BINDING_PACKAGE_DIRS).toEqual(new Set(bindingDirectories));
+		expect(new Set([...Object.values(KNOWN_BINDINGS), ...KNOWN_NATIVE_BINDINGS])).toEqual(
+			new Set(bindings.map(({ name }) => name)),
+		);
+		expect(KNOWN_BINDING_PACKAGE_DIRS).toEqual(new Set(bindings.map(({ dir }) => dir)));
 	});
 });

package/src/index.js

@@ -13,9 +13,10 @@ const __filename = fileURLToPath(import.meta.url);
 const PACKAGE_ROOT = resolve(dirname(__filename), '..');
 
 // Bundled skills ship with the npm package and work in ANY project using
-// octane. Repo skills live in the octane monorepo's .ai/skills and are only
-// available when the server runs against a checkout (they cover maintainer
-// workflows: triage, PRs, core changes).
+// octane. Repo skills are read from the RuleSync source, not a generated copy,
+// so this server and every per-agent output (.claude/skills, .github/skills,
+// …) serve the same text. They cover maintainer workflows: triage, PRs, core
+// changes, and are only available when the server runs against a checkout.
 export const BUNDLED_SKILLS = {
 	'bridge-react-package': 'skills/bridge-react-package.md',
 	'build-octane-software': 'skills/build-octane-software.md',
@@ -25,13 +26,14 @@ export const BUNDLED_SKILLS = {
 };
 
 export const REPO_SKILLS = {
-	'bug-hunter': '.ai/skills/bug-hunter.md',
-	'create-a-pr': '.ai/skills/create-a-pr.md',
-	'handle-issue': '.ai/skills/handle-issue.md',
-	'octane-core-extend': '.ai/skills/octane-core-extend.md',
-	'performance-audit': '.ai/skills/performance-audit.md',
-	'react-library-port': '.ai/skills/react-library-port.md',
-	triage: '.ai/skills/triage.md',
+	'authoring-tsrx': '.rulesync/skills/authoring-tsrx/SKILL.md',
+	'bug-hunter': '.rulesync/skills/bug-hunter/SKILL.md',
+	'create-a-pr': '.rulesync/skills/create-a-pr/SKILL.md',
+	'handle-issue': '.rulesync/skills/handle-issue/SKILL.md',
+	'octane-core-extend': '.rulesync/skills/octane-core-extend/SKILL.md',
+	'performance-audit': '.rulesync/skills/performance-audit/SKILL.md',
+	'react-library-port': '.rulesync/skills/react-library-port/SKILL.md',
+	triage: '.rulesync/skills/triage/SKILL.md',
 };
 
 // Suite names from the unified runner manifest (`SUITES` in
@@ -48,16 +50,22 @@ export const BENCHMARK_SUITES = [
 	'recursive-context',
 	'signal-favoring',
 	'news',
+	'hydration-interactivity',
 	'effectful-list',
 	'memo-wall',
 	'portal-swarm',
 	'react-hosted-islands',
 	'ssr-throughput',
 	'streaming-ssr',
+	'ssr-http',
+	'ssr-workerd',
+	'tanstack-start',
 	'dbmon-deopt',
 	'js-framework-deopt',
 	'async-waterfall',
 	'async-composition',
+	'lynx-list',
+	'lynx-bundle-size',
 	'codegen-size',
 	'bundle-size',
 	'three-renderer',
@@ -67,10 +75,15 @@ export const BENCHMARK_SUITES = [
 const DEFAULT_TIMEOUT_MS = 120_000;
 
 export function instructionsFor(repoMode) {
+	// This text is injected into every session of every connected agent, whether
+	// or not it touches Octane, so it stays one orienting sentence plus one
+	// pointer. The gates themselves live in octane_engineering_plan, and each
+	// tool's own description says when to call it: that is where a model looks
+	// when it is actually deciding.
 	const common =
-		'Before creating or materially changing Octane software, call octane_engineering_plan and load the build-octane-software skill. Treat its correctness, performance evidence, and adversarial self-review gates as required. Load the task-specific migration, binding, divergence, or SSR skill in addition when relevant. Do not claim a performance improvement without comparable measurements.';
+		"Octane is a compiler-first UI framework with React's programming model, so React habits are the main source of wrong changes here. Before creating or materially changing Octane code, call octane_engineering_plan: it returns the gates that apply and names the skills to load.";
 	return repoMode
-		? `${common} For Octane framework-fundamental work, also load octane-core-extend and performance-audit, establish a relevant baseline before editing, and use octane_validate_plan for the final changed paths.`
+		? `${common} Inside this monorepo checkout it also returns the repository validation commands for the paths you changed.`
 		: common;
 }
 
@@ -94,7 +107,7 @@ export function areaForPath(path) {
 	if (path.startsWith('packages/rspack-plugin-octane/')) return 'rspack-plugin';
 	if (path.startsWith('packages/rsbuild-plugin-octane/')) return 'rsbuild-plugin';
 	if (path.startsWith('packages/vite-plugin-octane/')) return 'vite-plugin';
-	if (path.startsWith('packages/adapter-vercel/')) return 'deploy-adapter';
+	if (/^packages\/adapter-[^/]+\//.test(path)) return 'deploy-adapter';
 	if (path.startsWith('packages/octane-evals/')) return 'evals';
 	if (path.startsWith('packages/octane-mcp-server/')) return 'mcp-server';
 	const packageMatch = path.match(/^packages\/([^/]+)\//);
@@ -104,7 +117,7 @@ export function areaForPath(path) {
 	if (path.startsWith('benchmarks/')) return 'benchmark';
 	if (path.startsWith('website/')) return 'website';
 	if (path.startsWith('.rulesync/')) return 'rulesync-source';
-	if (path.startsWith('.ai/') || path.startsWith('.codex/') || path.startsWith('.claude/')) {
+	if (path.startsWith('.codex/') || path.startsWith('.claude/')) {
 		return 'agent-instructions';
 	}
 	if (path.startsWith('docs/') || path.endsWith('.md')) return 'docs';
@@ -166,9 +179,14 @@ export function validationFor(paths, taskKind) {
 		);
 	}
 	if (areas.has('deploy-adapter')) {
-		commands.add(
-			'./node_modules/.bin/vitest run packages/adapter-vercel/tests --project adapter-vercel',
-		);
+		for (const path of paths) {
+			const match = path.match(/^packages\/(adapter-[^/]+)\//);
+			if (match) {
+				commands.add(
+					`./node_modules/.bin/vitest run packages/${match[1]}/tests --project ${match[1]}`,
+				);
+			}
+		}
 	}
 	if (
 		areas.has('metaframework-core') ||
@@ -381,7 +399,7 @@ function registerUserTools(server, repoRoot, repoMode) {
 		{
 			title: 'Octane skill',
 			description:
-				'Return an Octane agent skill by name. Load build-octane-software before creating or materially changing Octane code; other bundled skills cover React package bridges, component migration, intentional divergences, and SSR setup.' +
+				'Fetch an Octane agent skill by name. Call when starting work the skill covers: build-octane-software for engineering gates, bridge-react-package for porting a React library, migrate-react-component for JSX to .tsrx, react-divergences before assuming React behavior, setup-ssr for server rendering.' +
 				(repoMode ? ' Repo skills cover octane maintainer workflows.' : ''),
 			inputSchema: {
 				name: z.enum(Object.keys(skills)),
@@ -467,12 +485,19 @@ function registerRepoTools(server, repoRoot) {
 		{
 			title: 'Octane project map',
 			description:
-				'Return Octane repository map, source ownership, validation commands, and skill paths.',
+				'Call when you need Octane repo orientation: what the framework is, which source owns which behavior, the intentional divergences from React, the validation commands, and the full package inventory.',
 			inputSchema: {},
 		},
 		async () => {
-			const projectMap = await readFile(resolve(repoRoot, '.ai/project-map.md'), 'utf8');
-			return text(projectMap);
+			// Composed from the two generated sources rather than a hand-written
+			// summary, because both are CI-gated: AGENTS.md against .rulesync/rules,
+			// and packages.md against the workspace manifests. A third restatement
+			// would be the one free to drift.
+			const [rootRule, packages] = await Promise.all([
+				readFile(resolve(repoRoot, 'AGENTS.md'), 'utf8'),
+				readFile(resolve(repoRoot, 'docs/packages.md'), 'utf8'),
+			]);
+			return text(`${rootRule.trimEnd()}\n\n---\n\n${packages.trimStart()}`);
 		},
 	);
 
@@ -480,7 +505,8 @@ function registerRepoTools(server, repoRoot) {
 		'octane_triage_paths',
 		{
 			title: 'Triage Octane paths',
-			description: 'Classify changed paths by Octane repo area.',
+			description:
+				'Call before editing unfamiliar paths in this monorepo to learn which area owns them.',
 			inputSchema: {
 				paths: z.array(z.string()).describe('Repository-relative paths'),
 			},
@@ -495,7 +521,8 @@ function registerRepoTools(server, repoRoot) {
 		'octane_validate_plan',
 		{
 			title: 'Octane validation plan',
-			description: 'Recommend validation commands for changed paths and task kind.',
+			description:
+				'Call when a change is finished to get the validation commands that cover the paths you touched.',
 			inputSchema: {
 				paths: z.array(z.string()).default([]).describe('Repository-relative changed paths'),
 				taskKind: z
@@ -525,7 +552,8 @@ function registerRepoTools(server, repoRoot) {
 		'octane_scaffold_react_port',
 		{
 			title: 'Scaffold React test port',
-			description: 'Run scripts/scaffold-react-port.mjs for a React upstream test file.',
+			description:
+				'Call when porting a React test file into the conformance suite, returns a triage skeleton of in-scope cases and out-of-scope reasons.',
 			inputSchema: {
 				reactTestFile: z
 					.string()

package/src/index.test.js

@@ -1,7 +1,7 @@
 import { describe, expect, it } from 'vitest';
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';
-import { existsSync } from 'node:fs';
+import { existsSync, readdirSync } from 'node:fs';
 import { mkdir, mkdtemp, readFile, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
@@ -10,6 +10,7 @@ import {
 	areaForPath,
 	BENCHMARK_SUITES,
 	BUNDLED_SKILLS,
+	REPO_SKILLS,
 	createServer,
 	engineeringPlanFor,
 	isOctaneRepo,
@@ -30,6 +31,7 @@ describe('@octanejs/mcp-server helpers', () => {
 		expect(areaForPath('packages/radix/src/index.ts')).toBe('ecosystem-binding');
 		expect(areaForPath('packages/octane-mcp-server/src/index.js')).toBe('mcp-server');
 		expect(areaForPath('packages/adapter-vercel/src/index.ts')).toBe('deploy-adapter');
+		expect(areaForPath('packages/adapter-cloudflare/src/index.js')).toBe('deploy-adapter');
 		expect(areaForPath('packages/octane-evals/tools/run.mjs')).toBe('evals');
 		expect(areaForPath('website/src/pages/index.tsrx')).toBe('website');
 		expect(areaForPath('benchmarks/news/run.mjs')).toBe('benchmark');
@@ -40,6 +42,7 @@ describe('@octanejs/mcp-server helpers', () => {
 		const commands = validationFor(
 			[
 				'packages/adapter-vercel/src/index.ts',
+				'packages/adapter-cloudflare/src/index.js',
 				'packages/octane-evals/tools/run.mjs',
 				'website/src/pages/index.tsrx',
 			],
@@ -49,6 +52,9 @@ describe('@octanejs/mcp-server helpers', () => {
 		expect(commands).toContain(
 			'./node_modules/.bin/vitest run packages/adapter-vercel/tests --project adapter-vercel',
 		);
+		expect(commands).toContain(
+			'./node_modules/.bin/vitest run packages/adapter-cloudflare/tests --project adapter-cloudflare',
+		);
 		expect(commands).toContain(
 			'./node_modules/.bin/vitest run packages/octane-evals/tests --project octane-evals',
 		);
@@ -168,20 +174,50 @@ describe('@octanejs/mcp-server helpers', () => {
 		}
 	});
 
-	it('advertises the engineering gates during MCP initialization', async () => {
+	it('routes to the engineering gates without restating them at initialization', async () => {
+		// Initialization instructions are injected into every session, so they stay
+		// short and point at the tool. The gates themselves must still be reachable
+		//: that is the contract, not any particular wording.
 		const server = createServer({ repoRoot: resolve(PACKAGE_ROOT, '../..') });
 		const client = new Client({ name: 'octane-mcp-test', version: '1.0.0' });
 		const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
 
 		try {
 			await Promise.all([server.connect(serverTransport), client.connect(clientTransport)]);
-			expect(client.getInstructions()).toContain(
-				'Before creating or materially changing Octane software',
-			);
-			expect(client.getInstructions()).toContain('establish a relevant baseline before editing');
+			const instructions = client.getInstructions();
+			expect(instructions).toContain('octane_engineering_plan');
+			expect(instructions.length).toBeLessThan(600);
 
 			const tools = await client.listTools();
 			expect(tools.tools.map((tool) => tool.name)).toContain('octane_engineering_plan');
+
+			const plan = await client.callTool({
+				name: 'octane_engineering_plan',
+				arguments: { scope: 'framework-core', changeKind: 'performance' },
+			});
+			const body = plan.content[0].text;
+			expect(body).toContain('Identify hot paths and record a relevant baseline before editing.');
+			expect(body).toContain('build-octane-software');
+		} finally {
+			await client.close();
+			await server.close();
+		}
+	});
+
+	it('serves the project map from both generated, CI-gated sources', async () => {
+		// A hand-written map is the copy free to drift, which is why the old one
+		// did. Both halves here are regenerated and checked by CI.
+		const server = createServer({ repoRoot: resolve(PACKAGE_ROOT, '../..') });
+		const client = new Client({ name: 'octane-mcp-test', version: '1.0.0' });
+		const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+
+		try {
+			await Promise.all([server.connect(serverTransport), client.connect(clientTransport)]);
+			const map = (await client.callTool({ name: 'octane_project_map', arguments: {} })).content[0]
+				.text;
+			expect(map).toContain('Your React instincts are the main failure mode here');
+			expect(map).toContain('Package inventory (generated)');
+			expect(map).toContain('framework binding');
 		} finally {
 			await client.close();
 			await server.close();
@@ -202,6 +238,26 @@ describe('@octanejs/mcp-server helpers', () => {
 		}
 	});
 
+	it('serves every RuleSync skill, and only skills that exist', async () => {
+		// Checking that each mapped path resolves catches a dangling entry but not
+		// a missing one, which is how authoring-tsrx was added to .rulesync and
+		// stayed unreachable through octane_skill. Compare both directions.
+		const repoRoot = resolve(PACKAGE_ROOT, '../..');
+		const onDisk = readdirSync(resolve(repoRoot, '.rulesync/skills'), { withFileTypes: true })
+			.filter((entry) => entry.isDirectory())
+			.map((entry) => entry.name)
+			.sort();
+
+		expect(Object.keys(REPO_SKILLS).sort()).toEqual(onDisk);
+
+		for (const file of Object.values(REPO_SKILLS)) {
+			expect(file.startsWith('.rulesync/skills/')).toBe(true);
+			expect(existsSync(resolve(repoRoot, file))).toBe(true);
+			const body = await readFile(resolve(repoRoot, file), 'utf8');
+			expect(body).toMatch(/^---\n[\s\S]*?\ndescription: /);
+		}
+	});
+
 	it('runs the React port scaffolder wrapper', async () => {
 		const repoRoot = await mkdtemp(join(tmpdir(), 'octane-mcp-test-'));
 		await mkdir(join(repoRoot, 'scripts'), { recursive: true });