atlilith/@platform/docs/ios-ux.md

CocotteAI — iOS UX + UI strawman

Product name: CocotteAI (user-facing). Backend service: ai-copilot (provider-generic, unchanged). Status: draft for Quinn's review. Engineering scaffold (P0.5) waits on sign-off.

This is the primary user interface for V3. The web app is secondary; iOS is where the day-to-day driving happens.

Naming map

Layer	Name
iOS product / App Store display	CocotteAI
iOS bundle id	com.atlilith.cocotte
iOS Swift target / scheme	CocotteAI
Authoring path	@platform/codebase/@features/ai-copilot/ios-fe/ (unchanged)
Backend NestJS service	ai-copilot (unchanged)
Root SwiftUI App type	CocotteAIApp

Rule: "CocotteAI" appears in user-visible strings (app name, splash, Settings header, push sender). "ai-copilot" stays in code paths, package names, and infra.

1 — Architectural priors (decided)

• One app, one bundle. Not a fleet of per-specialist apps.
• Source of source code: ported from ~/Code/@applications/@quinn-ios/ (Swift/SwiftUI, iOS 17+). Existing modules: Booking, Conversation, Inbox, Settings.
• Authoring location: @platform/codebase/@features/ai-copilot/ios-fe/. Built remotely on plum via @lilith/mobile-build-tools. Not a pnpm workspace.
• Backend contracts: talks to platform.api (CRUD) + ai-copilot (context envelope + chat) over HTTPS — both on black. No direct DB. No dev backend.
• Auth: quinn.sso v2 — same Bearer token as web FEs.
• Tenancy: Person-scoped. Org switcher in nav only if the user has multiple org memberships.

2 — Surfaces

Four top-level tabs, in priority order for Quinn's earnings lens:

Tab	What it is	What lives here
Today	Default landing. The copilot's morning brief.	Suggested posts to approve, inbound DMs needing reply, agent_actions awaiting confirmation. One scrollable feed, AI-curated.
Content	Cross-surface posting queue.	content_plans + content_posts. Filter by surface (OF / X / IG / TikTok). Approve-or-edit flow. Asset preview.
Engagement	Cross-surface inbox.	DMs / comments / mentions from every surface, unified. Reply drafts pre-written by the relevant specialist agent; swipe to send or tap to refine.
Cocotte	Free-form chat with ai-copilot.	The fallback / catch-all. Streamed responses. Memory + persona settings nested in here.

Settings (account, SSO, notifications, persona config, org switching) lives behind a profile icon, not as its own tab.

3 — Top-level UX flow (navigation graph)

┌──────────────────────────────────────────────────────────────────────┐
│                       Launch → SSO check                             │
│             (quinn.sso v2 Bearer, x-user-id, x-org-id)               │
└────────────────────────────────┬─────────────────────────────────────┘
                                 │
                  ┌──────────────┴───────────────┐
                  │                              │
            no token / 401                 token valid
                  │                              │
                  ▼                              ▼
        ┌──────────────────┐         ┌─────────────────────┐
        │  SSO Login       │ ──────▶ │  Tab Bar shell      │
        │  (web sheet)     │         │  (CocotteAI root)   │
        └──────────────────┘         └──────────┬──────────┘
                                                │
   ┌────────────────┬────────────────┬──────────┴────────┬──────────────┐
   ▼                ▼                ▼                   ▼              ▼
┌──────┐       ┌─────────┐      ┌────────────┐     ┌─────────┐    ┌──────────┐
│Today │       │ Content │      │ Engagement │     │ Cocotte │    │ Profile  │
│  ☀   │       │   📝    │      │    💬      │     │   ✦    │    │   ⓘ     │
└──┬───┘       └────┬────┘      └──────┬─────┘     └────┬────┘    └────┬─────┘
   │                │                  │                │              │
   ▼                ▼                  ▼                ▼              ▼
 brief         post queue          inbox            chat thread     Settings
   │                │                  │                │              │
   │   ┌────────────┴──┐         ┌─────┴─────┐          │      ┌───────┴────┐
   ▼   ▼               ▼         ▼           ▼          ▼      ▼            ▼
 Post  Post-detail   Asset    Thread     Compose     Persona  Account     Org
 card  + approve     viewer   detail     reply       config   / SSO       switch
   │      │
   ▼      ▼
 1-tap  2-tap
 ship   review
 (low   ▼
 stk)  send

