@happier-dev/stack 0.1.0-preview.5.1

package/docs/mobile-ios.md

@@ -0,0 +1,322 @@
+# Mobile app development (iOS)
+
+This is optional. Most people can use the served web UI on mobile via Tailscale:
+see the “Using Happier from your phone” section in the main README.
+
+## Prereqs (one-time)
+
+- Xcode installed
+- CocoaPods installed (`brew install cocoapods`)
+
+## Two supported modes
+
+- **Shared dev-client app** (recommended for development):
+  - Install *one* hstack dev-client 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).
+
+- **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)
+
+If you ran `hstack setup --profile=dev`, the setup wizard can optionally offer to install the dev-client for you.
+
+Install the dedicated hstack dev-client app on your iPhone (USB).
+
+This command **runs a prebuild** (generates `ios/` + runs CocoaPods) and then installs a Debug build
+without starting Metro:
+
+```bash
+hstack mobile-dev-client --install
+```
+
+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
+hstack stack mobile-dev-client <stack> --install
+```
+
+Optional:
+
+```bash
+hstack mobile-dev-client --install --device="Your iPhone"
+hstack mobile-dev-client --install --clean
+```
+
+Then run any stack with mobile enabled:
+
+```bash
+hstack stack dev <stack> --mobile
+# or:
+hstack dev --mobile
+```
+
+Notes:
+
+- **LAN requirement**: for physical iPhones, Metro must be reachable over LAN.
+  - hstack defaults to `lan` for mobile, and will print a QR code + deep link.
+  - For simulators you can usually use `localhost` (see `HAPPIER_STACK_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
+hstack stack mobile:install <stack> --name="Happier (<stack>)"
+hstack stack mobile:install <stack> --name="Happier PR 272" --device="Your iPhone"
+```
+
+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
+- `apps/ui/ios/` was deleted
+- you hit CocoaPods / deployment-target mismatches after a dependency bump
+
+Run:
+
+```bash
+hstack mobile --prebuild
+# (optional) fully regenerate ios/:
+hstack mobile --prebuild --clean
+```
+
+What this does today:
+
+- 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:
+  - `hstack mobile-dev-client --install`
+  - `hstack stack mobile:install <stack>`
+  already include `--prebuild`.
+- Legacy alias: `hstack mobile:prebuild` exists (hidden), but prefer `hstack mobile --prebuild`.
+
+## Manual `hstack mobile` usage (advanced)
+
+If you want to work on the embedded Expo app directly (outside `hstack dev --mobile`), `hstack mobile` supports:
+
+```bash
+# Start Metro (keeps running):
+hstack mobile --host=lan
+
+# Build + install on iOS (and exit). If you omit --device, it will try to auto-pick a connected iPhone over USB:
+hstack mobile --prebuild --run-ios --device="Your iPhone"
+hstack mobile --prebuild --run-ios --configuration=Release --no-metro
+```
+
+## Notes / troubleshooting
+
+- **QR opens the wrong app**:
+  - The dev-client QR uses the `HAPPIER_STACK_DEV_CLIENT_SCHEME` (default: `hstack-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
+hstack mobile:devices
+```
+
+- **Code signing weirdness on a real iPhone**:
+  - hstack 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 `hstack mobile ...` / `hstack stack mobile <stack> ...`.
+
+## Bake the default server URL into the app (optional)
+
+If you want the built app to default to your hstack server URL, set this **when building**:
+
+```bash
+HAPPIER_STACK_SERVER_URL="https://<your-machine>.<tailnet>.ts.net" hstack mobile-dev-client --install
+```
+
+Note: changing `HAPPIER_STACK_SERVER_URL` requires rebuilding/reinstalling the app you care about.
+
+Important:
+
+- For **non-main stacks**, `HAPPIER_STACK_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)
+
+hstack uses these identities:
+
+- **Dev-client**: defaults to `Happier Dev` + bundle id `dev.happier.stack.dev.<user>`
+- **Per-stack release**: defaults to `Happier (<stack>)` + bundle id `dev.happier.stack.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 bundle id you’re using isn’t available/owned by your Apple team.
+
+```bash
+HAPPIER_STACK_IOS_BUNDLE_ID="com.yourname.hstack.dev" hstack mobile --prebuild --run-ios --no-metro
+```
+
+- **App name (what shows on the home screen)**:
+
+```bash
+HAPPIER_STACK_IOS_APP_NAME="hstack" hstack mobile --prebuild --run-ios --no-metro
+```
+
+## Suggested env (recommended)
+
+Add these to your main stack env file (`~/.happier/stacks/main/env`) (or `~/.happier-stack/env.local` for global overrides) so you don’t have to prefix every command:
+
+```bash
+# How the phone reaches Metro:
+# - lan: recommended for real devices
+# - localhost: OK for simulators
+HAPPIER_STACK_MOBILE_HOST="lan"
+
+# (optional) default scheme used in the dev-client QR / deep link
+# (must match your installed dev-client app):
+HAPPIER_STACK_DEV_CLIENT_SCHEME="hstack-dev"
+
+# Default public server URL for the stack (baked into the Expo app config):
+HAPPIER_STACK_SERVER_URL="https://<your-machine>.<tailnet>.ts.net"
+
+# Optional: home screen name:
+HAPPIER_STACK_IOS_APP_NAME="Happier"
+```
+
+## EAS builds per stack (production / App Store-like)
+
+This section documents the end-to-end workflow for producing a **fully working** EAS Build (cloud) for a stack,
+with a **custom bundle id + app name** (example: `dev.happier.app` / `Happier`), while keeping upstream defaults unchanged when env vars are unset.
+
+### Overview
+
+To get a reliable EAS build for a stack-specific app identity, you generally need:
+
+- a **Happier monorepo worktree** that contains the app config hooks (dynamic `app.config.js`)
+- a stack pinned to that worktree (`hstack stack wt <stack> -- use ...`)
+- stack env vars describing the **app identity** (bundle id, name, scheme, etc.)
+- EAS **environment variables** configured on Expo (so the cloud builder sees the same values)
+- an initial **interactive** credentials setup (iOS signing) before non-interactive builds work
+- for identity changes: run **prebuild** so `ios/` + `android/` native projects reflect the new id
+
+### 1) Create (or select) a stack + pin a worktree
+
+Example stack name: `happier`.
+
+Create a `happy` monorepo worktree from your fork branch (example):
+
+```bash
+hstack wt new happy happier --from=origin --base=origin/happier
+```
+
+Pin the `happier` stack to that worktree:
+
+```bash
+hstack stack wt happier -- use happier-dev/happier
+```
+
+### 2) Set the app identity in the stack env (local + build-time config)
+
+These are evaluated by `apps/ui/app.config.js` when building:
+
+```bash
+hstack stack env happier set \
+  APP_ENV=production \
+  EXPO_APP_NAME="Happier" \
+  EXPO_APP_BUNDLE_ID="dev.happier.app" \
+  EXPO_APP_SCHEME="happier" \
+  EXPO_APP_SLUG="happier" \
+  EXPO_APP_OWNER="happier-dev"
+```
+
+Notes:
+
+- `APP_ENV` drives the built-in variant logic (development/preview/production).
+- `EXPO_APP_*` overrides keep upstream defaults intact when unset.
+
+### 3) Regenerate native projects (“prebuild”) when changing identity
+
+When changing bundle IDs / schemes / config plugins, you should run a clean prebuild so native projects match the config:
+
+```bash
+hstack stack mobile happier --prebuild --platform=ios --clean --no-metro
+# or:
+hstack stack mobile happier --prebuild --platform=all --clean --no-metro
+```
+
+### 4) Make sure the cloud builder sees your env vars (EAS Environment Variables)
+
+Cloud builds do **not** automatically inherit your local shell env.
+You must configure EAS Environment Variables on Expo (project settings) and ensure your build profile selects an environment.
+
+The EAS project env var workflow:
+
+1) Ensure your `eas.json` build profiles set `"environment": "production"` / `"preview"` / `"development"`.
+2) Create env vars in EAS for that environment (plain text or sensitive so config resolution can read them).
+
+With hstack helpers (stack-scoped):
+
+```bash
+# Inspect:
+hstack stack eas happier env:list --environment production
+
+# Create (use env:update if it already exists):
+hstack stack eas happier env:create --name EXPO_APP_NAME --value "Happier" --environment production --visibility plainText
+hstack stack eas happier env:create --name EXPO_APP_BUNDLE_ID --value "dev.happier.app" --environment production --visibility plainText
+hstack stack eas happier env:create --name EXPO_APP_SCHEME --value "happier" --environment production --visibility plainText
+hstack stack eas happier env:create --name EXPO_APP_OWNER --value "happier-dev" --environment production --visibility plainText
+hstack stack eas happier env:create --name EXPO_APP_SLUG --value "happier" --environment production --visibility plainText
+```
+
+Tip:
+
+- If you see “No environment variables with visibility Plain text and Sensitive found…”, it means your EAS environment variables are missing (or set to `secret`).
+
+### 5) EAS project + account sanity checks
+
+If you see permission errors, verify the Expo account:
+
+```bash
+hstack stack eas happier whoami
+hstack stack eas happier login
+```
+
+If the project is not initialized/linked under your account yet:
+
+```bash
+hstack stack eas happier project:init
+```
+
+### 6) Build (iOS / Android)
+
+First-time iOS credential setup usually requires interactive mode:
+
+```bash
+hstack stack eas happier ios --profile production --interactive
+```
+
+After credentials are set up, you can run non-interactive builds:
+
+```bash
+hstack stack eas happier ios --profile production --no-wait --non-interactive
+hstack stack eas happier android --profile production --no-wait --non-interactive
+```
+
+### Common pitfalls
+
+- **`eas.json is not valid` / `"build.base" must be of type object`**:
+  - your `eas.json` is using an old schema; update `build.base` to an object and use `"extends": "base"`.
+- **`Credentials are not set up. Run this command again in interactive mode.`**:
+  - run the same build with `--interactive` once to configure iOS signing.
+- **Cloud build doesn’t see stack env vars**:
+  - set EAS environment variables (project settings) and make sure your profile has `"environment": "production"`.

package/docs/monorepo-migration.md

@@ -0,0 +1,20 @@
+# Monorepo migration (legacy)
+
+hstack is **monorepo-only** today, but it still ships a helper (`hstack monorepo port`) that can be used to port commits from legacy split repos into the Happier monorepo.
+
+Current monorepo service layout:
+
+- `apps/ui`
+- `apps/cli`
+- `apps/server`
+
+If you’re migrating old work, start here:
+
+```bash
+hstack monorepo port --help
+```
+
+Notes:
+
+- Prefer doing ports in a dedicated worktree (`hstack wt new ...`) and validating in an isolated stack (`hstack stack new ...`).
+- If you don’t need this, you can ignore it; it exists only for historical migrations.

package/docs/paths-and-env.md

@@ -0,0 +1,154 @@
+# Paths, folders, and env precedence
+
+This doc explains the **directories** that hstack uses (home/workspace/runtime/stacks), and the **environment file precedence** used by `hstack`.
+
+If you’re ever unsure what your machine is actually using, run:
+
+```bash
+hstack where
+```
+
+---
+
+## Quick glossary
+
+- **CLI root dir**
+  - The directory containing the `@happier-dev/stack` scripts (`scripts/*.mjs`) that your `hstack` command is currently executing.
+  - This is *not* necessarily your current shell `cwd`.
+  - It can be:
+    - a cloned repo checkout (e.g. `/Users/<you>/.../happier-dev`), or
+    - the installed runtime package under `~/.happier-stack/runtime/node_modules/@happier-dev/stack` (see “Runtime dir”).
+
+- **Home dir** (`HAPPIER_STACK_HOME_DIR`)
+  - Default: `~/.happier-stack`
+  - Stores **global user config** + caches, and may include a runtime install.
+
+- **Runtime dir** (`HAPPIER_STACK_RUNTIME_DIR`)
+  - Default: `~/.happier-stack/runtime`
+  - Used by `hstack self update` to install/upgrade a pinned `@happier-dev/stack` runtime package.
+
+- **Workspace dir** (`HAPPIER_STACK_WORKSPACE_DIR`)
+  - Default: `~/.happier-stack/workspace` (when it exists).
+  - This is the **storage workspace for the Happier monorepo checkout + worktrees** used by hstack.
+  - It typically contains:
+    - `<workspace>/main` (stable monorepo checkout)
+    - `<workspace>/dev` (dev monorepo checkout; created by `hstack setup --profile=dev`)
+    - `<workspace>/pr/...` (PR worktrees)
+    - `<workspace>/local/<owner>/...` (local worktrees)
+    - `<workspace>/tmp/<owner>/...` (temporary worktrees)
+
+- **Repo dir** (`HAPPIER_STACK_REPO_DIR`)
+  - Default: `<workspace>/main`
+  - This is the active Happier monorepo checkout (either `main`, `dev`, or a worktree).
+  - `hstack wt use ...` and `hstack stack wt <stack> -- use ...` update this value.
+
+- **Worktrees**
+  - PRs: `<workspace>/pr/...`
+  - locals: `<workspace>/local/<owner>/...`
+  - tmp: `<workspace>/tmp/<owner>/...`
+
+- **Stacks storage dir**
+  - Default: `~/.happier/stacks`
+  - Each stack lives under `~/.happier/stacks/<name>/...` and has its own env file:
+    - `~/.happier/stacks/<name>/env`
+
+---
+
+## “Where am I actually running from?”
+
+`hstack` may **re-exec** to a different CLI root dir (for example, when you use an installed shim but want it to run a local checkout).
+
+- Run `hstack where` to see:
+  - **rootDir** (CLI root dir)
+  - **homeDir** (stacks home dir)
+  - **runtimeDir**
+  - **workspaceDir**
+  - resolved env file paths
+
+Tip: to pin the shim to a local checkout, use:
+
+```bash
+hstack self use-cli dev
+```
+
+Tip: `hstack where --json` is easier to parse.
+
+---
+
+## Env files + precedence (lowest → highest)
+
+hstack loads env in `scripts/utils/env.mjs`.
+
+### 0) “Canonical pointer” env (discovery)
+
+If `HAPPIER_STACK_HOME_DIR` is *not* set, we first try to read the **canonical pointer** env file to discover the intended home dir (useful for LaunchAgents / SwiftBar / minimal shells).
+
+- Default canonical pointer path: `~/.happier-stack/.env`
+- Override canonical pointer location:
+  - `HAPPIER_STACK_CANONICAL_HOME_DIR=/some/dir` (pointer becomes `<dir>/.env`)
+
+### 1) Global defaults (home config) OR cloned-repo defaults
+
+If home config exists, we load:
+
+- `~/.happier-stack/.env` (**defaults**)
+- `~/.happier-stack/env.local` (**overrides**, prefix-aware for `HAPPIER_STACK_*`)
+
+If home config does *not* exist (cloned repo usage before `hstack init`), we load:
+
+- `<cliRootDir>/.env`
+- `<cliRootDir>/env.local` (prefix-aware for `HAPPIER_STACK_*`)
+
+### 2) Repo `.env` fallback (dev convenience)
+
+Even when home config exists, we also load:
+
+- `<cliRootDir>/.env` (non-overriding fallback)
+
+This exists so repo-local dev settings (example: `HAPPIER_CODEX_ACP_BIN`) can work without forcing everyone to duplicate them into `~/.happier-stack/env.local`.
+
+Notes:
+- This is a **fallback only** (`override: false`): it won’t stomp on values already provided by the environment or home config.
+- We intentionally do **not** auto-load `<cliRootDir>/env.local` in this “home config exists” path, because it’s higher-precedence and can unexpectedly fight stack config.
+
+### 3) Stack env overlay (highest precedence)
+
+Finally, we load the active stack env file (override = true):
+
+- `HAPPIER_STACK_ENV_FILE`
+- if neither is set, we auto-select the env file for the current stack (defaults to `main`) if it exists
+
+Stack env files are allowed to contain **non-prefixed keys** (like `DATABASE_URL`) because that’s required for per-stack isolation.
+
+---
+
+## What should go where? (rules of thumb)
+
+- Put **global, machine-wide defaults** in `~/.happier-stack/.env`.
+- Put **your personal overrides** in `~/.happier-stack/env.local`.
+- Put **per-stack isolation config** in the stack env file `~/.happier/stacks/<name>/env` (this is what `hstack stack edit` and `hstack stack wt` mutate).
+- Put **repo-local dev-only defaults** in `<cliRootDir>/.env` (works best when you’re actually running from that checkout as the CLI root dir).
+
+---
+
+## Sandbox / test installs (fully isolated)
+
+If you want to test the full install + setup flows without touching your real installation, run with:
+
+```bash
+npx @happier-dev/stack@latest --sandbox-dir /tmp/hstack-sandbox where
+```
+
+In sandbox mode, hstack redirects **home/workspace/runtime/storage** under the sandbox folder (so you can `rm -rf` it to reset).
+
+Global OS side effects (PATH edits, SwiftBar plugin install, LaunchAgents/systemd services) are **disabled by default** in sandbox mode.
+To explicitly allow them for testing, set:
+
+- `HAPPIER_STACK_SANDBOX_ALLOW_GLOBAL=1`
+
+---
+
+## Related docs
+
+- `docs/stacks.md` (stacks lifecycle + commands)
+- `docs/worktrees-and-forks.md` (worktrees layout + upstream/fork workflows)

package/docs/remote-access.md

@@ -0,0 +1,43 @@
+# Remote access (Tailscale + phone)
+
+Happier relies on “secure context” browser features (WebCrypto). Browsers treat `http://localhost` as a secure context, but **not** `http://<lan-ip>:<port>` or `http://<tailscale-ip>:<port>`.
+
+For remote access (phone, another laptop, etc) you should use **HTTPS**.
+
+The recommended approach is **Tailscale Serve**, which gives you an `https://*.ts.net` URL for your machine that is only accessible inside your tailnet.
+
+## Quickstart
+
+1) Install Tailscale and sign in on your computer.
+
+2) Enable Serve:
+
+```bash
+hstack tailscale enable
+hstack tailscale url
+```
+
+3) Open the URL from `hstack tailscale url` on another device (also signed into Tailscale).
+
+Tip: on iOS, you can “Add to Home Screen” from Safari to use it like an app.
+
+## Automation
+
+If Serve is already configured, `hstack start` will automatically prefer the `https://*.ts.net` URL for “public” links unless you explicitly set `HAPPIER_STACK_SERVER_URL`.
+
+You can also ask hstack to enable Serve automatically at boot:
+
+```bash
+HAPPIER_STACK_TAILSCALE_SERVE=1 hstack start
+```
+
+Useful knobs:
+- `HAPPIER_STACK_TAILSCALE_WAIT_MS`
+- `HAPPIER_STACK_TAILSCALE_BIN`
+
+## Using the native Happier mobile app (optional)
+
+The native Happier mobile app has an “API Endpoint” setting (developer mode).
+Point it at the same HTTPS `*.ts.net` URL to use your local server.
+
+However, the simplest option is usually the **served web UI** (no app updates needed).

package/docs/server-flavors.md

@@ -0,0 +1,147 @@
+# Server flavors: `happier-server-light` vs `happier-server`
+
+hstack supports two server “flavors”. You can switch between them globally (main stack) or per stack.
+
+## What’s the difference?
+
+Both flavors use the **same server codebase** (the monorepo server package, typically `apps/server`), but run with different backends and storage assumptions.
+
+### `happier-server-light` (recommended default)
+
+- **No Docker required**
+- Uses **embedded Postgres via PGlite** (“PG_Light”) stored under the stack directory (per-stack isolation)
+- Stores local public files under the stack directory
+- Best choice for a stable “main” stack and quick local installs
+
+Light stacks are isolated by default:
+
+```
+~/.happier/stacks/<stack>/server-light/files
+~/.happier/stacks/<stack>/server-light/pglite
+```
+
+Key env vars (stored in the stack env file):
+
+- `HAPPIER_SERVER_LIGHT_DATA_DIR`
+- `HAPPIER_SERVER_LIGHT_FILES_DIR`
+- `HAPPIER_SERVER_LIGHT_DB_DIR`
+
+### `happier-server` (full server)
+
+- Docker-managed infra per stack (Postgres + Redis + Minio/S3)
+- Closer to “production-like” behavior
+- Useful when you need Redis/S3 semantics or want to reproduce full-server-only issues
+
+## Full server infra (no AWS required)
+
+`happier-server` requires:
+
+- Postgres (`DATABASE_URL`)
+- Redis (`REDIS_URL`)
+- S3-compatible object storage (`S3_*`)
+
+hstack can **manage this for you automatically per stack** using Docker Compose (Postgres + Redis + Minio),
+so you **do not need AWS S3**.
+
+This happens automatically when you run `hstack start/dev --server=happier-server` (or when a stack uses `happier-server`),
+unless you disable it with:
+
+```bash
+export HAPPIER_STACK_MANAGED_INFRA=0
+```
+
+If disabled, you must provide `DATABASE_URL`, `REDIS_URL`, and `S3_*` yourself.
+
+## UI serving with `happier-server`
+
+The upstream `happier-server` does not serve the built UI itself.
+
+For a “one URL” UX (especially with Tailscale), hstack starts a lightweight **UI gateway** that:
+
+- serves the built UI at `/` (if a build exists)
+- reverse-proxies API calls to the backend server
+- reverse-proxies realtime websocket upgrades (`/v1/updates`)
+- reverse-proxies public files (to local Minio)
+
+This means `hstack start --server=happier-server` can still work end-to-end without requiring AWS S3 or a separate nginx setup.
+
+## Migrating between flavors (PG_Light ⇢ Postgres)
+
+hstack includes an **experimental** migration helper that can copy core chat data from a
+`happier-server-light` stack (embedded PGlite) into a `happier-server` stack (Docker Postgres):
+
+```bash
+hstack migrate light-to-server --from-stack=main --to-stack=full1
+```
+
+Optional: include local public files (server-light `files/`) by mirroring them into Minio:
+
+```bash
+hstack migrate light-to-server --from-stack=main --to-stack=full1 --include-files
+```
+
+Notes:
+- This preserves IDs (session URLs remain valid on the target server).
+- It also copies the `HANDY_MASTER_SECRET` from the source stack into the target stack’s secret file so auth tokens remain valid.
+
+## Prisma behavior (why start is safer under LaunchAgents)
+
+- **`hstack start`** is “production-like”. It avoids running heavyweight schema sync loops under launchd KeepAlive.
+- **`hstack dev`** is for rapid iteration:
+  - for `happier-server`: hstack runs `prisma migrate deploy` by default (configurable via `HAPPIER_STACK_PRISMA_MIGRATE`).
+  - for `happier-server-light`:
+    - hstack runs the server package’s `migrate:light:deploy` script, which applies `prisma migrate deploy` against the **embedded PGlite DB** using the standard Postgres schema (`prisma/schema.prisma`).
+
+Important: for a given run (`hstack start` / `hstack dev`) you choose **one** flavor.
+
+## How to switch (main stack)
+
+Use the `srv` helper (persisted in `~/.happier/stacks/main/env` by default, or in your stack env file when using `hstack stack ...`):
+
+```bash
+hstack srv status
+hstack srv use happier-server-light
+hstack srv use happier-server
+hstack srv use --interactive
+```
+
+This persists `HAPPIER_STACK_SERVER_COMPONENT`.
+
+## How to switch for a specific stack
+
+Use the stack wrapper:
+
+```bash
+hstack stack srv exp1 -- status
+hstack stack srv exp1 -- use happier-server-light
+hstack stack srv exp1 -- use happier-server
+hstack stack srv exp1 -- use --interactive
+```
+
+This updates the stack env file (typically `~/.happier/stacks/<name>/env`).
+
+## One-off overrides (do not persist)
+
+You can override the server flavor for a single run:
+
+```bash
+hstack start --server=happier-server-light
+hstack start --server=happier-server
+
+hstack dev --server=happier-server-light
+hstack dev --server=happier-server
+```
+
+## Flavor vs repo selection
+
+There are two separate concepts:
+
+- **Flavor selection**: which server flavor hstack runs
+  - controlled by `HAPPIER_STACK_SERVER_COMPONENT` (via `hstack srv use ...`)
+- **Repo selection**: which monorepo checkout/worktree the stack runs from
+  - controlled by `HAPPIER_STACK_REPO_DIR` (via `hstack wt use ...` / `hstack stack wt <stack> -- use ...`)
+
+## SQLite note
+
+SQLite is **not** used by `happier-server-light` today (it is PG_Light via embedded PGlite). SQLite may be reintroduced later as an additional light flavor, but it is not part of the current default stack.
+