rcf-lite 0.20.0 → 0.21.0

package/rcf/user-stories/us-2301.json

@@ -0,0 +1,51 @@
+{
+  "createdAt": "2026-09-05T01:30:00.000Z",
+  "updatedAt": "2026-09-05T01:30:00.000Z",
+  "usId": "US-2301",
+  "prdId": "PRD-001",
+  "reqId": "REQ-023",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "The application-admin-console blueprint ships on the shelf; its probe pack fires only on applied capabilities and refuses on a broken admin surface",
+  "asA": "shelf consumer applying the application-admin-console v1.0.0 blueprint",
+  "iWant": "the shipped blueprint files with a users, roles, orgs, audit-log surface set that self-configures from the applied capability declarations, the Playwright probe pack whose four checks each gate their fire on the applied capability, and a sample-app fixture proving the pack passes on a compliant surface, records applicable: false where the capability is absent, and refuses on the three break switches",
+  "soThat": "a project consuming rcf-lite gets a vendor-neutral admin console conditional on what identity blueprint is applied, no dead links to unapplied capabilities, the pack that proves the ARIA APG grid pattern on the permission matrix, the request-log ACs on the audit view, and a golden fixture the pack refuses on a surface that loses the grid roles, drops the request-access control, or writes an audit entry missing the correlation id",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-2301-1",
+      "description": "The shelf carries blueprints/application-admin-console/blueprint.json declaring slug application-admin-console, version 1.0.0, category application, 23 contributions in the 6 REQ / 9 US / 4 TAC / 4 ADR groups per spec section 5.5; requiresAppliedCapabilities.capabilities is [principalDirectory] with allowSkipFlag: allow-no-auth-yet; elicits[] declares baselineRoles (when roleModel), tenancyShape (when tenancy), inviteTransport, and auditRetentionDays (when auditLog); suggestedCompanions declares logging and errorHandling with reasons from spec section 5.5; providesRoles is absent per spec 5.5.3.",
+      "testable": true
+    },
+    {
+      "id": "AC-2301-2",
+      "description": "rcf define blueprint add ./blueprints/application-admin-console --allow-no-auth-yet applies the 23 contributions cleanly on a fresh init project with only application-spa applied; rcf define validate reports the tree clean; both rcf audit coverage --strict and rcf audit eval coverage --strict exit 0 on the scratch project; the sidecar rcf/blueprints/application-admin-console.applied.json declares allowNoAuthYet: true and an appliedCapabilities: [] union.",
+      "testable": true
+    },
+    {
+      "id": "AC-2301-3",
+      "description": "rcf define blueprint add ./blueprints/application-admin-console on a project with only application-spa applied exits 3 with a stderr message beginning 'application-admin-console requires at least one applied security-auth-*' and naming the currently-applied blueprints; nothing is written to disk (no contributions, no sidecar, no manifest entry).",
+      "testable": true
+    },
+    {
+      "id": "AC-2301-4",
+      "description": "rcf define blueprint add ./blueprints/application-admin-console on a project with security-auth-magic-link 1.1.0 applied applies cleanly; the sidecar's appliedCapabilities reads exactly [principalDirectory] with no roleModel; rcf define blueprint add on a project with security-auth-clerk 1.2.0 + observability-logging applied produces appliedCapabilities [principalDirectory, roleModel, auditLog] (order-agnostic).",
+      "testable": true
+    },
+    {
+      "id": "AC-2301-5",
+      "description": "The shipped probe pack blueprints/application-admin-console/probe-packs/application-admin-console.pack.mjs loads via T-0's pack-loader against a scratch project with the blueprint applied; each of its four check ids (AC-21102-1, AC-21103-1, AC-21104-1, AC-21105-1) resolves to an AC id contributed by the blueprint per T-0 AC-1701-3; every check carries a description field per spec section 9; each check's appliesTo predicate reads manifest.blueprints[]/${slug}.applied.json capabilities and returns false when the required capability is absent so the check records applicable: false; the pack-level appliesTo predicate references BOTH tacIds and route.",
+      "testable": true
+    },
+    {
+      "id": "AC-2301-6",
+      "description": "The sample-app fixture at packages/rcf-lite/test/fixtures/probe-pack-application-admin-console/ ships a dependency-free Node HTTP server (server.js) with a start script; CAPS env or ?caps= query switch selects which surfaces exist mirroring the applied capability set (principalDirectory, roleModel, tenancy, auditLog, or comma combinations thereof); the console shell nav only links applied surfaces; the users directory table enumerates every row by data-user-id inside the role=table region; the permission matrix renders under role=grid with role=row on every rank, role=rowheader on the leftmost cell of each role rank, role=columnheader on every permission header, role=gridcell on inner cells, and each cell announces the exact permission string on focus via aria-label; the org switcher is present only when tenancy is applied; the audit-log table enumerates every row by data-audit-id and every audit entry carries actor, target, before, after, timestamp, and correlationId in inspectable columns; an access-denied route renders a request-access control routed to a POST /api/request-access endpoint; window.__adminFetches and /__requests mirror every request.",
+      "testable": true
+    },
+    {
+      "id": "AC-2301-7",
+      "description": "The probe pack refuses ship on each broken fixture: with ?break=matrix-grid the permission matrix drops the role=grid attributes so AC-21103-1 fails at severity block; with ?break=denied the access-denied route drops the request-access control so AC-21102-1's negative branch (a principal without admin scope) fails at severity block; with ?break=audit-fields the audit entries omit the correlationId column so AC-21105-1 fails at severity block."
+      ,
+      "testable": true
+    }
+  ]
+}

