happy-stacks 0.3.0 → 0.5.0

package/docs/commit-audits/happy/leeroy-wip.manual-review-queue.md

@@ -0,0 +1,116 @@
+# leeroy-wip manual review queue (oldest → newest)
+
+Generated: 2026-01-24
+Source: docs/commit-audits/happy/leeroy-wip.commit-analysis.md
+
+Commits flagged for manual review: 71
+
+## Bucket counts
+
+- `codex`: 9
+- `cli`: 7
+- `sync`: 5
+- `i18n`: 4
+- `new-session`: 4
+- `claude`: 3
+- `expo-app`: 3
+- `secrets`: 3
+- `tools`: 3
+- `ui`: 3
+- `agent-input`: 2
+- `auth`: 2
+- `permission`: 2
+- `profiles`: 2
+- `resume`: 2
+- `server`: 2
+- `app`: 1
+- `crypto`: 1
+- `experiments`: 1
+- `fork`: 1
+- `happy-cli`: 1
+- `new`: 1
+- `pr107`: 1
+- `reducer`: 1
+- `rpc`: 1
+- `security`: 1
+- `server-light`: 1
+- `settings`: 1
+- `terminal`: 1
+- `tmux`: 1
+- `typecheck`: 1
+
+## Queue
+
+Each entry is: `index date short-sha bucket — subject — reasons`
+
+- 001 2026-01-17 58528a7c37d3 `crypto` — chore(crypto): patch react-native-libsodium — YES (safety/security-sensitive area)
+- 004 2026-01-17 4890a471df31 `auth` — fix(auth): harden tokenStorage web persistence — YES (safety/security-sensitive area)
+- 005 2026-01-17 4adc41d92af0 `sync` — feat(sync): add permission mode types and mapping — YES (safety/security-sensitive area)
+- 017 2026-01-17 65bae55a0b61 `i18n` — refactor(i18n): separate translation types and content — YES (diff summary skipped (large change (+1756/-1006)))
+- 018 2026-01-17 2993b5c860ff `new-session` — fix(new-session): restore standard modal flow — YES (diff summary skipped (large change (+3142/-1629)))
+- 019 2026-01-17 9e08047d2478 `profiles` — fix(profiles): harden routing, grouping, and editing — YES (diff summary skipped (large change (+1319/-857)))
+- 020 2026-01-17 8d9f56e85e5a `ui` — refactor(ui): unify list selectors and modal primitives — YES (diff summary skipped (too many files (28)); safety/security-sensitive area)
+- 022 2026-01-17 2d4675a5d051 `agent-input` — fix(agent-input): use compact permission badges — YES (safety/security-sensitive area)
+- 027 2026-01-18 7899bbd8433e `profiles` — feat(profiles): add API key requirements flow — YES (safety/security-sensitive area)
+- 028 2026-01-18 0023ba1ea5aa `i18n` — refactor(i18n): update translations and tooling — YES (diff summary skipped (large change (+2913/-143)))
+- 033 2026-01-18 daa0b4527d7f `new-session` — feat(new-session): add api key selection and wizard extraction — YES (diff summary skipped (large change (+1719/-1116)))
+- 036 2026-01-18 97ca69e0a735 `i18n` — refactor(i18n): replace remaining UI literals — YES (safety/security-sensitive area)
+- 038 2026-01-18 7976b877259c `experiments` — feat(experiments): gate Zen, file viewer, and voice auth flow — YES (safety/security-sensitive area)
+- 039 2026-01-21 6ed379f82c34 `ui` — refactor(ui): add modal + popover overlay primitives — YES (diff summary skipped (too many files (43)))
+- 040 2026-01-21 f0787de5308e `sync` — feat(sync): add secrets + terminal settings primitives — YES (diff summary skipped (too many files (60)); safety/security-sensitive area)
+- 041 2026-01-21 66ee1eaf88a6 `secrets` — feat(secrets): add secrets management + requirement resolver — YES (diff summary skipped (too many files (29)); safety/security-sensitive area)
+- 043 2026-01-21 bc779e4f7909 `new-session` — refactor(new-session): integrate secrets + terminal spawn options — YES (safety/security-sensitive area)
+- 049 2026-01-21 2e956f32f220 `new` — fix(new): keep pick screens above iOS modal — YES (safety/security-sensitive area)
+- 057 2026-01-21 ff7bec72358f `secrets` — fix(secrets): tighten callback deps and fix indentation — YES (safety/security-sensitive area)
+- 058 2026-01-21 1bb65f5dd494 `new-session` — fix(new-session): avoid stuck secret requirement modal guard — YES (safety/security-sensitive area)
+- 060 2026-01-22 bb09f91de715 `settings` — fix(settings): keep valid secrets when one entry is invalid — YES (safety/security-sensitive area)
+- 061 2026-01-22 765423af52b4 `agent-input` — fix(agent-input): cycle permission mode from normalized state — YES (safety/security-sensitive area)
+- 063 2026-01-22 2ed3100311c7 `secrets` — fix(secrets): hide values when using secret vault — YES (safety/security-sensitive area)
+- 064 2026-01-22 e5848c480522 `ui` — fix(ui): harden overlays and permission cycling — YES (safety/security-sensitive area)
+- 065 2026-01-13 69fdcff96a4c `sync` — fix(sync): restore session permission mode from last message — YES (safety/security-sensitive area)
+- 066 2026-01-13 9b499c5dccce `sync` — fix(sync): persist permission mode timestamp for restart-safe arbitration — YES (safety/security-sensitive area)
+- 067 2026-01-13 def8852509d0 `sync` — fix(sync): persist permission mode reliably across devices — YES (safety/security-sensitive area)
+- 069 2026-01-06 c06b6202b5d4 `expo-app` — Add copy-to-clipboard button to message blocks — YES (non-Conventional-Commits subject)
+- 072 2026-01-21 82d74454c3c4 `typecheck` — fix(typecheck): restore permission imports and Popover web styles — YES (safety/security-sensitive area)
+- 086 2026-01-13 86330e263595 `security` — fix(security): redact spawn secrets from daemon logs — YES (safety/security-sensitive area)
+- 089 2026-01-13 ef418bc4dda3 `pr107` — fix(pr107): redact profile secrets in doctor + align tmux tmpDir — YES (safety/security-sensitive area)
+- 096 2026-01-15 2973f7fe6861 `codex` — fix(codex): harden MCP command detection — YES (safety/security-sensitive area)
+- 099 2026-01-15 c52227082c2b `tmux` — fix(tmux): correct env, tmpdir, and session selection — YES (safety/security-sensitive area)
+- 113 2026-01-21 51782fdbfbcd `codex` — test(codex): reset transport instances between tests — YES (safety/security-sensitive area)
+- 124 2026-01-13 8b88dcd73d40 `claude` — fix(claude): carry permission mode across remote/local switches — YES (safety/security-sensitive area)
+- 125 2026-01-13 8f0e10c9428b `claude` — fix(claude): publish permission mode in session metadata — YES (safety/security-sensitive area)
+- 126 2026-01-13 ffad20faa406 `cli` — fix(cli): publish permission mode for codex/gemini sessions — YES (safety/security-sensitive area)
+- 137 2026-01-12 68a6ba4bc244 `fork` — feat(fork): enable Codex inactive-session resume via codex-reply — YES (safety/security-sensitive area)
+- 140 2026-01-22 9c40c54018c2 `cli` — Revert "fix(tools): support Windows arm64 tool unpacking" — YES (non-Conventional-Commits subject; revert commit)
+- 141 2026-01-22 ab35b47ff699 `resume` — fix(resume): make inactive resume reliable; gate Codex resume — YES (multiple major areas: cli, expo-app; safety/security-sensitive area)
+- 144 2026-01-22 0140ae276869 `codex` — refactor(codex): install mcp resume server via install-dep — YES (multiple major areas: cli, expo-app; safety/security-sensitive area)
+- 146 2026-01-22 e1deb6db8ddb `codex` — refactor(codex): add dep-status and drop codex-resume RPCs — YES (multiple major areas: cli, expo-app)
+- 148 2026-01-22 8bebf04aca92 `cli` — refactor(cli): modularize capabilities and env preview — YES (diff summary skipped (large change (+1296/-908)); safety/security-sensitive area)
+- 150 2026-01-22 a5cac698f15b `cli` — feat(cli): harden session queue, switching, and lifecycle — YES (safety/security-sensitive area)
+- 151 2026-01-22 3fc704424e8d `app` — feat(app): add pending queue, discard markers, and capabilities — YES (diff summary skipped (too many files (44)))
+- 156 2026-01-22 8c16ee8f9cef `auth` — fix(auth): surface auth failures and gate unauth routes — YES (safety/security-sensitive area)
+- 158 2026-01-22 3b3609fed434 `rpc` — fix(rpc): add structured code for missing RPC methods — YES (multiple major areas: expo-app, server)
+- 160 2026-01-22 7fbe1f1cc727 `permission` — fix(permission): avoid no-op permissionModeUpdatedAt bumps — YES (safety/security-sensitive area)
+- 162 2026-01-22 ee0bec2a0b90 `resume` — Delete INACTIVE_SESSION_RESUME.md — YES (non-Conventional-Commits subject)
+- 165 2026-01-23 8b3f39f22664 `cli` — feat(cli): add interaction.respond for AskUserQuestion — YES (safety/security-sensitive area)
+- 166 2025-12-24 ed4bc007308a `codex` — feat: add execpolicy approval option for Codex — YES (safety/security-sensitive area)
+- 167 2025-12-24 78adc9c58811 `codex` — feat(codex): support execpolicy approvals and MCP tool calls — YES (safety/security-sensitive area)
+- 168 2026-01-22 9dfa09bef8d8 `i18n` — fix(i18n): add Codex execpolicy button text — YES (safety/security-sensitive area)
+- 169 2026-01-22 559d39da116d `reducer` — fix(reducer): keep permission messages idempotent — YES (safety/security-sensitive area)
+- 171 2026-01-19 d06d5a833f8e `claude` — Add signal forwarding to claudeLocal.ts — YES (non-Conventional-Commits subject)
+- 174 2025-12-24 e956463db3e2 `codex` — fix: use runtime execPath for MCP bridge — YES (safety/security-sensitive area)
+- 175 2026-01-23 f0a7d8d0b40c `codex` — fix(codex): use mcp tool call id for approvals — YES (safety/security-sensitive area)
+- 176 2026-01-22 da620b6865ad `server` — feat(server): add full/light flavors with sqlite migrations — YES (diff summary skipped (too many files (38)))
+- 183 2026-01-23 46186162ae14 `happy-cli` — test(happy-cli): fix timer cleanup and MCP schema mocks — YES (safety/security-sensitive area)
+- 208 2026-01-23 61a18ac95e17 `tools` — fix(tools): require permission id for ExitPlanMode actions — YES (safety/security-sensitive area)
+- 209 2026-01-23 5b36c9bf91c1 `tools` — test(tools): avoid null permission in ExitPlanToolView tests — YES (safety/security-sensitive area)
+- 211 2026-01-23 55428fb0253c `tools` — fix(tools): alert when AskUserQuestion permission id is missing — YES (safety/security-sensitive area)
+- 212 2026-01-23 dc6955f88abd `terminal` — fix(terminal): prevent sessionId path traversal in attachment info — YES (safety/security-sensitive area)
+- 226 2026-01-23 c461ed1cb4ef `permission` — feat(permission): add permission mode option helpers — YES (safety/security-sensitive area)
+- 228 2026-01-23 523989b4de8e `server-light` — fix(server-light): avoid master secret race — YES (safety/security-sensitive area)
+- 237 2026-01-23 241f0ae24b1d `cli` — test(cli): prevent legacy sessionId path traversal — YES (safety/security-sensitive area)
+- 238 2026-01-23 a1e4a6dd3fbd `cli` — fix(cli): block legacy sessionId path traversal — YES (safety/security-sensitive area)
+- 241 2026-01-23 1464402758bf `codex` — fix(codex): preserve falsy MCP tool results — YES (safety/security-sensitive area)
+- 247 2026-01-23 24b607abfa07 `server` — Refactor schema sync and centralize Prisma types — YES (non-Conventional-Commits subject; diff summary skipped (too many files (29)))
+- 248 2026-01-23 bf3027799623 `expo-app` — Set EXPO_UNSTABLE_WEB_MODAL env var in Expo scripts — YES (non-Conventional-Commits subject)
+- 249 2026-01-23 c803115dcbdc `expo-app` — Improve postinstall script for symlinked paths and patching — YES (non-Conventional-Commits subject)

