threenative-engine-mcp 0.2.6 → 0.2.8

package/README.md

@@ -1,18 +1,48 @@
 # threenative-engine-mcp
 
-An offline MCP server that lets a ThreeNative authoring agent search the committed engine
-capability manifest by situation and inspect one capability in detail.
+The ThreeNative planning gate uses this MCP server to discover engine capabilities and classic-game
+mechanics. Start with the installed `threenative-capabilities` skill, then `prd-creator`; the skill
+owns the discovery order and plan record.
 
-The server exposes exactly two read-only tools: `engine_search_capabilities` and
-`engine_capability_detail`.
+The server exposes `engine_search_capabilities`, `engine_capability_detail`,
+`engine_search_references`, `engine_reference_detail`, and `engine_save_reference`.
+Capability search works offline. Full requests use `scope: "request"` (up to 15 deduplicated
+matches); mechanic searches use `scope: "mechanic"` (up to five). Inspect `matchedSituation`
+and the detail constraints before implementing. A `none` capability result includes up to three
+reference suggestions.
 
 First infer the concrete mechanics implied by the request. Call `engine_search_capabilities` once
 with that mechanically explicit request and `scope: "request"`, then once per mechanic with
 `scope: "mechanic"`. Complete requests return up to 15 deduplicated capabilities; focused
-situations return up to five. A genre label alone returns no guessed recipe. Every result includes
+situations return up to five. A request that names a game or genre a starter kit covers (`like mario`, `zelda-style`) leads with a
+`starterKits` entry carrying `npx create-threenative <dir> --template <name>`; scaffold it first, then
+search the mechanics it does not cover. The kits and their words come from each `kit.json` through
+the manifest's `starterKits` section (verdict `"starterKit"` when no mechanic also matched). Every result includes
 `matchedSituation`, so an authoring agent can verify why it was selected instead of treating a
 lexical coincidence as engine guidance.
 
