rcf-lite 0.21.0 → 0.22.0

package/blueprints/application-onboarding-tour/contributions/requirements/application-onboarding-tour-req-003.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "application-onboarding-tour-REQ-003",
+  "prdId": "PRD-001",
+  "title": "Checklist surface: on the dashboard when application-dashboard is applied, on the settings page when not",
+  "description": "A first-run checklist renders on the dashboard-top anchor when application-dashboard is applied (open by default, so a new principal sees the outstanding items at a glance) and collapses to a settings-page anchor when application-dashboard is not applied (closed by default, so an existing principal reaching the settings surface can expand it). The collapse contract is a <details> element whose open state mirrors the anchor choice: dashboard-top -> open, settings-page -> closed. The checklist enumerates the applied tour surfaces with a link back to the restart-tour affordance on the settings surface. The blueprint contributes the anchor slot contract (ADR-2703) and the surface conditionality, not the checklist items.",
+  "category": "functional",
+  "domain": "application",
+  "priority": "must",
+  "rationale": "Per visual round 4 spec (2026-09-06) section 5.5, REQ 3 of the onboarding-tour blueprint.",
+  "tags": [
+    "blueprint:application-onboarding-tour",
+    "category:03-checklist-slot"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-06T23:15:00Z",
+  "updatedAt": "2026-09-06T23:15:00Z"
+}

package/blueprints/application-onboarding-tour/contributions/requirements/application-onboarding-tour-req-004.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "application-onboarding-tour-REQ-004",
+  "prdId": "PRD-001",
+  "title": "Completion-state persistence per principal in the applied persistence blueprint with an spa-local-storage fallback per Q4",
+  "description": "The completion state persists per principal in the applied persistence blueprint (server-side-per-principal when a persistence blueprint is applied and the operator picks that store) or per browser in spa-local-storage as the Q4 fallback when no persistence blueprint is applied. spa-session-storage is a third option the operator can pick when a per-session tour is deliberately wanted. A restart-tour control renders on the settings surface (composing on application-account-settings when applied; on any settings-shaped surface as a fallback) and clears the completion state so the tour re-opens on the next principal load.",
+  "category": "functional",
+  "domain": "application",
+  "priority": "must",
+  "rationale": "Per visual round 4 spec (2026-09-06) section 5.5, REQ 4 of the onboarding-tour blueprint. Q4 default (spa-local-storage fallback) ratified per spec section 10.",
+  "tags": [
+    "blueprint:application-onboarding-tour",
+    "category:04-completion-store"
+  ],
+  "version": "1.0.0",
+  "status": "approved",
+  "createdAt": "2026-09-06T23:15:00Z",
+  "updatedAt": "2026-09-06T23:15:00Z"
+}

package/blueprints/application-onboarding-tour/contributions/tacs/tac-2701-application-onboarding-tour-step-runner.json

