projecta-rrr 1.21.3 → 1.21.5

package/CHANGELOG.md

@@ -4,6 +4,79 @@ All notable changes to RRR will be documented in this file.
 
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [1.21.5] - 2026-04-18
+
+**Stale-global-CLI detection + `/rrr:update` global-binary refresh.**
+
+### Fixed
+
+- **`/rrr:update` now refreshes the global `projecta-rrr` CLI binary.**
+  Previously, update ran `npx --yes projecta-rrr@latest --global` which
+  updates RRR runtime files in `~/.claude/rrr/` but does NOT touch the
+  `projecta-rrr` binary installed via `npm install -g`. Result: RRR
+  slash-commands worked at the latest version, but subcommands like
+  `projecta-rrr hosted-setup` (added in 1.21.4) failed because the
+  binary on PATH was still from an older version. The update workflow
+  now additionally runs `npm install -g projecta-rrr@latest` with
+  best-effort EACCES tolerance.
+
+- **`install.js` self-detects stale global CLI** at end of install.
+  If `command -v projecta-rrr` resolves to a package.json version older
+  than the currently-running install, prints a clear warning with the
+  two fixes: `npm install -g projecta-rrr@latest` OR use
+  `npx projecta-rrr@latest <subcommand>`.
+
+### Why this matters
+
+A user reported: after `/rrr:update` from 1.20.0 to 1.21.4, running
+`projecta-rrr hosted-setup` fell through to the default RRR install
+flow ("Global/Local?" prompt). Cause: the stale v1.19.1 binary on PATH
+didn't know about `hosted-setup`. Fix lands in 1.21.5.
+
+## [1.21.4] - 2026-04-18
+
+**One-command adoption + slash-command integration.**
+
+### Added
+
+- **`projecta-rrr hosted-setup`** — interactive wizard for any repo to adopt
+  hosted semantic search in ~1 minute. Steps: prerequisite check → bearer
+  paste → team/repo/root_sha detection → `.rrr-search.json` generation →
+  `claude mcp add` → GitHub App install link → first-index hint.
+  Idempotent; safe to re-run. Also callable as:
+    - `projecta-rrr-hosted-setup` (standalone bin)
+    - `npx projecta-rrr hosted-setup`
+
+- **`rrr/references/semantic-search-preference.md`** — shared reference
+  included in 5 slash commands via `@rrr/references/...` import:
+    - `/rrr:progress`
+    - `/rrr:plan-phase`
+    - `/rrr:execute-phase`
+    - `/rrr:discuss-phase`
+    - `/rrr:verify-work`
+
+  Instructs the command workflow to prefer `mcp__rrr-search-hosted__semantic_search`
+  (or local stdio fallback) over Grep/Read for concept-level exploration.
+  Grep remains the right tool for exact-identifier lookups.
+
+- **Postinstall nudge** — after `npm install projecta-rrr`, if the current
+  dir is a git repo without `.rrr-search.json`, prints a 3-line invitation
+  to run `projecta-rrr hosted-setup`. Non-blocking; skipped gracefully on
+  any error.
+
+### Why this release
+
+Before v1.21.4 the hosted infrastructure was live but disconnected from
+daily RRR workflow: slash commands used Grep/Read directly, only the
+`rrr-explore` agent was wired to semantic_search, and the local-stdio
+`rrr-search` was preferred over the hosted path. This release makes the
+hosted path the default for conceptual code exploration across all RRR
+slash commands, while preserving grep for the cases it's best at.
+
+Other repos adopting RRR get `hosted-setup` as a one-step wizard instead
+of the manual `claude mcp add` + `.rrr-search.json` + GitHub App dance
+documented in `docs/ONBOARDING.md`.
+
 ## [1.21.3] - 2026-04-18
 
 **Phase 78 D.5 dogfood — real measurements + onboarding for other repos.**

package/bin/hosted-setup.js

