l-demo-builds

Rebuild the local app install for the thin-launcher architecture — ROOT core (zudotext.app) by default, plus the debug LEAVES on request. Use when user says 'demo builds', 'build debug apps', 'l-demo-...

Refresh the local app install in ONE command via scripts/rebuild-local-apps.sh (pnpm rebuild:local-apps). No per-app argument.

Under the thin-launcher model (#2280/#2285) ROOT (zudotext.app) holds the ONE shared core (Contents/Frameworks/libzudotext_core.dylib) that embeds the renderer and all backend logic; the LEAVES are KB-scale stubs that point at ROOT's core via a Contents/Resources/core-path sidecar. ROOT runs the full writing app — so rebuilding ROOT alone is a complete local install for everyday testing.

[1/2] build ROOT     → scripts/build-root-thin.sh  (shared core cdylib + stub)
[2/2] install ROOT   → /Applications/zudotext.app   (move-aside + cp -R)
[3/3] stamp LEAVES   → ~/Applications/<name>.app    (ONLY with WITH_LEAVES=1)

The one expensive step is [1/2], the ROOT core build (minutes).

Why ROOT-only is the default (post cloud pivot)

Before the cloud pivot each LEAF pointed at its own local workspace directory, so the six LEAVES were six genuinely different apps and stamping them all was the point. Epic #4204 D14 retired local workspace directories: an app instance now binds to a cloud workspace via config.json v2 (renamed from "vault" by epic #4991 Wave 2), and every entry in build-debug-apps.sh's APP_LIST currently has a blank workspace id — meaning each stamped LEAF is unbound and boots to the same onboarding screen. Six identical onboarding stubs is cost without signal, so LEAF stamping became opt-in.

Stamp the LEAVES when you actually need them:

WITH_LEAVES=1 pnpm rebuild:local-apps

That is worth doing once you've minted real workspaces (pnpm generate <name> --genesis …) and filled their ids into APP_LIST, or when you're specifically testing the thin-launcher LEAF path itself (stub stamping, core-path resolution, per-app identity).

Why ROOT goes to `/Applications` (stable daily-driver path)

Each LEAF's core-path sidecar bakes ROOT's absolute path at stamp time, so the LEAVES must point at a stable location that survives cargo clean/rebuilds — NOT the volatile cargo-target bundle. rebuild-local-apps.sh installs ROOT to /Applications/zudotext.app, and in the WITH_LEAVES=1 path stamps every LEAF against it (it sets ZUDOTEXT_ROOT_APP=/Applications/zudotext.app for the inner build-debug-apps.sh). If ROOT is later moved or deleted, the LEAVES exit at launch with "shared core not found".

Available LEAF names

modmsg, prompts, pxg, worktext, zmod, writing — defined in scripts/build-debug-apps.sh APP_LIST as "name workspaceId" pairs (blank workspace id = unbound). There is no per-app workspace directory anymore; content comes from the bound cloud workspace. Note writing is also the dev-entry renderer name (pnpm writing:dev / tauri.conf.writing.json); the stamped writing.app is independent of the dev-entry build and does not conflict with it.

Instructions

Run from the project root — no argument parsing, ignore any app name in $ARGUMENTS:
```
pnpm rebuild:local-apps
```
Fast path (reuse an already-built ROOT): if ROOT was just built this session (e.g. pnpm tauri:build already ran), skip the multi-minute recompile and only reinstall:
```
SKIP_ROOT_BUILD=1 pnpm rebuild:local-apps
```
Timeout: allow several minutes for the full run (the ROOT core build dominates); the SKIP_ROOT_BUILD=1 path is seconds. WITH_LEAVES=1 adds seconds per LEAF, plus a one-time couple of minutes the first time it builds the stamp-leaf binary (cargo build --release --bin stamp-leaf).
Report success/failure from the script's exit code and printed lines. Relay the git HEAD: <sha> <subject> line and the installed core: <timestamp> line — the cheapest proof that the just-merged code made it into the core ROOT runs. With WITH_LEAVES=1, also relay the per-app ✓ Stamped and installed ~/Applications/<name>.app lines.

Single-LEAF re-stamp (power use, not this skill)

To stamp ONE LEAF against an already-built+installed ROOT, call the primitive directly:

ZUDOTEXT_ROOT_APP=/Applications/zudotext.app bash scripts/build-debug-apps.sh modmsg

Common failure modes

ROOT bundle missing (with SKIP_ROOT_BUILD=1) — Error: ROOT bundle not found at …/release/bundle/macos/zudotext.app. Drop SKIP_ROOT_BUILD=1 so the script builds ROOT first (macOS only).
ROOT build / stamp-leaf build fails (e.g. a Rust compile error or linker error after a dependency change). set -euo pipefail fails loudly — read the cargo output and fix the cause; do not blindly retry.
A stamped LEAF dies at launch with "shared core not found" — the ROOT it points at was moved or deleted. Re-run this skill (with WITH_LEAVES=1) so ROOT is reinstalled at /Applications/zudotext.app and the LEAVES are re-stamped against it.
A stamped LEAF boots to onboarding — expected when its APP_LIST workspace id is blank. Bind it to a real workspace (pnpm generate <name> --workspace-id <id>) or complete onboarding in the app.
First launch renders blank / a tiny window when a thin LEAF replaces a same-named prior install — the new stub inherits the old app's ~/Library/WebKit/com.takazudo.<name> + NSUserDefaults (keyed on the shared CFBundleIdentifier); incompatible persisted UI state can blank the renderer on the first launch. It self-heals on the second launch. Pre-release-acceptable (old persisted UI state is re-creatable per the root CLAUDE.md). For a clean first launch, clear the stale state first: defaults delete com.takazudo.<name>; trash ~/Library/WebKit/com.takazudo.<name>.