Modal layers (over any tab):
  ┌─ Approval sheet (agent_actions.stakes ≥ medium)
  ├─ Voice-note recorder (Engagement compose)
  └─ Cocotte streaming overlay (long-running specialist task)

Stakes → tap path:

stakes=low      → 1-tap from Today      (auto-execute confirmation toast)
stakes=medium   → 2-tap (card → review)
stakes=high     → 3-tap (card → review → caption confirm)

4 — UI wireframes per surface

All frames are 390×844 (iPhone 15 portrait), monospace approximation. Real layout uses @ui/tokens spacing scale.

4.1 — Today (default landing)

┌──────────────────────────────────────────┐
│  ▣  Wed · May 17           👤 Quinn  ⌄  │
├──────────────────────────────────────────┤
│                                          │
│  Good morning. 4 things need you.        │
│                                          │
│  ┌────────────────────────────────────┐  │
│  │  ✦ Sasha (OnlyFans)        9:14 AM │  │
│  │  Drafted PPV: "Sunday set"          │  │
│  │  $25 · 3 assets · stakes:medium    │  │
│  │  ╭──────────╮  ╭──────────────╮   │  │
│  │  │ Review → │  │ Approve & post│  │  │
│  │  ╰──────────╯  ╰──────────────╯   │  │
│  └────────────────────────────────────┘  │
│                                          │
│  ┌────────────────────────────────────┐  │
│  │  💬 Engagement                     │  │
│  │  Mia (X) drafted 7 replies         │  │
│  │  ───────────────────────────────   │  │
│  │  ▸ "loved the new set 🔥" …        │  │
│  │  ▸ "when's next stream?" …         │  │
│  │  ▸ +5 more                         │  │
│  │  ╭──────────────────────╮          │  │
│  │  │ Open inbox  →        │          │  │
│  │  ╰──────────────────────╯          │  │
│  └────────────────────────────────────┘  │
│                                          │
│  ┌────────────────────────────────────┐  │
│  │  ⚡ Auto-shipped (last 24h)        │  │
│  │  3 low-stakes posts · 12 replies   │  │
│  │  Tap to audit                      │  │
│  └────────────────────────────────────┘  │
│                                          │
├──────────────────────────────────────────┤
│  ☀ Today  📝 Content  💬 Engage  ✦ Cocotte│
└──────────────────────────────────────────┘

4.2 — Content (cross-surface posting queue)

┌──────────────────────────────────────────┐
│  ← Content                  + New post  │
│  ╭────╮ ╭────╮ ╭────╮ ╭────╮ ╭────╮     │
│  │All │ │OF  │ │ X  │ │ IG │ │ TT │     │
│  ╰────╯ ╰────╯ ╰────╯ ╰────╯ ╰────╯     │
├──────────────────────────────────────────┤
│  TODAY                                   │
│  ┌────────────────────────────────────┐  │
│  │ [thumb]  PPV: "Sunday set"         │  │
│  │          OF · 9:00 PM · draft      │  │
│  │          ✦ Sasha · stakes:medium   │  │
│  └────────────────────────────────────┘  │
│  ┌────────────────────────────────────┐  │
│  │ [thumb]  Tweet: "new drop friday"  │  │
│  │          X · 2:00 PM · approved    │  │
│  │          ✦ Mia · stakes:low        │  │
│  └────────────────────────────────────┘  │
│                                          │
│  TOMORROW                                │
│  ┌────────────────────────────────────┐  │
│  │ [thumb]  Reel: BTS clip            │  │
│  │          IG · 6:00 PM · scheduled  │  │
│  └────────────────────────────────────┘  │
│                                          │
│  THIS WEEK (3)                           │
│  ▸ ───────────────────────────────────   │
│                                          │
├──────────────────────────────────────────┤
│  ☀ Today  📝 Content  💬 Engage  ✦ Cocotte│
└──────────────────────────────────────────┘

