docs(mobile): defer sync engine adoption

docs/MOBILE_DELEGATION_ROADMAP.md

@@ -250,11 +250,14 @@ Execute in **flexible order**; prefer **small commits**.
 
 ## Block I — Optional sync engine (`@bytelyst/sync`)
 
-**Last.** Mobile currently hydrates via **REST + Zustand**. Replacing with **`@bytelyst/sync`** requires mapping entities (notes, workspaces, inbox) to backend contracts and conflict rules — verify with backend before swapping.
+**Decision for this handoff:** defer **`@bytelyst/sync`** adoption and keep the current `@bytelyst/offline-queue` mutation retry model. See [`MOBILE_SYNC_DECISION.md`](./MOBILE_SYNC_DECISION.md).
+
+**Later.** Mobile currently hydrates via **REST + Zustand**. Replacing with **`@bytelyst/sync`** requires mapping entities (notes, workspaces, inbox) to backend contracts and conflict rules — verify with backend before swapping.
 
 ### I.1 Done criteria (only if attempted)
 
 - [ ] Parity with current hydration + offline behavior
+- [x] Handoff decision recorded: defer `@bytelyst/sync` until backend sync contracts and conflict rules are explicit
 - [ ] Update [`AGENT_TASK_ROADMAP.md`](./AGENT_TASK_ROADMAP.md)
 - [ ] Commit: `feat(mobile): adopt @bytelyst/sync` (large; may split)
 

docs/MOBILE_SYNC_DECISION.md

@@ -0,0 +1,42 @@
+# Mobile Sync Decision
+
+Status: active decision
+Date: May 5, 2026
+Decision: defer `@bytelyst/sync` adoption for the production-readiness handoff.
+
+## Context
+
+NoteLett mobile currently uses:
+
+- REST hydration through `mobile/src/api/*`
+- Zustand stores for notes, workspaces, prompts, inbox, and auth
+- `@bytelyst/offline-queue` in `mobile/src/lib/offline-queue.ts` for failed note create/update retries
+- auth-gated queue flushing from `mobile/src/app/_layout.tsx`
+
+The shared `@bytelyst/sync` package provides an offline-first sync engine with entity mapping, persistent queue storage, pull/push cycles, conflict handling, retries, reconnect flushing, telemetry hooks, and configurable storage.
+
+## Decision
+
+Defer replacing the current mobile offline queue with `@bytelyst/sync` until NoteLett has explicit backend contracts for entity-level sync and conflict resolution.
+
+The current queue is intentionally narrow: it retries note create/update mutations after transient failures while keeping reads as live REST hydration. That is suitable for the current handoff. Moving to `@bytelyst/sync` would require product decisions about stale reads, workspace membership changes, note version conflicts, agent-action review state, prompt/intake jobs, and blob-backed artifacts.
+
+## Required Adoption Criteria
+
+Adopt `@bytelyst/sync` later when these are defined and tested:
+
+- entity map for notes, workspaces, relationships, tasks, artifacts, prompts, intake jobs, and agent actions
+- backend endpoints that support pull windows, updated-since cursors, tombstones, and conflict responses
+- conflict strategy for note title/body edits versus server-side versions and agent proposals
+- product-scoped storage keys using `PRODUCT_ID`
+- MMKV storage adapter parity and migration from the current offline queue key
+- telemetry events for sync success, failure, conflict, queue depth, and retry exhaustion
+- UX for sync status, stale data, retry failures, and conflict review
+- tests proving parity with current note create/update offline behavior before removing `@bytelyst/offline-queue`
+
+## Current Guardrails
+
+- Keep `@bytelyst/offline-queue` as the mobile mutation retry foundation for this handoff.
+- Do not add a second queue that can replay the same note mutation twice.
+- Expand the current queue only where production-readiness P6/P7 require clear retry UX.
+- Revisit `@bytelyst/sync` after backend sync contracts and mobile offline acceptance tests are explicit.

docs/ROADMAP.md

@@ -510,6 +510,7 @@ Detailed implementation plans live under `docs/roadmaps/`.
 - **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`)
 - **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** — `@bytelyst/sync` adoption is intentionally deferred for release handoff; mobile keeps the narrower `@bytelyst/offline-queue` retry model until backend sync/conflict contracts are explicit. See `docs/MOBILE_SYNC_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

@@ -29,7 +29,7 @@ Stack: React Native + Expo + TypeScript
 
 - [x] Lightweight local editing
 - [ ] Notification handling
-- [ ] Offline queue / sync polish
+- [ ] Offline queue / sync polish (`@bytelyst/sync` deferred; see `../MOBILE_SYNC_DECISION.md`)
 - [x] Approvals inbox scaffold if in MVP scope
 - [x] Basic artifact metadata viewing scaffold if in MVP scope