happy-stacks 0.4.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:
@@ -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/monorepo-migration.md

@@ -0,0 +1,286 @@
+# Monorepo migration (split repos → `slopus/happy`)
+
+This doc explains the **recommended, safe, step-by-step** flow to port commits from the legacy split repos (`happy`, `happy-cli`, `happy-server`) into the new `slopus/happy` monorepo layout:
+
+- old `happy` (UI) → `expo-app/`
+- old `happy-cli`  → `cli/`
+- old `happy-server` → `server/`
+
+The tooling used here is `happys monorepo port` (from this repo / Happy Stacks). It ports commits by generating patches (`git format-patch`) and applying them with `git am` into the target monorepo branch.
+
+## Quick start (if you don’t already use Happy Stacks)
+
+If you’re an external collaborator and you **don’t** have `happys` installed yet, this is the fastest “migration environment” setup:
+
+```bash
+npx happy-stacks init --install-path
+happys bootstrap --interactive
+happys stack new monorepo-merge --interactive
+```
+
+### “No install” option (npx-only, port command only)
+
+If you *only* want to run the port helper (and you already have local clones of the source repos + target monorepo), you can run it directly via `npx` without installing anything globally:
+
+```bash
+npx --yes happy-stacks monorepo port --help
+```
+
+Example:
+
+```bash
+npx --yes happy-stacks monorepo port \
+  --target=/abs/path/to/slopus-happy-monorepo \
+  --branch=your-port-branch \
+  --base=origin/main \
+  --3way \
+  --from-happy=/abs/path/to/old-happy \
+  --from-happy-base=origin/main
+```
+
+Notes:
+- This “npx-only” mode is great for **one-off ports**, but it won’t manage stacks/worktrees for you.
+- For the full guided flow (stacks + worktrees + repeatable commands), use the installed setup above.
+
+### Port helpers (guide / status / continue)
+
+Happy Stacks also provides small helpers that make conflict resolution less error-prone:
+
+```bash
+happys monorepo port guide
+happys monorepo port status --target=/abs/path/to/monorepo
+happys monorepo port continue --target=/abs/path/to/monorepo
+```
+
+- `port guide` is interactive (TTY required) and helps you build the initial port command safely.
+- `port guide` can also **pause on conflicts**, let you resolve them, and then resume until the port completes.
+- `port status` shows whether a `git am` session is in progress, the current patch subject, and conflicted files.
+- `port continue` runs `git am --continue` for the target repo (after you staged resolved files). If you started from `port guide`, it can also resume the remaining port automatically after each continue.
+
+How to bring “the changes you want to port” into this environment:
+
+- **If you already have local checkouts** of your legacy repos (recommended for forks/branches that aren’t PRs yet):
+  - keep them wherever they are
+  - you’ll pass their absolute paths to `happys monorepo port` via `--from-happy=...`, `--from-happy-cli=...`, etc.
+
+- **If your changes exist as GitHub PRs**, you can let Happy Stacks create a clean worktree from the PR directly:
+  - `happys wt pr happy-cli <pr-url-or-number> --use`
+  - `happys wt pr happy <pr-url-or-number> --use`
+  - (repeat for whichever repos your changes live in)
+
+Once you have:
+- a **target monorepo worktree** (from upstream), and
+- one or more **source repos** (paths or worktrees)
+
+…continue with the rest of this doc.
+
+## Prereqs
+
+- You have a **clean** source worktree/branch for each legacy repo you want to port.
+  - No uncommitted changes (unless you intentionally want to include them as new commits first).
+  - Ideally based on `upstream/main` (or you know the correct base ref).
+- You have a **clean** target monorepo checkout (a worktree of `slopus/happy`).
+- You are ready to resolve conflicts with `git am` (this is normal for large refactors, i18n changes, renamed files, etc).
+
+## Recommended workflow (interactive, safest)
+
+### 1) Create an isolated stack (don’t touch `main`)
+
+Pick a new stack name (example: `monorepo-merge`):
+
+```bash
+happys stack new monorepo-merge --interactive
+```
+
+### 2) Create a clean monorepo worktree from upstream
+
+Create a worktree based on `upstream/main` for the **monorepo** (`slopus/happy`):
+
+```bash
+happys wt new happy tmp/monorepo-port --from=upstream
+```
+
+Point your stack at that worktree (this keeps `main` stable):
+
+```bash
+happys stack wt monorepo-merge -- use happy /absolute/path/to/components/.worktrees/happy/slopus/tmp/monorepo-port
+```
+
+Notes:
+- In monorepo mode, `happy`, `happy-cli`, and `happy-server` are **one git repo**; the stack overrides should point at the same monorepo root.
+- `happys ... wt use happy <monorepo-root>` automatically updates all three component dir overrides together (prevents UI/CLI/server version skew).
+- If you pass a monorepo root, Happy Stacks normalizes component dirs to:
+  - `happy` → `.../expo-app`
+  - `happy-cli` → `.../cli`
+  - `happy-server` → `.../server`
+
+### 3) Create a target branch
+
+In the monorepo worktree, create your migration branch from `upstream/main`:
+
+```bash
+happys wt git happy slopus/tmp/monorepo-port -- checkout -b <your-branch-name> upstream/main
+```
+
+Example:
+
+```bash
+happys wt git happy slopus/tmp/monorepo-port -- checkout -b leeroy-wip upstream/main
+```
+
+### 4) Port the UI commits (old `happy` → `expo-app/`)
+
+Run the port in **interactive mode**:
+
+- use `--onto-current` to apply onto the branch you already checked out
+- use `--3way` so git can do a 3-way merge and produce conflict markers instead of failing immediately
+- **do not** use `--continue-on-failure` (you want it to stop at the first conflict)
+
+```bash
+happys monorepo port \
+  --target=/abs/path/to/monorepo-root \
+  --onto-current \
+  --3way \
+  --from-happy=/abs/path/to/old-happy-repo \
+  --from-happy-base=upstream/main
+```
+
+What `--from-happy-base` means:
+- It’s the ref used to compute the patch range (`merge-base(base, HEAD)..HEAD`).
+- If your branch is based on `upstream/main`, this should be `upstream/main`.
+
+### 5) Resolve conflicts (when the port stops)
+
+If the port stops, you are now in a normal `git am` session.
+
+Helpful commands:
+
+```bash
+git am --show-current-patch=diff
+git status
+```
+
+Fix conflicts in the files with conflict markers:
+- look for `<<<<<<<`, `=======`, `>>>>>>>`
+- edit to the desired final content
+- then stage the resolved files:
+
+```bash
+git add <file...>
+git am --continue
+```
+
+If you decide a specific patch should not be ported:
+
+```bash
+git am --skip
+```
+
+If you want to fully abort the current patch application:
+
+```bash
+git am --abort
+```
+
+Then rerun the `happys monorepo port ... --onto-current ...` command.
+
+### 6) Port the CLI commits (old `happy-cli` → `cli/`)
+
+After the UI port completes, port CLI commits onto the same branch:
+
+```bash
+happys monorepo port \
+  --target=/abs/path/to/monorepo-root \
+  --onto-current \
+  --3way \
+  --from-happy-cli=/abs/path/to/old-happy-cli-repo \
+  --from-happy-cli-base=upstream/main
+```
+
+Resolve conflicts the same way (`git am --continue`).
+
+### 7) Verify what landed
+
+Quick sanity checks:
+
+```bash
+# ensure upstream/main is an ancestor of your branch
+git merge-base --is-ancestor upstream/main HEAD
+
+# list commits introduced by the port
+git log --oneline upstream/main..HEAD
+```
+
+If you are porting multiple legacy branches, it’s often useful to compare counts:
+
+```bash
+git rev-list --count upstream/main..HEAD
+```
+
+### 8) Push and open a PR
+
+Push to the remote you intend to PR against (example uses `upstream`):
+
+```bash
+git push upstream HEAD:<branch-name>
+```
+
+## Common failures (expected) and what to do
+
+### “target repo is not clean”
+
+`happys monorepo port` refuses to run when the target has local changes.
+
+Fix: commit, stash, or reset your target worktree, then re-run.
+
+### “a git am operation is already in progress”
+
+You have an unfinished `git am` session from a previous attempt.
+
+Fix it first:
+
+```bash
+git am --continue   # after resolving conflicts
+# or
+git am --abort
+```
+
+Then re-run `happys monorepo port ...`.
+
+### “patch does not apply” / i18n churn / renamed files
+
+This usually means upstream moved and the patch context no longer matches.
+
+Recommended: rerun with `--3way` (3-way merge) so you get conflict markers to resolve.
+
+### “already exists in working directory”
+
+This often happens when a commit (especially “new file”) was already folded into the monorepo history.
+
+The tool auto-skips:
+- patches that are already present (exact-match reverse apply check)
+- pure new-file patches when the target already contains identical content
+
+If you still hit this manually during a stopped `git am`, decide whether to:
+- keep the existing file and `git am --skip`, or
+- reconcile content and continue.
+
+### Missing file path errors
+
+If the patch references files that no longer exist (or moved) in the monorepo, you’ll need to:
+- map the change to the new file location, or
+- skip that patch if it’s obsolete.
+
+Use `git am --show-current-patch=diff` to understand intent, then implement the equivalent change in the monorepo layout and continue.
+
+## Optional: audit mode (best-effort report)
+
+If you want a full report of what would apply vs fail (without stopping at the first conflict), you can run:
+
+```bash
+happys monorepo port ... --continue-on-failure --json
+```
+
+This is **not** the recommended way to produce a final clean branch, but it can be useful to:
+- discover the full set of expected conflicts
+- share a machine-readable report for assistance

