@cassiomc1/forgeloop 1.10.2 → 1.11.0

package/benchmarks/repository-index/run-persistent-transport.mjs

@@ -0,0 +1,169 @@
+import { appendFile, cp, mkdtemp, readFile, rm } from "node:fs/promises";
+import { execFile } from "node:child_process";
+import { performance } from "node:perf_hooks";
+import { promisify } from "node:util";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { searchRepository } from "../../src/repository-index/search.js";
+import { createTgrepBinaryHandle, runTgrep } from "../../src/repository-index/process.js";
+import { stopRepositoryIndexServer } from "../../src/repository-index/server.js";
+import { getCanonicalRepositorySearchArgs, appendSearchFilters } from "../../src/repository-index/args.js";
+import { getTgrepIndexPath } from "../../src/repository-index/paths.js";
+import { searchViaPersistentTransport, shutdownPersistentSearchHost } from "../../src/persistent-transport/client.js";
+
+const execFileAsync = promisify(execFile);
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
+const fixtureRoot = path.join(packageRoot, "tests", "fixtures", "repository-index", "sample-repo");
+const cliPath = path.join(packageRoot, "src", "cli.js");
+const binary = process.env.FORGELOOP_TGREP_BINARY;
+const iterations = Number.parseInt(process.env.FORGELOOP_BENCHMARK_ITERATIONS ?? "100", 10);
+
+if (!binary || !path.isAbsolute(binary)) throw new Error("Set FORGELOOP_TGREP_BINARY to the absolute path of the pinned native tgrep binary");
+if (!Number.isSafeInteger(iterations) || iterations < 1 || iterations > 1_000) throw new Error("FORGELOOP_BENCHMARK_ITERATIONS must be an integer from 1 to 1000");
+const binaryHandle = createTgrepBinaryHandle(binary);
+
+const fixture = await mkdtemp(path.join(os.tmpdir(), "forgeloop-persistent-transport-benchmark-"));
+const persistentHome = await mkdtemp(path.join(os.tmpdir(), "forgeloop-persistent-transport-home-"));
+const cliHome = await mkdtemp(path.join(os.tmpdir(), "forgeloop-persistent-transport-cli-home-"));
+const options = {
+  packageRoot,
+  binaryPath: binary,
+  startupTimeoutMs: 30_000,
+  commandTimeoutMs: 60_000,
+  requestTimeoutMs: 60_000,
+};
+const query = { pattern: "FORGELOOP_BENCHMARK_ABSENT", fixedStrings: true };
+const agentQueries = [
+  { pattern: "repositoryFingerprint", fixedStrings: true },
+  { pattern: "E_[A-Z_]+" },
+  { pattern: "executionreceipt", ignoreCase: true },
+  { pattern: "receipt", wordRegexp: true },
+  { pattern: "export", types: ["js"] },
+  { pattern: "const", fixedStrings: true },
+  { pattern: "FORGELOOP_BENCHMARK_ABSENT", fixedStrings: true },
+  { pattern: "searchRepository", fixedStrings: true },
+  { pattern: "forgeloop", ignoreCase: true },
+  { pattern: "THREAT_MODEL", fixedStrings: true },
+];
+
+function summarize(durations) {
+  const sorted = [...durations].sort((a, b) => a - b);
+  const percentile = (fraction) => sorted[Math.min(sorted.length - 1, Math.ceil(sorted.length * fraction) - 1)];
+  const totalMs = durations.reduce((sum, value) => sum + value, 0);
+  return {
+    iterations: durations.length,
+    totalMs: Math.round(totalMs),
+    minMs: Math.round(sorted[0]),
+    maxMs: Math.round(sorted.at(-1)),
+    meanMs: Math.round(totalMs / durations.length),
+    medianMs: Math.round(percentile(0.5)),
+    p95Ms: Math.round(percentile(0.95)),
+  };
+}
+
+async function repeated(callback) {
+  const durations = [];
+  for (let index = 0; index < iterations; index += 1) {
+    const startedAt = performance.now();
+    await callback();
+    durations.push(performance.now() - startedAt);
+  }
+  return summarize(durations);
+}
+
+async function rawTgrep(searchQuery = query) {
+  const args = [...getCanonicalRepositorySearchArgs({ indexPath: getTgrepIndexPath(fixture), pattern: searchQuery.pattern, options: searchQuery })];
+  appendSearchFilters(args, searchQuery);
+  args.push(fixture);
+  const result = await runTgrep({ binary: binaryHandle, repoRoot: fixture, args, timeoutMs: options.commandTimeoutMs, maxOutputBytes: 4 * 1024 * 1024 });
+  if (![0, 1].includes(result.exitCode)) throw new Error(`raw tgrep failed: ${result.stderr}`);
+}
+
+async function ripgrep(searchQuery = query) {
+  try {
+    await execFileAsync("rg", ["--fixed-strings", "--color", "never", "--glob", "!.forgeloop/repository-index/**", searchQuery.pattern, fixture], { maxBuffer: 4 * 1024 * 1024 });
+  } catch (error) {
+    if (error.code === "ENOENT") return false;
+    if (error.code !== 1) throw error;
+  }
+  return true;
+}
+
+async function cliSearch(homeDirectory, searchQuery = query) {
+  const fixed = searchQuery.fixedStrings ? ["--fixed-strings"] : [];
+  const ignoreCase = searchQuery.ignoreCase ? ["--ignore-case"] : [];
+  const word = searchQuery.wordRegexp ? ["--word-regexp"] : [];
+  const type = searchQuery.types?.flatMap((value) => ["--type", value]) ?? [];
+  const result = await execFileAsync(process.execPath, [cliPath, "search", searchQuery.pattern, ...fixed, ...ignoreCase, ...word, ...type, "--json", "--path", fixture], {
+    cwd: packageRoot,
+    env: { ...process.env, HOME: homeDirectory, USERPROFILE: homeDirectory, FORGELOOP_TGREP_BINARY: binary },
+    timeout: 120_000,
+    maxBuffer: 16 * 1024 * 1024,
+  });
+  return JSON.parse(result.stdout);
+}
+
+async function measureAgentWorkload(callback) {
+  const startedAt = performance.now();
+  const results = [];
+  for (const searchQuery of agentQueries) results.push(await callback(searchQuery));
+  const totalMs = performance.now() - startedAt;
+  return {
+    queries: agentQueries.length,
+    totalMs: Math.round(totalMs),
+    meanMs: Math.round(totalMs / agentQueries.length),
+    matchCounts: results.map((result) => result?.matches?.length ?? null),
+  };
+}
+
+try {
+  await cp(fixtureRoot, fixture, { recursive: true });
+  await execFileAsync("git", ["init", "--quiet", fixture]);
+  await execFileAsync("git", ["-C", fixture, "add", "."]);
+  await searchRepository(fixture, { ...options, ...query, homeDirectory: persistentHome });
+  const persistentColdStartedAt = performance.now();
+  await searchViaPersistentTransport(fixture, query, { ...options, homeDirectory: persistentHome, env: { FORGELOOP_TGREP_BINARY: binary } });
+  const persistentColdMs = performance.now() - persistentColdStartedAt;
+  const persistentWarm = await repeated(() => searchViaPersistentTransport(fixture, query, { ...options, homeDirectory: persistentHome, env: { FORGELOOP_TGREP_BINARY: binary } }));
+  const apiWarm = await repeated(() => searchRepository(fixture, { ...options, ...query, homeDirectory: persistentHome }));
+  const raw = await repeated(rawTgrep);
+  const rgAvailable = await ripgrep();
+  const rgWarm = rgAvailable ? await repeated(ripgrep) : null;
+  const cliColdStartedAt = performance.now();
+  await cliSearch(cliHome);
+  const cliColdMs = performance.now() - cliColdStartedAt;
+  const cliWarm = await repeated(() => cliSearch(cliHome));
+  const agentWorkload = {
+    api: await measureAgentWorkload((searchQuery) => searchRepository(fixture, { ...options, ...searchQuery, homeDirectory: persistentHome })),
+    persistentTransport: await measureAgentWorkload((searchQuery) => searchViaPersistentTransport(fixture, searchQuery, { ...options, homeDirectory: persistentHome, env: { FORGELOOP_TGREP_BINARY: binary } })),
+    cli: await measureAgentWorkload((searchQuery) => cliSearch(cliHome, searchQuery)),
+  };
+  const nodeStartupStartedAt = performance.now();
+  await execFileAsync(process.execPath, ["-e", "void 0"], { cwd: packageRoot });
+  const nodeStartupMs = performance.now() - nodeStartupStartedAt;
+  await appendFile(path.join(fixture, "src", "benchmark.js"), "\nexport const transportBenchmarkMutation = true;\n");
+  await searchViaPersistentTransport(fixture, { pattern: "transportBenchmarkMutation", fixedStrings: true }, { ...options, homeDirectory: persistentHome, env: { FORGELOOP_TGREP_BINARY: binary } });
+  console.log(JSON.stringify({
+    schemaVersion: 1,
+    repository: "repository-index-sample-fixture",
+    platform: process.platform,
+    arch: process.arch,
+    nodeVersion: process.version,
+    tgrepVersion: "1.0.3",
+    iterations,
+    cold: { persistentTransportMs: Math.round(persistentColdMs), cliMs: Math.round(cliColdMs) },
+    warm: { api: apiWarm, persistentTransport: persistentWarm, cli: cliWarm, rawTgrep: raw, ripgrep: rgWarm },
+    agentWorkload,
+    criticalPath: { nodeProcessStartupMs: Math.round(nodeStartupMs), note: "CLI timings include Node process startup and argument parsing." },
+    mutation: "verified through persistent transport",
+  }, null, 2));
+} finally {
+  await shutdownPersistentSearchHost({ homeDirectory: persistentHome, timeoutMs: 2_000 }).catch(() => {});
+  await shutdownPersistentSearchHost({ homeDirectory: cliHome, timeoutMs: 2_000 }).catch(() => {});
+  await stopRepositoryIndexServer(fixture, { ...options, homeDirectory: persistentHome }).catch(() => {});
+  await rm(fixture, { recursive: true, force: true });
+  await rm(persistentHome, { recursive: true, force: true });
+  await rm(cliHome, { recursive: true, force: true });
+}

