coding-os 0.3.2__py3-none-any.whl

templates/react-native/scaffold/docs/engineering/mobile-rules.md

@@ -0,0 +1,56 @@
+<!-- domain:MOBILE | layer:policy | ssot:true | updated:2026-04-29 -->
+# Mobile Engineering Rules
+
+> P: Rules every `src/mobile/**/*.{ts,tsx}` file must satisfy. Layered on top of clean-code, frontend-fundamentals, and a11y.
+> R: Reviewing or writing any mobile source file.
+> S: Touching the web frontend or backend.
+> N: [offline-first.md](offline-first.md), [accessibility-mobile.md](accessibility-mobile.md), [../playbooks/mobile-app.md](../playbooks/mobile-app.md)
+
+## 1. Architecture
+
+- Expo SDK + React Native 0.74+. Use Expo Router for navigation.
+- One root `_layout.tsx` per route segment.
+- State: hooks-local first, Zustand slice for cross-screen.
+- Style: StyleSheet.create OR utility-first (NativeWind) — pick one per stack, never mix.
+- Theme: tokens live in `src/shared/contracts/design-tokens.ts`, re-exported via `src/mobile/lib/theme/`.
+
+## 2. Performance
+
+- Screen TTI ≤ 600 ms on Pixel 5 / iPhone 13.
+- Animations 60 fps — verify with Reanimated profiler.
+- Image budget ≤ 200 KB per screen — `expo-image` mandatory.
+- Avoid `Animated` (legacy); prefer Reanimated v3 + worklets.
+
+## 3. Worklets
+
+- Functions running on the UI thread MUST start with `'worklet';`.
+- Worklets MAY NOT call `fetch`, `console.log`, `setTimeout`. Bridge via `runOnJS()`.
+- Shared values via `useSharedValue`, never `useState` for animation.
+
+## 4. Storage
+
+- All persistent storage goes through `src/mobile/lib/storage.ts`.
+- Sensitive values (auth tokens, PII) use `expo-secure-store` — exposed via `src/mobile/lib/secure-storage.ts`.
+- Tests inject a fake storage adapter — never read the real keychain in test mode.
+
+## 5. Networking
+
+- All HTTP via `src/mobile/lib/api/_client.ts` (timeout, retry, base URL, auth header).
+- Validate responses against `src/shared/contracts/<resource>.ts` schema.
+- Map errors to `<ResourceError>` envelope from `src/shared/contracts/errors.ts`.
+- Never call `fetch` directly from a screen / component.
+
+## 6. Tests
+
+- Colocated `.test.{ts,tsx}` next to source.
+- Given/When/Then in test names.
+- Snapshots only for static screens; never for hook-driven UI.
+- E2E flows live in `src/mobile/e2e/<flow>.yaml` — Maestro.
+
+## 7. Accessibility
+
+See [accessibility-mobile.md](accessibility-mobile.md). Every interactive element MUST carry `accessibilityRole`, `accessibilityLabel`, and `accessibilityState`. Test with VoiceOver + TalkBack before merge.
+
+## 8. Boundary
+
+`src/mobile/` may import from `src/shared/`. Never from `src/frontend/`, `src/backend/`, `src/ai-service/`. Cross-stack contracts live in `src/shared/types/` and `src/shared/contracts/`. SSOT: [`src/templates/react-native/scaffold-boundary.yaml`](../../../scaffold-boundary.yaml).

templates/react-native/scaffold/docs/engineering/offline-first.md

