rcf-lite 0.20.0 → 0.22.0

package/blueprints/application-onboarding-tour/contributions/adrs/adr-2701-application-onboarding-tour-dismissal-policy.json

@@ -0,0 +1,20 @@
+{
+  "adrId": "ADR-2701-application-onboarding-tour-dismissal-policy",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Dismissal policy: dismiss-permanently default, dismiss-until-next-major or dismiss-until-next-minor",
+  "context": "A dismissed tour has three legal re-open behaviours. Dismiss-permanently is the least intrusive: a principal who dismissed the tour once never sees it again unless the restart-tour control fires. Dismiss-until-next-major re-opens the tour when the applied blueprint set makes a major-version bump (a new tour surface a returning principal has not seen). Dismiss-until-next-minor re-opens on a minor bump for the same reason at higher frequency. The spec section 5.5 names all three; the recommended default is dismiss-permanently because a returning principal who dismissed the tour deliberately signalled that they do not want re-onboarding, and the restart-tour control on the settings surface remains available.",
+  "decision": "dismissal-policy is elicited (enum: dismiss-permanently | dismiss-until-next-major | dismiss-until-next-minor). Recommended default: dismiss-permanently. The step runner honours the answer by comparing the CompletionRecord.blueprintSetVersion against the current applied blueprint set version at principal load: dismiss-permanently never re-opens; dismiss-until-next-major re-opens when the major differs; dismiss-until-next-minor re-opens when the major or the minor differs. A blueprintSetVersion mismatch always renders the checklist on the resolved anchor even when the tour does not auto-open.",
+  "consequences": "A returning principal in the dismiss-permanently branch is not re-onboarded on any bump; a project that adds a major surface (a new admin console, a new billing area) can prompt returning principals through a restart-tour affordance on the release note surface rather than an intrusive re-open. A project that opts into dismiss-until-next-major or dismiss-until-next-minor accepts the interruption for the benefit of re-onboarding on shipped changes; the CompletionRecord.stepIds field lets the step runner skip already-seen steps when a re-open fires.",
+  "alternativesConsidered": [
+    {
+      "name": "Alternative approach considered",
+      "summary": "A time-based re-open (re-open after 30 days) was considered but time-based re-opens do not correlate with actual product changes; a returning principal on a stable product would be re-onboarded on nothing. Version-based re-opens correlate with real surface changes and let the operator choose the frequency.",
+      "reasonNotChosen": "See the decision text; the chosen shape composes cleanly with the applied blueprint set the spec section 5.5 names."
+    }
+  ],
+  "createdAt": "2026-09-06T23:15:00Z",
+  "updatedAt": "2026-09-06T23:15:00Z"
+}

package/blueprints/application-onboarding-tour/contributions/adrs/adr-2702-application-onboarding-tour-completion-store-shape.json

@@ -0,0 +1,20 @@
+{
+  "adrId": "ADR-2702-application-onboarding-tour-completion-store-shape",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Completion-state store shape: spa-local-storage default (Q4 fallback), spa-session-storage or server-side-per-principal",
+  "context": "The completion state needs a store. Three shapes are legal. spa-local-storage keeps the completion state per browser and per principal identifier; a returning principal on the same browser is not re-onboarded, and a different browser (or a private window) is re-onboarded. spa-session-storage keeps the completion state per session and re-plays the tour on every new session; useful only for a project that deliberately wants a per-session refresher. server-side-per-principal keeps the completion state on the principals record so it follows the user across devices; requires an applied persistence blueprint and the projects own writer adapter. The spec section 5.5 and section 10 Q4 ratify spa-local-storage as the fallback when no persistence blueprint is applied 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.",
+  "decision": "completion-state-store is elicited (enum: spa-local-storage | spa-session-storage | server-side-per-principal). Recommended default: spa-local-storage. At apply time the elicit surface offers all three; a project that answers server-side-per-principal without an applied persistence blueprint hits a documented refusal (the elicit's when predicate refuses per the mechanism minor T-5 does not extend; the refusal is enforced at the surface load by TAC-2703 which refuses to construct a server-side backend without a resolved persistence adapter and falls back to spa-local-storage with a documented note on the sidecar).",
+  "consequences": "A project with no persistence blueprint applied gets the spa-local-storage backend automatically per the Q4 fallback; a project with a persistence blueprint and the server-side-per-principal answer gets a cross-device tour completion; a project answering spa-session-storage accepts a per-session re-onboarding. The dismiss-until-next-major and dismiss-until-next-minor policies (ADR-2701) still work under any of the three shapes because the CompletionRecord.blueprintSetVersion travels with the record.",
+  "alternativesConsidered": [
+    {
+      "name": "Alternative approach considered",
+      "summary": "spa-session-storage as the default was considered but re-onboarding on every new session is intrusive on a stable product; the Q4 ratification names spa-local-storage as the fallback for that reason.",
+      "reasonNotChosen": "See the decision text; the chosen default composes cleanly with the applied blueprint set the spec section 5.5 names."
+    }
+  ],
+  "createdAt": "2026-09-06T23:15:00Z",
+  "updatedAt": "2026-09-06T23:15:00Z"
+}

