simt-dev 0.5.0 → 0.6.0

package/src/plugins.mjs

@@ -0,0 +1,164 @@
+// The package generator (plan 0003 R43): one command builds a Claude Code plugin, a
+// Gemini CLI extension, or a Cursor bundle, and all three are generated from the same
+// tables `agent-hooks install` writes into a repository. A package and a repository
+// install therefore cannot drift apart: the hooks document, the MCP registration and
+// (for Cursor) the kernel rules are all read from the one source, and only the entry
+// point differs — a package ships its own copy of the runtime rather than the binary on
+// PATH, so it installs into a clean profile that has never seen this tool.
+//
+// Each package is self-contained in the way its vendor requires:
+//
+//   claude   a directory with .claude-plugin/plugin.json, hooks/hooks.json and the
+//            runtime at its root; Claude names the root ${CLAUDE_PLUGIN_ROOT} and the
+//            project ${CLAUDE_PROJECT_DIR}.
+//   gemini   a directory with gemini-extension.json, hooks/hooks.json and the runtime at
+//            its root; the extension names its own directory ${extensionPath} and the
+//            workspace ${workspacePath}. The manifest's name must equal the directory's,
+//            so it is taken from the destination rather than fixed.
+//   cursor   a repository drop-in: .cursor/ with rules/kernel.mdc, hooks.json and
+//            mcp.json, and the runtime under .cursor/simt/. Cursor names the project
+//            ${CURSOR_PROJECT_DIR}.
+//
+// The skill registry is not shipped in any of them: it is workspace data (ADR-061), and
+// a package that carried one snapshot would ship a registry that is stale the moment it
+// leaves the machine it was built on. The command says so rather than pretending.
+
+import { cp, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+import { hookDocument } from './agenthooks/render.mjs';
+import { desiredRegion } from './projection/rules.mjs';
+import { PACKAGE_NAME, BIN_REL } from './name.mjs';
+
+/** The kinds `simt plugin` builds, in the order the help line names them. */
+export const PLUGIN_KINDS = ['claude', 'gemini', 'cursor'];
+
+/** Where the runtime copy lands inside a package, relative to the package root. */
+function runtimeDir(kind) {
+  return kind === 'cursor' ? join('.cursor', 'simt') : '.';
+}
+
+/** The entry point a package's config names: its own copy of the runtime, not PATH. */
+function entryPoint(kind) {
+  const bin = join(runtimeDir(kind), BIN_REL);
+  // The vendor's own variables must survive as literal text in the generated config, so
+  // they are escaped here: an unescaped ${...} would interpolate a JS binding that does
+  // not exist and ship the string "undefined" into the package.
+  if (kind === 'claude') return `node "\${CLAUDE_PLUGIN_ROOT}/${bin}"`;
+  if (kind === 'gemini') return `node "\${extensionPath}/${bin}"`;
+  // Cursor runs from the repository root, so a relative path is the honest one.
+  return `node ${bin}`;
+}
+
+/** The project root a package's hook resolves against, from the vendor's env var. */
+function rootFlag(kind) {
+  if (kind === 'claude') return ` --root "$CLAUDE_PROJECT_DIR"`;
+  if (kind === 'cursor') return ` --root "$CURSOR_PROJECT_DIR"`;
+  // Gemini documents no project-dir env var, but its base input carries cwd, which the
+  // adapter reads; passing a flag the vendor never sets would only expand to "".
+  return '';
+}
+
+/** Where the hooks document lands inside a package, relative to the package root. */
+function hooksPath(kind) {
+  return kind === 'cursor' ? join('.cursor', 'hooks.json') : join('hooks', 'hooks.json');
+}
+
+const json = (value) => `${JSON.stringify(value, null, 2)}\n`;
+
+/**
+ * The generated files of one package, relative to the package root: the manifest, the
+ * hooks document and the MCP registration. The runtime copy is planned separately because
+ * it is many files; this returns only the handful that are authored here.
+ */
+async function packageFiles(kind, { root = process.cwd(), out } = {}) {
+  const pkg = JSON.parse(await readFile(join(root, 'package.json'), 'utf8'));
+  const command = `${entryPoint(kind)} agent-hook pre-tool-use --harness ${kind}${rootFlag(kind)}`;
+  const files = [];
+
+  if (kind === 'claude') {
+    files.push({
+      path: join('.claude-plugin', 'plugin.json'),
+      text: json({
+        name: PACKAGE_NAME,
+        version: pkg.version,
+        description: pkg.description,
+        mcpServers: { [PACKAGE_NAME]: { command: 'node', args: [`\${CLAUDE_PLUGIN_ROOT}/${BIN_REL}`, 'mcp'] } },
+      }),
+    });
+  }
+
+  if (kind === 'gemini') {
+    // The vendor requires the manifest's name to equal the directory's, so it is the
+    // destination's basename rather than a fixed string: a package installed under any
+    // name is a valid extension, and the name travels with it.
+    files.push({
+      path: 'gemini-extension.json',
+      text: json({
+        name: basename(out),
+        version: pkg.version,
+        description: pkg.description,
+        mcpServers: { [PACKAGE_NAME]: { command: 'node', args: [`\${extensionPath}/${BIN_REL}`, 'mcp'], cwd: '${workspacePath}' } },
+      }),
+    });
+  }
+
+  if (kind === 'cursor') {
+    const kernel = await desiredRegion(root, { mode: 'kernel' });
+    files.push({
+      path: join('.cursor', 'rules', 'kernel.mdc'),
+      text: `---\ndescription: the kernel rules this repository enforces\nalwaysApply: true\n---\n${kernel.body}`,
+    });
+    files.push({
+      path: join('.cursor', 'mcp.json'),
+      text: json({ mcpServers: { [PACKAGE_NAME]: { command: 'node', args: [join('.cursor', 'simt', BIN_REL), 'mcp'] } } }),
+    });
+  }
+
+  files.push({ path: hooksPath(kind), text: hookDocument(kind, { command }) });
+  return files;
+}
+
+/**
+ * Build one package into `out`. With `apply` false it returns the plan and writes
+ * nothing; with true it copies the runtime and writes every generated file. The plan is
+ * the same in both cases, so a dry run and an apply agree on what will land.
+ */
+export async function buildPackage(kind, { root = process.cwd(), out, apply = false } = {}) {
+  if (!PLUGIN_KINDS.includes(kind)) {
+    throw new Error(`unknown package kind \`${kind}\`; one of: ${PLUGIN_KINDS.join(', ')}`);
+  }
+
+  const pkg = JSON.parse(await readFile(join(root, 'package.json'), 'utf8'));
+  const files = await packageFiles(kind, { root, out });
+  const notes = [
+    'the skill registry is workspace data (ADR-061) and is not shipped; run `simt skills index` in the profile to list what a workspace would offer',
+  ];
+
+  if (apply) {
+    const runtimeTarget = join(out, runtimeDir(kind));
+    await mkdir(runtimeTarget, { recursive: true });
+    // The runtime is the same set of paths npm publishes (the `files` field) plus
+    // package.json. Copying anything less ships a binary that answers the hook and then
+    // dies on the first MCP call: the server reads templates/ and rules/, which a
+    // bin+src-only copy leaves behind. The `files` field is the definition of "a working
+    // copy of this tool", so it is the set a package ships.
+    for (const part of pkg.files) {
+      await cp(join(root, part), join(runtimeTarget, part), { recursive: true });
+    }
+    await cp(join(root, 'package.json'), join(runtimeTarget, 'package.json'));
+    for (const f of files) {
+      const target = join(out, f.path);
+      await mkdir(join(target, '..'), { recursive: true });
+      await writeFile(target, f.text);
+    }
+  }
+
+  return {
+    kind,
+    out,
+    apply,
+    runtime: { target: runtimeDir(kind), parts: [...pkg.files, 'package.json'] },
+    files: files.map(({ text, ...rest }) => rest),
+    notes,
+  };
+}

package/src/projection/loaders.mjs

@@ -38,10 +38,12 @@
 //      required field rather than a comment. A reader that publishes no cap has
 //      `cap: null`, which means "checked, none found", not "not checked".
 //
-//   4. UNDOCUMENTED IS ITS OWN ANSWER. Copilot has no documented hooks file, and Gemini
-//      CLI's own configuration reference 404s today. Those cells are `null` with a
-//      `note` saying what was looked for. An empty string would read as "no hooks" and
-//      an invented path would read as a fact.
+//   4. UNDOCUMENTED IS ITS OWN ANSWER. Copilot has no documented hooks file. Those cells
+//      are `null` with a `note` saying what was looked for. An empty string would read
+//      as "no hooks" and an invented path would read as a fact. Gemini CLI spent a
+//      season here too — its configuration reference 404ed until it was re-checked on
+//      2026-10-26 and found live, which moved it from a thin row to a full one; the rule
+//      is unchanged, the example is.
 
 /**
  * One row per reader. Ordered by how widely the reader is deployed, so a truncated
@@ -152,7 +154,7 @@ export const LOADERS = [
       path: 'opencode.json',
       key: 'mcp.servers',
       verified:
-        'OpenCode v2 MCP servers docs: servers are named under mcp.servers; V2 does not place server names directly under mcp',
+        'OpenCode v2 MCP servers docs (read 2026-10-14): servers are named under mcp.servers; V2 does not place server names directly under mcp',
     },
     verified:
       'OpenCode v2 instructions, skills, plugins and MCP docs (opencode.ai/v2/docs, read 2026-10-14) — V2 loads AGENTS.md only, combining the global file with every project AGENTS.md from the workspace up to the project root; CLAUDE.md is not a fallback; the instructions array is accepted and not loaded; skills advertise name and description from .opencode/skills, .claude/skills and .agents/skills',
@@ -244,7 +246,7 @@ export const LOADERS = [
       path: '.mcp.json',
       key: null,
       verified:
-        'Claude Code MCP docs: project-scoped servers live in .mcp.json in the project root; local and user scope live in ~/.claude.json',
+        'Claude Code MCP docs (read 2026-10-14): project-scoped servers live in .mcp.json in the project root; local and user scope live in ~/.claude.json',
     },
     verified:
       'Claude Code memory docs (docs.claude.com/en/docs/claude-code/memory, read 2026-10-14) — CLAUDE.md and CLAUDE.local.md are concatenated from every directory above the working directory, subdirectory files load on demand, `@path` imports expand to four hops, a CLAUDE.md larger than 4 MiB is skipped, and AGENTS.md is read only when no CLAUDE.md exists above the working directory',
@@ -321,7 +323,7 @@ export const LOADERS = [
     mcp: {
       path: '.codex/config.toml',
       key: 'mcp_servers',
-      verified: 'Codex MCP docs: MCP configuration is stored in config.toml, ~/.codex/config.toml by default',
+      verified: 'Codex MCP docs (read 2026-10-14): MCP configuration is stored in config.toml, ~/.codex/config.toml by default',
     },
     verified:
       'Codex AGENTS.md documentation and configuration reference (developers.openai.com/codex, read 2026-10-14) — the project scope walks from the project root to the working directory, taking at most one file per directory in the order AGENTS.override.md, AGENTS.md, project_doc_fallback_filenames; the merge runs root to cwd and stops adding files at project_doc_max_bytes, 32 KiB by default',
@@ -387,7 +389,7 @@ export const LOADERS = [
     mcp: {
       path: '.cursor/mcp.json',
       key: null,
-      verified: 'Cursor MCP docs: "Create .cursor/mcp.json in your project"',
+      verified: 'Cursor MCP docs (read 2026-10-14): "Create .cursor/mcp.json in your project"',
     },
     verified:
       'Cursor rules documentation (cursor.com/docs/context/rules, read 2026-10-14) — only .cursor/rules/*.mdc is read, a plain .md there is ignored; alwaysApply decides whether a rule costs bytes at start; @file references in a rule body are not inlined; AGENTS.md is read in the project root and in subdirectories, combined with parents',
@@ -471,13 +473,85 @@ export const LOADERS = [
     mcp: {
       path: '.agents/mcp_config.json',
       key: null,
-      verified: 'Antigravity MCP docs: "Configured in your workspace under .agents/mcp_config.json"',
+      verified:
+        'Antigravity MCP docs (read 2026-10-14): "Configured in your workspace under .agents/mcp_config.json"',
     },
     verified:
       'Google Antigravity rules documentation (antigravity.google/docs/rules/, read 2026-10-14) — rules are cumulative across global, workspace and directory scope; .agents/rules/*.md requires frontmatter with trigger, and an invalid block silently discards the rule; the directory is scanned flat and nested files are ignored unless registered in .agents/rules.json; each rule file is truncated at 24,000 bytes after includes are expanded, and global plus always_on rules share a 20,000-token budget past which the largest are demoted to pointers',
     note:
       'The flat scan is the fact that made the meter wrong before this table existed: a recursive walk of .agents/rules/ counts bytes for files Antigravity never reads.',
   },
+  {
+    id: 'gemini',
+    label: 'Gemini CLI',
+    readers: 'Gemini CLI (google-gemini/gemini-cli)',
+    // No projection surface of its own: the gemini-md pointer already hands the reader
+    // the standard region, and `context.fileName` is the only mechanism by which this
+    // reader would load AGENTS.md at all — renaming the context file is the vendor's
+    // documented way to point at it. A separate rules row would be a second way to hand
+    // one reader the same rules (the ruling recorded on the surfaces `gemini-md`
+    // pointer). This FACTS row exists because the reader's own facts differ from every
+    // other row's: no published cap, depth-5 imports, and the one MCP registration left
+    // that a project file can carry.
+    surface: null,
+    start: [
+      {
+        scope: 'project',
+        path: 'GEMINI.md',
+        tree: 'chain',
+        atStart: true,
+        why: 'Gemini CLI context docs (docs/cli/gemini-md/): GEMINI.md is collected from the working directory upward through parent directories until the first directory holding a boundary marker (.git by default) or home',
+      },
+      {
+        scope: 'user',
+        path: '~/.gemini/GEMINI.md',
+        tree: 'single',
+        atStart: true,
+        why: 'Gemini CLI context docs: the user-global ~/.gemini/GEMINI.md opens the concatenation, before any project file',
+      },
+    ],
+    alsoReads: [
+      {
+        what: 'the context file under another name — settings.json context.fileName, a string or an array',
+        atStart: true,
+        why: 'Gemini CLI configuration docs: context.fileName renames the context file (a string or an array), so an installation listing AGENTS.md there reads AGENTS.md as its GEMINI.md',
+      },
+      {
+        what: 'GEMINI.md (or the renamed context file) in subdirectories below the working directory',
+        atStart: false,
+        why: 'Gemini CLI context docs: directories a tool touches are scanned for a context file up to a trusted root, bounded by context.discoveryMaxDirs (200) - not at session start',
+      },
+    ],
+    order:
+      'user-global ~/.gemini/GEMINI.md first, then the project chain general to specific - project-root side first (upward traversal stops at the first directory holding a boundary marker, .git by default) down through each directory to the working directory - then just-in-time files a tool touch discovered; the whole result is one concatenation with origin separators',
+    cap: null,
+    capNote: 'no byte cap is published for the merged Gemini CLI context (checked 2026-10-26)',
+    imports: {
+      syntax: '@path',
+      depth: 5,
+      why: 'Gemini CLI context docs: @path imports resolve relative or absolute to a maximum depth of 5, with cycles prevented by skipping files already on the stack',
+    },
+    nested:
+      'general to specific, all loaded — unlike Codex, every context file on the walk contributes; a nearer file cannot hide a parent one, it just concatenates after it; subdirectory files wait for a tool touch',
+    skills: [],
+    skillsNote:
+      'no project skill directory is documented for Gemini CLI; extensions are the distribution mechanism, and they are tooling not context',
+    hooks: {
+      path: '.gemini/settings.json',
+      verified:
+        'Gemini CLI hooks reference (geminicli.com/docs/hooks/reference/, read 2026-10-26): a project .gemini/settings.json carries a top-level hooks object whose events are arrays of {matcher, hooks:[{type:"command",command,timeout? (milliseconds)}]} — the same shape Claude and Codex use; BeforeTool denies with {decision:"deny",reason}, BeforeAgent and AfterTool inject via hookSpecificOutput.additionalContext',
+    },
+    mcp: {
+      path: '.gemini/settings.json',
+      key: 'mcpServers',
+      verified:
+        'Gemini CLI configuration docs (docs/reference/configuration/, read 2026-10-26): a project .gemini/settings.json (a user ~/.gemini/settings.json merged behind it, objects merged key by key) carries a top-level mcpServers object whose entries name a command, a url or an httpUrl',
+    },
+    verified:
+      'Gemini CLI context and configuration docs (geminicli.com/docs/cli/gemini-md/ and docs/reference/configuration/, read 2026-10-26) — settings live at project .gemini/settings.json and user ~/.gemini/settings.json, merged for objects; the context is user ~/.gemini/GEMINI.md plus the context file (GEMINI.md unless context.fileName renames it, an array is allowed) from the working directory upward through parents to the first .git or home, with @path imports to depth 5; server registration is the mcpServers object in those same settings files; no byte cap is published',
+    note:
+      'The configuration reference this table once recorded as 404ing is live again as of 2026-10-26, which is why the row is full instead of thin. What still shapes a byte count is the pair of absences the docs confirm rather than deny: no cap, and no promise that AGENTS.md is read at all — context.fileName decides that, and it may name anything.',
+  },
   {
     id: 'copilot',
     label: 'GitHub Copilot',
@@ -533,7 +607,7 @@ export const LOADERS = [
       path: '.vscode/mcp.json',
       key: null,
       verified:
-        'GitHub Copilot MCP docs: the VS Code extension reads .vscode/mcp.json; Copilot CLI reads .mcp.json, .github/mcp.json or ~/.copilot/mcp-config.json; a repository-level configuration entered on github.com is not a file at all',
+        'GitHub Copilot MCP docs (read 2026-10-14): the VS Code extension reads .vscode/mcp.json; Copilot CLI reads .mcp.json, .github/mcp.json or ~/.copilot/mcp-config.json; a repository-level configuration entered on github.com is not a file at all',
     },
     verified:
       'GitHub Copilot documentation (docs.github.com/en/copilot, read 2026-10-14) — repository-wide instructions live at .github/copilot-instructions.md; path-specific instructions live at .github/instructions/**/NAME.instructions.md with applyTo globs and an optional excludeAgent; agent instructions are one or more AGENTS.md anywhere in the repository, nearest wins, or a single root CLAUDE.md or GEMINI.md; no byte cap is published',

package/src/projection/manifest.mjs

@@ -12,7 +12,7 @@
 //            Inventing a number here would be worse than declaring none.
 //
 // Every default this module produces is explained by the ADR that requires it. The
-// rationale is not duplicated into the JSON (data must stay data); `simt-dev init`
+// rationale is not duplicated into the JSON (data must stay data); `simt init`
 // prints the reason for each value it writes.
 
 import { readFile, rename, writeFile } from 'node:fs/promises';
@@ -430,7 +430,7 @@ export function buildManifest({ root, stack = [], sha, version, existing = null,
     gates: gatesFinal,
     localSkills: existing?.localSkills ?? [],
     // ADR-013: profile ids the repo wants, whether they ship centrally or live
-    // in `.simt-dev/profiles/`. Detection already selects the right profiles; this
+    // in `.simt/profiles/`. Detection already selects the right profiles; this
     // is the declaration a reviewer reads to see the repo's intent stated rather
     // than inferred.
     profiles: existing?.profiles ?? [],
@@ -482,8 +482,8 @@ export function buildManifest({ root, stack = [], sha, version, existing = null,
     // simtDevSha is the digest of the rule bytes this projection was rendered from;
     // version is the simt-dev release that produced it. The gate compares the running
     // binary to version and refuses on a mismatch, which is how a repository without
-    // npm (a global install, pinned only by this field) is held to the release it
-    // adopted. See src/package-version.mjs.
+    // npm (the release binary in `.simt/bin`, pinned only by this field) is held to
+    // the release it adopted. See src/package-version.mjs.
     projection: { simtDevSha: sha ?? null, version: version ?? null },
   };
   return withRepoKeys(existing, owned);

package/src/projection/project.mjs

@@ -11,7 +11,7 @@
 // which are interchangeable in a profile (ADR-013) - plus one fallback profile
 // so a JS/TS repo is never left with core rules and nothing else.
 //
-// Profiles may live in the repo, not only here. `.simt-dev/profiles/*.md` uses
+// Profiles may live in the repo, not only here. `.simt/profiles/*.md` uses
 // the same frontmatter contract as `rules/stacks/*.md` and is selected by the
 // same matcher, so supporting an ecosystem nobody here has heard of requires no
 // code change and no release.
@@ -412,7 +412,7 @@ export async function checkTargets(root, flags = {}) {
   //
   // Reported as `orphaned`, never `drift`. ADR-021 ruling 6: `sync` does not delete a
   // file it once generated, so there is nothing for the reader to repair and a
-  // `run: simt-dev sync --yes` remedy would be a lie. Removal is a human decision.
+  // `run: simt sync --yes` remedy would be a lie. Removal is a human decision.
   findings.push(...(await orphanedRuleFiles(root, resolved)));
 
   // Pointers are checked last, and whether one blocks depends on who reads it.
@@ -604,7 +604,7 @@ async function regionOpts(root) {
  * A reader that stops at a byte offset never sees a region that ends past it.
  * The finding names the reader, because "the file is long" does not say who stops.
  */
-// Exported for the context meter (`simt-dev tokens`), which answers the same question
+// Exported for the context meter (`simt tokens`), which answers the same question
 // about a region rather than about a diff. It reads the structured fields instead of
 // re-deriving the limit, because a second implementation of "which reader stops, and
 // where" is a second thing to keep right - and a second thing to quote in a message.

package/src/projection/rules.mjs

@@ -15,7 +15,7 @@
 // which are interchangeable in a profile (ADR-013) - plus one fallback profile so
 // a JS/TS repo is never left with core rules and nothing else.
 //
-// Profiles may live in the repo, not only here. `.simt-dev/profiles/*.md` uses the
+// Profiles may live in the repo, not only here. `.simt/profiles/*.md` uses the
 // same frontmatter contract as `rules/stacks/*.md` and is selected by the same
 // matcher, so supporting an ecosystem nobody here has heard of requires no code
 // change and no release.
@@ -46,6 +46,17 @@ const HERE = dirname(fileURLToPath(import.meta.url));
 export const ROOT = resolve(HERE, '..', '..');
 const RULES_DIR = join(ROOT, 'rules');
 
+// The orientation pointer that follows the command card in every projected region.
+//
+// The agent playbook — `brief` on a new task, `why` before an edit — lives in this
+// package's README and never reaches the agent working in an adopted repository: the
+// projection carries the rules, not the tool that serves them. Without this line the
+// agent has no way to know `simt brief` exists, and "answers over exploration" has no
+// delivery path in the one file every harness reads. Static on purpose: a byte that
+// varied per repository would break the stable prefix this region exists to protect.
+export const ORIENTATION_POINTER =
+  `New task? Run \`${CLI} brief "<task>"\` before exploring; before editing a file, \`${CLI} why <file>\`.`;
+
 /**
  * The identity recorded in generated regions and in the manifest pin.
  *
@@ -131,7 +142,7 @@ async function walk(dir, prefix = '') {
 }
 
 /** Repo-local profile directory, relative to a repo root (ADR-013 section 2). */
-export const LOCAL_PROFILE_DIR = '.simt-dev/profiles';
+export const LOCAL_PROFILE_DIR = '.simt/profiles';
 
 /**
  * Which origin outranks which when two profiles claim one `simt-id`.
@@ -501,7 +512,12 @@ export async function desiredRegion(root, flags) {
   // symmetric: packing a line that should have been deferred spends the budget the mode
   // exists to save, while deferring a line that should have been packed costs a reader
   // one `rules show`. The mode is a promise about bytes, so it is the bytes that win.
-  const mode = await projectionMode(root);
+  // An explicit `mode` flag overrides the declared one. The caller is the MCP
+  // `simt://kernel` resource, which by name promises the kernel's bytes for any
+  // repository: the declared mode governs what `sync` writes to disk, not what a read
+  // path may look at, so the read renders in the mode the URI names instead of
+  // re-reading a manifest it must not obey (ADR-002).
+  const mode = typeof flags?.mode === 'string' ? flags.mode : await projectionMode(root);
   const packed = [];
   const deferred = [];
   for (const r of inRegion) {
@@ -683,6 +699,10 @@ export async function desiredRegion(root, flags) {
     const repoRules = kept.filter((r) => !toolRule(r)).sort((a, b) => String(a.id).localeCompare(String(b.id)));
     let text = render(stable);
     if (card.text) text += `${text === '' ? '' : '\n\n'}${card.text}`;
+    // The pointer follows the card: the card says what this repository runs, and the
+    // pointer says how the tool serves a task. Adjacent, they read as one block of
+    // repo-facing advice instead of two facts the reader has to connect.
+    text += `${text === '' ? '' : '\n\n'}${ORIENTATION_POINTER}`;
     const repoText = render(repoRules);
     if (repoText) text += `\n\n${repoText}`;
     const sources = [...stable, ...repoRules].map((r) => r.source);
@@ -962,7 +982,7 @@ function scopedPaths(rule, resolved) {
 
 /**
  * Read every rule file once, with its frontmatter parsed, plus any repo-local
- * profile under `.simt-dev/profiles/`.
+ * profile under `.simt/profiles/`.
  *
  * A rule without a `simt-id` is a defect, not a default: ids are what `rules why`
  * and the generated region's source list refer to.

package/src/projection/surfaces.mjs

@@ -30,7 +30,7 @@
 //      `.agents/rules/` or `.github/instructions/`, and a symlink into a
 //      directory whose reader's symlink behaviour is unverified is a guess with a
 //      mode bit. So those get machine-written copies — and because every byte is
-//      derived from `rules/mdc/*.mdc` and `simt-dev check` compares each against
+//      derived from `rules/mdc/*.mdc` and `simt check` compares each against
 //      that same derivation, they are not duplication, they are a build output.
 //      The difference from that duplicate is that nobody can hand-edit one
 //      and have it survive a sync.
@@ -387,12 +387,30 @@ export const SURFACE_IDS = SURFACES.map((s) => s.id);
  * this repository", never "this harness is installed" and never "its rules are not
  * being loaded".
  *
+ * The exception that proves the rule is `.gemini`: R42 read Gemini CLI's
+ * configuration docs, so its entry carries readsAgentsMd and a `verified` the same way
+ * a surface row does. Everyone else stays a bare name until somebody reads their
+ * vendor pages — the bar for facts here is a document, not an ML search snippet, and
+ * that bar is what keeps this list honest as harnesses come and go.
+ *
  * `.github` is absent even though the Copilot row carries it: `.github` holds workflows
  * and issues, so its presence says nothing about whether Copilot is used, and the
  * Copilot row's own detection is not something this command is for.
  */
 export const CANDIDATE_DIRS = [
-  { dir: '.gemini', harness: 'Gemini CLI' },
+  {
+    // The one candidate with verified facts (R42): Gemini CLI's configuration reference
+    // was live and read on 2026-10-26, so presence now carries provenance instead of
+    // the default "a reader may be configured here". AGENTS.md is loaded only when
+    // settings.json `context.fileName` names it - the context file is GEMINI.md
+    // otherwise - so the fact is "some", which here means one reader under
+    // configuration, and the note says exactly that.
+    dir: '.gemini',
+    harness: 'Gemini CLI',
+    readsAgentsMd: 'some',
+    readsAgentsMdNote: 'AGENTS.md is loaded only when settings.json context.fileName names it; the context file is GEMINI.md otherwise',
+    verified: 'Gemini CLI configuration docs (geminicli.com/docs/reference/configuration/, read 2026-10-26) — a .gemini directory holds the project settings.json, and the reader loads GEMINI.md unless context.fileName renames it',
+  },
   { dir: '.windsurf', harness: 'Windsurf' },
   { dir: '.zed', harness: 'Zed' },
   { dir: '.kiro', harness: 'Kiro' },

package/src/review/critic.mjs

@@ -5,10 +5,10 @@
 // consumer: it sends the brief to the endpoint named in the manifest (R37) and asks
 // for an ADR-008 verdict skeleton, then verifies the verdict vocabulary and every
 // cited id against that brief before the reply becomes a proposal under
-// `.simt-dev/reviews/`. A proposal a human never reads is a dead file, which is the
+// `.simt/reviews/`. A proposal a human never reads is a dead file, which is the
 // intended failure mode (ADR-075, ADR-090).
 //
-// Nothing here writes outside `.simt-dev/reviews/`, and nothing here edits a source
+// Nothing here writes outside `.simt/reviews/`, and nothing here edits a source
 // file — the model is a critic, not an author. The verdict is advisory by
 // construction; no gate reads it. The row's own promotion rule names the test:
 // precision at least 0.8 on a labelled set of historical diffs. Until
@@ -32,9 +32,9 @@ import { digestOf, promptHash, proposalFrontmatter } from '../distill/engine.mjs
 
 const exec = promisify(execFile);
 
-// Locked on-disk beneath `.simt-dev`, like `.simt-dev/distilled` (R38) — a cache of
+// Locked on-disk beneath `.simt`, like `.simt/distilled` (R38) — a cache of
 // proposals keyed by content digest, never projected and never committed.
-const REVIEW_DIR = '.simt-dev/reviews';
+const REVIEW_DIR = '.simt/reviews';
 const ENGINE_REVIEW_LOCAL = 'review-local';
 
 /** The diff brief's byte cap; `--budget` overrides it, `0` means unlimited. */

package/src/toolwords.mjs

@@ -21,21 +21,24 @@ import { CHECK_MARKER } from './kernel/checks.mjs';
 import { VARIANTS_MARKER } from './kernel/variants.mjs';
 import { LESSON_KEYS } from './memory/lessons.mjs';
 import { DECISION_KEYS } from './memory/decide.mjs';
+import { PROMPT_WORDS } from './mcp/prompts.mjs';
 
 /**
  * `simt-` names that belong to this tool and never to a repository.
  *
- * The last three are not frontmatter: they are names this tool writes into files it
- * adopts a repository into — the package, the gate file it puts in `.github`, and the
- * hooks directory it points `core.hooksPath` at. `simt-dev` itself is here for the same
- * reason the estate pattern exempts it, and stating it once here is what stops the two
- * readers from disagreeing about the tool's own name.
+ * The three markers and the four suffixed names are not frontmatter: they are names this
+ * tool writes into files it adopts a repository into — the package, the gate file it puts
+ * in `.github`, the hooks directory it points `core.hooksPath` at, and the two prompts it
+ * serves over MCP, derived from the module that owns them. `simt-dev` itself is here for
+ * the same reason the estate pattern exempts it, and stating it once here is what stops
+ * the two readers from disagreeing about the tool's own name.
  */
 export const TOOL_WORDS = new Set([
   ...KNOWN_KEYS,
   ...PROFILE_KEYS,
   ...LESSON_KEYS,
   ...DECISION_KEYS,
+  ...PROMPT_WORDS,
   INFERABLE_MARKER,
   CHECK_MARKER,
   VARIANTS_MARKER,

package/src/tsconfig.mjs

@@ -16,8 +16,8 @@
 //      tool's output rather than the file's.
 //
 // The whole file is owned by `init` alone. It is not in `src/ci/` and not in
-// `src/projection/baselines.mjs` because it is neither a `.github` file that `simt-dev ci`
-// refreshes nor a marker region: `simt-dev check` reports its absence and never its contents.
+// `src/projection/baselines.mjs` because it is neither a `.github` file that `simt ci`
+// refreshes nor a marker region: `simt check` reports its absence and never its contents.
 
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
@@ -174,7 +174,7 @@ export function readJsonc(text) {
  *
  * There is no `refresh`. ADR-026 gave simt-dev's own `.github` files a refresh path because
  * this repository is the template's only author; a base file has the same argument, and it
- * is deliberately not extended to it. `simt-dev check` in this repository reports the
+ * is deliberately not extended to it. `simt check` in this repository reports the
  * baseline files as unmanaged by design, so a refresh path here would be a way to make this
  * repository's own gate green by rewriting the file it is judging — which is the same
  * mistake as a gate that edits its own expectations.

package/src/upgrade/plan.mjs

@@ -29,7 +29,7 @@ export function planUpgrade({ name, path, manifest, manifestExists, manifestErro
   const primary = list[0] ?? null;
   const base = { name, path, sha, pinnedSha: manifest?.projection?.simtDevSha ?? null };
 
-  // A repo that never adopted is not behind; it is absent. `simt-dev init` is the command
+  // A repo that never adopted is not behind; it is absent. `simt init` is the command
   // for it, and calling this a failure would make the exit code describe the estate's
   // migration progress rather than this run's correctness.
   if (!manifestExists) {