package/docs/happy-development.md

@@ -375,7 +375,7 @@ In interactive TTY runs, `happys dev` / `happys start` may auto-open the UI in y
 - **Dependency install**: ensures component deps are installed when needed.
 - **Schema readiness**:
   - `happy-server` (Postgres): applies `prisma migrate deploy` (configurable via `HAPPY_STACKS_PRISMA_MIGRATE`)
-  - `happy-server-light` (SQLite): upstream dev normally runs `prisma db push` (toggle via `HAPPY_STACKS_PRISMA_PUSH`)
+  - `happy-server-light` (SQLite): applies `prisma migrate deploy` using the SQLite migration history in the unified server repo
 - **Auth seeding for new stacks** (non-main + non-interactive default):
   - Uses the configured seed stack via `HAPPY_STACKS_AUTH_SEED_FROM` (default: `main`) when the stack looks uninitialized.
   - Recommended for development: create + log into a dedicated seed stack once (usually `dev-auth`) and set:
@@ -559,9 +559,9 @@ Most commands support `--help` and `--json`.
 ### Core run commands
 
 - **`happys start`**: production-like run (no Expo)
-  - Flags: `--server=happy-server|happy-server-light`, `--restart`, `--no-daemon`, `--no-ui`, `--no-browser`
+  - Flags: `--server=happy-server|happy-server-light`, `--restart`, `--no-daemon`, `--no-ui`, `--no-browser`, `--mobile`
 - **`happys dev`**: dev run (server + daemon + Expo web)