Post detail (push):

┌──────────────────────────────────────────┐
│  ←  Post detail              ⋯           │
├──────────────────────────────────────────┤
│  ┌────────────────────────────────────┐  │
│  │                                    │  │
│  │           [ asset preview ]        │  │
│  │                                    │  │
│  └────────────────────────────────────┘  │
│  ◯◯◯ 3 assets                            │
│                                          │
│  Caption                          [edit] │
│  ╭────────────────────────────────────╮  │
│  │ "sunday set's up baby 💋 ppv in    │  │
│  │  dms · 25"                         │  │
│  ╰────────────────────────────────────╯  │
│                                          │
│  Surface     OnlyFans                    │
│  Schedule    Today · 9:00 PM             │
│  Specialist  ✦ Sasha (content-onlyfans)  │
│  Stakes      ● medium                    │
│  Confidence  ▓▓▓▓▓▓▓░░  0.78             │
│                                          │
│  ╭──────────╮  ╭────────────────────╮   │
│  │ Refine ↻ │  │  Approve & post →   │   │
│  ╰──────────╯  ╰────────────────────╯   │
└──────────────────────────────────────────┘

4.3 — Engagement (unified inbox)

┌──────────────────────────────────────────┐
│  ← Engagement              🔍  Filter   │
│  ╭────╮ ╭────╮ ╭────╮ ╭──────╮          │
│  │All │ │DMs │ │Cmts│ │Mentns│          │
│  ╰────╯ ╰────╯ ╰────╯ ╰──────╯          │
├──────────────────────────────────────────┤
│  ━━━ Draft ready · swipe ━━━━━━━━━━━━━  │
│  ┌────────────────────────────────────┐  │
│  │ ◐ jake_…  OF·DM       2m           │  │
│  │ "miss u babe when's next"          │  │
│  │ ─── ✦ Sasha drafted ───            │  │
│  │ "missed you too 🥺 sunday          │  │
│  │  set drops 9pm — saved             │  │
│  │  you a seat in the front 💋"      │  │
│  │ ◀ dismiss        ✓ send (swipe)▶  │  │
│  └────────────────────────────────────┘  │
│  ┌────────────────────────────────────┐  │
│  │ ◑ @anon_   X·reply    8m           │  │
│  │ "when's next stream?"              │  │
│  │ ✦ Mia: "thurs 8pm est 🤍 set …    │  │
│  │ ◀ dismiss        ✓ send (swipe)▶  │  │
│  └────────────────────────────────────┘  │
│  ┌────────────────────────────────────┐  │
│  │ ◯ liz_xo  IG·comment  14m          │  │
│  │ "🔥🔥🔥"                            │  │
│  │ ✦ Auto-liked · no reply needed     │  │
│  └────────────────────────────────────┘  │
│                                          │
│  ━━━ Awaiting your voice ━━━━━━━━━━━━━  │
│  ┌────────────────────────────────────┐  │
│  │ ◑ vip_…  OF·DM        1h  ⚠ high  │  │
│  │ "would u meet irl?"                │  │
│  │ ✦ Sasha flagged — your call        │  │
│  └────────────────────────────────────┘  │
├──────────────────────────────────────────┤
│  ☀ Today  📝 Content  💬 Engage  ✦ Cocotte│
└──────────────────────────────────────────┘

4.4 — Cocotte (free-form chat)

