# Journeys

End-to-end multi-view flows for the Oshun V1 PWA. Per-view checklists verify
that each view _individually_ works; journeys catch the bugs that hide _between_
views — broken bridges, role-transition gaps, state that doesn't persist across
a navigation, audit trails that miss a step.

Read [`../00-conventions.md`](../00-conventions.md) for the file shape and the
walking discipline. Every journey opens with `# Journey: <name>` (no
frontmatter) and follows: Personas → Pre-conditions → numbered Steps →
Post-conditions → Failure modes → E2E coverage → Per-view files touched →
Cross-references → Open questions.

This index lists all **58** V1 PWA journeys. The six admin-app journeys live in
the separate [Admin journey index](../../ADMIN_WALKTHROUGH/journeys/README.md),
bringing the Docs Center registry total to 64.

## When to walk a journey

- **Before a release** — walk the journeys whose pre-conditions match the
  surfaces you're shipping. The per-view files won't catch a broken handoff; the
  journey will.
- **After a structural change** — middleware rewrite, auth refactor, SW cache
  version bump, BFF route move. Walk the journeys that touch the affected
  substrate.
- **When a customer reports something weird** — find the journey that describes
  their flow; the failure mode is probably already listed there.

## Bucket map

### First-time and PWA infrastructure (6)

| Journey                                                                | What it walks                                                                                                                                                                                                                                                 |
| ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`first-time-anonymous-visitor.md`](./first-time-anonymous-visitor.md) | Anonymous browser visit → landing → welcome → sign-up → verify → 10-step onboarding → first home. Catches public-surface gates and SEO.                                                                                                                       |
| [`first-tara-sit.md`](./first-tara-sit.md)                             | First-time user's very first Tara sit. Home rail → hub → Begin → mid-sit → completion → reflection. **Walkable end-to-end** (2026-05-26) — `TaraRoom` Begin links to `/tara/sit/[id]`; `TaraSitPlayer` ships timer/transcript/reflection.                     |
| [`install-as-pwa.md`](./install-as-pwa.md)                             | Browser visit → install eligibility → A2HS / native prompt → cold start → relaunch target → offline → reconnect → SW update → push → sign-out.                                                                                                                |
| [`offline-first-time-use.md`](./offline-first-time-use.md)             | Newly-installed PWA, network drops mid-session. Banner → cached read → queued write → reconnect → sync.                                                                                                                                                       |
| [`pwa-update-flow.md`](./pwa-update-flow.md)                           | SW `waiting` detected → `PwaUpdatePrompt` → `OSHUN_SKIP_WAITING` → `controllerchange` reload → old caches purged.                                                                                                                                             |
| [`onboarding-ten-steps.md`](./onboarding-ten-steps.md)                 | `/welcome` mode tabs → 10-step onboarding wizard (lineage / pace / sensitivities / accessibility / memory) → `patchProfilePreferences` → `resolveFirstRunEntryTarget` → first home with `OnboardingResumeBanner`. Distinct from the omnibus first-visit walk. |

### Customer-domain entries (6, one per V1 domain)

| Journey                                                      | What it walks                                                                                                                                                                                                                                |
| ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`tara-daily-ritual.md`](./tara-daily-ritual.md)             | Home rail continuation → Tara → today's sit → complete → reflection → return.                                                                                                                                                                |
| [`arete-create-habit.md`](./arete-create-habit.md)           | New habit creation flow. Goal → plan → habit setup → first check-in → streak begins.                                                                                                                                                         |
| [`veritas-evidence-trail.md`](./veritas-evidence-trail.md)   | Story → claim → evidence sources → counterclaim → save to library. Sophia citation flow embedded.                                                                                                                                            |
| [`nyx-tonight-observation.md`](./nyx-tonight-observation.md) | Tonight's sky event → detail → observation log entry.                                                                                                                                                                                        |
| [`nisaba-scholarly-read.md`](./nisaba-scholarly-read.md)     | Real search opens an Epictetus passage in the live workspace; the compact daily Dhammapada room and static Marcus Aurelius lanes remain separate, while the room retains a mismatched save id and no joined notebook/plan completion record. |
| [`metis-lesson-completion.md`](./metis-lesson-completion.md) | Course pick → lesson → assessment → tutor question → results.                                                                                                                                                                                |

