rcf-lite 0.12.0 → 0.14.0

package/src/cli/view.js

@@ -5,7 +5,9 @@
 // exported from that bin now live here so the CLI tests can still
 // exercise them without spawning a subprocess.
 
+import { readFile } from 'node:fs/promises';
 import { spawn } from 'node:child_process';
+import { join } from 'node:path';
 import { platform } from 'node:process';
 
 import { formatErrors } from '#core/errors';
@@ -20,6 +22,8 @@ import {
   readLogTail,
 } from '../view-supervisor/index.js';
 import { parsePersistUntil } from '../view-supervisor/persist-until.js';
+// Deep-link scope resolution (w-2026-08-30-dave-020).
+import { contributionsForBlueprint, listAppliedSlugs, treeHasId } from '../view/scope.js';
 
 export const DEFAULT_PORT = 4373;
 export const SHUTDOWN_BUDGET_MS = 2000;
@@ -58,6 +62,19 @@ Subverbs (spec §9.2):
                             record.
   rcf audit view logs [--tail <n>]
                             Print the supervisor log tail (default 200).
+  rcf audit view open [--blueprint <slug>] [--node <id>] [--no-open] [--json]
+                            Resolve a scoped deep-link into the running
+                            (or default) view server and print the URL.
+                            --blueprint scopes the tree to the applied
+                            blueprint's namespaced contribution list;
+                            --node focuses a single doc id (any kind in
+                            the tree). Both compose. Prints the URL to
+                            stdout every time; opens it in the default
+                            browser too when the terminal is a TTY and
+                            --no-open was not passed. --json emits the
+                            resolution shape for scripting. Refuses (exit
+                            2) if the slug is not applied or the node id
+                            is not on the tree.
 
 Options:
   --port <n>        Bind the HTTP server on the given port.