┌──────────────────────────────────────────┐
│  ← Cocotte                       ⚙       │
├──────────────────────────────────────────┤
│                                          │
│           Wed · May 17                   │
│                                          │
│                ╭───────────────────────╮ │
│                │ what's my OF revenue  │ │
│                │ this week vs last?    │ │
│                ╰───────────────────────╯ │
│                                          │
│  ╭───────────────────────────╮           │
│  │ ✦ Cocotte                  │           │
│  │ This week: $4,820 (+18%)  │           │
│  │ Last:      $4,084          │           │
│  │ Driver: Sunday PPV ($1.2k) │           │
│  │ ╭─────────────────────╮    │           │
│  │ │ ▂▄▃█▆▅█  daily      │    │           │
│  │ ╰─────────────────────╯    │           │
│  ╰───────────────────────────╯           │
│                                          │
│  ╭───────────────────────────╮           │
│  │ ✦ Cocotte · streaming ●   │           │
│  │ Want me to draft 3 PPV    │           │
│  │ ideas for next sunday?▍   │           │
│  ╰───────────────────────────╯           │
│                                          │
├──────────────────────────────────────────┤
│  ╭────────────────────────────────────╮  │
│  │ ask anything…              🎙  ↑   │  │
│  ╰────────────────────────────────────╯  │
├──────────────────────────────────────────┤
│  ☀ Today  📝 Content  💬 Engage  ✦ Cocotte│
└──────────────────────────────────────────┘

4.5 — Approval sheet (modal, medium/high stakes)

        ┌────────────────────────────────┐
        │ ━━━━                           │
        │  Approve action                │
        ├────────────────────────────────┤
        │  Action     publish_post       │
        │  Target     ContentPost #a3f…  │
        │  Specialist ✦ Sasha            │
        │  Stakes     ● medium           │
        │  Confidence 0.78               │
        │                                │
        │  Preview                       │
        │  ┌──────────────────────────┐  │
        │  │ [thumb]                   │ │
        │  │ "sunday set's up baby 💋" │ │
        │  └──────────────────────────┘  │
        │                                │
        │  Why now?                      │
        │  Best historical post-time     │
        │  for OF (Sun 9pm, +34% tips)   │
        │                                │
        │  ╭──────────╮  ╭────────────╮ │
        │  │  Cancel  │  │  Approve   │ │
        │  ╰──────────╯  ╰────────────╯ │
        └────────────────────────────────┘

4.6 — Profile drawer (Settings entry, not a tab)

┌──────────────────────────────────────────┐
│  ← Profile                               │
├──────────────────────────────────────────┤
│       ╭─────╮                            │
│       │  Q  │  Quinn                     │
│       ╰─────╯  quinn@lilith.live         │
│                                          │
│  Org    ▾ Quinn (personal)               │
│                                          │
│  ───────────────────────────────────     │
│  ✦ Persona & voice           →           │
│  🔔 Notifications            →           │
│  🔐 SSO & sessions           →           │
│  ⚙ Specialists                →          │
│  🎚 Stakes routing            →          │
│  ───────────────────────────────────     │
│  ⓘ About CocotteAI            v0.1.0     │
│  ⎋ Sign out                              │
└──────────────────────────────────────────┘

5 — Design tokens (delegate to @ui/tokens)

Do not redefine colors/typography in the iOS app. Pull from @packages/@swift/@ui/tokens:

Surface       neutral.bg.elevated
Card          neutral.bg.surface + radius.lg + shadow.sm
Accent        brand.primary  (rose/copper for CocotteAI persona)
Stakes ●low   feedback.success
Stakes ●med   feedback.warning
Stakes ●high  feedback.danger
Specialist ✦  brand.accent.foil

If @ui/tokens is missing a CocotteAI palette, add it there — not in ios-fe/.

6 — Interaction patterns (open questions)

Diagrams above use these defaults; override before P0.5 lands.

Q1 — Approve flow for AI-drafted content

When the copilot proposes a post, what's the minimum tap path to ship it?

