rcf-lite 0.20.0 → 0.22.0

package/blueprints/application-account-settings/probe-packs/application-account-settings.pack.mjs

@@ -0,0 +1,246 @@
+// application-account-settings probe pack (v1.0.0).
+//
+// Five capability-gated checks anchored to the blueprint AC ids:
+//   AC-25101-1 shell tabs mirror the applied capability set (always fires; guard-checked)
+//   AC-25102-1 profile surface renders with WCAG 1.3.5 autocomplete tokens (always fires)
+//   AC-25105-1 security surface renders the branch matching the applied capability +
+//              the elicited security-surface-shape (fires when credentialSelfService or
+//              hostedIdentityUi is applied)
+//   AC-25106-1 sessions surface lists rows and renders the ARIA APG dialog-modal on
+//              terminate (fires when sessionInventory is applied)
+//   AC-25108-1 theme surface renders the radiogroup and persists per the elicited
+//              theme-persistence (fires when application-spa is applied via caps)
+//
+// Every check drives the real Playwright browser the T-0 runner injects and reads
+// its per-check applicability from the blueprint applied sidecar
+// (rcf/blueprints/application-account-settings.applied.json) written by the apply
+// verb: an absent capability records verdict: skipped and the aggregate treats the
+// check as neither pass nor fail (spec section 3.3, rcf-schemas 0.6.1 has no
+// applicable: false field, per round-3 T-5 precedent).
+//
+// Sample-app fixture: packages/rcf-lite/test/fixtures/probe-pack-application-account-settings/.
+// The fixture ships CAPS and APPS env / ?caps= / ?apps= switches mirroring the
+// applied capability set so the pack can be probed for every fixture combination
+// on the shelf gate.
+
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+async function readAppliedCapabilities(projectRoot) {
+  if (!projectRoot) return [];
+  try {
+    const raw = await readFile(join(projectRoot, 'rcf', 'blueprints', 'application-account-settings.applied.json'), 'utf8');
+    const doc = JSON.parse(raw);
+    return Array.isArray(doc.appliedCapabilities) ? doc.appliedCapabilities.slice() : [];
+  } catch {
+    return [];
+  }
+}
+
+async function readAppliedElicitations(projectRoot) {
+  if (!projectRoot) return {};
+  try {
+    const raw = await readFile(join(projectRoot, 'rcf', 'blueprints', 'application-account-settings.applied.json'), 'utf8');
+    const doc = JSON.parse(raw);
+    return typeof doc.appliedElicitations === 'object' && doc.appliedElicitations ? doc.appliedElicitations : {};
+  } catch {
+    return {};
+  }
+}
+
+function withUrl(runtimeUrl, path) {
+  return new URL(path, runtimeUrl).toString();
+}
+
+export default {
+  packName: 'application-account-settings',
+  version: '1.0.0',
+  blueprintSlug: 'application-account-settings',
+  appliesTo: ({ fbs }) => {
+    const routes = fbs?.designStage?.navModel?.routes ?? [];
+    const tacIds = fbs?.contextRequirements?.tacIds ?? [];
+    if (tacIds.includes('TAC-2601-application-account-settings-shell')) return true;
+    return routes.some((r) => typeof r?.path === 'string' && /\/(account|settings|profile)(\/|$)/.test(r.path));
+  },
+  boot: { bootCommand: null, waitForUrl: null, waitForSelector: null },
+  checks: [
+    {
+      id: 'AC-25101-1',
+      severity: 'block',
+      description: 'Shell renders as an ARIA APG tabs region and its tabs mirror the union of applied capabilities plus the always-on profile tab; a tab whose capability is not applied does not render',
+      appliesTo: async () => true,
+      run: async ({ browser, runtimeUrl, projectRoot }) => {
+        if (!browser) return { verdict: 'fail', detail: 'no packBrowser wired' };
+        const caps = await readAppliedCapabilities(projectRoot);
+        await browser.goto(withUrl(runtimeUrl, '/account'));
+        const dom = await browser.evaluate(() => {
+          const nav = document.querySelector('nav[data-role="account-settings-nav"]');
+          if (!nav) return { present: false };
+          const tabs = Array.from(nav.querySelectorAll('[role="tab"]')).map((t) => t.getAttribute('data-tab-id'));
+          const role = nav.getAttribute('role');
+          const ariaLabel = nav.getAttribute('aria-label');
+          return { present: true, tabs, role, ariaLabel };
+        });
+        if (!dom.present) return { verdict: 'fail', detail: 'nav[data-role="account-settings-nav"] not found' };
+        if (dom.role !== 'tablist') return { verdict: 'fail', detail: `nav role expected tablist, got ${dom.role}` };
+        if (!dom.ariaLabel) return { verdict: 'fail', detail: 'nav missing aria-label (accessible name)' };
+        if (!dom.tabs.includes('profile')) return { verdict: 'fail', detail: `profile tab missing from ${JSON.stringify(dom.tabs)}` };
+        const securityExpected = caps.includes('credentialSelfService') || caps.includes('hostedIdentityUi');
+        const securityRendered = dom.tabs.includes('security');
+        if (securityExpected && !securityRendered) return { verdict: 'fail', detail: `security tab expected (caps=${JSON.stringify(caps)}) but not rendered` };
+        if (!securityExpected && securityRendered) return { verdict: 'fail', detail: `security tab rendered but caps=${JSON.stringify(caps)} declare neither credentialSelfService nor hostedIdentityUi (leak)` };
+        const sessionsExpected = caps.includes('sessionInventory');
+        const sessionsRendered = dom.tabs.includes('sessions');
+        if (sessionsExpected && !sessionsRendered) return { verdict: 'fail', detail: `sessions tab expected but not rendered` };
+        if (!sessionsExpected && sessionsRendered) return { verdict: 'fail', detail: `sessions tab rendered but sessionInventory not applied (leak)` };
+        return { verdict: 'pass', detail: `tabs=${JSON.stringify(dom.tabs)} caps=${JSON.stringify(caps)}` };
+      },
+    },
+    {
+      id: 'AC-25102-1',
+      severity: 'block',
+      description: 'Profile surface renders a form with WCAG 1.3.5 autocomplete tokens (name, email, bday, country) and a polite aria-live save-status region',
+      appliesTo: async () => true,
+      run: async ({ browser, runtimeUrl }) => {
+        if (!browser) return { verdict: 'fail', detail: 'no packBrowser wired' };
+        await browser.goto(withUrl(runtimeUrl, '/account/profile'));
+        const dom = await browser.evaluate(() => {
+          const form = document.querySelector('form[data-surface="profile"]');
+          if (!form) return { present: false };
+          const nameAuto = form.querySelector('input[name="name"]')?.getAttribute('autocomplete');
+          const emailAuto = form.querySelector('input[name="email"]')?.getAttribute('autocomplete');
+          const bdayAuto = form.querySelector('input[name="bday"]')?.getAttribute('autocomplete');
+          const countryAuto = form.querySelector('input[name="country"]')?.getAttribute('autocomplete');
+          const status = form.querySelector('[role="status"][aria-live="polite"]');
+          return { present: true, nameAuto, emailAuto, bdayAuto, countryAuto, statusPresent: !!status };
+        });
+        if (!dom.present) return { verdict: 'fail', detail: 'form[data-surface="profile"] not found' };
+        if (dom.nameAuto !== 'name') return { verdict: 'fail', detail: `name autocomplete token expected "name", got "${dom.nameAuto}"` };
+        if (dom.emailAuto !== 'email') return { verdict: 'fail', detail: `email autocomplete token expected "email", got "${dom.emailAuto}"` };
+        if (dom.bdayAuto !== 'bday') return { verdict: 'fail', detail: `bday autocomplete token expected "bday", got "${dom.bdayAuto}"` };
+        if (dom.countryAuto !== 'country') return { verdict: 'fail', detail: `country autocomplete token expected "country", got "${dom.countryAuto}"` };
+        if (!dom.statusPresent) return { verdict: 'fail', detail: 'save-status region [role="status"][aria-live="polite"] not found' };
+        return { verdict: 'pass', detail: `autocomplete tokens name+email+bday+country present; save-status present` };
+      },
+    },
+    {
+      id: 'AC-25105-1',
+      severity: 'block',
+      description: 'Security surface renders the self-service branch when credentialSelfService is applied and security-surface-shape=self-service; renders the hosted-link-out or hosted-embed branch when hostedIdentityUi is applied and security-surface-shape matches',
+      appliesTo: async ({ projectRoot }) => {
+        const caps = await readAppliedCapabilities(projectRoot);
+        return caps.includes('credentialSelfService') || caps.includes('hostedIdentityUi');
+      },
+      run: async ({ browser, runtimeUrl, projectRoot }) => {
+        if (!browser) return { verdict: 'fail', detail: 'no packBrowser wired' };
+        const caps = await readAppliedCapabilities(projectRoot);
+        const elicits = await readAppliedElicitations(projectRoot);
+        const shape = elicits['security-surface-shape'] ?? 'self-service';
+        await browser.goto(withUrl(runtimeUrl, `/account/security?security-surface-shape=${encodeURIComponent(shape)}`));
+        const dom = await browser.evaluate(() => {
+          const region = document.querySelector('[data-surface="security"]');
+          if (!region) return { present: false };
+          return {
+            present: true,
+            branch: region.getAttribute('data-branch'),
+            hasPassword: !!region.querySelector('[data-role="change-password"]'),
+            hasMfa: !!region.querySelector('[data-role="mfa-management"]'),
+            hasLinkOut: !!region.querySelector('[data-role="hosted-link-out"]'),
+            hasEmbed: !!region.querySelector('[data-role="hosted-embed"]'),
+            linkRel: region.querySelector('[data-role="hosted-link-out"]')?.getAttribute('rel'),
+            embedSandbox: region.querySelector('[data-role="hosted-embed"]')?.getAttribute('sandbox'),
+          };
+        });
+        if (!dom.present) return { verdict: 'fail', detail: '[data-surface="security"] not found' };
+        if (caps.includes('credentialSelfService') && shape === 'self-service') {
+          if (!dom.hasPassword) return { verdict: 'fail', detail: 'self-service branch missing [data-role="change-password"]' };
+          if (!dom.hasMfa) return { verdict: 'fail', detail: 'self-service branch missing [data-role="mfa-management"]' };
+        } else if (caps.includes('hostedIdentityUi') && shape === 'hosted-link-out') {
+          if (!dom.hasLinkOut) return { verdict: 'fail', detail: 'hosted-link-out branch missing [data-role="hosted-link-out"]' };
+          if (!/noopener/.test(dom.linkRel || '')) return { verdict: 'fail', detail: `hosted-link-out missing rel=noopener (rel="${dom.linkRel}")` };
+        } else if (caps.includes('hostedIdentityUi') && shape === 'hosted-embed') {
+          if (!dom.hasEmbed) return { verdict: 'fail', detail: 'hosted-embed branch missing [data-role="hosted-embed"]' };
+          if (!/allow-scripts/.test(dom.embedSandbox || '')) return { verdict: 'fail', detail: `hosted-embed sandbox missing allow-scripts (got "${dom.embedSandbox}")` };
+        } else {
+          return { verdict: 'fail', detail: `no branch matches caps=${JSON.stringify(caps)} shape="${shape}"` };
+        }
+        return { verdict: 'pass', detail: `branch=${dom.branch} caps=${JSON.stringify(caps)} shape="${shape}"` };
+      },
+    },
+    {
+      id: 'AC-25106-1',
+      severity: 'block',
+      description: 'Sessions surface renders one row per active session enumerated by data-session-id with device and last-active columns plus a terminate action; opens an ARIA APG dialog-modal on terminate',
+      appliesTo: async ({ projectRoot }) => {
+        const caps = await readAppliedCapabilities(projectRoot);
+        return caps.includes('sessionInventory');
+      },
+      run: async ({ browser, runtimeUrl }) => {
+        if (!browser) return { verdict: 'fail', detail: 'no packBrowser wired' };
+        await browser.goto(withUrl(runtimeUrl, '/account/sessions'));
+        const dom = await browser.evaluate(() => {
+          const region = document.querySelector('[data-surface="sessions"]');
+          if (!region) return { present: false };
+          const rows = Array.from(region.querySelectorAll('[data-session-id]'));
+          const ids = rows.map((r) => r.getAttribute('data-session-id'));
+          const firstRowColumns = rows[0] ? Array.from(rows[0].querySelectorAll('[data-column]')).map((c) => c.getAttribute('data-column')) : [];
+          const nonCurrentTerminates = rows.filter((r) => r.getAttribute('data-current-session') !== 'true').every((r) => !!r.querySelector('[data-action="terminate"]'));
+          const currentRow = rows.find((r) => r.getAttribute('data-current-session') === 'true');
+          const currentHasTerminate = currentRow ? !!currentRow.querySelector('[data-action="terminate"]') : false;
+          const dialog = region.querySelector('[role="dialog"][aria-modal="true"][data-role="terminate-confirm"]');
+          const dialogLabel = dialog ? dialog.getAttribute('aria-labelledby') : null;
+          const announce = region.querySelector('[role="status"][aria-live="polite"][data-role="session-terminated-announce"]');
+          return { present: true, ids, firstRowColumns, nonCurrentTerminates, currentHasTerminate, dialogPresent: !!dialog, dialogLabel, announcePresent: !!announce };
+        });
+        if (!dom.present) return { verdict: 'fail', detail: '[data-surface="sessions"] not found' };
+        if (dom.ids.length === 0) return { verdict: 'fail', detail: 'sessions surface rendered no rows with data-session-id' };
+        const required = ['device', 'lastActive'];
+        const missing = required.filter((c) => !dom.firstRowColumns.includes(c));
+        if (missing.length > 0) return { verdict: 'fail', detail: `sessions rows missing columns: ${JSON.stringify(missing)} present=${JSON.stringify(dom.firstRowColumns)}` };
+        if (!dom.nonCurrentTerminates) return { verdict: 'fail', detail: 'at least one non-current session row missing [data-action="terminate"]' };
+        if (dom.currentHasTerminate) return { verdict: 'fail', detail: 'the current-session row must not carry [data-action="terminate"]' };
+        if (!dom.dialogPresent) return { verdict: 'fail', detail: 'terminate confirmation dialog [role="dialog"][aria-modal="true"] not rendered' };
+        if (!dom.dialogLabel) return { verdict: 'fail', detail: 'dialog missing aria-labelledby' };
+        if (!dom.announcePresent) return { verdict: 'fail', detail: 'session-terminated announce region not rendered' };
+        return { verdict: 'pass', detail: `rows=${JSON.stringify(dom.ids)} columns=${JSON.stringify(dom.firstRowColumns)} dialog=${dom.dialogPresent}` };
+      },
+    },
+    {
+      id: 'AC-25108-1',
+      severity: 'block',
+      description: 'Theme surface renders as an ARIA APG radiogroup with light/dark/system options and persists per the elicited theme-persistence',
+      appliesTo: async ({ projectRoot }) => {
+        // The theme surface gates on application-spa being applied. On the
+        // fixture side we mirror this via the ?apps=application-spa switch.
+        // A future minor bump reads the manifest.blueprints[] set directly;
+        // for v1 the applied-blueprint set is inferred from the caps sidecar
+        // and the appliedElicitations map (theme-persistence answered => spa applied).
+        const elicits = await readAppliedElicitations(projectRoot);
+        return typeof elicits['theme-persistence'] === 'string';
+      },
+      run: async ({ browser, runtimeUrl, projectRoot }) => {
+        if (!browser) return { verdict: 'fail', detail: 'no packBrowser wired' };
+        const elicits = await readAppliedElicitations(projectRoot);
+        const persist = elicits['theme-persistence'] ?? 'spa-local-storage';
+        await browser.goto(withUrl(runtimeUrl, `/account/theme?apps=application-spa&theme-persistence=${encodeURIComponent(persist)}`));
+        const dom = await browser.evaluate(() => {
+          const region = document.querySelector('[data-surface="theme"]');
+          if (!region) return { present: false };
+          const role = region.getAttribute('role');
+          const ariaLabel = region.getAttribute('aria-label');
+          const persistAttr = region.getAttribute('data-persist');
+          const options = Array.from(region.querySelectorAll('input[type="radio"][name="theme"]')).map((el) => el.getAttribute('value'));
+          return { present: true, role, ariaLabel, persistAttr, options };
+        });
+        if (!dom.present) return { verdict: 'fail', detail: '[data-surface="theme"] not found' };
+        if (dom.role !== 'radiogroup') return { verdict: 'fail', detail: `role expected radiogroup, got ${dom.role}` };
+        if (!dom.ariaLabel) return { verdict: 'fail', detail: 'radiogroup missing aria-label' };
+        const required = ['light', 'dark', 'system'];
+        const missing = required.filter((v) => !dom.options.includes(v));
+        if (missing.length > 0) return { verdict: 'fail', detail: `radiogroup missing options: ${JSON.stringify(missing)} present=${JSON.stringify(dom.options)}` };
+        if (dom.persistAttr !== persist) return { verdict: 'fail', detail: `data-persist expected "${persist}", got "${dom.persistAttr}"` };
+        return { verdict: 'pass', detail: `role=${dom.role} options=${JSON.stringify(dom.options)} persist=${dom.persistAttr}` };
+      },
+    },
+  ],
+};

