rcf-lite 0.12.0 → 0.13.0

package/blueprints/security-secrets-management/guide/security-secrets-management.md

@@ -0,0 +1,68 @@
+# Security secrets management blueprint guide
+
+## What it is
+
+A default secrets-management floor for small greenfield rcf-lite projects. The blueprint contributes the WHAT of a secrets pattern: how the project declares what secrets exist, how one client is the sole reader of every value, how each deployable is restricted to its own slice, how every access is audited, how coding agents work with values without leaking them into transcripts and logs, how `.env` sits at the surface as an ephemeral projection rather than the source of truth, how environment shape is elicited from the operator, how rotation is gated at CI, and how an operator-facing Secrets page is offered as a three-way elicited choice.
+
+Concretely, the blueprint ships ten requirements, ten user stories (thirty acceptance criteria), five architecture components, and five architecture decision records. One ADR is `scope: global` on the `secretsSource` topic; the other four are scope-local operational ADRs (default vendor, agent access discipline, `.env` reflection posture, rotation-and-audit posture) that a composing blueprint does not conflict with by default.
+
+## What it is not
+
+Not a vendor SDK. The default vendor named in ADR-902 is SOPS with age keys, chosen for the zero-infrastructure floor the rcf-lite tier expects. Larger deployments supersede ADR-902 with a project-level ADR and swap the vendor adapter for Vault, a cloud secrets manager, or a hosted third-party service; the ADR-901 contract stays intact.
+
+Not an authorisation model. The blueprint governs READ of secret material and the audit trail of that read; who is allowed to trigger a rotation, who sees the admin-UI Secrets page, and who owns which secret at the operational level are project-side authorisation concerns that layer above the audit sink.
+
+Not a rotation orchestrator. The blueprint gates on rotation age at CI, it does not itself run the rotation. Running a rotation is a project-authored procedure the vendor's own tooling supports (SOPS re-encrypt, Vault's rotate endpoint, a cloud provider's rotation trigger); the blueprint's rotation gate then registers the fresh `lastRotatedAt` next time it runs.
+
+Not a UI framework. When `uiIntegration.mode` is `integrate`, the field contract for the Secrets page is fixed (TAC-905's structured output surface) but the page implementation lives in the host project's admin UI. A future admin-spa blueprint (unshipped at v1.0.0, promotion signal: the third project asks for a self-contained admin surface that hosts this page alongside others) will cover the standalone case.
+
+Not a config manager. Non-secret configuration (feature flags, tunable thresholds, endpoint URLs that are not sensitive) sits outside this blueprint; the manifest is for secret material only. A project that wants a unified config surface authors that on top; it does not belong here.
+
+## When to reach for it
+
+Reach for the security-secrets-management blueprint when:
+
+- The project depends on secret material of any kind (third-party API keys, database credentials, signing keys, session salts, TLS keys) and there is no single source of truth for what secrets exist.
+- Multiple deployables share a secret pool and least-privilege slicing is the intended posture rather than a wishful comment in a README.
+- Coding agents (Claude, Cursor, Copilot workflows, in-house LLM-driven scripts) are part of the operator's day and secret material must not land in the surfaces those workflows create.
+- Rotation is a real policy rather than a document nobody reads; CI is the intended enforcement layer.
+- The project is a small greenfield rcf-lite deployment (single deployable or a small deployable fleet, one small team or one solo operator, no ops team standing by) where a zero-infrastructure secrets story is a feature.
+
+## When it does not fit
+
+Do not reach for the security-secrets-management blueprint when:
+
+- The project's secret pool is genuinely trivial (one API key, one deployable, one operator) and running a manifest plus a CI gate is more machinery than the actual risk warrants. A lightweight `.env` and a rotation reminder on a calendar is honestly the right shape at that scale; this blueprint's audit-and-slice discipline is overkill.
+- The project has a hard corporate mandate for a specific hosted secrets vendor and there is no useful default for day one because everything already lives in that vendor. Apply the blueprint anyway if you want the ADR-901 contract, but expect to supersede ADR-902 with a project-level ADR at apply time.
+- Compliance requires an audit stream shape different from the one ADR-905 fixes (a specific SIEM schema, a regulator-mandated field set). The blueprint fixes the SHAPE of the audit events; a project with a stricter schema supersedes ADR-905 with a project-level ADR that names the target schema and the mapping.
+- The deploy target has no persistent filesystem for the SOPS-with-age default to live on and no working alternative vendor. The default vendor assumes a stable path the encrypted files survive at; a project without that assumption picks a different vendor (a hosted service is the natural fit) and supersedes ADR-902 accordingly.
+
+An earlier design pass scoped a Vault-first blueprint (candidate name `secrets-vault`). The blueprint at v1.0.0 does not lead with Vault because the container-plus-server cost is disproportionate for the rcf-lite tier this blueprint targets. Vault remains the reference open-source promotion path for projects with dedicated ops capacity, and the blueprint's contract composes cleanly with a Vault vendor adapter; the promotion is a project-level ADR supersede on ADR-902 and an adapter swap.
+
+## What a good outcome looks like
+
+A project applies the blueprint on a fresh tree, elicits its environment set (say `dev`, `ci`, `live`), declares its deployables and their per-deployable secret slices in `secrets.yaml`, chooses one of the three UI outcomes (`integrate`, `admin-spa`, `none`), realises the five TACs in project-authored FBSes with the default SOPS-with-age vendor adapter, and lands on a deployed application where:
+
+- Every runtime path that reads a secret imports the Secrets Manager client; nothing else touches the vendor SDK. A source-tree scan confirms the boundary.
+- The `secrets.yaml` at the repo root is the file the operator reads to see what secrets the project depends on; adding a new secret is a two-step change (add the manifest entry, then commit an encrypted value file or configure the vendor path).
+- A required secret missing in `live` fails boot with a stable-coded error naming the logical name and the environment; the operator diagnoses in one step.
+- A coding agent that needs to wire a secret into a starting process runs `secrets read N | consumer-tool` and the value never lands in the agent's transcript, its tool log, or a scratch file on the working tree.
+- A developer laptop `.env` exists because the developer ran `secrets reflect --deployable local-api --env dev`; deleting the file and re-running the reflector produces an identical file; the file is gitignored and its stale-and-regenerable status is visible in the workflow.
+- The rotation gate runs on every CI change; a secret past its `rotationDays` budget fails the run with a naming error the author can act on immediately; a legitimate mid-rotation override is authored with an expiry timestamp and every application of it is audited.
+- The audit stream contains every fetch attempt with `name`, `path`, `environment`, `principal`, `outcome`, and `at`; a byte-equality scan against every resolved secret value finds no match anywhere on the stream.
+- When the operator picked `integrate`, the admin UI's Secrets page renders name, environment, owner, `lastRotatedAt`, and `rotationDays` per row; no cell renders a secret value. When the operator picked `none`, no Secrets page exists anywhere on the deployed application; the CLI plus the audit stream are the whole story.
+
+## Operator decisions that remain open after apply
+
+- Vendor choice (SOPS+age default, or a superseding project-level ADR selecting Vault, AWS Secrets Manager, GCP Secret Manager, Azure Key Vault, Doppler, Infisical, or a project-authored adapter). Blueprint owns the contract on both sides of the boundary; project owns the vendor.
+- Environment set (`dev`/`ci`/`live` common default; project-specific names supported). Blueprint owns the enforcement that the manifest and the boot input agree; project owns the names.
+- Deployable-to-slice map (which deployable reads which secrets). Blueprint owns the least-privilege enforcement; project owns the split.
+- UI integration outcome (`integrate`, `admin-spa`, `none`). Blueprint owns the field contract for the `integrate` outcome; project owns the page implementation and the admin UI it lives in.
+- Rotation-days budgets per entry (a small budget for high-turnover keys, a larger budget for session salts). Blueprint owns the CI gate that enforces the budget; project owns the numbers.
+- Rotation override policy (who is allowed to author an override, how long an override may last, what the audit review cadence is). Blueprint owns that overrides carry an `expiresAt` and are audited every time; project owns the human process around them.
+- Audit sink implementation (where the audit events land: a local file, a SIEM, a data warehouse, a project's own event bus). Blueprint owns the event shape; project owns the shipper.
+- Secret owners (who is on the hook when an entry expires or an incident touches its blast radius). Blueprint owns that the manifest carries an `owner` field per entry; project owns the roster.
+
+## Cost-honesty paragraph
+
+Shipping this doc set costs the project the following. Every new secret is now a manifest change and a vendor-side configuration change instead of a stray environment variable; the discipline is intentional and adds a small friction to prototype-shaped work. The default SOPS-with-age vendor requires every developer laptop and every CI runner and every deploy host to hold an age key; losing every copy is a recover-by-rewrite problem for a pre-launch project and a recover-by-re-issue problem thereafter. The rotation gate fails CI on real drift; a project that wants faster merges buys them by rotating on cadence or by keeping the override discipline honest, neither is free. The audit sink is a stream the project now maintains; wiring it to a real sink (a SIEM, a data warehouse) is a project cost the blueprint does not carry. The three-way UI choice keeps a project without a UI honest, but a project that later wants one is a real build task rather than a config flip. The blueprint says nothing about authorisation, about the vendor's own rotation orchestration, about SIEM schemas, or about compliance reporting; a project that needs any of those spends its own build cycles on them and this blueprint does not save it any work there.

package/fixtures/canary-manifest.json

@@ -1,103 +1,3 @@
 {
-  "registerCanary": [
-    {
-      "id": "rc-2026-08-28-001",
-      "createdAt": "2026-08-28T15:27:07.804Z",
-      "buildVersion": "0.12.0-mockdriver",
-      "fixturePromptId": "canary-prompt-01",
-      "responseWordCount": 55,
-      "grades": {
-        "internalRuleCitation": {
-          "verdict": "pass",
-          "matches": []
-        },
-        "unglossedJargon": {
-          "verdict": "pass",
-          "matches": []
-        },
-        "redundantPermissionAsk": {
-          "verdict": "pass",
-          "matches": []
-        },
-        "bypassOffer": {
-          "verdict": "pass",
-          "matches": []
-        },
-        "wordCountBudget": {
-          "verdict": "pass",
-          "target": 200,
-          "actual": 55,
-          "matches": []
-        }
-      },
-      "verdict": "fail",
-      "shipDespiteFailReason": "mock canary driver used; no real subagent was dispatched. This record verifies canary infrastructure only, not the register itself."
-    },
-    {
-      "id": "rc-2026-08-28-002",
-      "createdAt": "2026-08-28T15:27:07.805Z",
-      "buildVersion": "0.12.0-mockdriver",
-      "fixturePromptId": "canary-prompt-02",
-      "responseWordCount": 55,
-      "grades": {
-        "internalRuleCitation": {
-          "verdict": "pass",
-          "matches": []
-        },
-        "unglossedJargon": {
-          "verdict": "pass",
-          "matches": []
-        },
-        "redundantPermissionAsk": {
-          "verdict": "pass",
-          "matches": []
-        },
-        "bypassOffer": {
-          "verdict": "pass",
-          "matches": []
-        },
-        "wordCountBudget": {
-          "verdict": "pass",
-          "target": 200,
-          "actual": 55,
-          "matches": []
-        }
-      },
-      "verdict": "fail",
-      "shipDespiteFailReason": "mock canary driver used; no real subagent was dispatched. This record verifies canary infrastructure only, not the register itself."
-    },
-    {
-      "id": "rc-2026-08-28-003",
-      "createdAt": "2026-08-28T15:27:07.805Z",
-      "buildVersion": "0.12.0-mockdriver",
-      "fixturePromptId": "canary-prompt-03",
-      "responseWordCount": 55,
-      "grades": {
-        "internalRuleCitation": {
-          "verdict": "pass",
-          "matches": []
-        },
-        "unglossedJargon": {
-          "verdict": "pass",
-          "matches": []
-        },
-        "redundantPermissionAsk": {
-          "verdict": "pass",
-          "matches": []
-        },
-        "bypassOffer": {
-          "verdict": "pass",
-          "matches": []
-        },
-        "wordCountBudget": {
-          "verdict": "pass",
-          "target": 200,
-          "actual": 55,
-          "matches": []
-        }
-      },
-      "verdict": "fail",
-      "shipDespiteFailReason": "mock canary driver used; no real subagent was dispatched. This record verifies canary infrastructure only, not the register itself."
-    }
-  ]
+  "registerCanary": []
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rcf-lite",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "type": "module",
   "description": "One-install tooling for the Requirements Confidence Framework (RCF): the unified `rcf` CLI grouped into the five RCF tool groups (discover, define, build, verify, audit) plus a small core set (init, doctor, guidance, mcp), an MCP server, the live tree viewer and the fresh-context adversarial ship-gate verifier. Consumes @stravica-ai/rcf-schemas.",
   "license": "Apache-2.0",
@@ -28,6 +28,8 @@
     "guidance",
     "rcf",
     "fixtures",
+    "blueprints",
+    "scripts/preinstall-node-check.mjs",
     "README.md",
     "LICENSE",
     "CHANGELOG.md"
@@ -36,6 +38,17 @@
     "registry": "https://registry.npmjs.org/",
     "access": "public"
   },
+  "scripts": {
+    "test": "node --test --test-concurrency=1 'test/**/*.test.js'",
+    "vendor": "node scripts/vendor-mermaid.mjs",
+    "build:managed": "node scripts/gen-managed-artefacts.mjs",
+    "canary:register": "node scripts/canary-register.mjs",
+    "stage:blueprints": "node scripts/stage-blueprint-shelf.mjs",
+    "preinstall": "node scripts/preinstall-node-check.mjs",
+    "prepack": "node scripts/stage-blueprint-shelf.mjs",
+    "prepublishOnly": "node scripts/gen-managed-artefacts.mjs && node scripts/stage-blueprint-shelf.mjs",
+    "rcf": "node bin/rcf.js"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Stravica/rcf-lite.git",
@@ -64,12 +77,5 @@
   "devDependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "mermaid": "11.6.0"
-  },
-  "scripts": {
-    "test": "node --test --test-concurrency=1 'test/**/*.test.js'",
-    "vendor": "node scripts/vendor-mermaid.mjs",
-    "build:managed": "node scripts/gen-managed-artefacts.mjs",
-    "canary:register": "node scripts/canary-register.mjs",
-    "rcf": "node bin/rcf.js"
   }
-}
+}

