AGENTS.md

Guidance for coding agents working on nk304 apps/mobile. The app shares product contracts with web-next but has native routing, storage, biometrics, file handling, and build constraints.

Project Overview

apps/mobile is an Expo Router React Native app. It uses Expo SDK 56, React Native, React Query, Zustand, Socket.IO client, secure storage, local authentication, Expo file/document/image APIs, and shared workspace packages. It includes auth, public order flows, admin data screens, reports, tickets, files, memos, calendar, assistant, inventory, apartment/project workspaces, developer API keys, system status, and Open Chat screens.

Mobile work should preserve native constraints rather than copying web assumptions. Focus on safe API adapters, query hooks, native file handling, biometric/session behavior, and transport-crypto parity with the backend.

Project Map

• app/ contains Expo Router routes, auth grouping, protected app grouping, public checkout, order lookup, invite, payment, and workspace detail pages.
• src/ui/theme.ts and src/ui/primitives.tsx define mobile-specific visual primitives.
• src/lib/api/ contains the base client, origin handling, and request-body behavior.
• src/lib/auth/ contains session state, secure-store persistence, public-screen behavior, and biometric auth.
• src/lib/transport-crypto/ contains envelope, HTTP, socket, session, and registry logic.
• src/lib/realtime/ contains Open Chat, global, and inventory socket clients.
• src/lib// folders pair API calls, query builders, hooks, and focused tests for admin, assistant, audit, calendar, developer keys, files, inventory, notices, reports, settings, support, system, tickets, workspaces, and Open Chat.
• src/features/ contains cross-route feature shells such as session bootstrap and Open Chat room panels.

Setup Commands

Use workspace commands from the monorepo root:

bashpnpm --filter @nk304/mobile run start
pnpm --filter @nk304/mobile run android
pnpm --filter @nk304/mobile run ios
pnpm --filter @nk304/mobile run doctor
pnpm --filter @nk304/mobile run test
pnpm --filter @nk304/mobile run typecheck
pnpm --filter @nk304/mobile run build:deps

Preview and production native builds are defined in package scripts. Before running them, review their environment expectations locally and do not publish real service origins or upload endpoints.

Change Rules For Agents

• Add or update a focused src/lib//*query.test.mts or API contract test when changing a mobile data path.
• Preserve secure storage and biometric flows in src/lib/auth; do not replace them with web-only storage semantics.
• Keep transport crypto changes mirrored against backend expectations and covered by registry.test.mts.
• Do not introduce direct ad hoc fetches from screens; add domain API/query helpers first.
• Keep native file downloads and sharing inside the file helper modules. Mobile filesystem behavior is different from web protected download behavior.
• Keep Expo Router route names and grouping stable unless the task explicitly changes navigation.
• Prefer existing mobile primitives and theme tokens instead of importing web CSS ideas.

Verification

The package test script is intentionally broad and covers many domain query helpers:

bashpnpm --filter @nk304/mobile run test
pnpm --filter @nk304/mobile run typecheck

For targeted work, run the nearest Node test file directly:

bashpnpm --filter @nk304/mobile exec node --test src/lib/<domain>/<target>.test.mts

For dependency updates or native integration changes, also run:

bashpnpm --filter @nk304/mobile run doctor

Security Notes

Do not log access tokens, refresh tokens, CSRF values, transport session material, biometric decisions, local file URIs, or platform upload credentials. Use placeholders in documentation and fixtures. Keep protected calls behind the shared API and transport-crypto layers.

PR Checklist

• New data access has a domain helper, query hook, and test.
• Auth/session changes cover public-screen and biometric behavior.
• Transport crypto changes include registry or envelope tests.
• Native file or image handling stays inside mobile helper modules.
• Typecheck and relevant tests pass before handoff.