@@ -0,0 +1,61 @@
+<!-- domain:MOBILE | layer:policy | ssot:true | updated:2026-04-29 -->
+# Offline-First Patterns
+
+> P: Sync-queue + conflict-resolution patterns every mutating action in the mobile app must follow.
+> R: Adding a user-mutating action (log medication, save profile, post message).
+> S: Read-only screens that never POST / PATCH / DELETE.
+> N: [mobile-rules.md](mobile-rules.md), [../playbooks/mobile-app.md](../playbooks/mobile-app.md)
+
+## 1. Optimistic UI
+
+Every mutation:
+
+1. Updates Zustand state immediately.
+2. Pushes the action to `src/mobile/sync/queue.ts`.
+3. Drains the queue with `src/mobile/sync/drainer.ts` when connectivity returns.
+
+Never block the UI on a pending sync.
+
+## 2. Action shape
+
+Every queued action is a typed object with `kind`, `payload`, `clientId`, `clientTimestamp`:
+
+```ts
+type LogMedicationAction = {
+  kind: 'log_medication';
+  clientId: string;          // UUID generated client-side
+  clientTimestamp: string;   // ISO-8601 in user's local TZ
+  payload: { petId: string; medicationId: string; dose: number };
+};
+```
+
+`clientId` is the idempotency key — the server must dedupe on it.
+
+## 3. Drainer guarantees
+
+- Drainer runs on every `NetInfo` connectivity change AND on app foreground.
+- Actions are FIFO per pet / resource group; cross-resource ordering is best-effort.
+- A single failure is retried with exponential backoff (`100ms → 1s → 10s → user-visible error`).
+- On 4xx the action is moved to `src/mobile/sync/dlq.ts` and the user sees a `<ConflictModal />`.
+
+## 4. Conflict resolution
+
+Three strategies, decide per action type:
+
+| Strategy | When | Implementation |
+|---|---|---|
+| Last-write-wins | Profile fields, simple state | server overwrites local on 409 |
+| Merge | Lists (medication log) | client + server unions on `clientId` |
+| User-prompt | Conflicting edits, deletes | `<ConflictModal />` with both versions |
+
+Never silently drop user data.
+
+## 5. Storage
+
+Queue persists via `src/mobile/lib/storage.ts` so app restarts don't lose pending actions. The drainer reads at startup before mounting any UI.
+
+## 6. Tests
+
+- Unit-test `enqueue()` and `apply()` separately with a fake drainer.
+- Integration: simulate offline → mutate 3x → reconnect → assert all 3 reach the server.
+- E2E (Maestro): airplane mode → action → connectivity → action visible on the server.

templates/react-native/scaffold/docs/playbooks/mobile-app.md

@@ -0,0 +1,49 @@
+<!-- domain:MOBILE | layer:playbook | ssot:true | updated:2026-04-29 -->
+# Mobile App Playbook
+
+> P: Routes mobile-specific tasks to anatomy.md, the right rules file, and verification commands.
+> R: Picking up any task whose primary work happens in `src/mobile/`.
+> S: Working on web / backend / ai-service code.
+> N: [../engineering/mobile-rules.md](../engineering/mobile-rules.md), [../engineering/offline-first.md](../engineering/offline-first.md), [../engineering/accessibility-mobile.md](../engineering/accessibility-mobile.md)
+
+## When to use
+
+Any task that touches `src/mobile/**/*.{ts,tsx}` — new screens, components, hooks, sync actions, native bridges, or perf work.
+
+## Read selection guide (3-7 files max)
+
+For typical tasks, read in this order:
+
+1. The active task file — `docs/tasks/TASK-NNN-*.md`.
+2. [`anatomy.md`](../../skills/react-native-mobile/references/anatomy.md) — file map + entity recipe for the action you're about to take.
+3. The matching rule file (`mobile-rules.md` for general, `offline-first.md` for sync, `accessibility-mobile.md` for a11y).
+4. The existing parent screen/component/hook the change relates to.
+5. `src/shared/contracts/<resource>.ts` if you're adding an API call.
+6. `src/mobile/store/<slice>.ts` if you're touching shared state.
+7. `src/mobile/sync/queue.ts` if you're queueing a mutation.
+
+Stop reading when no further file would change the implementation decision.
+
+## Steps
+
+1. Classify: which entity recipe in [`anatomy.md`](../../skills/react-native-mobile/references/anatomy.md) matches?
+2. Map dependencies: which files do you read, edit, or create?
+3. Implement smallest correct change.
+4. Add or extend colocated tests (Given/When/Then).
+5. Manual smoke: run on iOS simulator AND Android emulator before opening PR.
+
+## Verification
+
+| Changed | Command |
+|---|---|
+| `src/mobile/**/*.{ts,tsx}` | `cd mobile && npm run lint && npm test -- --findRelatedTests <file>` |
+| `src/mobile/sync/**` | `cd mobile && npm test -- src/mobile/sync` |
+| `src/mobile/native/**` | manual native build (iOS + Android) |
+| `src/mobile/e2e/**` | `cd mobile && npx maestro test e2e/<flow>.yaml` |
+
+## Failure modes
+
+- White screen on Android only → Reanimated worklet calling JS-thread API.
+- Optimistic state out of sync after reconnect → `src/mobile/sync/drainer.ts` not idempotent.
+- VoiceOver skips an element → `accessibilityRole` missing.
+- iOS-only crash on launch → native bridge ADR not implemented for the target version.