package/releases/releases.yaml

@@ -40,8 +40,18 @@
 # `npm install rcf-lite`.
 
 feedVersion: 1
-latest: "0.20.0"
+latest: "0.21.0"
 releases:
+  - version: "0.21.0"
+    date: "2026-09-05"
+    breaking: false
+    headlines:
+      - "rcf-lite 0.21.0 adds five visual-feature blueprints to the shelf (data table, charts, dashboard with packaged design guidance, in-app notifications, admin console) and the mechanism that proves them: a blueprint can now ship a Playwright probe pack that rcf verify runs against your running app in a real browser, and the ship gate refuses while a surface check fails."
+      - "The admin console only offers the surfaces your applied auth blueprint can support. Blueprints can now ask you questions at apply time."
+      - "The schema floor moves to rcf-schemas 0.6.1."
+    minAgentAction: null
+    notesUrl: "https://stravica.ai/docs/rcf/changelog/"
+
   - version: "0.20.0"
     date: "2026-09-04"
     breaking: true

package/src/blueprint/apply.js

@@ -20,6 +20,7 @@ import { loadBlueprint } from './loader.js';
 import { updateManifest } from './manifest-writer.js';
 import { stampId } from './namespace.js';
 import { nextResolutionId } from './resolutions.js';
+import { buildRefusalMessage, discoverAppliedCapabilities, runCustomAuthCapabilityElicits, runElicitationPhase, writeSidecar } from './capabilities.js';
 
 /**
  * @typedef {object} ApplyResult
@@ -79,7 +80,7 @@ import { nextResolutionId } from './resolutions.js';
  *        prove the rollback runs. Never used in production.
  * @returns {Promise<ApplyResult | import('../core/errors/index.js').RcfError>}
  */
