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.