templates/react-native/scaffold/src/mobile/App.tsx

@@ -0,0 +1,9 @@
+import { Text, View } from "react-native";
+
+export default function App() {
+  return (
+    <View>
+      <Text>mobile — health ok</Text>
+    </View>
+  );
+}

templates/react-native/scaffold/src/mobile/eslint.config.js

@@ -0,0 +1,17 @@
+import js from "@eslint/js";
+import tseslint from "typescript-eslint";
+
+export default tseslint.config(
+  {
+    ignores: ["**/android/**", "**/ios/**", "**/dist/**", "**/build/**", "**/coverage/**", ".coding-os/**"],
+  },
+  js.configs.recommended,
+  ...tseslint.configs.recommended,
+  {
+    rules: {
+      "no-console": ["warn", { allow: ["warn", "error"] }],
+      "@typescript-eslint/no-unused-vars": ["error", { argsIgnorePattern: "^_" }],
+      "@typescript-eslint/consistent-type-imports": "error",
+    },
+  },
+);

templates/react-native/scaffold/src/mobile/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "mobile",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "lint": "eslint . && tsc --noEmit",
+    "test": "vitest run",
+    "build": "tsc --noEmit"
+  },
+  "dependencies": {
+    "react": ">=18",
+    "react-native": ">=0.74"
+  },
+  "devDependencies": {
+    "@eslint/js": ">=9",
+    "@types/react": ">=18",
+    "eslint": ">=9",
+    "typescript": ">=5.4",
+    "typescript-eslint": ">=8",
+    "vitest": ">=2"
+  }
+}

templates/react-native/scaffold/src/mobile/src/greeting.test.ts

@@ -0,0 +1,9 @@
+import { describe, expect, it } from "vitest";
+
+import { greeting } from "./greeting";
+
+describe("greeting", () => {
+  it("greets by name", () => {
+    expect(greeting("mobile")).toBe("Hello, mobile");
+  });
+});

templates/react-native/scaffold/src/mobile/src/greeting.ts

@@ -0,0 +1,3 @@
+export function greeting(name: string): string {
+  return `Hello, ${name}`;
+}

templates/react-native/scaffold/src/mobile/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "lib": ["ESNext"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true
+  },
+  "include": ["App.tsx", "src"],
+  "exclude": ["node_modules", "android", "ios", "build", "dist", ".coding-os"]
+}

templates/react-native/scaffold/src/mobile/vitest.config.ts

@@ -0,0 +1,10 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: "node",
+    include: ["src/**/*.{test,spec}.{ts,tsx}"],
+    exclude: ["node_modules", "android", "ios"],
+  },
+});

templates/react-native/scaffold-boundary.yaml