package/completions/_forgeloop

@@ -1,7 +1,7 @@
 #compdef forgeloop
 # Generated by scripts/generate-shell-completions.mjs. Do not edit.
 _arguments \
-  '1:command:(action-authorize action-propose action-reconcile action-record action-show action-verify activate advance approval-request approval-resolve attestation-create attestation-status attestation-verify attestation-verify-range audit baseline bundle clear-continuity clear-state complete continuity doctor efficiency eval handoff-accept handoff-create handoff-list handoff-show history init inspect metrics migrate-protocol next policy policy-diff policy-discover policy-status preflight prepare-completion profile-interview progress protocol-info quality-baseline quality-status quality-verify reconcile-closure reconcile-continuity record-check record-continuity record-decision-criterion record-diagnosis record-hypothesis-disposition record-intervention record-terminal-result reflect report responsibility-set responsibility-status route rule-verify run-action run-check status task-create task-list task-lock-status task-migrate task-recover task-repair-legacy-recovery task-resume task-scope task-show task-unlock trace update usage-record validate-protocol validate-receipt validate-state verify-scope workspace-bind workspace-status)' \
+  '1:command:(action-authorize action-propose action-reconcile action-record action-show action-verify activate advance approval-request approval-resolve attestation-create attestation-status attestation-verify attestation-verify-range audit baseline bundle clear-continuity clear-state complete continuity doctor efficiency eval handoff-accept handoff-create handoff-list handoff-show history index-rebuild index-setup index-start index-status index-stop init inspect metrics migrate-protocol next policy policy-diff policy-discover policy-status preflight prepare-completion profile-interview progress protocol-info quality-baseline quality-status quality-verify reconcile-closure reconcile-continuity record-check record-continuity record-decision-criterion record-diagnosis record-hypothesis-disposition record-intervention record-terminal-result reflect report responsibility-set responsibility-status route rule-verify run-action run-check search status task-create task-list task-lock-status task-migrate task-recover task-repair-legacy-recovery task-resume task-scope task-show task-unlock trace update usage-record validate-protocol validate-receipt validate-state verify-scope workspace-bind workspace-status)' \
   '*::options:->options'
 case $words[2] in
   action-authorize) _arguments '--action[durable action ID]' '--approval[current fingerprint-bound approval]' '--help[show this help]' '--json[emit structured output as JSON]' '--path[target project directory (default: current directory)]' '--task[task ID to operate on (when omitted, resolved from context or single active task)]' '--version[show the installed package version]' ;;