@@ -0,0 +1,41 @@
+{
+  "tacId": "TAC-2701-application-onboarding-tour-step-runner",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Onboarding-tour step runner",
+  "purpose": "Owns the rendered tour surface: the step manifest walk, the anchor resolver, the tooltip-as-dialog mount, and the focus lifecycle across open, walk and close. The step runner is the base surface every step-shaped AC anchors on.",
+  "responsibilities": [
+    "Walk the elicited step manifest in order and resolve each step's anchor selector against the live DOM (AC-26101-1).",
+    "Mount each step's tooltip as an ARIA APG dialog-modal (role=\"dialog\", aria-labelledby, aria-describedby) and move focus into it on open (AC-26102-1, AC-26107-1).",
+    "Return focus to the anchor on close (Escape, dismiss control, or last-step confirm) (AC-26102-1).",
+    "Trap focus between the tour controls (previous, next, dismiss) and refuse Tab escape to the underlying surface while Escape still exits (AC-26101-1).",
+    "Keep the tooltip visible at every breakpoint the applied SPA blueprint declares; refuse a step render whose anchor would clip the tooltip below the viewport minimum (AC-26102-1)."
+  ],
+  "internalStructure": "One step runner module that reads the applied elicits, mounts the tooltip mount-point at document.body-level, drives the manifest walk, and calls the completion-state store on the last step. The framework is not prescribed; the runner interfaces are what the project realises against React, Vue, Svelte or vanilla DOM.",
+  "interfaces": [
+    {
+      "name": "renderTourRunner",
+      "kind": "factory",
+      "description": "renderTourRunner({ stepManifest, anchorResolver, dialogMount, focusLifecycle, completionStore }) -> { openAtStep(stepId), dismiss(), destroy() }. The project supplies the stepManifest (from the elicit), the anchorResolver (from a CSS selector to a live element), the dialogMount (an element or a factory), the focusLifecycle (open, walk, close hooks) and the completionStore (the resolved TAC-2703 backend)."
+    },
+    {
+      "name": "stepManifest",
+      "kind": "shape",
+      "description": "[{ id, anchorSelector, heading, body, order }]. Ordered list of 3 to 5 steps. Each step is opened by openAtStep(stepId) or advanced by the previous / next controls."
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "Completion store",
+      "kind": "tac",
+      "tacId": "TAC-2703-application-onboarding-tour-completion-store",
+      "description": "The step runner calls the completion store on the last step to persist the completion record."
+    }
+  ],
+  "tradeoffs": "The step runner mounts the tooltip at document.body-level rather than inline at the anchor so a positioned parent (transform, contain) does not clip the tooltip. This costs one extra pointer resolution on every step open (anchor selector -> live element -> viewport rect); the alternative would silently clip tooltips inside common flex/grid layouts.",
+  "notes": "Composes on the applied SPA blueprint for the routing and iconography, and on the applied dashboard blueprint for the highest-value first surface. Known mechanism-reach gaps: the runner cannot prove the described-text screen-reader read order without a real screen reader (documented under AC-26107-1); the runner cannot prove focus does not escape the tooltip in every framework rendering (documented under AC-26101-1). See README Known mechanism-reach gaps.",
+  "createdAt": "2026-09-06T23:15:00Z",
+  "updatedAt": "2026-09-06T23:15:00Z"
+}

package/blueprints/application-onboarding-tour/contributions/tacs/tac-2702-application-onboarding-tour-checklist-slot.json

@@ -0,0 +1,35 @@
+{
+  "tacId": "TAC-2702-application-onboarding-tour-checklist-slot",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Onboarding-tour checklist slot",
+  "purpose": "Owns the checklist surface: the anchor-slot resolution (dashboard-top vs settings-page vs custom-anchor), the collapse contract (<details open> on dashboard-top; <details> closed on settings-page), and the enumeration of the applied tour surfaces with a link back to the restart-tour affordance on the settings surface.",
+  "responsibilities": [
+    "Read the elicited checklist-anchor (ADR-2703) at load and mount the checklist at the resolved slot (AC-26103-1).",
+    "Render the checklist as a <details> element carrying data-role=\"onboarding-tour-checklist\" whose open state mirrors the anchor: open on dashboard-top, closed on settings-page (AC-26103-1).",
+    "Enumerate the applied tour surfaces as list items with a link to the restart-tour control on the settings surface.",
+    "Suppress the checklist entirely when neither the dashboard nor the settings surface is applied and no custom-anchor is supplied."
+  ],
+  "internalStructure": "One checklist module that reads the applied capability set from the sidecar-adjacent applied-blueprint list, picks the anchor per the elicited value or the default derived at apply time, and mounts the <details> element into the resolved slot. The framework is not prescribed.",
+  "interfaces": [
+    {
+      "name": "renderChecklist",
+      "kind": "factory",
+      "description": "renderChecklist({ anchor, appliedSet, items }) -> { mount(rootElement), unmount() }. The project supplies the anchor (one of dashboard-top, settings-page, custom-anchor with a selector), the appliedSet (from the applied-blueprint list) and the items (from the manifest walk)."
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "Step runner",
+      "kind": "tac",
+      "tacId": "TAC-2701-application-onboarding-tour-step-runner",
+      "description": "The checklist links back to the step runner via the restart-tour control on the settings surface."
+    }
+  ],
+  "tradeoffs": "The <details>/<summary> collapse contract is chosen over an ARIA APG disclosure widget because <details> ships browser-native keyboard behaviour (Space, Enter to toggle) and screen-reader-native semantics; a bespoke disclosure widget would need every keyboard case re-implemented. The trade-off is styling constraints; the fixture ships an unstyled <details> to make the shape testable.",
+  "notes": "Composes on application-dashboard for the dashboard-top slot and application-account-settings for the settings-page slot; a project applying neither falls back to a custom-anchor. Known mechanism-reach gap: the checklist cannot inspect which items a principal has already completed without a persistence-blueprint reader; documented under AC-26103-1 as a fixture-side signal only.",
+  "createdAt": "2026-09-06T23:15:00Z",
+  "updatedAt": "2026-09-06T23:15:00Z"
+}