package/docs/server-flavors.md

@@ -4,7 +4,21 @@ Happy Stacks supports two server “flavors”. You can switch between them glob
 
 ## What’s the difference?
 
-Both are forks/flavors of the same upstream server repo (`slopus/happy-server`), but optimized for different use cases:
+Both are forks/flavors of the same upstream server repo (`slopus/happy-server`), but optimized for different use cases.
+
+### Unified codebase (recommended)
+
+When your `happy-server` checkout includes the light flavor artifacts (notably `prisma/sqlite/schema.prisma` — legacy: `prisma/schema.sqlite.prisma`), Happy Stacks treats it as a **single unified server codebase** that supports both:
+
+- `happy-server` (full / Postgres+Redis+S3)
+- `happy-server-light` (light / SQLite+local files, can serve UI)
+
+In that setup:
+
+- there is **no server code duplication**
+- `happy-server-light` can point at the **same checkout/worktree** as `happy-server`
+- `happys stack new` will default to pinning **both** server component dirs to the same path
+- `happys start/dev --server=happy-server-light` will run `start:light` / `dev:light` when available
 
 - **`happy-server-light`** (recommended default)
   - optimized for local usage
@@ -73,7 +87,7 @@ Notes:
 - **`happys start`** is “production-like”. It avoids running heavyweight schema sync loops under launchd KeepAlive.
 - **`happys dev`** is for rapid iteration:
   - for `happy-server`: Happy Stacks runs `prisma migrate deploy` by default (configurable via `HAPPY_STACKS_PRISMA_MIGRATE`).