@@ -33,6 +33,11 @@ case $words[2] in
   handoff-list) _arguments '--help[show this help]' '--json[emit handoff list as JSON]' '--path[target project directory (default: current directory)]' '--task[task ID to operate on (when omitted, resolved from context or single active task)]' '--version[show the installed package version]' ;;
   handoff-show) _arguments '--help[show this help]' '--id[handoff identifier]' '--json[emit handoff as JSON]' '--path[target project directory (default: current directory)]' '--task[task ID to operate on (when omitted, resolved from context or single active task)]' '--version[show the installed package version]' ;;
   history) _arguments '--checks[show only verification events]' '--compact[one line per event]' '--failures[show only failed/blocked verification events]' '--help[show this help]' '--json[emit structured history output as JSON]' '--limit[show only the last N events after filtering]' '--path[target project directory (default: current directory)]' '--phase[comma-separated lifecycle phases to include]' '--since[include events at or after this timestamp]' '--task[task ID to operate on (when omitted, resolved from context or single active task)]' '--type[comma-separated event types or categories to include]' '--until[include events at or before this timestamp]' '--verbose[show full event data]' '--version[show the installed package version]' ;;
+  index-rebuild) _arguments '--asset[use a preloaded pinned tgrep archive instead of downloading]' '--help[show this help]' '--json[emit repository-index rebuild as JSON]' '--path[target project directory (default: current directory)]' '--version[show the installed package version]' ;;
+  index-setup) _arguments '--asset[use a preloaded pinned tgrep archive instead of downloading]' '--force[rebuild the repository index even when metadata is current]' '--help[show this help]' '--json[emit repository-index setup as JSON]' '--path[target project directory (default: current directory)]' '--version[show the installed package version]' ;;
+  index-start) _arguments '--help[show this help]' '--json[emit repository-index start as JSON]' '--path[target project directory (default: current directory)]' '--version[show the installed package version]' ;;
+  index-status) _arguments '--help[show this help]' '--json[emit repository-index health as JSON]' '--path[target project directory (default: current directory)]' '--version[show the installed package version]' ;;
+  index-stop) _arguments '--help[show this help]' '--json[emit repository-index stop as JSON]' '--path[target project directory (default: current directory)]' '--version[show the installed package version]' ;;
   init) _arguments '--dry-run[perform deterministic init planning and conflict detection without writing]' '--help[show this help]' '--path[target project directory (default: current directory)]' '--version[show the installed package version]' ;;
   inspect) _arguments '--contract-file[current JSON contract used for freshness comparison]' '--help[show this help]' '--json[emit structured output as JSON]' '--path[target project directory (default: current directory)]' '--task[task ID to operate on (when omitted, resolved from context or single active task)]' '--version[show the installed package version]' ;;
   metrics) _arguments '--help[show this help]' '--json[emit trajectory metrics as JSON]' '--path[target project directory (default: current directory)]' '--task[task ID to operate on (when omitted, resolved from context or single active task)]' '--version[show the installed package version]' ;;
@@ -67,6 +72,7 @@ case $words[2] in
   rule-verify) _arguments '--help[show this help]' '--json[emit structured output as JSON]' '--path[target project directory (default: current directory)]' '--rule[verify a specific policy rule ID]' '--version[show the installed package version]' ;;
   run-action) _arguments '--[exact command argv; shell mode is never used]' '--action[stable durable action ID]' '--approval[current fingerprint-bound approval]' '--capability[canonical action capability]' '--effect-class[durable action effect class]' '--help[show this help]' '--idempotency-key[immutable logical action idempotency key]' '--json[emit structured output as JSON]' '--path[target project directory (default: current directory)]' '--required-for-completion[mark the action as required for completion]' '--requirement[bound completion requirement]' '--target[bounded external action target]' '--task[task ID to operate on (when omitted, resolved from context or single active task)]' '--timeout-ms[maximum command duration before termination]' '--version[show the installed package version]' ;;
   run-check) _arguments '--[exact command argv to classify, execute, and attest]' '--details[additional structured check details]' '--help[show this help]' '--id[stable check identifier]' '--json[emit structured output as JSON]' '--path[target project directory (default: current directory)]' '--requirement[completion requirement covered by the check]' '--scope-ref[current verification-scope.json to bind to execution evidence]' '--task[task ID to operate on (when omitted, resolved from context or single active task)]' '--timeout-ms[maximum command duration before termination]' '--version[show the installed package version]' ;;
+  search) _arguments '--after-context[lines of context after matches]' '--before-context[lines of context before matches]' '--context[lines of context before and after matches]' '--files-with-matches[return matching file paths only]' '--fixed-strings[treat the pattern as a literal string]' '--glob[include files matching a glob]' '--help[show this help]' '--ignore-case[search case-insensitively]' '--json[emit normalized provider-neutral search JSON]' '--max-count[maximum matches per file]' '--path[target project directory (default: current directory)]' '--smart-case[use case-insensitive search only for lowercase patterns]' '--stats[include observed native search statistics]' '--type[include files of a tgrep type]' '--version[show the installed package version]' '--word-regexp[match whole words only]' ;;
   status) _arguments '--contract-file[current JSON contract used for freshness comparison]' '--help[show this help]' '--json[emit structured output as JSON]' '--path[target project directory (default: current directory)]' '--task[task ID to operate on (when omitted, resolved from context or single active task)]' '--version[show the installed package version]' ;;
   task-create) _arguments '--claim[scoped file path or directory prefix claimed for mutation]' '--contract-file[path to initial contract file]' '--help[show this help]' '--json[emit structured output as JSON]' '--path[target project directory (default: current directory)]' '--task[task ID to operate on (when omitted, resolved from context or single active task)]' '--version[show the installed package version]' ;;
   task-list) _arguments '--help[show this help]' '--json[emit structured output as JSON]' '--path[target project directory (default: current directory)]' '--version[show the installed package version]' ;;

package/completions/forgeloop.bash

@@ -35,6 +35,11 @@ _forgeloop() {
       handoff-list) command="handoff-list" ;;
       handoff-show) command="handoff-show" ;;
       history) command="history" ;;
