rcf-lite 0.12.0 → 0.13.0

package/src/blueprint/namespace.js

@@ -12,12 +12,14 @@
 //
 // - Prefix families (REQ, US, PRD, BS, TAD, TS): the blueprint slug is
 //   attached as a lowercase kebab-slug PREFIX joined by `-` to the
-//   family prefix. `REQ-001` under blueprint `spa` becomes `spa-REQ-001`.
+//   family prefix. `REQ-001` under blueprint `application-spa` becomes
+//   `application-spa-REQ-001`.
 //
 // - Suffix families (ADR, TAC, FBS, CN): the blueprint slug is attached
 //   as a lowercase kebab-slug SUFFIX joined by `-` to the numeric tail.
-//   `ADR-005` under blueprint `spa` becomes `ADR-005-spa`; a longer slug
-//   segment (`spa-theme`) becomes `ADR-005-spa-theme`.
+//   `ADR-005` under blueprint `application-spa` becomes
+//   `ADR-005-application-spa`; a longer slug (`application-spa-theme`)
+//   becomes `ADR-005-application-spa-theme`.
 //
 // - AC and TC: not namespaced. AC ids are anchored to their parent US
 //   (whose id is prefix-namespaced) and TC ids are anchored to their
@@ -70,21 +72,22 @@ export function namespaceStyleFor(id) {
  *   - Ids that already carry a slug segment are accepted VERBATIM: the
  *     blueprint author's declared contribution list is the truth for
  *     what that blueprint owns. String grammar does not veto (`stampId`
- *     used to refuse `ADR-201-spa-theme` under slug `spa` on the basis
- *     that `spa-theme` != `spa`, which broke every blueprint whose
- *     suffix-family ids carried a semantic tail after the slug).
+ *     used to refuse `ADR-201-application-spa-theme` under slug
+ *     `application-spa` on the basis that `application-spa-theme` !=
+ *     `application-spa`, which broke every blueprint whose suffix-family
+ *     ids carried a semantic tail after the slug).
  *   - AC and TC pass through unchanged (no namespacing family).
  *   - An id that matches no family pattern, or a slug that is not a
  *     valid kebab, is refused.
  *
- * Cross-blueprint claims (`spa-theme-REQ-001` declared under blueprint
- * `spa` where `spa-theme` is also applied) are caught by the manifest-
- * record consulted at write time (`apply.js` overwrite guard +
- * cross-claim detector). String parsing here is deliberately not a
- * trust surface.
+ * Cross-blueprint claims (`application-spa-theme-REQ-001` declared
+ * under blueprint `application-spa` where `application-spa-theme` is
+ * also applied) are caught by the manifest-record consulted at write
+ * time (`apply.js` overwrite guard + cross-claim detector). String
+ * parsing here is deliberately not a trust surface.
  *
  * @param {string} id - canonical id (either bare `REQ-001` or already
- *                      namespaced `spa-REQ-001` / `ADR-201-spa-theme`)
+ *                      namespaced `application-spa-REQ-001` / `ADR-201-application-spa-theme`)
  * @param {string} slug - blueprint slug (must be well-formed kebab)
  * @returns {{ id: string } | { error: string }}
  */
@@ -119,10 +122,11 @@ export function stampId(id, slug) {
  * scan). `isNamespacedFor` retains exact-slug grammar semantics for
  * external consumers (docs generators, id-audit tooling) but must NOT
  * be used to authorise a write or a delete -- for slug+tail ids like
- * `ADR-201-spa-theme` the parsed suffix is `spa-theme`, which returns
- * false for a legitimate `spa`-owned contribution whose author put a
- * semantic tail after the slug. That misread is the exact reason the
- * ownership call-sites were routed off this predicate.
+ * `ADR-201-application-spa-theme` the parsed suffix is
+ * `application-spa-theme`, which returns false for a legitimate
+ * `application-spa`-owned contribution whose author put a semantic tail
+ * after the slug. That misread is the exact reason the ownership
+ * call-sites were routed off this predicate.
  *
  * @param {string} id
  * @param {string} slug

package/src/blueprint/shelf-resolver.js

