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.

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.

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.

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.

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.