+      index-rebuild) command="index-rebuild" ;;
+      index-setup) command="index-setup" ;;
+      index-start) command="index-start" ;;
+      index-status) command="index-status" ;;
+      index-stop) command="index-stop" ;;
       init) command="init" ;;
       inspect) command="inspect" ;;
       metrics) command="metrics" ;;
@@ -69,6 +74,7 @@ _forgeloop() {
       rule-verify) command="rule-verify" ;;
       run-action) command="run-action" ;;
       run-check) command="run-check" ;;
+      search) command="search" ;;
       status) command="status" ;;
       task-create) command="task-create" ;;
       task-list) command="task-list" ;;
@@ -92,7 +98,7 @@ _forgeloop() {
     esac
   done
   if [[ -z "\${command}" && "\${cur}" != -* ]]; then
-    COMPREPLY=( $(compgen -W 'action-authorize action-propose action-reconcile action-record action-show action-verify activate advance approval-request approval-resolve attestation-create attestation-status attestation-verify attestation-verify-range audit baseline bundle clear-continuity clear-state complete continuity doctor efficiency eval handoff-accept handoff-create handoff-list handoff-show history init inspect metrics migrate-protocol next policy policy-diff policy-discover policy-status preflight prepare-completion profile-interview progress protocol-info quality-baseline quality-status quality-verify reconcile-closure reconcile-continuity record-check record-continuity record-decision-criterion record-diagnosis record-hypothesis-disposition record-intervention record-terminal-result reflect report responsibility-set responsibility-status route rule-verify run-action run-check status task-create task-list task-lock-status task-migrate task-recover task-repair-legacy-recovery task-resume task-scope task-show task-unlock trace update usage-record validate-protocol validate-receipt validate-state verify-scope workspace-bind workspace-status' -- "$cur") )
+    COMPREPLY=( $(compgen -W 'action-authorize action-propose action-reconcile action-record action-show action-verify activate advance approval-request approval-resolve attestation-create attestation-status attestation-verify attestation-verify-range audit baseline bundle clear-continuity clear-state complete continuity doctor efficiency eval handoff-accept handoff-create handoff-list handoff-show history index-rebuild index-setup index-start index-status index-stop init inspect metrics migrate-protocol next policy policy-diff policy-discover policy-status preflight prepare-completion profile-interview progress protocol-info quality-baseline quality-status quality-verify reconcile-closure reconcile-continuity record-check record-continuity record-decision-criterion record-diagnosis record-hypothesis-disposition record-intervention record-terminal-result reflect report responsibility-set responsibility-status route rule-verify run-action run-check search status task-create task-list task-lock-status task-migrate task-recover task-repair-legacy-recovery task-resume task-scope task-show task-unlock trace update usage-record validate-protocol validate-receipt validate-state verify-scope workspace-bind workspace-status' -- "$cur") )
     return
   fi
   case "\${command}" in
@@ -125,6 +131,11 @@ _forgeloop() {
     handoff-list) COMPREPLY=( $(compgen -W '--help --json --path --task --version' -- "$cur") );;
     handoff-show) COMPREPLY=( $(compgen -W '--help --id --json --path --task --version' -- "$cur") );;
     history) COMPREPLY=( $(compgen -W '--checks --compact --failures --help --json --limit --path --phase --since --task --type --until --verbose --version' -- "$cur") );;
+    index-rebuild) COMPREPLY=( $(compgen -W '--asset --help --json --path --version' -- "$cur") );;
+    index-setup) COMPREPLY=( $(compgen -W '--asset --force --help --json --path --version' -- "$cur") );;
+    index-start) COMPREPLY=( $(compgen -W '--help --json --path --version' -- "$cur") );;
+    index-status) COMPREPLY=( $(compgen -W '--help --json --path --version' -- "$cur") );;
+    index-stop) COMPREPLY=( $(compgen -W '--help --json --path --version' -- "$cur") );;
     init) COMPREPLY=( $(compgen -W '--dry-run --help --path --version' -- "$cur") );;
     inspect) COMPREPLY=( $(compgen -W '--contract-file --help --json --path --task --version' -- "$cur") );;
     metrics) COMPREPLY=( $(compgen -W '--help --json --path --task --version' -- "$cur") );;
@@ -159,6 +170,7 @@ _forgeloop() {
     rule-verify) COMPREPLY=( $(compgen -W '--help --json --path --rule --version' -- "$cur") );;
     run-action) COMPREPLY=( $(compgen -W '-- --action --approval --capability --effect-class --help --idempotency-key --json --path --required-for-completion --requirement --target --task --timeout-ms --version' -- "$cur") );;
     run-check) COMPREPLY=( $(compgen -W '-- --details --help --id --json --path --requirement --scope-ref --task --timeout-ms --version' -- "$cur") );;
+    search) COMPREPLY=( $(compgen -W '--after-context --before-context --context --files-with-matches --fixed-strings --glob --help --ignore-case --json --max-count --path --smart-case --stats --type --version --word-regexp' -- "$cur") );;
     status) COMPREPLY=( $(compgen -W '--contract-file --help --json --path --task --version' -- "$cur") );;
     task-create) COMPREPLY=( $(compgen -W '--claim --contract-file --help --json --path --task --version' -- "$cur") );;
     task-list) COMPREPLY=( $(compgen -W '--help --json --path --version' -- "$cur") );;

package/completions/forgeloop.fish

@@ -1,5 +1,5 @@
 # Generated by scripts/generate-shell-completions.mjs. Do not edit.
