cocottetech/@platform/codebase/@features/ai-copilot/docs/README.md

# ai-copilot — design briefs

Inputs for design agents (`frontend-design`, design subagents) shaping the
**CocotteAI** iOS primary surface and the `ai.cocotte.maison` web companion.

## Quick map

```
00-system-*.md                 Foundation — visual system + voice + conversational UX. Read first.
[A-V]-*.brief.md               Thematic UX dimensions (A daily-driver → V data portability).
{X,Y,Z,AA,…,AF}-*.brief.md     Cross-cutting + speculative dimensions (X accessibility · Y marketplace · Z billing · AA marketing · AB Watch/Vision · AC second-member · AD multilingual-opaque · AE peer-social · AF encryption+hw-keys).
<topic>.brief.md               Cross-cutting topic-named briefs that don't fit the dimension model (e.g. cross-surface-fanout).
surface-<id>.brief.md          Per-surface deep briefs (surface-tryst is the first / template).
specialist-roster.md           Index of per-specialist contracts.
specialist-*.contract.md       Per-specialist contract cards (split out of brief L).
_engineering-*.md              Port-map + non-UX annexes. Reference only.
_deprecated-*.md               Superseded; kept for traceability. Don't create new ones — git keeps history.
<topic>.flow.md                End-to-end conversational flow narration (per 00-system-conversational-ux).
<surface>-<topic>.{screen,flow}.md  Surface-scoped screen or flow (e.g. tryst-inbox.screen.md).
<topic>.screen.md              Single-screen breakdown (layout, components, states, capabilities, invoking flows).
OPEN-DECISIONS.md              Blocking / nice-to-have / exploratory open questions.
README.md                      This file.
```

**Naming is dual-track** (decided 2026-05-18). Letter-prefixed (A–AD) for thematic dimensions; topic-named (no letter) for cross-cutting patterns + per-surface briefs. See File-shape conventions below for the full rules.

**Flat dir convention:** every doc lives at the top of `docs/` — no subdirectories. Prefixes encode role.

## Dependency map

```mermaid
flowchart TD
  classDef foundation fill:#fde,stroke:#a36,color:#000
  classDef core fill:#def,stroke:#369,color:#000
  classDef ops fill:#efd,stroke:#393,color:#000
  classDef domain fill:#fed,stroke:#963,color:#000
  classDef annex fill:#eee,stroke:#999,color:#333,stroke-dasharray: 3 3

  subgraph FOUND[Foundation]
    VS[visual-system]:::foundation
    VC[voice]:::foundation
    CX[conversational-ux]:::foundation
  end

  subgraph CORE[Daily-driver core]
    A[A · chat-surface]:::core
    B[B · drawers]:::core
  end

  subgraph ENTRY[Entry / shape]
    D[D · onboarding]:::core
    E[E · cross-platform]:::core
  end

  subgraph OPS[Operations]
    C[C · notifications]:::ops
    G[G · web-surfaces]:::ops
    H[H · recurring-chores]:::ops
    I[I · audit-trust-replay]:::ops
    P[P · inboxes]:::ops
    Q[Q · vigil-journal-autoconvo]:::ops
  end

  subgraph DOMAIN[Domain / safety / fleet]
    K[K · safety-blocklist]:::domain
    L[L · specialists-fleet]:::domain
    M[M · error-degraded]:::domain
    N[N · provider-coop]:::domain
    O[O · surfaces-roster]:::domain
  end

  O --> R & S & U

  subgraph SPEC[Cross-cutting / speculative]
    R[R · tours-events-hotels]:::domain
    S[S · settings-ia]:::ops
    T[T · analytics-dashboard]:::ops
    U[U · global-search]:::ops
    V[V · data-portability]:::ops
    W[W · org-overlay-P5+]:::annex
    X[X · accessibility]:::annex
    Y[Y · marketplace-P5+]:::annex
    Z[Z · billing-P5+]:::annex
    AA[AA · marketing-site]:::annex
    AB[AB · watch+vision-P5+]:::annex
    AC[AC · second-member-P5+]:::annex
    AD[AD · multilingual-opaque]:::annex
    AE[AE · peer-social-P5+]:::annex
    AF[AF · encryption+hw-keys]:::annex
  end

  subgraph CROSS[Cross-cutting topic-named]
    XSF[cross-surface-fanout]:::core
    STR[surface-tryst — template]:::domain
  end

  JX[_engineering-v2-port-map]:::annex
  JE[_engineering-surface-adapter-container]:::annex
  JC[_engineering-credentials-vault]:::annex

  VS --> A & B & G & E & K & L & M & R & S & T & U & V
  VC --> A & C & D & H & K & L & N & R & S & T & V & W
  CX --> A & B & H & I & STR & XSF
  A --> B
  B --> D
  E --> A & B
  C --> G
  H --> B & K
  I --> A & B & H
  G --> A & B
  K --> B & H & I & P & Q
  L --> A & B & C & I & K
  M --> A & C & H & I & K & L
  N --> M
  O --> C & H & I & K & L
  P --> A & B & C & D & I & K & L & M
  Q --> A & B & H & I & K & L & P
  R --> B & H & I & K & L & N & Q
  S --> A & B & C & D & H & I & K & L & O & P & Q & R & T & U & V
  T --> A & I & R & V
  U --> A & B & I & K & N & P & Q & R & S & V
  V --> I & K & N & Q & S & C
  W --> A & B & D & I & L & N & S & T & U & V
  X -.cross-cuts.-> A & B & C & D & E & G & H & I & K & L & M & N & O & P & Q & R & S & T & U & V & W
  Y --> D & N & W & Z & AA
  Z --> M & O & S & W
  AA --> K & N & I & Y & Z
  AB --> A & C & E
  AC --> D & W & S
  AD -.cross-cuts.-> A & D & I & K & L & M & X
  AE -.cross-cuts.-> A & B & I & K & L & N & W & AD
  AF -.cross-cuts.-> AE & Q & N & I & V & W & D & S & X & AB & AD
  XSF --> A & H & I & L & M & N
  STR --> O & H & K & I & L & M
  JX -.references.-> A & C & G & H & I & L & N
  JE -.references.-> STR & K & M & V
  JC -.references.-> STR & V & K & I
```