package/blueprints/application-onboarding-tour/contributions/tacs/tac-2703-application-onboarding-tour-completion-store.json

@@ -0,0 +1,34 @@
+{
+  "tacId": "TAC-2703-application-onboarding-tour-completion-store",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "name": "Onboarding-tour completion-state store",
+  "purpose": "Owns the completion-state store contract: the writer the step runner calls on the last step, the reader first-run detection calls on principal load, and the clearer the restart-tour control calls. Delegates to the applied persistence blueprint when server-side-per-principal is elicited (and refuses at apply if no persistence blueprint is applied); falls back to spa-local-storage per Q4 or spa-session-storage per the elicit.",
+  "responsibilities": [
+    "Write the completion record on the last step (AC-26104-1).",
+    "Read the completion record on principal load so first-run detection can gate the tour auto-open (AC-26105-1).",
+    "Clear the completion record when the restart-tour control fires (AC-26104-1, AC-26106-1).",
+    "Refuse at apply when server-side-per-principal is elicited without an applied persistence blueprint."
+  ],
+  "internalStructure": "One completion-store module with three backends (spa-local-storage, spa-session-storage, server-side-per-principal) selected at apply time from the elicited completion-state-store answer or the Q4 fallback (spa-local-storage). The server-side backend calls the applied persistence blueprint's writer through the projects own adapter interface; the two SPA backends read and write window.localStorage / window.sessionStorage under a namespaced key derived from the applied blueprint set version.",
+  "interfaces": [
+    {
+      "name": "completionStore",
+      "kind": "shape",
+      "description": "{ read(principalId): CompletionRecord | null, write(principalId, record), clear(principalId) }. CompletionRecord = { completedAt: ISO string, blueprintSetVersion: string, stepIds: string[] }. The blueprintSetVersion is the versioned identifier of the applied blueprint set so a dismiss-until-next-major or dismiss-until-next-minor policy can re-open the tour on the right bump."
+    }
+  ],
+  "dependencies": [
+    {
+      "name": "Persistence blueprint",
+      "kind": "external",
+      "description": "Optional composition: only the server-side-per-principal backend delegates to an applied persistence blueprint writer. spa-local-storage and spa-session-storage need no persistence blueprint. The rcf-schemas 0.6.1 TAC dependency kind enum is limited to tac and external, so the composition-optional relation is recorded as external and made explicit in the description and notes."
+    }
+  ],
+  "tradeoffs": "spa-local-storage is chosen as the Q4 default because 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; spa-session-storage remains an option for a project that deliberately wants a per-session tour. server-side-per-principal is chosen when the tour completion is a real profile fact (a cross-device onboarding) rather than a per-browser convenience.",
+  "notes": "The blueprintSetVersion in the CompletionRecord is what lets ADR-2701's dismiss-until-next-major and dismiss-until-next-minor policies re-open the tour on the right bump. Known mechanism-reach gap: the server-side-per-principal backend cannot prove a round-trip in a unit test without an applied persistence blueprint; the pack skips the persistence round-trip check for spa-* stores (inspects the storage directly) and drives it for server-side-per-principal on the fixture branch that stands up an in-fixture writer. The Persistence blueprint dependency is recorded with kind external per the rcf-schemas 0.6.1 enum and is optional-composition semantically: server-side-per-principal delegates to the applied persistence blueprint writer, and the spa-local-storage and spa-session-storage backends need no persistence blueprint applied. Refusal at apply for the server-side-per-principal branch is enforced in the store module.",
+  "createdAt": "2026-09-06T23:15:00Z",
+  "updatedAt": "2026-09-07T00:45:00Z"
+}