-complete -c forgeloop -f -n '__fish_use_subcommand' -a 'action-authorize action-propose action-reconcile action-record action-show action-verify activate advance approval-request approval-resolve attestation-create attestation-status attestation-verify attestation-verify-range audit baseline bundle clear-continuity clear-state complete continuity doctor efficiency eval handoff-accept handoff-create handoff-list handoff-show history init inspect metrics migrate-protocol next policy policy-diff policy-discover policy-status preflight prepare-completion profile-interview progress protocol-info quality-baseline quality-status quality-verify reconcile-closure reconcile-continuity record-check record-continuity record-decision-criterion record-diagnosis record-hypothesis-disposition record-intervention record-terminal-result reflect report responsibility-set responsibility-status route rule-verify run-action run-check status task-create task-list task-lock-status task-migrate task-recover task-repair-legacy-recovery task-resume task-scope task-show task-unlock trace update usage-record validate-protocol validate-receipt validate-state verify-scope workspace-bind workspace-status'
+complete -c forgeloop -f -n '__fish_use_subcommand' -a 'action-authorize action-propose action-reconcile action-record action-show action-verify activate advance approval-request approval-resolve attestation-create attestation-status attestation-verify attestation-verify-range audit baseline bundle clear-continuity clear-state complete continuity doctor efficiency eval handoff-accept handoff-create handoff-list handoff-show history index-rebuild index-setup index-start index-status index-stop init inspect metrics migrate-protocol next policy policy-diff policy-discover policy-status preflight prepare-completion profile-interview progress protocol-info quality-baseline quality-status quality-verify reconcile-closure reconcile-continuity record-check record-continuity record-decision-criterion record-diagnosis record-hypothesis-disposition record-intervention record-terminal-result reflect report responsibility-set responsibility-status route rule-verify run-action run-check search status task-create task-list task-lock-status task-migrate task-recover task-repair-legacy-recovery task-resume task-scope task-show task-unlock trace update usage-record validate-protocol validate-receipt validate-state verify-scope workspace-bind workspace-status'
 complete -c forgeloop -f -n '__fish_seen_subcommand_from action-authorize' -l 'action' -d 'durable action ID'
 complete -c forgeloop -f -n '__fish_seen_subcommand_from action-authorize' -l 'approval' -d 'current fingerprint-bound approval'
 complete -c forgeloop -f -n '__fish_seen_subcommand_from action-authorize' -l 'help' -d 'show this help'
@@ -213,6 +213,29 @@ complete -c forgeloop -f -n '__fish_seen_subcommand_from history' -l 'type' -d '
 complete -c forgeloop -f -n '__fish_seen_subcommand_from history' -l 'until' -d 'include events at or before this timestamp'
 complete -c forgeloop -f -n '__fish_seen_subcommand_from history' -l 'verbose' -d 'show full event data'
 complete -c forgeloop -f -n '__fish_seen_subcommand_from history' -l 'version' -d 'show the installed package version'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from index-rebuild' -l 'asset' -d 'use a preloaded pinned tgrep archive instead of downloading'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from index-rebuild' -l 'help' -d 'show this help'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from index-rebuild' -l 'json' -d 'emit repository-index rebuild as JSON'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from index-rebuild' -l 'path' -d 'target project directory (default: current directory)'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from index-rebuild' -l 'version' -d 'show the installed package version'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from index-setup' -l 'asset' -d 'use a preloaded pinned tgrep archive instead of downloading'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from index-setup' -l 'force' -d 'rebuild the repository index even when metadata is current'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from index-setup' -l 'help' -d 'show this help'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from index-setup' -l 'json' -d 'emit repository-index setup as JSON'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from index-setup' -l 'path' -d 'target project directory (default: current directory)'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from index-setup' -l 'version' -d 'show the installed package version'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from index-start' -l 'help' -d 'show this help'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from index-start' -l 'json' -d 'emit repository-index start as JSON'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from index-start' -l 'path' -d 'target project directory (default: current directory)'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from index-start' -l 'version' -d 'show the installed package version'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from index-status' -l 'help' -d 'show this help'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from index-status' -l 'json' -d 'emit repository-index health as JSON'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from index-status' -l 'path' -d 'target project directory (default: current directory)'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from index-status' -l 'version' -d 'show the installed package version'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from index-stop' -l 'help' -d 'show this help'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from index-stop' -l 'json' -d 'emit repository-index stop as JSON'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from index-stop' -l 'path' -d 'target project directory (default: current directory)'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from index-stop' -l 'version' -d 'show the installed package version'
 complete -c forgeloop -f -n '__fish_seen_subcommand_from init' -l 'dry-run' -d 'perform deterministic init planning and conflict detection without writing'
 complete -c forgeloop -f -n '__fish_seen_subcommand_from init' -l 'help' -d 'show this help'
 complete -c forgeloop -f -n '__fish_seen_subcommand_from init' -l 'path' -d 'target project directory (default: current directory)'
@@ -462,6 +485,22 @@ complete -c forgeloop -f -n '__fish_seen_subcommand_from run-check' -l 'scope-re
 complete -c forgeloop -f -n '__fish_seen_subcommand_from run-check' -l 'task' -d 'task ID to operate on (when omitted, resolved from context or single active task)'
 complete -c forgeloop -f -n '__fish_seen_subcommand_from run-check' -l 'timeout-ms' -d 'maximum command duration before termination'
 complete -c forgeloop -f -n '__fish_seen_subcommand_from run-check' -l 'version' -d 'show the installed package version'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from search' -l 'after-context' -d 'lines of context after matches'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from search' -l 'before-context' -d 'lines of context before matches'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from search' -l 'context' -d 'lines of context before and after matches'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from search' -l 'files-with-matches' -d 'return matching file paths only'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from search' -l 'fixed-strings' -d 'treat the pattern as a literal string'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from search' -l 'glob' -d 'include files matching a glob'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from search' -l 'help' -d 'show this help'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from search' -l 'ignore-case' -d 'search case-insensitively'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from search' -l 'json' -d 'emit normalized provider-neutral search JSON'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from search' -l 'max-count' -d 'maximum matches per file'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from search' -l 'path' -d 'target project directory (default: current directory)'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from search' -l 'smart-case' -d 'use case-insensitive search only for lowercase patterns'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from search' -l 'stats' -d 'include observed native search statistics'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from search' -l 'type' -d 'include files of a tgrep type'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from search' -l 'version' -d 'show the installed package version'
+complete -c forgeloop -f -n '__fish_seen_subcommand_from search' -l 'word-regexp' -d 'match whole words only'
 complete -c forgeloop -f -n '__fish_seen_subcommand_from status' -l 'contract-file' -d 'current JSON contract used for freshness comparison'
 complete -c forgeloop -f -n '__fish_seen_subcommand_from status' -l 'help' -d 'show this help'
 complete -c forgeloop -f -n '__fish_seen_subcommand_from status' -l 'json' -d 'emit structured output as JSON'

package/docs/AGENT_PROTOCOL_SUMMARY.md

@@ -7,7 +7,7 @@
 ForgeLoop is a portable protocol and support CLI for verifiable engineering workflows. It records and validates task state, contracts, routing, checks, evidence, continuity, and optional code attestations. It does not become an agent scheduler, delegation service, source-control authority, or secret manager.
 
 Protocol version: 1
