From 6bcef323be74bd75468ed9c9dc79d3b5c0f35393 Mon Sep 17 00:00:00 2001
From: space <space@reversed.dev>
Date: Wed, 24 Jun 2026 17:44:07 +0200
Subject: [PATCH] docs: add CLAUDE.md with architecture and command reference

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 CLAUDE.md | 69 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 69 insertions(+)

diff --git a/CLAUDE.md b/CLAUDE.md
index 43c994c..078aeeb 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1 +1,70 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
 @AGENTS.md
+
+## Commands
+
+```bash
+npx expo start          # Start Expo dev server (scan QR with Expo Go)
+npx expo start --android
+npx expo start --ios
+npx expo start --web
+
+eas build --profile preview --platform android   # Build APK via EAS
+eas build --profile production --platform android
+```
+
+There is no test suite or lint script configured in package.json.
+
+## Architecture
+
+This is an Expo SDK 56 app that monitors AI service usage limits for **Codex CLI** and **Claude.ai**. It fetches usage data from their private REST APIs using credentials the user provides.
+
+### Navigation (Expo Router v3)
+
+```
+app/index.tsx              → checks onboarding state, redirects
+app/onboarding/            → stack: welcome → codex → claude → done
+app/(tabs)/
+  _layout.tsx              → bottom tab navigator (4 tabs)
+  index.tsx                → Dashboard: both services side-by-side
+  codex.tsx                → Codex CLI detailed view
+  claude.tsx               → Claude.ai detailed view (not yet in git)
+  settings.tsx             → Settings (not yet in git)
+```
+
+### Data Flow
+
+Each service follows the same pattern:
+
+1. **Hook** (`hooks/useCodexUsage.ts`, `hooks/useClaudeUsage.ts`) — manages auth + usage state, persists credentials to SecureStore, exposes `refresh()` / `clear()`.
+2. **API module** (`lib/api/codexApi.ts`, `lib/api/claudeApi.ts`) — thin fetch wrappers with no side effects.
+3. **Screen** — calls the hook, renders `ServiceStatusCard` or the detailed usage UI.
+
+### Credential Storage
+
+All credentials live in `expo-secure-store` (never AsyncStorage). Keys:
+
+- `codex_auth` — serialized `CodexAuth` object (Bearer token + optional account ID), imported from the user's `auth.json` file via `expo-document-picker`.
+- `claude_session_key` — cookie value used as `Cookie: sessionKey=…` on claude.ai API calls.
+
+`TOKEN_EXPIRED` errors automatically clear the stored credential and prompt re-entry.
+
+### Styling
+
+NativeWind v4 (Tailwind CSS for React Native). Brand colors:
+- Codex: `#10a37f` (teal)
+- Claude: `#d97706` (amber)
+
+Use Tailwind utility classes on all components. Dark mode is supported via `dark:` variants.
+
+### Key Types
+
+- `lib/types/codex.ts` — `CodexAuth`, `CodexUsageResponse`, `UsageWindow`
+- `lib/types/claude.ts` — `ClaudeOrg`, `ClaudeUsageResponse`, `ClaudeWindowUsage`
+
+### Path Alias
+
+`@/` maps to the repo root (configured in `tsconfig.json`). Use `@/components/...`, `@/lib/...`, `@/hooks/...` everywhere.