feat: add UI components, CI workflows, offline docs, and feature types

- Add shared UI components: Activity, ErrorBoundary, FocusAwareStatusBar, ScreenHeader, SuspenseBoundary, ThemedStatusBar
- Add feature types/index.ts for auth, home, settings, user (consolidate domain types)
- Add CI workflow, Maestro smoke tests, CODE_OF_CONDUCT
- Add docs: OFFLINE.md, OPERATIONS.md, development.md
- Add navigation persistence, NavigationRoot, SVG tab icons
- Add Sentry monitoring stub, ensure-env/wait-for-device scripts
- Update theme tokens, Button, ScreenWrapper, IconSvg, interceptors
- Update AGENTS.md, CLAUDE.md, rules, README, CONTRIBUTING, CHANGELOG

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: maximcoding

.claude/CLAUDE.md

@@ -1,6 +1,6 @@
-# CLAUDE.md — React Native Project
+# CLAUDE.md — React Native Starter
 
-**Claude Code context** for this repo. **Canonical agent rules:** [AGENTS.md](../AGENTS.md) at the repo root (structure, don’ts, “when adding”). This file duplicates stack/commands for Claude; on conflict, prefer **AGENTS.md** and the codebase.
+**Claude Code context** for this repo. **Canonical agent rules:** [AGENTS.md](../AGENTS.md) (structure, don’ts, “when adding”, documentation map). This file adds stack/commands for Claude; on conflict, prefer **AGENTS.md** and the codebase. **Path-scoped rules:** [.claude/rules/](rules/) (`config`, `features`, `shared-components`, `shared-services`).
 
 ## Project Overview
 
@@ -16,7 +16,7 @@ Production-oriented React Native starter for mobile apps: feature-first architec
 - **Backend/API:** `src/shared/services/api/`
 - **Auth:** interceptors in shared API; session in `src/session/`
 - **Testing:** Jest (react-native preset), react-test-renderer; `jest.config.js`, `jest.setup.js`
