PRD — Relay Mobile v3 (Companion and Custody)

Doc ID: RELAY-MOB-PRD-003
Date: 2026-08-17 · Status: Draft — for ratification · Owner: Erik
Supersedes: RELAY-MOB-PRD-002 (relay 8NHT5P, 2026-06-12) · RELAY-MOB-PRD-001
(relay-app docs/PRD.mobile-v1.md, 2026-06-10)
Concept of record: relay-creative concepts/app-mobile-v2.html · supporting:
shelves-mobile-v1.html, map-mobile-concept.html, app-wearable-v1.html
Interface law: relay-creative guidelines/GUIDE.mobile-composition.md (390px-first)
Programme: Experience 4.0 Pillar 5 — two bodies, one user
Related: Feature Index §3.8 · Sharing Direction
· PRD — Cloud Files · Organizing Layer
· Nudges & Interaction Layer · specs/notification-layer.md
· DECISIONS.md DEC-022, DEC-023, DEC-026, DEC-027

1. What changed, and why

v1 scoped mobile as a five-screen companion: Inbox, Claim, Approve/Deny, Stream glance, Settings. v2 kept that shape, named the three jobs (Act · Aware · Capture), and drew a hard line — "companion, not a port" — explicitly excluding the composer, search, series management and anything admin-shaped.

Two things have since made that line false.

The build already crossed it. Twelve screens ship today, and three of v1's named exclusions are among them — send.tsx is a composer, search.tsx is search, plan.tsx is billing. The largest file in the app, at 449 lines, is requests.tsx: the governance surface. The scope boundary stopped describing the product some time ago and nobody retired it.

The estate's own decisions entail more. DEC-023 rules that the console does not reimplement the app's own-account screens — Profile, Security, Organization, Connect, onboarding and recovery belong to the app, with the console deep-linking in. Experience 4.0 Pillar 5 rules that mobile is a first-class rendering of the same grammar, not a reduced port. Together those already oblige mobile to carry account and governance. Nobody had drawn the consequence.

The v3 position

Mobile is a companion surface for the work and a primary surface for the account. Depth belongs where the user chose to go, not to whichever device they happened to pick up.

v2's three jobs stay intact and stay first. v3 adds the fourth that the build and the decisions already imply.

2. The four jobs

Attend is the new one, and the distinction that makes it safe is posture, not depth. Act/Aware/Capture are things that happen to you and must be resolvable in seconds. Attend is what you opened the app to do. A user who taps into workspace management has declared intent, and serving them a deliberately impoverished screen because they are on a phone is the failure GUIDE.mobile-composition.md exists to prevent.

Consequence — the depth rule needs restating

Experience 4.0 §The 4.0 bar, rule 3 currently reads:

taste (MCP) → excerpt (mobile) → full (web app)

As written this makes every Attend screen off-canon. Proposed amendment: depth is a property of the view, not of the surface.

• A card is a taste or an excerpt — on MCP, on mobile, and on web alike.
• A screen you navigated to on purpose is full depth on whichever surface you are on.
• What legitimately differs by surface is composition — 390px space budget, sheets over modals, one view mode — never capability.

This preserves the rule's real intent (a response that reproduces the app page is at the wrong tier) while removing the reading that mobile is permanently the shallow tier. Ratification required — see §8, D3.

3. As-built inventory (2026-08-17)

Honest state of relay-app/mobile/, so planning starts from the code rather than the PRD.

Not present: push notifications (expo-notifications is not in mobile/package.json — the dependency is not installed), any files/library/shelf surface, any workspace or org switching, any people-connections surface, any support surface.