package/blueprints/application-onboarding-tour/contributions/adrs/adr-2703-application-onboarding-tour-checklist-anchor.json

@@ -0,0 +1,20 @@
+{
+  "adrId": "ADR-2703-application-onboarding-tour-checklist-anchor",
+  "prdId": "PRD-001",
+  "tadId": "TAD-001",
+  "version": "1.0.0",
+  "status": "accepted",
+  "title": "Checklist anchor slot: dashboard-top when application-dashboard is applied, settings-page when not, custom-anchor as escape hatch",
+  "context": "The checklist has three legal homes. dashboard-top when application-dashboard is applied because the dashboard shell is the highest-value surface a returning principal reaches. settings-page when application-dashboard is not applied because the settings surface is the next-highest-value reference surface. custom-anchor when the project prefers a bespoke slot (a marketing surface, a landing shell, a home route). The spec section 5.5 ratifies all three and marks the anchor as elicited with a default derived at apply time from what is applied.",
+  "decision": "checklist-anchor is elicited (enum: dashboard-top | settings-page | custom-anchor). Recommended default: derived at apply time (dashboard-top when application-dashboard is in the applied set; settings-page when it is not; custom-anchor requires the projects own CSS selector). The collapse contract is a <details open> element on dashboard-top and a <details> (closed) element on settings-page; custom-anchor takes the setting-page default (closed) unless the project supplies an override.",
+  "consequences": "A project applying application-dashboard renders the checklist open on the dashboard shell so a new principal sees the outstanding items at a glance; a project not applying application-dashboard renders it closed on the settings surface so it does not intrude; a project with a custom-anchor takes responsibility for the placement. AC-26103-1 probes the collapse contract on the two shipped anchors; custom-anchor is verified by the fixture READMEs manual boot line.",
+  "alternativesConsidered": [
+    {
+      "name": "Alternative approach considered",
+      "summary": "Auto-selecting always to the dashboard-top slot regardless of the applied set was considered but a project without application-dashboard applied has no dashboard shell to mount into; the checklist would be lost. Deriving the default from the applied set at apply time keeps the anchor honest.",
+      "reasonNotChosen": "See the decision text; the chosen shape composes cleanly with the applied blueprint set the spec section 5.5 names."
+    }
+  ],
+  "createdAt": "2026-09-06T23:15:00Z",
+  "updatedAt": "2026-09-06T23:15:00Z"
+}

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

@@ -0,0 +1,18 @@
+{
+  "reqId": "application-onboarding-tour-REQ-001",
+  "prdId": "PRD-001",
+  "title": "Step-manifest contract: 3 to 5 steps per tour with per-step anchor selector and per-step content voice slot",
+  "description": "The blueprint contributes a step-manifest contract for a 3 to 5 step onboarding tour. Each step declares a step id, an anchor selector (CSS resolved at step-open time to place the tooltip against a live element in the DOM), a heading and a body slot the project fills with its own voice. The step runner walks the manifest in order and refuses to open a step whose anchor does not resolve to a visible element rather than rendering a floating tooltip. The blueprint contributes the WHAT (the manifest shape and the resolver contract), not the words.",
+  "category": "functional",
+  "domain": "application",
+  "priority": "must",
+  "rationale": "Per visual round 4 spec (2026-09-06) section 5.5, REQ 1 of the onboarding-tour blueprint.",
+  "tags": [
+    "blueprint:application-onboarding-tour",
+    "category:01-step-runner"
+  ],
+  "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-002.json

@@ -0,0 +1,18 @@
+{
+  "reqId": "application-onboarding-tour-REQ-002",
+  "prdId": "PRD-001",
+  "title": "Tooltip-as-dialog contract per the ARIA APG dialog-modal pattern",
+  "description": "Each step's tooltip carries role=\"dialog\", aria-labelledby to the step heading, aria-describedby to the step body. Focus moves to the tooltip on open, focus returns to the anchor on close. The dialog traps focus between the tour controls (previous, next, dismiss) and refuses to let Tab escape to the underlying surface (WCAG 2.1.2 No Keyboard Trap satisfied because Escape always exits). Escape dismisses the tour. Focus is not obscured on any breakpoint (WCAG 2.4.11 Focus Not Obscured Minimum). Follows the ARIA APG dialog-modal pattern for the tooltip surface.",
+  "category": "functional",
+  "domain": "application",
+  "priority": "must",
+  "rationale": "Per visual round 4 spec (2026-09-06) section 5.5, REQ 2 of the onboarding-tour blueprint.",
+  "tags": [
+    "blueprint:application-onboarding-tour",
+    "category:02-dialog-modal"
+  ],
+  "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-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.