@@ -96,7 +113,7 @@ Exit codes:
   130 SIGINT
 `;
 
-const SUBVERBS = new Set(['start', 'status', 'stop', 'logs']);
+const SUBVERBS = new Set(['start', 'status', 'stop', 'logs', 'open']);
 
 /**
  * Parse the view subcommand argv. Hand-rolled so the CLI can pass
@@ -375,6 +392,10 @@ async function runSubverb({ subverb, argv, deps }) {
     return 0;
   }
 
+  if (subverb === 'open') {
+    return await runOpenSubverb({ argv, projectRoot, deps: { env, stdout, stderr } });
+  }
+
   if (subverb === 'logs') {
     const tailIdx = argv.indexOf('--tail');
     const tail = tailIdx >= 0 ? Number.parseInt(argv[tailIdx + 1] ?? '', 10) : 200;
@@ -452,3 +473,263 @@ async function runSubverb({ subverb, argv, deps }) {
     return 1;
   }
 }
+
+// -------------------------------------------------------------------
+// `rcf audit view open` (w-2026-08-30-dave-020).
+//
+// Resolves a scoped deep-link into the running (or default) view
+// server and prints the URL. The agent-facing surface: during a
+// blueprint integration validation gate, the agent runs this to hand
+// the operator a URL that opens the viewer with the relevant
+// contribution set already visible (rest dimmed) and the target node
+// scrolled into view. Read-only: v1 does not accept approve/reject
+// state; that is a v2 concern (state-bearing, needs its own design).
+// -------------------------------------------------------------------
+
+/**
+ * Parse the argv slice for `open`. Kept out of `parseArgs` because
+ * the flag set overlaps enough to conflate error messages.
+ *
+ * @param {string[]} argv
+ * @returns {{ opts: object, errors: string[] }}
+ */
+export function parseOpenArgs(argv) {
+  const opts = {
+    blueprint: null,
+    node: null,
+    noOpen: false,
+    json: false,
+    port: null,
+    help: false,
+  };
+  const errors = [];
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    switch (arg) {
+      case '--no-open':
+        opts.noOpen = true;
+        break;
+      case '--json':
+        opts.json = true;
+        break;
+      case '--help':
+      case '-h':
+        opts.help = true;
+        break;
+      case '--blueprint': {
+        const next = argv[i + 1];
+        if (next === undefined || next.startsWith('--')) {
+          errors.push('--blueprint requires a slug argument');
+          break;
+        }
+        opts.blueprint = next;
+        i += 1;
+        break;
+      }
+      case '--node': {
+        const next = argv[i + 1];
+        if (next === undefined || next.startsWith('--')) {
+          errors.push('--node requires a doc id argument');
+          break;
+        }
+        opts.node = next;
+        i += 1;
+        break;
+      }
+      case '--port': {
+        const next = argv[i + 1];
+        if (next === undefined || next.startsWith('--')) {
+          errors.push('--port requires a numeric argument');
+          break;
+        }
+        const n = Number(next);
+        if (!Number.isInteger(n) || n < 0 || n > 65535) {
+          errors.push(`--port expects an integer in [0, 65535], got ${next}`);
+        } else {
+          opts.port = n;
+        }
+        i += 1;
+        break;
+      }
+      default:
+        errors.push(`unknown option: ${arg}`);
+    }
+  }
+  return { opts, errors };
+}
+
+/**
+ * Read `rcf/manifest.json` off disk (bypasses the walker so the CLI
+ * can validate scope fast without a full tree walk when only a slug
+ * check is needed).
+ *
+ * @param {string} projectRoot
+ * @returns {Promise<object|null>}
+ */
+async function readManifestFile(projectRoot) {
+  try {
+    const raw = await readFile(join(projectRoot, 'rcf', 'manifest.json'), 'utf8');
+    return JSON.parse(raw);
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return null;
+    throw err;
+  }
+}
+
+/**
+ * Compose a scoped URL from the base URL plus scope params.
+ *
+ * @param {object} args
+ * @param {string} args.baseUrl - e.g. `http://127.0.0.1:4373/`
+ * @param {string|null} args.blueprint
+ * @param {string|null} args.node
+ * @returns {string}
+ */
+export function composeScopeUrl({ baseUrl, blueprint, node }) {
+  // The base URL from the supervisor / --port / env / default resolver
+  // always ends with `/`. Normalise defensively so a caller-supplied
+  // base without one still composes to a valid URL.
+  const trimmed = baseUrl.endsWith('/') ? baseUrl : `${baseUrl}/`;
+  const params = [];
+  if (blueprint) params.push(`blueprint=${encodeURIComponent(blueprint)}`);
+  if (node) params.push(`node=${encodeURIComponent(node)}`);
+  const query = params.length > 0 ? `?${params.join('&')}` : '';
+  // Hash so the existing hash-router activates the tab + drills the
+  // ancestor <details> chain without waiting for the client to fetch
+  // /scope.json.
+  const hash = node ? `#${encodeURIComponent(node)}` : '';
+  return `${trimmed}${query}${hash}`;
+}
+
+/**
+ * Resolve the base URL to open at. Prefers a running detached
+ * supervisor's recorded URL (respects any non-default --port a prior
+ * start invocation bound to); otherwise the RCF_VIEW_PORT / default
+ * pair. The command still prints a URL even when no server is
+ * running, so an agent can print one to the operator alongside a
+ * hint to start the server.
+ *
+ * @param {object} args
+ * @param {string} args.projectRoot
+ * @param {number|null} args.port
+ * @param {NodeJS.ProcessEnv} args.env
+ * @returns {Promise<{ baseUrl: string, source: 'supervisor'|'flag'|'env'|'default' }>}
+ */
+export async function resolveBaseUrl({ projectRoot, port, env }) {
+  if (typeof port === 'number') {
+    return { baseUrl: `http://127.0.0.1:${port}/`, source: 'flag' };
+  }
+  try {
+    const status = await statusOfDetached(projectRoot);
+    if (status && status.state === 'running' && typeof status.url === 'string' && status.url.length > 0) {
+      const url = status.url.endsWith('/') ? status.url : `${status.url}/`;
+      return { baseUrl: url, source: 'supervisor' };
+    }
+  } catch { /* fall through */ }
+  const raw = env.RCF_VIEW_PORT;
+  if (raw !== undefined && raw !== '') {
+    const n = Number(raw);
+    if (Number.isInteger(n) && n >= 0 && n <= 65535) {
+      return { baseUrl: `http://127.0.0.1:${n}/`, source: 'env' };
+    }
+  }
+  return { baseUrl: `http://127.0.0.1:${DEFAULT_PORT}/`, source: 'default' };
+}
+
+/**
+ * The full open flow. Kept as a named export so the test suite can
+ * exercise it directly.
+ *
+ * @param {object} args
+ * @param {string[]} args.argv
+ * @param {string} args.projectRoot
+ * @param {{ env: NodeJS.ProcessEnv, stdout: NodeJS.WritableStream, stderr: NodeJS.WritableStream }} args.deps
+ * @returns {Promise<number>}
+ */
+export async function runOpenSubverb({ argv, projectRoot, deps }) {
+  const { env, stdout, stderr } = deps;
+  const { opts, errors: argErrors } = parseOpenArgs(argv);
+  if (opts.help) {
+    stdout.write(HELP);
+    return 0;
+  }
+  if (argErrors.length > 0) {
+    for (const msg of argErrors) stderr.write(`[error] usage view open: ${msg}\n`);
+    return 2;
+  }
+  if (!opts.blueprint && !opts.node) {
+    stderr.write('[error] usage view open: pass --blueprint <slug> and/or --node <id>\n');
+    return 2;
+  }
+
+  // Validate scope.
+  let manifest = null;
+  if (opts.blueprint) {
+    manifest = await readManifestFile(projectRoot);
+    const hit = contributionsForBlueprint(manifest, opts.blueprint);
+    if (!hit.found) {
+      const applied = listAppliedSlugs(manifest);
+      const hint = applied.length > 0
+        ? ` Applied: ${applied.join(', ')}.`
+        : ' No blueprints are applied to this project.';
+      stderr.write(`[error] usage view open: blueprint '${opts.blueprint}' is not applied to this project.${hint}\n`);
+      return 2;
+    }
+  }
+  let contributionIds = [];
+  if (manifest && opts.blueprint) {
+    const hit = contributionsForBlueprint(manifest, opts.blueprint);
+    contributionIds = hit.found ? hit.contributionIds : [];
+  }
+
+  if (opts.node) {
+    // Walk the tree once to prove the node exists. Cheaper than
+    // guessing at grammar; also gives the user the same "unknown id"
+    // wording as define/link.
+    const { tree } = await walkTree({ projectRoot });
+    if (!treeHasId(tree, opts.node)) {
+      stderr.write(`[error] usage view open: node id '${opts.node}' is not present on the tree.\n`);
+      return 2;
+    }
+  }
+
+  const { baseUrl, source } = await resolveBaseUrl({ projectRoot, port: opts.port, env });
+  const url = composeScopeUrl({ baseUrl, blueprint: opts.blueprint, node: opts.node });
+  const supervisor = source === 'supervisor';
+  const serverRunningNote = supervisor
+    ? null
+    : 'view server is not running; start it with `rcf audit view start --detach` for the URL to load';
+
+  if (opts.json) {
+    stdout.write(`${JSON.stringify({
+      url,
+      baseUrl,
+      urlSource: source,
+      blueprint: opts.blueprint,
+      node: opts.node,
+      contributionCount: contributionIds.length,
+      opened: false,
+      serverRunning: supervisor,
+    }, null, 2)}\n`);
+  } else {
+    stdout.write(`${url}\n`);
+    if (opts.blueprint) {
+      stdout.write(`  blueprint: ${opts.blueprint} (${contributionIds.length} contribution${contributionIds.length === 1 ? '' : 's'})\n`);
+    }
+    if (opts.node) {
+      stdout.write(`  node: ${opts.node}\n`);
+    }
+    if (serverRunningNote) stdout.write(`  note: ${serverRunningNote}\n`);
+  }
+
+  if (!opts.noOpen) {
+    maybeAutoOpen({
+      target: url,
+      noOpen: opts.noOpen,
+      stream: stdout,
+      env,
+      stderr,
+    });
+  }
+  return 0;
+}