-  - Flags: `--server=happy-server|happy-server-light`, `--restart`, `--no-daemon`, `--no-ui`, `--watch`, `--no-watch`, `--no-browser`
+  - Flags: `--server=happy-server|happy-server-light`, `--restart`, `--no-daemon`, `--no-ui`, `--watch`, `--no-watch`, `--no-browser`, `--mobile`
 - **`happys stop`**: stop stacks and related processes
   - Flags: `--except-stacks=main,exp1`, `--yes`, `--aggressive`, `--sweep-owned`, `--no-docker`, `--no-service`
 
@@ -628,7 +628,6 @@ Happy Stacks uses `HAPPY_STACKS_*` as the canonical prefix; most settings also a
 - **Full server infra** (happy-server):
   - `HAPPY_STACKS_MANAGED_INFRA=0` (disable Docker-managed Postgres/Redis/Minio; provide URLs yourself)
 - **Prisma behavior**:
-  - `HAPPY_STACKS_PRISMA_PUSH=0` (server-light: avoid `prisma db push` in dev mode)
   - `HAPPY_STACKS_PRISMA_MIGRATE=0` (full server: disable `prisma migrate deploy`)
 - **happy-cli build behavior**:
   - `HAPPY_STACKS_CLI_BUILD_MODE=auto|always|never`