@@ -0,0 +1,275 @@
+#!/usr/bin/env node
+/**
+ * bin/hosted-setup.js — one-command wizard for hosted-search onboarding.
+ *
+ * Walks a user through:
+ *   1. Prerequisite check (claude CLI, git repo, Node 18+)
+ *   2. Bearer token capture (paste OR link to admin)
+ *   3. Team + repo identity (team_id prompt, slug from dir name, root_sha from git)
+ *   4. .rrr-search.json creation (if missing)
+ *   5. `claude mcp add` for rrr-search-hosted
+ *   6. GitHub App install link (open in browser)
+ *   7. Optional: trigger first index via MCP tool (prints curl command)
+ *
+ * Re-entrant: skips completed steps. Idempotent.
+ *
+ * Usage:
+ *   npx projecta-rrr hosted-setup
+ *   OR: rrr-hosted-setup       (if globally installed)
+ *
+ * No-interactive mode (for CI):
+ *   projecta-rrr hosted-setup --team my-team --bearer rrr_... --repo-slug my-repo --yes
+ */
+
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+const { execSync, spawnSync } = require('child_process');
+
+const HOSTED_URL = 'https://rrr-search-hosted.fly.dev/mcp';
+const GH_APP_INSTALL_URL = 'https://github.com/apps/rrr-search/installations/new';
+const MCP_NAME = 'rrr-search-hosted';
+
+// ──────────────────────────────── UI ──────────────────────────────────────
+
+const COLOR = process.stdout.isTTY;
+const c = {
+  dim: s => COLOR ? `\x1b[2m${s}\x1b[0m` : s,
+  bold: s => COLOR ? `\x1b[1m${s}\x1b[0m` : s,
+  green: s => COLOR ? `\x1b[32m${s}\x1b[0m` : s,
+  yellow: s => COLOR ? `\x1b[33m${s}\x1b[0m` : s,
+  red: s => COLOR ? `\x1b[31m${s}\x1b[0m` : s,
+  cyan: s => COLOR ? `\x1b[36m${s}\x1b[0m` : s
+};
+
+function banner (text) {
+  const bar = '━'.repeat(65);
+  console.log(c.cyan(bar));
+  console.log(c.bold(c.cyan(` ${text}`)));
+  console.log(c.cyan(bar));
+}
+
+function step (n, total, title) {
+  console.log();
+  console.log(c.bold(`Step ${n}/${total}: ${title}`));
+}
+
+function ok (msg) { console.log(`  ${c.green('✓')} ${msg}`); }
+function warn (msg) { console.log(`  ${c.yellow('⚠')} ${msg}`); }
+function err (msg) { console.log(`  ${c.red('✗')} ${msg}`); }
+function info (msg) { console.log(`  ${c.dim(msg)}`); }
+
+async function prompt (rl, question) {
+  return new Promise(resolve => rl.question(`  ${c.bold('?')} ${question} `, resolve));
+}
+
+// ──────────────────────────────── args ────────────────────────────────────
+
+function parseArgs (argv) {
+  const out = { team: null, bearer: null, repoSlug: null, yes: false, skipIndex: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--team') out.team = argv[++i];
+    else if (a === '--bearer') out.bearer = argv[++i];
+    else if (a === '--repo-slug') out.repoSlug = argv[++i];
+    else if (a === '--yes' || a === '-y') out.yes = true;
+    else if (a === '--skip-index') out.skipIndex = true;
+    else if (a === '-h' || a === '--help') {
+      console.log(`Usage: projecta-rrr hosted-setup [--team X] [--bearer rrr_...] [--repo-slug X] [--yes] [--skip-index]`);
+      process.exit(0);
+    }
+  }
+  return out;
+}
+
+// ──────────────────────────────── checks ──────────────────────────────────
+
+function which (cmd) {
+  try {
+    execSync(`command -v ${cmd}`, { stdio: 'pipe' });
+    return true;
+  } catch { return false; }
+}
+
+function gitRootSha (cwd) {
+  try {
+    const out = execSync('git rev-list --max-parents=0 HEAD', { cwd, stdio: 'pipe' }).toString().trim().split('\n')[0];
+    if (!/^[a-f0-9]{40}$/.test(out)) return null;
+    return out;
+  } catch { return null; }
+}
+
+function gitRemoteOwnerRepo (cwd) {
+  try {
+    const url = execSync('git config --get remote.origin.url', { cwd, stdio: 'pipe' }).toString().trim();
+    const m = url.match(/[:/]([^/:]+)\/([^/:.]+?)(?:\.git)?$/);
+    if (!m) return null;
+    return { owner: m[1], repo: m[2] };
+  } catch { return null; }
+}
+
+function mcpAlreadyRegistered (name) {
+  try {
+    const out = execSync('claude mcp list', { stdio: 'pipe' }).toString();
+    return out.includes(name + ':');
+  } catch { return false; }
+}
+
+// ──────────────────────────────── flow ────────────────────────────────────
+
+async function main () {
+  const args = parseArgs(process.argv.slice(2));
+  const cwd = process.cwd();
+  const TOTAL_STEPS = 6;
+
+  banner(` rrr-search-hosted setup — ${path.basename(cwd)}`);
+
+  // ---------- Step 1: prerequisites ----------
+  step(1, TOTAL_STEPS, 'Prerequisites');
+  let ready = true;
+
+  if (which('claude')) ok('Claude Code CLI installed');
+  else { err('Claude Code CLI (`claude`) not found on PATH'); ready = false; }
+
+  if (fs.existsSync(path.join(cwd, '.git'))) ok('In a git repo');
+  else { err('Not in a git repo — `cd` into your project root first'); ready = false; }
+
+  const nodeMaj = Number(process.versions.node.split('.')[0]);
+  if (nodeMaj >= 18) ok(`Node ${process.versions.node}`);
+  else { err(`Node ${process.versions.node} (need ≥18)`); ready = false; }
+
+  if (mcpAlreadyRegistered(MCP_NAME)) {
+    warn(`${MCP_NAME} already registered in Claude Code — will re-validate`);
+  }
+
+  if (!ready) { console.log(); err('Fix above and re-run.'); process.exit(1); }
+
+  // ---------- Step 2: bearer token ----------
+  step(2, TOTAL_STEPS, 'Team bearer token');
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+
+  let bearer = args.bearer || process.env.RRR_HOSTED_MCP_TOKEN || null;
+  if (!bearer && !args.yes) {
+    info('You need a bearer token of the form: rrr_<prefix>_<32chars>');
+    info('New team? Ask your rrr-search admin to run:');
+    info('  node rrr/hosted-mcp/scripts/issue-team-token.mjs <team-id>');
+    console.log();
+    bearer = (await prompt(rl, 'Paste bearer (or blank to skip MCP registration):')).trim() || null;
+  }
+
+  if (bearer) {
+    if (!/^rrr_[a-z0-9]{1,16}_[A-Za-z0-9]{32}$/.test(bearer)) {
+      rl.close();
+      err('Bearer format invalid. Expected rrr_<prefix>_<32chars>.');
+      process.exit(1);
+    }
+    ok(`Bearer captured (team prefix: ${bearer.split('_')[1]})`);
+  } else {
+    warn('No bearer — skipping MCP registration. You can run this wizard again after getting one.');
+  }
+
+  // ---------- Step 3: team + repo identity ----------
+  step(3, TOTAL_STEPS, 'Team + repo identity');
+
+  const rootSha = gitRootSha(cwd);
+  if (!rootSha) { rl.close(); err('Could not read git root commit'); process.exit(1); }
+  const rootSha12 = rootSha.slice(0, 12);
+  ok(`root_sha (first 12): ${rootSha12}`);
+
+  const remote = gitRemoteOwnerRepo(cwd);
+  if (remote) info(`Remote: ${remote.owner}/${remote.repo}`);
+
+  let teamId = args.team;
+  if (!teamId) {
+    const default_ = remote?.owner?.toLowerCase()?.replace(/[^a-z0-9-]/g, '-') || 'my-team';
+    if (!args.yes) {
+      teamId = (await prompt(rl, `team_id [${default_}]:`)).trim() || default_;
+    } else teamId = default_;
+  }
+  ok(`team_id: ${teamId}`);
+
+  let repoSlug = args.repoSlug || remote?.repo || path.basename(cwd);
+  if (!args.yes) {
+    const ans = (await prompt(rl, `slug [${repoSlug}]:`)).trim();
+    if (ans) repoSlug = ans;
+  }
+  ok(`slug: ${repoSlug}`);
+
+  const repoId = `${teamId}:${repoSlug}:${rootSha12}`;
+  info(`repo_id: ${repoId}`);
+
+  // ---------- Step 4: .rrr-search.json ----------
+  step(4, TOTAL_STEPS, '.rrr-search.json');
+
+  const cfgPath = path.join(cwd, '.rrr-search.json');
+  if (fs.existsSync(cfgPath)) {
+    ok(`.rrr-search.json exists — leaving as-is`);
+  } else {
+    const cfg = {
+      team_id: teamId,
+      slug: repoSlug,
+      root_sha: rootSha,
+      budget_tokens: 10_000_000,
+      deny_extra: []
+    };
+    fs.writeFileSync(cfgPath, JSON.stringify(cfg, null, 2) + '\n');
+    ok(`Wrote .rrr-search.json (budget 10M tokens, no extra deny globs)`);
+  }
+
+  // ---------- Step 5: register MCP ----------
+  step(5, TOTAL_STEPS, 'Register MCP in Claude Code');
+
+  if (!bearer) {
+    warn('Skipping (no bearer).');
+  } else {
+    if (mcpAlreadyRegistered(MCP_NAME)) {
+      info('Removing existing registration to re-register with current bearer');
+      try { execSync(`claude mcp remove ${MCP_NAME}`, { stdio: 'pipe' }); } catch { /* ignore */ }
+    }
+    const res = spawnSync('claude', [
+      'mcp', 'add', '--transport', 'http', MCP_NAME, HOSTED_URL,
+      '--header', `Authorization: Bearer ${bearer}`
+    ], { stdio: 'pipe' });
+    if (res.status === 0) ok(`Registered ${MCP_NAME}`);
+    else {
+      err(`claude mcp add failed (exit ${res.status})`);
+      console.log(res.stderr?.toString() || res.stdout?.toString() || '');
+      rl.close();
+      process.exit(1);
+    }
+    // Verify connection
+    try {
+      const list = execSync('claude mcp list', { stdio: 'pipe' }).toString();
+      if (list.includes(`${MCP_NAME}:`) && /Connected|✓/.test(list)) {
+        ok('MCP connection verified');
+      } else {
+        warn(`Registered but health check inconclusive — run: claude mcp list`);
+      }
+    } catch { warn('Health check skipped'); }
+  }
+
+  // ---------- Step 6: GitHub App + first index ----------
+  step(6, TOTAL_STEPS, 'GitHub App + first index');
+  console.log();
+  console.log(c.bold('  Install GitHub App (required for ingest):'));
+  console.log(c.cyan(`    ${GH_APP_INSTALL_URL}`));
+  console.log();
+  info('After installing, note the installation_id (URL: .../installations/<ID>)');
+  info(`Then queue first index via MCP tool (with bearer):`);
+  console.log(c.dim(`    mcp__${MCP_NAME}__index_repo({`));
+  console.log(c.dim(`      git_url: "https://github.com/${remote?.owner || '<OWNER>'}/${remote?.repo || '<REPO>'}.git",`));
+  console.log(c.dim(`      team_id: "${teamId}",`));
+  console.log(c.dim(`      slug: "${repoSlug}",`));
+  console.log(c.dim(`      installation_id: <ID>`));
+  console.log(c.dim(`    })`));
+
+  rl.close();
+  console.log();
+  banner(' Done.');
+  console.log(`  ${c.green('→')} Restart Claude Code session (/clear) so MCP tools reload.`);
+  console.log(`  ${c.green('→')} In a new session, agents can call ${c.bold('mcp__rrr-search-hosted__semantic_search')}.`);
+  console.log(`  ${c.dim('Docs: docs/ONBOARDING.md · Troubleshooting: docs/hosted-search-setup.md')}`);
+  console.log();
+}
+
+main().catch(e => { console.error(c.red('Fatal:'), e.message); process.exit(1); });

