@geohar/un-bien 0.8.0 → 0.14.0

package/README.md

@@ -1,22 +1,20 @@
 > **Derived from [remote-pi](https://github.com/jacobaraujo7/remote_pi)** by Jacob
 > Moura, used under the MIT License (preserved in [`LICENSE`](LICENSE)). This tree
-> is part of the [un-bien](../README.md) monorepo and is mid-rework — the content
-> below still carries upstream branding and is being rebranded to un-bien.
+> is part of the [Un Bien](../README.md) monorepo.
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/georgeharker/un-bien/main/app/icons/un-bien-macos-1024.png" width="160" alt="un-bien logo" />
+  <img src="https://raw.githubusercontent.com/georgeharker/un-bien/main/app/icons/un-bien-macos-1024.png" width="160" alt="Un Bien logo" />
 </p>
 
-<h1 align="center">un-bien</h1>
+<h1 align="center">Un Bien</h1>
 
 > Extend the [Pi coding agent](https://github.com/earendil-works/pi) with two
-> superpowers: agents that talk to each other on the same machine, and a mobile
-> app that drives Pi from your phone.
+> superpowers: **remote-control Pi from your phone** (native iOS/macOS app over a
+> relay you host), and a **local agent mesh** where several Pi sessions talk to
+> each other.
 
-**Homepage:** <https://remote-pi.jacobmoura.work>
-
-`/remote-pi` is a single slash command that wires both at once. Run it; the
-first time it asks a couple of questions and you are done.
+`/unbien` is a single slash command that wires both at once. Run it; the first
+time it asks a couple of questions and you are done.
 
 ## Protocol & Security
 
@@ -32,22 +30,28 @@ document — this README only covers user-facing setup.
 Install the extension (one-time):
 
 ```bash
-pi install npm:remote-pi
+pi install npm:@geohar/un-bien
 ```
 
 Then in any Pi terminal:
 
 ```text
-/remote-pi
+/unbien
 ```
 
 The first run shows a short interactive wizard (agent name, default session,
-whether to auto-start the relay). On every following run, `/remote-pi` joins
-the local agent session and starts the relay automatically — no extra typing.
+whether to use the relay on this terminal). On every following run, `/unbien`
+joins the local agent session and starts the relay automatically — no extra
+typing.
+
+> **You must configure a relay before the mobile app can connect.** Un Bien ships
+> pointing at **nobody's** infrastructure — there is no built-in default relay.
+> Self-host one (see [The relay](#the-relay)) and point the extension at it with
+> `/unbien set-relay <url>`.
 
 ### Try the agent network in 30 seconds
 
-Open **two** Pi terminals in the same directory and run `/remote-pi` in each.
+Open **two** Pi terminals in the same directory and run `/unbien` in each.
 Both join the same session. Now just talk to the LLM — it has the tools.
 
 In terminal A (say it ended up named `agent-A`):
@@ -78,8 +82,7 @@ normalize it.
 
 ## What it does
 
-Remote Pi adds two independent layers on top of Pi. You can use either, or
-both:
+Un Bien adds two independent layers on top of Pi. You can use either, or both:
 
 ### 1) Agent network (local broker, optional cross-PC relay)
 
@@ -97,7 +100,7 @@ current turn, and receive any later reply through the inbox/turn flow with
 `re` correlating it to the original message id.
 
 Peers on the same machine talk over a Unix domain socket at
-`~/.pi/remote/sessions/<session-name>/broker.sock`. When sibling PCs are paired,
+`~/.local/state/un-bien/sessions/<session-name>/broker.sock`. When sibling PCs are paired,
 a leader-capable Extension or MCP participant bridges the opaque cross-PC
 addresses over the relay; local-only use stays on UDS when relay access is off.
 Useful for splitting work across roles (`backend`, `frontend`, `tests`,
@@ -109,22 +112,19 @@ over — the failover is invisible to the LLMs.
 
 ### 2) Mobile app (over the relay)
 
-The companion mobile app lets you send prompts to Pi and read its responses
-from your phone. The phone and the Pi process find each other through a
-**relay**: a small WebSocket server that ferries messages between them.
-Pairing is one-time and per device, via QR code.
+The companion native iOS/macOS app lets you **attach to a running Pi session — or
+launch a new one** — and drive it from your phone: send prompts, read responses,
+answer Pi's interactive prompts, and switch models. The phone and the Pi process
+find each other through a **relay**: a small WebSocket server that ferries
+messages between them. Pairing is one-time and per device, via QR code.
 
 Communication uses WebSocket over TLS to the relay. Fields such as `ct` are
 wire containers, not a systemwide end-to-end confidentiality guarantee: current
 Pi-forward, cross-PC, app, and control envelopes visible to the relay are not
 fully opaque or E2E encrypted. A relay operator can see routed plaintext
 protocol content and metadata; see [`rpc-envelope`](../docs/rpc-envelope.md) for the exact
-trust boundaries.
-
-**Get the app** — all current download options (Google Play, App Store, and
-direct builds while public releases roll out):
-
-<https://remote-pi.jacobmoura.work/#get-the-app>
+trust boundaries. **Host the relay yourself** to keep that operator role in your
+own hands.
 
 ---
 
@@ -150,23 +150,25 @@ under "App actions".
 It is **not** a generic slash-command picker. The Pi SDK does not expose
 programmatic invocation for most builtins (those live in the TUI's
 interactive loop), so the app exposes only the actions that have a clean
-SDK call. The [`pi-telegram`](https://github.com/llblab/pi-telegram) adapter
-follows the same pattern.
+SDK call.
 
 ### Images
 
-The app can attach **one image** (camera or gallery) to a message. It's
-compressed on the device and rides **inline** in the `user_message` — the
-optional `images` field carries `{ data: <base64>, mime }`. The pi-extension
-turns it into the SDK's multimodal content (an `ImageContent` followed by the
-caption `TextContent`) and calls `sendUserMessage(content)`, so the model sees
-the picture plus your text.
+Un Bien **displays images produced during a session** — when a tool or the agent
+emits an image, the extension surfaces it to the app as a preview (customType
+`un-bien:received-image`), capped at 10 MB.
+
+On the inbound side, the wire and extension also support **image ingest**: a
+`user_message` may carry an optional `images` field (`{ data: <base64>, mime }`),
+which the extension turns into the SDK's multimodal content (an `ImageContent`
+followed by the caption `TextContent`) and feeds to `sendUserMessage(content)`.
+The mobile app does **not** yet expose an attach control, so this path is
+available to clients but not surfaced in the app today.
 
 Whether a model accepts images is surfaced as a `vision` flag on each
-`WireModel` (derived from the SDK's `Model.input` including `"image"`); the app
-greys out the attach button when the active model is text-only.
+`WireModel` (derived from the SDK's `Model.input` including `"image"`).
 
-The **relay is unchanged** — the image travels inside the same application
+The **relay is unchanged** — an image travels inside the same application
 message container as the text, so there's no binary channel (large files are a
 future track). Base64 or a field named `ct` is not an E2E confidentiality
 boundary; the current Relay visibility follows the trust model above. Text-only
@@ -179,39 +181,39 @@ messages are unaffected.
 Requirements: Node 20+, Pi (the host coding agent).
 
 ```bash
-pi install npm:remote-pi
+pi install npm:@geohar/un-bien
 ```
 
-The extension self-registers the `/remote-pi` slash command and deploys an
+The extension self-registers the `/unbien` slash command and deploys an
 agent skill that teaches the LLM how to use `list_peers`, `agent_send`, and the
 event-driven inbox/reply flow.
 
 To verify:
 
 ```text
-/remote-pi config
+/unbien config
 ```
 
 It should print the effective relay URL and where it came from
-(`env` / `config` / `default`).
+(`env` / `config` / `unset`).
 
 ---
 
-## Using `/remote-pi`
+## Using `/unbien`
 
 The bare command is the everyday entry point:
 
 ```text
-/remote-pi
+/unbien
 ```
 
 Behavior depends on whether there's a local config for this directory:
 
-| State                                      | What happens                                                                             |
-| ------------------------------------------ | ---------------------------------------------------------------------------------------- |
-| First run (no `.pi/remote-pi/config.json`) | Interactive wizard → saves config → joins agent session → starts relay (if you opted in) |
-| Returning user, auto-start enabled         | Joins agent session + starts relay automatically, then prints status                     |
-| Returning user, auto-start disabled        | Prints status only; join/relay must be run manually                                      |
+| State                                    | What happens                                                                             |
+| ---------------------------------------- | ---------------------------------------------------------------------------------------- |
+| First run (no `.pi/un-bien/config.json`) | Interactive wizard → saves config → joins agent session → starts relay (if you opted in) |
+| Returning user, auto-start enabled       | Joins agent session + starts relay automatically, then prints status                     |
+| Returning user, auto-start disabled      | Prints status only; join/relay must be run manually                                      |
 
 The wizard asks three questions:
 
@@ -220,36 +222,36 @@ The wizard asks three questions:
    an address from this name. Defaults to the directory name.
 2. **Default session** — the name of the agent-network room for this
    directory. Multiple terminals in the same directory join the same session.
-3. **Auto-start relay (for mobile app access)?** — `Yes` if you want
-   `/remote-pi` to also connect to the relay so the mobile app can reach this
-   Pi. `No` for local-only use (agent network without mobile access).
+3. **Use the relay on this terminal?** — `Yes` if you want `/unbien` to also
+   connect to the relay so the mobile app (and paired PCs) can reach this Pi.
+   `No` for local-only use (agent network without mobile access).
 
-Re-run the wizard later with `/remote-pi setup`.
+Re-run the wizard later with `/unbien setup`.
 
 ---
 
 ## Pairing a mobile device
 
-Once the relay is up (`/remote-pi relay status` shows `started` or `paired`):
+Once the relay is up (`/unbien relay status` shows `started` or `paired`):
 
 ```text
-/remote-pi pair
+/unbien pair
 ```
 
-A QR code is printed in the terminal. Scan it with the Remote Pi mobile app.
+A QR code is printed in the terminal. Scan it with the Un Bien mobile app.
 Pairing is **per machine** — once a device is paired, every Pi process on
-this machine accepts it (it lives in `~/.pi/remote/peers.json`).
+this machine accepts it (it lives in `~/.local/state/un-bien/peers.json`).
 
 To list paired devices:
 
 ```text
-/remote-pi devices
+/unbien devices
 ```
 
 To remove one:
 
 ```text
-/remote-pi revoke <shortid>
+/unbien revoke <shortid>
 ```
 
 The shortid is the first 8 chars shown by `devices`.
@@ -259,60 +261,36 @@ The shortid is the first 8 chars shown by `devices`.
 ## The relay
 
 The relay is the network boundary. TLS protects transit, but the Relay can see
-routed plaintext protocol content and metadata; use a relay you trust or
-self-host. There is no systemwide or PC-mesh E2E guarantee. For Pi-to-Pi
+routed plaintext protocol content and metadata; **use a relay you trust or
+self-host**. There is no systemwide or PC-mesh E2E guarantee. For Pi-to-Pi
 forwarding, the Relay currently permits a route when any correctly signed Owner
 blob lists both canonical Pi keys. That does not prove the Owner paired with or
 controls either Pi.
 
-### Upgrade order (Relay 0.3 first, then Extension 0.6)
-
-Upgrade the **Relay to 0.3 first**: an old Extension can consume the new
-Relay's UUID errors. Extension 0.6 carries a one-release legacy wire-label
-shim, so mixed new/old Extensions interoperate when both select the same unique
-colon-free signed nickname label, or when neither has one and both use the
-canonical standard-padded key prefix. Delimiter or collision cases, like
-divergent nickname views, are unsupported and may be silently dropped by the
-old receiver. Upgrade all Extension/MCP participants in one maintenance window.
-The shim does not replace the receiver-local aliases returned by `list_peers`;
-addresses remain opaque.
-
-Extension 0.6 accepts an old Relay's lowercase 32-hex trusted error ID only as
-a narrow shim for an old Relay or Relay rollback; that shim is not why
-Relay-first is safe.
-
-You have two options:
-
-### Option A — Use the community relay
-
-`https://relay-rp1.jacobmoura.work` (default). Zero setup. Good for trying
-things out or for casual use. (The extension converts to `wss://…`
-internally when opening the connection — both schemes point at the same
-endpoint.)
+**Un Bien ships with no default relay** — `/unbien config` reports `unset` until
+you configure one, and the extension refuses to connect until you do.
 
-Caveats:
+### Self-host the relay
 
-- Shared infrastructure — availability is best-effort.
-- **There is no IP allow-listing or VPN gating**.
-
-### Option B — Self-host (recommended for privacy)
-
-Run the relay yourself in Docker and put it behind a VPN like
+Run the relay yourself and put it behind a VPN like
 [Tailscale](https://tailscale.com), [WireGuard](https://www.wireguard.com),
 or your own VPC. Because the relay's network-level protection is just TLS +
 keypair authentication, layering a VPN on top means **only your devices** can
 even reach the WebSocket port — defense in depth.
 
-Quick Docker outline (see the
-[relay README](https://github.com/jacobaraujo7/remote_pi/blob/main/relay/README.md#self-hosted-relay-recommended-for-privacy)
-for the full setup, environment variables, and reverse-proxy guidance):
+Build and run from the `relay/` crate in this monorepo (see the
+[relay README](../relay/README.md) for environment variables and reverse-proxy
+guidance):
 
 ```bash
+# From the monorepo root:
+docker build -t un-bien-relay ./relay
 docker run -d \
-  --name remote-pi-relay \
+  --name un-bien-relay \
   -p 3000:3000 \
+  -v un-bien-data:/data \
   --restart unless-stopped \
-  ghcr.io/jacobaraujo7/remote-pi-relay:latest
+  un-bien-relay
 ```
 
 Bind the container to your VPN interface, terminate TLS in a reverse proxy,
@@ -323,7 +301,7 @@ and point both your Pi and your phone at the resulting `https://…` URL.
 Once your relay is reachable, tell the extension:
 
 ```text
-/remote-pi relay url https://relay.yourdomain.tld
+/unbien relay url https://relay.yourdomain.tld
 ```
 
 The URL **must** be `http://` or `https://` — `ws://` / `wss://` are
@@ -331,21 +309,23 @@ rejected at validation. The extension converts to WebSocket internally when
 it opens the connection. Same canonical form for the mobile app and any
 self-hosting docs: paste the URL your reverse proxy exposes.
 
-This writes `~/.pi/remote/config.json` with `{ "relay": "..." }`. Resolution
-order (highest precedence first):
+This writes the `relay` field into the global config at
+`~/.pi/extensions/un-bien.json`. Resolution order (highest precedence first):
+
+1. `UNBIEN_RELAY` environment variable (CI / one-off overrides)
+2. `relay` field in `~/.pi/extensions/un-bien.json`
 
-1. `REMOTE_PI_RELAY` environment variable (CI / one-off overrides)
-2. `~/.pi/remote/config.json`
-3. The built-in default (`https://relay-rp1.jacobmoura.work`)
+There is **no built-in default** — when neither is set, the extension refuses
+to connect and prompts you to configure a relay.
 
 Verify the active URL and its source with:
 
 ```text
-/remote-pi config
+/unbien config
 ```
 
-If you change the URL while connected, run `/remote-pi relay stop` then
-`/remote-pi relay start` (or `/remote-pi relay` to toggle).
+If you change the URL while connected, run `/unbien relay stop` then
+`/unbien relay start` (or `/unbien relay` to toggle).
 
 The mobile app has its own relay-URL setting in its preferences pane — keep
 both pointing at the same relay.
@@ -394,16 +374,16 @@ original message id.
 
 The wire format is a 5-field envelope `{ from, to, id, re, body }` serialized
 as one JSON line per message. The leader's broker writes an `audit.jsonl`
-log at `~/.pi/remote/sessions/<name>/audit.jsonl` for postmortem inspection.
+log at `~/.local/state/un-bien/sessions/<name>/audit.jsonl` for postmortem inspection.
 
 Useful commands:
 
-| Command                   | What it does                                          |
-| ------------------------- | ----------------------------------------------------- |
-| `/remote-pi`              | Join the local mesh (and start the relay, if enabled) |
-| `/remote-pi peers`        | List local + cross-PC mesh peers, grouped by PC       |
-| `/remote-pi rename <new>` | Rename this agent in the current session              |
-| `/remote-pi stop`         | Leave the local mesh and disconnect the relay         |
+| Command                | What it does                                          |
+| ---------------------- | ----------------------------------------------------- |
+| `/unbien`              | Join the local mesh (and start the relay, if enabled) |
+| `/unbien peers`        | List local + cross-PC mesh peers, grouped by PC       |
+| `/unbien rename <new>` | Rename this agent in the current session              |
+| `/unbien stop`         | Leave the local mesh and disconnect the relay         |
 
 Name collisions inside a session get a numeric suffix automatically
 (`backend`, `backend#2`, `backend#3`). The broker assigns it and returns the
@@ -415,71 +395,30 @@ real name to the peer.
 
 ### Local session (one Pi, one terminal)
 
-| Command                                  | Description                                                                    |
-| ---------------------------------------- | ------------------------------------------------------------------------------ |
-| `/remote-pi`                             | Connect (join local mesh + start relay), or run setup on first use             |
-| `/remote-pi setup`                       | Run the setup wizard and update local config                                   |
-| `/remote-pi status`                      | Show local mesh + relay status                                                 |
-| `/remote-pi stop`                        | Stop everything for **this** terminal (mesh + relay)                           |
-| `/remote-pi pair`                        | Show QR code + copy-paste pairing URI for a new mobile device                  |
-| `/remote-pi devices`                     | List paired mobile devices (online/offline per device)                         |
-| `/remote-pi revoke <shortid>`            | Revoke a paired device by its shortid                                          |
-| `/remote-pi set-relay <url>`             | Persist a new relay URL (http:// or https://)                                  |
-| `/remote-pi relay [start\|stop\|status]` | Relay-only control — leaves local mesh membership untouched (no verb = toggle) |
-| `/remote-pi relay url <url>`             | Same as `set-relay`                                                            |
-| `/remote-pi config`                      | Show the effective relay URL and its source (env / config / default)           |
-
-### Daemon fleet (one supervisor, N background Pis — see [Daemon mode](#daemon-mode))
-
-| Command                                        | Description                                                                   |
-| ---------------------------------------------- | ----------------------------------------------------------------------------- |
-| `/remote-pi create <cwd> [--name X]`           | Register a folder as a daemon                                                 |
-| `/remote-pi remove <id>`                       | Unregister a daemon (local config preserved)                                  |
-| `/remote-pi daemons`                           | List registered daemons + state                                               |
-| `/remote-pi daemon start`                      | Start every registered daemon                                                 |
-| `/remote-pi daemon stop`                       | Stop every running daemon (`/remote-pi stop` stops only the local terminal)   |
-| `/remote-pi daemon restart`                    | Stop + start all daemons                                                      |
-| `/remote-pi daemon status`                     | Detailed runtime status (pid, uptime, restart count)                          |
-| `/remote-pi daemon send <id> "<text>"`         | Send a prompt to a specific daemon                                            |
-| `/remote-pi cron add <id> "<expr>" "<prompt>"` | Schedule a recurring prompt (`--tz`, `--wake`, `--no-skip-busy`, `--catchup`) |
-| `/remote-pi cron list`                         | List scheduled jobs (schedule, enabled, next run, last status)                |
-| `/remote-pi cron run <jobId>`                  | Fire a job now (ignores its schedule)                                         |
-| `/remote-pi cron enable\|disable <jobId>`      | Toggle a job on/off                                                           |
-| `/remote-pi cron remove <jobId>`               | Delete a job                                                                  |
-| `/remote-pi cron log [<jobId>] [--tail N]`     | Read the fire/skip audit log                                                  |
-| `/remote-pi install`                           | Install `pi-supervisord` as a system service                                  |
-| `/remote-pi uninstall`                         | Remove the system service (registry preserved)                                |
+| Command                               | Description                                                                    |
+| ------------------------------------- | ------------------------------------------------------------------------------ |
+| `/unbien`                             | Connect (join local mesh + start relay), or run setup on first use             |
+| `/unbien setup`                       | Run the setup wizard and update local config                                   |
+| `/unbien status`                      | Show local mesh + relay status                                                 |
+| `/unbien stop`                        | Stop everything for **this** terminal (mesh + relay)                           |
+| `/unbien pair`                        | Show QR code + copy-paste pairing URI for a new mobile device                  |
+| `/unbien devices`                     | List paired mobile devices (online/offline per device)                         |
+| `/unbien revoke <shortid>`            | Revoke a paired device by its shortid                                          |
+| `/unbien set-relay <url>`             | Persist a new relay URL (http:// or https://)                                  |
+| `/unbien relay [start\|stop\|status]` | Relay-only control — leaves local mesh membership untouched (no verb = toggle) |
+| `/unbien relay url <url>`             | Same as `set-relay`                                                            |
+| `/unbien config`                      | Show the effective relay URL and its source (env / config / unset)             |
+
+### Service install & remote launch (see [Remote launch](#remote-launch))
+
+| Command             | Description                                                                        |
+| ------------------- | ---------------------------------------------------------------------------------- |
+| `/unbien install`   | Install the **unbien-launcher** daemon as a system service + link the `unbien` CLI |
+| `/unbien uninstall` | Remove the launcher service + CLI links (pairing and config preserved)             |
 
 All commands above work both as Pi slash commands (interactive) and as
-shell-level `remote-pi <subcommand>` when the package is installed
-globally (`npm install -g remote-pi`).
-
-### Scheduled prompts (`cron`)
-
-`remote-pi cron` schedules **recurring prompts** to daemons through the
-supervisor — e.g. a daily "summarise new PRs". Output flows fire-and-forget to
-the mesh/app like any prompt; the cron layer only audits the dispatch.
-
-- **Schedule** is a cron expression (croner syntax; an optional 6th _seconds_
-  field is supported), with an optional IANA timezone via `--tz`:
-
-  ```sh
-  remote-pi cron add a1b2c3d4 "0 9 * * *" "Summarise new PRs" --tz America/Sao_Paulo
-  ```
-
-- **Minimum interval is 60s** — more frequent schedules are rejected (guards
-  token cost + pileup). A fire is **skipped when the daemon is mid-turn**
-  (`--no-skip-busy` to override); `--wake` starts a stopped daemon first;
-  `--catchup` runs once on supervisor start if the previous run was missed.
-- **Prerequisite**: the supervisor must run as a service (`remote-pi install`).
-  Without it there is no scheduler, and `cron` commands say so instead of
-  silently pretending to schedule.
-- **Audit**: every fire **and** every skip appends one line to
-  `~/.pi/remote/cron.jsonl` with a `result` of `delivered`,
-  `woke_and_delivered`, `deliver_failed`, `skipped_busy`, `skipped_down`, or
-  `skipped_disabled` — read it with `remote-pi cron log`.
-
-Step-by-step walkthrough: the [daemon tutorial](https://remote-pi.jacobmoura.work/tutorials/daemon).
+shell-level `unbien <subcommand>` when the package is installed
+globally (`npm install -g @geohar/un-bien`).
 
 ### Footer + title
 
@@ -494,167 +433,190 @@ tabs.
 
 ---
 
-## Daemon mode
+## Remote launch
 
-When you want a Pi to keep running in the background (responding to
-mobile prompts at 3am, processing cron jobs, monitoring a folder while
-you're not at the keyboard), promote it to a **daemon** managed by a
-single OS-level supervisor.
+The **unbien-launcher** is a lightweight mesh peer — **not** a Pi session — that
+lets a paired app reach your machine even when no Pi is running. It reuses the
+machine's un-bien config (identity + relay), joins the machine-level control
+room, advertises `remote_launch`, and spawns a `pi` window via `tmux` (default)
+or `herdr` when the app asks for one.
 
 See [`docs/daemon.md`](./docs/daemon.md) for troubleshooting.
 
 ### One-time setup
 
 ```bash
-# Install the package globally so `remote-pi` and `pi-supervisord`
-# are on your PATH (`pi install npm:remote-pi` alone makes the Pi
-# extension available but does NOT expose the CLI binaries — see
+# Install the package globally so the `unbien` CLI is on your PATH
+# (`pi install npm:@geohar/un-bien` alone makes the Pi extension available
+# but does NOT expose the CLI binary — see
 # https://docs.npmjs.com/cli/v10/configuring-npm/package-json#bin).
-npm install -g remote-pi
+npm install -g @geohar/un-bien
 
-# Install the supervisor as a user-level system service. Linux uses
+# Install the launcher as a user-level system service. Linux uses
 # systemd --user; macOS uses launchd LaunchAgent. Both auto-start at
 # login and survive reboots.
-remote-pi install
+unbien install
 ```
 
+Or from inside Pi: `/unbien install` — same service, plus it links the
+`unbien` CLI into `~/.local/bin` so no global npm install is needed.
+
 The `install` command:
 
-- Writes `~/.config/systemd/user/remote-pi-supervisord.service` (Linux)
-  or `~/Library/LaunchAgents/dev.remotepi.supervisord.plist` (macOS)
+- Writes `~/.config/systemd/user/unbien-launcher.service` (Linux) or
+  `~/Library/LaunchAgents/dev.unbien.launcher.plist` (macOS); on Windows it
+  registers a Task Scheduler task (`RemotePiLauncher`) and prompts for
+  elevation once
 - Activates it via `systemctl --user enable --now` or `launchctl bootstrap`
-- The supervisor starts immediately and re-starts on every login
+- The launcher starts immediately and re-starts on every login
 
-### Per-folder workflow
+A standalone package exists for running the launcher in the foreground, no
+service: `npm install -g @geohar/un-bien-launcher` → `unbien-launcher`. Same
+daemon, shipped as its own binary (see the
+[launcher README](../launcher/README.md)).
 
-For each agent you want to keep alive 24/7:
+### Enable remote launch
 
-```bash
-# 1. Configure the agent interactively first (one time).
-cd ~/Movies
-pi                                 # /remote-pi → setup wizard, /remote-pi pair, etc
-
-# 2. Promote to a daemon. The id is derived from the cwd
-#    (sha256(realpath)[:8]), stable across machines.
-remote-pi create ~/Movies --name "Video Editor"
-# → Daemon registered: id=4e39152d name="Video Editor" cwd=/Users/x/Movies
+The launcher only spawns sessions where remote launch is **opted in**:
 
-# 3. Start it (supervisor spawns `pi --mode rpc` for this folder).
-remote-pi daemon start
-```
+- per directory: `allow_remote_launch: true` in `<cwd>/.pi/un-bien/config.json`
+- or machine-wide: `defaults.allow_remote_launch: true` in the global config
+  (`~/.pi/extensions/un-bien.json`)
 
-Now you can:
+The spawn backend is machine-wide: `launch.backend` in the global config —
+`tmux` (default; one shared `un-bien` tmux session, a window per launched Pi)
+or `herdr`. The backend binary must be on PATH: `unbien install` snapshots
+your PATH at install time, so re-run it after installing new tools.
 
-```bash
-remote-pi daemons                  # list + state
-remote-pi daemon status            # uptime, pid, restart count
-remote-pi daemon send 4e39152d "Cut the first 30 seconds of latest clip"
-remote-pi daemon stop              # stop all
-remote-pi daemon restart           # restart all
-```
+### Launch names
 
-The agent receives the prompt as if a user typed it; its response flows
-back through the relay/mesh you configured during interactive setup —
-mobile app sees it live, other agents on the same machine can see it
-via the local UDS mesh.
+A `session_launch` request may carry a `name`. On the tmux backend the
+launched Pi gets it as `pi -n <name>` — pi's native session display name —
+which the extension resolves as the session-scoped agent name: the mesh
+join, cwd lock, `room_meta`, and the app's session tile all show it instead
+of the path-derived default. It is per-process (never inherited by
+subagents or child processes) and never persisted — a manual `pi` in the
+same directory keeps its configured `agent_name`. `/unbien rename` still
+wins once it runs. The herdr backend uses the name as the workspace label
+only until it can pass args through to pi.
 
 ### Removing or uninstalling
 
 ```bash
-remote-pi remove <id>              # unregister one daemon (config preserved)
-remote-pi uninstall                # remove the supervisor service (registry kept)
+unbien uninstall        # remove the launcher service (pairing + config kept)
 ```
 
-`uninstall` is reversible — re-running `install` later brings every
-registered daemon back. To wipe the registry entirely, `rm
-~/.pi/remote/daemons.json`.
+`uninstall` is reversible — re-running `install` later brings the launcher
+back. Pairing and identity live in the state root and are never touched.
 
 ### Where to find logs
 
-| Platform | Command                                         |
-| -------- | ----------------------------------------------- |
-| Linux    | `journalctl --user -u remote-pi-supervisord -f` |
-| macOS    | `tail -f ~/.pi/remote/supervisord.log`          |
-
-Each spawned daemon's stderr is forwarded into the supervisor's log
-with a `[<cwd>]` prefix, so a single log stream shows every agent.
-
-### Caveats (plan/26 trade-offs)
-
-- **Tool approval is not gated.** Daemons inherit the same Pi config
-  the interactive run uses — Bash, Edit, Write etc. all execute without
-  prompting. Configure Pi's tool permissions to taste before promoting
-  a folder to daemon.
-- **Pairing still happens interactively.** Daemons don't show a QR
-  themselves; the keypair + paired devices come from the prior `pi`
-  session in the same folder.
-- **Single supervisor.** If `pi-supervisord` crashes all daemons go
-  down with it. systemd/launchd restarts it within seconds; daemons
-  come back automatically.
-- **One daemon per cwd.** The `roomIdForCwd` derivation makes daemons
-  by-path; two daemons in the same folder is rejected at `create` time.
+| Platform | Command                                                 |
+| -------- | ------------------------------------------------------- |
+| Linux    | `journalctl --user -u unbien-launcher -f`               |
+| macOS    | `tail -f ~/.local/state/un-bien/launcher.log`           |
+| Windows  | `Get-Content ~\.local\state\un-bien\launcher.log -Wait` |
 
----
-
-## Configuration files
-
-| Path                                         | Scope         | What's in it                                                                                        |
-| -------------------------------------------- | ------------- | --------------------------------------------------------------------------------------------------- |
-| `<cwd>/.pi/remote-pi/config.json`            | Per-directory | `agent_name`, `session_name`, `auto_start_relay`                                                    |
-| `~/.pi/remote/config.json`                   | Per-user      | `relay` URL; optional `defaults.auto_start_relay` (machine-wide fallback for per-directory configs) |
-| `~/.pi/remote/peers.json`                    | Per-machine   | Paired mobile devices                                                                               |
-| `~/.pi/remote/sessions/<name>/`              | Per-session   | Broker socket + `audit.jsonl`                                                                       |
-| `~/.pi/remote/skills/agent-network/SKILL.md` | Per-user      | Agent skill the LLM reads                                                                           |
+### Caveats
 
-Every path above **except the global `config.json`** derives from a single
-**state root** — by default `~/.pi/remote`. Two environment variables relocate
-that state root:
+- **Pairing still happens interactively.** The launcher doesn't show a QR; it
+  only trusts owners already paired via `/unbien pair` in a Pi session on
+  this machine.
+- **Tool execution is not gated.** A launched Pi inherits the same Pi config
+  an interactive run uses — Bash, Edit, Write etc. all execute without
+  prompting. Configure Pi's tool permissions to taste before enabling
+  `allow_remote_launch`.
+- **Same identity, same relay.** The launcher reads the machine's global
+  config — `/unbien config` shows exactly what it will use.
 
-| Variable         | Behaviour                                                                                                                                                        |
-| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `REMOTE_PI_DIR`  | Absolute path to the state root. No suffix appended — set this to an XDG-style location like `~/.config/pi/remote-pi`. Takes priority over every other variable. |
-| `REMOTE_PI_HOME` | Stand-in for `$HOME`; state lives at `<REMOTE_PI_HOME>/.pi/remote`. Kept for backward compatibility.                                                             |
-
-When both are set, `REMOTE_PI_DIR` wins. Use these to put remote-pi **state**
-(sessions, daemon registries, cwd locks, paired identity) on a specific disk,
-inside an XDG directory, or anywhere your system's conventions dictate.
+---
 
-The global `config.json` (relay URL + defaults) is resolved separately, so it
-can sit beside the coding agent's own settings rather than the state tree:
+## Configuration & settings
 
-| Variable              | Behaviour                                                                                                                                                                                                                     |
-| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `PI_CODING_AGENT_DIR` | The Pi host's settings root (default `~/.pi`). `config.json` lives at `<PI_CODING_AGENT_DIR>/remote/config.json`, so with the default agent dir the path stays exactly `~/.pi/remote/config.json`. Takes priority for config. |
+### Files
 
-When `PI_CODING_AGENT_DIR` is unset, `config.json` falls back to the state root
-above (so a pure `REMOTE_PI_DIR` relocation still keeps config beside the rest).
+| Path                                                   | Scope             | What's in it                                                                   |
+| ------------------------------------------------------ | ----------------- | ------------------------------------------------------------------------------ |
+| `~/.pi/extensions/un-bien.json`                        | Per-user (global) | `relay` URL, `defaults`, `identity`, `debug` — the global settings (see below) |
+| `<cwd>/.pi/un-bien/config.json`                        | Per-directory     | `agent_name`, `auto_start_relay`, `allow_remote_launch`                        |
+| `~/.local/state/un-bien/identity.json`                 | Per-machine       | Paired identity keypair (file identity backend; `0600`)                        |
+| `~/.local/state/un-bien/peers.json`                    | Per-machine       | Paired mobile devices                                                          |
+| `~/.local/state/un-bien/sessions/<name>/`              | Per-session       | Broker socket + `audit.jsonl`                                                  |
+| `~/.local/state/un-bien/skills/agent-network/SKILL.md` | Per-user          | Agent skill the LLM reads                                                      |
 
-### Global defaults
+### Global settings — `~/.pi/extensions/un-bien.json`
 
-The global `~/.pi/remote/config.json` can include a `defaults` block that acts
-as a fallback for every per-directory config that doesn't set the field:
+This is a Pi **extension config** (it lives beside the coding agent's own
+settings, under `PI_CODING_AGENT_DIR/extensions/`, not in the state tree). All
+fields are optional:
 
 ```jsonc
 {
+  // Relay URL in canonical http(s):// form. No default — unset means the
+  // extension refuses to connect. Set via `/unbien set-relay <url>`.
   "relay": "https://relay.yourdomain.tld",
-  "defaults": {
-    "auto_start_relay": true,
-  },
+
+  // Machine-wide fallback for every per-cwd config that doesn't set the field.
+  // Pin auto-start once instead of dropping a file into every repo.
+  "defaults": { "auto_start_relay": true },
+
+  // Remote-launch backend a `session_launch` request uses on THIS machine:
+  // "tmux" (default; one shared tmux session, a window per launched Pi) or
+  // "herdr". Machine-wide choice — whether remote launch is enabled at all
+  // stays the per-cwd `allow_remote_launch` flag.
+  "launch": { "backend": "tmux" },
+
+  // Machine-identity storage. `storage` selects the PRIMARY backend for this
+  // Pi's long-term Ed25519 seed: "keychain" (OS-secured, default) or "file"
+  // (a 0600 seed file — the SSH-private-key model: cat-able, portable,
+  // works headless). `path` overrides the file-backend location
+  // (default ~/.local/state/un-bien/identity.json). The unselected backend is still
+  // READ to recover an existing identity, but never written.
+  "identity": { "storage": "keychain", "path": "~/.local/state/un-bien/identity.json" },
+
+  // File-based diagnostic logs. Off by default. Read from config (not env)
+  // because the daemon fork usually runs detached without a shell's env.
+  "debug": { "envelope": false, "panels": false },
 }
 ```
 
-This lets you pin `auto_start_relay` once — beside `relay` — instead of
-dropping a `config.json` into every repo. A per-directory file (or the
-`REMOTE_PI_DIRECT_CONFIG` env var) still overrides the global default.
+### Per-directory settings — `<cwd>/.pi/un-bien/config.json`
+
+Written by the `/unbien` setup wizard:
+
+| Field                 | Default        | Meaning                                                                                    |
+| --------------------- | -------------- | ------------------------------------------------------------------------------------------ |
+| `agent_name`          | directory name | Presentation leaf name for this agent (senders still use the opaque `list_peers` address)  |
+| `auto_start_relay`    | `true`         | On a fresh terminal, `/unbien` auto-joins the mesh and starts the relay                    |
+| `allow_remote_launch` | `false`        | Honor `session_launch` requests from a paired owner (spawn a new Pi session). Opt-in only. |
+
+### Environment variables
+
+| Variable               | Purpose                                                                                                                    |
+| ---------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| `UNBIEN_RELAY`         | Relay URL override (highest precedence, ahead of the config file). CI / one-off use.                                       |
+| `UNBIEN_STATE_DIR`     | Absolute override of the **state** dir itself. The knob for relocating state. Highest precedence of the state knobs.       |
+| `UNBIEN_DIR`           | Legacy absolute override of the **state** dir itself (no suffix appended). Lower precedence than `UNBIEN_STATE_DIR`.       |
+| `UNBIEN_HOME`          | Legacy stand-in `$HOME`; state lives at `<UNBIEN_HOME>/.pi/un-bien`. Lower precedence than `UNBIEN_DIR`.                   |
+| `PI_CODING_AGENT_DIR`  | The Pi host's settings root (default `~/.pi`); the global config lives at `<PI_CODING_AGENT_DIR>/extensions/un-bien.json`. |
+| `UNBIEN_DIRECT_CONFIG` | Inline per-cwd config (JSON) instead of a `.pi/un-bien/config.json` file — CI / one-off use.                               |
 
-The `defaults` block is read from wherever the global `config.json` resolves, so
-it follows a relocated config: with `PI_CODING_AGENT_DIR` set it lives at
-`<PI_CODING_AGENT_DIR>/remote/config.json` (see the environment overrides above).
+The state root resolves as `UNBIEN_STATE_DIR` > `UNBIEN_DIR` > `UNBIEN_HOME` >
+`${XDG_STATE_HOME:-~/.local/state}/un-bien` — the XDG-style default. `UNBIEN_DIR`/
+`UNBIEN_HOME` relocate un-bien **state** (sessions, cwd locks, paired identity) and stay honored for older deployments. On first use
+of the new default, a one-time best-effort migration moves any legacy
+`~/.pi/un-bien` state (peers.json included) into the new root.
+`PI_CODING_AGENT_DIR` relocates only the global **config**, so it can sit
+beside the coding agent's own settings.
+
+**Deprecated**: the relay no longer defaults its SQLite DB to a CWD-relative
+`data/mesh.db` — see the relay README for its `UNBIEN_MESH_DB_PATH` /
+state-root resolution.
 
 Override the relay for a single run without persisting:
 
 ```bash
-REMOTE_PI_RELAY=https://staging.example.tld pi
+UNBIEN_RELAY=https://staging.example.tld pi
 ```
 
 ---
@@ -664,13 +626,16 @@ REMOTE_PI_RELAY=https://staging.example.tld pi
 **Footer says `🟡 relay waiting for pairing` even though I paired a device.**
 The icon reflects whether _any_ device has been paired on this machine, not
 whether one is connected right now. If you really have a paired device in
-`/remote-pi devices`, restart Pi — the cache may be stale (fixed in current
+`/unbien devices`, restart Pi — the cache may be stale (fixed in current
 release; report a bug if it recurs).
 
 **Mobile app times out connecting.** Verify the same relay URL is configured
 on both sides. If you self-host behind a VPN, your phone must also be on the
 VPN (Tailscale on iOS/Android works fine).
 
+**`/unbien config` says the relay is `unset`.** Un Bien has no default relay.
+Self-host one and set it with `/unbien set-relay <url>` (or `UNBIEN_RELAY`).
+
 **`agent_request` keeps timing out.** It is deprecated because it blocks the
 turn while waiting for another agent's content reply. Migrate to `agent_send`;
 a unicast waits only for the delivery ACK, and the receiver can reply later
@@ -683,44 +648,17 @@ other terminal first.
 
 ---
 
-## Branding
-
-Official brand assets live in
-[`/branding`](https://github.com/jacobaraujo7/remote_pi/tree/main/branding) —
-SVG sources for the logo (full, foreground, background, monochrome) plus a
-banner. See the
-[branding README](https://github.com/jacobaraujo7/remote_pi/blob/main/branding/README.md)
-for palette and export sizes.
-
-<table>
-  <tr>
-    <td align="center">
-      <img src="https://raw.githubusercontent.com/jacobaraujo7/remote_pi/main/branding/logo-full.svg" width="96" alt="logo-full" /><br/>
-      <sub><code>logo-full</code></sub>
-    </td>
-    <td align="center">
-      <img src="https://raw.githubusercontent.com/jacobaraujo7/remote_pi/main/branding/logo-foreground.svg" width="96" alt="logo-foreground" /><br/>
-      <sub><code>logo-foreground</code></sub>
-    </td>
-    <td align="center">
-      <img src="https://raw.githubusercontent.com/jacobaraujo7/remote_pi/main/branding/logo-monochrome.svg" width="96" alt="logo-monochrome" /><br/>
-      <sub><code>logo-monochrome</code></sub>
-    </td>
-  </tr>
-</table>
-
----
-
 ## Links
 
-- Homepage: <https://remote-pi.jacobmoura.work>
-- Source: <https://github.com/jacobaraujo7/remote_pi>
+- Repository: <https://github.com/georgeharker/un-bien>
+- Documentation: <https://docs.georgeharker.com/un-bien>
 - Pi coding agent: <https://github.com/earendil-works/pi>
-- Relay (self-hosting guide): <https://github.com/jacobaraujo7/remote_pi/blob/main/relay/README.md>
-- Issues / bugs: <https://github.com/jacobaraujo7/remote_pi/issues>
+- Relay (self-hosting guide): [`../relay/README.md`](../relay/README.md)
+- Upstream project (remote-pi, MIT): <https://github.com/jacobaraujo7/remote_pi>
 
 ---
 
 ## License
 
-MIT
+MIT — derived from [remote-pi](https://github.com/jacobaraujo7/remote_pi) by
+Jacob Moura. See [`LICENSE`](LICENSE).