package/docs/isolated-linux-vm.md

@@ -0,0 +1,82 @@
+# Isolated Linux VM (Apple Silicon) for `review-pr`
+
+If you want to validate `happys review-pr` on a **fresh system** (no existing `~/.happy-stacks`, no host tooling), the simplest repeatable approach on Apple Silicon is a Linux VM managed by **Lima** (it uses Apple’s Virtualization.framework).
+
+This avoids Docker/container UX issues (browser opening, Expo networking, file watching) while still being truly “clean”.
+
+## Option A (recommended): Lima + Ubuntu ARM64
+
+### 1) Install Lima (macOS host)
+
+```bash
+brew install lima
+```
+
+### 2) Create a VM
+
+```bash
+limactl create --name happy-pr --tty=false template://ubuntu-24.04
+limactl start happy-pr
+```
+
+### 3) Provision the VM (Node + build deps)
+
+```bash
+limactl shell happy-pr
+```
+
+Inside the VM:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/leeroybrun/happy-local/main/scripts/provision/linux-ubuntu-review-pr.sh -o /tmp/linux-ubuntu-review-pr.sh && chmod +x /tmp/linux-ubuntu-review-pr.sh && /tmp/linux-ubuntu-review-pr.sh
+```
+
+### 4) Run `review-pr` via `npx` (published package)
+
+Inside the VM:
+
+```bash
+npx --yes happy-stacks@latest review-pr \
+  --happy=https://github.com/leeroybrun/happy/pull/10 \
+  --happy-cli=https://github.com/leeroybrun/happy-cli/pull/12 \
+  --no-mobile \
+  --verbose
+```
+
+Notes:
+- `--no-mobile` keeps the validation focused (Expo mobile dev-client adds more host requirements).
+- You can also add `--keep-sandbox` if you want to inspect the sandbox contents after a failure.
+- For full reproducibility, pin the version: `npx --yes happy-stacks@0.3.0 review-pr ...`
+
+### Optional: test **unreleased local changes**
+
+If you need to test changes that aren’t published to npm yet:
+
+1) On your Mac (repo checkout):
+
+```bash
+npm pack
+```
+
+2) Copy the generated `happy-stacks-*.tgz` into the VM (any method you like), then inside the VM:
+
+```bash
+npx --yes ./happy-stacks-*.tgz review-pr ...
+```
+
+## Option B: GUI VM (UTM) – simplest when you want a “real desktop”
+
+If you want the most realistic “reviewer” experience (open browser, etc.), a GUI VM is great:
+
+1. Install UTM (macOS host): `brew install --cask utm`
+2. Create an Ubuntu 24.04 ARM64 VM (UTM wizard).
+3. Run the same provisioning + `node bin/happys.mjs review-pr ...` inside the VM.
+
+## Option C: Apple “container” / Docker
+
+Containers are excellent for server-only validation, but are usually **not** the best fit for end-to-end `review-pr` UX because:
+- opening the host browser from inside the container is awkward
+- Expo/dev-server workflows and networking tend to require extra port mapping and host interaction
+
+Use containers only if you explicitly want “CLI-only” checks and are okay opening URLs manually.
+

package/docs/mobile-ios.md

@@ -8,101 +8,166 @@ see the “Using Happy from your phone” section in the main README.
 - Xcode installed
 - CocoaPods installed (`brew install cocoapods`)
 
-## Step 1: Generate iOS native project + Pods (run when needed)
+## Two supported modes
 
-Run this after pulling changes that affect native deps/config, or if `ios/` was deleted:
+- **Shared dev-client app** (recommended for development):
+  - Install *one* “Happy Stacks Dev” app on your phone.
+  - Run any stack with `--mobile`; scan the QR to open that stack inside the dev-client.
+  - Per-stack auth/storage is isolated via `EXPO_PUBLIC_HAPPY_STORAGE_SCOPE` (set automatically in stack mode).
 
-```bash
-happys mobile:prebuild
-```
+- **Per-stack “release” app** (recommended for demos / strict isolation):
+  - Install a separate iOS app per stack (unique bundle id + scheme).
+  - Each stack app is isolated by iOS app container (no token collisions).
+
+## Shared dev-client app (install once)
 
-## Step 2: Install the iOS dev build
+Install the dedicated Happy Stacks dev-client app on your iPhone (USB).
 
-- **iOS Simulator**:
+This command **runs a prebuild** (generates `ios/` + runs CocoaPods) and then installs a Debug build
+without starting Metro:
 
 ```bash