+Reference search reads a gzipped stub index; detail fetches one pinned game's map and cards lazily.
+The source is the latest release of [threenative-reverse-engineer-mcp](https://github.com/ThreeNativeHQ/threenative-reverse-engineer-mcp),
+separate CC-BY 4.0 data. Downloads validate before replacing the cache in
+`$XDG_CACHE_HOME/threenative/refs` (default `~/.cache/threenative/refs`), refresh with ETags, and
+work offline from that cache. The index has a 5-second fetch budget; game files have 30 seconds,
+including their response bodies. `THREENATIVE_REFERENCES_URL` overrides the release asset base URL;
+`THREENATIVE_REFERENCES_CACHE` overrides the cache directory. Without network or cache, tools report
+`references unavailable` and capability discovery keeps working.
+
+Saved references live in the game's `.threenative/refs/<game-id>.json`. Local entries take priority;
+published entries without a local override remain searchable and loadable, with their own pinned SHA.
+Successive local saves merge by id at the same commit SHA. A conflicting SHA is rejected without changing the saved file.
+The save tool returns a `gh issue create` command for a POSIX shell; run it in that shell.
+It does not send the contribution. Reference guardrail: mechanics and feel only, with pinned
+`file:line` sources; no code, level layouts, character names or art.
+
+## One call from the command line
+
+A session started outside the game folder never loads its `.mcp.json`. It calls a tool once
+instead: `node <game>/node_modules/@threenative/core/mcp/engine.mjs engine_search_capabilities
+'{"situation":"triple jump"}'` prints the tool's answer and exits 0, or names the error and exits 1.
+
 ## Which manifest the server reads
 
 The first that exists wins, so the manifest can never drift from the engine the project runs:

package/dist/index.d.ts

@@ -23,6 +23,20 @@ interface ICapabilityManifest {
     readonly version: number;
     readonly entries: readonly ICapabilityEntry[];
     readonly notOwned: readonly INotOwnedCapability[];
+    readonly starterKits?: readonly IStarterKit[];
+}
+interface IStarterKit {
+    readonly name: string;
+    readonly title: string;
+    readonly blurb: string;
+    /** Genre plus kit.json aliases, lowercase. */
+    readonly words: readonly string[];
+}
+interface IStarterKitResult {
+    readonly name: string;
+    readonly title: string;
+    readonly blurb: string;
+    readonly command: string;
 }
 interface ICapabilitySearchResult {
     readonly symbol: string;
@@ -35,7 +49,12 @@ interface ICapabilitySearchResult {
     readonly score: number;
 }
 interface ICapabilitySearchResponse {
-    readonly verdict: "matched" | "none";
+    /** Present when the request names a genre or game a starter kit covers; it leads the response. */
+    readonly starterKits?: readonly IStarterKitResult[];
+    /** Present when the request asks to reverse engineer a game: the tools that read its pinned decomp. */
+    readonly referenceTools?: readonly string[];
+    /** "starterKit": a kit matched but no engine capability did; scaffold the kit, then search its gaps. */
+    readonly verdict: "matched" | "none" | "starterKit";
     readonly results: readonly ICapabilitySearchResult[];
     readonly guidance: string;
 }
@@ -46,21 +65,21 @@ interface IEngineTool {
     readonly description: string;
     readonly annotations: {
         readonly destructiveHint: false;
-        readonly openWorldHint: false;
-        readonly readOnlyHint: true;
+        readonly openWorldHint: boolean;
+        readonly readOnlyHint: boolean;
     };
     readonly inputSchema: {
         readonly type: "object";
         readonly properties: Record<string, {
             readonly description?: string;
             readonly enum?: readonly string[];
-            readonly type: "string";
+            readonly type: "string" | "object";
         }>;
         readonly required: readonly string[];
         readonly additionalProperties: false;
     };
 }
-declare const ENGINE_MCP_TOOL_NAMES: readonly ["engine_search_capabilities", "engine_capability_detail"];
+declare const ENGINE_MCP_TOOL_NAMES: readonly ["engine_search_capabilities", "engine_capability_detail", "engine_search_references", "engine_reference_detail", "engine_save_reference"];
 /** Chosen by the current-manifest threshold sweep: the highest recalled candidate at 0.27. */
 declare const RELEVANCE_FLOOR = 0.27;
 declare function defaultManifestPath(cwd?: string): string;
@@ -81,7 +100,16 @@ declare function toolDefinitions(): readonly IEngineTool[];
  * line must be consumed silently. Extracted so the stdio contract is testable without a live
  * `process.stdin`: this framing is the whole surface an authoring agent's MCP client speaks.
  */
-declare function handleLine(line: string, manifestFile: string): string | undefined;
+declare function handleLine(line: string, manifestFile: string): Promise<string | undefined>;
+/**
+ * One tool call from the command line: `engine.mjs <tool> '<json arguments>'` prints the tool's
+ * text and exits 0, or names the error and exits 1. A session started outside the project never
+ * loads its `.mcp.json`, and this is how it still searches (PRD-750 kit-loop row 1).
+ */
+declare function runCli(argv: readonly string[], manifestFile?: string, io?: {
+    stderr: (text: string) => void;
+    stdout: (text: string) => void;
+}): Promise<number>;
 declare function runServer(manifestFile?: string): void;
 
-export { ENGINE_MCP_TOOL_NAMES, type ICapabilityDetail, type ICapabilityEntry, type ICapabilityManifest, type ICapabilitySearchResponse, type ICapabilitySearchResult, type IEngineTool, type INotOwnedCapability, RELEVANCE_FLOOR, capabilityDetail, capabilityDetails, capabilitySituationTokens, defaultManifestPath, handleLine, loadCapabilityManifest, runServer, searchCapabilities, toolDefinitions };
+export { ENGINE_MCP_TOOL_NAMES, type ICapabilityDetail, type ICapabilityEntry, type ICapabilityManifest, type ICapabilitySearchResponse, type ICapabilitySearchResult, type IEngineTool, type INotOwnedCapability, type IStarterKit, type IStarterKitResult, RELEVANCE_FLOOR, capabilityDetail, capabilityDetails, capabilitySituationTokens, defaultManifestPath, handleLine, loadCapabilityManifest, runCli, runServer, searchCapabilities, toolDefinitions };

package/dist/index.js

@@ -1,12 +1,444 @@
 #!/usr/bin/env node
-import { realpathSync, readFileSync, existsSync, mkdirSync, appendFileSync } from 'fs';
-import path from 'path';
+import { realpathSync, readFileSync, existsSync, mkdirSync, rmSync, writeFileSync, appendFileSync, renameSync, readdirSync } from 'fs';
+import path2 from 'path';
 import { createInterface } from 'readline';
 import { fileURLToPath } from 'url';
+import { createHash } from 'crypto';
+import os from 'os';
+import { gunzipSync } from 'zlib';
 
+var DEFAULT_REFERENCES_URL = "https://github.com/ThreeNativeHQ/threenative-reverse-engineer-mcp/releases/latest/download/";
+var FETCH_TIMEOUT_MS = 5e3;
+var GAME_FETCH_TIMEOUT_MS = 3e4;
+var ID = /^[a-z0-9][a-z0-9-]*$/u;
+function referencesBaseUrl() {
+  const value = process.env.THREENATIVE_REFERENCES_URL?.trim() || DEFAULT_REFERENCES_URL;
+  return value.endsWith("/") ? value : `${value}/`;
+}
+function referencesCacheDir() {
+  const override = process.env.THREENATIVE_REFERENCES_CACHE?.trim();
+  const source = createHash("sha256").update(referencesBaseUrl()).digest("hex").slice(0, 16);
+  if (override) return path2.join(path2.resolve(override), source);
+  const cacheHome = process.env.XDG_CACHE_HOME?.trim() || path2.join(os.homedir(), ".cache");
+  return path2.join(cacheHome, "threenative", "refs", source);
+}
+function localReferencesDir(cwd = process.cwd()) {
+  return path2.join(cwd, ".threenative", "refs");
+}
+function fail(where, reason) {
+  throw new Error(`TN_REFERENCES_MALFORMED: ${where}: ${reason}`);
+}
+function record(value, where, keys) {
+  if (typeof value !== "object" || value === null || Array.isArray(value))
+    fail(where, "expected an object");
+  const unknown = Object.keys(value).filter((key) => !keys.includes(key));
+  if (unknown.length > 0)
+    fail(where, `unknown field ${unknown.map((key) => `'${key}'`).join(", ")}`);
+  return value;
+}
+function text(value, where) {
+  if (typeof value !== "string" || value.trim().length === 0)
+    fail(where, "expected a non-empty string");
+  if (/```|~~~/u.test(value)) fail(where, "holds a code block; describe the behaviour instead");
+  return value;
+}
+function id(value, where) {
+  const result = text(value, where);
+  if (!ID.test(result)) fail(where, `'${result}' is not a lowercase kebab-case id`);
+  return result;
+}
+function texts(value, where) {
+  if (!Array.isArray(value)) fail(where, "expected an array of strings");
+  return value.map((entry, index) => text(entry, `${where}[${index}]`));
+}
+function list(value, where, item) {
+  if (!Array.isArray(value)) fail(where, "expected an array");
+  return value.map((entry, index) => item(entry, `${where}[${index}]`));
+}
+function line(value, where) {
+  if (!Number.isInteger(value) || value < 1) fail(where, "expected a line number");
+  return value;
+}
+function sourcePath(value, where) {
+  const result = text(value, where);
+  if (path2.isAbsolute(result) || result.split("/").includes("..") || !/^[a-zA-Z0-9_./-]+$/u.test(result))
+    fail(where, "expected a safe relative source path");
+  return result;
+}
+function prose(value, where) {
+  const result = text(value, where);
+  if (result.includes("```")) fail(where, "holds a code block; describe the behaviour instead");
+  return result;
+}
+function validateStub(value, where) {
+  const stub = record(value, where, [
+    "id",
+    "game",
+    "kind",
+    "name",
+    "summary",
+    "tags",
+    "capabilities"
+  ]);
+  if (stub.kind !== "node" && stub.kind !== "card") fail(`${where}.kind`, "expected node or card");
+  return {
+    capabilities: texts(stub.capabilities, `${where}.capabilities`),
+    game: id(stub.game, `${where}.game`),
+    id: id(stub.id, `${where}.id`),
+    kind: stub.kind,
+    name: text(stub.name, `${where}.name`),
+    summary: prose(stub.summary, `${where}.summary`),
+    tags: texts(stub.tags, `${where}.tags`)
+  };
+}
+function validateReferenceIndex(value, where = "index") {
+  const index = record(value, where, ["version", "games", "stubs"]);
+  if (index.version !== 1) fail(`${where}.version`, "expected 1");
+  const games = list(index.games, `${where}.games`, (entry, at) => {
+    const game = record(entry, at, [
+      "id",
+      "title",
+      "platform",
+      "repo",
+      "tier",
+      "kind",
+      "rating",
+      "genre",
+      "subgenre"
+    ]);
+    if (game.tier !== 1 && game.tier !== 2) fail(`${at}.tier`, "expected 1 or 2");
+    return {
+      id: id(game.id, `${at}.id`),
+      platform: text(game.platform, `${at}.platform`),
+      repo: text(game.repo, `${at}.repo`),
+      tier: game.tier,
+      title: text(game.title, `${at}.title`)
+    };
+  });
+  const stubs = list(index.stubs, `${where}.stubs`, validateStub);
+  unique(
+    games.map((game) => game.id),
+    `${where}.games`
+  );
+  unique(
+    stubs.map((stub) => `${stub.game}/${stub.kind}/${stub.id}`),
+    `${where}.stubs`
+  );
+  for (const stub of stubs)
+    if (!games.some((game) => game.id === stub.game)) fail(where, `missing game '${stub.game}'`);
+  return { games, stubs, version: 1 };
+}
+function validateNode(value, where) {
+  const node = record(value, where, [
+    "id",
+    "name",
+    "purpose",
+    "parent",
+    "paths",
+    "functions",
+    "dependsOn"
+  ]);
+  return {
+    dependsOn: texts(node.dependsOn, `${where}.dependsOn`),
+    functions: list(node.functions, `${where}.functions`, (entry, at) => {
+      const fn = record(entry, at, ["name", "path", "lines"]);
+      if (!Array.isArray(fn.lines) || fn.lines.length !== 2)
+        fail(`${at}.lines`, "expected [from, to]");
+      const from = line(fn.lines[0], `${at}.lines[0]`);
+      const to = line(fn.lines[1], `${at}.lines[1]`);
+      if (to < from) fail(`${at}.lines`, "ends before it starts");
+      return {
+        lines: [from, to],
+        name: text(fn.name, `${at}.name`),
+        path: sourcePath(fn.path, `${at}.path`)
+      };
+    }),
+    id: id(node.id, `${where}.id`),
+    name: text(node.name, `${where}.name`),
+    paths: list(node.paths, `${where}.paths`, sourcePath),
+    purpose: prose(node.purpose, `${where}.purpose`),
+    ...node.parent === void 0 ? {} : { parent: id(node.parent, `${where}.parent`) }
+  };
+}
+function validateCard(value, where) {
+  const card = record(value, where, [
+    "id",
+    "node",
+    "name",
+    "summary",
+    "behavior",
+    "constants",
+    "sources",
+    "capabilities",
+    "tags"
+  ]);
+  const sources = list(card.sources, `${where}.sources`, (entry, at) => {
+    const source = record(entry, at, ["path", "line"]);
+    return { line: line(source.line, `${at}.line`), path: sourcePath(source.path, `${at}.path`) };
+  });
+  if (sources.length === 0) fail(`${where}.sources`, "expected at least one source");
+  return {
+    behavior: prose(card.behavior, `${where}.behavior`),
+    capabilities: texts(card.capabilities, `${where}.capabilities`),
+    constants: list(card.constants, `${where}.constants`, (entry, at) => {
+      const constant = record(entry, at, ["name", "value", "unit", "source"]);
+      if ((typeof constant.value !== "number" || !Number.isFinite(constant.value)) && typeof constant.value !== "string")
+        fail(`${at}.value`, "expected a number or a string");
+      const source = text(constant.source, `${at}.source`);
+      const citation = /^(.*):([1-9][0-9]*)$/u.exec(source);
+      if (!citation) fail(`${at}.source`, "expected source path:line");
+      sourcePath(citation[1], `${at}.source`);
+      return {
+        name: text(constant.name, `${at}.name`),
+        source,
+        unit: text(constant.unit, `${at}.unit`),
+        value: typeof constant.value === "string" ? text(constant.value, `${at}.value`) : constant.value
+      };
+    }),
+    id: id(card.id, `${where}.id`),
+    name: text(card.name, `${where}.name`),
+    node: id(card.node, `${where}.node`),
+    sources,
+    summary: prose(card.summary, `${where}.summary`),
+    tags: texts(card.tags, `${where}.tags`)
+  };
+}
+function unique(ids, where) {
+  const seen = /* @__PURE__ */ new Set();
+  for (const value of ids) {
+    if (seen.has(value)) fail(where, `duplicate id '${value}'`);
+    seen.add(value);
+  }
+}
+function validateReferenceGame(value, where = "game") {
+  const game = record(value, where, ["version", "id", "title", "repo", "sha", "nodes", "cards"]);
+  if (game.version !== 1) fail(`${where}.version`, "expected 1");
+  const nodes = list(game.nodes, `${where}.nodes`, validateNode);
+  const cards = list(game.cards, `${where}.cards`, validateCard);
+  unique(
+    nodes.map((node) => node.id),
+    `${where}.nodes`
+  );
+  unique(
+    cards.map((card) => card.id),
+    `${where}.cards`
+  );
+  const nodeIds = new Set(nodes.map((node) => node.id));
+  for (const node of nodes) {
+    for (const dependency of node.dependsOn)
+      if (!nodeIds.has(dependency)) fail(where, `missing dependency '${dependency}'`);
+    const ancestors = /* @__PURE__ */ new Set([node.id]);
+    let parent = node.parent;
+    while (parent !== void 0) {
+      if (ancestors.has(parent)) fail(where, `cyclic parent '${parent}'`);
+      ancestors.add(parent);
+      parent = nodes.find((entry) => entry.id === parent)?.parent;
+    }
+  }
+  for (const node of nodes)
+    if (node.parent !== void 0 && !nodeIds.has(node.parent))
+      fail(`${where}.nodes.${node.id}.parent`, `no node '${node.parent}'`);
+  for (const card of cards)
+    if (!nodeIds.has(card.node)) fail(`${where}.cards.${card.id}.node`, `no node '${card.node}'`);
+  const sha = text(game.sha, `${where}.sha`);
+  if (!/^[0-9a-f]{40}$/u.test(sha)) fail(`${where}.sha`, "expected a commit SHA");
+  return {
+    cards,
+    id: id(game.id, `${where}.id`),
+    nodes,
+    repo: text(game.repo, `${where}.repo`),
+    sha,
+    title: text(game.title, `${where}.title`),
+    version: 1
+  };
+}
+function referenceStubs(game) {
+  return [
+    ...game.nodes.map((node) => ({
+      capabilities: [],
+      game: game.id,
+      id: node.id,
+      kind: "node",
+      name: node.name,
+      summary: node.purpose,
+      tags: []
+    })),
+    ...game.cards.map((card) => ({
+      capabilities: card.capabilities,
+      game: game.id,
+      id: card.id,
+      kind: "card",
+      name: card.name,
+      summary: card.summary,
+      tags: card.tags
+    }))
+  ];
+}
+async function cachedAsset(name, parse, timeout = FETCH_TIMEOUT_MS) {
+  const file = path2.join(referencesCacheDir(), name);
+  const etagFile = `${file}.etag`;
+  let response;
+  try {
+    const etag2 = existsSync(file) && existsSync(etagFile) ? readFileSync(etagFile, "utf8") : "";
+    response = await fetch(new URL(name, referencesBaseUrl()), {
+      headers: etag2.length > 0 ? { "if-none-match": etag2 } : {},
+      signal: AbortSignal.timeout(timeout)
+    });
+  } catch (error) {
+    if (existsSync(file)) return parse(readFileSync(file));
+    throw new Error(`TN_REFERENCES_UNAVAILABLE: ${name}: ${String(error)}`);
+  }
+  if (response.status === 304 && existsSync(file)) return parse(readFileSync(file));
+  if (!response.ok) {
+    if (existsSync(file)) return parse(readFileSync(file));
+    throw new Error(`TN_REFERENCES_UNAVAILABLE: ${name}: HTTP ${response.status}`);
+  }
+  let body;
+  try {
+    body = Buffer.from(await response.arrayBuffer());
+  } catch (error) {
+    if (existsSync(file)) return parse(readFileSync(file));
+    throw new Error(`TN_REFERENCES_UNAVAILABLE: ${name}: ${String(error)}`);
+  }
+  const parsed = parse(body);
+  mkdirSync(path2.dirname(file), { recursive: true });
+  atomicWrite(file, body);
+  const etag = response.headers.get("etag");
+  if (etag === null) rmSync(etagFile, { force: true });
+  else writeFileSync(etagFile, etag);
+  return parsed;
+}
+function parseJson(body, name) {
+  try {
+    return JSON.parse(body.toString("utf8"));
+  } catch (error) {
+    return fail(name, `cannot parse JSON: ${String(error)}`);
+  }
+}
+var indexLoad;
+var gameLoads = /* @__PURE__ */ new Map();
+function loadReferenceIndex() {
+  indexLoad ??= cachedAsset(
+    "index.json.gz",
+    (body) => validateReferenceIndex(parseJson(gunzipSync(body), "index.json.gz"), "index.json.gz")
+  ).catch((error) => {
+    indexLoad = void 0;
+    throw error;
+  });
+  return indexLoad;
+}
+function loadLocalReferenceGames(cwd = process.cwd()) {
+  const directory = localReferencesDir(cwd);
+  if (!existsSync(directory)) return [];
+  return readdirSync(directory).filter((file) => file.endsWith(".json")).sort().map((file) => {
+    const game = validateReferenceGame(
+      parseJson(readFileSync(path2.join(directory, file)), file),
+      path2.join(".threenative", "refs", file)
+    );
+    if (game.id !== path2.basename(file, ".json"))
+      fail(file, `id '${game.id}' differs from filename`);
+    return game;
+  });
+}
+function loadReferenceGame(gameId, cwd = process.cwd()) {
+  id(gameId, "game id");
+  const file = path2.join(localReferencesDir(cwd), `${gameId}.json`);
+  if (existsSync(file)) {
+    const local = validateReferenceGame(parseJson(readFileSync(file), file), file);
+    if (local.id !== gameId) fail(file, `id '${local.id}' differs from requested '${gameId}'`);
+    return Promise.resolve(local);
+  }
+  return loadReleaseReferenceGame(gameId);
+}
+function loadReleaseReferenceGame(gameId) {
+  const name = `game-${id(gameId, "game id")}.json`;
+  let load = gameLoads.get(name);
+  if (load === void 0) {
+    load = cachedAsset(
+      name,
+      (body) => {
+        const game = validateReferenceGame(parseJson(body, name), name);
+        if (game.id !== gameId) fail(name, `id '${game.id}' differs from requested '${gameId}'`);
+        return game;
+      },
+      GAME_FETCH_TIMEOUT_MS
+    ).catch((error) => {
+      gameLoads.delete(name);
+      throw error;
+    });
+    gameLoads.set(name, load);
+  }
+  return load;
+}
+function atomicWrite(file, value) {
+  const temporary = `${file}.${process.pid}.tmp`;
+  try {
+    writeFileSync(temporary, value);
+    renameSync(temporary, file);
+  } finally {
+    rmSync(temporary, { force: true });
+  }
+}
+function shellQuote(value) {
+  return `'${value.replaceAll("'", `'"'"'`)}'`;
+}
+var CONTRIBUTION_REPO = "ThreeNativeHQ/threenative-reverse-engineer-mcp";
+function saveReferenceGame(value, cwd = process.cwd()) {
+  const incoming = record(value, "reference", [
+    "version",
+    "id",
+    "title",
+    "repo",
+    "sha",
+    "nodes",
+    "cards"
+  ]);
+  const gameId = id(incoming.id, "reference.id");
+  const file = path2.join(localReferencesDir(cwd), `${gameId}.json`);
+  const previous = existsSync(file) ? validateReferenceGame(parseJson(readFileSync(file), file), file) : void 0;
+  if (previous !== void 0 && previous.sha !== incoming.sha)
+    fail(
+      "reference.sha",
+      `saved game '${gameId}' is pinned to ${previous.sha}; cannot merge revision ${String(incoming.sha)}`
+    );
+  const merge = (old, next) => {
+    if (!Array.isArray(next)) fail("reference", "expected an array");
+    const replacements = new Set(
+      next.map(
+        (entry) => typeof entry === "object" && entry !== null && "id" in entry ? entry.id : void 0
+      )
+    );
+    return [...old.filter((entry) => !replacements.has(entry.id)), ...next];
+  };
+  const merged = validateReferenceGame(
+    previous === void 0 ? incoming : {
+      ...incoming,
+      cards: merge(previous.cards, incoming.cards),
+      nodes: merge(previous.nodes, incoming.nodes)
+    },
+    "reference"
+  );
+  mkdirSync(path2.dirname(file), { recursive: true });
+  atomicWrite(file, `${JSON.stringify(merged, null, 2)}
+`);
+  const relative = path2.relative(cwd, file);
+  const title = `Reference cards: ${merged.title} (${merged.nodes.length} nodes, ${merged.cards.length} cards)`;
+  return {
+    contribution: {
+      command: `gh issue create --repo ${CONTRIBUTION_REPO} --title ${shellQuote(title)} --body-file ${shellQuote(relative)}`,
+      title
+    },
+    saved: relative
+  };
+}
+
+// src/index.ts
 var ENGINE_MCP_TOOL_NAMES = [
   "engine_search_capabilities",
-  "engine_capability_detail"
+  "engine_capability_detail",
+  "engine_search_references",
+  "engine_reference_detail",
+  "engine_save_reference"
 ];
 var DEFAULT_MANIFEST_FILE = "capabilities.json";
 var STOP_WORDS = /* @__PURE__ */ new Set([
@@ -125,29 +557,29 @@ var STOP_WORDS = /* @__PURE__ */ new Set([
 var MAX_COMPLETE_REQUEST_RESULTS = 15;
 var MAX_SITUATION_RESULTS = 5;
 var RELEVANCE_FLOOR = 0.27;
-var AUTHORING_INSTRUCTIONS = `Before authoring, infer concrete gameplay mechanics. Preserve the request's distinctive fantasy: choose the smallest loop that uses its characteristic setting, traversal medium, or simulation instead of a generic character game with themed props, and search those implied mechanics even when the user did not name engine terms. Search the mechanically explicit complete request with scope "request", then each mechanic with scope "mechanic". A genre label alone is not a capability query: clarify or decompose it; do not assume a preset. Inspect capability detail and obey constraints before implementing. Capability detail is authoritative on platform support: never invent a platform limitation it does not state. A response with verdict "none" is an actionable answer: follow its guidance and write game-owned behavior in src/ instead of rephrasing the same request.`;
+var AUTHORING_INSTRUCTIONS = "Invoke threenative-capabilities to route authoring. New games: steps 1-8 \u2014 prompt, matching starter kit (minimal fallback), mechanics references PLUS built-in capabilities, core-mechanics plan via prd-creator, required textures, execute, mechanics playtest, reference-image visual judge. Existing games: steps 5-7 only \u2014 required textures, execute and mechanics playtest using existing context; no kit selection, rediscovery, whole-game replanning or added step 8. In both routes, execute plan with subagents focused on specific areas: bounded tasks, file ownership, then coordinator integration before step 7 mechanics playtests. Follow binding capability constraints. References borrow mechanics only: no code, level layouts, character names or art; cite pinned file:line sources.";
 var GENERIC_GUIDANCE = "No installed engine capability matches this situation. Decompose it into concrete mechanics and write the game-owned behavior in your project's src/; inspect the relevant template AGENTS.md before adding a package.";
 function defaultManifestPath(cwd = process.cwd()) {
   const override = process.env.THREENATIVE_CAPABILITIES_MANIFEST;
-  if (override !== void 0 && override.trim().length > 0) return path.resolve(cwd, override);
-  for (let directory = path.resolve(cwd); ; directory = path.dirname(directory)) {
-    const nodeModules = path.join(directory, "node_modules");
-    const installed = path.join(nodeModules, "@threenative", "core", "capabilities.json");
+  if (override !== void 0 && override.trim().length > 0) return path2.resolve(cwd, override);
+  for (let directory = path2.resolve(cwd); ; directory = path2.dirname(directory)) {
+    const nodeModules = path2.join(directory, "node_modules");
+    const installed = path2.join(nodeModules, "@threenative", "core", "capabilities.json");
     if (existsSync(installed)) {
-      const relative = path.relative(realpathSync(directory), realpathSync(nodeModules));
-      if (relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative))
+      const relative = path2.relative(realpathSync(directory), realpathSync(nodeModules));
+      if (relative !== ".." && !relative.startsWith(`..${path2.sep}`) && !path2.isAbsolute(relative))
         return installed;
     }
-    const parent = path.dirname(directory);
+    const parent = path2.dirname(directory);
     if (parent === directory) break;
   }
-  for (let directory = path.dirname(fileURLToPath(import.meta.url)); ; directory = path.dirname(directory)) {
-    const repository = path.join(directory, "packages", "core", "capabilities.json");
+  for (let directory = path2.dirname(fileURLToPath(import.meta.url)); ; directory = path2.dirname(directory)) {
+    const repository = path2.join(directory, "packages", "core", "capabilities.json");
     if (existsSync(repository)) return repository;
-    const parent = path.dirname(directory);
+    const parent = path2.dirname(directory);
     if (parent === directory) break;
   }
-  return path.resolve(cwd, DEFAULT_MANIFEST_FILE);
+  return path2.resolve(cwd, DEFAULT_MANIFEST_FILE);
 }
 function manifestError(file, reason) {
   return new Error(`TN_ENGINE_CAPABILITIES_MANIFEST: ${file}: ${reason}`);
@@ -170,6 +602,11 @@ function validateManifest(value, file) {
       throw manifestError(file, `entry ${index} is malformed`);
     }
   }
+  for (const [index, raw] of (Array.isArray(value.starterKits) ? value.starterKits : []).entries()) {
+    if (!isRecord(raw) || typeof raw.name !== "string" || typeof raw.title !== "string" || typeof raw.blurb !== "string" || !isStringArray(raw.words)) {
+      throw manifestError(file, `starterKits ${index} is malformed`);
+    }
+  }
   const notOwnedIds = /* @__PURE__ */ new Set();
   for (const [index, raw] of value.notOwned.entries()) {
     if (!isRecord(raw) || typeof raw.id !== "string" || raw.id.trim().length === 0 || !Array.isArray(raw.situations) || raw.situations.length === 0 || !raw.situations.every(
@@ -245,13 +682,13 @@ function agreement(situation, query) {
 }
 function scorePhrase(value, queryTokens, queryText, weights) {
   const phrase = tokens(value);
-  const unique = [...new Set(phrase)];
-  const total = unique.reduce((sum, token) => sum + weightOf(weights, token), 0);
-  const matched = unique.filter((token) => queryTokens.has(token)).reduce((sum, token) => sum + weightOf(weights, token), 0);
+  const unique2 = [...new Set(phrase)];
+  const total = unique2.reduce((sum, token) => sum + weightOf(weights, token), 0);
+  const matched = unique2.filter((token) => queryTokens.has(token)).reduce((sum, token) => sum + weightOf(weights, token), 0);
   const phraseBonus = phrase.join(" ").includes(queryText) || queryText.includes(phrase.join(" ")) ? 1 : 0;
   if (total === 0 || matched === 0 && phraseBonus === 0) return void 0;
   const coverage = matched / total;
-  const agreed = agreement(unique, queryTokens);
+  const agreed = agreement(unique2, queryTokens);
   return { agreed, coverage, matched, phraseBonus, score: coverage * agreed + phraseBonus };
 }
 function isDistinctivePhrase(candidate) {
@@ -335,10 +772,62 @@ function capabilitySearchKey(entry) {
 ${entry.summary}
 ${entry.situations.join("\n")}`;
 }
+function matchedStarterKits(situation, kits) {
+  const words = (text2) => ` ${text2.toLowerCase().replace(/[^a-z0-9]+/gu, " ").trim()} `;
+  const request = words(situation);
+  const claims = kits.map((kit) => ({
+    kit,
+    spans: kit.words.flatMap((word) => {
+      const at = request.indexOf(words(word));
+      return at < 0 ? [] : [{ at, end: at + words(word).length }];
+    })
+  }));
+  const inside = (span, own) => claims.some(
+    (other) => other !== own && other.spans.some(
+      (o) => o.at <= span.at && o.end >= span.end && o.end - o.at > span.end - span.at
+    )
+  );
+  return claims.map((claim) => ({
+    at: Math.min(...claim.spans.filter((span) => !inside(span, claim)).map((span) => span.at)),
+    kit: claim.kit
+  })).filter(({ at }) => Number.isFinite(at)).sort((left, right) => left.at - right.at).map(({ kit: { blurb, name, title } }) => ({
+    blurb,
+    command: `npx create-threenative <dir> --template ${name}`,
+    name,
+    title
+  }));
+}
 function searchCapabilities(situation, manifestFile = defaultManifestPath(), scope = "mechanic") {
   if (typeof situation !== "string" || situation.trim().length === 0)
     throw new Error("engine_search_capabilities requires a non-empty situation string.");
   const manifest = loadCapabilityManifest(manifestFile);
+  const starterKits = matchedStarterKits(situation, manifest.starterKits ?? []);
+  const response = withReferenceTools(situation, searchMechanics(situation, manifest, scope));
+  if (starterKits.length === 0) return response;
+  return {
+    starterKits,
+    ...response,
+    ...response.verdict === "none" ? {
+      guidance: `Scaffold from the starter kit first, then search the mechanics it does not cover. ${response.guidance}`,
+      verdict: "starterKit"
+    } : {}
+  };
+}
+var REVERSE_ENGINEER = /\breverse[\s-]?engineer|\bdecomp|\bdisassembl/iu;
+var REFERENCE_TOOLS = [
+  "engine_search_references",
+  "engine_reference_detail",
+  "engine_save_reference"
+];
+function withReferenceTools(situation, response) {
+  if (!REVERSE_ENGINEER.test(situation)) return response;
+  return {
+    referenceTools: REFERENCE_TOOLS,
+    ...response,
+    guidance: `Reverse engineer the game with engine_search_references, then engine_reference_detail for its pinned cards. ${response.guidance}`
+  };
+}
+function searchMechanics(situation, manifest, scope) {
   const query = tokens(situation);
   const limit = scope === "request" ? MAX_COMPLETE_REQUEST_RESULTS : MAX_SITUATION_RESULTS;
   const weights = tokenWeights(manifest.entries);
@@ -432,19 +921,61 @@ var TOOL_DEFINITIONS = [
       required: ["symbol"],
       type: "object"
     }
+  },
+  {
+    name: "engine_search_references",
+    description: "Reverse engineer classic games: search mechanic cards and repository map nodes from their decomps. Tier-2 titles link to repos to explore and save. References describe feel only; borrow algorithms, cite pinned sources, copy no code or art.",
+    annotations: { destructiveHint: false, openWorldHint: true, readOnlyHint: true },
+    inputSchema: {
+      type: "object",
+      additionalProperties: false,
+      properties: { situation: { type: "string" } },
+      required: ["situation"]
+    }
+  },
+  {
+    name: "engine_reference_detail",
+    description: "Reverse engineer a game: read its pinned map or mechanic card. A node includes files, key functions, dependencies and child nodes; a card includes constants and sources.",
+    annotations: { destructiveHint: false, openWorldHint: true, readOnlyHint: true },
+    inputSchema: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        game: { type: "string" },
+        id: { type: "string" },
+        kind: { type: "string", enum: ["node", "card"] }
+      },
+      required: ["game", "id", "kind"]
+    }
+  },
+  {
+    name: "engine_save_reference",
+    description: "Save what you reverse engineer: validate and save a pinned game's repository map and mechanic cards to .threenative/refs, merged by id at the same SHA; conflicting revisions are refused. Pass a game object with version:1, id, title, repo, sha, nodes and cards. Returns a POSIX-shell contribution command for review; does not send it. Unknown fields and fenced code are refused.",
+    annotations: { destructiveHint: false, openWorldHint: false, readOnlyHint: false },
+    inputSchema: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        game: {
+          type: "object",
+          description: "Pinned game reference: version, id, title, repo, sha (40 hex), nodes [{id,name,purpose,parent?,paths,functions:[{name,path,lines:[from,to]}],dependsOn}], cards [{id,node,name,summary,behavior,constants:[{name,value,unit,source}],sources:[{path,line}],capabilities,tags}]. No extra fields or code fences."
+        }
+      },
+      required: ["game"]
+    }
   }
 ];
 function toolDefinitions() {
   return TOOL_DEFINITIONS;
 }
-var DEFAULT_LOG_FILE = path.join(".threenative", "engine-mcp.log");
+var DEFAULT_LOG_FILE = path2.join(".threenative", "engine-mcp.log");
 var logBroken = false;
 function logToolCall(entry) {
   if (logBroken) return;
   const target = process.env.THREENATIVE_ENGINE_MCP_LOG ?? DEFAULT_LOG_FILE;
   if (target === "off") return;
   try {
-    mkdirSync(path.dirname(path.resolve(target)), { recursive: true });
+    mkdirSync(path2.dirname(path2.resolve(target)), { recursive: true });
     appendFileSync(target, `${JSON.stringify({ time: (/* @__PURE__ */ new Date()).toISOString(), ...entry })}
 `);
   } catch (error) {
@@ -453,11 +984,11 @@ function logToolCall(entry) {
 `);
   }
 }
-function jsonRpcError(id, code, message) {
-  return JSON.stringify({ id, jsonrpc: "2.0", error: { code, message } });
+function jsonRpcError(id2, code, message) {
+  return JSON.stringify({ id: id2, jsonrpc: "2.0", error: { code, message } });
 }
-function jsonRpcResult(id, result) {
-  return JSON.stringify({ id, jsonrpc: "2.0", result });
+function jsonRpcResult(id2, result) {
+  return JSON.stringify({ id: id2, jsonrpc: "2.0", result });
 }
 function writeLine(value) {
   process.stdout.write(`${value}
@@ -466,7 +997,77 @@ function writeLine(value) {
 function toolText(value) {
   return { content: [{ text: JSON.stringify(value, null, 2), type: "text" }] };
 }
-function handleToolCall(params, manifestFile) {
+async function searchReferences(situation, limit = 5) {
+  const local = loadLocalReferenceGames();
+  let release;
+  try {
+    release = await loadReferenceIndex();
+  } catch (error) {
+    if (!(error instanceof Error && error.message.startsWith("TN_REFERENCES_UNAVAILABLE:")))
+      throw error;
+    if (local.length === 0)
+      return {
+        results: [],
+        guidance: "references unavailable: no release cache or network; capability search still works."
+      };
+  }
+  const localIds = new Set(local.map((game) => game.id));
+  const localStubs = local.flatMap(referenceStubs);
+  const localKeys = new Set(localStubs.map((stub) => `${stub.game}/${stub.kind}/${stub.id}`));
+  const games = [
+    ...(release?.games ?? []).filter((game) => !localIds.has(game.id)),
+    ...local.map((game) => ({
+      id: game.id,
+      title: game.title,
+      repo: game.repo,
+      platform: "local",
+      tier: 1
+    }))
+  ];
+  const stubs = [
+    ...(release?.stubs ?? []).filter(
+      (stub) => !localKeys.has(`${stub.game}/${stub.kind}/${stub.id}`)
+    ),
+    ...localStubs
+  ];
+  const titles = new Map(games.map((game) => [game.id, game.title]));
+  const candidates = [
+    ...stubs.map((stub) => ({
+      ...stub,
+      title: titles.get(stub.game) ?? ""
+    })),
+    ...games.filter((game) => game.tier === 2).map((game) => ({
+      ...game,
+      game: game.id,
+      kind: "game",
+      name: game.title,
+      summary: game.title,
+      tags: [],
+      capabilities: [],
+      guidance: "Explore this repository, then call engine_save_reference."
+    }))
+  ];
+  const phrases = candidates.map((stub) => ({
+    situations: [stub.name, stub.summary, ...stub.tags],
+    aliases: [stub.title]
+  }));
+  const weights = tokenWeights(phrases);
+  const query = tokens(situation);
+  return {
+    guidance: "",
+    results: candidates.map((stub, index) => {
+      const content = situationScore(query, phrases[index]?.situations ?? [], [], weights);
+      const title = scoreAliases(
+        phrases[index]?.aliases ?? [],
+        new Set(query),
+        query.join(" "),
+        weights
+      );
+      return { ...stub, ...content, score: content.score + title };
+    }).filter((stub) => stub.score >= RELEVANCE_FLOOR).sort((a, b) => b.score - a.score || a.id.localeCompare(b.id)).slice(0, limit)
+  };
+}
+async function handleToolCall(params, manifestFile) {
   const name = params.name;
   const argumentsValue = isRecord(params.arguments) ? params.arguments : {};
   if (name === "engine_search_capabilities") {
@@ -483,7 +1084,17 @@ function handleToolCall(params, manifestFile) {
       tool: name,
       verdict: response.verdict
     });
-    return toolText(response);
+    return toolText(
+      response.verdict === "none" ? {
+        ...response,
+        references: await searchReferences(argumentsValue.situation, 3).catch(
+          (error) => ({
+            results: [],
+            guidance: `references unavailable: ${String(error)}`
+          })
+        )
+      } : response
+    );
   }
   if (name === "engine_capability_detail") {
     if (typeof argumentsValue.symbol !== "string")
@@ -506,13 +1117,49 @@ function handleToolCall(params, manifestFile) {
     });
     return toolText(detail);
   }
+  if (name === "engine_search_references") {
+    if (typeof argumentsValue.situation !== "string" || !argumentsValue.situation.trim())
+      throw new Error("engine_search_references requires a non-empty string 'situation'.");
+    const response = await searchReferences(argumentsValue.situation);
+    logToolCall({
+      tool: name,
+      situation: argumentsValue.situation,
+      results: response.results.map((entry) => entry.id)
+    });
+    return toolText(response);
+  }
+  if (name === "engine_reference_detail") {
+    if (typeof argumentsValue.game !== "string" || typeof argumentsValue.id !== "string" || argumentsValue.kind !== "node" && argumentsValue.kind !== "card")
+      throw new Error("engine_reference_detail requires game, id and kind (node or card).");
+    let game = await loadReferenceGame(argumentsValue.game);
+    const { id: id2, kind } = argumentsValue;
+    let entry = kind === "node" ? game.nodes.find((node) => node.id === id2) : game.cards.find((card) => card.id === id2);
+    if (!entry) {
+      game = await loadReleaseReferenceGame(argumentsValue.game);
+      entry = kind === "node" ? game.nodes.find((node) => node.id === id2) : game.cards.find((card) => card.id === id2);
+    }
+    if (!entry) throw new Error(`No reference ${kind} '${id2}' in '${game.id}'.`);
+    logToolCall({ tool: name, game: game.id, id: id2, kind });
+    return toolText({
+      game: game.id,
+      title: game.title,
+      repo: game.repo,
+      sha: game.sha,
+      ...kind === "node" ? { node: entry, children: game.nodes.filter((node) => node.parent === id2) } : { card: entry }
+    });
+  }
+  if (name === "engine_save_reference") {
+    const saved = saveReferenceGame(argumentsValue.game);
+    logToolCall({ tool: name, saved: saved.saved });
+    return toolText(saved);
+  }
   throw new Error(`Unknown engine MCP tool '${String(name)}'.`);
 }
-function handleLine(line, manifestFile) {
-  if (line.trim().length === 0) return void 0;
+async function handleLine(line2, manifestFile) {
+  if (line2.trim().length === 0) return void 0;
   let request;
   try {
-    request = JSON.parse(line);
+    request = JSON.parse(line2);
   } catch (error) {
     return jsonRpcError(null, -32700, `Invalid JSON: ${String(error)}`);
   }
@@ -524,7 +1171,7 @@ function handleLine(line, manifestFile) {
         capabilities: { tools: { listChanged: false } },
         instructions: AUTHORING_INSTRUCTIONS,
         protocolVersion: "2025-06-18",
-        serverInfo: { name: "threenative-engine-mcp", version: "0.2.6" }
+        serverInfo: { name: "threenative-engine-mcp", version: "0.2.8" }
       });
     }
     if (request.method === "tools/list") {
@@ -532,7 +1179,7 @@ function handleLine(line, manifestFile) {
     }
     if (request.method === "tools/call") {
       if (!isRecord(request.params)) throw new Error("tools/call requires an object params value.");
-      return jsonRpcResult(request.id, handleToolCall(request.params, manifestFile));
+      return jsonRpcResult(request.id, await handleToolCall(request.params, manifestFile));
     }
     return jsonRpcError(request.id, -32601, `Method not found: ${request.method}`);
   } catch (error) {
@@ -541,16 +1188,45 @@ function handleLine(line, manifestFile) {
     return jsonRpcError(request.id, -32e3, message);
   }
 }
+async function runCli(argv, manifestFile = defaultManifestPath(), io = {
+  stderr: (text2) => void process.stderr.write(text2),
+  stdout: (text2) => void process.stdout.write(text2)
+}) {
+  const [name, json = "{}"] = argv;
+  try {
+    const result = await handleToolCall(
+      { arguments: JSON.parse(json), name },
+      manifestFile
+    );
+    io.stdout(`${result.content[0].text}
+`);
+    return 0;
+  } catch (error) {
+    io.stderr(`${name}: ${error instanceof Error ? error.message : String(error)}
+`);
+    return 1;
+  }
+}
 function runServer(manifestFile = defaultManifestPath()) {
+  const tool = process.argv[2];
+  if (tool?.startsWith("engine_") === true) {
+    void runCli(process.argv.slice(2), manifestFile).then((code) => {
+      process.exitCode = code;
+    });
+    return;
+  }
   loadCapabilityManifest(manifestFile);
   const input = createInterface({ input: process.stdin });
-  input.on("line", (line) => {
-    const response = handleLine(line, manifestFile);
-    if (response !== void 0) writeLine(response);
+  void loadReferenceIndex().catch((error) => process.stderr.write(`${String(error)}
+`));
+  input.on("line", (line2) => {
+    void handleLine(line2, manifestFile).then((response) => {
+      if (response !== void 0) writeLine(response);
+    });
   });
 }
 var entryPath = process.argv[1];
-if (entryPath !== void 0 && realpathSync(path.resolve(entryPath)) === realpathSync(fileURLToPath(import.meta.url))) {
+if (entryPath !== void 0 && realpathSync(path2.resolve(entryPath)) === realpathSync(fileURLToPath(import.meta.url))) {
   try {
     runServer();
   } catch (error) {
@@ -560,4 +1236,4 @@ if (entryPath !== void 0 && realpathSync(path.resolve(entryPath)) === realpathSy
   }
 }
 
-export { ENGINE_MCP_TOOL_NAMES, RELEVANCE_FLOOR, capabilityDetail, capabilityDetails, capabilitySituationTokens, defaultManifestPath, handleLine, loadCapabilityManifest, runServer, searchCapabilities, toolDefinitions };
+export { ENGINE_MCP_TOOL_NAMES, RELEVANCE_FLOOR, capabilityDetail, capabilityDetails, capabilitySituationTokens, defaultManifestPath, handleLine, loadCapabilityManifest, runCli, runServer, searchCapabilities, toolDefinitions };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "threenative-engine-mcp",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "license": "MIT",
   "description": "Offline MCP capability discovery for ThreeNative authoring agents.",
   "keywords": [