rcf-lite 0.20.0 → 0.22.0

package/blueprints/application-notifications-in-app/guide/application-notifications-in-app.md

@@ -0,0 +1,47 @@
+# Guide: application-notifications-in-app (v1.0.0)
+
+## What it is
+
+A shipped, vendor-neutral in-app-notifications contract for a rcf-lite application. Ships the live-region preseeding discipline (TAC-2101), the transient-toast contract with the priority-to-role mapping (ADR-2101) and the WCAG 2.2.1 six-second timeout floor (ADR-2102), the notification-centre inbox with the ADR-2103 retention window and the per-item acknowledge round-trip (TAC-2102), the per-user preferences UI with category silence and sibling-channel delegation (TAC-2103), and the delivery-attempt log write path (REQ-005, TAC-2102). Ships a Playwright probe pack that gates ship on the three runtime-observable surfaces the shelf assures: both live-region wrappers are preseeded on every declared route before any notification fires, every toast maps priority to the correct wrapper and role with an announcement measured against the six-second floor, and every centre acknowledge control round-trips to the server with the DOM updating on the response.
+
+## What it deliberately is not
+
+- Not a notifications transport. The in-app slug is the discriminator; sibling channel blueprints under the reserved `application-notifications-` family prefix ship their own transports. This blueprint ships no email, no Web Push, no webhook.
+- Not a notifications store. The delivery-attempt log's persistence layer is the applied `logging` companion's; this blueprint owns the row shape and delegates the write path.
+- Not a preferences store. The preferences UI records intent on the surface (category silence, digest opt-in); the store where those preferences persist is the applying project's, and each sibling channel blueprint reads its own share of the intent.
+
+## When to reach for it
+
+- Any shipped rcf-lite application whose operators need transient toasts, a durable notification centre and per-user category silence. Web SaaS applications, admin consoles, dashboards with alerting.
+- Projects that want the WCAG 4.1.3 status-message discipline and the WCAG 2.2.1 timeout floor enforced at ship without hand-authoring the live-region contract.
+- Projects that expect to add sibling channels (email digest, Web Push, webhooks) later: the family-prefix reservation and the preferences UI's sibling-delegation shape land the discipline early.
+
+## When it does not fit
+
+- Server-to-server notifications with no operator surface. If nobody reads the notification on a screen, this blueprint's contract is expensive noise; use a logging blueprint alone.
+- A project whose notifications are single-channel and channel-first (an SMS-only alert product) where the in-app slot is not the primary surface. The sibling channel blueprint is the fit; the in-app blueprint composes later if the surface grows.
+- Highly bespoke chat-like surfaces (a support-inbox blueprint, a workflow-review inbox) where the accessibility contract differs from the WCAG 4.1.3 status-message discipline. Supersede this blueprint with a project-authored REQ naming the residual, or apply a different chat-oriented blueprint.
+
+## What a good outcome looks like
+
+Every route the applying project ships preseeds both live-region wrappers in the DOM at page load; no announcement race is possible. Every toast writes into exactly one wrapper based on its priority (info to polite as `role="status"`, error to assertive as `role="alert"`) and stays visible for six seconds unless dismissed; the reader hears an interruption exactly when the application asserts one. The notification centre lists notifications within the retention window with every item Tab-reachable and every acknowledge round-tripping to the server. The preferences UI carries per-category silence toggles and clearly labels any sibling channel that is not yet applied. The shipped probe pack runs green on the delivery-ci-workflows gate.
+
+## The operator decisions that remain open
+
+- **Toast timeout floor** (ADR-2102). Six seconds by default; operator elicits a longer dwell time if the surface has a very high notification volume.
+- **Notification categories** (REQ-004). Payment, security and product are the shipped default categories on the fixture; the operator elicits their own category list at apply.
+- **Centre retention window** (ADR-2103). Thirty days by default; operator elicits a longer or shorter window at apply.
+- **Notification centre route path** (REQ-003 note). `/notifications-centre` by default; operator elicits an override for a bespoke route.
+- **Sibling channels applied** (REQ-004 note). Which of `-email`, `-push`, `-webhook` (or a project-authored sibling) is applied on the project; discovered, not elicited, from the manifest.
+
+## Common gotchas
+
+- The two live-region wrappers must be preseeded before the first notification. A lazy-mount defect is silent at the DOM (the wrapper appears "eventually") but loses the first announcement at the assistive-technology layer. The pack refuses ship on this shape.
+- The priority-to-role mapping is fixed at v1.0.0 (info to polite/status, error to assertive/alert). A third priority (`warning`) is a v1.1 minor bump because it changes the role vocabulary; free-form priorities are refused at project-side review.
+- The toast timeout floor is a floor, not a ceiling. Six seconds is the default; an operator-elicited value above the floor is honoured (thirty seconds), a value below the floor is refused at apply. The pack measures the actual elapsed time against the shell root's declared floor and against the six-second baseline; both must clear.
+- The centre enumerates items by `data-notification-id`, per the T-3 gate discipline. A centre implementation that uses only `role="listitem"` on the children (without a per-element id attribute) passes the accessibility contract but does not let the pack enumerate individual items reliably; ship both.
+- The family-prefix reservation is documented; naming a future notifications blueprint outside the family (`application-alerts-email`) reads against the reservation and stops at author-side review.
+
+## Cost honesty
+
+Shipping this blueprint costs the project a design pass on the notification categories and retention window, and a build pass on the live-region factory and the centre inbox surface. It buys the WCAG 4.1.3 and WCAG 2.2.1 disciplines enforced at ship, the ARIA APG alert pattern on the assertive slot, the centre inbox with the acknowledge round-trip, the preferences UI with sibling delegation, and the family-prefix reservation that survives when the shelf grows a second notifications channel. The gate reviewer verifies the pack runs green against the sample-app fixture and reviews the applying project's own notifications surfaces against the ADR set.