### Customer-domain follow-ons (5)

| Journey                                                                                            | What it walks                                                                                                                                                                                                                                                         |
| -------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`arete-living-offering-create.md`](./arete-living-offering-create.md)                             | `/arete/offering` intent → Lilith crisis pre-screen → coach scoring (CBT/ACT/Stoic/Reflective) → keep → optional share. Uses real `POST /v1/arete/coach/responses`.                                                                                                   |
| [`weekly-review-arete.md`](./weekly-review-arete.md)                                               | Sunday push/reminder → `/arete/review` four acts (look back / acknowledge / pivot / commit) → KPIs + journal → continuity card → next-week plan.                                                                                                                      |
| [`veritas-retraction-cascade-customer-view.md`](./veritas-retraction-cascade-customer-view.md)     | Editorial retract → cascade fan-out → `veritas-retraction` banner on story → saved-claim banner → notebook drill-down → kept-Living-Offering banner. Customer side of `editorial-review-approval.md`.                                                                 |
| [`metis-byom-ingest-to-course.md`](./metis-byom-ingest-to-course.md)                               | Tenant teacher uploads BYOM → safety scan → Sophia ingestion → KG anchor → tenant teacher approval gate → published `CourseBuild` appears inline in `/metis` (the `MetisSchoolroom` course list — `/metis/courses` is not a route; only `/metis/courses/new` exists). |
| [`psyche-tutor-live-session-to-graded-record.md`](./psyche-tutor-live-session-to-graded-record.md) | `/metis/tutor` → Psyche real-time envelope → transcript auto-persists → Iris memory bridge → adaptive-loop mastery update → optional operator-metis review lane → optional Nisaba scholarly handoff. Distinct from `metis-lesson-completion` (quiz/assessment path).  |

### Discovery, messages, library (7)

| Journey                                                                                        | What it walks                                                                                                                                                                                                                                                                                                         |
| ---------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`messages-center-deliver-and-unsubscribe.md`](./messages-center-deliver-and-unsubscribe.md)   | Message arrives via channel adapter → `/messages` inbox → deep-link to artifact → delivery receipt → unsubscribe per channel × category.                                                                                                                                                                              |
| [`messages-quiet-hours-and-channel-binding.md`](./messages-quiet-hours-and-channel-binding.md) | Bind a channel (Telegram / WhatsApp / SMS / email) → consent → quiet-hours setup → Lilith persona-policy gate → first delivery respecting quiet hours.                                                                                                                                                                |
| [`telegram-bot-assistant-delivery.md`](./telegram-bot-assistant-delivery.md)                   | Bound Telegram user sends text or voice note to the bot → BFF webhook → Sophia-grounded composer → reply with disclosure footer + optional TTS audio. Delivery-side counterpart to `messages-quiet-hours-and-channel-binding.md`.                                                                                     |
| [`library-save-collection-share.md`](./library-save-collection-share.md)                       | In-domain Save → `/library` → create collection → multi-item add → share collection with permissions (private / link-with-key / public).                                                                                                                                                                              |
| [`search-explore-deep-read-library-save.md`](./search-explore-deep-read-library-save.md)       | `/search` query → filter facets → deep-read view → save to library → continue across devices (overlaps with `multi-device-workspace-handoff.md`).                                                                                                                                                                     |
| [`nyx-event-calendar-sync-reminder.md`](./nyx-event-calendar-sync-reminder.md)                 | Dynamic agenda feed, fixed rich detail, action preferences, durable member reminders, provider export, opt-in worker, service-worker tap, and observation are separate authorities. No joined detail-action → reminder → event-open → observation receipt exists. Complements `nyx-tonight-observation.md`.           |
| [`nisaba-notebook-capture-and-cite.md`](./nisaba-notebook-capture-and-cite.md)                 | Legacy reading durably associates annotations with BFF notebook items, while Studio separately authors Nisaba-native Postgres notebooks/cards and study-trail exports; local notes, client citations, silent fixtures, and the id-ignoring specimen remain other authorities. Complements `nisaba-scholarly-read.md`. |

