cocottetech/@platform/codebase/@features/ai-copilot/docs

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

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	Tokens, typography, motion, stakes semantics, 24-surface iconography (F5), component library. Foundation — everything inherits.
sys	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	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	Primary chat surface in CocotteAI (iOS). 10 states, gestures, voice, multimodal input.
B	B-drawers.brief.md	Full-screen contextual views opened from chat — calendar, asset library, prospect, agent-actions, persona, specialist.
C	C-notifications.brief.md	Channel × stakes × specialist matrix; iOS push / iMessage / email digest; stakes-aware deeplinks.
D	D-onboarding.brief.md	First-run: SSO device-link → persona-seed interview → empty state.
E	E-cross-platform.brief.md	iPhone canonical; iPad / macOS / web variants; dark / light.
G	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	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	Trust loop — daily digest, audit drawer, row detail with feedback, counter-actions, trust panel + policy graduations.
K	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	Fleet roster + user-facing specialist UX + lifecycle. Per-specialist contracts now in specialist-roster.md.
M	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	Inter-org provider-coop safety-intel network — opt-in membership, attributed/anonymous reports, peer discovery, dispute / moderation.
O	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	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	Ambient layer — vigil detection, auto-journaling, auto-conversation visibility.
R	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	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	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	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	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	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	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	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	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	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	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	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	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	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	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 (split out of brief L §L3).

Flows + screens (concrete sequences)

Kind	File	What it shows
flow	day-in-life.flow.md	A typical Quinn day that exercises every brief. Validates cohesion.
flow	audit-to-counter-action.flow.md	Spotting a bad row → dispatching a counter-action (retract / revert / follow-up).
flow	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	Daily-driver chat-home — layout sketch, components, 12 states, gestures, edge cases. Pair with A.
screen	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	Single agent_actions row inspection sheet — meta + why + result + feedback + counter-actions + lineage + raw. Pair with I.
screen	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	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	iOS lock-screen / Notification Center rich preview per stakes × kind.
flow	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	Five failure paths (adapter / specialist / backend / offline / catastrophic) with banner copy, retry budget, reconciliation. Pair with M, K.
screen	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	Morning surface — vigil header, Claude-drafted journal block (feedback affordances), receipts, call-outs. Pair with Q, I.
screen	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	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	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	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	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	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	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	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	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	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	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	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	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	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	First per-surface conversational flow — cookie path + full-credentials path as actual transcripts. Demonstrates the 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	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	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	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	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 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	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	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 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	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	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	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	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	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	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	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	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	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	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 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	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	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	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	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 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	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	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	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	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	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	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	first-time auth grant (cookie paste flow + verify call + account preview). Per surface-tryst §2.
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	rendered "as a client sees it" frame; Live/Proposed/Side-by-side picker; approve-and-push. Per §3.
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	hero + gallery slot manager; per-photo flags (NSFW / face-blurred / expires); drag-reorder. Per §3 photos.
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	Sumsub KYC re-up + deadname-risk privacy disclosure. Sensitive surface. Per §6.
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	Per-feature port/redesign/replace/skip verdict for every v2 AI feature. Engineering tracker; not a UX brief.
_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	Index of every open question across briefs, tagged **[blocking

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 (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. 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, 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, screens are tools Cocotte invokes mid-conversation. Every .screen.md should declare its role at the top via a short header note:

# 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: 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, 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, 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.

# <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.