package/blueprints/application-admin-console/CHANGELOG.md

@@ -0,0 +1,11 @@
+# application-admin-console CHANGELOG
+
+## 1.0.0 (visual round T-5, spec 2026-09-04)
+
+- First ratified version of the shelf's admin-console blueprint. Six REQs (console shell with no dead links, conditional users, conditional roles with Owner + Admin + Member + Viewer baseline, conditional orgs, conditional audit-log, access-denied plus request-access), nine USs 21101-21109 binding 16 runtime-observable ACs, four TACs 2201-2204 (shell, capability discovery, permission matrix, audit view consuming datatable), four ADRs 2201-2204 (capability vocabulary, baseline roles, invite transport, audit retention). No new global topics.
+- Introduces the capability-declaration mechanism: `capabilities[]` on identity blueprints (v1.1.0 minor bumps on magic-link, clerk, oauth2, keycloak land in the same PR per spec Q2 default), `requiresAppliedCapabilities` and `elicits[]` on consumer blueprints, apply-time discovery via source read-back on `manifest.blueprints[]`, exit-3 refusal with the spec 5.5.1 verbatim message on bare-SPA applies, and a `--allow-no-auth-yet` operator override.
+- Persists per-project apply-time state in a sidecar `rcf/blueprints/application-admin-console.applied.json` (the applied-blueprint-record schema in rcf-schemas 0.6.0 is closed under additionalProperties:false; the source-manifest read-back precedent from the T-2 core-companions train applies here). The sidecar carries `appliedCapabilities`, `appliedElicitations`, `allowNoAuthYet?` and `notes?`.
+- Ships `probe-packs/application-admin-console.pack.mjs`: four capability-gated browser-verify checks anchored to AC-21102-1 (users), AC-21103-1 (permission matrix), AC-21104-1 (org switcher), AC-21105-1 (audit-log surface). Each check reads the applied capability sidecar and records `applicable: false` where its required capability is absent (T-5 residual cure). Fifth shipped consumer of T-0's probe-pack runner extension.
+- Ships a dependency-free sample-app fixture at `packages/rcf-lite/test/fixtures/probe-pack-application-admin-console/` with `CAPS` env or `?caps=` query switch selecting which surfaces exist, break switches for the negative runs (matrix-grid, denied, audit-fields), and the mandatory README for the gate reviewer.
+- Consumes `application-datatable` (T-1) for the users and audit surfaces; declares `suggestedCompanions` logging and errorHandling.
+- Does NOT declare `providesRoles` per spec 5.5.3 (the console is a consumer of `principalDirectory`, never a provider).

