rcf-lite 0.12.0 → 0.14.0

package/src/cli/blueprint-library.js

@@ -0,0 +1,419 @@
+// `rcf define blueprint library <verb>` CLI.
+//
+// Verbs (Phase 2b):
+//   add      register an external library on this project (local source in
+//            2b; network fetchers land in 2c)
+//   list     list registered libraries
+//   remove   unregister a library (refuses when any applied blueprint on
+//            the project came through the library)
+//   refresh  re-validate an already-registered library's on-disk shape
+//
+// Spec: external-blueprint-libraries-spec-2026-08-31.md sections 4, 8.
+
+import { isAbsolute, resolve } from 'node:path';
+import { stat } from 'node:fs/promises';
+import { createInterface } from 'node:readline';
+
+import { isRcfError } from '#core/errors';
+import { findProjectRoot } from '../view/index.js';
+import { loadLibrary } from '../blueprint/library-loader.js';
+import {
+  detectBandOverlap,
+  detectPrefixCollision,
+  findLibrary,
+  loadCoreBandReservations,
+  readLibraryRegistry,
+  writeLibraryRegistry,
+} from '../blueprint/library-registry.js';
+import { knownShelfSlugs, packagedShelfPath } from '../blueprint/shelf-resolver.js';
+import { walkTree } from '#core/store';
+
+/**
+ * Union of core-shelf blueprint slugs used for the prefix-collision
+ * gate. The packaged-shelf directory is copied into the tarball at
+ * prepack time (`files: ['blueprints']`), so a source checkout does
+ * not have `packages/rcf-lite/blueprints/` on disk; falling back to
+ * the shipped `data/core-band-reservations.json` keeps the gate
+ * effective in both shapes.
+ */
+async function collectCoreSlugs() {
+  const fromShelf = await knownShelfSlugs(packagedShelfPath()).catch(() => []);
+  const reservations = await loadCoreBandReservations();
+  const slugs = new Set(fromShelf);
+  for (const row of reservations.ac ?? []) if (row.blueprint) slugs.add(row.blueprint);
+  for (const row of reservations.suffixBlocks ?? []) if (row.blueprint) slugs.add(row.blueprint);
+  return [...slugs];
+}
+
+export const LIBRARY_HELP = `Usage: rcf define blueprint library <verb> [options]
+
+Verbs:
+  add <ref>            Register an external library on this project.
+                       <ref> is either a local absolute or relative path
+                       to a library root (a directory containing
+                       library.json). Fetches metadata, runs review-on-
+                       add, and writes an entry to
+                       rcf/blueprint-libraries.json.
+
+                       Phase 2b covers local sources; the git and
+                       tarball fetchers land in Phase 2c. A private-repo
+                       library today is registered via a local clone.
+
+  list [--json]        List every registered library on this project
+                       (prefix, source, publisher, blueprint count).
+
+  remove <prefix>      Unregister a library. Refuses when any applied
+                       blueprint on the project came through this
+                       library.
+
+  refresh <prefix>     Re-validate an already-registered library's
+                       on-disk shape. Phase 2b re-reads the local
+                       library.json and reports any drift from the
+                       registry snapshot; phase 2c will re-fetch a git
+                       or tarball source and verify the sha.
+
+Options:
+  --prefix <slug>      (add) Override the library's declared prefix.
+                       Rarely needed; only useful when two libraries
+                       collide on prefix locally.
+  --i-have-reviewed    (add) Skip the interactive review-on-add prompt.
+                       Required companion to --no-review when scripting;
+                       the two-flag form keeps a library-add trust
+                       decision loud (spec §9.7).
+  --no-review          (add) Bypass the interactive prompt. Requires
+                       --i-have-reviewed.
+  --json               (add, list) Emit machine-readable JSON.
+  --dry-run            Print intended writes without executing.
+  --quiet              Suppress non-error stdout.
+  --help               Print this help.
+`;
+
+const LIBRARY_OPTION_SPEC = {
+  prefix: { type: 'string' },
+  'i-have-reviewed': { type: 'boolean' },
+  'no-review': { type: 'boolean' },
+  json: { type: 'boolean' },
+  'dry-run': { type: 'boolean' },
+  quiet: { type: 'boolean' },
+  help: { type: 'boolean' },
+};
+
+/**
+ * Handle `rcf define blueprint library <verb>`.
+ *
+ * @param {import('node:util').ParseArgsConfig} parsed - already-parsed argv (see cli/blueprint.js)
+ * @param {string[]} rest - positional args after `library`
+ * @param {object} deps
+ * @returns {Promise<number>}
+ */
+export async function handleLibraryVerb(parsed, rest, deps) {
+  const stdout = deps.stdout;
+  const stderr = deps.stderr;
+  const cwd = deps.cwd;
+  const now = deps.now ?? new Date();
+  const stdin = deps.stdin ?? process.stdin;
+
+  if (parsed.values.help || rest.length === 0) {
+    stdout.write(LIBRARY_HELP);
+    return 0;
+  }
+  const verb = rest[0];
+  const args = rest.slice(1);
+
+  const projectRoot = await findProjectRoot(cwd);
+  if (!projectRoot) {
+    stderr.write('[error] no rcf/ tree found in this directory or any ancestor.\n');
+    return 2;
+  }
+
+  if (verb === 'add') return handleAdd({ args, parsed, projectRoot, now, stdout, stderr, stdin });
+  if (verb === 'list') return handleList({ parsed, projectRoot, stdout, stderr });
+  if (verb === 'remove') return handleRemove({ args, parsed, projectRoot, stdout, stderr });
+  if (verb === 'refresh') return handleRefresh({ args, parsed, projectRoot, stdout, stderr });
+
+  stderr.write(`[error] blueprint library: unknown verb '${verb}'\n`);
+  stderr.write(LIBRARY_HELP);
+  return 2;
+}
+
+async function handleAdd({ args, parsed, projectRoot, now, stdout, stderr, stdin }) {
+  if (args.length === 0) {
+    stderr.write('[error] blueprint library add: missing <ref>\n');
+    return 2;
+  }
+  const ref = args[0];
+
+  // Phase 2b: local sources only. Fetchers land in 2c.
+  const kind = classifySourceRef(ref);
+  if (kind !== 'local') {
+    stderr.write(
+      `[error] blueprint library add: source kind '${kind}' requires the network fetchers landing in Phase 2c. `
+      + 'In 2b, register the library from a local path (a directory carrying library.json). '
+      + 'For private git repos today, clone the repo locally and point add at the clone.\n',
+    );
+    return 2;
+  }
+
+  const localRoot = isAbsolute(ref) ? ref : resolve(projectRoot, ref);
+  let libStat;
+  try {
+    libStat = await stat(localRoot);
+  } catch (err) {
+    stderr.write(`[error] blueprint library add: path '${localRoot}' cannot be read: ${err.message}\n`);
+    return 2;
+  }
+  if (!libStat.isDirectory()) {
+    stderr.write(`[error] blueprint library add: path '${localRoot}' is not a directory.\n`);
+    return 2;
+  }
+
+  const library = await loadLibrary(localRoot, { validateBlueprints: true });
+  if (isRcfError(library)) {
+    stderr.write(`[error] blueprint library add: ${library.message}\n`);
+    return 2;
+  }
+
+  const libraryPrefix = typeof parsed.values.prefix === 'string' && parsed.values.prefix.length > 0
+    ? parsed.values.prefix
+    : library.libraryPrefix;
+
+  const registry = await readLibraryRegistry(projectRoot);
+  if (isRcfError(registry)) {
+    stderr.write(`[error] blueprint library add: ${registry.message}\n`);
+    return 2;
+  }
+  if (findLibrary(registry, libraryPrefix)) {
+    stderr.write(`[error] blueprint library add: libraryPrefix '${libraryPrefix}' is already registered on this project. Use 'library refresh' or 'library remove' first.\n`);
+    return 2;
+  }
+  const coreSlugs = await collectCoreSlugs();
+  const prefixErr = detectPrefixCollision({ libraryPrefix, registry, coreSlugs });
+  if (prefixErr) {
+    stderr.write(`[error] blueprint library add: ${prefixErr.message}\n`);
+    return 2;
+  }
+  const coreReservations = await loadCoreBandReservations();
+  const bandErr = detectBandOverlap({
+    candidate: { libraryPrefix, bands: library.bands },
+    registry,
+    coreReservations,
+  });
+  if (bandErr) {
+    stderr.write(`[error] blueprint library add: ${bandErr.message}\n`);
+    return 2;
+  }
+
+  const wantsReview = parsed.values['no-review'] !== true;
+  const iHaveReviewed = parsed.values['i-have-reviewed'] === true;
+  if (parsed.values['no-review'] === true && !iHaveReviewed) {
+    stderr.write('[error] blueprint library add: --no-review requires --i-have-reviewed (spec §9.7: the two-flag form keeps the trust decision loud).\n');
+    return 2;
+  }
+  if (wantsReview) {
+    printReview({ stdout, ref, library, libraryPrefix, coreReservations });
+    if (!iHaveReviewed) {
+      const proceed = await prompt(stdin, stdout, 'Proceed with add? [y/N] ');
+      if (!/^y(es)?$/i.test((proceed ?? '').trim())) {
+        stdout.write('[blueprint library] aborted by operator; no registry entry written.\n');
+        return 0;
+      }
+    }
+  }
+
+  const entry = {
+    libraryPrefix,
+    sourceKind: 'local',
+    sourceRef: localRoot,
+    displayName: library.displayName,
+    publisher: { ...library.publisher },
+    libraryRef: library.libraryRef,
+    bands: library.bands,
+    blueprints: library.blueprints.map((b) => ({ slug: b.slug, path: b.path })),
+    addedAt: now.toISOString(),
+    reviewedBy: 'operator',
+    provenance: { tier: 'local' },
+    cachePath: localRoot,
+  };
+
+  const nextRegistry = {
+    registryVersion: registry.registryVersion,
+    libraries: [...registry.libraries, entry],
+  };
+  const write = await writeLibraryRegistry(projectRoot, nextRegistry, { dryRun: parsed.values['dry-run'] === true });
+  if (isRcfError(write)) {
+    stderr.write(`[error] blueprint library add: ${write.message}\n`);
+    return 2;
+  }
+  if (parsed.values.json) {
+    stdout.write(`${JSON.stringify({
+      added: !parsed.values['dry-run'],
+      dryRun: parsed.values['dry-run'] === true,
+      libraryPrefix: entry.libraryPrefix,
+      blueprintCount: entry.blueprints.length,
+      registryPath: write.path,
+    })}\n`);
+    return 0;
+  }
+  if (!parsed.values.quiet) {
+    if (parsed.values['dry-run']) {
+      stdout.write(`[blueprint library] dry-run: would add '${libraryPrefix}' (${entry.blueprints.length} blueprint(s)) to ${write.path}.\n`);
+    } else {
+      stdout.write(`[blueprint library] added '${libraryPrefix}' (${entry.blueprints.length} blueprint(s)) to ${write.path}.\n`);
+    }
+  }
+  return 0;
+}
+
+async function handleList({ parsed, projectRoot, stdout, stderr }) {
+  const registry = await readLibraryRegistry(projectRoot);
+  if (isRcfError(registry)) {
+    stderr.write(`[error] blueprint library list: ${registry.message}\n`);
+    return 2;
+  }
+  if (parsed.values.json) {
+    stdout.write(`${JSON.stringify({
+      registryVersion: registry.registryVersion,
+      libraries: registry.libraries.map((l) => ({
+        libraryPrefix: l.libraryPrefix,
+        sourceKind: l.sourceKind,
+        sourceRef: l.sourceRef,
+        publisher: l.publisher,
+        libraryRef: l.libraryRef,
+        blueprintCount: Array.isArray(l.blueprints) ? l.blueprints.length : 0,
+        addedAt: l.addedAt,
+      })),
+    }, null, 2)}\n`);
+    return 0;
+  }
+  if (registry.libraries.length === 0) {
+    if (!parsed.values.quiet) stdout.write('[blueprint library] no libraries registered on this project.\n');
+    return 0;
+  }
+  for (const l of registry.libraries) {
+    const count = Array.isArray(l.blueprints) ? l.blueprints.length : 0;
+    stdout.write(`${l.libraryPrefix}\t${l.sourceKind}\t${l.publisher.displayName}\t${count} blueprint(s)\t${l.sourceRef}\n`);
+  }
+  return 0;
+}
+
+async function handleRemove({ args, parsed, projectRoot, stdout, stderr }) {
+  if (args.length === 0) {
+    stderr.write('[error] blueprint library remove: missing <libraryPrefix>\n');
+    return 2;
+  }
+  const libraryPrefix = args[0];
+  const registry = await readLibraryRegistry(projectRoot);
+  if (isRcfError(registry)) {
+    stderr.write(`[error] blueprint library remove: ${registry.message}\n`);
+    return 2;
+  }
+  const entry = findLibrary(registry, libraryPrefix);
+  if (!entry) {
+    stderr.write(`[error] blueprint library remove: library '${libraryPrefix}' is not registered.\n`);
+    return 2;
+  }
+  // Refuse when any applied blueprint on the project came through the
+  // library. Signal: `manifest.blueprints[].source` starts with `<prefix>:`.
+  const { tree, errors } = await walkTree({ projectRoot });
+  if (errors.length > 0) {
+    for (const e of errors) stderr.write(`[tree] ${e.kind}: ${e.message}\n`);
+    return 2;
+  }
+  const referring = (tree.manifest?.blueprints ?? []).filter((b) => typeof b.source === 'string' && b.source.startsWith(`${libraryPrefix}:`));
+  if (referring.length > 0) {
+    stderr.write(`[error] blueprint library remove: ${referring.length} applied blueprint(s) came through '${libraryPrefix}':\n`);
+    for (const r of referring) stderr.write(`  ${r.slug} <- ${r.source}\n`);
+    stderr.write('remove those first (rcf define blueprint remove <slug>) or explicitly force with an escalation flag (not in v1).\n');
+    return 3;
+  }
+  const nextRegistry = {
+    registryVersion: registry.registryVersion,
+    libraries: registry.libraries.filter((l) => l.libraryPrefix !== libraryPrefix),
+  };
+  const write = await writeLibraryRegistry(projectRoot, nextRegistry, { dryRun: parsed.values['dry-run'] === true });
+  if (isRcfError(write)) {
+    stderr.write(`[error] blueprint library remove: ${write.message}\n`);
+    return 2;
+  }
+  if (!parsed.values.quiet) {
+    stdout.write(`[blueprint library] removed '${libraryPrefix}' from ${write.path}.\n`);
+  }
+  return 0;
+}
+
+async function handleRefresh({ args, parsed, projectRoot, stdout, stderr }) {
+  if (args.length === 0) {
+    stderr.write('[error] blueprint library refresh: missing <libraryPrefix>\n');
+    return 2;
+  }
+  const libraryPrefix = args[0];
+  const registry = await readLibraryRegistry(projectRoot);
+  if (isRcfError(registry)) {
+    stderr.write(`[error] blueprint library refresh: ${registry.message}\n`);
+    return 2;
+  }
+  const entry = findLibrary(registry, libraryPrefix);
+  if (!entry) {
+    stderr.write(`[error] blueprint library refresh: library '${libraryPrefix}' is not registered.\n`);
+    return 2;
+  }
+  if (entry.sourceKind !== 'local') {
+    stderr.write(`[error] blueprint library refresh: source kind '${entry.sourceKind}' requires the network fetchers landing in Phase 2c.\n`);
+    return 2;
+  }
+  const library = await loadLibrary(entry.cachePath, { validateBlueprints: true });
+  if (isRcfError(library)) {
+    stderr.write(`[error] blueprint library refresh: ${library.message}\n`);
+    return 2;
+  }
+  // Detect drift from the registry snapshot on load-bearing fields.
+  const drifted = [];
+  if (library.libraryPrefix !== entry.libraryPrefix) drifted.push(`libraryPrefix '${entry.libraryPrefix}' -> '${library.libraryPrefix}'`);
+  if (library.libraryRef !== entry.libraryRef) drifted.push(`libraryRef '${entry.libraryRef}' -> '${library.libraryRef}'`);
+  if (JSON.stringify(library.bands) !== JSON.stringify(entry.bands)) drifted.push('bands changed');
+  if (drifted.length > 0) {
+    stderr.write(`[blueprint library refresh] '${libraryPrefix}' has drifted from the registered snapshot:\n`);
+    for (const d of drifted) stderr.write(`  ${d}\n`);
+    stderr.write("re-run 'rcf define blueprint library add <ref>' to pick up the newer library (spec §10.1: freshness is advisory, adoption is an operator act).\n");
+    return 3;
+  }
+  if (!parsed.values.quiet) {
+    stdout.write(`[blueprint library] '${libraryPrefix}' refresh clean: on-disk library matches the registry snapshot.\n`);
+  }
+  return 0;
+}
+
+function classifySourceRef(ref) {
+  if (ref.startsWith('git+') || ref.startsWith('git@') || ref.startsWith('https://') || ref.startsWith('http://') || ref.startsWith('ssh://')) return 'git';
+  if (ref.endsWith('.tar.gz') || ref.endsWith('.tgz') || ref.endsWith('.tar')) return 'tarball';
+  return 'local';
+}
+
+function printReview({ stdout, ref, library, libraryPrefix, coreReservations }) {
+  const suffix = (library.bands.suffixBlocks ?? []).map((b) => `${b.kind} ${b.start}-${b.end}`).join(', ');
+  stdout.write(`\nREVIEW - you are about to add this library to the project registry.\n\n`);
+  stdout.write(`  Library      : ${library.displayName}\n`);
+  stdout.write(`  Prefix       : ${libraryPrefix}\n`);
+  stdout.write(`  Publisher    : ${library.publisher.displayName}${library.publisher.contact ? ` <${library.publisher.contact}>` : ''}\n`);
+  stdout.write(`  Source       : ${ref} (local)\n`);
+  stdout.write(`  Library ref  : ${library.libraryRef}\n`);
+  stdout.write(`  AC band      : ${library.bands.ac.start} - ${library.bands.ac.end}\n`);
+  if (suffix.length > 0) stdout.write(`  Suffix blocks: ${suffix}\n`);
+  stdout.write(`\n  Blueprints on this library:\n`);
+  for (const bp of library.blueprints) {
+    stdout.write(`    ${libraryPrefix}:${bp.slug}\n`);
+  }
+  stdout.write(`\n  Provenance   : local (dev use)\n`);
+  stdout.write(`  Band check   : cross-checked ${coreReservations.ac.length} core AC row(s), ${coreReservations.suffixBlocks.length} core suffix block(s); no overlap.\n`);
+  stdout.write(`\n`);
+}
+
+async function prompt(stdin, stdout, question) {
+  return new Promise((resolveP) => {
+    const rl = createInterface({ input: stdin, output: stdout });
+    rl.question(question, (answer) => {
+      rl.close();
+      resolveP(answer);
+    });
+  });
+}

