# Hope — API, web, and native iOS monorepo

## Read first

- Current architecture and deployment: `IMPLEMENTATION_PLAN.md`, `control/README.md`, `QUALIFICATION.md`, and `tests/README.md`.
- Shared chat behavior: `docs/CHAT_CONTRACT.md` and `docs/CHAT_FEATURES_CONTRACT.md`. These current contracts supersede historical no-model-picker notes.
- Native work: `ios/AGENTS.md`, `ios/docs/PROJECT_STATUS.md`, and `ios/docs/ENGINEERING_LEARNINGS.md` before changing native code, tests, signing, or lifecycle.
- Migration/history: `docs/IOS_MONOREPO_MIGRATION.md`.

## Layout and boundaries

- `control/`: trusted multi-user account service and private per-account Hermes provisioning.
- `agent/` and root container configuration: Azure STT → authenticated dedicated Hermes → Azure TTS over LiveKit.
- `web/`: browser client, HTTPS proxy bootstrap, and web assets.
- `ios/`: SwiftUI app, XcodeGen source `project.yml`, generated shared Xcode project, native tests and device guidance.
- `docs/`, `tests/`, `scripts/`: shared contracts, offline qualification, and protected deployment tooling.
- Hope Music is external. Do not embed its player or restore its dependencies into this app/container.

## Invariants

- No anonymous bootstrap, direct upstream provider credentials, shared account memory, trust-all TLS, plaintext fallback, or fabricated integrations.
- Text chat uses authenticated HTTP/SSE and does not start a microphone/LiveKit session. Voice retains its separate explicit session lifecycle.
- Model/thinking preferences are server-owned via the current settings contract; do not restore removed legacy OpenWebUI/MCP dispatch paths.
- Preserve account scoping, logout/server-change teardown, TLS pinning, revision checks, durable conversations and SSE replay semantics across both clients.
- Never expose credentials or private payloads in logs, tests, artifacts, or commits. Keep runtime data and certificates outside CI checkouts.
- Use current contracts as the authority; historical iOS plans/deployment receipts are evidence, not instructions to redeploy obsolete images.

## Verification

- Use the offline commands in `tests/README.md` or the explicit offline selection in `.gitea/workflows/rebuild.yml`; never invoke the legacy live-default suite by accident.
- Run theme generator checks after shared theme changes. Native generated theme lives at `ios/Sources/Chat/HopeTheme.generated.swift`.
- From `ios/`, use XcodeGen when adding/removing sources/resources, and run simulator tests with scheme `Voice_iOS`. Opt-in live tests stay off unless explicitly authorized.
- Date qualification records and distinguish unit/simulator/build evidence from production API, installation, and physical microphone/TTS evidence.

## Git and deployment

- `master` of this repository is the single integration branch for API/web/iOS. The old `hope-voice-ios` repository is a read-only archive after migration.
- Preserve original iOS ancestry; do not squash away the imported history. See the migration record for original tips and lookup commands.
- Use conventional commits and explicitly stage intended files; leave unrelated local design artifacts untouched.
- Inspect `.gitea/workflows/rebuild.yml` before pushing: root backend changes can deploy to Unraid; iOS-only and documentation changes are excluded. Do not disable backend qualification or mutate protected runtime configuration.
- Maintain `ios/docs/PROJECT_STATUS.md` for native changes and `QUALIFICATION.md` for backend/web qualification. A Git push is not proof of iPhone installation or physical audio success.