-Package version: 1.10.2
+Package version: 1.11.0
 
 ## Canonical loop
 
@@ -90,6 +90,7 @@ Phases: RECEIVED, DISCOVERING, CONTRACT_READY, ROUTED, DESIGNING, PLANNED, EXECU
 | integrationApi | 1 | yes |
 | observabilityStability | n/a | yes |
 | reflection | 1 | yes |
+| repositoryIndex | 1 | yes |
 | responsibilityConstraints | 1 | yes |
 | structuralQuality | 1 | yes |
 | structuredTrace | 1 | yes |
@@ -198,12 +199,14 @@ capability-family versions.
 | efficiency | READ_ONLY | Projects usage and timing efficiency, comparing only against a metadata-compatible local baseline. |
 | eval | MUTATING | Evaluates the current trajectory against a validated project-local reference scenario. |
 | history | READ_ONLY | Shows chronological protocol history reconstructed from canonical ForgeLoop state. |
+| index-status | READ_ONLY | Reports provider-neutral repository-index health, metadata, and owned-server status. |
 | inspect | READ_ONLY | Inspects target repository health, dirty files, active branch, and artifact freshness. |
 | metrics | READ_ONLY | Projects trajectory, action, execution, timing, and known usage metrics without mutating state. |
 | profile-interview | READ_ONLY | Optional interactive or dry-run interview to refine project profile facts. |
 | progress | READ_ONLY | Evaluates task progress across verification cycles and detects stalls deterministically. |
 | protocol-info | READ_ONLY | Reports versioning, lifecycle, command, guide, and public error compatibility metadata for external harnesses. |
 | reflect | READ_ONLY | Analyzes diagnostic and correction history deterministically for information gain, repeated failures, ineffective interventions, and oscillation. |
+| search | READ_ONLY | Searches the ForgeLoop repository index through the provider-neutral search contract. |
 | status | READ_ONLY | Displays current lifecycle phase, active checks, blockers, and artifact freshness bindings. |
 | trace | READ_ONLY | Emits detailed structured task trace with provenance and artifact relationships. |
 | usage-record | MUTATING | Records actor-reported usage telemetry without treating it as verification evidence. |
@@ -248,6 +251,10 @@ capability-family versions.
 
 | Command | Mutation | Purpose |
 | --- | --- | --- |
+| index-rebuild | MUTATING | Atomically rebuilds the repository index and restarts its owned watcher. |
+| index-setup | MUTATING | Provisions the pinned tgrep engine, builds the repository index, and starts its owned watcher. |
+| index-start | MUTATING | Starts the owned tgrep repository-index watcher after an index has been built. |
+| index-stop | MUTATING | Stops only a tgrep server whose process identity is provably owned by ForgeLoop. |
 | init | MUTATING | Initializes a target project directory with ForgeLoop discovery adapters, schemas, and templates. |
 | migrate-protocol | MUTATING | Safely migrates explicitly supported protocol state; unknown target versions fail without rewriting artifacts. |
 | task-migrate | MUTATING | Migrates a legacy 1.0 singleton task state layout into a task-namespaced layout. |

package/docs/CLI_REFERENCE.md

@@ -58,8 +58,8 @@ error codes. Default output and default JSON remain unchanged.
 
 | Category | Commands |
 | --- | --- |
