acbridge 1.1.0 → 1.1.2

package/README.md

@@ -2,73 +2,236 @@
 
 <img src="https://www.ac-bridge.com/brand/ac-bridge-mark-gradient.png" width="96" alt="AC Bridge">
 
-**Quiet status lights for Claude Code and Codex.**
+[![npm version](https://img.shields.io/npm/v/acbridge)](https://www.npmjs.com/package/acbridge)
+[![node](https://img.shields.io/node/v/acbridge)](https://nodejs.org)
+[![platforms](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux%20%7C%20WSL2-blue)](https://ac-bridge.com)
 
-Control **AC Bridge** from any terminal: sign in, run the bridge, and drive your smart-home devices
-and Profiles — the scenes that react to what your coding agent is doing.
+**Ambient status for Claude Code and Codex — let your smart home tell you, gently.**
 
-It is the full terminal peer of the [AC Bridge](https://ac-bridge.com) desktop app. Everything below
-runs headlessly on a box with no GUI; sign-in wants a browser once (see the SSH note below).
+AC Bridge connects your coding agents to the smart-home devices around you. Instead of a jarring
+completion chime or compulsive tab-switching, the room keeps you informed: the desk lamp shifts to
+amber when Claude is waiting on a permission, pulses red on an error, and settles back to warm
+white when the work is done. Turn the terminal sound effects off for good — glance up from another
+screen, or another room, and know exactly where your agent is.
+
+Every state is yours to map to any device, colour, brightness, or scene — the options are
+limitless.
+
+`acbridge` is the full terminal peer of the [AC Bridge desktop app](https://ac-bridge.com):
+everything below runs headlessly on a box with no GUI.
 
 ```sh
 npm i -g acbridge
 ```
 
-## Before you start
+## How it works
+
+```
+Claude Code / Codex session ──hooks──▶ local bridge ──▶ your lights & devices
+```
+
+Lightweight hooks (installed once by `acbridge setup`) report what your agent is doing to a small
+local bridge on your PC. **Profiles** map those session states to device scenes, and the bridge
+applies them live. When a session ends — or you run `acbridge stop` — every device it touched is
+put back exactly the way it was found.
+
+Nothing needs to change about how you work: once the bridge is up, lights react to **any**
+`claude` or `codex` session launched in a profile-bound project. No flags, no wrappers.
+
+## The states your agent can signal
+
+Roughly thirty session states for Claude Code and twenty-three for Codex, including:
+
+- **needs permission** — a tool call is waiting on your approval
+- **has a question** / **plan ready** — the agent wants your input
+- **working / finished / error / idle**
+- **context low / context critical** — the context window is filling up
+- **usage high / cost high / long-running** — thresholds you set per profile
+- **plan, auto-accept, and bypass permission modes**, **model changed**, **subagents**,
+  **compacting**, **rate limited**, and more
+
+Run `acbridge profiles states` for the full catalog with hints and threshold ranges. Each state
+takes a colour (fixed, the device's resting "main" look, or a per-session colour), brightness or a
+relative scale, colour temperature, power, hold-or-revert behaviour, effects — plus an action lane
+that can run any device command. Per-profile quiet hours and do-not-disturb are built in.
+
+## Requirements
 
 - **Node.js 22 or newer.**
 - **An AC Bridge subscription** — sign up (3-day free trial) at <https://ac-bridge.com>.
-- **[Claude Code](https://claude.com/claude-code) or the OpenAI Codex CLI**, if you want Profiles to
-  react to your sessions. Device control works without either.
+- **[Claude Code](https://claude.com/claude-code) or the OpenAI Codex CLI**, if you want Profiles
+  to react to your sessions. Device control works without either.
 
-## Get going
+## Quick start
 
 ```sh
-acbridge login     # sign in this machine (opens your browser)
-acbridge setup     # once per machine: installs the agent hooks that feed Profiles
-acbridge start     # bring the bridge up in the background
+acbridge login                        # sign this machine in (opens your browser)
+acbridge setup                        # once per machine: installs the agent hooks
+acbridge start                        # bring the bridge up in the background
+acbridge scan                         # find devices on your LAN — each row prints its next command
+acbridge profiles create --starter --bind    # wire a ready-made scene set to this project
 ```
 
-Then launch `claude` (or `codex`) in any project and your Profiles react to it. `acbridge stop` puts
-every device it touched back the way it found it.
+Then launch `claude` (or `codex`) in the bound project and watch the room react. `acbridge stop`
+puts every device it touched back the way it found it.
+
+The `--starter` scene set pre-wires six states: **working** follows each session's own colour,
+**needs permission / plan ready / error / finished** get attention colours, and **idle** dims to
+30% — all reversible, no holds. Tune any of it afterwards:
+
+```sh
+acbridge profiles set-state focus needs_permission --device "desk lamp" --color 30,100 --brightness 80
+acbridge profiles set-state focus error --device "desk lamp" --color 0,100
+acbridge profiles set-state focus finished --device "desk lamp" --return main
+```
 
 No browser on the box? `acbridge login --no-browser` prints a sign-in URL served on this machine's
 loopback — open it in a browser **on the same machine**, or over SSH forward the port first
-(`ssh -L 8765:127.0.0.1:8765 <box>`) and open it on your laptop. The command keeps waiting either way.
+(`ssh -L 8765:127.0.0.1:8765 <box>`) and open it on your laptop. The command keeps waiting either
+way.
+
+## Connect your devices
 
-## What else it does
+Link an ecosystem account, or connect open-protocol devices directly from a LAN scan:
 
-| | |
+| Provider | How to connect |
 |---|---|
-| `acbridge status` | is the bridge up, who is signed in, what is running |
-| `acbridge doctor` | checks every requirement and prints the fix for each one |
-| `acbridge scan` | find smart-home devices on your LAN |
-| `acbridge connect` / `link` | add a device or link a provider account (Hue, Home Assistant, SmartThings, Tuya, and more) |
-| `acbridge devices` | list devices and control them — on/off, brightness, colour, scenes |
-| `acbridge profiles` | build and edit Profiles right here: `create` (wizard or flags, `--starter` pre-wires a scene set), `set-state` links devices to session states, `bind` attaches a profile to a project |
-| `acbridge repos` / `groups` | the project (bridge) list sessions launch from, and device groups |
-| `acbridge stop` | stop the bridge and revert every device it changed |
+| **Home Assistant** | `acbridge link home-assistant --url http://homeassistant.local:8123 --token <token>` |
+| **Philips Hue** | `acbridge link hue --host <bridge-ip>` — then press the bridge's link button |
+| **MQTT** (Zigbee2MQTT, Tasmota, ESPresense…) | `acbridge link mqtt --host <broker[:port]>` — every Home Assistant Discovery device appears; no vendor account needed |
+| **SmartThings** | `acbridge link smartthings` — browser sign-in |
+| **Tuya / Smart Life** | `acbridge link tuya` — terminal wizard |
+| **Meross** | `acbridge link meross` — terminal wizard |
+| **eWeLink (Sonoff)** | `acbridge link ewelink` — terminal wizard |
+| **Govee** | `acbridge link govee` — API key |
+| **Nanoleaf** | `acbridge scan` → `acbridge connect <device>` while holding the panel's power button |
+| **TP-Link Kasa, WiZ, Yeelight, LIFX, Shelly, ESPHome…** | `acbridge scan` → `acbridge connect <device>` |
 
-Run `acbridge --help`, or `acbridge <command> --help`, for the full list and every flag.
+Wizard secrets prompt with muted echo and are stored **only on this machine** — in your OS
+keychain where one is available, `0600` files otherwise. Every secret flag has a `--token-file` /
+`--key-file` / `--password-file` twin for CI, which touches neither argv nor the environment.
 
-## Good to know
+## Command reference
 
-- **Your credentials stay on your machine.** Device and provider secrets are written to your OS
-  keychain where one is available, and to `0600` files otherwise — they never leave the machine.
-  `acbridge logout` removes them.
-- **The bridge only runs while something is holding it.** Closing the app or running `acbridge stop`
-  releases it; nothing lingers in the background that you did not ask for.
-- **Windows, macOS and Linux**, including WSL2.
+Run `acbridge --help`, or `acbridge <command> --help`, for every flag.
+
+### Run the bridge
+
+| Command | What it does |
+|---|---|
+| `acbridge start` | Bring the bridge up in the background and return your terminal. Idempotent — a second `start` reports "already running". `--no-revert` skips the device restore on stop; `--attach` runs in the foreground. |
+| `acbridge stop` | The complete off-switch: restores every touched device (*"lights: reverted 6 of 7 devices"*), then tears the bridge down. Running agent sessions are left alone. |
+| `acbridge restart` | Stop, then start with the same flags. |
+| `acbridge daemon` | The foreground keeper `start` runs detached — useful under a process manager. Self-heals a crashed bridge (capped respawn). |
+| `acbridge status` | Everything at a glance: sign-in, plan, bridge, daemon, devices session. **The exit code is the bridge state** (`0` running, `1` stopped) so scripts can health-gate on it. |
+
+### Account
+
+| Command | What it does |
+|---|---|
+| `acbridge login` | Browser sign-in for this machine; also how you switch accounts. `--if-needed` is the idempotent form for scripts; `--provider google/github/microsoft/sso` and `--email <addr>` skip the chooser; `--no-browser` prints the URL instead. |
+| `acbridge logout` | Stops the bridge, revokes this machine's credential, and deletes it locally. |
+| `acbridge whoami` | The signed-in account, this machine's node id and label, the relay, and your plan. |
+
+### Devices
+
+| Command | What it does |
+|---|---|
+| `acbridge devices` | The connected-device graph — name, type, area, reachability — live from the bridge. |
+| `acbridge devices on <device>` / `off <device>` | Power, by name or id (an ambiguous name lists the candidates). |
+| `acbridge devices set <device> <capability.command> --param k=v` | Any device command — brightness, colour, temperature, locks, thermostats. Validated against the device's real capabilities *before* anything is sent. |
+| `acbridge devices set-main <device>` | The device's resting "main" look — what profile scenes return to. `--color <hue>,<sat>`, `--brightness <0-100>`, `--kelvin <k>`, each settable or cleared with `none`. |
+| `acbridge rename <device> <new name>` | A durable rename, everywhere — the app, the graph, the CLI. |
+| `acbridge groups` | Device groups, shared with the app: `add`, `rename`, `remove`, `assign <device> <group>`, `unassign`. |
+
+```sh
+acbridge devices off "desk lamp"
+acbridge devices set bedroom brightness.setBrightness --param level=35
+acbridge devices set heater thermostat.setSetpoint --param celsius=21
+```
+
+### Discovery & integrations
+
+| Command | What it does |
+|---|---|
+| `acbridge scan` | Find smart devices on your LAN. Each result prints its exact next command — `connect` for direct devices, `link` for ecosystem hubs. `--timeout <s>` caps the poll. |
+| `acbridge connect <mac or ip or id>` | Onboard one device directly into the bridge. `--name` sets its display name; `--credentials-file <path>` supplies credentials headlessly. |
+| `acbridge connect <ip> --as govee/wiz/yeelight/kasa/esphome` | Connect-by-IP for a device the scan's fingerprint missed — persists only after a live probe replies. |
+| `acbridge connect --forget <device>` | Undo a connect; `--purge` also deletes any stored credential. `--auto on/off` answers the auto-connect policy. |
+| `acbridge link <provider>` | Link a provider account (table above). |
+| `acbridge unlink <provider>` | Remove a keyed provider's account, its secrets, and its devices. |
+| `acbridge integrations` | Every linked provider account, with the exact link command for anything missing. `enable` / `disable` pause an account; `remove` deletes one. |
+
+### Profiles & projects
+
+| Command | What it does |
+|---|---|
+| `acbridge profiles` | Your profiles and which project binds to which, across both agent lanes. |
+| `acbridge profiles create` | New profile — a short wizard on a terminal, or fully flag-driven: `--agent claude/codex`, `--devices <list>`, `--starter`, `--bind`. |
+| `acbridge profiles set-state <profile> <state>` | The scripting surface for one state's scene: `--device`, `--color`, `--brightness`, `--kelvin`, `--power`, `--return`, `--hold`, `--effect-json`, an `--action` lane, `--threshold`, `--announce`, and more. |
+| `acbridge profiles states` | Every state a profile can react to, per agent, with hints and threshold ranges. |
+| `acbridge profiles show / edit / rename / duplicate / delete` | Inspect or reshape a profile; `edit` is the interactive editor. |
+| `acbridge profiles bind <profile>` / `unbind` | Attach a profile to a project, per agent lane — Claude and Codex bindings coexist on one repo. `--repo` defaults to the current folder. |
+| `acbridge repos` | The project list sessions launch from, shared with the app: `add <path>` (`--root` imports every subfolder), `remove`. |
 
-## Uninstalling
+### Machine setup & health
+
+| Command | What it does |
+|---|---|
+| `acbridge setup` | Once per machine: installs the Claude Code plugin and managed settings (merged, never overwritten), and — if Codex is installed — merges AC Bridge's session-state hooks into `~/.codex/hooks.json` (every foreign hook preserved). |
+| `acbridge doctor` | Diagnoses everything — agent installs, plugin, sign-in, account, LAN-scan capability, bridge reachability — and **each line prints its own fix**. |
+| `acbridge capture on/off/status` | The per-machine session-transcript capture switch. |
+| `acbridge uninstall` | The clean exit: unwires everything `setup` wired, asks about your account data (default: keep), then hands off to `npm uninstall -g acbridge`. `--purge` deletes everything AC Bridge stored so a future install starts fresh. |
+
+### Voice (preview)
+
+AC Bridge was built to make coding agents reachable by voice through Amazon Echo devices —
+`acbridge run` launches a voice-connected session. Voice is switched off in current builds while
+the Alexa skill completes publication, so `run` exits with a notice today. Everything else on this
+page works fully without it.
+
+## Scripting
+
+Every command follows one exit-code contract, and `--json` (on the commands that take it) prints
+exactly one JSON document on stdout with all narration on stderr — pipes stay parseable:
 
 ```sh
-acbridge uninstall     # unwires the agent hooks, plugin, and firewall rule; asks about your account data
-npm uninstall -g acbridge
+acbridge status --json | jq .hub        # "running" | "stopped"
+acbridge stop --json | jq .revert       # {reverted, failed, skipped}
 ```
 
-Add `--purge` to the first command to delete **everything** AC Bridge stored on this machine —
-sign-out included — so a future install starts completely fresh.
+| Exit code | Meaning |
+|---|---|
+| `0` | Success. |
+| `1` | Operational failure. |
+| `2` | Usage error. |
+| `3` | Not signed in / setup incomplete — scripts can branch straight to `acbridge login`. |
+| `4` | Update required — this build is below the minimum version; update, don't retry. |
+| `5` | No active subscription — subscribe at <https://ac-bridge.com>, don't retry. |
+
+## Configuration
+
+Settings resolve **environment variable → `~/.claude-bridge/config.json` → default**:
+
+| Setting | Env | config.json | Default |
+|---|---|---|---|
+| Relay URL | `BRIDGE_RELAY_URL` | `relayUrl` | `https://relay.ac-bridge.com` |
+| Bridge port | `BRIDGE_HUB_PORT` | `hubPort` | `8790` |
+| Machine label | `BRIDGE_MACHINE` | `machine` | short hostname |
+| Secrets dir | `BRIDGE_SECRET_DIR` | — | `~/.claude-bridge` |
+| Auto-profiles | `BRIDGE_AUTO_PROFILES` | `autoProfiles` | on |
+| Codex hooks | `BRIDGE_CODEX_HOOKS` | `autoCodexHooks` | on |
+
+## Good to know
+
+- **Your credentials stay on your machine.** Device and provider secrets are written to your OS
+  keychain where one is available, and to `0600` files otherwise — they never leave the machine.
+  `acbridge logout` removes them.
+- **Your agent's tool policy is untouched.** AC Bridge installs no permission rules and never
+  changes what your agents are allowed to do — it only listens to their state.
+- **Nothing lingers.** The bridge runs only while something is holding it — the app, a daemon, a
+  session. Closing them (or `acbridge stop`) releases it, and stop reverts your devices.
+- **Windows, macOS and Linux**, including WSL2 (`doctor` explains that platform's scanning limits).
 
 ## Help