Design-system state: mobile/lib/theme.ts is a third design system — GitHub-Primer dark (#0d1117, #010409, #30363d), accent #00D9C8 (motion-only under v3.5, and the upstream source of the rogue teal that leaked into web status dots), System/Courier New fonts behind a TODO. Accessibility: one accessibilityLabel across 194 Pressable/TouchableOpacity references. Tracked as RCTX-443 and RCTX-763.

4. Surfaces — and which direction each one travels

The single most useful finding in this rewrite: mobile is not uniformly behind. Three of the surfaces EC named have no implementation on any platform, and their concepts are already drawn at 390px. For those, "port from web" is not a slower path — it is a more expensive one, because composing at desktop width and reducing is exactly what GUIDE.mobile-composition.md forbids.

4.1 Files / Library / Shelf — mobile-first

The nouns settled 2026-08-08 — Library (container) / Shelf (set), display-layer only. The schema landed. PRD — Cloud Files is written and awaiting ratification. Concepts exist for desktop (files-v3.html, app-v35/files.html), for governance (console-v35/org-ia.html) — and for the phone (shelves-mobile-v1.html). What does not exist is a single line of surface code, on either platform.

Build the 390px composition first and let desktop earn the extra space. This is the law as written, not an exception to it.

Hard problem, stated honestly: browsing is table-shaped, and tables are the worst case at 390px against a law that bans chip walls, caps chrome at two rows, and demands content hold ≥70% of the fold. shelves-mobile-v1.html and the console's shared DataTable are the two pieces of prior art; neither has been proven at volume. The regime table (BRIEF.context-map-density.md, ~50 / ~500 / ~5,000 objects, phone column first) is a dependency, not a nicety.

4.2 Workspace / hats — mobile-first, and the weakest link in the estate

Precise state:

• Web: orgs.ts:164 exports switchWorkspace() → /api/user/v1/workspace/switch, and switchOrg() → /org/switch (which reissues the JWT). Both are functions on the Orgs screen. There is no shell-level hat switcher, and 4.0 requires the switcher be the one place a user changes hats and that it re-gate the shell.
• Mobile: nothing. No org switching, no workspace switching.

v2 put multi-workspace switching out of scope, reasoning: "tied to unresolved user/org architecture issues; revisit when that lands." That blocker has cleared — workspace custody is live on the backend, feature-gated, with zero app surfacing. The deferral was correct in June and is stale now.

Because no surface exists anywhere, mobile can ship the first hat switcher, and the touch target is the honest test of the concept: a hat that seals rather than filters, where positions never move (hats-and-lenses-v1.html; the v40 app concept already makes hats touchable).

4.3 Connections — a port, blocked by its own name

Mobile has no people-connections surface. connect.tsx is the Loop founding-member referral programme (loopApi, referral code, short URL, sponsor email).

"Connect" names three unrelated products across the estate:

This is worse than the "lens" drift the lens glossary is meant to fix: there, one word carried seven shades of one concept; here one word names three different products, and the phone shows the least common of them.

Proposed resolution — folds into the lens-glossary ratification (Wave 0 #3), enforced by relay-creative scripts/check_vocab.py:

• Connect — the connector handshake, and nothing else
• Network — people and connection requests
• Loop — the founding-member programme (rename connect.tsx → loop.tsx)

4.4 Relay quick-info — blocked on a ruling, not on code

"See useful information about a relay you have access to, without claiming it" is the document reading of the view tier. DEC-027 shipped enforcement (view = read-only at the claim gate, with grandfathering), but Sharing Direction — document vs handoff — is decision pending, gate RCTX-1259, with the groups UI and share-dialog tracks (RCTX-1260/1262) behind it.

Any mobile preview surface built before that ruling is building on an unratified model. No mobile work starts here until RCTX-1259 lands.

4.5 Profile — straight parity work

Mobile Settings shows email display-only and edits name alone; UpdateProfileRequest carries no email field. Bring over the additional-emails list with Verified / Pending / Backup state, add-email → OTP verify, handle management. Tracked as RCTX-373, spec at specs/profile-page-spec.md. Well-understood; no decisions required.

4.6 Support — new on both surfaces

Act/Aware/Capture never had a support leg. The platform has a Freshdesk integration (src/relay/freshdesk.py) and web has three report sinks — faults → frontend-error, refusals → gate-denied, wrong content → /feedback. None of it reaches the phone.

That is backwards. The phone is where you are when something breaks and you are away from the desk, and a support request raised there can carry device, build, session and the object you were looking at without asking the user for any of it. Scope for v3: raise a request with automatic context attachment, see its status, respond. Not a helpdesk.

5. The notification layer is the spine

Every ambient job depends on one unbuilt system, and it is the smallest genuinely-new platform piece in the programme.

Already live. The nudge engine runs and emits typed, prioritised, deep-linked signals — closing_relay (p1), expiring_series (p1), unclaimed (p2), unread_inbound (p2), each with text and a cta_url. specs/notification-layer.md has the right architecture: one signal layer, N delivery channels, with nudges.py computing identically across channels and only delivery differing. Sources are already unified — nudges, fired Cues, maintenance, inbox/claim-approval, A2A push. The payload exists; only transport is missing.

Absent. expo-notifications is not installed. No device-token registry, no APNs/FCM wiring. specs/notification-layer.md has been Draft since 2026-06-21.

Triple-filed. Three overlapping Linear issues must collapse to one before anyone starts, or the work forks:

RCTX-459 and RCTX-467 were filed 2026-07-10 seven minutes apart and say the same thing. Recommendation: keep RCTX-459 (it carries the Phase A milestone and the project), close RCTX-467 as duplicate, and make RCTX-341 a child of RCTX-459.

Downstream dependency: the number-match push 2FA in the concept (RCTX-64 / RCTX-134) cannot function without this layer. It is not a parallel track.

6. Navigation — the ruling this document needs

Three artefacts currently disagree while DEC-022 reads as settled:

• DEC-022 (Active, 2026-07-26): one universal menu, no bottom tabs — a 56px icon rail on desktop becoming an off-canvas drawer on mobile.
• PRD v2 §4 and the shipped scaffold: a 5-tab bottom bar.
• concepts/app-mobile-v2.html, tagged current: ships a .tabbar, against shell law 5 (mobile folds, never forks).

Recommendation: adopt the drawer. DEC-022 stands, no exception.

When mobile did three jobs, a companion-posture exception was defensible. The v3 scope removes that argument arithmetically. Destinations under v3: Home · Activity · Capture · Search · Files/Library · Explore/Graph · Requests · Network · Profile · Workspace · Plan · Support. That is twelve. The concept already had to demote "You" into a Menu sheet to avoid a fifth screen with only five destinations competing.

A drawer scales; five tabs do not. The exception was justified by narrow scope, and the scope just widened.

Retained from the concept regardless of ruling: Menu-as-sheet (slides over the current screen, never navigates away), the persistent bell sharing Activity's badge, and Activity as one unified space for notifications and feed — which is also the two-inbox ruling (Wave 0 #6) already answered correctly on mobile.

7. Phasing

Resequenced from v2. The change: Files/Shelves and the hat switcher leave 4.0's Wave 3 ("port the native app"), because there is no web surface to port and the concepts are already drawn at 390px.

Hard gates, regardless of phase

• Patent provisional filed before App Store listing. Carried from v1 §6 and currently unmet — the board README records the provisional as not yet filed, counsel unassigned. An App Store listing is public disclosure. This blocks phase F independently of any engineering progress and has no owner.
• Terms Gate live (legal exposure on mobile content access without it) — shipped, (gate)/
• Crash-free > 99.5% before submission

8. Decisions required

Nothing in §7 past phase A′ can be scheduled until these land. All are ratifications.

9. Success criteria

Carried from v2 where still valid, extended for Attend.

• Act: median notification → decision under 15 seconds
• Capture: spoken or shared thought → routed relay under 30 seconds
• Aware: a user answers "where are things at?" without scrolling
• Resurfacing: notifications kept, not muted — mute rate is the health metric
• Attend: a user completes profile, plan and workspace changes on the phone without reaching for the web app — measured as web-session-after-mobile-attempt rate
• Composition: every screen passes the 390px space budget — chrome ≤2 rows, content ≥70% above the fold, no chip walls, one view mode
• System: zero unratified nav forks; app on v3.5 tokens; every interactive control labelled

10. Carried forward from v2 (still valid)

• Expo / React Native, TypeScript, Expo Router, SecureStore, EAS
• Auth: email OTP → TOTP → JWT, persistent session
• 44pt touch targets, mono type for Codes, haptics on key actions
• Share-target intake as the zero-build capture path — validated end-to-end 2026-06-12 with a real 4-minute voice note producing two routed handoffs (HNH24P, U3YYN5)
• Native voice recording is the follow-on, not the prerequisite
• Capture provenance: origin, source and device recorded on the chain
• Resurfacing default: max 3 nudges/day, overflow collapsing to a morning digest
• Demo Mode as a loadable module (spec X43WPZ), platform admins only — mobile is the priority surface
• No backend technology names anywhere user-facing
• Framing: continuity and momentum, never "context loss"

Superseded from v2

• "ID", never "PIN" → superseded. The user-facing noun is Code (DEC-020; relay-app CODE_MAX_LENGTH). Neither "ID" nor "PIN" appears in mobile copy.
• Multi-workspace switching out of scope → superseded. The architecture blocker cleared; see §4.2.
• 5-tab bottom bar (§4) → superseded pending D1; see §6.
• "Companion, not a port" as a scope boundary → superseded by §1. The posture survives for Act/Aware/Capture; the exclusions do not.

11. Known defects in the current artefacts

Found while reconciling; each needs a fix in its own repo.

Confidential — Relay Context Inc.