-happys mobile --run-ios --device="iPhone 16 Pro"
+happys mobile-dev-client --install
 ```
 
-- **Real iPhone** (requires code signing in Xcode once):
+If you want to ensure the dev-client is built from a specific stack’s active `happy` worktree
+(e.g. to include upstream changes that aren’t merged into your default checkout yet), run:
 
 ```bash
-happys mobile --run-ios --device="Your iPhone"
+happys stack mobile-dev-client <stack> --install
 ```
 
-Tip: you can omit `--device` to auto-pick the first connected iPhone over USB:
+Optional:
 
 ```bash
-happys mobile --run-ios
+happys mobile-dev-client --install --device="Your iPhone"
+happys mobile-dev-client --install --clean
 ```
 
-To see the exact device names/IDs you can pass:
+Then run any stack with mobile enabled:
 
 ```bash
-happys mobile:devices
+happys stack dev <stack> --mobile
+# or:
+happys dev --mobile
 ```
 
-If you hit a bundle identifier error (e.g. `com.slopus.happy.dev` “not available”), set a unique local bundle id:
+Notes:
+
+- **LAN requirement**: for physical iPhones, Metro must be reachable over LAN.
+  - Happy Stacks defaults to `lan` for mobile, and will print a QR code + deep link.
+  - For simulators you can usually use `localhost` (see `HAPPY_STACKS_MOBILE_HOST` below).
+- **If Expo is already running in web-only mode**: re-run with `--restart` and include `--mobile`.
+
+## Per-stack app install (isolated)
+
+Install an isolated app for a specific stack (unique bundle id + scheme, Release config, no Metro):
 
 ```bash