### Cross-domain bridges (4)

| Journey                                                        | What it walks                                                                                                                                                                                                              |
| -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`tara-to-nisaba-handoff.md`](./tara-to-nisaba-handoff.md)     | Tara sit completion → contemplative reading hand-off to Nisaba. Bridge: `buildTaraNisabaPassageCompanion` + `NisabaPassageCompanionCard`.                                                                                  |
| [`nyx-to-tara-bridge.md`](./nyx-to-tara-bridge.md)             | Fixed Nyx event → static content relationship → Tara timer → generic Nyx suggestion. The hub cue is dormant; event identity, audio, emitted telemetry, member policy, durable completion, and exact return are not joined. |
| [`veritas-to-nisaba-deeper.md`](./veritas-to-nisaba-deeper.md) | Veritas grounded story → claim's primary source → Nisaba scholarly passage / commentary. Bridge: `resolveVeritasNisabaClaimRelationship`, `buildNisabaSourceLineageHref`.                                                  |
| [`arete-streak-recovery.md`](./arete-streak-recovery.md)       | Broken Arete streak → humane recovery copy → resumption. Tests Lilith tone policy as applied to Arete.                                                                                                                     |

### Lilith policy (1)

| Journey                                                        | What it walks                                                                                                                                                |
| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [`crisis-aware-tone-policy.md`](./crisis-aware-tone-policy.md) | User input expresses distress → Lilith substrate intercepts → safety surface → escalation. Includes false-positive, missed-true, and recovery failure modes. |

### Account, billing, identity (4)

| Journey                                                                    | What it walks                                                                                                                                                                                        |
| -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`account-deletion-and-dsar.md`](./account-deletion-and-dsar.md)           | `/profile` → DSAR/export request → identity verification → tombstone fan-out across domains → audit attestation → receipt. Covers GDPR right-to-deletion.                                            |
| [`memory-edit-pause-forget.md`](./memory-edit-pause-forget.md)             | `/profile/memory` → review entries → edit → conflict prompt → pause (off-the-record) → forget with step-up auth → 7-day grace. Iris memory UX per features.md.                                       |
| [`sign-up-and-pay-crypto.md`](./sign-up-and-pay-crypto.md)                 | `/welcome` sign-up → entitlement gate → `/billing/crypto` invoice → fiat-rate lock → settlement → `payment.invoice.confirmed` event → entitlement grant. Crypto payments + Aje bridge state machine. |
| [`aaa-upgrade-entitlement-bounce.md`](./aaa-upgrade-entitlement-bounce.md) | Customer hits AAA-only surface → middleware redirects to `/aaa-upgrade` → "Continue in Yemaya AAA Studio" → cross-app landing. AAA tier gating via `proxy.ts` + `studio-boundary.ts`.                |

### Scene + atelier authoring (7)

