docs(mobile): defer react native platform sdk

docs/MOBILE_DELEGATION_ROADMAP.md

@@ -88,7 +88,9 @@ Block I  →  Optional — @bytelyst/sync or deeper sync (last; needs API contra
 
 ### A.3 Optional (platform SDK parity)
 
-If the team standardizes on **`@bytelyst/react-native-platform-sdk`**: either integrate **`AuthProvider`** with the **same MMKV keys** as `createAuthClient({ storagePrefix: PRODUCT_ID })`, or document a minimal bridge (same approach as NomGap Block A in `learning_ai_fastgap`).
+Decision for this handoff: defer direct **`@bytelyst/react-native-platform-sdk`** adoption and keep mobile on direct shared `@bytelyst/*` clients. See [`MOBILE_PLATFORM_SDK_DECISION.md`](./MOBILE_PLATFORM_SDK_DECISION.md).
+
+If the team standardizes on the SDK later: either integrate **`AuthProvider`** with the **same MMKV keys** as `createAuthClient({ storagePrefix: PRODUCT_ID })`, or document a minimal bridge (same approach as NomGap Block A in `learning_ai_fastgap`).
 
 ### A.4 Done criteria
 

docs/MOBILE_PLATFORM_SDK_DECISION.md

@@ -0,0 +1,40 @@
+# Mobile Platform SDK Decision
+
+Status: active decision
+Date: May 5, 2026
+Decision: defer direct adoption of `@bytelyst/react-native-platform-sdk` for the production-readiness handoff.
+
+## Context
+
+NoteLett mobile already uses shared common-platform clients directly:
+
+- `@bytelyst/auth-client` in `mobile/src/api/auth.ts`
+- `@bytelyst/api-client` in `mobile/src/api/client.ts`
+- `@bytelyst/platform-client` in `mobile/src/lib/platform-api.ts`
+- telemetry, feature flags, kill switch, blob, diagnostics, billing, broadcast, survey, feedback, and offline queue clients in `mobile/src/lib/*`
+
+The current `@bytelyst/react-native-platform-sdk` package in `../learning_ai/learning_ai_common_plat` exposes React Native providers/hooks for auth, telemetry, feature flags, kill switch, broadcasts, and surveys. It does not yet cover the full NoteLett mobile composition: product-backend API calls, blob uploads, diagnostics singleton metadata, billing, feedback, offline queue flushing, or the existing `@bytelyst/auth-client` token storage contract.
+
+## Decision
+
+Defer replacing NoteLett's direct shared clients with `@bytelyst/react-native-platform-sdk` until the shared SDK can be adopted without losing current behavior.
+
+This is not a rejection of the SDK. It is a release-readiness choice: the direct clients already come from common platform, have product/auth/request propagation tests, and are closer to NoteLett's current Expo/MMKV architecture.
+
+## Required Adoption Criteria
+
+Adopt the React Native platform SDK later when it can provide or cleanly bridge:
+
+- the same MMKV token keys as `createAuthClient({ storagePrefix: PRODUCT_ID })`
+- product-backend API client access with `x-product-id`, bearer token, and request ID propagation
+- blob upload/download parity with `@bytelyst/blob-client`
+- diagnostics metadata parity for app version, build number, release channel, install ID, and auth token access
+- billing, feedback, broadcast, survey, feature flag, kill-switch, telemetry, and offline queue integration without duplicate initialization
+- testable hooks/providers that fit the existing Expo Router auth bootstrap and root-layout gating flow
+
+## Current Guardrails
+
+- Keep using direct `@bytelyst/*` clients in mobile for this handoff.
+- Do not introduce a second auth/token source.
+- Do not add `@bytelyst/react-native-platform-sdk` as a mobile dependency until a migration plan removes redundant direct initialization.
+- Revisit this decision after P2/P7 production-readiness gates and mobile offline/sync decisions are complete.

docs/ROADMAP.md

@@ -481,7 +481,7 @@ Detailed implementation plans live under `docs/roadmaps/`.
   - SAS-based upload/download via platform-service blob endpoints
 - 2026-03-10 — QA / release hardening:
   - AGENTS.md and README.md created following ecosystem conventions
-- 2026-03-11 — Mobile platform SDK integration (`878c644`):
+- 2026-03-11 — Mobile direct shared-client integration (`878c644`):
   - Added @bytelyst/telemetry-client, feature-flag-client, kill-switch-client, blob-client to mobile deps
   - Created mobile/src/lib/platform.ts — centralized platform init (telemetry, flags, kill-switch, blob)
   - Refactored web blob-client.ts to use shared @bytelyst/blob-client (DRY)
@@ -509,7 +509,7 @@ Detailed implementation plans live under `docs/roadmaps/`.
 - **Active lint blocker** — backend lint is missing `@eslint/js`, web lint has React compiler rule violations, and mobile lint has one unresolved shared billing-client import. Tracked by production-readiness P0.5, P4.3, P7.4, P8.1, and P8.5.
 - **Active runtime smoke gap** — platform-service, extraction-service, mcp-server, blob, telemetry, diagnostics, flags, kill switch, and NoteLett backend health need documented and automated smoke checks. Tracked by production-readiness P2.2-P2.4 and P8.4.
 - ~~**Blocker** — Product identity not finalized~~ **Resolved:** locked as NoteLett (`e1fde25`)
-- ~~**Blocker** — `@bytelyst/react-native-platform-sdk` not wired~~ **Resolved:** platform.ts with telemetry, flags, kill-switch, blob (`878c644`)
+- **Deferred** — `@bytelyst/react-native-platform-sdk` adoption is intentionally deferred for release handoff; mobile uses direct shared `@bytelyst/*` clients instead. See `docs/MOBILE_PLATFORM_SDK_DECISION.md`.
 - ~~**Deferred** — Blob-backed artifacts and upload/download flows~~ **Resolved:** SAS-based blob client (`196b210`)
 - ~~**Deferred** — Fully integrated approval/review/audit UX~~ **Resolved:** batch review, review notes, agent timeline across web + mobile (`ca3cdba`, `f8a4c18`)
 - ~~**Deferred** — Persisted saved views~~ **Resolved:** backend CRUD + web client + UI (`bdbf387`, `12d9009`)

docs/roadmaps/04_MOBILE_ROADMAP.md

@@ -7,7 +7,7 @@ Stack: React Native + Expo + TypeScript
 # Phase M0 — Scaffold
 
 - [x] Create Expo app structure
-- [ ] Wire `@bytelyst/react-native-platform-sdk`
+- [ ] Defer direct `@bytelyst/react-native-platform-sdk` adoption until shared SDK parity is ready
 - [ ] Wire `@bytelyst/api-client`
 - [x] Wire `@bytelyst/platform-client`
 - [x] Wire `@bytelyst/offline-queue`
@@ -103,8 +103,8 @@ Stack: React Native + Expo + TypeScript
 
 # Blockers
 
-- `@bytelyst/react-native-platform-sdk` is referenced as a planned shared dependency, but the current workspace package does not appear ready for direct runtime consumption in this new app yet.
-- Product identity and backend contract details remain provisional in the planning docs, so mobile config values are placeholders.
+- `@bytelyst/react-native-platform-sdk` direct adoption is deferred for the production-readiness handoff; mobile currently uses direct shared `@bytelyst/*` clients. See [`../MOBILE_PLATFORM_SDK_DECISION.md`](../MOBILE_PLATFORM_SDK_DECISION.md).
+- ~~Product identity and backend contract details remain provisional in the planning docs, so mobile config values are placeholders.~~ **Resolved:** NoteLett identity and backend URLs are now canonical.
 
 # Deferred