@@ -0,0 +1,173 @@
+// Resolve a `rcf define blueprint add <source>` argument to an absolute
+// blueprint directory.
+//
+// Resolution order (Phase 1; the phase-2 external-library registry
+// layers on top of this without reworking the CLI):
+//
+//   1. Any argument that names a filesystem location - starts with `./`,
+//      `../`, `/`, or `~`, or contains a path separator, or names an
+//      existing directory - is treated as a PATH and returned unchanged.
+//      This preserves the existing local / relative-path semantic every
+//      test and existing operator invocation relies on.
+//   2. `@stock/<slug>` is reserved for the packaged shelf. The `@stock/`
+//      qualifier strips off and the bare slug resolves against the
+//      packaged shelf. This is the recommended long-form.
+//   3. Any other bare kebab slug (`deploy-cloudflare-workers`,
+//      `application-spa`) resolves against the packaged shelf. This is
+//      the sugar the persona reviews asked for; it means the docs and
+//      the CLI say the same thing.
+//   4. A slug qualifier that names a KNOWN external-library alias other
+//      than `@stock` is rejected with a clear message pointing the
+//      operator at the current phase-1 capabilities. This reservation
+//      keeps the phase-2 external-libraries mechanism free to land the
+//      registry surface later without a breaking rename.
+//
+// The packaged shelf lives at `<packageRoot>/blueprints/<slug>/` - the
+// tarball is built with `files: [ "blueprints" ]` and a `prepack`
+// script that copies the repo-root shelf into the package directory
+// before pack runs.
+
+import { existsSync } from 'node:fs';
+import { stat } from 'node:fs/promises';
+import { dirname, isAbsolute, join, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { rcfError } from '../core/errors/index.js';
+
+const here = dirname(fileURLToPath(import.meta.url));
+// packages/rcf-lite/src/blueprint -> packages/rcf-lite
+const PACKAGE_ROOT = resolve(here, '..', '..');
+const PACKAGED_SHELF = join(PACKAGE_ROOT, 'blueprints');
+
+const KEBAB_SLUG = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+const QUALIFIED = /^@([a-z][a-z0-9-]*)\/([a-z][a-z0-9]*(?:-[a-z0-9]+)*)$/;
+
+const PATH_HINT = /[\\/]|^~|^\./;
+
+/**
+ * @typedef {object} ResolvedSource
+ * @property {'path' | 'shelf'} kind
+ *   `path` if the argument was treated as a filesystem path (unchanged);
+ *   `shelf` if a bare slug or `@stock/<slug>` was resolved against the
+ *   packaged shelf. The apply.js layer treats both the same once resolved -
+ *   both are absolute directory paths - but the kind is exposed for the
+ *   CLI's future diagnostics (`--dry-run` labelling, etc.).
+ * @property {string} resolved  Absolute path suitable for `applyBlueprint({ source })`.
+ * @property {string} original  The argument the operator typed, preserved for
+ *   diagnostics and the conflict-renderer's supersede hint.
+ * @property {string} [slug]    The bare slug when resolution went through the shelf.
+ */
+
+/**
+ * @param {string} source - argument as typed by the operator
+ * @param {object} [opts]
+ * @param {string} [opts.packagedShelf] - override for tests
+ * @returns {Promise<ResolvedSource | import('../core/errors/index.js').RcfError>}
+ */
+export async function resolveBlueprintSource(source, opts = {}) {
+  if (typeof source !== 'string' || source.length === 0) {
+    return rcfError({ kind: 'usage', message: 'blueprint source is required' });
+  }
+  const packagedShelf = opts.packagedShelf ?? PACKAGED_SHELF;
+
+  // Rule 2 / 4 FIRST: qualified `@lib/slug` forms carry a `/` that
+  // would otherwise trip the path-hint check below. `@stock/<slug>`
+  // resolves to the packaged shelf; any other library qualifier is
+  // reserved for the phase-2 external-libraries mechanism and refuses
+  // with a clear message.
+  const qualified = QUALIFIED.exec(source);
+  if (qualified) {
+    const [, library, slug] = qualified;
+    if (library === 'stock') {
+      return resolveShelfSlug(slug, source, packagedShelf);
+    }
+    return rcfError({
+      kind: 'usage',
+      message: (
+        `blueprint source '${source}' names external library '@${library}', which is reserved for the phase-2 external-libraries mechanism and not resolvable yet. `
+        + 'Use `@stock/<slug>` for the packaged shelf, a local path (`./path/to/blueprint`), or wait for the external-library registry.'
+      ),
+    });
+  }
+
+  // Rule 1: path-looking arguments are passed through unchanged. We look
+  // at the SHAPE only (does it contain a separator, does it start with a
+  // relative-path marker, is it absolute), so an existing operator with a
+  // `./blueprints/foo` invocation keeps the current behaviour byte-for-byte.
+  if (isAbsolute(source) || PATH_HINT.test(source)) {
+    return { kind: 'path', resolved: resolve(source), original: source };
+  }
+
+  // Rule 3: any other bare kebab token is a shelf slug.
+  if (KEBAB_SLUG.test(source)) {
+    return resolveShelfSlug(source, source, packagedShelf);
+  }
+
+  // Anything that has slipped through here is neither a path, nor a
+  // qualified library slug, nor a bare kebab slug. Treat it as a path so
+  // the loader emits the familiar "no blueprint.json found" error against
+  // the exact string the operator typed; that keeps the failure locus
+  // close to what they wrote rather than adding a resolver-specific class.
+  return { kind: 'path', resolved: resolve(source), original: source };
+}
+
+async function resolveShelfSlug(slug, original, packagedShelf) {
+  const candidate = join(packagedShelf, slug);
+  if (!existsSync(candidate)) {
+    const known = await knownShelfSlugs(packagedShelf);
+    const suggestion = known.length > 0
+      ? ` Known shelf slugs: ${known.join(', ')}.`
+      : ' The packaged shelf appears empty; reinstall rcf-lite to restore it.';
+    return rcfError({
+      kind: 'usage',
+      message: `blueprint source '${original}' did not match a packaged shelf entry at ${candidate}.${suggestion}`,
+      filePath: candidate,
+    });
+  }
+  try {
+    const s = await stat(candidate);
+    if (!s.isDirectory()) {
+      return rcfError({
+        kind: 'usage',
+        message: `blueprint source '${original}' resolved to ${candidate} but that path is not a directory.`,
+        filePath: candidate,
+      });
+    }
+  } catch (err) {
+    return rcfError({
+      kind: 'ioFailure',
+      message: `blueprint source '${original}' resolution failed: ${err.message}`,
+      filePath: candidate,
+    });
+  }
+  return { kind: 'shelf', resolved: candidate, original, slug };
+}
+
+/**
+ * Enumerate the packaged shelf's slugs (top-level directories). Empty
+ * array on a missing shelf. Used to render a helpful "did you mean"
+ * hint on a resolver miss.
+ *
+ * @param {string} [packagedShelf]
+ * @returns {Promise<string[]>}
+ */
+export async function knownShelfSlugs(packagedShelf = PACKAGED_SHELF) {
+  try {
+    const { readdir } = await import('node:fs/promises');
+    const entries = await readdir(packagedShelf, { withFileTypes: true });
+    return entries
+      .filter((e) => e.isDirectory())
+      .map((e) => e.name)
+      .sort();
+  } catch {
+    return [];
+  }
+}
+
+/** Absolute path of the packaged shelf. Test-visible. */
+export function packagedShelfPath() {
+  return PACKAGED_SHELF;
+}
+
+/** Placeholder to keep unused-import linters happy in bundles that only pull the constant. */
+export const PATH_SEPARATOR = sep;

package/src/blueprint/supersede.js

@@ -85,12 +85,13 @@ export async function supersedeBlueprintTopic({ projectRoot, tree, topic, incomi
   if (typeof topic !== 'string' || topic.trim().length === 0) {
     // Schema minLength:1 accepts whitespace-only; the writer refuses
     // it up-front so a whitespace-only topic never lands on disk.
-    return rcfError({ kind: 'usage', message: `topic is required (e.g. rcf define blueprint supersede errorEnvelope --incoming ./blueprints/rest)` });
+    return rcfError({ kind: 'usage', message: `topic is required (e.g. rcf define blueprint supersede errorEnvelope --incoming ./blueprints/application-api-rest)` });
   }
   // Topic is a LOOKUP KEY into applied ADR topics, not a slug (ADR-010).
   // Schema is minLength:1 with no character constraint and the schema
   // docs explicitly cite camelCase examples ('errorEnvelope'). The
-  // shipped SPA + REST blueprints declare camelCase topics; we accept
+  // shipped application-spa + application-api-rest blueprints declare
+  // camelCase topics; we accept
   // any topic string that exact-matches an applied or incoming ADR
   // topic below, and kebab-ify only when projecting into the
   // scaffolded project-ADR id slug tail (adrId grammar requires

package/src/browser-verify/invariants.js

@@ -34,6 +34,7 @@
  * @property {object} [uiBaseline]               the manifest uiBaseline record (defaults + opt-outs)
  * @property {string} dom                        the response HTML for the route
  * @property {boolean} [authenticated]           whether the request carried the auth cookie
+ * @property {string} [landedPath]               the pathname the browser's final URL resolved to after any redirect chain; when the driver reports it, `authenticatedLandsOnRequestedPath` compares it against `routePath` (AC-1131-3 landed-path refusal)
  */
 
 const OPT_OUT_FIELDS = new Set([
@@ -91,6 +92,12 @@ const V1_INVARIANTS = [
     perThemeOnly: false,
     run: checkNoInlineStyleBlocks,
   },
+  {
+    name: 'authenticatedLandsOnRequestedPath',
+    severity: 'block',
+    perThemeOnly: false,
+    run: checkAuthenticatedLandsOnRequestedPath,
+  },
 ];
 
 /** Versioned constant, module-encoded per §12 O-6. */
@@ -326,6 +333,39 @@ function checkNoInlineStyleBlocks(ctx) {
   };
 }
 
+/**
+ * AC-1131-3 landed-path refusal: when the driver reports the browser's
+ * final URL path after any redirect chain resolves, and the request was
+ * for an authenticated route, the landed path MUST equal the requested
+ * route path. Cures the class of harness where a broken session lane
+ * silently caused every authenticated-route assertion to run against a
+ * styled /login (Playwright's page.goto follows redirects by default,
+ * so the resolved response is 200 from the redirect target and the
+ * downstream styled/CSP assertions pass against the wrong surface).
+ * Watchpost partial-acceptance w-2026-08-24-003 / AC-1601-14; ported
+ * into the SPA blueprint TAC-209 v1.0.1.
+ *
+ * The invariant is opt-in: when the driver does NOT populate
+ * `ctx.landedPath` the invariant passes (older drivers keep working).
+ * Once the SPA-blueprint drivers report `landedPath` this becomes a
+ * hard block-severity refusal.
+ */
+function checkAuthenticatedLandsOnRequestedPath(ctx) {
+  if (typeof ctx.landedPath !== 'string' || ctx.landedPath.length === 0) return { verdict: 'pass' };
+  if (ctx.authenticated === false) return { verdict: 'pass' };
+  const routes = ctx.fbs?.designStage?.navModel?.routes ?? [];
+  const routeSpec = routes.find((r) => r.path === ctx.routePath);
+  // If the FBS enumerates the route and marks it authRequired=false, the
+  // landed-path refusal does not fire (a public route is allowed to
+  // redirect to any other public surface by design).
+  if (routeSpec && routeSpec.authRequired === false && ctx.authenticated !== true) return { verdict: 'pass' };
+  if (ctx.landedPath === ctx.routePath) return { verdict: 'pass' };
+  return {
+    verdict: 'fail',
+    detail: `authenticated navigation landed on '${ctx.landedPath}' (requested '${ctx.routePath}'); a silent redirect chain to another surface (e.g. a session-broken 302 to /login) validated the redirect target's styled state instead of the requested route (AC-1131-3 pathMismatch; watchpost AC-1601-14, w-2026-08-24-003).`,
+  };
+}
+
 function topLevelChildTagSequence(dom) {
   // Extract the tag-name sequence of direct children of <body>. Cheap
   // regex-based; deliberately conservative (misses nested body-siblings

package/src/browser-verify/runner.js

@@ -28,6 +28,7 @@ import { composeBrowserVerificationRecord } from './manifest-writer.js';
  * @property {string} dom
  * @property {string} screenshotPath
  * @property {boolean} [authenticated]
+ * @property {string} [landedPath]  the pathname of the browser's final URL after any redirect chain resolved (`new URL(page.url()).pathname`); when the driver reports it, the `authenticatedLandsOnRequestedPath` invariant fires (AC-1131-3 landed-path refusal, watchpost AC-1601-14 port)
  */
 
 /**
@@ -78,6 +79,7 @@ export async function runAgentScreenshotCritique({
       uiBaseline: tree.manifest?.uiBaseline,
       dom: cap.dom,
       authenticated: cap.authenticated,
+      landedPath: cap.landedPath,
     });
     perCapture.push({ routePath: cap.routePath, themeApplied: cap.themeApplied, results });
     routesChecked.push({ path: cap.routePath, screenshotPath: cap.screenshotPath, themeApplied: cap.themeApplied });

package/src/cli/blueprint.js

@@ -16,9 +16,12 @@ import { findProjectRoot } from '../view/index.js';
 import {
   applyBlueprint,
   diffBlueprintTopic,
+  enrichRowsWithCategories,
+  groupRowsByCategory,
   listBlueprints,
   removeBlueprint,
   renderDiff,
+  resolveBlueprintSource,
   supersedeBlueprintTopic,
 } from '../blueprint/index.js';
 import { conflictReportJson, renderConflictReport } from '../blueprint/conflicts.js';
@@ -26,13 +29,23 @@ import { conflictReportJson, renderConflictReport } from '../blueprint/conflicts
 export const HELP = `Usage: rcf define blueprint <verb> [options]
 
 Verbs:
-  add <source>           Apply a blueprint from a source directory
-                         (Phase 1: local path; the registry / git-ref
-                         resolver is a Phase 2 concern). Writes an entry
-                         to manifest.blueprints[] and copies namespaced
-                         contributions into the tree.
+  add <source>           Apply a blueprint from a source directory.
+                         <source> resolves in this order:
+                           - a path (./foo, /abs, has a slash) is used as-is;
+                           - @stock/<slug> resolves to the packaged shelf that
+                             ships with rcf-lite (recommended long form);
+                           - a bare kebab slug (deploy-cloudflare-workers,
+                             application-spa) resolves to the same shelf;
+                           - any other @<library>/<slug> is reserved for the
+                             phase-2 external-libraries mechanism and refuses.
+                         Writes an entry to manifest.blueprints[] and copies
+                         namespaced contributions into the tree.
   list                   List every applied blueprint (slug, version,
-                         appliedAt, contributionCount).
+                         appliedAt, contributionCount), grouped by the
+                         \`category\` declared on each blueprint's own
+                         \`blueprint.json\`. Blueprints whose source no
+                         longer resolves, or whose source declares no
+                         category, appear under \`uncategorised\`.
   remove <slug>          Remove an applied blueprint. Refuses when any
                          project-authored doc references a contribution
                          id; prints the referring docs and exits 3.
@@ -142,7 +155,22 @@ export async function main(argv, deps = {}) {
       stderr.write('[error] blueprint add: missing <source>\n');
       return 2;
     }
-    const source = rest[0];
+    const rawSource = rest[0];
+    const resolved = await resolveBlueprintSource(rawSource);
+    if (isRcfError(resolved)) {
+      if (parsed.values.json) {
+        stderr.write(`${JSON.stringify({ refused: true, error: { kind: resolved.kind, message: resolved.message } })}\n`);
+      } else {
+        stderr.write(`[error] blueprint add: ${resolved.message}\n`);
+      }
+      return 2;
+    }
+    // Feed the resolved absolute path to the applier; keep the original
+    // typed source on the CLI for the supersede hint the conflict
+    // renderer prints, so the operator sees exactly the string they can
+    // copy back into a fresh shell.
+    const source = resolved.resolved;
+    const displaySource = resolved.original;
     const resolveDeclarations = parseResolveOptions(parsed.values.resolve, parsed.values.reason);
     if (resolveDeclarations.error) {
       stderr.write(`[error] blueprint add: ${resolveDeclarations.error}\n`);
@@ -150,6 +178,7 @@ export async function main(argv, deps = {}) {
     }
     const result = await applyBlueprint({
       projectRoot, tree, source,
+      displaySource,
       namespaceOverride: parsed.values.namespace,
       resolveDeclarations: resolveDeclarations.value,
       now,
@@ -211,8 +240,23 @@ export async function main(argv, deps = {}) {
       if (!parsed.values.quiet) stdout.write('[blueprint] no blueprints applied on this project.\n');
       return 0;
     }
-    for (const row of rows) {
-      stdout.write(`${row.slug}\t${row.version}\t${row.appliedAt}\t${row.contributionCount} contribution(s)\n`);
+    // Enrich with category from each applied blueprint's source. The
+    // manifest schema does not carry category (additionalProperties:
+    // false on appliedBlueprintRecord), so the enricher re-loads each
+    // source's blueprint.json at list time; a source that no longer
+    // resolves surfaces under the `uncategorised` group rather than
+    // being dropped.
+    const enriched = await enrichRowsWithCategories(rows);
+    const groups = groupRowsByCategory(enriched);
+    let first = true;
+    for (const group of groups) {
+      const label = group.category ?? 'uncategorised';
+      if (!first) stdout.write('\n');
+      first = false;
+      stdout.write(`# ${label}\n`);
+      for (const row of group.rows) {
+        stdout.write(`${row.slug}\t${row.version}\t${row.appliedAt}\t${row.contributionCount} contribution(s)\n`);
+      }
     }
     return 0;
   }

package/src/cli/init.js

@@ -219,6 +219,8 @@ export async function main(argv, deps = {}) {
     stdout.write(`  Gitignore          ${gitignoreVerbAndTarget(gitignoreResult)}.\n`);
     stdout.write('\nNext: start your agent session in this directory and tell it what you want to build. '
       + 'It elicits the requirements and drives the build from there - you do not fill in the document chain by hand.\n');
+    stdout.write('\nRun `rcf doctor` to confirm the wiring stays clean over time '
+      + '(it also checks whether managed blocks have drifted from the shipped canon).\n');
   }
   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/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.',