| Journey                                                                        | What it walks                                                                                                                                                                                                |
| ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [`scene-keep-and-share.md`](./scene-keep-and-share.md)                         | Living Scene completion → keep (private) → opt-in share → privacy level (private link / password / public) → `/scene/<id>` viewer → embed code → revoke. Uses `LivingScene` unlock-token cookie (P1.3 / P3). |
| [`public-scene-abuse-report.md`](./public-scene-abuse-report.md)               | Anonymous viewer at `/scene/<id>` → "Report" link → `/scene/<id>/report` form → Lilith review queue → operator triage. Read-side counterpart for unauthenticated visitors.                                   |
| [`scene-public-viewer-anonymous.md`](./scene-public-viewer-anonymous.md)       | `/scene/<id>` consumption by an anonymous visitor: password gate, OG preview, accessibility chrome, captions/transcript, watermark, retire-status fall-through.                                              |
| [`atelier-image-to-library.md`](./atelier-image-to-library.md)                 | `/atelier` index → pick image room → generate → "Save plate to notebook" → library appearance with provenance.                                                                                               |
| [`atelier-video-render-queue.md`](./atelier-video-render-queue.md)             | `/atelier/video` → inspect twelve storyboard shots → verify sh 06 render progress and queued shots → confirm Cut timeline remains an honest placeholder.                                                     |
| [`atelier-motion-to-cinematheque.md`](./atelier-motion-to-cinematheque.md)     | `/atelier/motion` → inspect rigged stage/timeline/bake/takes → placeholder draft actions stay disabled → "Open in Cinematheque" routes to `/atelier/video`.                                                  |
| [`lilith-studio-tara-scene-publish.md`](./lilith-studio-tara-scene-publish.md) | `/lilith-studio` → scene editor → zone placement → simulate → accessibility checks → publish through editorial release branch → consumer sees the new scene on `/tara`.                                      |

### Agentic pipelines (1)

| Journey                                                                                | What it walks                                                                                                                                                                                                                                                                                  |
| -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`agentic-pipeline-customer-invocation.md`](./agentic-pipeline-customer-invocation.md) | Single template walking any of the six Cross-Domain Autonomous Pipelines (`veritas.story_drafting`, `metis.course_from_byom`, `tara.seasonal_program`, `nyx.event_explainer_set`, `arete.weekly_review_draft`, `nisaba.edition_study_guide`) end-to-end. Includes per-pipeline variants table. |

### Assistant, operator, tenant — extended (7)

| Journey                                                                                          | What it walks                                                                                                                                                                                                                                                          |
| ------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`assistant-handoff-context-carry.md`](./assistant-handoff-context-carry.md)                     | Assistant dock invocation from any domain → assistant panel → context handoff (current view, recent reads/sits, persona) → cross-domain persona switch → Iris memory recall → disclosure rendering.                                                                    |
| [`tenant-bulk-member-invite-scim.md`](./tenant-bulk-member-invite-scim.md)                       | `/operator/tenant` → Export CSV / Invite / "+ Add member" / SCIM 2.0 batch → identity-provider provision callback → role assignment defaults → per-invitee first-login. Bulk path, distinct from per-member `tenant-onboard`.                                          |
| [`tenant-bulk-operations-export.md`](./tenant-bulk-operations-export.md)                         | Platform operator drafts, validates, dry-runs, stages, and commits a tenant users bulk operation; generates and verifies bulk export manifests; and checks audit/search read-back.                                                                                     |
| [`tenant-integrations-api-keys-webhooks.md`](./tenant-integrations-api-keys-webhooks.md)         | Tenant/operator integration admin creates, rotates, and revokes API keys; uses one against a scoped tenant resource; creates signed webhook subscriptions; fires sandbox simulator deliveries; and verifies audit/search read-back.                                    |
| [`tenant-oneroster-roster-sync.md`](./tenant-oneroster-roster-sync.md)                           | Tenant operator dry-runs OneRoster users/enrollments, inspects the operator diff table, commits a conflict-free import, reconciles a periodic SIS pull, and verifies roster summaries.                                                                                 |
| [`tenant-sso-config-saml-oidc-claim-mapping.md`](./tenant-sso-config-saml-oidc-claim-mapping.md) | Tenant admin uploads SAML metadata XML / OIDC discovery URL → maps external claims onto tenant role templates → sets MFA / IP allowlist / device-posture policy → test sign-in → enable. **Setup-side** of `tenant-bulk-member-invite-scim` Step 5 (consumption-side). |
| [`tenant-audit-log-investigation.md`](./tenant-audit-log-investigation.md)                       | Operator opens `/operator/admin` audit explorer → filter audit events (`editorial.*` / `incident.*` / `drift.*` / `tenant.*` / `flag.*`) → save investigation → add notes → export bundle with chain-of-custody hash.                                                  |