package/blueprints/application-notifications-in-app/probe-packs/application-notifications-in-app.pack.mjs

@@ -0,0 +1,328 @@
+// application-notifications-in-app probe pack (v1.0.0).
+//
+// Three runtime-observable checks anchored to the blueprint's ACs:
+//   AC-20101-1 live-region preseeding (both wrappers present AND empty
+//              at load on every declared route)
+//   AC-20102-1 transient toast contract (priority-to-role mapping,
+//              one-shot announcement, timeout measured against the
+//              ADR-2102 six-second floor via data-shown-at /
+//              data-dismissed-at timestamps rather than a sleep in
+//              the pack)
+//   AC-20103-1 centre acknowledge round-trip (Tab-reachable acknowledge
+//              control POSTs to the server, the server responds, the
+//              DOM updates in response; enumerated by data-notification-id
+//              per the T-3 gate discipline, never by role alone)
+//
+// Every check drives the real Playwright browser the T-0 runner
+// injects (packages/rcf-lite/src/browser-verify/pack-browser.js) and
+// asserts on the DOM the applying project renders under TAC-2101
+// (live-region wrappers and toast factory), TAC-2102 (centre inbox
+// and acknowledge round-trip) and the priority-to-role mapping per
+// ADR-2101.
+//
+// The pack has no network-interception seam (T-0 shipped none); the
+// acknowledge round-trip is captured through the request log the
+// sample app exposes on window.__notificationFetches and at
+// GET /__requests. The toast timeout is measured with browser.evaluate
+// reading timestamps the sample app records on the toast element
+// (data-shown-at and data-dismissed-at), polled with a bounded loop
+// so the pack does not sleep for six seconds on the happy path.
+
+export default {
+  packName: 'application-notifications-in-app',
+  version: '1.0.0',
+  blueprintSlug: 'application-notifications-in-app',
+  // Applies to any FBS that realises the live-region TAC or whose
+  // navModel routes include a notifications-centre path. The source
+  // references BOTH `tacIds` and `route` so the T-0 loader's
+  // applicability source-scan sees the two legal seams (route is one
+  // of the three legal predicates).
+  appliesTo: ({ fbs }) => {
+    const routes = fbs?.designStage?.navModel?.routes ?? [];
+    const tacIds = fbs?.contextRequirements?.tacIds ?? [];
+    if (tacIds.includes('TAC-2101-application-notifications-in-app-live-region')) return true;
+    return routes.some((r) => typeof r?.path === 'string' && /notifications-centre/.test(r.path));
+  },
+  boot: { bootCommand: null, waitForUrl: null, waitForSelector: null },
+  checks: [
+    {
+      id: 'AC-20101-1',
+      severity: 'block',
+      description: 'Live-region preseeded on every declared route: both the polite wrapper ([aria-live="polite"] [data-live-region="polite"]) and the assertive wrapper ([role="alert"] [data-live-region="assertive"]) are preseeded and empty in the DOM at page load, before any notification fires. Enumerated by the per-element [data-live-region] attribute (never by aria-live or role alone).',
+      run: async ({ browser, runtimeUrl }) => {
+        if (!browser) return { verdict: 'fail', detail: 'no packBrowser wired' };
+        const routes = ['/', '/notifications-centre', '/notifications-preferences'];
+        const perRoute = [];
+        for (const path of routes) {
+          // Preserve the reviewer's --url query verbatim across every
+          // route navigation: swap the pathname, keep the search.
+          const target = new URL(runtimeUrl);
+          target.pathname = path;
+          await browser.goto(target.toString());
+          const measurement = await browser.evaluate(() => {
+            const polite = document.querySelector('[data-live-region="polite"]');
+            const assertive = document.querySelector('[data-live-region="assertive"]');
+            function inspect(el) {
+              if (!el) return null;
+              return {
+                tag: el.tagName,
+                ariaLive: el.getAttribute('aria-live'),
+                role: el.getAttribute('role'),
+                dataLiveRegion: el.getAttribute('data-live-region'),
+                childCount: el.childElementCount,
+                textLength: (el.textContent || '').trim().length,
+              };
+            }
+            return { polite: inspect(polite), assertive: inspect(assertive) };
+          });
+          perRoute.push({ path, measurement });
+        }
+        const failures = [];
+        for (const entry of perRoute) {
+          if (!entry.measurement.polite) {
+            failures.push({ path: entry.path, reason: 'polite wrapper missing at page load (preseeded wrappers are required per Sara Soueidan normative guidance)' });
+            continue;
+          }
+          if (!entry.measurement.assertive) {
+            failures.push({ path: entry.path, reason: 'assertive wrapper missing at page load' });
+            continue;
+          }
+          if (entry.measurement.polite.ariaLive !== 'polite') {
+            failures.push({ path: entry.path, reason: 'polite wrapper missing aria-live="polite"' });
+          }
+          if (entry.measurement.assertive.role !== 'alert') {
+            failures.push({ path: entry.path, reason: 'assertive wrapper missing role="alert"' });
+          }
+          if (entry.measurement.polite.textLength > 0 || entry.measurement.polite.childCount > 0) {
+            failures.push({ path: entry.path, reason: 'polite wrapper carries content at page load (must be empty until a notification fires)' });
+          }
+          if (entry.measurement.assertive.textLength > 0 || entry.measurement.assertive.childCount > 0) {
+            failures.push({ path: entry.path, reason: 'assertive wrapper carries content at page load (must be empty until a notification fires)' });
+          }
+        }
+        if (failures.length > 0) {
+          return { verdict: 'fail', detail: 'live-region preseeded contract broken: ' + JSON.stringify(failures) };
+        }
+        return { verdict: 'pass', detail: 'live-region wrappers preseeded and empty on every declared route: ' + JSON.stringify(perRoute.map((r) => ({ path: r.path, polite: r.measurement.polite, assertive: r.measurement.assertive }))) };
+      },
+    },
+    {
+      id: 'AC-20102-1',
+      severity: 'block',
+      description: 'Transient toast contract: an info-priority toast renders inside the polite wrapper with role="status", an error-priority toast renders inside the assertive wrapper with role="alert" (per ADR-2101 priority-to-role mapping); every toast body appears in exactly one wrapper (never both); every toast records data-shown-at and data-dismissed-at, and a timeout-dismissed toast carries an elapsed time at or above the ADR-2102 six-second floor per WCAG 2.2.1.',
+      run: async ({ browser, runtimeUrl }) => {
+        if (!browser) return { verdict: 'fail', detail: 'no packBrowser wired' };
+        const target = new URL('', runtimeUrl).toString();
+        await browser.goto(target);
+        // Read the shell's declared timeout floor (defaults to six
+        // seconds per ADR-2102; may be overridden above the floor).
+        const shellFloorSeconds = await browser.evaluate(() => {
+          const root = document.querySelector('[data-region="shell-root"]');
+          const value = root && root.getAttribute('data-toast-timeout-floor-seconds');
+          return value ? Number(value) : 6;
+        });
+        // Fire one info toast and one error toast through the triggers
+        // the fixture ships; a real applying project may drive the
+        // same shape via a click on its own trigger, an evaluate hook,
+        // or a background-event dispatch.
+        await browser.click('[data-toast-trigger="info"]');
+        await browser.click('[data-toast-trigger="error"]');
+        // Poll for both toasts to dismiss (bounded loop; cap slightly
+        // above the shell's floor so a six-second floor passes and a
+        // two-second break-timeout run still finishes in time).
+        const capMs = Math.max(shellFloorSeconds * 1000, 6000) + 3500;
+        const outcome = await browser.evaluate(async (capMs) => {
+          const start = Date.now();
+          function toastState() {
+            const infoToast = document.querySelector('[data-toast-priority="info"]');
+            const errorToast = document.querySelector('[data-toast-priority="error"]');
+            return { infoToast, errorToast };
+          }
+          return await new Promise((resolve) => {
+            function tick() {
+              const { infoToast, errorToast } = toastState();
+              const infoDismissedAt = infoToast && infoToast.getAttribute('data-dismissed-at');
+              const errorDismissedAt = errorToast && errorToast.getAttribute('data-dismissed-at');
+              if (infoDismissedAt && errorDismissedAt) {
+                resolve({ done: true });
+                return;
+              }
+              if (Date.now() - start > capMs) {
+                resolve({ done: false });
+                return;
+              }
+              setTimeout(tick, 60);
+            }
+            tick();
+          });
+        }, capMs);
+        if (!outcome || !outcome.done) {
+          return { verdict: 'fail', detail: 'toasts did not dismiss within the polling cap (' + capMs + 'ms); the shell may have failed to fire the toast timer' };
+        }
+        const evidence = await browser.evaluate(() => {
+          const politeWrapper = document.querySelector('[data-live-region="polite"]');
+          const assertiveWrapper = document.querySelector('[data-live-region="assertive"]');
+          function inspect(el) {
+            if (!el) return null;
+            return {
+              id: el.getAttribute('data-toast-id'),
+              priority: el.getAttribute('data-toast-priority'),
+              role: el.getAttribute('role'),
+              parentDataLiveRegion: el.parentElement && el.parentElement.getAttribute('data-live-region'),
+              shownAt: el.getAttribute('data-shown-at'),
+              dismissedAt: el.getAttribute('data-dismissed-at'),
+              body: (el.textContent || '').trim(),
+            };
+          }
+          function texts(wrapper) {
+            if (!wrapper) return [];
+            return Array.from(wrapper.querySelectorAll('[data-toast-id]')).map((t) => (t.textContent || '').trim());
+          }
+          const infoToast = document.querySelector('[data-toast-priority="info"]');
+          const errorToast = document.querySelector('[data-toast-priority="error"]');
+          return {
+            info: inspect(infoToast),
+            error: inspect(errorToast),
+            politeBodies: texts(politeWrapper),
+            assertiveBodies: texts(assertiveWrapper),
+          };
+        });
+        if (!evidence.info) return { verdict: 'fail', detail: 'no info-priority toast rendered after trigger' };
+        if (!evidence.error) return { verdict: 'fail', detail: 'no error-priority toast rendered after trigger' };
+        if (evidence.info.parentDataLiveRegion !== 'polite') {
+          return { verdict: 'fail', detail: 'info toast rendered in wrapper ' + JSON.stringify(evidence.info.parentDataLiveRegion) + ' instead of polite (ADR-2101 mapping broken)' };
+        }
+        if (evidence.info.role !== 'status') {
+          return { verdict: 'fail', detail: 'info toast role is ' + JSON.stringify(evidence.info.role) + ' instead of status (ADR-2101 mapping broken)' };
+        }
+        if (evidence.error.parentDataLiveRegion !== 'assertive') {
+          return { verdict: 'fail', detail: 'error toast rendered in wrapper ' + JSON.stringify(evidence.error.parentDataLiveRegion) + ' instead of assertive (ADR-2101 mapping broken)' };
+        }
+        if (evidence.error.role !== 'alert') {
+          return { verdict: 'fail', detail: 'error toast role is ' + JSON.stringify(evidence.error.role) + ' instead of alert (ADR-2101 mapping broken)' };
+        }
+        // Disjoint-content check (AC-20108-1 support): the info body
+        // does not appear in the assertive wrapper and vice versa.
+        if (evidence.assertiveBodies.some((body) => body === evidence.info.body)) {
+          return { verdict: 'fail', detail: 'info toast body appears in the assertive wrapper (double-post defect)' };
+        }
+        if (evidence.politeBodies.some((body) => body === evidence.error.body)) {
+          return { verdict: 'fail', detail: 'error toast body appears in the polite wrapper (double-post defect)' };
+        }
+        // Timeout floor check (WCAG 2.2.1): elapsed time between
+        // data-shown-at and data-dismissed-at at or above the ADR-2102
+        // floor. Six seconds baseline; an operator-elicited override
+        // raises the floor (never lowers it).
+        const infoElapsed = new Date(evidence.info.dismissedAt).getTime() - new Date(evidence.info.shownAt).getTime();
+        const errorElapsed = new Date(evidence.error.dismissedAt).getTime() - new Date(evidence.error.shownAt).getTime();
+        const floorMs = shellFloorSeconds * 1000;
+        if (infoElapsed < 6000) {
+          return { verdict: 'fail', detail: 'info toast dismissed after ' + infoElapsed + 'ms, below the WCAG 2.2.1 six-second floor (shell declared floor: ' + shellFloorSeconds + 's)' };
+        }
+        if (errorElapsed < 6000) {
+          return { verdict: 'fail', detail: 'error toast dismissed after ' + errorElapsed + 'ms, below the WCAG 2.2.1 six-second floor (shell declared floor: ' + shellFloorSeconds + 's)' };
+        }
+        if (shellFloorSeconds < 6) {
+          return { verdict: 'fail', detail: 'shell root declared a toast timeout floor of ' + shellFloorSeconds + 's, below the ADR-2102 six-second floor' };
+        }
+        return { verdict: 'pass', detail: 'toast contract honoured: info in polite/status (elapsed ' + infoElapsed + 'ms), error in assertive/alert (elapsed ' + errorElapsed + 'ms), floor ' + shellFloorSeconds + 's, ' + evidence.politeBodies.length + ' polite bodies + ' + evidence.assertiveBodies.length + ' assertive bodies, disjoint' };
+      },
+    },
+    {
+      id: 'AC-20103-1',
+      severity: 'block',
+      description: 'Notification centre acknowledge round-trip: the centre lists notifications within the ADR-2103 retention window (default thirty days), each item carries a stable data-notification-id (enumerated per-element, never by role alone), and a Tab-reachable [data-action="acknowledge"] control activates a POST /api/notifications/acknowledge round-trip whose 2xx response flips the item data-acknowledged to true. Reconciled against window.__notificationFetches and /__requests.',
+      run: async ({ browser, runtimeUrl }) => {
+        if (!browser) return { verdict: 'fail', detail: 'no packBrowser wired' };
+        // Preserve the reviewer's --url query across the route swap.
+        const target = new URL(runtimeUrl);
+        target.pathname = '/notifications-centre';
+        await browser.goto(target.toString());
+        const initial = await browser.evaluate(() => {
+          // Enumerate only the notification wrappers (articles carrying
+          // data-notification-id AND data-acknowledged; the acknowledge
+          // and mark-read controls also carry data-notification-id so
+          // scope the query to article elements).
+          const items = Array.from(document.querySelectorAll('article[data-notification-id]'));
+          return {
+            itemCount: items.length,
+            itemIds: items.map((el) => el.getAttribute('data-notification-id')),
+            itemAcknowledged: items.map((el) => el.getAttribute('data-acknowledged')),
+            centreRegion: Boolean(document.querySelector('[data-region="notifications-centre"]')),
+            markAllRead: Boolean(document.querySelector('[data-action="mark-all-read"]')),
+            initialFetchCount: (window.__notificationFetches || []).length,
+          };
+        });
+        if (!initial.centreRegion) {
+          return { verdict: 'fail', detail: 'centre region not found (missing [data-region="notifications-centre"])' };
+        }
+        if (initial.itemCount === 0) {
+          return { verdict: 'fail', detail: 'centre inbox has zero items; the seeded backlog should render within the retention window' };
+        }
+        if (!initial.markAllRead) {
+          return { verdict: 'fail', detail: 'mark-all-read control missing ([data-action="mark-all-read"])' };
+        }
+        // Pick the first not-yet-acknowledged item and activate its
+        // acknowledge control by clicking. A Tab-driven activation
+        // would exercise the same handler; the runner has no keyboard
+        // seam beyond click / type / press but the fixture places the
+        // acknowledge control inside a <button> so the click is the
+        // same click a keyboard activation would trigger.
+        const firstUnackIndex = initial.itemAcknowledged.findIndex((v) => v !== 'true');
+        if (firstUnackIndex === -1) {
+          return { verdict: 'fail', detail: 'every seeded notification is already acknowledged; cannot exercise the round-trip on an unacknowledged item' };
+        }
+        const targetId = initial.itemIds[firstUnackIndex];
+        await browser.click('[data-action="acknowledge"][data-notification-id="' + targetId + '"]');
+        // Poll for the DOM update (bounded loop; the acknowledge
+        // round-trip should complete in well under a second).
+        const outcome = await browser.evaluate(async (targetId) => {
+          const start = Date.now();
+          return await new Promise((resolve) => {
+            function tick() {
+              const item = document.querySelector('[data-notification-id="' + targetId + '"]');
+              if (item && item.getAttribute('data-acknowledged') === 'true') {
+                resolve({ done: true });
+                return;
+              }
+              if (Date.now() - start > 3000) {
+                resolve({ done: false });
+                return;
+              }
+              setTimeout(tick, 50);
+            }
+            tick();
+          });
+        }, targetId);
+        if (!outcome || !outcome.done) {
+          return { verdict: 'fail', detail: 'acknowledge on notification ' + JSON.stringify(targetId) + ' did not flip data-acknowledged to true within 3s; the POST or the DOM update path is broken' };
+        }
+        // Reconcile the round-trip via window.__notificationFetches
+        // and /__requests: an `acknowledge` client record and an
+        // `acknowledge-server` server record should both exist for
+        // this notificationId.
+        const clientRecords = await browser.evaluate((targetId) => {
+          const fetches = window.__notificationFetches || [];
+          return fetches.filter((f) => f.type === 'acknowledge' && f.notificationId === targetId);
+        }, targetId);
+        if (!clientRecords || clientRecords.length === 0) {
+          return { verdict: 'fail', detail: 'no client-side acknowledge fetch recorded for ' + JSON.stringify(targetId) };
+        }
+        try {
+          const requestsRes = await fetch(new URL('/__requests', runtimeUrl).toString());
+          if (requestsRes.status !== 200) {
+            return { verdict: 'fail', detail: '/__requests endpoint returned ' + requestsRes.status };
+          }
+          const requestsBody = await requestsRes.json();
+          const serverAcks = (Array.isArray(requestsBody) ? requestsBody : []).filter((r) => r.kind === 'acknowledge-server' && r.notificationId === targetId);
+          if (serverAcks.length === 0) {
+            return { verdict: 'fail', detail: 'no server-side acknowledge record for ' + JSON.stringify(targetId) + ' at /__requests' };
+          }
+        } catch (err) {
+          return { verdict: 'fail', detail: '/__requests endpoint unreachable: ' + err.message };
+        }
+        return { verdict: 'pass', detail: 'acknowledge round-trip on ' + JSON.stringify(targetId) + ' completed: ' + initial.itemCount + ' items seeded, client + server records reconciled, data-acknowledged flipped to true' };
+      },
+    },
+  ],
+};