-| **Inspection & Diagnostics** | [`protocol-info`](#protocol-info), [`doctor`](#doctor), [`metrics`](#metrics), [`usage-record`](#usage-record), [`efficiency`](#efficiency), [`eval`](#eval), [`history`](#history), [`trace`](#trace), [`reflect`](#reflect), [`progress`](#progress), [`profile-interview`](#profile-interview), [`inspect`](#inspect), [`status`](#status), [`validate-state`](#validate-state), [`validate-protocol`](#validate-protocol) |
-| **Setup & Maintenance** | [`init`](#init), [`update`](#update), [`task-migrate`](#task-migrate), [`migrate-protocol`](#migrate-protocol), [`task-unlock`](#task-unlock), [`task-recover`](#task-recover), [`task-repair-legacy-recovery`](#task-repair-legacy-recovery), [`task-resume`](#task-resume) |
+| **Inspection & Diagnostics** | [`protocol-info`](#protocol-info), [`doctor`](#doctor), [`index-status`](#index-status), [`search`](#search), [`metrics`](#metrics), [`usage-record`](#usage-record), [`efficiency`](#efficiency), [`eval`](#eval), [`history`](#history), [`trace`](#trace), [`reflect`](#reflect), [`progress`](#progress), [`profile-interview`](#profile-interview), [`inspect`](#inspect), [`status`](#status), [`validate-state`](#validate-state), [`validate-protocol`](#validate-protocol) |
+| **Setup & Maintenance** | [`init`](#init), [`index-setup`](#index-setup), [`index-start`](#index-start), [`index-stop`](#index-stop), [`index-rebuild`](#index-rebuild), [`update`](#update), [`task-migrate`](#task-migrate), [`migrate-protocol`](#migrate-protocol), [`task-unlock`](#task-unlock), [`task-recover`](#task-recover), [`task-repair-legacy-recovery`](#task-repair-legacy-recovery), [`task-resume`](#task-resume) |
 | **Lifecycle & State** | [`activate`](#activate), [`route`](#route), [`preflight`](#preflight), [`advance`](#advance), [`next`](#next), [`record-diagnosis`](#record-diagnosis), [`record-intervention`](#record-intervention), [`record-hypothesis-disposition`](#record-hypothesis-disposition), [`record-decision-criterion`](#record-decision-criterion), [`complete`](#complete), [`clear-state`](#clear-state), [`reconcile-closure`](#reconcile-closure), [`task-create`](#task-create), [`task-list`](#task-list), [`task-show`](#task-show), [`task-lock-status`](#task-lock-status), [`task-scope`](#task-scope) |
 | **Verification & Completion** | [`quality-baseline`](#quality-baseline), [`quality-verify`](#quality-verify), [`quality-status`](#quality-status), [`prepare-completion`](#prepare-completion), [`run-check`](#run-check), [`record-check`](#record-check), [`record-terminal-result`](#record-terminal-result), [`audit`](#audit), [`report`](#report), [`validate-receipt`](#validate-receipt), [`verify-scope`](#verify-scope) |
 | **Cross-Harness Continuity** | [`continuity`](#continuity), [`record-continuity`](#record-continuity), [`reconcile-continuity`](#reconcile-continuity), [`clear-continuity`](#clear-continuity), [`handoff-create`](#handoff-create), [`handoff-list`](#handoff-list), [`handoff-show`](#handoff-show) |
@@ -76,6 +76,118 @@ error codes. Default output and default JSON remain unchanged.
 
 ## 1. Setup & Maintenance
 
+### `index-setup`
+
+Provisions or reuses the managed Repository Index engine, builds its derived
+index, and starts the owned watcher.
+
+- **Purpose**: Establish mandatory repository-search readiness.
+- **Mutation**: Writes only Repository Index runtime state and cache data.
+- **Options**:
+
+<!-- BEGIN FORGELOOP GENERATED: cli:index-setup:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--asset <path>`: use a preloaded pinned tgrep archive instead of downloading
+- `--force`: rebuild the repository index even when metadata is current
+- `--json`: emit repository-index setup as JSON
+
+<!-- END FORGELOOP GENERATED: cli:index-setup:options -->
+
+### `index-start`
+
+Starts the ForgeLoop-owned Repository Index watcher after a complete index is
+available. A verified healthy server is reused.
+
+- **Options**:
+
+<!-- BEGIN FORGELOOP GENERATED: cli:index-start:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--json`: emit repository-index start as JSON
+
+<!-- END FORGELOOP GENERATED: cli:index-start:options -->
+
+### `index-stop`
+
+Stops only a server whose repository, index, metadata, executable, and process
+identity are verified as ForgeLoop-owned.
+
+- **Options**:
+
+<!-- BEGIN FORGELOOP GENERATED: cli:index-stop:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--json`: emit repository-index stop as JSON
+
+<!-- END FORGELOOP GENERATED: cli:index-stop:options -->
+
+### `index-status`
+
+Reports normalized Repository Index engine, index, policy, watcher, and health
+state without repairing or provisioning it.
+
+Structured output is path-safe by default: it omits machine-local repository,
+index, state, and binary paths. Use `doctor` when an explicitly diagnostic
+surface needs local path details.
+
+- **Options**:
+
+<!-- BEGIN FORGELOOP GENERATED: cli:index-status:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--json`: emit repository-index health as JSON
+
+<!-- END FORGELOOP GENERATED: cli:index-status:options -->
+
+### `index-rebuild`
+
+Rebuilds only the derived Repository Index cache and restarts its owned
+watcher. ForgeLoop task and protocol artifacts remain outside the deletion
+boundary.
+
+- **Options**:
+
+<!-- BEGIN FORGELOOP GENERATED: cli:index-rebuild:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `--asset <path>`: use a preloaded pinned tgrep archive instead of downloading
+- `--json`: emit repository-index rebuild as JSON
+
+<!-- END FORGELOOP GENERATED: cli:index-rebuild:options -->
+
+### `search`
+
+Searches the managed Repository Index through the provider-neutral structured
+search contract. Native tgrep flags are not accepted as a generic pass-through.
+
+The first query performs strong setup checks. Warm queries reuse process-local
+per-repository readiness and avoid repeated `tgrep --version`, native status,
+and process-inspection commands. A server/index failure gets one bounded
+setup-and-retry attempt; native exit code `1` is a successful empty result.
+
+- **Options**:
+
+<!-- BEGIN FORGELOOP GENERATED: cli:search:options -->
+
+- `--path <directory>`: target project directory (default: current directory)
+- `<pattern>`: regular expression or literal search pattern
+- `--glob <glob>`: include files matching a glob (repeatable)
+- `--type <type>`: include files of a tgrep type (repeatable)
+- `--fixed-strings`: treat the pattern as a literal string
+- `--ignore-case`: search case-insensitively
+- `--smart-case`: use case-insensitive search only for lowercase patterns
+- `--word-regexp`: match whole words only
+- `--context <lines>`: lines of context before and after matches
+- `--before-context <lines>`: lines of context before matches
+- `--after-context <lines>`: lines of context after matches
+- `--max-count <number>`: maximum matches per file
+- `--files-with-matches`: return matching file paths only
+- `--stats`: include observed native search statistics
+- `--json`: emit normalized provider-neutral search JSON
+
+<!-- END FORGELOOP GENERATED: cli:search:options -->
+
 ## Workspace, Handoff, Responsibility, Scope, and Attestation
 
 These commands add optional, task-scoped protocol artifacts. They do not turn

package/docs/DOCUMENTATION_GUIDE.md

@@ -11,7 +11,7 @@ ForgeLoop strictly separates normative protocol definitions from operational doc
 | Area | Location | Responsibility | Rule |
 | --- | --- | --- | --- |
 | **Normative Protocol** | Root (`LOOP_ENGINEERING.md`, `PROTOCOL_INTEGRATION.md`, `LOOP_SYSTEM_DESIGN.md`, `THREAT_MODEL.md`, `EXECUTION_STATE.md`) | Canonical authority for protocol rules, schemas, state transitions, and security | Never duplicate normative rules in sub-documents; link back to root files. |
-| **Operational & Reference** | `docs/` (`GETTING_STARTED.md`, `CROSS_HARNESS_CONTINUITY.md`, `CLI_REFERENCE.md`, `ARTIFACT_REFERENCE.md`, `TROUBLESHOOTING.md`, `RECIPES.md`) | Tutorials, command reference, handoff workflows, and troubleshooting | Explains how to operate the system. Links to normative sources for formal specifications. |
+| **Operational & Reference** | `docs/` (`GETTING_STARTED.md`, `CROSS_HARNESS_CONTINUITY.md`, `CLI_REFERENCE.md`, `ARTIFACT_REFERENCE.md`, `TROUBLESHOOTING.md`, `RECIPES.md`, `REPOSITORY_INDEX.md`, `PERSISTENT_SEARCH_TRANSPORT.md`) | Tutorials, command reference, handoff workflows, repository search, transport behavior, and troubleshooting | Explains how to operate the system. Links to normative sources for formal specifications. |
 | **Domain Engineering** | `ENG/` (`clean-code-eng.md`, `design-code-eng.md`, `test-code-eng.md`, etc.) | Domain-specific implementation and quality standards | Frontmatter must adhere to `validate_loop_system.py` standards. |
 | **Consumer Documentation Quality** | [`ENG/documentation-quality-eng.md`](../ENG/documentation-quality-eng.md) | Quality standards for documentation work in projects using ForgeLoop | Governs client/consumer project documentation tasks via guide routing. |
 | **Visual Architecture** | `docs/diagrams/manifest.json` + the three typed workflow sources under `docs/diagrams/` | Governance metadata and canonical typed Archify workflow sources | Animated HTML explorers, animated SVG fallbacks, deterministic receipts, and source-bound human reviews are committed under `docs/assets/diagrams/` and `docs/diagrams/reviews/`. |
@@ -34,6 +34,8 @@ Documentation routing   -> DOCS_INDEX.md
 Integration API truth   -> src/integration.js (exports, envelope, limits, risk classes, resources)
 MCP behavior truth      -> integrations/mcp/src/* and integrations/mcp/package.json
 MCP package boundary    -> MCP package tests + scripts/mcp-package-smoke.mjs
+Repository Index truth  -> src/repository-index/*, CLI definitions, Integration API, and MCP resource registry
+Persistent transport truth -> src/persistent-transport/*, CLI search dispatcher, and transport tests
 ```
 
 Operational documentation must explain canonical behavior, not redefine it.
@@ -129,6 +131,8 @@ conformance checks detect omissions.
 | **Discovery resume rules** | `DISCOVERY_SURFACES` & `nativeShim` | `scripts/validate_documentation_conformance.mjs` |
 | **Task-layout path freshness** | `TASK_LAYOUT_DOCUMENTS` & `task-paths.js` | `scripts/validate_documentation_conformance.mjs` |
 | **Package-shipped docs and runtime** | `package.json` (`files`) + `docs/PACKAGE_CONTENTS.md` | `tests/package.test.js` + `scripts/package_smoke.mjs` |
+| **Repository Index contract** | `src/repository-index/*`, `src/core/cli-command-definitions.js`, `src/integration.js` | Repository Index unit/native tests + `scripts/verify-tgrep-manifest.mjs` |
+| **Persistent CLI search transport** | `src/persistent-transport/*`, `src/commands/repository-index.js`, `src/repository-index/search.js` | Persistent transport unit/native tests + Repository Index integration tests |
 | **Architecture and trust diagrams** | `docs/diagrams/manifest.json` plus each typed workflow source | `scripts/check-documentation-diagrams.mjs` and `scripts/documentation-diagram-inventory.mjs` |
 
 ---
@@ -204,10 +208,11 @@ requires an explicit mapping and tests before activation.
 
 ## 8. README Hero and Package Boundary
 
-README hero assets are branding/conceptual illustrations. They are not the
-canonical protocol diagram. The typed Archify workflow under `docs/diagrams/`
-remains the canonical architecture flow source, with generated outputs under
-`docs/assets/diagrams/`.
+README hero assets are branding/conceptual architecture illustrations. They are
+not the canonical protocol diagram. The typed Archify workflow under
+`docs/diagrams/` remains the canonical lifecycle architecture source, with
+generated outputs under `docs/assets/diagrams/`; the CLI-only persistent search
+transport is explained by `docs/PERSISTENT_SEARCH_TRANSPORT.md`.
 
 The README hero is intentionally GitHub-repository-only:
 

package/docs/GETTING_STARTED.md

@@ -99,6 +99,23 @@ What `init` does:
 - Installs the canonical instruction kit under `.forgeloop/kit/`;
 - Places native discovery shims at the project root (`AGENTS.md`, `CLAUDE.md`, `.cursor/rules/`, `.github/copilot-instructions.md`);
 - Creates `.forgeloop/` for project configuration and `.forgeloop/task-state/` for isolated task execution.
+- For a Git repository, provisions the pinned managed Repository Index, builds
+  its derived cache under `.forgeloop/repository-index/tgrep/`, starts the
+  owned watcher, and verifies readiness. The first setup may need network
+  access; use `forgeloop index-setup --asset <absolute-archive>` for an
+  explicitly preloaded release asset.
+
+Repository discovery uses the same canonical service from every transport:
+
+```bash
+forgeloop index-status --json
+forgeloop search "ExecutionReceipt" --json
+```
+
+The index is a disposable local cache. Its matches help an agent find relevant
+files but do not define verification scope, evidence, task ownership, or
+completion truth. Read [`REPOSITORY_INDEX.md`](./REPOSITORY_INDEX.md) for the
+full command, Integration API, MCP, platform, offline, and security contract.
 
 ---
 

package/docs/MCP.md

@@ -56,6 +56,21 @@ Capability flags (process-scoped, immutable after launch):
 - `forgeloop://task/{taskId}/context` — bounded profile-aware host context
 - `forgeloop://task/{taskId}/evaluations`
 - `forgeloop://project/capability-policy`
+- `forgeloop://repository/index-status` — mandatory Repository Index health,
+  pinned engine, policy, and owned-server projection
+
+The `forgeloop_search` tool is the read-only MCP projection of the canonical
+provider-neutral Repository Search command. It accepts bounded search inputs
+and returns project-relative normalized matches without machine-local root,
+index, state, or binary paths; it does not accept raw tgrep arguments, arbitrary
+binaries, or a no-index bypass. Setup/start/stop/rebuild
+remain maintenance commands and are launch-capability gated.
+
+MCP calls the canonical Repository Search service directly. It does not use
+the CLI's user-scoped persistent search host or its local IPC endpoint. The
+transport distinction, host lifecycle, ownership proof, bounded recovery, and
+privacy projection are documented in
+[`PERSISTENT_SEARCH_TRANSPORT.md`](./PERSISTENT_SEARCH_TRANSPORT.md).
 
 The durable-action resources are read-only projections. The first release does
 not expose `run-action` or host-attestation minting over MCP. An action that is
@@ -135,7 +150,7 @@ forgeloop-mcp-http --project /repo --mode safe          # 127.0.0.1:3333
 
 | Component | Current contract |
 | --- | --- |
-| ForgeLoop core package | `>=1.5.0 <2` dependency range; current release `1.10.2` |
+| ForgeLoop core package | `>=1.5.0 <2` dependency range; current release candidate `1.11.0` |
 | ForgeLoop protocol | `1` |
 | Integration API | `1` |
 | MCP package | `0.1.x` initial package |