# AGENTS.md

This file configures Codex behavior for the repository root (`/Users/craigvandergalien/Documents/GitHub/lichun`).

## Scope And Precedence

- Applies to the whole monorepo by default.
- `ios/AGENTS.md` overrides this file for work inside `ios/`.
- `android/AGENTS.md` overrides this file for work inside `android/`.

## Repository Map

- `server/`: Active Node.js/TypeScript WebSocket backend.
- `ws/`: Legacy Python WebSocket backend (reference/maintenance only).
- `ios/`: SwiftUI iOS app.
- `android/`: Kotlin + Jetpack Compose Android app.
- `deploy-gcp.sh`: GCP deployment entrypoint.
- `docs/DEPLOYMENT.md`: Full deployment details.
- `docs/TESTING.md`: Backend testing guidance.
- `docs/EVENT_SYSTEM_V2.md`: Canonical Tier 3 event protocol/runtime reference.

## Core Development Commands

### TypeScript Backend (`server/`)

```bash
cd server
npm install
npm run dev
npm run build
npm test
npm run test:coverage
```

### Legacy Python Backend (`ws/`)

```bash
cd ws
pip install -r requirements-dev.txt
./startServer.sh
pytest tests/
```

### iOS App (`ios/`)

```bash
cd ios
open lichunWebsocket.xcodeproj
xcodebuild -project lichunWebsocket.xcodeproj -scheme BaoLife -configuration Debug build
xcodebuild test -project lichunWebsocket.xcodeproj -scheme BaoLife -destination 'platform=iOS Simulator,name=iPhone 15'
```

### Android App (`android/`)

```bash
cd android
./gradlew assembleDebug
./gradlew test
./gradlew connectedAndroidTest
./gradlew lint
```

## GCloud CLI Runbook (Remote Lichun Server)

### Prerequisites

```bash
gcloud auth login
gcloud auth application-default login
gcloud config set project <PROJECT_ID>
gcloud config set run/region us-central1
```

### Day-To-Day Service Management

```bash
# List services
gcloud run services list --platform=managed --region=us-central1 --project=<PROJECT_ID>

# Describe a service
gcloud run services describe baolife-backend-dev --platform=managed --region=us-central1 --project=<PROJECT_ID>

# Tail logs
gcloud run logs read baolife-backend-dev --region=us-central1 --project=<PROJECT_ID> --limit=100

# List revisions
gcloud run revisions list --service=baolife-backend-dev --region=us-central1 --project=<PROJECT_ID>

# Roll back traffic to a previous revision
gcloud run services update-traffic baolife-backend-dev --to-revisions=<REVISION_NAME>=100 --region=us-central1 --project=<PROJECT_ID>

# Scale service
gcloud run services update baolife-backend-dev --min-instances=0 --max-instances=5 --region=us-central1 --project=<PROJECT_ID>
```

### Cloud SQL + Secrets Operations

```bash
# SQL instances
gcloud sql instances list --project=<PROJECT_ID>
gcloud sql instances describe baolife-db-dev --project=<PROJECT_ID>
gcloud sql connect baolife-db-dev --user=baolife --project=<PROJECT_ID>

# Secrets
gcloud secrets list --project=<PROJECT_ID>
gcloud secrets describe dev-db-password --project=<PROJECT_ID>
gcloud secrets describe dev-jwt-secret --project=<PROJECT_ID>
```

## Deployment Process

### Initial Environment Provisioning

```bash
./deploy-gcp.sh --project <PROJECT_ID> --environment dev --db-password '<STRONG_PASSWORD>'
```

Use `staging` or `production` for `--environment` as needed.

### Code-Only Update Deployment

```bash
./deploy-gcp.sh --project <PROJECT_ID> --environment dev --skip-db --skip-secrets
```

### Post-Deployment Validation

```bash
gcloud run services describe baolife-backend-dev --region=us-central1 --project=<PROJECT_ID>
gcloud run logs read baolife-backend-dev --region=us-central1 --project=<PROJECT_ID> --limit=100
curl -I https://<SERVICE_HOST>/health
```

## Important Deployment Note

- `deploy-gcp.sh` builds from `./server` and deploys the active TypeScript backend image.
- The TypeScript Cloud Run container uses `server/Dockerfile` and `node dist/index.js`.

## Event System v2 Notes

- Active event runtime is `server/src/events/v2` (prompt + deterministic resolution).
- Interactive responses must use command `eventResponse` with payload `{ eventId, choiceId }`.
- Legacy fallback dispatch via `allEvents`/`classBasedEvents` is not part of active runtime behavior.

## WebSocket Contract Tests

```bash
cd server
npm run test:contracts   # manifest, envelope, payload matrix, client coverage
npm run contract:docs    # regenerate docs/WEBSOCKET_CONTRACT.md
```

Contract manifest: `server/src/contracts/websocket-commands.ts`. Enable strict runtime validation with `CONTRACT_STRICT=true`.