### Operator + studio + cross-surface (8)

| Journey                                                                                    | What it walks                                                                                                                                                                                                                                                                                               |
| ------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`editorial-review-approval.md`](./editorial-review-approval.md)                           | Author submits → operator-studio review queue → approve / request changes → publish → audit. Studio authoring + operator surface.                                                                                                                                                                           |
| [`incident-triage.md`](./incident-triage.md)                                               | Auto-INC fires → admin inbox → operator triages → resolves → audit.                                                                                                                                                                                                                                         |
| [`citation-drift-resolution.md`](./citation-drift-resolution.md)                           | Citation drift detected on artifact → INC routes → Isis provenance inspector → hash chain checked → resolve.                                                                                                                                                                                                |
| [`tenant-onboard.md`](./tenant-onboard.md)                                                 | Tenant admin invites member → SCIM provision → role assignment → first-login → first-action. Multi-surface (operator → email → customer → operator).                                                                                                                                                        |
| [`user-flag-to-review.md`](./user-flag-to-review.md)                                       | Customer flags content → routed to admin inbox → operator action → user notified. The first-pass flag affordance now ships on Veritas / Nisaba / Tara surfaces and browser E2E reads the submitted live report back from the admin moderation queue; operator decision + reporter notification remain open. |
| [`sophia-grounded-answer.md`](./sophia-grounded-answer.md)                                 | Query needing citations → Sophia composes answer with citation trail → user verifies sources → optional pin.                                                                                                                                                                                                |
| [`themis-assessment-appeal.md`](./themis-assessment-appeal.md)                             | Student receives assessment verdict with Themis academic-integrity flag → opens appeal with rationale + evidence → tenant teacher reviews in `/operator/metis` → override / upheld → student notified → audit chain captures full lifecycle.                                                                |
| [`persona-voice-avatar-approval-workflow.md`](./persona-voice-avatar-approval-workflow.md) | Creator proposes new persona (role + lineage + voice profile + avatar pack) in `/lilith-studio/personas` → Lilith quality eval → voice-quality + avatar reviewer checks → operator-studio publish gate → deployed to session-selection → eventual deprecation / supersession.                               |

### Platform integrations (1)

| Journey                                                      | What it walks                                                                                                                                                                       |
| ------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`lms-connectors-operator.md`](./lms-connectors-operator.md) | Operator lists, validates, creates, overrides, and removes LMS connectors; verifies LTI launch boundaries, capability health, source precedence, and fail-closed provider behavior. |

### Workspace shell (1)

| Journey                                                                    | What it walks                                                                                                                                                                                                                                                                        |
| -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [`multi-device-workspace-handoff.md`](./multi-device-workspace-handoff.md) | Desktop researcher captures a six-item Iris packet, stores one latest per-user BFF record, and can expose it on native Home. Current return stops at an assistant prompt; responsive browser restoration, fixture Library, device inventory, and profile sync are separate evidence. |

## Cross-cutting findings from the journey sweep

These findings came from tracing multi-view paths rather than reading each route
in isolation. Their status below is reconciled against the current source.

1. **The historic ghost-button sweep is nearly closed.** Tara start actions;
   Arete ritual, coach, and navigation actions; Veritas save/source/share
   actions; Nyx event and cross-domain links; Nisaba save, speech, citation, and
   navigation actions; Metis quiz, assessment, course, citation, and composer
   actions; Trust & Safety reporting; studio review decisions; Admin inbox
   filtering and row selection; tenant export/invite/member actions; and Nyx
   event persistence now have concrete handlers or links. The remaining known
   inert controls are `Not now`, `Tell me more`, and `Apply for one week` in the
   deeper Arete coaching letter (`components/lilith/arete.tsx`). Relevant
   journey failure-mode sections carry the exact open checks.