package/blueprints/application-onboarding-tour/CHANGELOG.md

@@ -0,0 +1,12 @@
+# application-onboarding-tour CHANGELOG
+
+## 1.0.0 (visual round T-5, spec 2026-09-06 section 5.5)
+
+- First shipped version. Introduces the tour step runner (ARIA APG dialog-modal per step, focus lifecycle, `role="dialog"`, `aria-labelledby`, `aria-describedby`, keyboard trap inside the tooltip with Escape as the exit, focus-not-obscured at 1440 and 360 breakpoints via `browser.resize`), the checklist slot (dashboard-top open collapse on `application-dashboard` applied; settings-page closed collapse when not; `<details>` browser-native for keyboard-native keyboard behaviour and screen-reader-native semantics), and the completion-state store contract (three backend shapes selected at apply time from the elicited answer or the Q4 fallback `spa-local-storage` when no persistence blueprint is applied).
+- Ships six elicits: `tour-step-manifest`, `anchor-selectors`, `per-step-content-voice` (all project-owned strings the blueprint contributes the WHAT for), `dismissal-policy` (default `dismiss-permanently`), `completion-state-store` (default `spa-local-storage` per Q4), `checklist-anchor` (default derived at apply time from the applied-blueprint set).
+- Ships a Playwright probe pack under `probe-packs/application-onboarding-tour.pack.mjs` with four surface-observable checks anchored to `AC-26101-1` (step-container focus and Escape), `AC-26102-1` (tooltip-as-dialog contract at two breakpoints), `AC-26103-1` (checklist-slot on both dashboard-top and settings-page anchors), and `AC-26104-1` (completion-state persistence and restart-tour re-open).
+- Ships a dependency-free sample-app fixture at `packages/rcf-lite/test/fixtures/probe-pack-application-onboarding-tour/` realising the tour surface honestly across both checklist branches and multiple completion-store shapes, plus four break switches (`?break=no-role`, `?break=focus-escape`, `?break=no-collapse`, `?break=no-persist`) driving the negative runs.
+- Composes on `application-spa` (routing and iconography), `application-dashboard` (dashboard-top anchor slot; settings-page fallback), `application-notifications-in-app` (polite `aria-live` completion announce), `application-account-settings` (restart-tour control home; any settings-shaped surface as fallback), and any `security-auth-*` blueprint (per-principal completion state; per-browser under a bare namespace as fallback).
+- Q4 default: when no persistence blueprint is applied AND the operator does not answer `completion-state-store`, the store defaults to `spa-local-storage`. Rationale in ADR-2702 and the README's Q4 fallback section.
+- Two documented mechanism-reach gaps: `AC-26105-1` first-run detection is fixture-verified via the manual boot line; `AC-26107-1` screen-reader traversal is asserted at the DOM contract level and verified manually via the fixture READMEs VoiceOver smoke. Runner cleanup rides `w-2026-09-04-dave-020`.
+- No new global topics claimed. Extends the section 5 shelf id band registry with `application-onboarding-tour` at 26101 to 26899 (US) and 27xx (ADR/TAC).