package/blueprints/application-onboarding-tour/contributions/user-stories/application-onboarding-tour-us-26101.json

@@ -0,0 +1,27 @@
+{
+  "usId": "application-onboarding-tour-US-26101",
+  "prdId": "PRD-001",
+  "reqId": "application-onboarding-tour-REQ-001",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "First-run principal sees the tour open on the highest-value surface and can walk it or dismiss it with the keyboard",
+  "asA": "first-run principal reaching the application",
+  "iWant": "the tour to open on the highest-value surface with the first step, and to be able to walk through it or dismiss it using only the keyboard",
+  "soThat": "I can learn the surface my project ships without a mouse, and I can leave the tour at any point without a trap",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-26101-1",
+      "testable": true,
+      "scope": "runtime",
+      "description": "Given a first-run principal on the SPA, the tour opens on the highest-value surface with the first step; Escape dismisses the tour and hides the tooltip; keyboard-only users reach every tour control (previous, next, dismiss) via Tab in DOM order and activate the next control with Enter (WCAG 2.1.1 Keyboard, WCAG 2.1.2 No Keyboard Trap, WCAG 2.4.3 Focus Order). Anchors to TAC-2701-application-onboarding-tour-step-runner; probed by application-onboarding-tour.pack.mjs check AC-26101-1."
+    }
+  ],
+  "tacIds": [
+    "TAC-2701-application-onboarding-tour-step-runner"
+  ],
+  "tags": [
+    "blueprint:application-onboarding-tour"
+  ],
+  "createdAt": "2026-09-06T23:15:00Z",
+  "updatedAt": "2026-09-06T23:15:00Z"
+}

package/blueprints/application-onboarding-tour/contributions/user-stories/application-onboarding-tour-us-26102.json

@@ -0,0 +1,27 @@
+{
+  "usId": "application-onboarding-tour-US-26102",
+  "prdId": "PRD-001",
+  "reqId": "application-onboarding-tour-REQ-002",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Each step's tooltip renders as an ARIA APG dialog-modal with focus lifecycle and focus not obscured",
+  "asA": "principal walking through the tour",
+  "iWant": "each step's tooltip to behave like a proper dialog, with focus arriving on open and returning to the anchor on close and remaining visible at every breakpoint",
+  "soThat": "an assistive-technology user hears the step content on open and returns to context on close, and no tooltip is clipped at the viewport edge",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-26102-1",
+      "testable": true,
+      "scope": "runtime",
+      "description": "Given a step showing a tooltip anchored to a UI element, focus moves to the tooltip on open; the tooltip carries role=\"dialog\" with aria-labelledby pointing at the step heading; focus returns to the anchor on close (Escape or the dismiss control) per the ARIA APG dialog-modal pattern; focus is not obscured on the 1440 wide breakpoint or the 360 narrow breakpoint (WCAG 2.4.11 Focus Not Obscured Minimum). Anchors to TAC-2701-application-onboarding-tour-step-runner; probed by application-onboarding-tour.pack.mjs check AC-26102-1."
+    }
+  ],
+  "tacIds": [
+    "TAC-2701-application-onboarding-tour-step-runner"
+  ],
+  "tags": [
+    "blueprint:application-onboarding-tour"
+  ],
+  "createdAt": "2026-09-06T23:15:00Z",
+  "updatedAt": "2026-09-06T23:15:00Z"
+}

