feat: consolidate iOS with API and web preserving history

docs/IOS_MONOREPO_MIGRATION.md

@@ -0,0 +1,69 @@
+# iOS monorepo migration — 2026-10-04
+
+## Source and history
+
+The native app is now maintained under `ios/` on this repository's `master`.
+Imported source: `snowspeeder/hope-voice-ios`, branch `feat/ios-app`, original tip
+`7bd893ae5c46ee470203eae273e4a15454d66f04` (41 reachable commits).
+Original default `main` tip `40aaf4fea7f3ee9d3a5742b4cc6a090520ee0d73` is an ancestor
+of that feature tip. No source branches had additional unmerged commits or tags.
+
+The import is a two-parent, non-squashed subtree-style merge. Backend master
+`91a0d8820ffdd1cd028e4a1a52599da1a9701aec` remains the first parent; the unchanged
+original iOS tip is the second parent. Original commit IDs and complete ancestry
+are retained, not rewritten. Historical native paths were at the old repository
+root; current paths are under `ios/`.
+
+```bash
+git log 7bd893ae -- Sources/Chat/ChatViews.swift
+git show 7bd893ae:Sources/Chat/ChatViews.swift
+git log --all --graph --oneline
+```
+
+The source repository will be archived using authenticated `tea api` **only after**
+the import is pushed and remote ancestry/tree checks pass. Archival is reversible;
+no source repository deletion or local checkout deletion is part of this operation.
+The old local checkout is no longer the development source of truth.
+
+## Working here
+
+Open `ios/Voice.xcodeproj`; scheme `Voice_iOS`. Run `xcodegen generate` from
+`ios/` when changing project membership. Root generator
+`scripts/generate_hope_themes.py` writes/checks both shared and native Swift theme
+copies. Native instructions and dated qualification remain under `ios/docs/`.
+
+The root ignore file excludes secrets, runtime state, Python/JS caches, Xcode
+build/results and user state without hiding versioned source, project definitions,
+lockfiles or environment examples. Docker excludes native/design source from
+backend contexts. Backend push automation ignores iOS-only and documentation
+changes; changes to backend code or automation still qualify/deploy normally.
+The obsolete imported native backend deployment script now fails closed.
+
+## Compatibility scope
+
+Read-only independent audit compared the imported native tip to backend master:
+authentication, bearer confinement, token bootstrap/conversation binding, voice
+catalog, snake_case envelopes, revisions, uploads and SSE event contracts match.
+No API compatibility blocker to this migration was found. No production calls or
+physical-device tests were performed for this import.
+
+Two pre-existing functional follow-ups were identified, not introduced or repaired
+by the directory/history migration:
+
+- Native workspace filtering occurs after global pagination; it should use server
+  `workspace_id` filtering and maintain that scope during reload/sync.
+- Native and web edited/regenerated attachment-bearing turns can lose the original
+  turn's attachment IDs; these need shared regression coverage and ownership-aware
+  preservation.
+
+Verification from the relocated tree on 2026-10-04: XcodeGen regenerated the
+project without a project-file diff; native simulator test target passed 60 Swift
+Testing cases plus 12 XCTest cases, with one explicit live-chat skip, at
+`/tmp/hope-ios-redesign-derived/Logs/Test/Test-Voice_iOS-2026.10.04_07-21-55--0400.xcresult`
+(log `/tmp/hope-monorepo-ios-tests.log`). Shared theme artifacts verified; the
+backend CI offline selection passed **147 tests**, with one dependency deprecation
+warning. No device install, live audio or production API probe was performed.
+
+These are explicitly not claims of exhaustive UI/functionality qualification.
+Existing untracked local design prototypes/screenshots were left untouched and
+were not included in the migration commit.