package/blueprints/application-onboarding-tour/README.md

@@ -0,0 +1,77 @@
+# Onboarding-tour blueprint (v1.0.0)
+
+Vendor-neutral onboarding-tour surface for an rcf-lite application. Composes on the SPA, dashboard, notifications-in-app, account-settings and any auth blueprint the project has applied, without a hard dependency on any of them: where a compose target is present the tour uses it, where it is not the tour uses the documented fallback per Q4. Ships a tour step runner mounted as an ARIA APG dialog-modal per step, a first-run checklist that renders on the dashboard shell when `application-dashboard` is applied and collapses to the settings page when not, a completion-state store with three backend shapes, and a restart-tour affordance on the settings surface. Ships a Playwright probe pack under `probe-packs/application-onboarding-tour.pack.mjs` whose four checks drive the real browser against a dependency-free sample-app fixture.
+
+## Apply
+
+```
+rcf define blueprint add <path-to>/blueprints/application-onboarding-tour
+```
+
+No `requiresAppliedCapabilities`: T-5 has no hard dependency, and the compose targets (SPA, dashboard, notifications-in-app, account-settings, any auth) are all optional. Prompts the elicitation phase for six parameters: the step manifest (3 to 5 steps with per-step anchor and content), the anchor selectors, the per-step content voice, the dismissal policy (default `dismiss-permanently`), the completion-state store shape (default `spa-local-storage`, the Q4 fallback), and the checklist anchor slot (default derived at apply time from what is applied). Writes a sidecar `rcf/blueprints/application-onboarding-tour.applied.json` capturing the answered elicits and the discovered `appliedBlueprints[]` (dashboard, notifications-in-app, account-settings, spa presence). Consumes the `logging` and `errorHandling` companions when they resolve to an applied provider or a registered library.
+
+## Anatomy
+
+| Piece | Where | What |
+|---|---|---|
+| Metadata | `blueprint.json` | Slug, version 1.0.0, category `application`, no `requiresAppliedCapabilities`, six elicits, `suggestedCompanions: [logging, errorHandling]`, 17 contributions in the 26xxx / 27xx bands |
+| Doc set | `contributions/` | 4 REQs, 7 USs (7 runtime-observable ACs; two documented mechanism-reach gaps on AC-26105-1 and AC-26107-1), 3 TACs, 3 ADRs |
+| Probe pack | `probe-packs/application-onboarding-tour.pack.mjs` | Four surface-observable browser-verify checks anchored to AC-26101-1 step-container focus, AC-26102-1 tooltip-as-dialog, AC-26103-1 checklist-slot, AC-26104-1 completion-state persistence |
+| Guide | `guide/application-onboarding-tour.md` | Operator-facing: when to reach, when not, mechanism-reach gaps, ARIA APG dialog-modal pattern and WCAG SCs the tour honours |
+| Coordination vocabulary | `docs/topics.md` | Shelf id band registry update; no new global topics claimed; cross-references to `application-dashboard`, `application-notifications-in-app`, `application-account-settings`, `application-spa` |
+| Sample-app fixture | `packages/rcf-lite/test/fixtures/probe-pack-application-onboarding-tour/` | Dependency-free Node HTTP server the pack is probed against on the shelf gate |
+
+## Composition: what the tour reaches when
+
+| Applied blueprint | Effect on the tour |
+|---|---|
+| `application-spa` applied | Routing (`/tour`, `/dashboard`, `/settings`), iconography, theming carry through. Absent: the tour still renders but the project supplies the routing shell. |
+| `application-dashboard` applied | Checklist anchor defaults to `dashboard-top` inside a `<details open>` element on the dashboard shell. Absent: checklist anchor defaults to `settings-page` inside a `<details>` (closed) element on the settings surface, per ADR-2703 and AC-26103-1. |
+| `application-notifications-in-app` applied | Tour completion emits a polite `aria-live` announcement through the notifications-in-app live region. Absent: the completion is silent at the announce layer (the step runner still logs one line if a `logging` companion resolves). |
+| `application-account-settings` applied | Restart-tour control lives inside the account settings surface. Absent: the restart-tour control renders on any settings-shaped surface the project supplies (`/settings`, `/account`, `/account/settings`). |
+| Any `security-auth-*` applied | Completion state persists per principal identifier (the sidecar carries the principal namespace at apply). Absent: completion state persists per browser under a bare namespace; the tour behaves as a single-principal experience. |
+
+## Q4 fallback: completion-state store shape
+
+Q4 of the ratified spec (section 10) settles the completion-state fallback. When no persistence blueprint is applied AND the operator does not answer `completion-state-store` explicitly, the store defaults to `spa-local-storage`: a per-browser record so a returning principal on the same browser is not re-onboarded, and a different browser is re-onboarded. Rationale: a per-session tour that re-plays on every new session is worse than a one-time tour that persists across sessions on that browser; per the elicit surface, the operator can override to `spa-session-storage` (per-session refresh) or `server-side-per-principal` (cross-device; requires an applied persistence blueprint).
+
+## Standards trace
+
+- ARIA APG dialog-modal pattern: `role="dialog"`, `aria-labelledby` on the step heading, `aria-describedby` on the step body, focus moves to the tooltip on open, focus returns to the anchor on close. `AC-26102-1`, `AC-26107-1`.
+- WCAG 2.2 AA 2.1.1 Keyboard: every tour control activatable with the keyboard. `AC-26101-1`.
+- WCAG 2.2 AA 2.1.2 No Keyboard Trap: Escape always exits, focus never permanently trapped. `AC-26101-1`.
+- WCAG 2.2 AA 2.4.3 Focus Order: Tab reaches every tour control in DOM order inside the tooltip. `AC-26101-1`.
+- WCAG 2.2 AA 2.4.11 Focus Not Obscured Minimum: tooltip visible at the 1440 wide and 360 narrow breakpoints (probed via `browser.resize`). `AC-26102-1`.
+
+Spec `standardsTrace` empty at the blueprint level; each ADR contribution carries a non-null `standardsTraceClause` per authoring section 8a.4 (the sentinel `generic enterprise practice` used where no SC applies).
+
+## Known mechanism-reach gaps
+
+- `AC-26105-1` (first-run detection): the runner cannot fully prove the first-run vs returning-principal branch in one browser session without a persisted state seed; the pack drives the first-run branch via `?first-run=1` and the returning branch is verified by the fixture READMEs manual boot line (walk `/tour` twice, confirm the tour auto-opens on run 1 and does not on run 2).
+- `AC-26107-1` (screen-reader traversal): the pack asserts the DOM contract (`aria-labelledby`, `aria-describedby`) but does not drive a real screen reader in CI. The fixture README names the manual VoiceOver smoke. Runner cleanup rides `w-2026-09-04-dave-020`.
+- `AC-26106-1` (restart-tour clears state and re-opens): fully exercised inside the AC-26104-1 pack check end-to-end (the check clicks restart, then navigates to `/tour` and asserts the tooltip re-appears).
+
+## Elicited parameters
+
+- `tour-step-manifest` (string; project-owned): the ordered list of 3 to 5 steps with per-step anchor, heading and body slot.
+- `anchor-selectors` (string; project-owned): the CSS selectors the runner resolves at step-open time.
+- `per-step-content-voice` (string; project-owned): the copy for each step.
+- `dismissal-policy` (enum: `dismiss-permanently` | `dismiss-until-next-major` | `dismiss-until-next-minor`; default `dismiss-permanently`).
+- `completion-state-store` (enum: `spa-local-storage` | `spa-session-storage` | `server-side-per-principal`; default `spa-local-storage` per Q4).
+- `checklist-anchor` (enum: `dashboard-top` | `settings-page` | `custom-anchor`; default derived at apply time from what is applied).
+
+## Suggested companions
+
+- `logging`: every step transition and tour completion writes one request-scoped log line with the correlation identifier.
+- `errorHandling`: a completion-state persistence failure constructs an internal error record.
+
+## Probe pack
+
+`probe-packs/application-onboarding-tour.pack.mjs` ships four surface-observable checks anchored to blueprint AC ids:
+
+- `AC-26101-1` step-container focus lifecycle and Escape.
+- `AC-26102-1` tooltip-as-dialog contract at 1440 and 360 breakpoints (via `browser.resize`).
+- `AC-26103-1` checklist slot on both dashboard-top (open) and settings-page (closed) branches.
+- `AC-26104-1` completion-state persistence and restart-tour re-open.
+
+The pack applies to any FBS binding `TAC-2701-application-onboarding-tour-step-runner` or whose `navModel` routes match the operator-configured tour-anchor path glob (`/tour`, `/welcome`, `/getting-started`, `/onboarding`). Every URL string is composed through the `withUrl(runtimeUrl, path)` helper (no bare string concatenation).