package/bin/install.js

@@ -1,5 +1,22 @@
 #!/usr/bin/env node
 
+// Subcommand dispatch — v1.21.4+. Routes `projecta-rrr <sub> ...` to
+// dedicated scripts. Empty / --hud-only / --global fall through to the
+// default install flow below for back-compat.
+(function dispatch () {
+  const sub = process.argv[2];
+  if (sub === 'hosted-setup') {
+    require('./hosted-setup.js');
+    return; // the required script runs main() immediately
+  }
+  // Fall through — default RRR install.
+})();
+
+// If the subcommand already took over (e.g. hosted-setup ended the process),
+// the lines below never execute. If we're on the default install path,
+// continue as before.
+if (process.argv[2] === 'hosted-setup') return;
+
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
@@ -2465,6 +2482,55 @@ ${optimizationNote}
 
   Run ${cyan}/rrr:help${reset} anytime to see all commands.
 `);
+
+  // v1.21.4+: nudge for hosted semantic search if not yet set up in cwd.
+  try {
+    const cwd = process.cwd();
+    const inGit = fs.existsSync(path.join(cwd, '.git'));
+    const hasRrrConfig = fs.existsSync(path.join(cwd, '.rrr-search.json'));
+    if (inGit && !hasRrrConfig) {
+      console.log(`  ${cyan}━━━ v1.21 Hosted Semantic Search available ━━━${reset}
+  ${dim}99% token savings vs grep on exploration queries.${reset}
+  ${dim}One-minute wizard walks you through setup:${reset}
+    ${green}projecta-rrr hosted-setup${reset}
+  ${dim}Or read docs/ONBOARDING.md for the manual path.${reset}
+`);
+    }
+  } catch { /* never block install on nudge */ }
+
+  // v1.21.5+: detect stale global CLI. When user ran via `npx projecta-rrr@latest`,
+  // the RRR runtime at ~/.claude/rrr/ is up-to-date but an older
+  // `projecta-rrr` on PATH (from a previous `npm install -g`) may still exist.
+  // Surface the mismatch so users know to run `npm install -g projecta-rrr@latest`.
+  try {
+    const pkgVersion = require('../package.json').version;
+    let onPathVersion = null;
+    try {
+      const onPathBin = execSync('command -v projecta-rrr', { stdio: ['pipe', 'pipe', 'ignore'] }).toString().trim();
+      if (onPathBin) {
+        // Read the package.json of whatever bin is on PATH
+        const realPath = fs.realpathSync(onPathBin);
+        // The bin is bin/install.js inside its package; go up to package.json
+        const binDir = path.dirname(realPath);
+        let candidate = path.dirname(binDir); // .../projecta-rrr
+        const pkgJson = path.join(candidate, 'package.json');
+        if (fs.existsSync(pkgJson)) {
+          onPathVersion = require(pkgJson).version;
+        }
+      }
+    } catch { /* no bin on PATH → not stale, no warning needed */ }
+
+    if (onPathVersion && onPathVersion !== pkgVersion) {
+      console.log(`  ${orange}━━━ Stale global CLI detected ━━━${reset}
+  ${yellow}Your RRR runtime is ${pkgVersion} but the${reset} ${cyan}projecta-rrr${reset} ${yellow}binary on PATH is ${onPathVersion}.${reset}
+  ${dim}This means RRR slash-commands are current, but the${reset} ${cyan}projecta-rrr${reset} ${dim}CLI (e.g.,${reset} ${cyan}hosted-setup${reset}${dim}) is stale.${reset}
+
+  ${dim}Fix (one of):${reset}
+    ${green}npm install -g projecta-rrr@latest${reset}
+    ${green}npx projecta-rrr@latest <subcommand>${reset}   ${dim}(always latest, slower)${reset}
+`);
+    }
+  } catch { /* never block install on stale-check */ }
 }
 
 /**

package/commands/rrr/discuss-phase.md

@@ -21,6 +21,7 @@ Extract implementation decisions that downstream agents need — researcher and
 @~/.claude/rrr/references/principles.md
 @~/.claude/rrr/workflows/discuss-phase.md
 @~/.claude/rrr/templates/context.md
+@rrr/references/semantic-search-preference.md
 </execution_context>
 
 <context>

package/commands/rrr/execute-phase.md

@@ -29,6 +29,7 @@ When `--auto` flag is passed, chains discuss-plan-execute automatically for the
 @~/.claude/rrr/references/ui-brand.md
 @~/.claude/rrr/workflows/execute-phase.md
 @rrr/lib/phase-paths.md
+@rrr/references/semantic-search-preference.md
 </execution_context>
 
 <context>

package/commands/rrr/plan-phase.md

@@ -18,6 +18,7 @@ allowed-tools:
 @~/.claude/rrr/references/ui-brand.md
 @rrr/lib/phase-paths.md
 @rrr/lib/milestone-utils.md
+@rrr/references/semantic-search-preference.md
 </execution_context>
 
 <objective>

package/commands/rrr/progress.md

@@ -19,6 +19,7 @@ Provides situational awareness before continuing work.
 @rrr/lib/phase-paths.md
 @rrr/lib/status-display.js
 @rrr/workflows/drift-guard.md
+@rrr/references/semantic-search-preference.md
 </execution_context>
 
 <process>

package/commands/rrr/update.md

@@ -124,6 +124,33 @@ npx --yes projecta-rrr@latest --global
 2. Should show "Wrote INSTALL_INFO.json"
 3. Should show "Quarantined X legacy/duplicate root(s)" if any were found
 
+**Then refresh the global CLI binary** (v1.21.5+ fix). The `npx` line above
+updates RRR runtime files in `~/.claude/rrr/` but does NOT update the
+`projecta-rrr` binary on the user's PATH (via `~/.npm-global/bin/` or
+equivalent). Run this additional step — it's best-effort and tolerates
+EACCES silently:
+
+```bash
+# Best-effort global CLI refresh — does NOT block update if it fails.
+# On macOS with a prefix-configured npm (~/.npm-global or nvm), this works
+# without sudo. On a raw system install it may hit EACCES — that's fine,
+# user keeps working via npx for CLI invocations.
+npm install -g projecta-rrr@latest 2>&1 | tail -5 || echo "(global CLI refresh skipped — user's npm prefix not writable; use 'npx projecta-rrr' or fix with: npm config set prefix ~/.npm-global)"
+```
+
+**After this step, verify the CLI matches:**
+
+```bash
+projecta-rrr --version 2>&1 | head -1 || which projecta-rrr
+```
+
+If the version shown is older than what just installed, print a warning:
+```
+⚠ CLI binary stale (shows vX.Y.Z, expected vA.B.C).
+  Fix: `npm install -g projecta-rrr@latest` (may need sudo).
+  Workaround: use `npx projecta-rrr <subcommand>` until fixed.
+```
+
 **If install fails:**
 Show error and STOP. Do not proceed.
 </step>

package/commands/rrr/verify-work.md

@@ -72,6 +72,7 @@ Validate built features through **audit mode by default**, or interactive UAT wi
 <execution_context>
 @rrr/lib/phase-paths.md
 @rrr/lib/memory-store.js
+@rrr/references/semantic-search-preference.md
 </execution_context>
 
 <process>

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "projecta-rrr",
-  "version": "1.21.3",
+  "version": "1.21.5",
   "description": "A meta-prompting, context engineering and spec-driven development system for Claude Code by Projecta.ai",
   "bin": {
-    "projecta-rrr": "bin/install.js"
+    "projecta-rrr": "bin/install.js",
+    "projecta-rrr-hosted-setup": "bin/hosted-setup.js"
   },
   "scripts": {
     "postinstall": "node bin/install.js --hud-only --global && node scripts/register-mcp.js",

package/rrr/references/semantic-search-preference.md

@@ -0,0 +1,42 @@
+# Semantic Search Preference (v1.21+)
+
+**Include this via `@rrr/references/semantic-search-preference.md` in slash-command execution contexts.**
+
+## Rule
+
+When exploring the codebase to answer "what does X do?", "where is Y configured?", or "how does Z work?":
+
+1. **If `mcp__rrr-search-hosted__semantic_search` is available** (check via tool list): use it FIRST.
+   - Pass `repo_id` for this repo (format: `{team_id}:{slug}:{root_sha12}`; see `.rrr-search.json`).
+   - Set `k=5` for broad queries, `k=10` for deep dives.
+   - Follow-up with `Read` on the returned file paths if you need full context.
+
+2. **If `mcp__rrr-search__semantic_search` is available** (local stdio fallback): use it second.
+
+3. **Grep/ripgrep** only for **exact identifier lookups** (e.g., `grep "^function foo"`, `rg '\bFOO_CONSTANT\b'`) — NOT for concept exploration.
+
+4. **Read full files** only after semantic search has narrowed the target.
+
+## Why
+
+- **Token cost:** semantic_search returns 3-10 ranked chunks (~500 tokens). Grep returns hundreds of lines (~10K tokens). Read on a 500-line file burns ~10K tokens.
+- **Relevance:** semantic_search ranks by cosine similarity + RRF fusion with ripgrep; grep returns alphabetically.
+- **Cross-file synthesis:** top-K often spans multiple files — one call answers "how X works" that would otherwise need 3-5 greps.
+
+## Discovery
+
+Check availability once at workflow start:
+
+```bash
+claude mcp list 2>&1 | grep -E "rrr-search-hosted|rrr-search:" | head -2
+```
+
+Or via tool list in the current session (tools prefixed with `mcp__rrr-search-hosted__` or `mcp__rrr-search__` are signals).
+
+## Fallback
+
+If neither is registered: proceed with Grep/Read as before. The v1.21 hosted path is additive — it doesn't break local-only workflows.
+
+---
+
+*Referenced by: /rrr:progress, /rrr:plan-phase, /rrr:execute-phase, /rrr:discuss-phase, /rrr:verify-work (v1.21.4+).*