@@ -0,0 +1,30 @@
+# Scaffold boundary for the react-native stack.
+# Schema: docs/governance/scaffold-boundary-contract.md
+# SSOT for what `src/mobile/` may write, read, or import.
+
+version: 1
+stack: react-native
+
+roots:
+  - src/mobile/
+
+file_patterns:
+  - "src/mobile/**/*.ts"
+  - "src/mobile/**/*.tsx"
+  - "src/mobile/**/*.js"
+  - "src/mobile/**/*.jsx"
+
+imports_from:
+  - src/shared/
+  - src/shared/types/
+  - src/shared/contracts/
+
+forbids_writing_in:
+  - src/frontend/
+  - src/backend/
+  - src/ai-service/
+
+notes:
+  - "Hermes + Reanimated worklets impose constraints — mark `'worklet'` on UI-thread functions."
+  - "Cross-stack types live in src/shared/types — never import directly from another stack root."
+  - "Offline-first by default: every screen handles loading / empty / error states."

templates/react-native/skills/react-native-mobile/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: react-native-mobile
+tier: stack
+domain: [mobile]
+description: Use when creating or modifying React Native screens, components, hooks, or native bridges in the mobile app. Triggers on any .ts/.tsx file change under src/mobile/. Covers Hermes + Reanimated worklet constraints, three-state async UI, offline-first sync queues, navigation patterns, and a11y for VoiceOver / TalkBack.
+globs: "src/mobile/**/*.{ts,tsx}"
+depends_on:
+  - clean-code
+  - frontend-fundamentals
+  - a11y
+last_reviewed: "2026-06-04"
+versions_ref: versions.json
+
+---
+
+This skill enforces React Native + Expo conventions for the `src/mobile/` subtree. It `depends_on: [clean-code, frontend-fundamentals, a11y]` — universal code quality, three-state async UI, and accessibility checks load transitively. This skill adds ONLY mobile-specific concerns on top.
+
+Anatomy reference: [`references/anatomy.md`](references/anatomy.md). Read that file BEFORE writing any new screen / component / hook.
+
+## Pre-Code Checklist
+
+Before writing or modifying any `.ts` / `.tsx` file under `src/mobile/`:
+
+- [ ] Read [`references/anatomy.md`](references/anatomy.md) — file map and entity recipes.
+- [ ] If touching a screen: read `docs/playbooks/mobile-app.md`.
+- [ ] If touching offline / sync: read `docs/engineering/offline-first.md`.
+- [ ] If touching animation: confirm worklet vs JS thread split.
+- [ ] If touching API calls: read `docs/api-contracts/error-format.md`.
+
+## 1. Architecture defaults
+
+- **Navigation:** React Navigation v7 (stack + tabs). Every route lives under `src/mobile/app/(tabs)/<route>` or `src/mobile/app/<route>` if outside the tab bar.
+- **State:** prefer hooks-local state. Cross-screen state goes through `src/mobile/store/` (Zustand by default; swap is a stack-wide decision, not per-feature).
+- **Styling:** StyleSheet API for static styles, NativeWind / Tailwind RN for utility-first when configured. NEVER inline `style={{ }}` for repeated tokens.
+- **Theming:** read tokens from `src/shared/contracts/design-tokens.ts` — never hard-code colors / spacing.
+
+## 2. Three-state async UI (mandatory)
+
+Every screen that fetches data MUST handle three states explicitly:
+
+```tsx
+if (loading) return <Skeleton />;
+if (error)   return <ErrorView onRetry={retry} message={mapError(error)} />;
+if (!data)   return <EmptyState />;
+return <Content data={data} />;
+```
+
+If only happy path renders → fail in PR review.
+
+## 3. Hermes + Reanimated worklet rules
+
+- Functions executed on the UI thread MUST be marked with `'worklet'`:
+
+  ```tsx
+  const onScroll = useAnimatedScrollHandler({
+    onScroll: (event) => {
+      'worklet';
+      scrollY.value = event.contentOffset.y;
+    },
+  });
+  ```
+
+- Worklets MAY NOT call JS-thread APIs (`fetch`, `console.log`). Use `runOnJS()` to bridge.
+- `useSharedValue` for animated values; never `useState` for animation state.
+
+## 4. Offline-first + sync queue
+
+For any user-mutating action (log medication, save profile, post message):
+
+1. Optimistically update local state via Zustand action.
+2. Append the action to `src/mobile/sync/queue.ts`.
+3. When connectivity returns, drain the queue with `src/mobile/sync/drainer.ts`.
+4. Surface conflicts via `<ConflictModal />` — never silently drop user data.
+
+Pattern source: `docs/engineering/offline-first.md`.
+
+## 5. Accessibility (a11y)
+
+- Every interactive element MUST carry `accessibilityRole`, `accessibilityLabel`, and `accessibilityState`.
+- Test with VoiceOver (iOS) AND TalkBack (Android). Both ship in CI.
+- Focus management on screen change: use `AccessibilityInfo.announceForAccessibility(...)`.
+- Color contrast ≥ WCAG 2.2 AA — see `docs/engineering/accessibility-mobile.md`.
+
+## 6. Performance budgets
+
+- Screen TTI ≤ 600 ms on a Pixel 5 / iPhone 13.
+- Animations run at 60 fps — verify with Reanimated profiler before merge.
+- Image budget ≤ 200 KB per screen — use `expo-image` with `contentFit="cover"`.
+- Bundle: track size via `npx react-native-bundle-visualizer` per release.
+
+## 7. Native bridges
+
+Only fork to native code (Swift / Kotlin) when:
+
+1. The feature is impossible in JS (e.g. background tasks, hardware sensors).
+2. A maintained Expo or RN package does not cover it.
+3. ADR exists in `docs/architecture/adr/` documenting the decision.
+
+Otherwise: stay in TypeScript.
+
+## 8. Test discipline
+
+- Unit tests colocated: `src/mobile/components/foo/foo.test.tsx`.
+- Snapshot tests for static screens only — never for hook-driven UI.
+- E2E with Maestro: `src/mobile/e2e/<flow>.yaml`.
+- Fast: `npm test --watch` must run < 3 s on the changed file.
+
+## 9. Boundary
+
+`src/mobile/` may import from `src/shared/`. Never from `src/frontend/`, `src/backend/`, or `src/ai-service/`. Cross-stack contracts live in `src/shared/types/` and `src/shared/contracts/`.
+
+Boundary SSOT: [`src/templates/react-native/scaffold-boundary.yaml`](../../scaffold-boundary.yaml).
+
+## Deepening + tooling
+
+- [references/rn-2026-practices.md](references/rn-2026-practices.md) — New Architecture, Hermes, Expo vs bare, navigation/gestures (RN 0.85, 2026).
+- [references/anatomy.md](references/anatomy.md) — file map + scaffold; `scripts/new_screen.py` to generate a screen.
+- [assets/rn-mobile-checklist.md](assets/rn-mobile-checklist.md) — the review gate.
+- Versions pinned in [versions.json](versions.json) — `make skills-check-versions`.