package/src/core/store/writer.js

@@ -824,12 +824,30 @@ async function createInlineAc({ projectRoot, tree, options, body, walkErrors = [
       field: 'parent',
     });
   }
+  // Phantom-AC replacement (G5). A freshly-created US carries a single
+  // seeded AC-N-1 whose description equals the exact seed sentinel below;
+  // the schema requires acceptanceCriteria minItems:1, so we cannot ship
+  // the US without one. On the operator's FIRST `create ac --parent US-N`
+  // (no explicit --id given, and the existing single AC is unmistakably
+  // the seed), we REPLACE that phantom instead of appending after it -
+  // so the operator's first real AC lands at -1 and audit coverage /
+  // trace no longer count the seed as an unmet criterion. Any operator
+  // edit to the seed (custom given/when/then/scope/provenance, different
+  // description, testable=false) disqualifies it from replacement and
+  // the append path runs as before.
+  const currentAcs = Array.isArray(us.acceptanceCriteria) ? us.acceptanceCriteria : [];
+  const seedIndex = detectSeededPhantomAcIndex(currentAcs, parentUsId);
+  const replacingPhantom = seedIndex !== -1 && !options.id;
+
   let acId = options.id;
   if (acId) {
-    const existing = (us.acceptanceCriteria ?? []).some((ac) => ac.id === acId);
+    const existing = currentAcs.some((ac) => ac.id === acId);
     if (existing) {
       return rcfError({ kind: 'usage', message: `create ac: id ${acId} already exists on ${parentUsId}`, documentId: acId });
     }
+  } else if (replacingPhantom) {
+    // Reuse the seed's id (AC-<us>-1) so the operator's first AC is -1.
+    acId = currentAcs[seedIndex].id;
   } else {
     try {
       acId = nextIdForKind(tree, 'ac', { parentId: parentUsId });
@@ -845,9 +863,12 @@ async function createInlineAc({ projectRoot, tree, options, body, walkErrors = [
     ...(body?.when !== undefined ? { when: body.when } : {}),
     ...(body?.then !== undefined ? { then: body.then } : {}),
   };
+  const nextAcs = replacingPhantom
+    ? currentAcs.map((ac, i) => (i === seedIndex ? acEntry : ac))
+    : [...currentAcs, acEntry];
   const nextUs = {
     ...us,
-    acceptanceCriteria: [...(us.acceptanceCriteria ?? []), acEntry],
+    acceptanceCriteria: nextAcs,
     updatedAt: nowIso(),
   };
   const relPath = `rcf/user-stories/${parentUsId.toLowerCase()}.json`;
@@ -871,6 +892,47 @@ async function createInlineAc({ projectRoot, tree, options, body, walkErrors = [
   return { id: acId, filePath: relPath, parentId: parentUsId, body: acEntry };
 }
 
+/**
+ * A newly-created user story ships one seeded acceptance criterion
+ * (schema demands acceptanceCriteria minItems:1). The seed's description
+ * is the exact sentinel below, and no user-authored fields are attached.
+ * This detector returns the index of that seed AC when it is the ONLY AC
+ * on the US and is byte-for-byte unmodified from what the writer / init
+ * placed there; otherwise -1. Used by createInlineAc to REPLACE the seed
+ * on the operator's first `create ac`, so their first real AC lands at
+ * AC-<us>-1 rather than AC-<us>-2.
+ *
+ * Kept in sync with the two seed emitters:
+ *  - src/core/store/writer.js assembleBody 'userStory' -> 'TODO: first acceptance criterion'
+ *  - src/core/store/init.js userStoryTemplate -> 'TODO: describe the first acceptance criterion'
+ *
+ * @param {Array<{id:string, description:string, testable?:boolean}>} acs
+ * @param {string} parentUsId
+ * @returns {number}
+ */
+function detectSeededPhantomAcIndex(acs, parentUsId) {
+  if (!Array.isArray(acs) || acs.length !== 1) return -1;
+  const [ac] = acs;
+  if (!ac || typeof ac !== 'object') return -1;
+  const mUs = /^US-(\d+)$/.exec(parentUsId);
+  if (!mUs) return -1;
+  const expectedId = `AC-${mUs[1]}-1`;
+  if (ac.id !== expectedId) return -1;
+  if (ac.testable !== true) return -1;
+  const seedDescriptions = new Set([
+    'TODO: first acceptance criterion',
+    'TODO: describe the first acceptance criterion',
+  ]);
+  if (!seedDescriptions.has(ac.description)) return -1;
+  // Any operator-authored optional field disqualifies replacement.
+  if (ac.given !== undefined) return -1;
+  if (ac.when !== undefined) return -1;
+  if (ac.then !== undefined) return -1;
+  if (ac.scope !== undefined) return -1;
+  if (ac.provenance !== undefined) return -1;
+  return 0;
+}
+
 /**
  * Create an inline TC under a parent TS.
  */

package/src/server/index.js

@@ -16,6 +16,7 @@ import { join } from 'node:path';
 import { LIVE_CLIENT_PATH, STYLE_CSS_PATH, VENDORED_MERMAID_PATH, renderModelToPage } from '../view/index.js';
 import { watch as defaultWatch } from '../watch/index.js';
 import { createRouter } from './routes.js';
+import { createScopeHandler } from './scope-endpoint.js';
 import { createSseHub } from './sse.js';
 
 /**
@@ -96,12 +97,14 @@ export async function startServer(args) {
   // and the first SSE connect gets a real payload.
   await rewalk();
 
+  const scopeHandler = createScopeHandler({ projectRoot });
   const router = createRouter({
     currentState: () => state,
     sse,
     stylePath: STYLE_CSS_PATH,
     mermaidPath: VENDORED_MERMAID_PATH,
     liveClientPath: LIVE_CLIENT_PATH,
+    scope: scopeHandler,
   });
 
   const server = createServer(router);

package/src/server/routes.js

@@ -1,9 +1,10 @@
-// HTTP route table for the live-view server. Only five routes are served:
+// HTTP route table for the live-view server. Routes served:
 // GET /              -> rendered page (text/html)
 // GET /events        -> SSE stream (text/event-stream)
 // GET /style.css     -> shipped stylesheet
 // GET /mermaid.min.js-> vendored mermaid runtime
 // GET /live-client.js-> phase 3.8 live client script
+// GET /scope.json    -> deep-link scope resolver (w-2026-08-30-dave-020)
 // Everything else -> 404 text/plain.
 //
 // No CORS headers, no cache headers on static assets beyond what the
@@ -25,6 +26,10 @@ const MIME = {
  * @property {string} stylePath
  * @property {string} mermaidPath
  * @property {string} liveClientPath
+ * @property {((req: import('node:http').IncomingMessage, res: import('node:http').ServerResponse) => Promise<void>|void)} [scope]
+ *           Deep-link scope handler (w-2026-08-30-dave-020). Optional so
+ *           the router stays usable in tests that mount only the static
+ *           routes without a project root.
  */
 
 /**
@@ -74,6 +79,15 @@ export function createRouter(deps) {
       serveFile(res, deps.liveClientPath, MIME.js).catch((err) => fail(res, err));
       return;
     }
+    if (path === '/scope.json') {
+      if (typeof deps.scope !== 'function') {
+        res.writeHead(404, { 'content-type': MIME.txt });
+        res.end('not found\n');
+        return;
+      }
+      Promise.resolve(deps.scope(req, res)).catch((err) => fail(res, err));
+      return;
+    }
 
     res.writeHead(404, { 'content-type': MIME.txt });
     res.end('not found\n');

package/src/server/scope-endpoint.js

@@ -0,0 +1,105 @@
+// HTTP handler for `/scope.json`. The live-client fetches this to
+// resolve a `?blueprint=<slug>` URL query into the applied
+// contribution list and the customised-since-apply subset.
+//
+// Three shapes:
+//   GET /scope.json                    -> { blueprints: [{ slug, contributionCount, appliedAt, version }] }
+//                                          (the applied blueprint index; used by the client to know
+//                                          which slugs are valid before firing a scoped request)
+//   GET /scope.json?blueprint=<slug>   -> { slug, appliedAt, version, contributionIds, customisedIds, missingSourceIds }
+//   GET /scope.json?blueprint=<slug>   with slug not applied -> 404 { error: 'unknownBlueprint', slug }
+//
+// The endpoint is read-only. It reads manifest.json every call rather
+// than piggy-backing on the cached tree state; the caller is a browser
+// (small payload, low frequency), and a fresh read means scope answers
+// track a re-apply immediately even if a tree-update SSE broadcast has
+// not yet propagated.
+
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { contributionsForBlueprint, detectCustomisations, listAppliedSlugs } from '../view/scope.js';
+
+const MIME_JSON = 'application/json; charset=utf-8';
+
+/**
+ * Build a handler bound to a project root. Returns a function suitable
+ * for wiring into the router as the `/scope.json` route.
+ *
+ * @param {object} args
+ * @param {string} args.projectRoot
+ * @param {(root: string) => Promise<object|null>} [args._readManifest] - test seam
+ * @returns {(req: import('node:http').IncomingMessage, res: import('node:http').ServerResponse) => Promise<void>}
+ */
+export function createScopeHandler({ projectRoot, _readManifest, _detectCustomisations } = {}) {
+  const readManifest = _readManifest ?? defaultReadManifest;
+  const detectImpl = _detectCustomisations ?? detectCustomisations;
+  return async function handle(req, res) {
+    try {
+      const url = new URL(req.url ?? '/', 'http://localhost');
+      const slug = normaliseString(url.searchParams.get('blueprint'));
+      const manifest = await readManifest(projectRoot);
+      if (!slug) {
+        respond(res, 200, {
+          blueprints: appliedIndex(manifest),
+        });
+        return;
+      }
+      const found = contributionsForBlueprint(manifest, slug);
+      if (!found.found) {
+        respond(res, 404, { error: 'unknownBlueprint', slug });
+        return;
+      }
+      const { customisedIds, missingSourceIds } = await detectImpl({
+        projectRoot,
+        record: found.record,
+      });
+      respond(res, 200, {
+        slug,
+        appliedAt: found.record.appliedAt ?? null,
+        version: found.record.version ?? null,
+        contributionIds: found.contributionIds,
+        customisedIds,
+        missingSourceIds,
+      });
+    } catch (err) {
+      respond(res, 500, { error: 'ioFailure', message: err && err.message ? err.message : 'unknown' });
+    }
+  };
+}
+
+function appliedIndex(manifest) {
+  const slugs = listAppliedSlugs(manifest);
+  const list = manifest?.blueprints ?? [];
+  return slugs.map((slug) => {
+    const rec = list.find((b) => b?.slug === slug) ?? {};
+    return {
+      slug,
+      version: rec.version ?? null,
+      appliedAt: rec.appliedAt ?? null,
+      contributionCount: Array.isArray(rec.contributions) ? rec.contributions.length : 0,
+    };
+  });
+}
+
+function normaliseString(v) {
+  if (typeof v !== 'string') return null;
+  const trimmed = v.trim();
+  return trimmed.length === 0 ? null : trimmed;
+}
+
+async function defaultReadManifest(projectRoot) {
+  try {
+    const raw = await readFile(join(projectRoot, 'rcf', 'manifest.json'), 'utf8');
+    return JSON.parse(raw);
+  } catch (err) {
+    if (err && err.code === 'ENOENT') return null;
+    throw err;
+  }
+}
+
+function respond(res, status, body) {
+  const buf = Buffer.from(`${JSON.stringify(body)}\n`, 'utf8');
+  res.writeHead(status, { 'content-type': MIME_JSON, 'content-length': String(buf.length) });
+  res.end(buf);
+}

package/src/setup/agent-setup.js

@@ -184,17 +184,25 @@ export async function loadHarnessFragment({ templatePath } = {}) {
 }
 
 /**
- * Write or merge the project-root .mcp.json with the rcf server entry
- * (the exact registration shape docs/install.md documents). MERGE
- * discipline: other servers and unknown top-level keys are preserved
+ * Write or merge the project-root .mcp.json with the rcf server entry.
+ * MERGE discipline: other servers and unknown top-level keys are preserved
  * verbatim; an existing `rcf` entry is left alone.
  *
+ * The default entry invokes the CLI via `npx rcf-lite mcp` rather than an
+ * absolute `node <binPath>` path so the config stays portable across
+ * machines and CI checkouts (a project imported on a teammate's machine
+ * or moved to a different install location keeps working without a
+ * re-init). Callers wiring the config from tests can still pass an
+ * absolute `binPath` to force the legacy `node <binPath> mcp` shape.
+ *
  * @param {object} args
  * @param {string} args.projectRoot
- * @param {string} [args.binPath] - test override
+ * @param {string} [args.binPath] - if provided, use `{ command: 'node',
+ *        args: [binPath, 'mcp'] }` instead of `npx rcf-lite mcp`. Test
+ *        override / opt-out for pinned deployments.
  * @returns {Promise<{ file: string, action: 'created'|'merged'|'kept' } | import('#core/errors').RcfError>}
  */
-export async function writeMcpConfig({ projectRoot, binPath = rcfBinPath() }) {
+export async function writeMcpConfig({ projectRoot, binPath } = {}) {
   const file = join(projectRoot, '.mcp.json');
   const raw = await readIfExists(file);
   let config = {};
@@ -224,11 +232,14 @@ export async function writeMcpConfig({ projectRoot, binPath = rcfBinPath() }) {
   if (servers.rcf) {
     return { file: '.mcp.json', action: 'kept' };
   }
+  const rcfEntry = typeof binPath === 'string' && binPath.length > 0
+    ? { command: 'node', args: [binPath, 'mcp'] }
+    : { command: 'npx', args: ['rcf-lite', 'mcp'] };
   const next = {
     ...config,
     mcpServers: {
       ...servers,
-      rcf: { command: 'node', args: [binPath, 'mcp'] },
+      rcf: rcfEntry,
     },
   };
   await writeFile(file, `${JSON.stringify(next, null, 2)}\n`, 'utf8');
@@ -345,15 +356,22 @@ export const SETUP_FUNNEL_INSTRUCTION = 'Setup incomplete. Run `npx rcf init` to
 /**
  * Manual instructions printed by `rcf init --no-agent-setup`.
  *
- * @param {string} [binPath]
+ * @param {string} [binPath] - when omitted (the default), the manual
+ *   registration snippet uses `npx rcf-lite mcp` for portability across
+ *   machines and checkouts. Pass a specific absolute path only when the
+ *   caller wants to pin to a particular install (test fixtures, or a
+ *   deployment that has deliberately vendored the CLI).
  * @returns {string}
  */
-export function manualSetupInstructions(binPath = rcfBinPath()) {
+export function manualSetupInstructions(binPath) {
+  const useNpx = typeof binPath !== 'string' || binPath.length === 0;
+  const registration = useNpx
+    ? '       { "mcpServers": { "rcf": { "command": "npx", "args": ["rcf-lite", "mcp"] } } }'
+    : `       { "mcpServers": { "rcf": { "command": "node", "args": ["${binPath}", "mcp"] } } }`;
   return [
     'Agent setup skipped (--no-agent-setup). To wire the harness manually:',
     '  1. Register the MCP server in your project-root .mcp.json:',
-    '       { "mcpServers": { "rcf": { "command": "node",',
-    `         "args": ["${binPath}", "mcp"] } } }`,
+    registration,
     '  2. Paste the fragment from `rcf guidance harness-template` (the',
     '     first ```markdown fence) into your project\'s CLAUDE.md or',
     '     AGENTS.md.',