-  - for `happy-server-light`: the upstream dev script runs `prisma db push` by default (configurable via `HAPPY_STACKS_PRISMA_PUSH`).
+  - for `happy-server-light`: Happy Stacks runs `prisma migrate deploy` (SQLite migrations) using the unified schema under `prisma/sqlite/schema.prisma`.
 
 Important: for a given run (`happys start` / `happys dev`) you choose **one** flavor.
 
@@ -125,7 +139,9 @@ There are two separate concepts:
   - controlled by `HAPPY_STACKS_COMPONENT_DIR_HAPPY_SERVER_LIGHT` and `HAPPY_STACKS_COMPONENT_DIR_HAPPY_SERVER`
   - easiest via `happys wt use happy-server-light ...` / `happys wt use happy-server ...`
 
-If you set `HAPPY_STACKS_SERVER_COMPONENT=happy-server-light` but accidentally point the *server-light component dir* at a `happy-server` worktree (or vice versa), `happys start/dev/doctor` will refuse to run and print a fix hint.
+If you set `HAPPY_STACKS_SERVER_COMPONENT=happy-server-light` but accidentally point the *server-light component dir* at a postgres-only `happy-server` checkout (or vice versa), `happys start/dev/doctor` will refuse to run and print a fix hint.
+
+In unified mode (same repo supports both flavors), it is valid (and recommended) for both component dirs to point at the same checkout.
 
 `happys wt use` also prevents the most common mismatch when selecting server worktrees inside `components/` / `components/.worktrees/`.
 

package/docs/stacks.md

@@ -238,6 +238,41 @@ Cloned-repo fallback (before you run `happys init`):
 2. `<repo>/env.local` (optional overrides)
 3. `HAPPY_STACKS_ENV_FILE` (stack env)
 
