1 files changed, 61 insertions, 0 deletions
diff --git a/makima/ios/docs/DEVELOPMENT.md b/makima/ios/docs/DEVELOPMENT.md
new file mode 100644
index 0000000..f58a218
--- /dev/null
+++ b/makima/ios/docs/DEVELOPMENT.md
@@ -0,0 +1,61 @@
+# Makima iOS — Development
+
+## Prerequisites
+
+- macOS 14+ with Xcode 16+
+- Homebrew
+- `xcodegen` (auto-installed by `make bootstrap`)
+- Optional: `xcbeautify` for nicer build logs (`brew install xcbeautify`)
+- Optional: `swift-format` for linting (`brew install swift-format`)
+
+## Source of truth
+
+`project.yml` is the source of truth. `Makima.xcodeproj` is generated. **Do not commit `Makima.xcodeproj/`.** If you need to hand-tweak build settings, edit `project.yml` and re-run `make xcgen`.
+
+## Running
+
+```bash
+make ios-sim-fast     # simulator build
+make ios-device-fast  # device build (needs signing team set via env or project.yml)
+make test             # unit tests on simulator
+```
+
+First device build: open `Makima.xcodeproj` in Xcode, select the `Makima` target, set your Signing Team under "Signing & Capabilities". That value is only local to Xcode's derived config.
+
+## Folder layout
+
+```
+ios/
+  project.yml                 # XcodeGen source
+  Makefile                    # build shortcuts
+  Sources/Makima/
+    App/                      # entry point, Info.plist
+    Design/                   # Palette, Typography, shared components
+    Net/                      # APIClient, WebSocketClient, AuthStore (M2+)
+    Stores/                   # @Observable stores (M3+)
+    Features/                 # screen-level views
+    Models/                   # Codable types for the Makima API
+    Markdown/                 # custom markdown + code block rendering (M5)
+    Resources/
+      Assets.xcassets/        # app icon, colors
+      Logo/                   # copied from frontend/public/logo
+  Tests/MakimaTests/
+  docs/
+```
+
+## Server config during development
+
+Default server URL is `https://makima.jp`. For local dev against a self-hosted makima:
+
+1. Onboarding → Server URL → enter e.g. `http://<host>:8080`
+2. Provide an API key created via `POST /api/v1/auth/api-keys` on that server.
+
+`NSAllowsArbitraryLoads` is disabled; for plain-HTTP dev servers you must either run behind TLS or add an ATS exception for your dev host via project.yml's `Info.plist.properties`.
+
+## CI
+
+GitHub Actions workflow at `.github/workflows/ios-ci.yml` runs `make test` on macOS-14 runners for every PR touching `makima/ios/**`.
+
+## Release (v1)
+
+TestFlight release lane is defined in `docs/RELEASING.md` (to be written at M8).