package/blueprints/application-admin-console/README.md

@@ -0,0 +1,98 @@
+# Admin console blueprint (v1.0.0)
+
+Vendor-neutral admin-console shell for an rcf-lite application. Surfaces are CONDITIONAL on what the applied identity blueprint declares. Ships the console shell with navigation across the applied surfaces (no dead links to unapplied capabilities), a users directory with invite and deactivate controls, a permission matrix rendered as an ARIA APG grid with the Owner + Admin + Member + Viewer baseline, an org switcher for multi-tenant projects, an audit-log surface reading a delivered event stream, and an access-denied and request-access state per WCAG. Introduces the capability-declaration mechanism (`capabilities[]` on identity blueprints) and the apply-time discovery, refusal and custom-auth elicitation the spec section 5.5 ratifies. Ships a Playwright probe pack under `probe-packs/application-admin-console.pack.mjs` whose four checks are capability-gated: an absent capability records `applicable: false` and the aggregate verdict treats it as neither pass nor fail (spec section 3.3).
+
+## Apply
+
+```
+rcf define blueprint add <path-to>/blueprints/application-admin-console
+```
+
+Refuses with exit 3 and the spec 5.5.1 verbatim message on a project with no applied blueprint declaring `principalDirectory` unless `--allow-no-auth-yet` is passed for a scaffolding pass. Prompts the elicitation phase for parameters whose `when` predicate resolves true against the discovered applied-capability set. Writes a sidecar `rcf/blueprints/application-admin-console.applied.json` capturing the discovered `appliedCapabilities`, the elicit answers, and (when overridden) the scaffolding-note. Consumes the `logging` and `errorHandling` companions when they resolve to an applied provider or a registered library; falls back to the shelf providers otherwise.
+
+## Anatomy
+
+| Piece | Where | What |
+|---|---|---|
+| Metadata | `blueprint.json` | Slug, version 1.0.0, category `application`, `requiresAppliedCapabilities: [principalDirectory]`, `elicits[]` (baseline-roles, tenancy-shape, invite-transport, audit-retention-days), `suggestedCompanions: [logging, errorHandling]`, 23 contributions in the 22xx / 21xxx band |
+| Doc set | `contributions/` | 6 REQs, 9 USs (16 runtime-observable ACs), 4 TACs, 4 ADRs |
+| Probe pack | `probe-packs/application-admin-console.pack.mjs` | Four capability-gated browser-verify checks anchored to AC-21102-1, AC-21103-1, AC-21104-1, AC-21105-1 |
+| Guide | `guide/application-admin-console.md` | Operator-facing: when to reach, when not, mechanism-reach gaps |
+| Coordination vocabulary | `docs/topics.md` | Shelf id band registry update; no new global topics claimed |
+| Sample-app fixture | `packages/rcf-lite/test/fixtures/probe-pack-application-admin-console/` | Dependency-free Node HTTP server the pack is probed against on the shelf gate |
+
+## Conditionality: what surfaces render when
+
+| Applied capability | Surface | Rendered by |
+|---|---|---|
+| `principalDirectory` | Users directory (`/admin/users`) | Any applied auth blueprint (magic-link, clerk, oauth2, keycloak). |
+| `roleModel` | Permission matrix (`/admin/roles`) | Clerk, OAuth2, Keycloak. Magic-link does NOT declare it, so a bare-magic-link project gets NO roles surface (Baz's example, spec section 5.5). |
+| `tenancy` | Org switcher (`/admin/orgs`), org-scoped invites | Reserved for a future `application-tenancy-orgs` blueprint (spec section 11). No shelf provider today. |
+| `auditLog` | Audit-log surface (`/admin/audit`) | Via the applied `observability-logging` companion (implicit), or a future dedicated audit-log blueprint. |
+| (none) | Access-denied + request-access | Always renders for a non-admin principal reaching `/admin/*`. |
+
+## Bare-SPA refusal
+
+On a project with only `application-spa` applied (no auth), the apply exits 3 with:
+
+```
+application-admin-console requires at least one applied security-auth-* blueprint,
+or an operator override with --allow-no-auth-yet.
+
+Applied blueprints on this project:
+  application-spa v1.5.0
+
+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 application-admin-console --allow-no-auth-yet
+```
+
+The override records a note on the sidecar's `notes` field so `rcf define validate` reads back and flags surfaces that never activated.
+
+## Custom-auth projects (auth outside the shelf)
+
+A project that ships its own auth surface (no shelf `security-auth-*` blueprint applied) supplies capability answers via the elicitation phase:
+
+```
+rcf define blueprint add ./blueprints/application-admin-console \
+  --answer baseline-roles="Owner, Admin, Member, Viewer, SupportAgent" \
+  --answer tenancy-shape=per-user \
+  --answer invite-transport=email
+```
+
+Answers land on `rcf/blueprints/application-admin-console.applied.json`'s `appliedElicitations{}` map. The `when` predicate on each elicit gates whether the prompt fires: `baseline-roles` only fires when `roleModel` is applied, `tenancy-shape` only when `tenancy` is applied, and so on.
+
+## The one runtime gate
+
+`probe-packs/application-admin-console.pack.mjs` ships four checks the `rcf verify browser` runner invokes on any FBS whose surface matches the pack's `appliesTo` predicate (an FBS that binds `TAC-2201-application-admin-console-shell` or whose nav model routes name an admin path). Each check ALSO carries its own `appliesTo` predicate that reads the applied capability sidecar and returns false when the required capability is absent; the check records `applicable: false` and the aggregate verdict treats it as neither pass nor fail (spec section 3.3, T-5 residual cure). This is exactly the residual pattern the spec named: the surface does not exist, so the pack does not fire.
+
+Each check drives the real Playwright browser the runner provisions (through the pinned Playwright MCP or the consuming project's own `playwright` installation), reads the accessibility tree and the DOM, and returns a verdict.
+
+## Quality bar
+
+ARIA APG grid pattern on the permission matrix (ADR-2201, TAC-2203); role="row", role="rowheader", role="columnheader", role="gridcell" and per-cell aria-label announcing the permission string on focus (WCAG 4.1.3). Every access-denied state renders under WCAG 2.4.6 Headings and Labels and 3.3.4 Error Prevention with a keyboard-reachable request-access control and a polite live region announcing state changes. Every table surface enumerates rows by `data-<entity>-id` (users by `data-user-id`, audit entries by `data-audit-id`) inside the `data-surface` region. The Owner + Admin + Member + Viewer baseline is drawn from SaaS UI research 2026 (ADR-2202); the retention window on the audit view is elicited per project (ADR-2204).
+
+## Known mechanism-reach gaps
+
+Runtime-observable ACs the pack does NOT bind directly (checklist section 6.g), listed individually:
+
+- **AC-21101-2 (single primary nav landmark with accessible name).** Present on the fixture as `<nav data-role="primary-nav" aria-label="Admin console">`; the pack asserts the fixture renders the four surfaces but does not additionally probe the landmark's accessible name. A v1.1.0 minor bump can add a landmark-shape check driven by the accessibility tree.
+- **AC-21102-2 (per-row invite / deactivate control shape).** Present on the fixture as `[data-action="invite"]` and `[data-action="deactivate"]` buttons; the pack's AC-21102-1 check confirms the users directory renders row ids but does not additionally exercise the invite / deactivate click paths. A v1.1.0 minor bump can extend AC-21102-1 with a click-round-trip.
+- **AC-21103-2 (elicited additional roles rendered after the baseline four).** Present on the fixture as the Owner + Admin + Member + Viewer rank order; the pack's AC-21103-1 confirms the grid roles and per-cell announcements but does not additionally probe elicited-role position. A v1.1.0 minor bump can read the sidecar's `appliedElicitations.baseline-roles` and compare rank order.
+- **AC-21105-2 (audit view consumes the datatable shell TAC).** Realised on the fixture by rendering the audit table with the same column contract; the pack's AC-21105-1 confirms the correlation-id column but does not additionally probe the datatable shell's four state regions on the audit view. Datatable's own pack (T-1) still covers those on projects that render the audit view through the datatable factory.
+- **AC-21106-1 (access-denied region accessibility structure beyond the request-access control).** The pack's AC-21102-1 check probes the request-access control on the denied branch; the wider WCAG structure (heading, explanation, polite live region wiring) is present on the fixture but not additionally asserted. A v1.1.0 minor bump can add an axe-core sweep on the denied region.
+- **AC-21107-1 (sidecar file served under a stable path).** The pack reads the sidecar from `projectRoot`; the CLIENT-side read (over the network at load time) is a runtime-observable surface the pack does not additionally probe. A v1.1.0 minor bump can add a probe that reads `/admin/caps.json` on the fixture and diffs against the applied sidecar.
+- **AC-21108-1 (providesRoles absent on the blueprint).** A chain-scope AC probed by the anatomy tests, not by the browser pack.
+- **AC-21109-1 and AC-21109-2 (apply-time refusal and override).** Probed by the mechanism unit tests, not by the browser pack. The gate reviewer runs the CLI directly.
+
+## Companions
+
+`suggestedCompanions` declares `logging` (the audit-log surface reads the event stream the applied logger emits) and `errorHandling` (invite failures and role-change refusals construct internal error records). Neither is required to apply the blueprint; the audit surface simply suppresses when `logging` is not applied.
+
+## Consumers
+
+The audit view consumes `application-datatable` (T-1) for its table shell contract. Every project applying `application-admin-console` should also apply `application-datatable` if they want the ARIA APG table pattern, filter chrome, four state regions and pagination on the audit view.

package/blueprints/application-admin-console/blueprint.json

@@ -0,0 +1,226 @@
+{
+  "slug": "application-admin-console",
+  "version": "1.0.0",
+  "category": "application",
+  "requiresAppliedCapabilities": {
+    "capabilities": [
+      "principalDirectory"
+    ],
+    "allowSkipFlag": "allow-no-auth-yet",
+    "refusalMessageId": "application-admin-console-bare-spa"
+  },
+  "elicits": [
+    {
+      "id": "custom-auth-provides-principal-directory",
+      "prompt": "Custom auth: does your project's own auth blueprint expose a principal directory (identity records the users surface can list)?",
+      "kind": "boolean",
+      "default": false,
+      "providesCapability": "principalDirectory"
+    },
+    {
+      "id": "custom-auth-provides-role-model",
+      "prompt": "Custom auth: does your project's own auth declare operator-visible role labels a permission matrix can render?",
+      "kind": "boolean",
+      "default": false,
+      "providesCapability": "roleModel"
+    },
+    {
+      "id": "custom-auth-provides-tenancy",
+      "prompt": "Custom auth: does your project's own auth (or a paired tenancy blueprint) declare an organisation abstraction the console can switch across?",
+      "kind": "boolean",
+      "default": false,
+      "providesCapability": "tenancy"
+    },
+    {
+      "id": "custom-auth-provides-audit-log",
+      "prompt": "Custom auth: does your project emit an audit event stream the console's audit view can read?",
+      "kind": "boolean",
+      "default": false,
+      "providesCapability": "auditLog"
+    },
+    {
+      "id": "baseline-roles",
+      "prompt": "Baseline role labels for the permission matrix (comma-separated). Owner, Admin, Member, Viewer is the ratified default; extend with per-project labels here.",
+      "kind": "string",
+      "default": "Owner, Admin, Member, Viewer",
+      "when": {
+        "requiresCapability": [
+          "roleModel"
+        ]
+      }
+    },
+    {
+      "id": "tenancy-shape",
+      "prompt": "Tenancy shape for the org switcher: per-user (users belong to one org), per-org (all users belong to every org they can see) or both.",
+      "kind": "enum",
+      "options": [
+        "per-user",
+        "per-org",
+        "both"
+      ],
+      "default": "per-user",
+      "when": {
+        "requiresCapability": [
+          "tenancy"
+        ]
+      }
+    },
+    {
+      "id": "invite-transport",
+      "prompt": "Invite transport: email delegates to the email sibling when present; in-app-only records the invite as a notification; custom hands the delivery to your own transport at surface time.",
+      "kind": "enum",
+      "options": [
+        "email",
+        "in-app-only",
+        "custom"
+      ],
+      "default": "email"
+    },
+    {
+      "id": "audit-retention-days",
+      "prompt": "Audit-log retention window in days. The applied logger enforces retention at the write layer; the console reads the same window.",
+      "kind": "string",
+      "default": "90",
+      "when": {
+        "requiresCapability": [
+          "auditLog"
+        ]
+      }
+    }
+  ],
+  "suggestedCompanions": [
+    {
+      "role": "logging",
+      "reason": "The audit-log surface reads the event stream the applied logger emits; without a logging companion, the audit surface has no source and is suppressed at apply."
+    },
+    {
+      "role": "errorHandling",
+      "reason": "Invite failures and role-change refusals construct internal error records; an error-handling companion supplies the record factory and the boundary."
+    }
+  ],
+  "contributions": [
+    {
+      "id": "application-admin-console-REQ-001",
+      "kind": "req",
+      "path": "requirements/application-admin-console-req-001.json"
+    },
+    {
+      "id": "application-admin-console-REQ-002",
+      "kind": "req",
+      "path": "requirements/application-admin-console-req-002.json"
+    },
+    {
+      "id": "application-admin-console-REQ-003",
+      "kind": "req",
+      "path": "requirements/application-admin-console-req-003.json"
+    },
+    {
+      "id": "application-admin-console-REQ-004",
+      "kind": "req",
+      "path": "requirements/application-admin-console-req-004.json"
+    },
+    {
+      "id": "application-admin-console-REQ-005",
+      "kind": "req",
+      "path": "requirements/application-admin-console-req-005.json"
+    },
+    {
+      "id": "application-admin-console-REQ-006",
+      "kind": "req",
+      "path": "requirements/application-admin-console-req-006.json"
+    },
+    {
+      "id": "application-admin-console-US-21101",
+      "kind": "us",
+      "path": "user-stories/application-admin-console-us-21101.json"
+    },
+    {
+      "id": "application-admin-console-US-21102",
+      "kind": "us",
+      "path": "user-stories/application-admin-console-us-21102.json"
+    },
+    {
+      "id": "application-admin-console-US-21103",
+      "kind": "us",
+      "path": "user-stories/application-admin-console-us-21103.json"
+    },
+    {
+      "id": "application-admin-console-US-21104",
+      "kind": "us",
+      "path": "user-stories/application-admin-console-us-21104.json"
+    },
+    {
+      "id": "application-admin-console-US-21105",
+      "kind": "us",
+      "path": "user-stories/application-admin-console-us-21105.json"
+    },
+    {
+      "id": "application-admin-console-US-21106",
+      "kind": "us",
+      "path": "user-stories/application-admin-console-us-21106.json"
+    },
+    {
+      "id": "application-admin-console-US-21107",
+      "kind": "us",
+      "path": "user-stories/application-admin-console-us-21107.json"
+    },
+    {
+      "id": "application-admin-console-US-21108",
+      "kind": "us",
+      "path": "user-stories/application-admin-console-us-21108.json"
+    },
+    {
+      "id": "application-admin-console-US-21109",
+      "kind": "us",
+      "path": "user-stories/application-admin-console-us-21109.json"
+    },
+    {
+      "id": "TAC-2201-application-admin-console-shell",
+      "kind": "tac",
+      "path": "tacs/tac-2201-application-admin-console-shell.json"
+    },
+    {
+      "id": "TAC-2202-application-admin-console-capability-discovery",
+      "kind": "tac",
+      "path": "tacs/tac-2202-application-admin-console-capability-discovery.json"
+    },
+    {
+      "id": "TAC-2203-application-admin-console-permission-matrix",
+      "kind": "tac",
+      "path": "tacs/tac-2203-application-admin-console-permission-matrix.json"
+    },
+    {
+      "id": "TAC-2204-application-admin-console-audit-view",
+      "kind": "tac",
+      "path": "tacs/tac-2204-application-admin-console-audit-view.json"
+    },
+    {
+      "id": "ADR-2201-application-admin-console-capability-vocabulary",
+      "kind": "adr",
+      "path": "adrs/adr-2201-application-admin-console-capability-vocabulary.json",
+      "standardsTraceClause": "generic enterprise practice"
+    },
+    {
+      "id": "ADR-2202-application-admin-console-baseline-roles",
+      "kind": "adr",
+      "path": "adrs/adr-2202-application-admin-console-baseline-roles.json",
+      "elicited": true,
+      "standardsTraceClause": "SaaS UI research 2026"
+    },
+    {
+      "id": "ADR-2203-application-admin-console-invite-transport",
+      "kind": "adr",
+      "path": "adrs/adr-2203-application-admin-console-invite-transport.json",
+      "recommendedDefault": true,
+      "elicited": true,
+      "standardsTraceClause": "generic enterprise practice"
+    },
+    {
+      "id": "ADR-2204-application-admin-console-audit-retention",
+      "kind": "adr",
+      "path": "adrs/adr-2204-application-admin-console-audit-retention.json",
+      "elicited": true,
+      "standardsTraceClause": "generic enterprise practice"
+    }
+  ]
+}

package/blueprints/application-admin-console/contributions/adrs/adr-2201-application-admin-console-capability-vocabulary.json

@@ -0,0 +1,25 @@
+{
+  "adrId": "ADR-2201-application-admin-console-capability-vocabulary",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Capability vocabulary: principalDirectory, roleModel, tenancy, auditLog as the v1 capability set",
+  "context": "Admin-console surfaces are conditional on what the applied identity blueprint provides. The vocabulary must be small (four strings today), extensible (the section 6a table is chunk-zero, so a future capability lands with a docs edit and no code change), and grounded in industry practice (SaaS UI research, IAM literature). Baz decision 5 (2026-09-04) is that the initial four capabilities are principalDirectory, roleModel, tenancy and auditLog.",
+  "decision": "v1.0.0 declares four capability strings the applied identity blueprints can declare in their capabilities[] field: principalDirectory (identifies principals for a users surface); roleModel (declares operator-visible role labels for a permission matrix); tenancy (declares an organisation abstraction the console can switch across); auditLog (emits an event stream the audit view can read). The vocabulary lives in packages/rcf-lite/docs/blueprint-authoring.md section 6a as a table extending the roles registry; the loader validates capability SHAPE (lower camelCase on ^[a-z][a-zA-Z0-9]*$), not the vocabulary. A future capability lands by adding a table row and adopting it on an identity blueprints minor bump.",
+  "consequences": "The console renders only surfaces the applied capabilities enable, so a bare magic-link project gets a users surface but no roles surface (per Bazs verbatim example). A future dedicated audit-log blueprint declaring auditLog directly (rather than through observability-logging) composes cleanly. A new capability lands additively.",
+  "alternativesConsidered": [
+    {
+      "name": "Encode the vocabulary in code as an enum",
+      "summary": "Refuse any capability string outside the initial four at the loader.",
+      "reasonNotChosen": "Constrains a future capability behind a rcf-lite release; the section 6a chunk-zero pattern is the ratified convention for vocabulary in prose."
+    },
+    {
+      "name": "Use providesRoles[] for capabilities",
+      "summary": "Overload the existing providesRoles[] field to carry capabilities.",
+      "reasonNotChosen": "providesRoles paired with a scope:global ADR by design; a capability is a projection of the applied blueprints own state, not a role it offers to a second consumer. Overloading blurs the mechanism (spec 5.5.3)."
+    }
+  ],
+  "createdAt": "2026-09-05T01:30:00Z",
+  "updatedAt": "2026-09-05T01:30:00Z"
+}