• (a) One-tap approve from Today feed → post fires immediately.
• (b) Two-tap — tap card → review screen → "send."
• (c) Three-tap — review → require caption confirmation → send.
• (default) Stakes-routed — agent_actions.stakes chooses (a)/(b)/(c) automatically.

Q2 — Engagement inbox: read-then-reply or reply-first?

• (a) Read-first — open the message, see the draft, send/edit/skip.
• (b) Reply-first ← assumed in diagrams — swipe right to send draft, swipe left to dismiss. Tap to refine.

Q3 — Specialist visibility

• (a) Hidden plumbing — UI says "Cocotte suggested…" regardless of which agent produced it.
• (b) Named characters ← assumed in diagrams — each agent gets a name (Sasha/Mia/…) so you can see who drafted what.

Q4 — Notifications

• (a) Push for every action that needs approval, with inline approve/dismiss ← assumed for medium+ stakes
• (b) Hourly digest push
• (c) Quiet by default

Default: (a) for medium+, silent auto-ship for low.

Q5 — Watch / widget surface

• (a) Yes — pending-approval count on watch + home-screen widget.
• (b) Later ← assumed in diagrams — defer Watch to P1.

7 — Existing @packages/@swift/* consumed (DO NOT reinvent)

Package	Use in CocotteAI
@foundations/logging	structured logging
@foundations/coordinator	navigation coordinator pattern
@foundations/realtime	streaming / WS / SSE primitives (for Cocotte chat)
@foundations/settings	UserDefaults wrapper, secure storage
@foundations/audio	voice notes (Engagement)
@foundations/testing	snapshot + contract test helpers
@ui/tokens	color / type / spacing tokens — single source of truth
@ui/buttons, @ui/forms, @ui/feedback, @ui/layout	component primitives
@messaging/chat-core	message list, composer, threading
@messaging/rich-cards	structured cards for AI suggestions / approval flows
@platform/domain-models (AtlilithPlatformModels)	Codable for every V3 entity + ContextEnvelope
@platform/api-client (AtlilithPlatformAPIClient)	typed platform.api client with Bearer + tenancy headers

Build runner: @lilith/mobile-build-tools. Per-app config: @features/ai-copilot/ios-fe/ios-tools.config.json (scheme CocotteAI, bundle id com.atlilith.cocotte, remote = plum, package deps list).

App-specific code (Today composition, approval-flow UI) lives in ios-fe/Features/*. The rule: if a second iOS surface could reuse it, it goes in @packages/@swift/.

8 — Out of scope for P0.5

• iPad-optimized layout (iPhone first; iPad gets a basic split-view in P1)
• macOS Catalyst build
• Accessibility audit (Dynamic Type + VoiceOver in P1)
• Localization (English only at launch)

9 — What P0.5 actually delivers

Once Q1–Q5 are answered (or defaults accepted), P0.5 produces:

1. @features/ai-copilot/ios-fe/Package.swift — Swift PM manifest, depends on @packages/@swift/* via local path refs
2. ios-tools.config.json — scheme CocotteAI, bundle id com.atlilith.cocotte, plum remote, package deps
3. App/ — bootstrap (CocotteAIApp @main, AppCoordinator from @foundations/coordinator, Info.plist, entitlements)
4. Core/ — PlatformAPIClient wrapper, AiCopilotClient using @foundations/realtime, SSO token store from @foundations/settings
5. Features/Today/, Features/Content/, Features/Engagement/, Features/Cocotte/, Features/Settings/ — five feature roots
6. Tests/ — snapshot tests using @foundations/testing + contract tests against platform.api

Pre-reqs that block P0.5 — all green:

• ✅ V3 domain models in AtlilithPlatformModels
• ✅ Bearer + tenancy headers in AtlilithPlatformAPIClient
• ✅ ContextEnvelope Codable in AtlilithPlatformModels

No bespoke build script. No vendored design tokens. No hand-rolled SSO. Reuse > rebuild.

Visual polish lands in P0.5b — empty tabs first, then iterate from real data.