+## Manage per-stack environment variables (including API keys)
+
+To add/update environment variables in a stack env file from the CLI:
+
+```bash
+happys stack env <stack> set KEY=VALUE [KEY2=VALUE2...]
+```
+
+To remove keys:
+
+```bash
+happys stack env <stack> unset KEY [KEY2...]
+```
+
+To inspect:
+
+```bash
+happys stack env <stack> get KEY
+happys stack env <stack> list
+happys stack env <stack> path
+```
+
+Notes:
+
+- This is the recommended place for **provider API keys** the daemon needs (example: `OPENAI_API_KEY`).
+- Changes apply on the **next start** of the stack/daemon. Restart to pick them up:
+  - `main`: `happys start --restart`
+  - named stack: `happys stack start <stack> -- --restart` (or `happys stack dev <stack> -- --restart`)
+
+Self-host shortcut (defaults to `main` when not running under a stack wrapper):
+
+```bash
+happys env set OPENAI_API_KEY=sk-...
+```
+
 ## Daemon auth + “no machine” on first run
 
 On a **fresh machine** (or any new stack), the daemon may need to authenticate before it can register a “machine”.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "happy-stacks",
   "type": "module",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "packageManager": "pnpm@10.18.3",
   "bin": {
     "happys": "./bin/happys.mjs",

package/scripts/auth.mjs

@@ -16,6 +16,7 @@ import { dirname } from 'node:path';
 import { parseEnvToObject } from './utils/env/dotenv.mjs';
 import { ensureDepsInstalled, pmExecBin } from './utils/proc/pm.mjs';
 import { applyHappyServerMigrations, ensureHappyServerManagedInfra } from './utils/server/infra/happy_server_infra.mjs';
+import { resolvePrismaClientImportForServerComponent, resolveServerLightPrismaMigrateDeployArgs } from './utils/server/flavor_scripts.mjs';
 import { clearDevAuthKey, readDevAuthKey, writeDevAuthKey } from './utils/auth/dev_key.mjs';
 import { getExpoStatePaths, isStateProcessRunning } from './utils/expo/expo.mjs';
 import { resolveAuthSeedFromEnv } from './utils/stack/startup.mjs';
@@ -227,6 +228,15 @@ async function seedAccountsFromSourceDbToTargetDb({
   const sourceCwd = resolveServerComponentDir({ rootDir, serverComponent: fromServerComponent });
   const targetCwd = resolveServerComponentDir({ rootDir, serverComponent: targetServerComponent });
 
+  const sourceClientImport = resolvePrismaClientImportForServerComponent({
+    serverComponentName: fromServerComponent,
+    serverDir: sourceCwd,
+  });
+  const targetClientImport = resolvePrismaClientImportForServerComponent({
+    serverComponentName: targetServerComponent,
+    serverDir: targetCwd,
+  });
+
   const listScript = `
 process.on('uncaughtException', (e) => {
   console.error(e instanceof Error ? e.message : String(e));
@@ -236,7 +246,11 @@ process.on('unhandledRejection', (e) => {
   console.error(e instanceof Error ? e.message : String(e));
   process.exit(1);
 });
-import { PrismaClient } from '@prisma/client';
+const mod = await import(${JSON.stringify(sourceClientImport)});
+const PrismaClient = mod?.PrismaClient ?? mod?.default?.PrismaClient;
+if (!PrismaClient) {
+  throw new Error('Failed to load PrismaClient for DB seed (source).');
+}
 const db = new PrismaClient();
 try {
   const accounts = await db.account.findMany({ select: { id: true, publicKey: true } });
@@ -255,7 +269,11 @@ process.on('unhandledRejection', (e) => {
   console.error(e instanceof Error ? e.message : String(e));
   process.exit(1);
 });
-import { PrismaClient } from '@prisma/client';
+const mod = await import(${JSON.stringify(targetClientImport)});
+const PrismaClient = mod?.PrismaClient ?? mod?.default?.PrismaClient;
+if (!PrismaClient) {
+  throw new Error('Failed to load PrismaClient for DB seed (target).');
+}
 import fs from 'node:fs';
 const FORCE = ${force ? 'true' : 'false'};
 const raw = fs.readFileSync(0, 'utf8').trim();
@@ -633,7 +651,7 @@ async function cmdCopyFrom({ argv, json }) {
           await pmExecBin({
             dir: serverDirForPrisma,
             bin: 'prisma',
-            args: ['db', 'push'],
+            args: resolveServerLightPrismaMigrateDeployArgs({ serverDir: serverDirForPrisma }),
             env: { ...process.env, DATABASE_URL: targetDatabaseUrl },
             quiet: json,
           }).catch(() => {});

package/scripts/build.mjs

@@ -15,7 +15,7 @@ import { getInvokedCwd, inferComponentFromCwd } from './utils/cli/cwd_scope.mjs'
  * Build a lightweight static web UI bundle (no Expo dev server).
  *
  * Output directory default: ~/.happy/stacks/main/ui (legacy: ~/.happy/local/ui)
- * Server will serve it at / when HAPPY_SERVER_LIGHT_UI_DIR is set.
+ * Server will serve it at / when HAPPY_SERVER_UI_DIR is set.
  * (Legacy /ui paths are redirected to /.)
  */