-export async function applyBlueprint({ projectRoot, tree, source, displaySource, namespaceOverride, effectiveSlug, libraryPrefix, libraryBands, resolveDeclarations, now = new Date(), dryRun = false, _copyFileForTest }) {
+export async function applyBlueprint({ projectRoot, tree, source, displaySource, namespaceOverride, effectiveSlug, libraryPrefix, libraryBands, resolveDeclarations, allowNoAuthYet = false, elicitAnswers = null, customAuthReadLine = null, now = new Date(), dryRun = false, _copyFileForTest }) {
   const hintSource = typeof displaySource === 'string' && displaySource.length > 0 ? displaySource : source;
   const blueprint = await loadBlueprint(source);
   if (blueprint.kind) return blueprint; // RcfError
@@ -105,6 +106,69 @@ export async function applyBlueprint({ projectRoot, tree, source, displaySource,
     if (bandErr) return bandErr;
   }
 
+  // Capability-declaration mechanism (visual round T-5 spec 5.5).
+  // Discover the union of applied capabilities across every applied
+  // blueprint via source read-back; the applied-blueprint-record
+  // schema is closed (rcf-schemas 0.6.0) and does not carry a
+  // capabilities field, so the source blueprint.json is the ground
+  // truth for what each applied blueprint declares.
+  const discovery = await discoverAppliedCapabilities(applied, projectRoot);
+  const discoveredCapabilities = discovery.union;
+
+  // Custom-auth capability elicitation (visual round T-5 spec 5.5
+  // "Risks": custom auth elicits per capability). Fires BEFORE the
+  // requiresAppliedCapabilities refusal gate: providesCapability
+  // elicits let a project with no shelf auth blueprint declare which
+  // capabilities its own custom auth carries. Truthy answers fold
+  // into the effective applied set; that set is what the refusal gate
+  // and the standard elicitation phase see.
+  const customAuth = await runCustomAuthCapabilityElicits({
+    elicits: blueprint.elicits,
+    answers: elicitAnswers ?? {},
+    readLine: customAuthReadLine ?? undefined,
+  });
+  if (customAuth.kind) return customAuth; // RcfError
+  const appliedCapabilities = [...new Set([...discoveredCapabilities, ...customAuth.capsProvided])].sort();
+  const customAuthElicitations = customAuth.answered;
+
+  // Refusal gate for consumer blueprints that require at least one
+  // applied capability. When the effective set has no overlap AND
+  // the CLI did not pass the allow-skip flag AND no custom-auth
+  // capability answers were supplied that satisfy the gate, refuse
+  // with the templated message (spec 5.5.1 verbatim for admin-console).
+  if (blueprint.requiresAppliedCapabilities && !allowNoAuthYet) {
+    const required = blueprint.requiresAppliedCapabilities.capabilities;
+    const overlap = required.some((c) => appliedCapabilities.includes(c));
+    if (!overlap) {
+      const message = buildRefusalMessage({
+        slug: appliedSlug,
+        refusalMessageId: blueprint.requiresAppliedCapabilities.refusalMessageId,
+        requiredCapabilities: required,
+        appliedRecords: applied,
+        allowSkipFlag: blueprint.requiresAppliedCapabilities.allowSkipFlag,
+      });
+      return rcfError({ kind: 'requiresAppliedCapabilities', message });
+    }
+  }
+
+  // Elicitation phase (visual round T-5 spec section 5.5, T-2 gate).
+  // Evaluate each declared elicit against the effective capability set
+  // (union of applied blueprints and custom-auth answers). Skip
+  // providesCapability entries: those were resolved above and their
+  // answers already landed in customAuthElicitations. Coerce operator
+  // answers per kind. A missing required answer refuses before any
+  // write.
+  const regularElicits = Array.isArray(blueprint.elicits)
+    ? blueprint.elicits.filter((e) => typeof e.providesCapability !== 'string')
+    : [];
+  const elicitResult = runElicitationPhase({
+    elicits: regularElicits,
+    appliedCapabilities,
+    answers: elicitAnswers ?? {},
+  });
+  if (elicitResult.kind) return elicitResult; // RcfError
+  const appliedElicitations = { ...customAuthElicitations, ...elicitResult.value };
+
   // Pre-detection: fold operator-supplied --resolve declarations into a
   // WORKING COPY of the manifest so the detector honours them on this
   // run. The final manifest write later composes the same resolution
@@ -302,11 +366,44 @@ export async function applyBlueprint({ projectRoot, tree, source, displaySource,
   });
   if (manifestResult.kind) return manifestResult; // RcfError
 
+  // Sidecar write for the capability-declaration mechanism (visual
+  // round T-5 spec 5.5.1). Per-project apply-state that the applied-
+  // blueprint-record schema cannot carry today: the discovered
+  // appliedCapabilities snapshot, the elicit answers, and (when the
+  // gate was skipped) an allowNoAuthYet flag plus a notes string that
+  // rcf define validate later reads to flag ungated surfaces. The
+  // sidecar is written on ANY apply that carries capabilities-related
+  // data (declared capabilities, requiresAppliedCapabilities gate,
+  // elicits, or an override) so probe packs and audit tooling have
+  // one deterministic file to read. dryRun skips the write.
+  const wroteSidecar = !dryRun && (
+    blueprint.requiresAppliedCapabilities !== undefined ||
+    (Array.isArray(blueprint.elicits) && blueprint.elicits.length > 0) ||
+    Array.isArray(blueprint.capabilities) ||
+    allowNoAuthYet === true
+  );
+  let sidecarPath = null;
+  if (wroteSidecar) {
+    sidecarPath = await writeSidecar({
+      projectRoot,
+      slug: appliedSlug,
+      version: blueprint.version,
+      appliedAt: now.toISOString(),
+      appliedCapabilities,
+      appliedElicitations,
+      allowNoAuthYet: allowNoAuthYet === true ? true : undefined,
+      notes: allowNoAuthYet === true
+        ? `no auth yet: applied under --${blueprint.requiresAppliedCapabilities?.allowSkipFlag ?? 'allow-no-auth-yet'}; surfaces gated on ${(blueprint.requiresAppliedCapabilities?.capabilities ?? []).join(', ')} will refuse at runtime until an auth blueprint is applied.`
+        : undefined,
+    });
+  }
+
   return {
     applied: true,
     slug: appliedSlug,
     version: blueprint.version,
     contributions: writtenContributions,
+    ...(wroteSidecar ? { sidecarPath, appliedCapabilities, appliedElicitations } : {}),
     // Companion-suggestion mechanism (spec 2.6). Bubble the source
     // blueprint's `suggestedCompanions[]` up on the result so the CLI
     // can render the resolved-suggestion block after a successful

package/src/blueprint/capabilities.js

@@ -0,0 +1,318 @@
+// Capability-declaration mechanism (visual round T-5 spec section
+// 5.5.1, 5.5.2). Consumer blueprints gate their surfaces on the union
+// of currently-applied blueprints' `capabilities[]` declarations.
+//
+// Why source read-back. The applied-blueprint-record schema in
+// @stravica-ai/rcf-schemas is closed under additionalProperties:false
+// (0.6.0), so `appliedCapabilities[]` cannot land on the manifest
+// record without a schema bump. Rather than block the round on that
+// dependency, this file adopts the core-companions T-2 gate precedent:
+// read the source blueprint.json via manifest.blueprints[].source and
+// union its declared capabilities[]. Per-project answers (elicits) and
+// a per-project applied-capability snapshot are written to a sidecar
+// file at rcf/blueprints/${slug}.applied.json.
+//
+// This file is imported by apply.js at apply time and by the shipped
+// probe pack (blueprints/application-admin-console/probe-packs/) at
+// verify time.
+
+import { readFile, writeFile, mkdir, stat } from 'node:fs/promises';
+import { dirname, join, resolve, isAbsolute } from 'node:path';
+
+import { rcfError } from '../core/errors/index.js';
+
+/**
+ * Read a single applied blueprint's declared capabilities via
+ * source read-back. Silently ignores an applied blueprint whose
+ * source path no longer exists (the record's ownership fact is the
+ * slug on the manifest; the source file is provenance and can move).
+ *
+ * @param {{ slug: string, source: string }} appliedRecord
+ * @param {string} projectRoot
+ * @returns {Promise<string[]>}
+ */
+export async function readAppliedBlueprintCapabilities(appliedRecord, projectRoot) {
+  if (!appliedRecord || typeof appliedRecord.source !== 'string') return [];
+  const src = appliedRecord.source;
+  // A qualified typed ref (`wsd:auth-oauth2`) never resolves as a file
+  // path. Skip it; the library-resolved source blueprint is not on
+  // this local tree.
+  if (/^[a-z][a-z0-9-]*:[a-z]/i.test(src) && !src.startsWith('/') && !src.startsWith('.')) return [];
+  const abs = isAbsolute(src) ? src : resolve(projectRoot, src);
+  const metaPath = join(abs, 'blueprint.json');
+  let raw;
+  try {
+    raw = await readFile(metaPath, 'utf8');
+  } catch {
+    return [];
+  }
+  try {
+    const doc = JSON.parse(raw);
+    if (!Array.isArray(doc.capabilities)) return [];
+    return doc.capabilities.filter((s) => typeof s === 'string');
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Discover the union of applied capabilities across every applied
+ * blueprint on the tree.
+ *
+ * @param {Array<{ slug: string, source: string }>} appliedRecords
+ * @param {string} projectRoot
+ * @returns {Promise<{ union: string[], perSlug: Record<string, string[]> }>}
+ */
+export async function discoverAppliedCapabilities(appliedRecords, projectRoot) {
+  const perSlug = {};
+  const union = new Set();
+  for (const rec of appliedRecords ?? []) {
+    const caps = await readAppliedBlueprintCapabilities(rec, projectRoot);
+    perSlug[rec.slug] = caps;
+    for (const c of caps) union.add(c);
+  }
+  return { union: [...union].sort(), perSlug };
+}
+
+/**
+ * Build the refusal message for a requiresAppliedCapabilities gate.
+ * refusalMessageId maps to a known template; a message the loader
+ * accepts is used verbatim if the id is unknown (so a future
+ * blueprint can ship a bespoke refusal without a core code change).
+ *
+ * @param {object} args
+ * @param {string} args.slug        applying blueprint slug
+ * @param {string} args.refusalMessageId
+ * @param {string[]} args.requiredCapabilities
+ * @param {Array<{ slug: string, version: string }>} args.appliedRecords
+ * @param {string} args.allowSkipFlag  the CLI flag the operator can use to override
+ * @returns {string}
+ */
+export function buildRefusalMessage({ slug, refusalMessageId, requiredCapabilities, appliedRecords, allowSkipFlag }) {
+  // Applied blueprints list, one per line (indented 2 spaces per spec
+  // 5.5.1 formatting).
+  const appliedLines = (appliedRecords ?? [])
+    .map((r) => `  ${r.slug} v${r.version}`)
+    .join('\n');
+  const appliedBlock = appliedLines.length > 0 ? appliedLines : '  (none)';
+  if (refusalMessageId === 'application-admin-console-bare-spa') {
+    return [
+      `${slug} requires at least one applied security-auth-* blueprint,`,
+      `or an operator override with --${allowSkipFlag}.`,
+      '',
+      'Applied blueprints on this project:',
+      appliedBlock,
+      '',
+      'Suggested next steps:',
+      '  1. Apply an auth blueprint first:',
+      '       rcf define blueprint add security-auth-magic-link',
+      '     (or security-auth-clerk, security-auth-oauth2, security-auth-keycloak)',
+      `  2. Override for a scaffolding pass (surfaces will refuse at apply until an`,
+      `     auth blueprint is applied):`,
+      `       rcf define blueprint add ${slug} --${allowSkipFlag}`,
+    ].join('\n');
+  }
+  // Generic fallback. Names the required capabilities and applied set;
+  // the operator has enough to diagnose without a bespoke template.
+  return [
+    `${slug} requires an applied blueprint declaring at least one of:`,
+    `  ${requiredCapabilities.join(', ')}`,
+    `or an operator override with --${allowSkipFlag}.`,
+    '',
+    'Applied blueprints on this project:',
+    appliedBlock,
+  ].join('\n');
+}
+
+/**
+ * Run the elicitation phase. Reads a bag of operator-supplied answers
+ * (`--answer <id>=<value>` merged with `--answers <file>` in the CLI),
+ * evaluates each elicit's `when` predicate against the discovered
+ * capability set, coerces the answer per kind, and returns a
+ * `{id: value}` map. A missing required answer for an elicit whose
+ * predicate fires refuses with a validation rcfError.
+ *
+ * @param {object} args
+ * @param {Array<object>} args.elicits         from loader
+ * @param {string[]} args.appliedCapabilities  discovered union
+ * @param {Record<string, string|boolean>} args.answers  operator bag
+ * @returns {{value: Record<string, string|boolean|null>} | import('../core/errors/index.js').RcfError}
+ */
+export function runElicitationPhase({ elicits, appliedCapabilities, answers }) {
+  if (!Array.isArray(elicits) || elicits.length === 0) {
+    return { value: {} };
+  }
+  const capSet = new Set(appliedCapabilities ?? []);
+  const bag = answers ?? {};
+  const out = {};
+  for (const e of elicits) {
+    const gated = e.when ? Array.isArray(e.when.requiresCapability) && !e.when.requiresCapability.some((c) => capSet.has(c)) : false;
+    if (gated) continue;
+    const raw = bag[e.id];
+    let coerced;
+    if (raw === undefined || raw === null || raw === '') {
+      if (e.default === undefined) {
+        return rcfError({
+          kind: 'validation',
+          message: `blueprint apply: elicit '${e.id}' is required (no default declared) and no answer was supplied. Pass --answer ${e.id}=<value> or --answers <file>.`,
+        });
+      }
+      coerced = e.default;
+    } else if (e.kind === 'boolean') {
+      if (typeof raw === 'boolean') coerced = raw;
+      else {
+        const s = String(raw).trim().toLowerCase();
+        if (s === 'y' || s === 'yes' || s === 'true' || s === '1') coerced = true;
+        else if (s === 'n' || s === 'no' || s === 'false' || s === '0') coerced = false;
+        else return rcfError({ kind: 'validation', message: `blueprint apply: elicit '${e.id}' expects a boolean; got '${raw}'.` });
+      }
+    } else if (e.kind === 'enum') {
+      const s = String(raw).trim();
+      if (!e.options.includes(s)) {
+        return rcfError({ kind: 'validation', message: `blueprint apply: elicit '${e.id}' expects one of [${e.options.join(', ')}]; got '${raw}'.` });
+      }
+      coerced = s;
+    } else {
+      coerced = String(raw).trim();
+    }
+    out[e.id] = coerced;
+  }
+  return { value: out };
+}
+
+/**
+ * Sidecar path for a blueprint's per-project apply-state (relative to
+ * the project root). One file per applied blueprint slug.
+ */
+export function sidecarRelPath(slug) {
+  return join('rcf', 'blueprints', `${slug}.applied.json`);
+}
+
+/**
+ * Write the sidecar. Overwrites the file so re-apply on the same
+ * version is idempotent.
+ *
+ * @param {object} args
+ * @param {string} args.projectRoot
+ * @param {string} args.slug
+ * @param {string} args.version
+ * @param {string} args.appliedAt
+ * @param {string[]} args.appliedCapabilities
+ * @param {Record<string, string|boolean|null>} args.appliedElicitations
+ * @param {boolean} [args.allowNoAuthYet]
+ * @param {string} [args.notes]
+ */
+export async function writeSidecar({ projectRoot, slug, version, appliedAt, appliedCapabilities, appliedElicitations, allowNoAuthYet, notes }) {
+  const rel = sidecarRelPath(slug);
+  const abs = join(projectRoot, rel);
+  await mkdir(dirname(abs), { recursive: true });
+  const payload = { slug, version, appliedAt, appliedCapabilities: [...appliedCapabilities].sort(), appliedElicitations };
+  if (allowNoAuthYet === true) payload.allowNoAuthYet = true;
+  if (typeof notes === 'string' && notes.length > 0) payload.notes = notes;
+  await writeFile(abs, `${JSON.stringify(payload, null, 2)}\n`, 'utf8');
+  return rel;
+}
+
+/**
+ * Read the sidecar. Missing file returns null (never throws).
+ */
+export async function readSidecar(projectRoot, slug) {
+  const abs = join(projectRoot, sidecarRelPath(slug));
+  try {
+    const raw = await readFile(abs, 'utf8');
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Presence check for the sidecar file (does not parse).
+ */
+export async function sidecarExists(projectRoot, slug) {
+  try {
+    await stat(join(projectRoot, sidecarRelPath(slug)));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Custom-auth capability elicitation (visual round T-5 spec 5.5
+ * "Risks": custom auth elicits per capability). Runs BEFORE the
+ * requiresAppliedCapabilities refusal gate. Each elicit entry with
+ * a truthy `providesCapability` string is a boolean prompt asking
+ * whether the operator's own (non-shelf) auth blueprint provides
+ * the named capability. A truthy answer folds that capability into
+ * the effective applied set, so a project with no shelf auth
+ * blueprint can still pass the refusal gate without the allowNoAuthYet
+ * override, and the resulting sidecar records the operator-declared
+ * appliedCapabilities honestly.
+ *
+ * Interactive vs non-interactive:
+ *   - Non-interactive: only the elicits whose id appears in `answers`
+ *     resolve; the rest are treated as unanswered.
+ *   - Interactive (tty=true): unanswered custom-auth elicits are read
+ *     from stdin via readline with a `y/N` prompt; this branch is
+ *     driven synchronously by the CLI's `apply` wrapper when it
+ *     detects `process.stdin.isTTY === true`.
+ *
+ * A malformed boolean answer refuses with a validation rcfError.
+ *
+ * @param {object} args
+ * @param {Array<object>} args.elicits             from loader (may include non-providesCapability entries; they are ignored here)
+ * @param {Record<string, string|boolean>} args.answers  operator bag
+ * @param {(prompt: string) => Promise<string>} [args.readLine]  test seam for interactive input
+ * @returns {Promise<{ capsProvided: string[], answered: Record<string, boolean>, elicitsPresent: boolean, anyAnswered: boolean } | import('../core/errors/index.js').RcfError>}
+ */
+export async function runCustomAuthCapabilityElicits({ elicits, answers, readLine }) {
+  const capsProvided = new Set();
+  const answered = {};
+  let elicitsPresent = false;
+  const bag = answers ?? {};
+  for (const e of elicits ?? []) {
+    if (typeof e.providesCapability !== 'string' || e.providesCapability.length === 0) continue;
+    elicitsPresent = true;
+    const raw = bag[e.id];
+    let coerced;
+    if (raw === undefined || raw === null || raw === '') {
+      if (typeof readLine !== 'function') {
+        // Non-interactive branch, no answer supplied: skip. Default
+        // remains false in that case so a missing operator answer does
+        // not silently declare a capability.
+        continue;
+      }
+      const reply = await readLine(`Custom auth: does your auth provide '${e.providesCapability}'? [y/N]: `);
+      const s = String(reply ?? '').trim().toLowerCase();
+      if (s === '' || s === 'n' || s === 'no' || s === 'false' || s === '0') coerced = false;
+      else if (s === 'y' || s === 'yes' || s === 'true' || s === '1') coerced = true;
+      else {
+        return rcfError({
+          kind: 'validation',
+          message: `blueprint apply: elicit '${e.id}' expects a boolean; got '${reply}'.`,
+        });
+      }
+    } else if (typeof raw === 'boolean') {
+      coerced = raw;
+    } else {
+      const s = String(raw).trim().toLowerCase();
+      if (s === 'y' || s === 'yes' || s === 'true' || s === '1') coerced = true;
+      else if (s === 'n' || s === 'no' || s === 'false' || s === '0') coerced = false;
+      else {
+        return rcfError({
+          kind: 'validation',
+          message: `blueprint apply: elicit '${e.id}' expects a boolean; got '${raw}'.`,
+        });
+      }
+    }
+    answered[e.id] = coerced;
+    if (coerced === true) capsProvided.add(e.providesCapability);
+  }
+  return {
+    capsProvided: [...capsProvided].sort(),
+    answered,
+    elicitsPresent,
+    anyAnswered: Object.keys(answered).length > 0,
+  };
+}