update

packages/apn-relay/AGENTS.md

@@ -0,0 +1,106 @@
+# apn-relay Agent Guide
+
+This file defines package-specific guidance for agents working in `packages/apn-relay`.
+
+## Scope And Precedence
+
+- Follow root `AGENTS.md` first.
+- This file provides stricter package-level conventions for relay service work.
+- If future local guides are added, closest guide wins.
+
+## Project Overview
+
+- Minimal APNs relay service (Hono + Bun + PlanetScale via Drizzle).
+- Core routes:
+  - `GET /health`
+  - `GET /`
+  - `POST /v1/device/register`
+  - `POST /v1/device/unregister`
+  - `POST /v1/event`
+
+## Commands
+
+Run all commands from `packages/apn-relay`.
+
+- Install deps: `bun install`
+- Start relay locally: `bun run dev`
+- Typecheck: `bun run typecheck`
+- DB connectivity check: `bun run db:check`
+
+## Build / Test Expectations
+
+- There is no dedicated package test script currently.
+- Required validation for behavior changes:
+  - `bun run typecheck`
+  - `bun run db:check` when DB/env changes are involved
+  - manual endpoint verification against `/health`, `/v1/device/register`, `/v1/event`
+
+## Single-Test Guidance
+
+- No single-test command exists for this package today.
+- For focused checks, run endpoint-level manual tests against a local dev server.
+
+## Code Style Guidelines
+
+### Formatting / Structure
+
+- Keep handlers compact and explicit.
+- Prefer small local helpers for repeated route logic.
+- Avoid broad refactors when a targeted fix is enough.
+
+### Types / Validation
+
+- Validate request bodies with `zod` at route boundaries.
+- Keep payload and DB row shapes explicit and close to usage.
+- Avoid `any`; narrow unknown input immediately after parsing.
+
+### Naming
+
+- Follow existing concise naming in this package (`reg`, `unreg`, `evt`, `row`, `key`).
+- For DB columns, keep snake_case alignment with schema.
+
+### Error Handling
+
+- Return clear JSON errors for invalid input.
+- Keep handler failures observable via `app.onError` and structured logs.
+- Do not leak secrets in responses or logs.
+
+### Logging
+
+- Log delivery lifecycle at key checkpoints:
+  - registration/unregistration attempts
+  - event fanout start/end
+  - APNs send failures and retries
+- Mask sensitive values; prefer token suffixes and metadata.
+
+### APNs Environment Rules
+
+- Keep APNs env explicit per registration (`sandbox` / `production`).
+- For `BadEnvironmentKeyInToken`, retry once with flipped env and persist correction.
+- Avoid infinite retry loops; one retry max per delivery attempt.
+
+## Database Conventions
+
+- Schema is in `src/schema.sql.ts`.
+- Keep table/column names snake_case.
+- Maintain index naming consistency with existing schema.
+- For upserts, update only fields required by current behavior.
+
+## API Behavior Expectations
+
+- `register`/`unregister` must be idempotent.
+- `event` should return success envelope even when no devices are registered.
+- Delivery logs should capture per-attempt result and error payload.
+
+## Operational Notes
+
+- Ensure `APNS_PRIVATE_KEY` supports escaped newline format (`\n`) and raw multiline.
+- Validate that `APNS_DEFAULT_BUNDLE_ID` matches mobile app bundle identifier.
+- Avoid coupling route behavior to deployment platform specifics.
+
+## Before Finishing
+
+- Run `bun run typecheck`.
+- If DB/env behavior changed, run `bun run db:check`.
+- Manually exercise affected endpoints.
+- Confirm logs are useful and secret-safe.

packages/mobile-voice/AGENTS.md