2. ~~**`user-flag-to-review` cannot be walked at all.**~~ **Resolved.** A
   `TrustSafetyFlagButton` flag affordance now ships on Tara
   (`TaraSitPlayer.tsx:320`), Veritas (`VeritasArticleActions.tsx:115`,
   `VeritasClaimDetailWorkspace.tsx`), and Nisaba
   (`NisabaPassageActions.tsx:109`), and the BFF exposes `POST /v1/user-reports`
   (`apps/oshun/bff/src/routes/user-reports.ts:107`). The intake-to-admin-queue
   segment is now walkable and verified against the moderation workspace; see
   `shell/07-trust-safety.md`.
3. **Lilith crisis substrate is intentionally not a single route.** The
   substrate lives in `libs/oshun/persona-policy-lilith/src/crisis-recovery/`
   (incident-record, stillness-window, reentry-flow, reframe-protection,
   locales, check-ins) and is wired through each Lilith-using surface; the
   safety surface mounts in-place on the active surface. User-facing audit lives
   at `/profile/safety`. A dedicated `/lilith/crisis` route would conflict with
   the cascade design.
4. ~~**`LCustomerNav active` inconsistency in Veritas.**~~ Resolved — both the
   hub (`rooms.tsx#VeritasRoom`) and the depth views in
   `components/lilith/veritas.tsx` now mount `LCustomerNav active="library"`.
   The earlier "Hub mounts explore; depth mounts library" claim was stale by the
   time the journey sweep landed.
5. **Polished vs internal namespace drift carries between views.** `/arete`
   reads `getArete()` fixture; `/domains/arete/habits` reads `sampleHabits`.
   Habits created in one are invisible in the other. Same dual-fixture pattern
   in Tara, Nyx, Veritas. Affects how journeys land after navigation.
6. **Display specimens posing as live editors.** `/nisaba/notebook` claims "last
   edit, 11 min ago" without an edit affordance. The former `/metis/lesson` quiz
   specimen and `/metis/assessment` blinking-cursor answer specimen have shipped
   as real interactive components; the Metis journey docs track their remaining
   product gaps separately.
7. **Operator audit trail is the universal stamp.** Every operator journey
   writes to `apps/oshun/bff/src/routes/admin-audit-log.ts` (routes
   `/admin/audit-log/events` and `/admin/audit-log/investigations`). Audit-event
   taxonomies are documented per journey: `editorial.*`, `incident.*`,
   `drift.*`, `tenant.*`, `flag.*`.
8. **One previously grouped BFF gap remains.** The tenant invitation and T&S
   report writes now ship at `POST /v1/admin/tenant-console/members/invite` and
   `POST /v1/user-reports`; the author-side editorial submit route remains a
   documented journey gap. (The SCIM 2.0 endpoint also ships —
   `/v1/scim/v2/Users` in `apps/oshun/bff/src/routes/domain-stubs.ts`: GET list,
   GET `/:id`, POST, PATCH `/:id`, DELETE tombstone; no PUT.)
9. **Recommendation engine BFF target undocumented.** The recommendation engine
   surfaces in cross-domain bridges (Tara → Nisaba, Nyx → Tara) but the BFF
   endpoint is referenced only obliquely
   (`apps/oshun/bff/src/recommendations/`). Each cross-domain journey flags
   this.

## Adding a new journey

1. Pick a flow that traverses ≥ 2 views and has a clear pre-condition and
   post-condition.
2. Confirm every view it touches has a per-view walkthrough; if not, write those
   first.
3. Copy [`install-as-pwa.md`](./install-as-pwa.md) as a starting shape.
4. Ground every step in real component / route / contract names from the
   per-view files. Don't invent.
5. Use `ls` to confirm every per-view link target exists before committing.
6. Add the new entry to the bucket map above with a one-line summary.