-- **CI/CD:** GitHub Actions — `.github/workflows/android-ci.yml`, `.github/workflows/ios-ci.yml`; Fastlane mentioned in docs for Play/TestFlight
+- **CI/CD:** GitHub Actions — `.github/workflows/ci.yml` (PR checks), `.github/workflows/android-ci.yml`, `.github/workflows/ios-ci.yml` (manual); Fastlane optional — not in this template (add under `fastlane/` for store releases; see [docs/OPERATIONS.md](../docs/OPERATIONS.md#github-actions))
 
 ## Project Structure
 
@@ -35,12 +35,13 @@ src/
 │   ├── theme/
 │   ├── utils/
 │   └── types/
-├── features/<feature>/
+├── features/<feature>/    # per slice: types/, screens/, components/, hooks/, services/, api/, navigation/
 assets/
 scripts/
+ios/, android/     # native projects (Fastlane optional — add fastlane/ when needed)
 ```
 
-Feature services live under `src/features/<feature>/services/`; features own their screens, components, hooks, models (Zod + mappers), and api (query keys).
+Feature code lives under `src/features/<feature>/`: `screens/`, `components/`, `hooks/`, **`types/`** (interfaces + type aliases), `services/` (Zod + mappers + service modules), `api/keys.ts`, `navigation/param-list.ts`.
 
 ## Key Commands
 
@@ -49,7 +50,7 @@ Feature services live under `src/features/<feature>/services/`; features own the
 npm install
 
 # Metro
-npm run start
+npm start
 
 # Run
 npm run ios
@@ -86,7 +87,7 @@ npm run android:build:release   # Android
 - **Component pattern:** Functional components only; no class components.
 - **File naming:** PascalCase for components (e.g. `ScreenWrapper.tsx`); camelCase or kebab for utils/services (e.g. `navigation-helpers.ts`, `auth.service.ts`).
 - **Exports:** Named exports for components/hooks; screens follow existing files.
-- **API layer:** `src/shared/services/api/`; feature services in `features/<name>/services/`; Zod validation.
+- **API layer:** `src/shared/services/api/`; feature services in `features/<name>/services/`; domain types in `features/<name>/types/`; Zod validation.
 - **Error handling:** `src/shared/utils/normalize-error.ts`, `toast.ts`.
 - **Navigation typing:** `src/navigation/routes.ts`.
 
@@ -137,18 +138,25 @@ npm run android:build:release   # Android
 
 - **Navigation & route constants:** `src/navigation/` (`routes.ts`, stacks, tabs).
 - **Theme & query client infra:** `src/shared/theme/`, `src/shared/services/api/query/`.
-- **Feature API logic:** `src/features/<name>/services/`.
+- **Feature API logic:** `src/features/<name>/services/`; **feature types:** `src/features/<name>/types/`.
 
 ## Docs
 
-| Audience | Doc |
-|----------|-----|
-| Humans | [README.md](../README.md) |
-| Cursor / agents | [AGENTS.md](../AGENTS.md) |
-| Claude Code | This file |
-| Extended guidelines | [docs/MOBILE_E2E_GUIDE_additions.md](../docs/MOBILE_E2E_GUIDE_additions.md) |
-| Backlog | [docs/TODO.md](../docs/TODO.md) |
-| Versions | [CHANGELOG.md](../CHANGELOG.md) |
+Same **topic-to-doc** matrix as [AGENTS.md#documentation-map](../AGENTS.md#documentation-map) (canonical). Root [README.md](../README.md) is the only project README; do not duplicate the full table there.
+
+| Doc | Role |
+|-----|------|
+| [README.md](../README.md) | Landing: quick start, setup, env, links |
+| [AGENTS.md](../AGENTS.md) | Agents/humans: rules, where code lives, doc map |
+| This file | Claude Code stack reference + commands |
+| [docs/development.md](../docs/development.md) | Hooks, architecture, icons, i18n, npm scripts |
+| [docs/production-guidelines.md](../docs/production-guidelines.md) | Production patterns and checklists |
+| [docs/OPERATIONS.md](../docs/OPERATIONS.md) | Sentry, Maestro, CI, OTA, publishing |
+| [docs/OFFLINE.md](../docs/OFFLINE.md) | Offline stack |
+| [docs/permissions-bare-rn.md](../docs/permissions-bare-rn.md) | Permission catalog |
+| [docs/TODO.md](../docs/TODO.md) | Roadmap / backlog |
+| [CONTRIBUTING.md](../CONTRIBUTING.md) | PRs, changelog, quality checks, security reporting |
+| [CHANGELOG.md](../CHANGELOG.md) | Version history |
 
 ## MCP Servers
 
@@ -157,6 +165,7 @@ Figma MCP is configured for design-to-code (get_design_context, etc.). Use for F
 ## Common Pitfalls — Do NOT
 
 - Do NOT add new npm packages without asking/RFC.
+- Do NOT change any package version in `package.json` or `package-lock.json`. Fix consuming code to match the installed version instead.
 - Do NOT use `fetch`; use project HTTP/transport only.
 - Do NOT put feature logic in `src/shared/components/ui/` or `src/shared/stores/`.
 - Do NOT use raw colors/spacing/fonts in UI; use theme tokens.

.claude/agents/documentation-expert.md

@@ -0,0 +1,49 @@
+---
+name: documentation-expert
+description: Use this agent to create, improve, and maintain project documentation. Specializes in technical writing, documentation standards, and generating documentation from code. Examples: <example>Context: A user wants to add documentation to a new feature. user: 'Please help me document this new API endpoint.' assistant: 'I will use the documentation-expert to generate clear and concise documentation for your API.' <commentary>The documentation-expert is the right choice for creating high-quality technical documentation.</commentary></example> <example>Context: The project's documentation is outdated. user: 'Can you help me update our README file?' assistant: 'I'll use the documentation-expert to review and update the README with the latest information.' <commentary>The documentation-expert can help improve existing documentation.</commentary></example>
+color: cyan
+---
+
+You are a Documentation Expert specializing in technical writing, documentation standards, and developer experience. Your role is to create, improve, and maintain clear, concise, and comprehensive documentation for software projects.
+
+**This repository:** Canonical doc matrix is [AGENTS.md](../../AGENTS.md#documentation-map). The root [README.md](../../README.md) is the only project README—do not reintroduce a second index under `docs/`. Path-scoped authoring rules live in [.claude/rules/](../rules/).
+
+Your core expertise areas:
+- **Technical Writing**: Writing clear and easy-to-understand explanations of complex technical concepts.
+- **Documentation Standards**: Applying documentation standards and best practices, such as the "Diátaxis" framework or "Docs as Code".
+- **API Documentation**: Generating and maintaining API documentation using standards like OpenAPI/Swagger.
+- **Code Documentation**: Writing meaningful code comments and generating documentation from them using tools like JSDoc, Sphinx, or Doxygen.
+- **User Guides and Tutorials**: Creating user-friendly guides and tutorials to help users get started with the project.
+
+## When to Use This Agent
+
+Use this agent for:
+- Creating or updating project documentation (e.g., README, CONTRIBUTING, USAGE).
+- Writing documentation for new features or APIs.
+- Improving existing documentation for clarity and completeness.
+- Generating documentation from code comments.
+- Creating tutorials and user guides.
+
+## Documentation Process
+
+1. **Understand the audience**: Identify the target audience for the documentation (e.g., developers, end-users).
+2. **Gather information**: Collect all the necessary information about the feature or project to be documented.
+3. **Structure the documentation**: Organize the information in a logical and easy-to-follow structure.
+4. **Write the content**: Write the documentation in a clear, concise, and professional style.
+5. **Review and revise**: Review the documentation for accuracy, clarity, and completeness.
+
+## Documentation Checklist
+
+- [ ] Is the documentation clear and easy to understand?
+- [ ] Is the documentation accurate and up-to-date?
+- [ ] Is the documentation complete?
+- [ ] Is the documentation well-structured and easy to navigate?
+- [ ] Is the documentation free of grammatical errors and typos?
+
+## Output Format
+
+Provide well-structured Markdown files with:
+- **Clear headings and sections**.
+- **Code blocks with syntax highlighting**.
+- **Links to relevant resources**.
+- **Images and diagrams where appropriate**.

.claude/rules/config.md

@@ -2,6 +2,8 @@
 globs: src/config/**
 ---
 
+Global rules: [AGENTS.md](../../AGENTS.md). Claude stack summary: [CLAUDE.md](../CLAUDE.md).
+
 # Rules — config
 
 `src/config/` is the **environment boundary**: everything that varies between dev / staging / prod lives here and nowhere else.

.claude/rules/features.md

@@ -2,6 +2,8 @@
 globs: src/features/**
 ---
 
+Global rules: [AGENTS.md](../../AGENTS.md). Claude stack summary: [CLAUDE.md](../CLAUDE.md).
+
 # Rules — features
 
 Each feature (`auth`, `home`, `settings`, `user`, …) is a self-contained vertical slice.
@@ -12,6 +14,8 @@ src/features/<name>/
   screens/              # Screen components (route leaf nodes)
   components/           # Feature-private UI
   hooks/                # Feature-private React hooks (useLoginMutation, useMeQuery, …)
+  types/                # Interfaces and type aliases (domain models; re-export schema types if useful)
+    index.ts            # Barrel — import from @/features/<name>/types
   services/             # API schemas (Zod) + mappers + service functions
   api/
     keys.ts             # React Query key factory

.claude/rules/shared-components.md

@@ -2,6 +2,8 @@
 globs: src/shared/components/**
 ---
 
+Global rules: [AGENTS.md](../../AGENTS.md). Claude stack summary: [CLAUDE.md](../CLAUDE.md).
+
 # Rules — shared/components
 
 Components here are **stateless, themed primitives**. They form the UI kit used across all features.

.claude/rules/shared-services.md

@@ -2,6 +2,8 @@
 globs: src/shared/services/**
 ---
 
+Global rules: [AGENTS.md](../../AGENTS.md). Claude stack summary: [CLAUDE.md](../CLAUDE.md).
+
 # Rules — shared/services
 
 Infrastructure-level data layer. Split into two sub-trees:
@@ -28,5 +30,5 @@ shared/services/
 
 ## Must not
 - Do not import from `src/features/**` — this layer is feature-agnostic.
-- Do not put business logic or domain models here. Domain logic belongs in `src/features/<name>/services/`.
+- Do not put business logic or domain models here. Domain logic belongs in `src/features/<name>/services/`; domain **interfaces and type aliases** belong in `src/features/<name>/types/`.
 - Do not use Zustand stores inside this layer — pass data up via return values or callbacks.

.env.example

@@ -1,5 +1,14 @@
 API_URL=http://localhost:3000
+# Dev: enables mock REST + pre-fills login (demo@example.com / password) on Auth screen
+USE_MOCK_API=true
+
+# Optional: Sentry (https://docs.sentry.io/platforms/react-native/)
 SENTRY_DSN=
+# Set to 1 to send events from __DEV__ builds (default: off)
+SENTRY_ENABLE_IN_DEV=0
+# 0–1, performance sampling in production (0 = traces off)
+SENTRY_TRACES_SAMPLE_RATE=0
+
+# OTA / CodePush-style keys — see docs/OPERATIONS.md#over-the-air-updates (optional)
 CODEPUSH_KEY_IOS=
-CODEPUSH_KEY_ANDROID=
-USE_MOCK_API=true
+CODEPUSH_KEY_ANDROID=

.github/CODE_OF_CONDUCT.md

@@ -0,0 +1,30 @@
+# Contributor Covenant Code of Conduct
+
+## Our pledge
+
+We pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+## Our standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Accepting constructive criticism gracefully
+- Focusing on what is best for the community
+
+Examples of unacceptable behavior:
+
+- Harassment, trolling, or insulting comments
+- Public or private harassment
+- Publishing others’ private information without permission
+
+## Enforcement
+
+Project maintainers may remove, edit, or reject contributions that violate this code. Violations may result in a temporary or permanent ban from the project spaces.
+
+Reports may be sent to the maintainers via GitHub (e.g. direct message or issue, per project preference). Replace this section with a dedicated contact if you run a public fork.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1.

.github/workflows/android-ci.yml

@@ -1,5 +1,6 @@
 name: Android CI Build
 
+# Manual native release build (template). PR quality checks live in ci.yml.
 on:
   workflow_dispatch:
 
@@ -14,10 +15,11 @@ jobs:
       - name: Setup Node
         uses: actions/setup-node@v4
         with:
-          node-version: 18
+          node-version: '20'
+          cache: npm
 
-      - name: Install packages
-        run: npm install
+      - name: Install dependencies
+        run: npm ci
 
       - name: Install JDK
         uses: actions/setup-java@v4

.github/workflows/ci.yml

@@ -0,0 +1,36 @@
+name: CI
+
+on:
+  push:
+    branches: [master, main]
+  pull_request:
+    branches: [master, main]
+
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Biome
+        run: npm run lint
+
+      - name: Typecheck
+        run: npx tsc --noEmit
+
+      - name: Unit tests
+        run: npm test
+
+      - name: Check icons registry
+        run: npm run check:icons
+
+      - name: Check import paths
+        run: npm run check:imports