templates/react-native/skills/react-native-mobile/assets/rn-mobile-checklist.md

@@ -0,0 +1,28 @@
+<!-- domain:MOBILE | layer:asset | ssot:false | updated:2026-06-04 -->
+# React Native (Bare/Expo) Review Checklist
+
+Run when starting, upgrading, or reviewing a React Native app.
+
+## Baseline
+- [ ] New Architecture (Fabric + TurboModules) on; Hermes engine on.
+- [ ] React Navigation 7 native-stack; param lists typed.
+- [ ] Expo (prebuild for native) unless a hard native requirement justifies bare.
+- [ ] `make skills-check-versions` — RN/Expo pins current.
+
+## Upgrade safety
+- [ ] Every third-party native lib supports the New Architecture before bumping.
+- [ ] Test on both iOS + Android (real devices/emulators), not one.
+
+## Quality (with react-native-patterns)
+- [ ] Lists virtualized (FlatList/FlashList), stable keys, memoized rows.
+- [ ] Reanimated worklets for interactive animation (UI thread).
+- [ ] Platform-specific code isolated (`.ios`/`.android` or `Platform.select`).
+- [ ] Accessibility labels/roles set (a11y).
+
+## Cross-cutting (mobile-fundamentals)
+- [ ] Navigation, deep links, push, offline-sync handled per mobile-fundamentals.
+- [ ] Secure storage for tokens (Keychain/Keystore) — security-mobile.
+
+## Release
+- [ ] EAS Update (OTA) for JS-only fixes; store build for native changes.
+- [ ] Maestro flow covers the core journey (end-to-end-testing).