**Read order** (skim-then-deep-dive):

1. `00-system-visual-system.md` + `00-system-voice.md` + `00-system-conversational-ux.md` — foundation; every brief inherits these. **Conversational-ux is the load-bearing read** for understanding how the screens + flows relate.
2. `A-chat-surface` + `B-drawers` — the daily-driver core (the surface conversation lives on).
3. `cross-surface-fanout.brief.md` — the canonical conversational management form ("apply to all"). Subsumes H §H4.
4. `H` + `I` + `K` — the three highest-impact dimensions for revenue + safety.
5. `O` — the canonical surfaces roster (referenced by F, H, K, L, P, Q).
6. `surface-tryst.brief.md` + `tryst-connect.flow.md` — first per-surface deep brief + first conversational flow; together they're the template for how every surface gets documented.
7. Anything else in the order you need it; the graph above shows real dependencies.

## Briefs

| # | Brief | What it covers |
|---|-------|---------------|
| **sys** | [`00-system-visual-system.md`](./00-system-visual-system.md) | Tokens, typography, motion, stakes semantics, 24-surface iconography (F5), component library. Foundation — everything inherits. |
| **sys** | [`00-system-voice.md`](./00-system-voice.md) | Register gradient (hearth / working / plain), per-specialist voice lean, copy patterns, banned phrases. Linguistic foundation. |
| **sys** | [`00-system-conversational-ux.md`](./00-system-conversational-ux.md) | Conversation is the session; screens are rich-input/output surfaces Cocotte invokes mid-conversation. Capabilities model (rich-output / rich-input / structured-editor / approval / confirmation / inspector). Flows are first-class. Foundation. |
| **A** | [`A-chat-surface.brief.md`](./A-chat-surface.brief.md) | Primary chat surface in CocotteAI (iOS). 10 states, gestures, voice, multimodal input. |
| **B** | [`B-drawers.brief.md`](./B-drawers.brief.md) | Full-screen contextual views opened from chat — calendar, asset library, prospect, agent-actions, persona, specialist. |
| **C** | [`C-notifications.brief.md`](./C-notifications.brief.md) | Channel × stakes × specialist matrix; iOS push / iMessage / email digest; stakes-aware deeplinks. |
| **D** | [`D-onboarding.brief.md`](./D-onboarding.brief.md) | First-run: SSO device-link → persona-seed interview → empty state. |
| **E** | [`E-cross-platform.brief.md`](./E-cross-platform.brief.md) | iPhone canonical; iPad / macOS / web variants; dark / light. |
| **G** | [`G-web-surfaces.brief.md`](./G-web-surfaces.brief.md) | Secondary web FEs on vps-0 — content-portal, engagement-portal, agent-actions log viewer, ai.cocotte.maison companion. |
| **H** | [`H-recurring-chores.brief.md`](./H-recurring-chores.brief.md) | Tryst bumps, TS4Rent bumps, multi-surface profile edits, tours. **The biggest single time-suck CocotteAI eliminates.** §H5 covers 8+ surface density. |
| **I** | [`I-audit-trust-replay.brief.md`](./I-audit-trust-replay.brief.md) | Trust loop — daily digest, audit drawer, row detail with feedback, counter-actions, trust panel + policy graduations. |
| **K** | [`K-safety-blocklist.brief.md`](./K-safety-blocklist.brief.md) | Hard edges — blocklists, cross-surface guardrails (K3a–K3k across 24-surface roster), jurisdiction rules, **kill switch**. |
| **L** | [`L-specialists-fleet.brief.md`](./L-specialists-fleet.brief.md) | Fleet roster + user-facing specialist UX + lifecycle. Per-specialist contracts now in [`specialist-roster.md`](./specialist-roster.md). |
| **M** | [`M-error-degraded-modes.brief.md`](./M-error-degraded-modes.brief.md) | Failure-mode taxonomy across stack layers, three user-facing degradation states, notification fallback hierarchy. Plain-register companion to K. |
| **N** | [`N-provider-coop.brief.md`](./N-provider-coop.brief.md) | Inter-org provider-coop safety-intel network — opt-in membership, attributed/anonymous reports, peer discovery, dispute / moderation. |
| **O** | [`O-surfaces-roster.brief.md`](./O-surfaces-roster.brief.md) | Canonical 24-surface enumeration. N1 content / N2 directories / N3 brand sites / N4 channels / N5 commerce. |
| **P** | [`P-inboxes.brief.md`](./P-inboxes.brief.md) | Unified inbox across iMessage / SMS / multiple Proton / Gmail / per-surface DMs. Inbound counterpart to C's outbound notifications. |
| **Q** | [`Q-vigil-journal-auto-conversations.brief.md`](./Q-vigil-journal-auto-conversations.brief.md) | Ambient layer — vigil detection, auto-journaling, auto-conversation visibility. |
| **R** | [`R-tours-events-hotels.brief.md`](./R-tours-events-hotels.brief.md) | Touring backbone — discovery (event-anchored) → planning (floor/target) → hotel selection (Tor-pool scout) → active execution → close + post-mortem. Multi-leg routing (§R6 traveling-salesman). New `bookings-hotels` specialist. |
| **S** | [`S-settings-ia.brief.md`](./S-settings-ia.brief.md) | Settings backbone — index of every toggle across the corpus. 8 categories (S1 account · S2 voice · S3 notifications · S4 specialists · S5 surfaces · S6 safety · S7 tours · S8 privacy), 3 depth levels (quick toggles · category drawers · per-setting sheets), search, advanced gate, recently-changed audit-shadow, conflict warnings. |
| **T** | [`T-analytics-dashboard.brief.md`](./T-analytics-dashboard.brief.md) | Strategist's front-window. 5 panels — T1 revenue · T2 prospect funnel · T3 per-surface · T4 cohort warmth · T5 tour ledger. Once-per-vigil refresh; anomalies surface to chat. iOS drawer + web companion full page. The *how is it going* surface complementing brief I (*what was done*). |
| **U** | [`U-global-search.brief.md`](./U-global-search.brief.md) | One search across the corpus — prospects, messages, audit, plans, posts, assets, tour legs, hotels, settings, specialists, briefs, journals. Typed grouped results; tap to land in originating drawer. Lightweight operators (`@`, `#`, `type:`, `surface:`, `since:`). Voice query. Per-drawer filters reuse the component. |
| **V** | [`V-data-portability-erasure.brief.md`](./V-data-portability-erasure.brief.md) | Three flows: V1 Quinn-side full export (scope + format + size estimate + download), V2 staged erasure (30-day cooling-off, redact-not-delete audit, coop carve-out), V3 prospect-side SAR (composer + redaction preview + send). Plain register throughout. Privacy invariants cross-cut K, N, Q. |
| **W** | [`W-org-overlay.brief.md`](./W-org-overlay.brief.md) | Multi-tenant context switcher (P5+ pre-design). Top-bar chip · 3 scope categories (personal-only / scoped / org-only) · per-surface inheritance · org roster with admin/member/viewer roles · cross-context prospect handoff · org-context voice shift. Forward-compat for platform.db org_id columns shipped P0. |
| **X** | [`X-accessibility.brief.md`](./X-accessibility.brief.md) | Accessibility deep-dive. X1 VoiceOver · X2 Dynamic Type · X3 Reduced motion · X4 Color contrast · X5 Switch Control · X6 Voice-as-input · X7 per-brief audit index. Cross-cuts every brief with an `## Accessibility` mini-section by reference. |
| **Y** | [`Y-cross-org-marketplace.brief.md`](./Y-cross-org-marketplace.brief.md) | Multi-provider onboarding (P5+) when CocotteAI opens beyond Quinn/Demimonde. Y1 Discovery · Y2 Cold persona-seed at scale · Y3 Per-provider personalization · Y4 Cross-provider coop discovery · Y5 Per-provider analytics scope · Y6 Voice fork · Y7 Provider isolation · Y8 Departure flow. Distinguished from AC (org-internal invite) and D (cold first-run). |
| **Z** | [`Z-billing-payments.brief.md`](./Z-billing-payments.brief.md) | Billing + payments (P5+). Z1 Tier landing · Z2 Per-feature gating · Z3 Metered LLM cost transparency · Z4 Quota self-throttling (per M §M5) · Z5 Org-level billing · Z6 N5 commerce surface integration (Venmo / Cash App / WishTender) for Quinn-receives flows · Z7 Receipts · Z8 Failed-payment recovery. |
| **AA** | [`AA-marketing-site.brief.md`](./AA-marketing-site.brief.md) | Public marketing site at `cocottetech.com`. Hero · How it works · Provider stories (post-Y) · Trust signals (excerpted from K + N + I) · Pricing (post-Z) · FAQ · Sign-up funnel · Cross-brand boundary table (cocottetech.com vs cocotte.maison vs cocotte.io vs cocotte.dev). Brand-marketing voice register distinct from internal hearth/working/plain. |
| **AB** | [`AB-watch-vision-pro.brief.md`](./AB-watch-vision-pro.brief.md) | Watch + visionOS variants (P5+). AB1 Watch complication + glanceable approvals + stakes-aware haptic + single-tap approve/reject + "open on phone" long-press · AB2 Vision Pro spatial drawer · gaze+pinch approval · spatial-near approval / spatial-far audit · AB3 Watch ⇄ phone handoff · AB4 Notifications-on-Watch per C. Lightweight extension of brief E. |
| **AC** | [`AC-second-member-onboarding.brief.md`](./AC-second-member-onboarding.brief.md) | Demimonde admin invites a Member or Viewer to an existing org (P5+ pre-design). Distinct from D (cold first-run) and Y (stranger signs up). Pre-filled persona-seed with org templates, org/personal facet distinction, first-time mixed-scope explainer per W, admin completion receipt, first-week scaffolding (admin shares persona/contacts/blocklist with member). |
| **AD** | [`AD-multilingual-opaque.brief.md`](./AD-multilingual-opaque.brief.md) | Multilingual support that's invisible to both providers and clients. Provider writes/reads in their language; prospect receives in theirs; no toggle, no "translated from…" footnote ever shown. AD1 provider language sticky · AD2 prospect language sticky · AD3 register-faithful re-authoring (not literal translation) · AD4 per-locale banned phrases · AD5 cross-script K3 PII · AD6 audit triad (original/canonical-EN/provider-view/delivered) · AD7 confidence fallback (never names language) · AD8 approval-card behavior. Resolves voice §V8 + AA §163 + X §234 localization placeholders for the in-product surface. |
| **AE** | [`AE-provider-social-network.brief.md`](./AE-provider-social-network.brief.md) | Provider social network (P5+). Opens the peer plane beyond N coop safety-intel. AE1 discovery (coop-mediated / referral / directory) · AE2 follow + colleague connection model · AE3 ai-mediated peer DM (AD opacity holds) · AE4 group chats ("salons") · AE5 opt-in directory · AE6 content collaboration (co_tour / cross_promo / shared_playbook) · AE7 scope-claimed endorsements (positive complement to N flags) · AE8 structured mentorship pairings · AE9 anonymized aggregated peer feed · AE10 abuse/moderation · AE11 three-state opt-in posture. Replaces Y's "coops are the only inter-provider plane" out-of-scope clause. |
| **AF** | [`AF-encryption-and-hardware-keys.brief.md`](./AF-encryption-and-hardware-keys.brief.md) | At-rest encryption (sensitive-only enumerated set) + E2EE for journals (zero-knowledge) and peer-shared data (peer DMs, salons, collab, mentor drafts, endorsements) + hardware-key support (YubiKey / Passkey / FIDO2). AF1 threat model · AF2 at-rest scope · AF3 E2EE scope · AF4 key hierarchy · AF5 YubiKey enrollment + recovery · AF6 ai-mediation via server-side wrapped DEK (each user's ai-copilot as trusted endpoint, not third-party) · AF7 cross-device handoff · AF8 lost-key flows · AF9 audit interplay · AF10 cryptographic erasure · AF11 specialist scoping. Resolves AE3 E2EE-vs-mediation tension via server-wrap default; pure peer-to-peer is AE-Q4 + AF-Q6 P5+. |

## Specialist contracts

One file per specialist with the four-line declarative card: **Does / Auto / Proposes / Never / Correction lens**. See [`specialist-roster.md`](./specialist-roster.md) (split out of brief L §L3).

## Flows + screens (concrete sequences)

| Kind | File | What it shows |
|------|------|--------------|
| flow | [`day-in-life.flow.md`](./day-in-life.flow.md) | A typical Quinn day that exercises every brief. Validates cohesion. |
| flow | [`audit-to-counter-action.flow.md`](./audit-to-counter-action.flow.md) | Spotting a bad row → dispatching a counter-action (retract / revert / follow-up). |
| flow | [`cross-device-handoff.flow.md`](./cross-device-handoff.flow.md) | iPhone ⇄ web companion handoff: pick-up-where-you-left-off, sidekick-on-laptop, notification chase. |
| screen | [`chat-home.screen.md`](./chat-home.screen.md) | Daily-driver chat-home — layout sketch, components, 12 states, gestures, edge cases. Pair with A. |
| screen | [`approval-card.screen.md`](./approval-card.screen.md) | The supervised-autonomy centerpiece — 12 states (incl. multi-surface H4 variant, conflict, specialist-degraded), 6 variant body layouts per `kind`. Pair with A, H. |
| screen | [`audit-row-detail.screen.md`](./audit-row-detail.screen.md) | Single `agent_actions` row inspection sheet — meta + why + result + feedback + counter-actions + lineage + raw. Pair with I. |
| screen | [`specialist-drawer.screen.md`](./specialist-drawer.screen.md) | Per-specialist drawer — identity + trust meter + policy posture + recent activity + health + advanced (prompt, model). Pair with B6, L. |
| screen | [`persona-seed-interview.screen.md`](./persona-seed-interview.screen.md) | First-run conversational onboarding — 8 questions, chips + free-text, hearth-dialed-warmer voice, outputs to personas/blocklist/handles/facts. Pair with D. |
| screen | [`notification-rich-preview.screen.md`](./notification-rich-preview.screen.md) | iOS lock-screen / Notification Center rich preview per stakes × kind. |
| flow | [`kill-switch.flow.md`](./kill-switch.flow.md) | Three trigger paths → confirm → dispatch → banner → resume → audit-gap-rendered-in-digest. Pair with K, M. |
| flow | [`degraded-mode.flow.md`](./degraded-mode.flow.md) | Five failure paths (adapter / specialist / backend / offline / catastrophic) with banner copy, retry budget, reconciliation. Pair with M, K. |
| screen | [`unified-inbox.screen.md`](./unified-inbox.screen.md) | One feed, many sources. Source-labeled rows, prospect-threading, per-source triage posture. Pair with P, C, I. |
| screen | [`vigil-close-digest.screen.md`](./vigil-close-digest.screen.md) | Morning surface — vigil header, Claude-drafted journal block (feedback affordances), receipts, call-outs. Pair with Q, I. |
| screen | [`surfaces-settings.screen.md`](./surfaces-settings.screen.md) | Operational view of every surface — grouped by N1/N2/N3/N4/N5, status glyphs, per-row detail sheet. Pair with O, F §F5, L. |
| screen | [`coop-intel-detail.screen.md`](./coop-intel-detail.screen.md) | Single coop-intel report inspection — provenance, verdict, notes, encrypted attachments, peer reports, dispute / add-own / block-in-K1 actions. Pair with N, K, I. |
| screen | [`calendar-drawer.screen.md`](./calendar-drawer.screen.md) | B1 calendar drawer over `content_plans`. Week/month, per-surface color, swipe-approve on tiles, drag-to-reschedule (web), 10 states. Pair with B, A, R, G1, T5. |
| screen | [`asset-library.screen.md`](./asset-library.screen.md) | B2 asset library drawer — 3-col iPhone / 5-col iPad grid, filters, asset detail + variants, K3a NSFW gates, K3c-2 KYC vault carve-out. Pair with B, K, R, content-onlyfans. |
| screen | [`prospect-detail.screen.md`](./prospect-detail.screen.md) | B3 prospect drawer — cross-surface timeline, funnel chip, coop callout if peer reports match (N), share-with-org per W. Pair with B, P, N, Q3, U, I, W. |
| screen | [`cross-platform-variants.screen.md`](./cross-platform-variants.screen.md) | E2 iPad two-column / E3 macOS Catalyst three-column + ⌘-shortcuts / E4 web 768/1024/1440 breakpoints. Cross-cutting Dynamic Type + dark/light + a11y. Pair with E, A, B, G, F. |
| screen | [`web-portals.screen.md`](./web-portals.screen.md) | G1 content-portal (calendar drag-to-reschedule · assets batch-tag · persona side-by-side) · G2 engagement-portal (CRM table + funnel charts) · G3 agent-actions log viewer (replay scrub). Single-API-plane to black. Pair with G, A, B, I, T, U. |
| screen | [`multi-surface-fanout.screen.md`](./multi-surface-fanout.screen.md) | H4/H5 multi-surface approval card — 4 density variants (flat / accordion / compact / anchor-and-rest), split-card per K3i, search-within-card, post-dispatch retry. Pair with H, A, K, O, R, I. |
| flow | [`vacation-mode.flow.md`](./vacation-mode.flow.md) | H1 vacation-mode end-to-end — 9 staged steps from triggers through resume digest. Sibling to but distinct from kill-switch (broader pause but soft, not hard edge). Pair with H, K, R, P, C, I. |
| screen | [`multi-leg-tour-planning.screen.md`](./multi-leg-tour-planning.screen.md) | R6 three-route comparison card — net-revenue tradeoff, re-run-with-constraints sheet, jurisdiction/pre-lock warnings, mid-tour re-route entry. Pair with R, strategist, K K4, T5. |
| flow | [`export-build.flow.md`](./export-build.flow.md) | V1 Quinn-side export — scope picker → format → size estimate → worker dispatch → ready notification → download + privacy reminder → audit. Plain register. Pair with V, C, S §S8, I. |
| flow | [`erasure-cooling-off.flow.md`](./erasure-cooling-off.flow.md) | V2 staged erasure — typed-confirm → 30-day cooling-off → daily reminder → revert anytime → commit day-30 → audit-redacted-not-deleted → memory flush → email receipt. Pair with V, I, N, C, K. |
| screen | [`sar-composer.screen.md`](./sar-composer.screen.md) | V3 subject access request composer — prospect lookup, scope, format, delivery, redaction preview enforcing K3c-1 + K3f-2 + coop carve-out, send/refusal paths. Pair with V, B3, K, N, S §S8. |
| flow | [`context-switch.flow.md`](./context-switch.flow.md) | W org context switch end-to-end (P5+ pre-design) — chip tap → switcher → re-render → context-provider re-scope → voice register shift → mixed-scope warnings → audit. Pair with W, S §S1, L, I, A, D. |
| flow | [`tryst-connect.flow.md`](./tryst-connect.flow.md) | **First per-surface conversational flow** — cookie path + full-credentials path as actual transcripts. Demonstrates the [00-system-conversational-ux.md](./00-system-conversational-ux.md) pattern: chat orchestrates, screen invoked only when richer input/output is needed. Pair with surface-tryst §2, tryst-connect.screen.md (companion fallback). |
| screen | [`policy-card.screen.md`](./policy-card.screen.md) | Per-surface automation policy — cadence / active-window / vacation / failure threshold / last-10 receipts. Anchors H1 Tryst/TS4R bumps. Pair with H, M, L. |
| screen | [`daily-digest.screen.md`](./daily-digest.screen.md) | First-of-day morning briefing — "tended to" / "things that wait" / strategist note / "held off on". Hearth-warmest copy. Pair with I, C, voice. |
| screen | [`coop-drawer.screen.md`](./coop-drawer.screen.md) | Provider-coop interior — multi-coop selector, recent activity, subjects-I-reported, watchlist, info + leave-coop. Pair with N, K, L (triage / prospect-resolver). |
| screen | [`publish-report.screen.md`](./publish-report.screen.md) | The deliberate publish flow for a coop safety report — friction-deliberate compose + high-stakes confirmation. Pair with N §N5, M §M3, K. |
| screen | [`add-blocklist-entry.screen.md`](./add-blocklist-entry.screen.md) | Add to PERSONAL blocklist (distinct from coop) — 5 kinds (prospect / phrase / topic / surface_combo / jurisdiction), scope picker, expiry, reason. Pair with K, I, L (triage). |
| screen | [`analytics-dashboard.screen.md`](./analytics-dashboard.screen.md) | Strategist's front-window — 5 panels (revenue / funnel / per-surface / cohort warmth / tour ledger) with insight chips. Pair with T, strategist contract. |
| screen | [`global-search.screen.md`](./global-search.screen.md) | One search across the corpus — typed grouped results, operator chips (`@`, `#`, `type:`, `surface:`, `since:`, `specialist:`), voice query, drawer-handoff. Pair with U. |
| screen | [`settings-root.screen.md`](./settings-root.screen.md) | Settings overlay landing — 8 categories grid + quick toggles (pause / vacation / kill switch) + recently-changed audit shadow + advanced gate. Pair with S, I. |
| screen | [`tour-leg-detail.screen.md`](./tour-leg-detail.screen.md) | Single tour leg through 5 phases (discovery / planning / hotel-selection / active / close) — anchor event, revenue floor/target, hotel shortlist, pre-announcements. Pair with R, H §H3. |
| screen | [`hotel-scout.screen.md`](./hotel-scout.screen.md) | Tor-pool hotel scout — shortlist + live scout queue + skipped + manual add. Filter sheet for budget / safety / walkable / independent. Pair with R §R1c, J (v2 `tour-scout` port). |
| screen | [`trust-panel.screen.md`](./trust-panel.screen.md) | Per-specialist trust breakdown — bar + 4–6 contributing signals + posture-graduation history + recent corrections + adjust-posture actions. Pair with I §5, L §L4. |
| screen | [`fleet-roster.screen.md`](./fleet-roster.screen.md) | Full fleet list (all specialists) — grouped by status / phase / voice-lean / trust-tier; row = icon + status dot + trust + 24h count. Pair with L §L2c. |
| screen | [`event-detail.screen.md`](./event-detail.screen.md) | Single event from `event-scrapers` — provenance, audience overlap, anchored legs, anchor-new-leg / watchlist / hide actions. Pair with R §R2c, J (v2 `event-scrapers` port). |
| screen | [`data-export-erasure.screen.md`](./data-export-erasure.screen.md) | GDPR data export (JSON/CSV, passphrase-encrypted) + erasure flows (category / whole account with 7-day grace). Pair with V, S §S8, K destructive-flow pattern. |
| screen | [`watch-glance.screen.md`](./watch-glance.screen.md) | Apple Watch / Vision Pro compression of chat-home — state + one receipt + pending-count handoff. Complications. Pair with AB, E, F §F4. |
| screen | [`accessibility-settings.screen.md`](./accessibility-settings.screen.md) | Override iOS accessibility for Cocotte — Dynamic Type, reduced motion, color-blind palettes, register override (force plain), single-tap approvals. Pair with X, F, voice. |
| screen | [`marketing-landing.screen.md`](./marketing-landing.screen.md) | Public `cocotte.maison` umbrella site — hero, visibility/drafts/safety triptych, request-invite CTA. Pre-auth. Pair with AA, V (privacy link). |
| screen | [`billing-overview.screen.md`](./billing-overview.screen.md) | Subscription + usage meter (5 dims) + payment + history. Card-failed / approaching-cap / cancel-plan flows. P5+. Pair with Z, W (org billing inheritance). |
| screen | [`org-overlay-settings.screen.md`](./org-overlay-settings.screen.md) | Org admin: identity (Demimonde LLC + Cocotte brand), members, brands operated, data scope, billing inheritance, specialist scope, dissolution. P5+. Pair with W, Z, V. |
| screen | [`marketplace-detail.screen.md`](./marketplace-detail.screen.md) | Cross-org marketplace for shared copy templates / persona presets / blocklists / specialist configs / tour playbooks. P5+. Pair with Y, N (coop-only mode). |
| screen | [`second-member-invite.screen.md`](./second-member-invite.screen.md) | Invite a member to the org — role (owner/admin/talent/read-only), data-scope toggles, 14-day "propose only" safety default, brand assignment. P5+. Pair with AC, W, D. |
| screen | [`engagement-drawer.screen.md`](./engagement-drawer.screen.md) | Prospect-funnel drawer — tier filter (hot/warm/cold), source filter, per-row draft status. Sibling to unified-inbox (typed/funnel vs raw-thread). Pair with B, P, K, N, triage. |
| screen | [`audit-drawer.screen.md`](./audit-drawer.screen.md) | List view of `agent_actions` — specialist / action / stakes / auto-vs-approved / time filters; row→detail. Append-only invariant. Pair with B, I, V. |
| screen | [`persona-drawer.screen.md`](./persona-drawer.screen.md) | Persona facets — per-persona card with voice lean + consumed-by chips + edit/see-prompt. Respects brand-family naming (no `demimonde*` personas). Pair with B, J, voice. |
| screen | [`voice-input-settings.screen.md`](./voice-input-settings.screen.md) | S2 settings — STT engine, TTS character + speed, mic/PTT, voice-trigger opt-in, voice-register override. Pair with S §S2, voice, X. |
| screen | [`notifications-settings.screen.md`](./notifications-settings.screen.md) | S3 settings — channel × stakes matrix, quiet hours, per-specialist preferences, daily-digest cadence. Pair with S §S3, C, M §M4. |
| screen | [`tours-settings.screen.md`](./tours-settings.screen.md) | S7 settings — lead-time defaults, revenue floor/target formulas, hotel filter defaults, during-tour automation, post-tour journaling, multi-leg routing weights. Pair with S §S7, R, H §H3. |

## Cross-cutting topic-named briefs

Patterns that span many thematic letters and don't fit the A–AD dimension model. Topic-named, no letter prefix.

| Brief | What it covers |
|---|---|
| [`cross-surface-fanout.brief.md`](./cross-surface-fanout.brief.md) | The "apply to all escort platforms" canonical conversational form — audience selectors, per-surface adaptation engine via `personas.facets`, cross-surface approval card, live progress + retry-failed, stakes inheritance, partial-failure reconciliation. Extends H §H4. |

## Per-surface briefs

Deep briefs for specific surfaces — each maps the generic patterns (H1/H2/H3, K, P, T, I) onto the surface's actual UI, data model, and operational reality. **The first per-surface brief is written as a template** with *Generalization callouts* per section, so subsequent surface briefs inherit the structure.

| Surface | Brief | Status | Companion screens |
|---|---|---|---|
| Tryst (TLC directory) | [`surface-tryst.brief.md`](./surface-tryst.brief.md) | **first; written as template (operate-on shape)** | `tryst-connect`, `tryst-inbox`, `tryst-profile-preview`, `tryst-profile-editor`, `tryst-photo-manager`, `tryst-home-cities`, `tryst-verification` (no `tryst-reviews` — Tryst has no native reviews; see `reviews-list.screen.md` for N7 aggregators) |
| Client screening (category) | [`surface-screening.brief.md`](./surface-screening.brief.md) | **second; consume-from / lookup shape** | `screening-lookup` (planned), `screening-history` (planned) |
| TS4Rent | (planned) | inherits Tryst template | TBD |
| Slixa | (planned) | inherits Tryst template | TBD |
| Eros | (planned) | inherits Tryst template | TBD |
| OnlyFans | (planned) | inherits Tryst template | TBD |
| Per-other-surface | (per O roster) | inherits Tryst or screening template | TBD |

### Tryst screens (registered with the screen table below)

| Screen | Pair |
|---|---|
| [`tryst-connect.screen.md`](./tryst-connect.screen.md) | first-time auth grant (cookie paste flow + verify call + account preview). Per surface-tryst §2. |
| [`tryst-inbox.screen.md`](./tryst-inbox.screen.md) | Tryst-native thread list + thread detail. Surface-specific filters: verified-only / sender's listing rank / city. Sibling to unified-inbox. Per §5. |
| [`tryst-profile-preview.screen.md`](./tryst-profile-preview.screen.md) | rendered "as a client sees it" frame; Live/Proposed/Side-by-side picker; approve-and-push. Per §3. |
| [`tryst-profile-editor.screen.md`](./tryst-profile-editor.screen.md) | structured editor — about-me + rates table + services chips + hours + tour cities + photos link. Extends H §H2 for tabular fields. Per §3, §11. |
| [`tryst-photo-manager.screen.md`](./tryst-photo-manager.screen.md) | hero + gallery slot manager; per-photo flags (NSFW / face-blurred / expires); drag-reorder. Per §3 photos. |
| [`tryst-home-cities.screen.md`](./tryst-home-cities.screen.md) | Home cities management — N cities per tier, cadence-gated changes (Y days), tour-as-exception. Per §7 (corrected 2026-05-18 from earlier fee-gated lock model). |
| [`tryst-verification.screen.md`](./tryst-verification.screen.md) | Sumsub KYC re-up + deadname-risk privacy disclosure. Sensitive surface. Per §6. |
| [`reviews-list.screen.md`](./reviews-list.screen.md) | N7 aggregator reviews list (TER, PunterNet, USASexGuide, TNABoard) — renamed from `tryst-reviews.screen.md` because Tryst has no native reviews. Per O §N7. |

## Annexes (non-UX reference)

| File | Genre |
|------|-------|
| [`_engineering-v2-port-map.md`](./_engineering-v2-port-map.md) | Per-feature port/redesign/replace/skip verdict for every v2 AI feature. Engineering tracker; not a UX brief. |
| [`_engineering-credentials-vault.md`](./_engineering-credentials-vault.md) | v2 → v4 port plan for the AES-256-GCM credentials vault (`my.transquinnftw.com/api/credentials`). Foundation for every surface adapter. 7-step migration plan + schema + custodian SSE flow. |
| [`OPEN-DECISIONS.md`](./OPEN-DECISIONS.md) | Index of every open question across briefs, tagged **[blocking | nice-to-have | exploratory]** with backlinks. |

## File-shape conventions

All docs live flat at the top of `docs/`. Prefixes encode role. **Naming is dual-track** (decided 2026-05-18): letter-prefix for thematic UX dimensions, topic-name for cross-cutting patterns + per-surface briefs.

### Letter-prefixed (thematic UX dimensions)
- `<letter>-<topic>.brief.md` — one of the A–V core dimensions or W/X/Y/Z/AA–AF cross-cutting + speculative. Each letter is its own thematic slice (A=chat-surface, B=drawers, …).
- Adding a new thematic dimension? Allocate the next letter, document in the briefs table.

### Topic-named (cross-cutting / non-thematic briefs)
- `<topic>.brief.md` — a pattern that spans many thematic letters and doesn't fit the dimension model. First example: [`cross-surface-fanout.brief.md`](./cross-surface-fanout.brief.md) (the "apply to all" pattern; cuts across A, H, I, L, M, every surface).
- Use sparingly. If a brief feels thematic, letter-prefix it. If it's a pattern shared by many briefs, topic-name.

### Foundations + annexes (always at corpus root)
- `00-system-<topic>.md` — foundation (visual-system, voice, conversational-ux). Loaded first; everything else inherits.
- `_engineering-<topic>.md` — non-UX annex (engineering reference; not part of the design read-order).
- `_deprecated-<original-name>.md` — superseded; kept for traceability. New ones should be **deleted** going forward (git keeps history); existing ones stay until a corpus-cleanup pass.

### Specialists
- `specialist-<name>.contract.md` — per-specialist contract card.
- `specialist-roster.md` — index of contracts.

### Per-surface
- `surface-<id>.brief.md` — per-surface deep brief, inherits the template-shape from [`surface-tryst.brief.md`](./surface-tryst.brief.md). Always topic-named (not letter-prefixed).
- `<surface>-<topic>.screen.md` — surface-scoped screen (e.g. `tryst-inbox.screen.md`).
- `<surface>-<topic>.flow.md` — surface-scoped conversational flow (e.g. `tryst-connect.flow.md`).

### Flows + screens (corpus-wide, not surface-bound)
- `<topic>.flow.md` — end-to-end conversational flow narration (per [`00-system-conversational-ux.md`](./00-system-conversational-ux.md), flows are first-class).
- `<topic>.screen.md` — single-screen breakdown (layout, components, states, edge cases, **capabilities**, invoking flows).

### Meta
- `README.md` — this file.
- `OPEN-DECISIONS.md` — open-questions tracker.

## Screen-header convention (introduced 2026-05-18)

Per [`00-system-conversational-ux.md`](./00-system-conversational-ux.md), screens are tools Cocotte invokes mid-conversation. Every `.screen.md` should declare its role at the top via a short header note:

```markdown
# my-screen.screen

**Capabilities**: rich-output render · structured editor · approval surface.
**Invoked by**: [`my-flow.flow.md`](./my-flow.flow.md), `ai-copilot` direct ask ("show me X"), [`other-screen.screen.md`](./other-screen.screen.md) (chevron tap).
**Role**: tool invoked during conversation; not a primary navigation destination.

Brief intro paragraph here.
```

Capabilities draw from the 6-capability vocabulary in [`00-system-conversational-ux.md`](./00-system-conversational-ux.md): rich-output / rich-input / structured-editor / approval / confirmation / inspector.

Existing screens written before 2026-05-18 may lack this header — apply retroactively during the next focused audit pass; don't block adjacent work on it.

## Per-surface brief §14 requirement

Per [`surface-tryst.brief.md §14`](./surface-tryst.brief.md), every per-surface brief MUST include §14 Conversational management with 5 sub-sections:
- §14a verbs Quinn uses (table)
- §14b pure-chat actions
- §14c screen-invoking actions (with reasons)
- §14d cross-surface participation flags
- §14e voice-mode adaptations

This is the per-surface realization of the corpus-wide conversational primacy principle.

## Brief template (lead-then-annex)

**Note (2026-05-18)**: Per [`00-system-conversational-ux.md`](./00-system-conversational-ux.md), design starts with the **conversational flow**, not the screen. When writing a new brief:
1. Identify the conversation Quinn has with Cocotte to accomplish this surface's job.
2. Write the `.flow.md` first (transcripts of representative interactions).
3. Identify screen-shaped moments (rich input / rich output / structured edit).
4. Write or extend the `.screen.md` files for those moments.
5. Brief documents the why + design dimensions; flows + screens document the concrete shape.

```markdown
# <title>

## Goal
One sentence — what the user is trying to accomplish on this surface.

## Conversational shape
Brief description of what the conversation looks like. Pair with a `.flow.md`
for the full transcript. Surface where chat invokes screens.

## States to design
Enumerate every state (empty, loading, success, error, edge cases). Designers
read this first.

## Headline UX
The single most concrete UX statement of this brief — what the screen looks
like / what the user does. 60-second pitch.

## Open questions
Each tagged [blocking | nice-to-have | exploratory]. Blocking Qs gate design.
| screen | [`peer-directory.screen.md`](./peer-directory.screen.md) | AE5 opt-in directory browse. Filters (surface/language/region/endorsement). 11 states incl. shadowban + posture-rate-cap. Pair with AE, B. |
| screen | [`peer-profile.screen.md`](./peer-profile.screen.md) | Viewing another peer. Connection-state-driven footer (Follow/Request/Muted/Blocked). 14 states; block-by-peer indistinguishable from V erasure. Pair with AE, B, V. |
| screen | [`peer-dm-thread.screen.md`](./peer-dm-thread.screen.md) | AE3 ai-mediated peer DM. AD opacity holds; long-press = verbatim-expand (the only AD-opacity break, opt-in). 16 states incl. K3 leak, AD low-confidence, multi-message debounce. Pair with AE, A, AD, K. |
| screen | [`salon.screen.md`](./salon.screen.md) | AE4 group chat / salon. Proposal → awaiting-quorum → active → archived. 12 states incl. K3 broadcast suppression. Pair with AE, A, K. |
| screen | [`endorse-peer.screen.md`](./endorse-peer.screen.md) | AE7 scope-claimed endorsement composer. Voice §V6 + K3 gate before send. 12 states incl. abuse-heuristic spike. Pair with AE, K. |
| screen | [`mentorship-pairing.screen.md`](./mentorship-pairing.screen.md) | AE8 structured pairing — 4 vigils + 30d check-in + mutual review. 13 states incl. mid-pairing offboard. Pair with AE, I, V. |
| screen | [`peer-feed.screen.md`](./peer-feed.screen.md) | AE9 anonymized peer feed. k=5 anonymity floor; auto-suppress sensitive segments. 9 states incl. opted-out + sensitive-segment. Pair with AE, T, prospect-resolver. |
| flow | [`peer-block-report.flow.md`](./peer-block-report.flow.md) | AE10 abuse + moderation. 18-step end-to-end (block / mute / report → quorum review → sanction → 14d appeal). Plain register throughout. Audit append-only with supplements-not-deletes for appeals. Pair with AE, K, I, V. |
| screen | [`yubikey-enrollment.screen.md`](./yubikey-enrollment.screen.md) | AF5 hardware-key enrollment. One-step-at-a-time (4 steps: primary tap → backup nudge → tap-test → recovery-code reveal). 14 states incl. lost-primary recovery + recovery-code wrong-entry. Pair with AF, S Security, D nudge. |
| screen | [`signin.screen.md`](./signin.screen.md) | Return-user sign-in. 3 credential paths (passphrase / hardware-key / recovery-code) + new-device pairing. 17 states incl. mid-session re-auth, HSM unreachable, Cellular Watch fallback. Pair with AF, M §M2a, AB §AB-Q5, X. |

---

## Annex

### Constraints
Hard requirements (auth, offline, accessibility, brand) and host platform.

### Inputs
What data is available (cite platform.api endpoints + ai-copilot chat
response shape).

### Out of scope
What we are explicitly NOT designing now.

### Plumbing
Infrastructure detail — TypeORM, NestJS routes, pg LISTEN/NOTIFY,
mac-sync:3100 wiring, etc. Move here when it doesn't help the designer.
```

## Related

- Approved priorities + UX defaults: `~/.claude/plans/this-is-a-new-wiggly-wren.md` (P0.5 section).
- iOS stack: Swift 5.9+ / SwiftUI / iOS 17+, ported from `~/Code/@applications/lilith-messenger-ios`.
- Visual base: `lilith-messenger-ios/LilithMessenger/Design/{Theme,Typography}.swift`.
- Consumer-facing app name: **CocotteAI**. Platform-service layer: `cocotte.io` + `cocotte.dev` + `platform.api` + `platform.db`. Public umbrella brand: **Cocotte** (`cocotte.maison`). Back-office Org: **Demimonde** (invisible to customers). Sansonnet is a separately-held independent brand.