package/blueprints/application-onboarding-tour/blueprint.json

@@ -0,0 +1,164 @@
+{
+  "slug": "application-onboarding-tour",
+  "version": "1.0.0",
+  "category": "application",
+  "elicits": [
+    {
+      "id": "tour-step-manifest",
+      "prompt": "Tour step manifest: an ordered list of 3 to 5 steps, each with an anchor selector (CSS) and a content voice slot the project fills. Names each step id, anchor, heading and body.",
+      "kind": "string",
+      "default": ""
+    },
+    {
+      "id": "anchor-selectors",
+      "prompt": "Anchor selectors: CSS selectors the runtime resolves at step-open time to place the tooltip. One per manifest step.",
+      "kind": "string",
+      "default": ""
+    },
+    {
+      "id": "per-step-content-voice",
+      "prompt": "Per-step content voice: the project-owned copy for each step (heading and body). The blueprint contributes the WHAT, not the words.",
+      "kind": "string",
+      "default": ""
+    },
+    {
+      "id": "dismissal-policy",
+      "prompt": "Dismissal policy: dismiss-permanently (the tour never re-opens for a returning principal), dismiss-until-next-major (re-opens on a major version bump of the applied blueprint set), or dismiss-until-next-minor (re-opens on a minor bump). Recommended default: dismiss-permanently.",
+      "kind": "enum",
+      "options": [
+        "dismiss-permanently",
+        "dismiss-until-next-major",
+        "dismiss-until-next-minor"
+      ],
+      "default": "dismiss-permanently"
+    },
+    {
+      "id": "completion-state-store",
+      "prompt": "Completion-state store shape: spa-local-storage (per-browser, the Q4 fallback when no persistence blueprint is applied), spa-session-storage (per-session, re-plays on every new session), or server-side-per-principal (follows the principal across devices; requires an applied persistence blueprint). Recommended default: spa-local-storage.",
+      "kind": "enum",
+      "options": [
+        "spa-local-storage",
+        "spa-session-storage",
+        "server-side-per-principal"
+      ],
+      "default": "spa-local-storage"
+    },
+    {
+      "id": "checklist-anchor",
+      "prompt": "Checklist anchor slot: dashboard-top (renders on the dashboard shell when application-dashboard is applied), settings-page (renders on the settings surface when application-account-settings is applied or on any settings surface as a fallback), or custom-anchor (the project supplies a CSS selector). Default derived at apply time from what is applied.",
+      "kind": "enum",
+      "options": [
+        "dashboard-top",
+        "settings-page",
+        "custom-anchor"
+      ],
+      "default": "dashboard-top"
+    }
+  ],
+  "suggestedCompanions": [
+    {
+      "role": "logging",
+      "reason": "Every step transition and tour completion writes one request-scoped log line with the correlation identifier; a logging companion supplies the factory."
+    },
+    {
+      "role": "errorHandling",
+      "reason": "A completion-state persistence failure constructs an internal error record; an error-handling companion supplies the record factory and the boundary."
+    }
+  ],
+  "contributions": [
+    {
+      "id": "application-onboarding-tour-REQ-001",
+      "kind": "req",
+      "path": "requirements/application-onboarding-tour-req-001.json"
+    },
+    {
+      "id": "application-onboarding-tour-REQ-002",
+      "kind": "req",
+      "path": "requirements/application-onboarding-tour-req-002.json"
+    },
+    {
+      "id": "application-onboarding-tour-REQ-003",
+      "kind": "req",
+      "path": "requirements/application-onboarding-tour-req-003.json"
+    },
+    {
+      "id": "application-onboarding-tour-REQ-004",
+      "kind": "req",
+      "path": "requirements/application-onboarding-tour-req-004.json"
+    },
+    {
+      "id": "application-onboarding-tour-US-26101",
+      "kind": "us",
+      "path": "user-stories/application-onboarding-tour-us-26101.json"
+    },
+    {
+      "id": "application-onboarding-tour-US-26102",
+      "kind": "us",
+      "path": "user-stories/application-onboarding-tour-us-26102.json"
+    },
+    {
+      "id": "application-onboarding-tour-US-26103",
+      "kind": "us",
+      "path": "user-stories/application-onboarding-tour-us-26103.json"
+    },
+    {
+      "id": "application-onboarding-tour-US-26104",
+      "kind": "us",
+      "path": "user-stories/application-onboarding-tour-us-26104.json"
+    },
+    {
+      "id": "application-onboarding-tour-US-26105",
+      "kind": "us",
+      "path": "user-stories/application-onboarding-tour-us-26105.json"
+    },
+    {
+      "id": "application-onboarding-tour-US-26106",
+      "kind": "us",
+      "path": "user-stories/application-onboarding-tour-us-26106.json"
+    },
+    {
+      "id": "application-onboarding-tour-US-26107",
+      "kind": "us",
+      "path": "user-stories/application-onboarding-tour-us-26107.json"
+    },
+    {
+      "id": "TAC-2701-application-onboarding-tour-step-runner",
+      "kind": "tac",
+      "path": "tacs/tac-2701-application-onboarding-tour-step-runner.json"
+    },
+    {
+      "id": "TAC-2702-application-onboarding-tour-checklist-slot",
+      "kind": "tac",
+      "path": "tacs/tac-2702-application-onboarding-tour-checklist-slot.json"
+    },
+    {
+      "id": "TAC-2703-application-onboarding-tour-completion-store",
+      "kind": "tac",
+      "path": "tacs/tac-2703-application-onboarding-tour-completion-store.json"
+    },
+    {
+      "id": "ADR-2701-application-onboarding-tour-dismissal-policy",
+      "kind": "adr",
+      "path": "adrs/adr-2701-application-onboarding-tour-dismissal-policy.json",
+      "recommendedDefault": true,
+      "elicited": true,
+      "standardsTraceClause": "generic enterprise practice"
+    },
+    {
+      "id": "ADR-2702-application-onboarding-tour-completion-store-shape",
+      "kind": "adr",
+      "path": "adrs/adr-2702-application-onboarding-tour-completion-store-shape.json",
+      "recommendedDefault": true,
+      "elicited": true,
+      "standardsTraceClause": "generic enterprise practice"
+    },
+    {
+      "id": "ADR-2703-application-onboarding-tour-checklist-anchor",
+      "kind": "adr",
+      "path": "adrs/adr-2703-application-onboarding-tour-checklist-anchor.json",
+      "recommendedDefault": true,
+      "elicited": true,
+      "standardsTraceClause": "generic enterprise practice"
+    }
+  ]
+}