package/src/cli/blueprint.js

@@ -16,23 +16,37 @@ 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';
+import { handleLibraryVerb, LIBRARY_HELP } from './blueprint-library.js';
 
 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.
@@ -52,6 +66,11 @@ Verbs:
   diff <topic>           Side-by-side view of every applied blueprint's
                          scope:global ADR on <topic>: id, path, title,
                          status, decision. Read-only.
+  library <verb>         Manage external blueprint libraries. Sub-verbs:
+                         add, list, remove, refresh. See
+                         'rcf define blueprint library --help' for the
+                         full surface. Phase 2b covers local sources;
+                         network fetchers land in Phase 2c.
 
 Options:
   --namespace <slug>     Override the blueprint's default namespace
@@ -93,6 +112,11 @@ const OPTION_SPEC = {
   resolve: { type: 'string', multiple: true },
   reason: { type: 'string' },
   incoming: { type: 'string' },
+  // library-verb flags (parsed centrally so strict:true doesn't refuse
+  // them when the operator types `rcf define blueprint library add`).
+  prefix: { type: 'string' },
+  'i-have-reviewed': { type: 'boolean' },
+  'no-review': { type: 'boolean' },
   json: { type: 'boolean' },
   'dry-run': { type: 'boolean' },
   quiet: { type: 'boolean' },
@@ -118,13 +142,25 @@ export async function main(argv, deps = {}) {
     stderr.write(HELP);
     return 2;
   }
-  if (parsed.values.help || parsed.positionals.length === 0) {
+  const firstPositional = parsed.positionals[0];
+  // `rcf define blueprint library --help` routes into the library
+  // handler so the sub-verb HELP block is what the operator sees.
+  // Every other --help (and empty argv) prints the top-level HELP.
+  if (firstPositional !== 'library' && (parsed.values.help || parsed.positionals.length === 0)) {
     stdout.write(HELP);
     return 0;
   }
   const verb = parsed.positionals[0];
   const rest = parsed.positionals.slice(1);
 
+  // `library` sub-verbs manage the external-library registry; they
+  // never walk the RCF tree, and delegating early keeps the option
+  // parser from consuming `--i-have-reviewed` (a library-add-only flag)
+  // against a `library` add invocation.
+  if (verb === 'library') {
+    return handleLibraryVerb(parsed, rest, { stdout, stderr, cwd, now, stdin: deps.stdin });
+  }
+
   const projectRoot = await findProjectRoot(cwd);
   if (!projectRoot) {
     stderr.write('[error] no rcf/ tree found in this directory or any ancestor.\n');
@@ -142,7 +178,27 @@ 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, { projectRoot });
+    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. The original
+    // typed source is preserved on the CLI for the conflict renderer's
+    // supersede hint (so the operator sees exactly the string they can
+    // copy back into a fresh shell). It is ONLY forwarded to the applier
+    // as `displaySource` for library-qualified resolves - spec §5.3
+    // requires the qualified typed ref (`wsd:auth-oauth2`) to be the
+    // record's `source`. For shelf and path resolves the record must
+    // carry the RESOLVED ABSOLUTE PATH, which is the pre-#120 behaviour
+    // that /scope.json and `blueprint list --category` both depend on
+    // to load the shipping source file (integration review d-2026-08-31-046).
+    const source = resolved.resolved;
     const resolveDeclarations = parseResolveOptions(parsed.values.resolve, parsed.values.reason);
     if (resolveDeclarations.error) {
       stderr.write(`[error] blueprint add: ${resolveDeclarations.error}\n`);
@@ -151,6 +207,16 @@ export async function main(argv, deps = {}) {
     const result = await applyBlueprint({
       projectRoot, tree, source,
       namespaceOverride: parsed.values.namespace,
+      // Library-qualified resolves rewire the applied identity under
+      // the library prefix and forward the library's declared bands
+      // for the apply-time gate (spec §5.3, §8.3). The qualified typed
+      // ref is passed as `displaySource` so the applied record's
+      // `source` field carries it verbatim (spec §5.3).
+      ...(resolved.kind === 'library' ? {
+        displaySource: resolved.original,
+        effectiveSlug: resolved.effectiveSlug,
+        libraryBands: resolved.libraryBands,
+      } : {}),
       resolveDeclarations: resolveDeclarations.value,
       now,
       dryRun: parsed.values['dry-run'] === true,
@@ -211,8 +277,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, { projectRoot });
+    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/guidance.js

@@ -34,7 +34,7 @@ const OPTION_SPEC = {
 
 export const HELP = `Usage: rcf guidance [topic] [options]
 
-Print a guidance-pack document from the installed rcf-build-lite
+Print a guidance-pack document from the installed rcf-lite
 package to stdout. The pack ships with the package and is never copied
 into your project, so this verb is how a CLI-only agent reads the
 method. MCP-wired harnesses can use the rcf://docs/<slug> resources and

package/src/cli/help.js

@@ -36,6 +36,7 @@ import { HELP as DESIGN_HELP } from './design.js';
 import { HELP as BROWSER_VERIFY_HELP } from './browser-verify.js';
 import { HELP as UPDATE_HELP } from './update.js';
 import { HELP as VALIDATE_HELP } from './validate.js';
+import { HELP as VERSION_HELP } from './version.js';
 import { HELP as VIEW_HELP } from './view.js';
 import { HELP as REQ_CLASSIFY_HELP } from './req-classify.js';
 import { HELP as REQ_BASELINE_HELP } from './req-baseline.js';
@@ -64,6 +65,8 @@ core         Platform plumbing that predates any RCF stage.
   doctor                   Diagnose and repair init-hygiene drift.
   guidance [topic]         Print a method document from the installed pack.
   mcp                      Serve the project over MCP (local stdio).
+  version [--check]        Print installed version; --check compares
+                           against the release feed.
   help [group] [verb]      Print help for a group or a verb.
 
 discover     Learn what is already true for this project.
@@ -126,6 +129,24 @@ Run 'rcf help <group>' for group help; 'rcf help <group> <verb>' for
 per-verb help.
 `;
 
+const CORE_GROUP_HELP = `Usage: rcf <core-verb> [options]
+
+Platform plumbing that predates any RCF stage. Core verbs dispatch at
+the top level (they are invoked as \`rcf <verb>\`, not \`rcf core <verb>\`);
+this group is a documentation grouping for \`rcf help\`.
+
+Verbs:
+  init                     Scaffold a new RCF project in this directory.
+  doctor                   Diagnose and repair init-hygiene drift.
+  guidance [topic]         Print a method document from the installed pack.
+  mcp                      Serve the project over MCP (local stdio).
+  version [--check]        Print installed version; --check compares
+                           against the release feed.
+  help [group] [verb]      Print help for a group or a verb.
+
+Run 'rcf help <verb>' for per-verb help.
+`;
+
 const DISCOVER_HELP = `Usage: rcf discover <verb> [options]
 
 Learn what is already true for this project: classify supplied
@@ -223,6 +244,7 @@ Run 'rcf help audit <verb>' for per-verb help.
 `;
 
 export const GROUP_HELP = {
+  core: CORE_GROUP_HELP,
   discover: DISCOVER_HELP,
   define: DEFINE_HELP,
   build: BUILD_GROUP_HELP,
@@ -286,6 +308,7 @@ export const CORE_HELP = {
   doctor: DOCTOR_HELP,
   guidance: GUIDANCE_HELP,
   mcp: MCP_HELP,
+  version: VERSION_HELP,
 };
 
 /**
@@ -319,7 +342,10 @@ export async function main(argv, deps = {}) {
       stdout.write(GROUP_HELP[first]);
       return 0;
     }
-    const body = HELP_MAP[first][verb];
+    // `core` is a documentation grouping - core verbs dispatch at the
+    // top level, so `rcf help core <verb>` delegates to the same
+    // per-verb block that `rcf help <verb>` prints.
+    const body = first === 'core' ? CORE_HELP[verb] : HELP_MAP[first][verb];
     if (!body) {
       stderr.write(`[error] usage no help topic '${first} ${verb}'\n`);
       stdout.write(GROUP_HELP[first]);

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;
 }