-HAPPY_STACKS_IOS_BUNDLE_ID="com.yourname.happy.local.dev" happys mobile --run-ios
-# legacy: HAPPY_LOCAL_IOS_BUNDLE_ID="com.yourname.happy.local.dev" happys mobile --run-ios
+happys stack mobile:install <stack> --name="Happy (<stack>)"
+happys stack mobile:install <stack> --name="Happy PR 272" --device="Your iPhone"
 ```
 
-## Release build (runs without Metro)
+The chosen app name is persisted in the stack env so you can re-run installs without re-typing it.
+
+## Native iOS regeneration / “prebuild” (critical)
+
+You’ll need to regenerate the iOS native project + Pods when:
+
+- you pull changes that affect native deps / Expo config
+- `components/happy/ios/` was deleted
+- you hit CocoaPods / deployment-target mismatches after a dependency bump
 
-Build + install a Release configuration (no Metro required at runtime):
+Run:
 
 ```bash
-happys mobile:install
+happys mobile --prebuild
+# (optional) fully regenerate ios/:
+happys mobile --prebuild --clean
 ```
 
-## Step 3: Start Metro (dev client)
+What this does today:
 
-- **iOS Simulator**:
+- runs `expo prebuild --no-install` (so we can patch before CocoaPods runs)
+- patches `ios/Podfile.properties.json` to:
+  - set `ios.deploymentTarget` to `16.0`
+  - set `ios.buildReactNativeFromSource` to `true`
+- patches the generated Xcode project deployment target (where applicable)
+- runs `pod install`
+
+Notes:
+
+- **You usually don’t need to run this manually** because both:
+  - `happys mobile-dev-client --install`
+  - `happys stack mobile:install <stack>`
+  already include `--prebuild`.
+- Legacy alias: `happys mobile:prebuild` exists (hidden), but prefer `happys mobile --prebuild`.
+
+## Manual `happys mobile` usage (advanced)
+
+If you want to work on the embedded Expo app directly (outside `happys dev --mobile`), `happys mobile` supports:
 
 ```bash
-happys mobile --host=localhost
+# Start Metro (keeps running):
+happys mobile --host=lan
+
+# Build + install on iOS (and exit). If you omit --device, it will try to auto-pick a connected iPhone over USB:
+happys mobile --prebuild --run-ios --device="Your iPhone"
+happys mobile --prebuild --run-ios --configuration=Release --no-metro
 ```
 
-- **Real iPhone** (same Wi‑Fi as your Mac):
+## Notes / troubleshooting
+
+- **QR opens the wrong app**:
+  - The dev-client QR uses the `HAPPY_STACKS_DEV_CLIENT_SCHEME` (default: `happystacks-dev`).
+  - Per-stack installs use a different per-stack scheme, so they should not intercept dev-client QR scans.
+
+- **List connected devices** (for `--device=`):
 
 ```bash
-happys mobile --host=lan
+happys mobile:devices
 ```
 
-Open the dev build and tap Reload. Scanning the QR should open the dev build (not the App Store app).
+- **Code signing weirdness on a real iPhone**:
+  - Happy Stacks will try to “un-pin” signing fields in the generated `.pbxproj` so Expo/Xcode can reconfigure signing
+    (this avoids failures where automatic signing is disabled because `DEVELOPMENT_TEAM`/profiles were pinned).
+  - If you want to manage signing manually, pass `--no-signing-fix` to `happys mobile ...` / `happys stack mobile <stack> ...`.
 
 ## Bake the default server URL into the app (optional)
 
 If you want the built app to default to your happy-stacks server URL, set this **when building**:
 
 ```bash