@@ -0,0 +1,103 @@
+# mobile-voice Agent Guide
+
+This file defines package-specific guidance for agents working in `packages/mobile-voice`.
+
+## Scope And Precedence
+
+- Follow root `AGENTS.md` first.
+- This file overrides root guidance for this package when rules conflict.
+- If additional local guides are added later, treat the closest guide as highest priority.
+
+## Project Overview
+
+- Expo + React Native app for voice dictation and OpenCode session monitoring.
+- Uses native modules (`react-native-executorch`, `react-native-audio-api`, `expo-notifications`, `expo-camera`).
+- Development builds are required for native module changes.
+
+## Commands
+
+Run all commands from `packages/mobile-voice`.
+
+- Install deps: `bun install`
+- Start Metro: `bun run start`
+- Start dev client server (recommended): `bunx expo start --dev-client --clear --host lan`
+- iOS run: `bun run ios`
+- Android run: `bun run android`
+- Lint: `bun run lint`
+- Expo doctor: `bunx expo-doctor`
+- Dependency compatibility check: `bunx expo install --check`
+- Export bundle smoke test: `bunx expo export --platform ios --clear`
+
+## Build / Verification Expectations
+
+- For JS-only changes: run `bun run lint` and verify app behavior via dev client.
+- For native dependency/config/plugin changes: rebuild dev client via EAS before validation.
+- If notifications/camera/audio behavior changes, verify on a physical iOS device.
+- Do not claim a fix unless you validated in Metro logs and app runtime behavior.
+
+## Single-Test Guidance
+
+- This package currently has no dedicated unit test script.
+- Use targeted validation commands instead:
+  - `bun run lint`
+  - `bunx expo export --platform ios --clear`
+  - manual runtime test in dev client
+
+## Code Style And Patterns
+
+### Formatting / Structure
+
+- Preserve existing style (`semi: false`, concise JSX, stable import grouping).
+- Keep UI changes localized; avoid large architectural rewrites.
+- Avoid unrelated formatting churn.
+
+### Types
+
+- Avoid `any`; prefer local type aliases for component state and network payloads.
+- Keep exported/shared boundaries typed explicitly.
+- Use discriminated unions for UI modes/status where practical.
+
+### Naming
+
+- Prefer short, readable names consistent with nearby code.
+- Keep naming aligned with existing app state keys (`serverDraftURL`, `monitorStatus`, etc.).
+
+### Error Handling / Logging
+
+- Fail gracefully in UI (alerts, disabled actions, fallback text).
+- Log actionable diagnostics for runtime workflows:
+  - server health checks
+  - relay registration attempts
+  - notification token lifecycle
+- Never log secrets or full APNs tokens.
+
+### Network / Relay Integration
+
+- Normalize and validate URLs before storing server configs.
+- Keep relay registration idempotent.
+- Guard duplicate scan/add flows to avoid repeated server entries.
+
+### Notifications / APNs
+
+- Distinguish sandbox vs production token environments correctly.
+- On registration changes, ensure old token unregister flow remains intact.
+- Treat permission failures as non-fatal and degrade to foreground monitoring when needed.
+
+## Native-Module Safety
+
+- If adding a native module, ensure it is in `package.json` with SDK-compatible version.
+- Rebuild dev client after native module additions/changes.
+- For optional native capability usage, prefer runtime fallback paths instead of hard crashes.
+
+## Common Pitfalls
+
+- Black screen + "No script URL provided" often means stale dev client binary.
+- `expo-doctor` duplicate module warnings may appear in Bun workspaces; prioritize runtime verification.
+- `expo lint` may auto-generate `eslint.config.js`; do not commit accidental generated config unless requested.
+
+## Before Finishing
+
+- Run `bun run lint`.
+- If behavior could break startup, run `bunx expo export --platform ios --clear`.
+- Confirm no accidental config side effects were introduced.
+- Summarize what was verified on-device vs only in tooling.

packages/mobile-voice/src/app/index.tsx

@@ -557,7 +557,7 @@ export default function DictationScreen() {
           lastWaveformCommitRef.current = now
         }
 
-        // Always use the latest model ref to avoid stale closure
+        // Always use the latest model ref to avoid stale closure.
         modelRef.current.streamInsert(samples)
       },
     )

packages/mobile-voice/tsconfig.json

@@ -3,18 +3,9 @@
   "compilerOptions": {
     "strict": true,
     "paths": {
-      "@/*": [
-        "./src/*"
-      ],
-      "@/assets/*": [
-        "./assets/*"
-      ]
+      "@/*": ["./src/*"],
+      "@/assets/*": ["./assets/*"]
     }
   },
-  "include": [
-    "**/*.ts",
-    "**/*.tsx",
-    ".expo/types/**/*.ts",
-    "expo-env.d.ts"
-  ]
+  "include": ["**/*.ts", "**/*.tsx", ".expo/types/**/*.ts", "expo-env.d.ts"]
 }