package/blueprints/application-onboarding-tour/contributions/user-stories/application-onboarding-tour-us-26103.json

@@ -0,0 +1,27 @@
+{
+  "usId": "application-onboarding-tour-US-26103",
+  "prdId": "PRD-001",
+  "reqId": "application-onboarding-tour-REQ-003",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Checklist surface renders on the dashboard when application-dashboard is applied and on the settings page when not",
+  "asA": "returning principal who dismissed the tour and later wants to check the outstanding items",
+  "iWant": "the checklist to render on the dashboard shell when application-dashboard is applied and on the settings page when it is not, with a collapse contract that opens the checklist on the dashboard and closes it on the settings page by default",
+  "soThat": "the checklist meets me where I am, and it does not intrude on the settings surface where it is a reference rather than a primary task",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-26103-1",
+      "testable": true,
+      "scope": "runtime",
+      "description": "Given the applied capability set includes application-dashboard, the checklist renders inside a <details open> element on the dashboard-top anchor slot; given the applied capability set does NOT include application-dashboard, the checklist renders inside a <details> (closed) element on the settings-page anchor slot; the <details> element carries data-role=\"onboarding-tour-checklist\" in both branches. Anchors to TAC-2702-application-onboarding-tour-checklist-slot; probed by application-onboarding-tour.pack.mjs check AC-26103-1 on both application-dashboard and settings-page branches."
+    }
+  ],
+  "tacIds": [
+    "TAC-2702-application-onboarding-tour-checklist-slot"
+  ],
+  "tags": [
+    "blueprint:application-onboarding-tour"
+  ],
+  "createdAt": "2026-09-06T23:15:00Z",
+  "updatedAt": "2026-09-06T23:15:00Z"
+}

package/blueprints/application-onboarding-tour/contributions/user-stories/application-onboarding-tour-us-26104.json

@@ -0,0 +1,27 @@
+{
+  "usId": "application-onboarding-tour-US-26104",
+  "prdId": "PRD-001",
+  "reqId": "application-onboarding-tour-REQ-004",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Completion-state persists per principal and the restart-tour control clears it",
+  "asA": "returning principal who completed the tour",
+  "iWant": "the completion state to persist per principal in the applied persistence store (or per browser in spa-local-storage as the Q4 fallback), and a restart-tour control I can reach from the settings surface",
+  "soThat": "the tour does not re-open at every session, and I can bring it back deliberately when I need to",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-26104-1",
+      "testable": true,
+      "scope": "runtime",
+      "description": "Given a completed tour, the completion state persists per principal in the applied persistence blueprint (or in spa-local-storage as the Q4 fallback per ADR-2702 when no persistence blueprint is applied); a restart-tour control is reachable from the settings surface (composing on application-account-settings when applied; on any settings surface as a fallback); activating the control clears the completion state and re-opens the tour on the next principal load. Anchors to TAC-2703-application-onboarding-tour-completion-store; probed by application-onboarding-tour.pack.mjs check AC-26104-1."
+    }
+  ],
+  "tacIds": [
+    "TAC-2703-application-onboarding-tour-completion-store"
+  ],
+  "tags": [
+    "blueprint:application-onboarding-tour"
+  ],
+  "createdAt": "2026-09-06T23:15:00Z",
+  "updatedAt": "2026-09-06T23:15:00Z"
+}

package/blueprints/application-onboarding-tour/contributions/user-stories/application-onboarding-tour-us-26105.json

