@happier-dev/stack 0.1.0-preview.5.1

package/docs/forking-and-branding.md

@@ -0,0 +1,189 @@
+## Forking + branding while staying upstream-compatible
+
+This doc describes a **recommended hstack workflow** for maintaining:
+
+- an **upstream-compatible** branch/worktree (no branding changes; safe to upstream later)
+- a **branded fork** branch/worktree (custom app name/bundle id/icons/Firebase/EAS, etc)
+
+The goal is to keep day-to-day development clean and to make syncing changes reliable.
+
+---
+
+## Core idea
+
+- **Do product/feature work on an upstream-compatible branch** (example: `happier-dev/dev`).
+- **Keep branding + fork-only config on a separate branch** (example: `happier-dev/happier`).
+- Periodically **merge** upstream-compatible changes into the branded fork branch.
+
+The branded branch should ideally contain only:
+
+- assets (icons/splash/logos)
+- configuration files that are *unavoidably different* (Firebase, EAS linkage)
+- optional small “glue” needed to make config configurable via environment variables
+
+Everything else should stay identical to the upstream-compatible branch so merges stay low-conflict.
+
+---
+
+## Golden rules (hstack)
+
+- **Do not develop in the stable checkout** (typically `<workspace>/main`). Use `<workspace>/dev` or worktrees under `<workspace>/{pr,local,tmp}/...`.
+- **Use `hstack` entrypoints** (not raw `yarn`, `expo`, etc) when you’re running stack/dev/build/test commands.
+- **Do not commit generated native directories** for Expo apps:
+  - `apps/ui/ios/`
+  - `apps/ui/android/`
+  These are generated by `expo prebuild` and should be treated as build artifacts.
+
+---
+
+## Recommended branch/worktree layout
+
+Example (Happier monorepo):
+
+- Upstream-compatible dev checkout:
+  - `<workspace>/dev`
+  - Branch: `dev`
+- Branded fork worktree (example):
+  - `<workspace>/local/<owner>/happier`
+  - Branch: `feature/happier-branding` (or similar)
+
+Pin your branded stack to the branded worktree (recommended):
+
+```bash
+hstack stack wt happier -- use local/happier
+```
+
+Keep your stable/main stack on defaults, and use `happier` (or another stack) for branded testing/building.
+
+---
+
+## How to keep merges low-conflict
+
+### Keep fork-only changes “small and isolated”
+
+Prefer fork-only changes to live in these buckets:
+
+- **Brand assets**:
+  - `apps/ui/sources/assets/images/*` (icon/splash/logo/favicon, etc)
+- **Fork-only identity/config** (when not configurable via env):
+  - Firebase files (`google-services.json`, `GoogleService-Info.plist`)
+  - EAS project linkage (projectId/updates URL/channel)
+
+Avoid sprinkling branding changes throughout core logic; it increases conflict surface area.
+
+### Prefer configuration via environment variables
+
+When possible, drive identity via environment variables so the upstream-compatible branch keeps upstream defaults.
+
+For Expo identity, a common pattern is:
+
+- Keep defaults in `app.config.js`
+- Allow overrides via generic Expo-style vars (examples):
+  - `EXPO_APP_NAME`
+  - `EXPO_APP_BUNDLE_ID`
+  - `EXPO_APP_SCHEME`
+  - `EXPO_APP_SLUG`
+  - `EXPO_APP_OWNER`
+  - `EXPO_EAS_PROJECT_ID`
+  - `EXPO_UPDATES_URL`
+  - `EXPO_UPDATES_CHANNEL`
+  - `EXPO_ANDROID_GOOGLE_SERVICES_FILE`
+  - `EXPO_IOS_GOOGLE_SERVICES_FILE`
+
+Then set those **per stack** (in the stack env file) so the behavior is isolated to your branded stack.
+
+---
+
+## Day-to-day workflow
+
+### 1) Do feature work on the upstream-compatible branch
+
+Work in:
+
+- `<workspace>/dev`
+
+Keep it upstream-friendly:
+
+- no branding changes
+- no fork-only credentials/config
+
+### 2) Periodically sync branded fork branch with upstream-compatible branch
+
+In the branded worktree:
+
+```bash
+hstack wt git happier-dev/happier -- merge happier-dev/dev
+```
+
+Resolve conflicts (if any), then continue.
+
+### When merges conflict
+
+Conflicts usually mean a file is changing in both branches.
+
+Best practice:
+
+- **Move shared “configurability logic” into `dev`**, so it only has to merge one way.
+- Keep branded values/assets in `happier`.
+
+If a file must remain fork-only and conflicts often, consider:
+
+- extracting brand-specific settings into separate files referenced by env, or
+- cherry-picking specific commits from `dev` instead of merging (for a short period), then returning to merges.
+
+---
+
+## Mobile + EAS specifics
+
+### Prebuild is local-only; don’t commit the generated dirs
+
+Local:
+
+```bash
+hstack stack mobile happier --prebuild --platform=ios --clean --no-metro
+```
+
+This regenerates `apps/ui/ios` and installs pods. Treat this as build output.
+
+### EAS builds are easiest when identity comes from env
+
+Use the EAS wrapper (stack-scoped):
+
+```bash
+hstack stack eas happier whoami
+hstack stack eas happier build --platform ios --profile production --no-wait
+```
+
+For cloud builds, ensure your EAS project has the correct environment variables configured on expo.dev (or in `eas.json` profile `env`).
+
+---
+
+## What should live only on the branded branch?
+
+As a rule:
+
+- **Yes (fork-only)**:
+  - icons/splashes/logos
+  - Firebase app configs (matching your bundle id/package)
+  - App Store / Play Store metadata
+  - any integrations that cannot reasonably be driven by env/config
+
+- **No (should stay shared / upstream-compatible)**:
+  - core app logic
+  - shared tooling changes (anything under `apps/stack/scripts/` that improves workflows)
+  - general configurability hooks (e.g. “support `EXPO_*` overrides”)
+
+---
+
+## Quick checklist
+
+- **Upstream-compatible branch (`dev`)**:
+  - can be upstreamed
+  - runs with upstream defaults
+  - minimal / no fork-only config
+
+- **Branded fork branch (`happier`)**:
+  - pinned to its own stack
+  - overrides identity via env
+  - contains only necessary fork-only files
+  - periodically merges from `dev`