-HAPPY_STACKS_SERVER_URL="https://<your-machine>.<tailnet>.ts.net" happys mobile:install
+HAPPY_STACKS_SERVER_URL="https://<your-machine>.<tailnet>.ts.net" happys mobile-dev-client --install
 ```
 
-Note: changing `HAPPY_STACKS_SERVER_URL` requires rebuilding/reinstalling the Release app (`happys mobile:install`).
+Note: changing `HAPPY_STACKS_SERVER_URL` requires rebuilding/reinstalling the app you care about.
 
-You can also set a custom bundle id (recommended for real devices):
+Important:
 
-```bash
-HAPPY_STACKS_IOS_BUNDLE_ID="com.yourname.happy.local.dev" HAPPY_STACKS_SERVER_URL="https://<your-machine>.<tailnet>.ts.net" happys mobile:install
-```
+- For **non-main stacks**, `HAPPY_STACKS_SERVER_URL` is only respected if it’s set **in that stack’s env file**
+  (safety: we ignore “global” URLs for non-main stacks to avoid accidentally repointing other stacks).
+
+## Customizing the app identity (optional / advanced)
+
+Happy Stacks uses these identities:
 
-## Customizing the app identity (optional)
+- **Dev-client**: defaults to `Happy Stacks Dev` + bundle id `com.happystacks.dev.<user>`
+- **Per-stack release**: defaults to `Happy (<stack>)` + bundle id `com.happystacks.stack.<user>.<stack>`
+
+If you want to build/install *manually* (instead of `mobile-dev-client` / `stack mobile:install`), you can override:
 
 - **Bundle identifier (recommended for real iPhones)**:
-  - You may *need* this if the default `com.slopus.happy.dev` can’t be registered on your Apple team.
+  - You may need this if the bundle id you’re using isn’t available/owned by your Apple team.
 
 ```bash
-HAPPY_STACKS_IOS_BUNDLE_ID="com.yourname.happy.local.dev" happys mobile --run-ios
-HAPPY_STACKS_IOS_BUNDLE_ID="com.yourname.happy.local.dev" happys mobile:install
+HAPPY_STACKS_IOS_BUNDLE_ID="com.yourname.happy.local.dev" happys mobile --prebuild --run-ios --no-metro
 ```
 
 - **App name (what shows on the home screen)**:
 
 ```bash
-HAPPY_STACKS_IOS_APP_NAME="Happy Local" happys mobile:install
+HAPPY_STACKS_IOS_APP_NAME="Happy Local" happys mobile --prebuild --run-ios --no-metro
 ```
 
 ## Suggested env (recommended)
@@ -110,25 +175,18 @@ HAPPY_STACKS_IOS_APP_NAME="Happy Local" happys mobile:install
 Add these to your main stack env file (`~/.happy/stacks/main/env`) (or `~/.happy-stacks/env.local` for global overrides) so you don’t have to prefix every command:
 
 ```bash
-# Required if you want the Release app to default to your stack server:
-HAPPY_STACKS_SERVER_URL="https://<your-machine>.<tailnet>.ts.net"
+# How the phone reaches Metro:
+# - lan: recommended for real devices
+# - localhost: OK for simulators
+HAPPY_STACKS_MOBILE_HOST="lan"
 
-# Strongly recommended for real devices (needs to be unique + owned by your Apple team):
-HAPPY_STACKS_IOS_BUNDLE_ID="com.yourname.happy.local.dev"
+# (optional) default scheme used in the dev-client QR / deep link
+# (must match your installed dev-client app):
+HAPPY_STACKS_DEV_CLIENT_SCHEME="happystacks-dev"
+
+# Default public server URL for the stack (baked into the Expo app config):
+HAPPY_STACKS_SERVER_URL="https://<your-machine>.<tailnet>.ts.net"
 
 # Optional: home screen name:
 HAPPY_STACKS_IOS_APP_NAME="Happy Local"
 ```
-
-## Personal build on iPhone (EAS internal distribution)
-
-```bash
-cd "$HOME/.happy-stacks/workspace/components/happy"
-eas build --profile development --platform ios
-```
-
-Then keep Metro running from `happy-stacks`:
-
-```bash
-happys mobile --host=lan
-```