@@ -0,0 +1,27 @@
+{
+  "usId": "application-onboarding-tour-US-26105",
+  "prdId": "PRD-001",
+  "reqId": "application-onboarding-tour-REQ-004",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "First-run detection: a principal with no completion state sees the tour; a principal with completion state does not",
+  "asA": "returning principal",
+  "iWant": "the tour to open only on my first run, not on every visit",
+  "soThat": "I am not re-onboarded on every session and the surface stays clean",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-26105-1",
+      "testable": true,
+      "scope": "runtime",
+      "description": "Given a principal whose completion-state store contains no completion record for the applied blueprint set version, the tour auto-opens on the highest-value surface; given a principal whose completion-state store contains a completion record for the applied blueprint set version, the tour does NOT auto-open and only the checklist and the restart-tour control render. The check is documented as a mechanism-reach gap in the README (not directly probed at runtime; enforced by the fixture branch under manual boot for the gate reviewer)."
+    }
+  ],
+  "tacIds": [
+    "TAC-2703-application-onboarding-tour-completion-store"
+  ],
+  "tags": [
+    "blueprint:application-onboarding-tour"
+  ],
+  "createdAt": "2026-09-06T23:15:00Z",
+  "updatedAt": "2026-09-06T23:15:00Z"
+}

package/blueprints/application-onboarding-tour/contributions/user-stories/application-onboarding-tour-us-26106.json

@@ -0,0 +1,27 @@
+{
+  "usId": "application-onboarding-tour-US-26106",
+  "prdId": "PRD-001",
+  "reqId": "application-onboarding-tour-REQ-004",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Restart-tour control clears completion state and re-opens the tour",
+  "asA": "returning principal who completed the tour but wants to see it again",
+  "iWant": "a restart-tour control on the settings surface that clears my completion state and re-opens the tour",
+  "soThat": "I can revisit the guidance without clearing local storage by hand or hunting through the surface for a hidden trigger",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-26106-1",
+      "testable": true,
+      "scope": "runtime",
+      "description": "The restart-tour control renders on the settings surface as a <button data-action=\"restart-tour\"> reachable via Tab and activatable with Enter; activating it clears the completion state in the applied store (per ADR-2702) and re-opens the tour on the highest-value surface on the next principal load. Covered as part of AC-26104-1's pack check (the check exercises the restart flow end-to-end)."
+    }
+  ],
+  "tacIds": [
+    "TAC-2703-application-onboarding-tour-completion-store"
+  ],
+  "tags": [
+    "blueprint:application-onboarding-tour"
+  ],
+  "createdAt": "2026-09-06T23:15:00Z",
+  "updatedAt": "2026-09-06T23:15:00Z"
+}

package/blueprints/application-onboarding-tour/contributions/user-stories/application-onboarding-tour-us-26107.json

@@ -0,0 +1,27 @@
+{
+  "usId": "application-onboarding-tour-US-26107",
+  "prdId": "PRD-001",
+  "reqId": "application-onboarding-tour-REQ-002",
+  "version": "1.0.0",
+  "status": "approved",
+  "title": "Screen-reader traversal announces the step heading and body on open",
+  "asA": "assistive-technology user",
+  "iWant": "the tooltip to announce the step heading and body on open through the ARIA APG dialog-modal contract",
+  "soThat": "I hear the step content the moment focus arrives, not after a manual navigation",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-26107-1",
+      "testable": true,
+      "scope": "runtime",
+      "description": "The tooltip carries aria-labelledby pointing at the step heading and aria-describedby pointing at the step body; focus moves into the tooltip on open so the screen reader reads the labelled and described text. Documented as a mechanism-reach gap for the described-text read order because rcf-lite does not drive a real screen reader in CI; the pack asserts the DOM contract and the fixture README names the manual screen-reader smoke."
+    }
+  ],
+  "tacIds": [
+    "TAC-2701-application-onboarding-tour-step-runner"
+  ],
+  "tags": [
+    "blueprint:application-onboarding-tour"
+  ],
+  "createdAt": "2026-09-06T23:15:00Z",
+  "updatedAt": "2026-09-06T23:15:00Z"
+}

package/blueprints/application-onboarding-tour/docs/topics.md