templates/react-native/skills/react-native-mobile/references/anatomy.md

@@ -0,0 +1,140 @@
+<!-- domain:REACTNATIVE | layer:reference | ssot:true | updated:2026-04-29 -->
+# React Native Anatomy
+
+> P: Canonical file map and entity recipes for the React Native + Expo stack.
+> R: Adding any `.ts` / `.tsx` under `src/mobile/`, or routing a mobile task.
+> S: Working on web / backend / ai-service code.
+> N: [SKILL.md](../SKILL.md), [scaffold-boundary.yaml](../../../scaffold-boundary.yaml)
+
+> Nav: [Skill](../SKILL.md)
+
+---
+
+## 1. Boundary
+
+SSOT: [`src/templates/react-native/scaffold-boundary.yaml`](../../../scaffold-boundary.yaml).
+
+## 2. Layout map
+
+| Pattern | Location | Naming | Imports from | Description |
+|---|---|---|---|---|
+| Tab screen | `src/mobile/app/(tabs)/<name>.tsx` | `<name>.tsx` | `@/components`, `@/lib` | Tab-bar route |
+| Stack screen | `src/mobile/app/<name>.tsx` | `<name>.tsx` | `@/components`, `@/lib` | Outside tab bar |
+| Layout | `src/mobile/app/_layout.tsx` | `_layout.tsx` (literal) | `@/components` | Navigator |
+| Component | `src/mobile/components/<area>/<name>.tsx` | `kebab-case.tsx` | `@/lib` | Stateless preferred |
+| Hook | `src/mobile/lib/hooks/use<Name>.ts` | `useFooBar.ts` | none cross-area | Pure React hook |
+| API helper | `src/mobile/lib/api/<resource>.ts` | `<resource>.ts` | `@/shared/contracts` | Mapped errors |
+| Store slice | `src/mobile/store/<slice>.ts` | `<slice>.ts` | none cross-area | Zustand slice |
+| Sync action | `src/mobile/sync/<name>.ts` | `<name>.ts` | `@/store` | Offline queue |
+| Native bridge | `src/mobile/native/<name>.{ts,swift,kt}` | `<name>.<ext>` | none | ADR required |
+| Theme | `src/mobile/lib/theme/<name>.ts` | `<name>.ts` | `@/shared/contracts/design-tokens` | Re-export only |
+| Test | `src/mobile/<…>.test.{ts,tsx}` | `<file>.test.tsx` | source under test | Colocated |
+| E2E flow | `src/mobile/e2e/<flow>.yaml` | `<flow>.yaml` | none | Maestro |
+| Asset | `src/mobile/assets/<kind>/<name>.<ext>` | kebab-case | none | Images, fonts |
+
+## 3. Entity recipes
+
+### Add a new component
+
+- **Trigger:** "add a Button / Card / Avatar".
+- **Files:**
+  1. `src/mobile/components/<area>/<name>.tsx`
+  2. `src/mobile/components/<area>/<name>.test.tsx`
+- **Steps:**
+  1. Stateless default; lift state to the screen.
+  2. Style via StyleSheet.create OR utility classes (NativeWind) — pick one per stack.
+  3. Add `accessibilityRole` / `accessibilityLabel` for every Pressable / Touchable.
+  4. Author colocated test (Given/When/Then).
+
+### Add a new screen
+
+- **Trigger:** "add a profile screen", "new screen for X".
+- **Files:**
+  1. `src/mobile/app/(tabs)/<name>.tsx` OR `src/mobile/app/<name>.tsx`
+  2. `src/mobile/app/<name>.test.tsx`
+- **Steps:**
+  1. Decide tab vs stack — tab if user spends time, stack if modal/detail.
+  2. Implement three-state async UI (loading / error / empty / content).
+  3. Wire navigation via `router.push('<name>')`; type params in `src/mobile/lib/navigation/types.ts`.
+  4. Add screen-level analytics event on mount.
+- **Generator:** [`src/scripts/new_screen.py`](../scripts/new_screen.py).
+
+### Add a new hook
+
+- **Trigger:** "extract into useFoo".
+- **Files:**
+  1. `src/mobile/lib/hooks/use<Name>.ts`
+  2. `src/mobile/lib/hooks/use<Name>.test.ts`
+- **Steps:**
+  1. Hook MUST start with `use`.
+  2. Storage layered on `src/mobile/lib/storage.ts` — never `AsyncStorage` direct.
+  3. Memoize stable values; expose typed return.
+
+### Add a new API helper
+
+- **Trigger:** "wrap GET /users", "call X endpoint".
+- **Files:**
+  1. `src/mobile/lib/api/<resource>.ts`
+  2. `src/mobile/lib/api/<resource>.test.ts`
+- **Steps:**
+  1. `fetch` wrapped by `src/mobile/lib/api/_client.ts` (timeout, retry, base URL).
+  2. Validate response against `src/shared/contracts/<resource>.ts`.
+  3. Map errors to `<ResourceError>` envelope.
+  4. Auth tokens read from secure storage at call time — never module scope.
+
+### Add a new store slice
+
+- **Trigger:** "share state across screens".
+- **Files:**
+  1. `src/mobile/store/<slice>.ts`
+  2. `src/mobile/store/<slice>.test.ts`
+- **Steps:**
+  1. Default Zustand; one slice per concern.
+  2. Selectors exported alongside slice — components subscribe to selectors.
+  3. Persisted slices use `src/mobile/store/_persist.ts` middleware.
+
+### Add a new sync action
+
+- **Trigger:** "log medication offline", "queue this mutation".
+- **Files:**
+  1. `src/mobile/sync/<action>.ts`
+  2. `src/mobile/sync/<action>.test.ts`
+- **Steps:**
+  1. Define `<Action>Payload` type colocated.
+  2. Implement `enqueue()` and `apply()`.
+  3. Test with fake offline drainer.
+  4. Conflict surfaces via `<ConflictModal />`; never silently drop.
+
+### Add a new test
+
+- **Trigger:** every component / hook / helper / slice / action requires colocated test.
+- **Files:**
+  1. `<source>.test.{ts,tsx}` — same dir as source.
+- **Steps:**
+  1. Jest + `@testing-library/react-native`.
+  2. Given/When/Then; happy + ≥1 failure path.
+
+## 4. Conventions
+
+#### Naming
+
+- Files: `kebab-case.{ts,tsx}` — exception: Expo Router special names (`_layout.tsx`, `(tabs)/index.tsx`, `[id].tsx`).
+- Components: `PascalCase` exported symbol.
+- Hooks: `useCamelCase` symbol; file `useCamelCase.ts`.
+- Store slices: `<noun>Slice` symbol; file `<slice>.ts`.
+- Sync actions: `<verb><Noun>Action` symbol; file `<verb>-<noun>.ts`.
+- Constants: `SCREAMING_SNAKE_CASE`.
+
+#### Test colocation
+
+Colocated. `medication/dose-card.tsx` ⇄ `medication/dose-card.test.tsx`. E2E flows under `src/mobile/e2e/<flow>.yaml`. No `__tests__/` mirrors.
+
+#### Dependency rules
+
+- ✓ `src/mobile/` may import from `src/shared/`, `src/shared/types/`, `src/shared/contracts/`.
+- ✗ `src/mobile/` may NOT import from `src/frontend/`, `src/backend/`, `src/ai-service/`.
+- ✓ `src/mobile/components/` may import from `src/mobile/lib/` and `src/mobile/store/`.
+- ✗ `src/mobile/lib/` may NOT import from `src/mobile/components/` (one-way).
+- ✗ `src/mobile/store/` may NOT import from `src/mobile/components/` (state below view).
+- ✓ `src/mobile/sync/` may import from `src/mobile/store/` and `src/mobile/lib/api/`.
+- ✗ Worklets may NOT call JS-thread APIs (`fetch`, `console.log`) — bridge via `runOnJS`.