package/rcf/.identity/profile.md

@@ -0,0 +1,37 @@
+# Operator profile
+
+This file describes you (the operator) to any agent working on this
+repo. It lives in `rcf/.identity/` and is gitignored by default, so
+it is per-clone: another developer's clone of the same repo has their
+own profile, not yours.
+
+Fill in what is useful. Leave the rest. Freeform prose is fine; a
+bulleted list is fine. Nothing here is enforced by tooling.
+
+## Name
+
+_(who you are; how you want the agent to address you)_
+
+## Role
+
+_(what you do; what perspective you bring to this project)_
+
+## Working preferences
+
+_(how you like to work: casual or formal register, verbose or terse
+responses, willingness to be pushed back on, anything the agent should
+know before choosing its default posture)_
+
+## Project-scoped notes
+
+_(anything specific to this project that would be useful for the agent
+to know but does not belong in the shared requirements tree: a local
+dev workflow quirk, an in-flight side-experiment, a "do not touch this
+directory yet" flag)_
+
+---
+
+If you want to share your profile with the team, remove the
+`rcf/.identity/` line from the managed block in `.gitignore` (or `git
+add -f rcf/.identity/profile.md` for one-off sharing). The default is
+per-clone. Sharing is deliberate.

package/rcf/knowledge/INDEX.md

@@ -0,0 +1,12 @@
+# Knowledge index
+
+The human table of contents for `rcf/knowledge/`. Add a bullet when you
+add a file. Keep it grouped by area if it grows.
+
+## Notes
+
+_(none yet)_
+
+## Docs
+
+_(none yet)_

package/rcf/knowledge/README.md

@@ -0,0 +1,41 @@
+# Knowledge
+
+This directory is the project's memory. Everything an agent working on
+this repo should not have to relearn from scratch belongs here.
+
+## The convention
+
+- **`notes/`**: internal facts. Decisions, gotchas, runtime facts,
+  the small things that always cost time to rediscover ("the CI matrix
+  uses Node 22 not 24", "the pnpm store path on this machine is
+  non-default", "the local Postgres is on port 5433 not 5432"). Written
+  for future agents and future you, not for public readers.
+- **`docs/`**: user-facing prose the project might surface elsewhere.
+  Design notes the operator wants tidy, sections that might land in a
+  README or a spec, prose intended for a wider audience.
+
+## The rules
+
+1. **One topic per file.** The filename is the topic
+   (`notes/ci-node-version.md`, not `notes/general.md`). One paragraph
+   is enough. An empty file that only carries a pointer to somewhere
+   else is fine. A file called `misc.md` or `general.md` is not.
+2. **Write on learn.** If this session established a fact the next
+   session should not have to rediscover, write it here before the
+   session ends.
+3. **Grep before asking.** Before asking the stakeholder a question,
+   `rg -n '<topic>' rcf/knowledge/` to see whether the answer is
+   already here.
+
+## `INDEX.md`
+
+`INDEX.md` is a human table of contents. Add a bullet when you add a
+file. Keep it grouped by area if it grows. Nobody scans it
+programmatically in v1; it is for the person landing on the repo cold.
+
+## What this is not
+
+This is not a knowledge graph. There is no CLI verb, no indexer, no
+vector search. If a project needs one, that is a v2 decision, not a v1
+default. The convention above is deliberately cheap. The value is in
+the discipline of using it.

package/scripts/preinstall-node-check.mjs

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+// Preinstall hard-fail on Node < 24.
+//
+// The `engines` block in package.json only asks npm to complain; recent
+// npm defaults print a warning and install anyway, so a session on
+// Node 22 has historically resolved the last publish that ADVERTISED
+// support for it (`rcf-lite@0.0.1`, a placeholder stub) without ever
+// touching the current release train. That silent downgrade is the
+// worst-possible first touch for a new operator, so we fail loudly
+// here BEFORE any files land on disk.
+//
+// Bypass for maintainers who genuinely need to override: set
+// `RCF_LITE_SKIP_NODE_CHECK=1`. Do not set it in ordinary use.
+//
+// Source-monorepo exemption: the same script also runs when someone
+// installs this repo itself as a pnpm workspace (workspace members get
+// their preinstall invoked on `pnpm install`). Blocking the source dev
+// flow is not the point of this gate; the point is to stop
+// `npm install rcf-lite` on the wrong Node from silently landing a
+// broken tree. If we can detect we're being run from the pnpm workspace
+// root (an ancestor `pnpm-workspace.yaml` exists), we skip - the
+// engines WARN still fires, so contributors are not unaware.
+
+import { existsSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const REQUIRED_MAJOR = 24;
+
+if (process.env.RCF_LITE_SKIP_NODE_CHECK === '1') {
+  process.exit(0);
+}
+
+const here = dirname(fileURLToPath(import.meta.url));
+// packages/rcf-lite/scripts -> packages/rcf-lite -> packages -> repo-root
+const candidateRepoRoot = resolve(here, '..', '..', '..');
+if (existsSync(resolve(candidateRepoRoot, 'pnpm-workspace.yaml'))) {
+  // Running inside the source monorepo. The engines pin still complains,
+  // but we do not want to break `pnpm install` for a dev on the wrong
+  // Node while they are trying to bump their own environment. The gate
+  // is aimed at consumers of the published tarball, not at us.
+  process.exit(0);
+}
+
+const raw = process.versions.node;
+const match = /^(\d+)\./.exec(raw ?? '');
+const major = match ? Number(match[1]) : Number.NaN;
+
+if (!Number.isFinite(major) || major < REQUIRED_MAJOR) {
+  const lines = [
+    '',
+    '  rcf-lite requires Node.js >= 24.',
+    `  Detected Node.js ${raw}.`,
+    '',
+    '  Install a supported Node (see https://nodejs.org) and re-run.',
+    '  Bypass (not recommended): RCF_LITE_SKIP_NODE_CHECK=1 npm install rcf-lite',
+    '',
+  ];
+  process.stderr.write(lines.join('\n'));
+  process.exit(1);
+}

package/src/blueprint/apply.js

@@ -34,7 +34,11 @@ import { nextResolutionId } from './resolutions.js';
  * @param {object} args
  * @param {string} args.projectRoot
  * @param {import('#core/store/walker.js').TreeModel} args.tree
- * @param {string} args.source - path to blueprint directory
+ * @param {string} args.source - path to blueprint directory (absolute after the CLI resolver)
+ * @param {string} [args.displaySource] - the source string as the operator typed it;
+ *        used only for the conflict renderer's supersede hint so it can print the exact
+ *        string the operator can copy back. Defaults to `source` when omitted (so
+ *        existing callers keep today's byte-for-byte behaviour).
  * @param {string} [args.namespaceOverride] - non-default namespace slug
  * @param {Array<{ topic: string, resolvedByAdrId: string }>} [args.resolveDeclarations]
  *        Operator-supplied conflict resolutions declared on the add
@@ -54,7 +58,8 @@ 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, namespaceOverride, resolveDeclarations, now = new Date(), dryRun = false, _copyFileForTest }) {
+export async function applyBlueprint({ projectRoot, tree, source, displaySource, namespaceOverride, resolveDeclarations, 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
   const namespace = namespaceOverride ?? blueprint.slug;
@@ -100,7 +105,7 @@ export async function applyBlueprint({ projectRoot, tree, source, namespaceOverr
     // exactly as printed - `rcf blueprint supersede <topic> --incoming
     // <source>` - with a real source path the operator can copy back
     // into a fresh shell.
-    ...await enrichAdrConflicts(rawGlobalConflicts, tree, blueprint, source),
+    ...await enrichAdrConflicts(rawGlobalConflicts, tree, blueprint, hintSource),
     ...detectCrossBlueprintClaims(applied, incomingForConflicts),
   ];
   if (conflicts.length > 0) {
@@ -172,8 +177,9 @@ export async function applyBlueprint({ projectRoot, tree, source, namespaceOverr
         // first-apply into a tree that already has the file, or a new
         // contribution appearing in a re-applied version -- is treated
         // as foreign and refused. Grammar is deliberately not consulted
-        // here: `ADR-201-spa-theme` may be a legitimate `spa`-owned id
-        // whose author put a semantic tail after the slug.
+        // here: `ADR-201-application-spa-theme` may be a legitimate
+        // `application-spa`-owned id whose author put a semantic tail
+        // after the slug.
         if (!ownedIds.has(c.id)) {
           for (const w of stagedWrites) await unlink(w.tmpAbs).catch(() => {});
           return rcfError({
@@ -395,7 +401,7 @@ function composeDeclaredResolutions({ manifest, applied, incoming, declarations,
  * absent and the renderer falls back to id-at-path for that side.
  *
  * Round-2 review nit: the earlier version only enriched the existing
- * side, so a conflict report against shipped SPA + REST rendered
+ * side, so a conflict report against shipped application-spa + REST rendered
  * asymmetrically (spa gets 'SPA auth: cookie sessions — HttpOnly
  * cookies.' while rest gets 'ADR-003-rest at rcf/adrs/...'). Both
  * sides are readable — the existing side from tree, the incoming

package/src/blueprint/conflicts.js

@@ -15,10 +15,10 @@
 //    manifest record. The manifest's appliedBlueprintRecord.contributions[]
 //    list is the authoritative ownership record; two blueprints cannot
 //    both claim the same id. This is the ambiguity-class check that
-//    used to live inside `isNamespacedFor` grammar (blueprint `spa`
-//    silently claiming `ADR-005-spa-theme` because the string
-//    startsWith `spa-`). Grammar is no longer a trust surface here --
-//    the manifest is.
+//    used to live inside `isNamespacedFor` grammar (blueprint
+//    `application-spa` silently claiming `ADR-005-application-spa-theme`
+//    because the string startsWith `application-spa-`). Grammar is no
+//    longer a trust surface here -- the manifest is.
 //
 // Every other class the design brief names (non-global TACs/ADRs/REQs/USs
 // /FBSes, standards-value conflicts, manifest overlap) is either
@@ -111,10 +111,10 @@ export function detectGlobalAdrConflicts(appliedBlueprints, incoming, manifest =
 /**
  * Cross-blueprint ownership conflicts: an incoming contribution id is
  * already recorded as owned by a DIFFERENT applied blueprint. This
- * detector is what makes `spa` vs `spa-theme` cross-claim impossible
- * once one of the two has applied -- the second-mover's incoming id
- * hits the first-mover's manifest record and is refused, regardless
- * of how the id string parses.
+ * detector is what makes `application-spa` vs `application-spa-theme`
+ * cross-claim impossible once one of the two has applied -- the
+ * second-mover's incoming id hits the first-mover's manifest record
+ * and is refused, regardless of how the id string parses.
  *
  * Re-apply of the same slug (`applied.slug === incoming.slug`) is
  * skipped: same blueprint owning its own ids across re-apply is the

package/src/blueprint/index.js

@@ -1,7 +1,7 @@
 // Public surface for the blueprint mechanism.
 
 export { applyBlueprint } from './apply.js';
-export { listBlueprints } from './list.js';
+export { listBlueprints, enrichRowsWithCategories, groupRowsByCategory } from './list.js';
 export { removeBlueprint } from './remove.js';
 export { loadBlueprint } from './loader.js';
 export { detectGlobalAdrConflicts, detectCrossBlueprintClaims, renderConflictReport, conflictReportJson } from './conflicts.js';
@@ -10,3 +10,4 @@ export { registerStandardsPack, listStandards } from './standards.js';
 export { nextResolutionId, matchingResolution } from './resolutions.js';
 export { supersedeBlueprintTopic } from './supersede.js';
 export { diffBlueprintTopic, renderDiff } from './diff.js';
+export { resolveBlueprintSource, knownShelfSlugs, packagedShelfPath } from './shelf-resolver.js';

package/src/blueprint/list.js

@@ -1,6 +1,17 @@
 // Blueprint list. Reads manifest.blueprints[] and returns rows in
 // appliedAt order. Rows are already validated by the schema; this
 // module is a projection.
+//
+// Category enrichment lives in `enrichRowsWithCategories`. The applied
+// manifest record's shape is pinned by `@stravica-ai/rcf-schemas`
+// (additionalProperties: false on appliedBlueprintRecord), so category
+// is not persisted on apply. Instead each row's `source` path is
+// re-loaded at list time to read the shipping blueprint's own
+// `blueprint.json:category`. A source that no longer resolves surfaces
+// as `category: null` so grouped rendering can place it under an
+// uncategorised heading rather than swallow the row.
+
+import { loadBlueprint } from './loader.js';
 
 /**
  * @param {import('#core/store/walker.js').TreeModel} tree
@@ -19,3 +30,52 @@ export function listBlueprints(tree) {
       contributionCount: Array.isArray(b.contributions) ? b.contributions.length : 0,
     }));
 }
+
+/**
+ * Enrich list rows with a `category` field, read from each row's
+ * shipping blueprint source. Best-effort: any load failure yields
+ * `category: null` so the caller can render the row under an
+ * uncategorised group rather than skip it.
+ *
+ * @param {ReturnType<typeof listBlueprints>} rows
+ * @returns {Promise<Array<{ slug: string, version: string, appliedAt: string, source: string, namespace: string | null, contributionCount: number, category: string | null }>>}
+ */
+export async function enrichRowsWithCategories(rows) {
+  const out = [];
+  for (const row of rows) {
+    let category = null;
+    if (typeof row.source === 'string' && row.source.length > 0) {
+      const loaded = await loadBlueprint(row.source);
+      if (!loaded.kind && typeof loaded.category === 'string') {
+        category = loaded.category;
+      }
+    }
+    out.push({ ...row, category });
+  }
+  return out;
+}
+
+/**
+ * Group category-enriched rows by category. Preserves appliedAt order
+ * within each group. Categories are returned sorted alphabetically;
+ * rows with no category collect under a final `null` group so the
+ * renderer can label them (`uncategorised`) without a magic string
+ * leaking into the group key.
+ *
+ * @param {Awaited<ReturnType<typeof enrichRowsWithCategories>>} rows
+ * @returns {Array<{ category: string | null, rows: typeof rows }>}
+ */
+export function groupRowsByCategory(rows) {
+  const buckets = new Map();
+  for (const row of rows) {
+    const key = typeof row.category === 'string' ? row.category : null;
+    if (!buckets.has(key)) buckets.set(key, []);
+    buckets.get(key).push(row);
+  }
+  const named = [...buckets.keys()]
+    .filter((k) => k !== null)
+    .sort((a, b) => a.localeCompare(b));
+  const groups = named.map((category) => ({ category, rows: buckets.get(category) }));
+  if (buckets.has(null)) groups.push({ category: null, rows: buckets.get(null) });
+  return groups;
+}

package/src/blueprint/loader.js

@@ -6,7 +6,7 @@
 // `scope: 'global'` tag plus a `topic` string; these are the only
 // contributions the conflict detector reasons about.
 //
-// The registry / git-ref resolver is a Phase 2 concern (SPA and REST
+// The registry / git-ref resolver is a Phase 2 concern (application-spa and application-api-rest
 // blueprints ship as npm packages); this loader intentionally has no
 // network path so tests are hermetic.
 
@@ -40,6 +40,17 @@ const EXCLUDED_KINDS = new Set(['fbs']);
  * @property {string} slug
  * @property {string} version
  * @property {string} source        source directory (absolute)
+ * @property {string} [category]    optional shelf-grouping tag; kebab slug.
+ *                                  Read by `rcf define blueprint list` and by
+ *                                  the docs blueprint shelf to group entries.
+ *                                  The starter vocabulary (`application`,
+ *                                  `security`, `email`, `deploy`, `delivery`,
+ *                                  `persistence`, `observability`) lives in
+ *                                  the authoring standard; the loader
+ *                                  validates the shape (kebab slug), not the
+ *                                  vocabulary, so a new category can be
+ *                                  minted by adding it to the standard
+ *                                  without a code change.
  * @property {BlueprintContribution[]} contributions
  */
 
@@ -82,6 +93,7 @@ export async function loadBlueprint(source) {
     slug: doc.slug,
     version: doc.version,
     source: root,
+    ...(typeof doc.category === 'string' ? { category: doc.category } : {}),
     contributions: Array.isArray(doc.contributions) ? doc.contributions : [],
   };
 }
@@ -96,6 +108,19 @@ function validateMetadata(doc, metaPath) {
   if (typeof doc.version !== 'string' || !/^\d+\.\d+\.\d+$/.test(doc.version)) {
     return rcfError({ kind: 'validation', message: `blueprint.json: version '${doc.version}' is not semver`, filePath: metaPath });
   }
+  if (doc.category !== undefined) {
+    // Category is optional; when present it must be a kebab slug (same
+    // shape as blueprint slug). The loader validates SHAPE only: the
+    // vocabulary (application, security, email, deploy, delivery,
+    // persistence, observability, and future additions) is documented
+    // in the authoring standard rather than pinned in code, so a new
+    // category minted at standard-review time does not need a loader
+    // change. The docs shelf and `rcf define blueprint list` render
+    // whatever category strings appear on the applied blueprints.
+    if (typeof doc.category !== 'string' || !/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/.test(doc.category)) {
+      return rcfError({ kind: 'validation', message: `blueprint.json: category '${doc.category}' is not a valid kebab slug`, filePath: metaPath });
+    }
+  }
   if (doc.contributions !== undefined && !Array.isArray(doc.contributions)) {
     return rcfError({ kind: 'validation', message: 'blueprint.json: contributions must be an array', filePath: metaPath });
   }