package/docs/happy-development.md

@@ -0,0 +1,22 @@
+# Happier development (hstack)
+
+hstack is the recommended workflow for developing **Happier** locally.
+
+Key principles:
+
+- Use **repo worktrees** under `<workspace>/{pr,local,tmp}/...`
+- Keep `<workspace>/main` as the stable checkout (treat it as read-only)
+- Use `<workspace>/dev` as the default dev checkout (created by `hstack setup --profile=dev`)
+- Run feature work in isolated **stacks** (ports + dirs + env file)
+
+Quickstart (dev profile):
+
+```bash
+npx --yes -p @happier-dev/stack hstack setup --profile=dev
+```
+
+Common flows:
+
+- Worktrees: `docs/worktrees-and-forks.md`
+- Stacks: `docs/stacks.md`
+- Paths/env precedence: `docs/paths-and-env.md`

package/docs/isolated-linux-vm.md

@@ -0,0 +1,243 @@
+# Isolated Linux VM (Apple Silicon) for `review-pr`
+
+If you want to validate `hstack review-pr` on a **fresh system** (no existing `~/.happier-stack`, 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
+```
+
+### 1b) Automated E2E smoke test (optional)
+
+On your macOS host (this repo):
+
+```bash
+./scripts/provision/macos-lima-hstack-e2e.sh happy-e2e
+```
+
+What it validates (best-effort):
+- `hstack setup --profile=selfhost` in a fully isolated sandbox (no auth / tailscale / autostart / menubar)
+- server health endpoint (`/health`)
+- UI is served by server-light (`/` returns HTML)
+- monorepo worktree creation (`hstack wt new ...`)
+
+Notes:
+- This runs inside the VM (Linux) and uses `npx` by default.
+- You can pin the version under test: `HSTACK_VERSION=0.6.14 ./scripts/provision/macos-lima-hstack-e2e.sh happy-e2e`.
+- If you’re testing a fork, you can point the runner at your fork’s raw scripts:
+  `HSTACK_RAW_BASE=https://raw.githubusercontent.com/<owner>/<repo>/<ref>/apps/stack ./scripts/provision/macos-lima-hstack-e2e.sh happy-e2e`.
+- If you’re testing unpublished local changes, copy a packed tarball into the VM and run:
+  `HSTACK_TGZ=./happier-dev-stack-*.tgz /tmp/linux-ubuntu-e2e.sh`.
+
+### 2) Create + configure a VM (recommended script)
+
+On your macOS host (this repo):
+
+```bash
+./scripts/provision/macos-lima-happy-vm.sh happy-test
+```
+
+This creates the VM if needed and configures **localhost port forwarding** for the port ranges used by our VM defaults.
+(This is important because the Expo web app uses WebCrypto and needs a secure context like `http://localhost`.)
+
+It also sets a higher default VM memory size (to avoid Expo/Metro getting OOM-killed and exiting with `code=137`).
+Override if needed:
+
+```bash
+LIMA_MEMORY=12GiB ./scripts/provision/macos-lima-happy-vm.sh happy-test
+```
+
+Port ranges note:
+- `review-pr` runs in a **fully isolated sandbox** (separate hstack home dir), so VM defaults written to
+  `~/.happier-stack/env.local` inside the VM won’t be read automatically.
+- Prefer passing `--vm-ports` (or explicit `--stack-port-start=...`) to `review-pr` so the sandbox uses the forwarded ranges.
+
+### 2b) Manual setup (if you prefer)
+
+```bash
+limactl create --name happy-pr --tty=false template://ubuntu-24.04
+limactl start happy-pr
+```
+
+If you run `review-pr` (Expo web / Metro) inside the VM, **allocate enough memory** (recommend **8GiB+**).
+Edit `~/.lima/happy-pr/lima.yaml` on the macOS host and set:
+
+```yaml
+memory: "8GiB"
+```
+
+### 2c) Host access (ports + browser URLs)
+
+When you want to open Happier/Expo URLs in your macOS browser, **use localhost port forwarding**.
+
+Why this matters: the Expo web app uses WebCrypto (`crypto.subtle`) via `expo-crypto` for things like key derivation.
+Browsers only expose WebCrypto in **secure contexts**:
+- `https://...`
+- `http://localhost`, `http://127.0.0.1`, and `http://*.localhost`
+
+If you open the UI via a VM LAN IP like `http://192.168.x.y:PORT`, the browser treats it as **insecure** and you can hit errors like:
+`TypeError: Cannot read properties of undefined (reading 'digest')`.
+
+#### Configure port forwarding (recommended)
+
+Edit the instance config on the **macOS host**:
+
+```bash
+limactl stop happy-pr || true
+open -a TextEdit ~/.lima/happy-pr/lima.yaml
+```
+
+Add a `portForwards` section to forward the hstack VM port ranges to your host `localhost`:
+
+```yaml
+portForwards:
+  # Stack/server ports (default VM range from our provision script)
+  - guestPortRange: [13000, 13999]
+    hostPortRange:  [13000, 13999]
+
+  # Expo dev-server (web) ports (default VM range from our provision script)
+  - guestPortRange: [18000, 19099]
+    hostPortRange:  [18000, 19099]
+```
+
+Then restart the VM:
+
+```bash
+limactl start happy-pr
+```
+
+#### Optional: IP-based access (only when you need LAN)
+
+If you explicitly need to access guest services by VM IP (e.g. for testing from another device), you can enable `vzNAT`:
+
+```bash
+limactl stop happy-pr || true
+limactl start happy-pr --network vzNAT
+```
+
+Note: IP-based URLs (like `http://192.168...`) may break web-only crypto flows unless you use HTTPS or a browser dev override.
+
+### 3) Provision the VM (Node + build deps)
+
+```bash
+limactl shell happy-pr
+```
+
+Inside the VM:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/happier-dev/happier/main/apps/stack/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
+```
+
+### 3b) (Optional) Run the hstack dev setup wizard
+
+If your goal is to **work on changes** (not just review a PR), you can run the dev profile:
+
+```bash
+npx --yes -p @happier-dev/stack@latest hstack setup --profile=dev --bind=loopback
+```
+
+Notes:
+- This bootstraps a workspace (clones repos, installs deps, sets up worktrees/stacks tooling).
+- On Linux VMs you typically want `--no-mobile` workflows (iOS dev-client requires Xcode/macOS).
+
+### 4) Run `review-pr` via `npx` (published package)
+
+Inside the VM:
+
+```bash
+npx --yes -p @happier-dev/stack@latest hstack review-pr \
+  --repo=https://github.com/happier-dev/happier/pull/<PR_NUMBER> \
+  --vm-ports \
+  --no-mobile \
+  --keep-sandbox \
+  --verbose \
+  -- --bind=loopback
+```
+
+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 -p @happier-dev/stack@0.3.0 hstack review-pr ...`
+- `--vm-ports` forces the stack/server and Expo dev-server (web) ports into the forwarded VM ranges
+  (pairs with the `portForwards` config in this doc).
+
+### 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 `happier-dev-stack-*.tgz` into the VM (any method you like), then inside the VM:
+
+```bash
+npx --yes ./happier-dev-stack-*.tgz hstack 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/hstack.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.
+
+---
+
+## Resetting / starting fresh
+
+### Full reset (recommended): recreate the VM
+
+On the macOS host:
+
+```bash
+limactl stop happy-pr || true
+limactl delete happy-pr
+limactl create --name happy-pr --tty=false template:ubuntu-24.04
+limactl start happy-pr
+```
+
+Then re-run the provisioning step (Node + build deps) from this doc.
+
+### Soft reset: keep the VM, delete hstack state
+
+If you want a “clean-ish” rerun without recreating the VM, delete the hstack home + any workspace you chose:
+
+Inside the VM:
+
+```bash
+rm -rf ~/.happier-stack ~/.happier ~/.happy
+```
+
+Why these paths:
+- `~/.happier-stack`: stack runtime home (shims/runtime/cache/logs).
+- `~/.happier`: stack storage root (`~/.happier/stacks/<name>/...` env/state/data).
+- `~/.happy`: legacy pre-monorepo location that older migrations/import tooling may still reference.
+
+If you used `hstack setup --profile=dev` and picked a custom workspace directory (outside `~/.happier-stack/workspace`), delete that directory too.
+
+---
+
+## Notes / scope
+
+- This doc targets **web-only** validation (`--no-mobile`) on Ubuntu ARM64 VMs.
+- On-device iOS testing via `--mobile` requires a macOS host with Xcode (not possible inside the Linux VM).

package/docs/menubar.md

@@ -0,0 +1,244 @@
+# Menu bar (SwiftBar)
+
+`hstack` ships a macOS menu bar plugin powered by [SwiftBar](https://swiftbar.app/).
+
+SwiftBar runs a script on an interval and renders its output as native macOS menu items.
+
+## Features
+
+- **Status at a glance** with dynamic icons (green/orange/red)
+  - Server health
+  - Daemon status (PID + optional control server probe)
+  - Autostart LaunchAgent status
+  - Tailscale Serve status / URL (if configured)
+- **Quick controls**
+  - Start / stop / restart the stack
+  - Restart just the daemon (stack-safe)
+  - Install / enable / disable / uninstall autostart
+  - Enable / disable Tailscale Serve
+- **Details**
+  - PID, CPU %, RAM MB, uptime (where available)
+  - Useful URLs and file paths
+  - Stack details include aggregate CPU/RAM (server+daemon+autostart) when running
+  - Open logs in Console.app
+- **Refresh control**
+  - Manual refresh
+  - In-menu refresh interval toggles (includes slower intervals like 10m/15m/30m/1h/6h/12h/1d)
+  - Uses a small helper script (`extras/swiftbar/set-interval.sh`) to avoid SwiftBar quoting issues
+- **Stacks + services layout**
+  - Main stack is shown directly (no extra nesting level)
+  - Each stack shows service rows (Server/Daemon/Autostart/Tailscale) with per-service submenus
+- **Components (git/worktrees)**
+  - Available under a top-level **Components** submenu (to keep the main menu clean)
+  - Shows repo/worktree status for the active monorepo checkout (`<workspace>/main`, `<workspace>/dev`, or a worktree under `<workspace>/{pr,local,tmp}/...`)
+  - Each repo entry includes a **Worktrees** submenu listing all worktrees, with actions to switch/open
+  - Quick actions: `wt status/sync/update`, PR worktree prompt, open shells/editors (`wt shell/code/cursor`)
+  - Shows **origin** and **upstream** comparisons for the repo’s main branch (based on your last `git fetch`)
+  - Uses a **Git cache** by default so SwiftBar refresh stays fast even with many stacks/worktrees
+
+## Modes: selfhost vs dev
+
+The menu supports two modes:
+
+- **Selfhost mode** (`selfhost`): lightweight “control panel” for running Happier.
+  - Shows only the main stack essentials (Server/Daemon/Autostart/Tailscale) plus a small **Maintenance** section.
+  - Hides developer-oriented sections like stacks enumeration, git/worktrees, and worktree tooling.
+- **Dev mode** (`dev`): full stack control plane (stacks + git/worktrees + worktree tooling).
+
+### How to switch modes
+
+- In the menu, use the **Mode** section at the top, or
+- From a terminal:
+
+```bash
+hstack menubar mode selfhost
+hstack menubar mode dev
+```
+
+## Stacks (multiple instances)
+
+If you create additional stacks (see `docs/stacks.md`), the plugin shows:
+
+- **Main stack** (the default, stack name `main`)
+- **Stacks** section listing each stack found under `~/.happier/stacks/<name>/env`
+
+Each stack row renders the same “mini control panel” (server/daemon/autostart/logs + a few actions) with stack-specific ports, dirs, and LaunchAgent label.
+
+The menu also includes:
+
+- `stack new --interactive` (create stacks)
+- `stack edit <name> --interactive` (edit stack port/server flavor/repo checkout)
+- `stack wt <name> -- use --interactive` (switch the stack’s repo checkout/worktree)
+- “PR worktree into this stack (prompt)” (creates `wt pr ... --use` scoped to the stack env)
+
+## Worktrees (quick entry points)
+
+The menu also provides “jump off” actions for the worktree tooling:
+
+- `hstack wt use --interactive`
+- `hstack wt new --interactive`
+- `hstack wt sync-all`
+- `hstack wt update-all --dry-run` / `hstack wt update-all`
+- `hstack wt pr ...` (via an in-menu prompt)
+
+For stack-specific worktree selection (which worktree a stack uses), use:
+
+- `hstack stack edit <name> --interactive`
+  - or `hstack stack wt <name> -- use --interactive`
+
+### Note (worktree switching)
+
+Happier is a single monorepo, so switching worktrees is always a **repo-level** action. Use:
+
+- `hstack stack wt <name> -- use --interactive`
+
+## Implementation notes
+
+- **Entry script**: `extras/swiftbar/hstack.5s.sh` (installed into SwiftBar as `hstack.<interval>.sh`)
+- **Shared functions**: `extras/swiftbar/lib/*.sh` (sourced by the entry script)
+- **Helper scripts**:
+  - `extras/swiftbar/set-interval.sh`
+  - `extras/swiftbar/set-server-flavor.sh`
+
+## Install
+
+### 1) Install SwiftBar
+
+```bash
+brew install --cask swiftbar
+```
+
+### 2) Install the plugin
+
+```bash
+hstack menubar install
+```
+
+If you want a different default refresh interval at install time:
+
+```bash
+HAPPIER_STACK_SWIFTBAR_INTERVAL=15m hstack menubar install
+```
+
+### 3) Open the active SwiftBar plugin folder
+
+SwiftBar can be configured to use a custom plugin directory. To open the *active* one:
+
+```bash
+hstack menubar open
+```
+
+## Uninstall
+
+Remove the installed SwiftBar plugin files (does not delete your stacks/workspace):
+
+```bash
+hstack menubar uninstall
+```
+
+## How refresh works (important)
+
+SwiftBar’s refresh interval is controlled by the **filename** suffix:
+
+- `hstack.30s.sh` → every 30 seconds
+- `hstack.5m.sh` → every 5 minutes
+- `hstack.1h.sh` → every 1 hour
+
+The plugin defaults to a slower interval (recommended), and also sets:
+
+- `refreshOnOpen=false` (recommended) to avoid surprise refreshes while you’re navigating the menu.
+
+You can also change the interval directly from the menu via **Refresh interval** (it renames the plugin file and restarts SwiftBar).
+
+## Git cache (important for performance)
+
+Git/worktree inspection is the most expensive part of the menu when you have many stacks.
+By default, the plugin runs in **cached mode**:
+
+- It renders git/worktree info from an on-disk cache under `~/.happier-stack/cache/swiftbar/git`.
+- Normal menu refreshes do **not** run git commands (so refresh stays snappy).
+- The cache is refreshed explicitly (via menu actions), and can optionally refresh on TTL expiry.
+
+Controls and settings:
+
+- **Refresh now**: open **Components → Git cache** and run:
+  - “Refresh now (main components)”
+  - “Refresh now (all stacks/components)”
+  - or “Refresh now (this stack)” from a stack’s Components menu
+- **TTL**: `HAPPIER_STACK_SWIFTBAR_GIT_TTL_SEC` (default `21600` seconds = 6 hours)
+- **Mode**: `HAPPIER_STACK_SWIFTBAR_GIT_MODE=cached|live` (default `cached`)
+- (Optional) **Background auto-refresh**: `HAPPIER_STACK_SWIFTBAR_GIT_AUTO_REFRESH_SCOPE=main|all|off` (default `main`)
+
+Notes:
+
+- Cached git info can be stale; it’s meant for at-a-glance signal.
+- Actions like worktree switching/build/dev are always live (they use `hstack`); only *displayed git status* is cached.
+
+## Maintenance (selfhost mode)
+
+In **selfhost** mode, the menu includes a **Maintenance** section that can:
+
+- show whether a `hstack` update is available (from cached `~/.happier-stack/cache/update.json`)
+- run:
+  - `hstack self check`
+  - `hstack self update`
+
+## Terminal preference for interactive actions
+
+Many menu actions open a terminal (interactive wizards, long-running dev servers, etc).
+The plugin uses helper scripts so these run in your preferred terminal, using the same env var as `wt shell`:
+
+- `HAPPIER_STACK_WT_TERMINAL=auto|ghostty|iterm|terminal|current`
+
+Notes:
+- `auto` tries ghostty → iTerm → Terminal → current.
+- Ghostty is best-effort; if your Ghostty build can’t execute the command automatically, the command is copied to your clipboard and Ghostty is opened in the repo directory.
+
+## Start SwiftBar at login (optional)
+
+SwiftBar is independent from the hstack LaunchAgent/service.
+
+- In SwiftBar Preferences, enable **Launch at Login**, or
+- Add SwiftBar to macOS **Login Items**.
+
+## Troubleshooting
+
+### Plugin doesn’t show up
+
+- Ensure SwiftBar is running.
+- Check which plugin folder SwiftBar is using:
+  - SwiftBar → Preferences → Plugin Folder
+- Open the active folder:
+  - `hstack menubar open`
+
+### Daemon shows “auth required” / “no machine”
+
+This happens on a **fresh machine** (or any new stack) when the daemon does not yet have credentials in the
+stack-specific CLI home directory.
+
+**What’s going on**
+
+- The daemon stores credentials in `access.key` under the CLI home directory.
+- For stacks (including main), that’s typically:
+  - `~/.happier/stacks/<name>/cli/access.key`
+- When `access.key` is missing, `happy-cli daemon start` enters an interactive auth flow and won’t become a “machine” until it completes.
+  - Under `launchd` (autostart), this shows up as **no machine** and the daemon may appear “stopped”.
+
+**If it still needs auth**
+
+- In SwiftBar, open the **Daemon** section:
+  - If it shows `auth_required`, click **Auth login (opens browser)**
+- Or run manually:
+
+```bash
+hstack auth login
+```
+
+### “Daemon stale” even though it’s running
+
+The plugin checks:
+
+- `daemon.state.json` **PID is alive**, and
+- (optionally) the daemon control server responds.
+
+If the daemon is running but the menu is stale, refresh and check the **PID** line under “Daemon”.