templates/react-native/skills/react-native-mobile/references/rn-2026-practices.md

@@ -0,0 +1,54 @@
+<!-- domain:MOBILE | layer:reference | ssot:true | updated:2026-06-04 -->
+# React Native Practices (2026) — New Architecture, Hermes, Expo
+
+> P: The current RN baseline (New Architecture default, Hermes, Expo SDK 56) and what it changes.
+> R: Starting or upgrading a React Native app; choosing bare vs Expo.
+> S: List/render performance — that's the react-native-patterns skill's list-performance reference.
+> N: [SKILL.md](../SKILL.md), [rn-mobile-checklist.md](../assets/rn-mobile-checklist.md)
+
+> Nav: [Skill](../SKILL.md)
+
+Baseline as of 2026: React Native 0.85.x, React 19.2, Hermes (V1) default, the
+**New Architecture** (Fabric + TurboModules + JSI) default. Expo SDK 56 wraps
+this. Pins in [versions.json](../versions.json).
+
+## Expo vs bare — pick deliberately
+
+| | Expo (managed/prebuild) | Bare RN |
+|---|---|---|
+| native modules | config plugins + prebuild | edit ios/android directly |
+| OTA updates | EAS Update built-in | roll your own |
+| build | EAS Build (cloud) | local Xcode/Gradle |
+| use when | most apps — faster, less native pain | deep native customization needed |
+
+Default to Expo (with prebuild for native modules) unless you have a hard native
+requirement — it removes most of the iOS/Android toolchain pain. Cross-platform
+concerns (push, deep links, offline) are owned by
+[mobile-fundamentals](../../../core/skills/mobile-fundamentals/SKILL.md).
+
+## New Architecture implications
+
+- **TurboModules** — native modules load lazily via JSI (no bridge serialization);
+  faster startup. Codegen from a TS spec defines the native interface.
+- **Fabric** — the new renderer; concurrent-React-friendly, synchronous layout
+  reads when needed. Most app code doesn't change, but old native UI libraries may
+  need a Fabric-compatible version.
+- When upgrading, the long pole is third-party native libraries — check each
+  supports the New Architecture before bumping.
+
+## Navigation, gestures, animation
+
+- **React Navigation 7** — native-stack (uses platform navigators) for native feel
+  and performance; type the param lists.
+- **Reanimated 3** + **Gesture Handler** — animations/gestures run on the UI
+  thread (worklets), so a busy JS thread won't drop them. Prefer to the legacy
+  `Animated` API for anything interactive.
+- **FlashList** (Shopify) over `FlatList` for large lists.
+
+## Quality + release
+
+Hermes gives faster startup + lower memory — keep it on. Profile with the React
+DevTools profiler / Flipper / `react-native-performance`. Ship via EAS (Expo) or
+Fastlane (bare); use OTA updates (EAS Update) for JS-only fixes, a store build for
+native changes. Test journeys with Maestro
+([end-to-end-testing](../../../core/skills/end-to-end-testing/SKILL.md)).