@@ -0,0 +1,48 @@
+# application-onboarding-tour: coordination vocabulary
+
+## Global topics
+
+The blueprint claims no new global topics at v1.0.0. Onboarding-tour is a consumer of the applied SPA, dashboard, notifications-in-app and account-settings surfaces; every ADR (dismissal-policy, completion-state-store shape, checklist-anchor slot) is non-global.
+
+## Deliberately unclaimed topics
+
+- `completionStateStore` (the shape of a completion-state record beyond this blueprint's needs). Reserved for the applied persistence blueprint's own ADR set when server-side-per-principal is elicited. The onboarding-tour blueprint hands off the store to the applied provider through the completion-store interface.
+- `stepManifestFormat` (the shape of a shared onboarding manifest across blueprints). Reserved until a second blueprint contributes a step-shaped manifest surface (a settings walk-through, a role-tour); the dashboardShell rejection precedent stands: mint a topic only when a second consumer arrives.
+
+## Shelf id band and suffix block
+
+| Blueprint | US band | ADR/TAC suffix block | Status | Global topics |
+|---|---|---|---|---|
+| application-datatable | 17101-17899 | 18xx | shipped v1.0.0 | none |
+| application-charts | 18101-18899 | 19xx | shipped v1.0.0 | none |
+| application-dashboard | 19101-19899 | 20xx | shipped v1.0.0 | none |
+| application-notifications-in-app | 20101-20899 | 21xx | shipped v1.0.0 | none |
+| application-admin-console | 21101-21899 | 22xx | shipped v1.0.0 | none |
+| application-empty-error-states | 22101-22899 | 23xx | shipped v1.0.0 | none |
+| application-file-upload | 23101-23899 | 24xx | shipped v1.0.0 | none |
+| application-forms-wizard | 24101-24899 | 25xx | shipped v1.0.0 | none |
+| application-account-settings | 25101-25899 | 26xx | shipped v1.0.0 | none |
+| application-onboarding-tour | 26101-26899 | 27xx | shipped v1.0.0 | none |
+| persistence-data-postgres | 27101-27899 | 28xx | shipped v1.0.0 | `persistenceStore`, `migrationDiscipline` |
+| object-storage-s3 | 28101-28899 | 29xx | shipped v1.0.0 | `objectStorageContract` |
+
+The shelf-wide band registry lives in `packages/rcf-lite/docs/blueprint-authoring.md` section 5.
+
+## Cross-references
+
+- `application-spa` (round 1, shipped v1.5.0+): supplies the routing shell (`/tour`, `/dashboard`, `/settings`), the iconography and theming the tour uses. The tour still renders without the SPA blueprint; the project supplies its own routing.
+- `application-dashboard` (round 3, shipped v1.0.0): supplies the dashboard-top anchor slot where the checklist mounts as `<details open>` for returning principals. When absent, the checklist collapses to a `<details>` (closed) on the settings-page anchor (ADR-2703).
+- `application-notifications-in-app` (round 3, shipped v1.0.0): supplies the polite `aria-live` live region the tour-completion announcement uses. When absent, the tour is silent at the announce layer (the step runner still logs one line if a logging companion is present).
+- `application-account-settings` (round 4 T-4, shipped v1.0.0): supplies the settings surface where the restart-tour control lives. When absent, the restart-tour control renders on any settings-shaped surface (`/settings`, `/account`, `/account/settings`).
+- `application-empty-error-states` (round 4 T-1, shipped v1.0.0): the tour composes on the forbidden state when a principal reaches `/tour` without an authenticated session and an auth blueprint is applied. When no auth blueprint is applied, the tour behaves as a single-principal experience per the composition table.
+
+## 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 (always fires).
+- `AC-26102-1` tooltip-as-dialog contract at 1440 wide and 360 narrow breakpoints via `browser.resize` (always fires).
+- `AC-26103-1` checklist slot on both dashboard-top (open) and settings-page (closed) branches (always fires; branch selection reads the applied-blueprint set from the sidecar).
+- `AC-26104-1` completion-state persistence and restart-tour re-open (always fires; store selection reads the elicited `completion-state-store` answer, defaulting to `spa-local-storage` per Q4).
+
+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`). See `packages/rcf-lite/docs/blueprint-authoring.md` section 8c for the pack authoring rules.

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

@@ -0,0 +1,59 @@
+# application-onboarding-tour guide
+
+Operator-facing guide to the onboarding-tour blueprint. Reach for it when your project wants a keyboard-accessible product tour with a first-run checklist that composes on the surfaces you already have, and where the completion state honestly persists.
+
+## When to reach for this blueprint
+
+- You have a first-run onboarding narrative that fits 3 to 5 steps and every step anchors on a live element in your DOM.
+- You want the tour to honour WCAG 2.2 AA keyboard rules (2.1.1 Keyboard, 2.1.2 No Keyboard Trap, 2.4.3 Focus Order, 2.4.11 Focus Not Obscured Minimum) and the ARIA APG dialog-modal pattern out of the box, without a hand-rolled tooltip library.
+- You want a checklist surface that meets returning principals where they are (on the dashboard when the dashboard blueprint is applied, on the settings surface when it is not) and does not intrude when the tour is done.
+- You want a documented restart-tour affordance without inventing the persistence flow.
+
+## When NOT to reach for this blueprint
+
+- You need a multi-hour interactive product simulation. This blueprint contributes an onboarding contract, not a training platform.
+- Your tour has more than five steps per surface. Refactor into multiple applied tours (one per surface family) rather than one long tour.
+- You need per-org customisation of the tour content at runtime. The blueprint contributes the WHAT; the elicited `per-step-content-voice` is a project-owned string, not a per-tenant surface.
+
+## Standards trace
+
+- ARIA APG dialog-modal pattern (`https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/`): the tooltip is a modal dialog with `role="dialog"`, `aria-labelledby` to the step heading, `aria-describedby` to the step body, focus into the tooltip on open and back to the anchor on close.
+- WCAG 2.2 AA 2.1.1 Keyboard (`https://www.w3.org/WAI/WCAG22/Understanding/keyboard.html`): every tour control activatable with the keyboard.
+- WCAG 2.2 AA 2.1.2 No Keyboard Trap (`https://www.w3.org/WAI/WCAG22/Understanding/no-keyboard-trap.html`): Escape always exits; focus never permanently trapped.
+- WCAG 2.2 AA 2.4.3 Focus Order (`https://www.w3.org/WAI/WCAG22/Understanding/focus-order.html`): Tab reaches every tour control in DOM order inside the tooltip.
+- WCAG 2.2 AA 2.4.11 Focus Not Obscured Minimum (`https://www.w3.org/WAI/WCAG22/Understanding/focus-not-obscured-minimum.html`): the tooltip is visible at the 1440 wide and 360 narrow breakpoints (probed via `browser.resize`).
+
+## Q4 fallback
+
+When no persistence blueprint is applied AND the operator does not answer `completion-state-store` explicitly, the store defaults to `spa-local-storage` per Q4 of the ratified spec. 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; the elicit surface offers all three shapes for a deliberate override.
+
+## Mechanism-reach gaps
+
+- `AC-26105-1` first-run detection: manual verification via the fixture README boot line (open `/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; the manual VoiceOver smoke is in the fixture README.
+
+Both gaps ride runner cleanup `w-2026-09-04-dave-020`.
+
+## Compose targets
+
+The tour reaches these applied blueprints with the effect named in the README's composition table. None is a hard dependency; every unapplied target has a documented fallback.
+
+- `application-spa` (routing, iconography, theming).
+- `application-dashboard` (dashboard-top checklist anchor; fallback `settings-page`).
+- `application-notifications-in-app` (polite `aria-live` announce on completion; fallback silent at announce layer).
+- `application-account-settings` (restart-tour control home; fallback any settings-shaped surface).
+- Any `security-auth-*` (per-principal completion state; fallback per-browser bare namespace).
+
+## Apply
+
+```
+rcf define blueprint add <path-to>/blueprints/application-onboarding-tour
+```
+
+## Verify
+
+```
+rcf verify browser <fbs-id> --url <runtime-url> --probe-pack application-onboarding-tour --json
+```
+
+Runs the four checks against the shipped fixture at `packages/rcf-lite/test/fixtures/probe-pack-application-onboarding-tour/`. See the fixture README for the four break-switch runs the gate reviewer walks manually.