@phnx-labs/agents-cli 1.22.39 → 1.22.41

package/README.md

@@ -1,14 +1,14 @@
 <p align="center">
-  <img src="assets/logo.png" alt="agents" width="120" />
+  <img src="assets/logo.png" alt="agi-cli" width="120" />
 </p>
 
-<h1 align="center">agents</h1>
+<h1 align="center">agi-cli</h1>
 
 <p align="center">
   <a href="https://www.npmjs.com/package/@phnx-labs/agents-cli"><img src="https://img.shields.io/npm/v/@phnx-labs/agents-cli.svg?style=flat-square" alt="npm version" /></a>
   <a href="./LICENSE"><img src="https://img.shields.io/npm/l/@phnx-labs/agents-cli.svg?style=flat-square" alt="license" /></a>
   <a href="https://www.npmjs.com/package/@phnx-labs/agents-cli"><img src="https://img.shields.io/npm/dm/@phnx-labs/agents-cli.svg?style=flat-square" alt="downloads" /></a>
-  <a href="https://github.com/phnx-labs/agents-cli"><img src="https://img.shields.io/badge/github-phnx--labs%2Fagents--cli-blue?style=flat-square" alt="github" /></a>
+  <a href="https://github.com/phnx-labs/agi-cli"><img src="https://img.shields.io/badge/github-phnx--labs%2Fagi--cli-blue?style=flat-square" alt="github" /></a>
 </p>
 
 **A framework for running a distributed agent factory.** Dispatch Claude, Codex, Antigravity, Grok, and more across your own machines, in parallel, on your existing subscriptions. Measure every run with `agents perf` / `agents insights`, fold what you learn back into `AGENTS.md` and skills, then put the loop on a schedule with routines and monitors. Spawn parallel teams in isolated terminals or dispatch to the cloud for a PR. Watch live state across the fleet, nudge stalled runs, and message agents mid-flight. Store secrets behind Touch ID, drive real browsers and Electron apps, and steer the whole fleet from a menu bar — all from one CLI.
@@ -39,7 +39,7 @@
   <a href="https://docs.warp.dev/reference/cli" title="Warp Agent CLI (Oz)"><picture><source media="(prefers-color-scheme: dark)" srcset="assets/harnesses/warp.svg"><img src="assets/harnesses/warp-light.svg" height="32" alt="Warp Agent CLI" /></picture></a>
 </p>
 
-https://agents-cli.sh/demo.mp4
+https://agi-cli.sh/demo.mp4
 
 ## Quickstart
 
@@ -54,11 +54,11 @@ agents run claude "explain this repo"  # run any agent on your existing subscrip
 
 Full path -- installing harnesses, logging in, smoke-testing `agents teams`, and setting up your own fleet: [`apps/cli/docs/QUICKSTART.md`](apps/cli/docs/QUICKSTART.md).
 
-**Learn (concepts):** [Loop + graph engineering](https://agents-cli.sh/learn/loop-and-graph-engineering) · [Teams as graph engineering](https://agents-cli.sh/learn/teams-graph-engineering) · [Sessions · index + cross-device](https://agents-cli.sh/learn/sessions-index) · [Distributed fleet execution](https://agents-cli.sh/learn/distributed-fleet). Also: [harness engineering](https://agents-cli.sh/learn/harness-engineering) · [visual longform](https://share.agents-cli.sh/muqsitnawaz/agents-loop-and-graph-engineering).
+**Learn (concepts):** [Loop + graph engineering](https://agi-cli.sh/learn/loop-and-graph-engineering) · [Teams as graph engineering](https://agi-cli.sh/learn/teams-graph-engineering) · [Sessions · index + cross-device](https://agi-cli.sh/learn/sessions-index) · [Distributed fleet execution](https://agi-cli.sh/learn/distributed-fleet). Also: [harness engineering](https://agi-cli.sh/learn/harness-engineering) · [visual longform](https://share.agents-cli.sh/muqsitnawaz/agents-loop-and-graph-engineering).
 
-Already installed? `agents upgrade` updates agents-cli itself to the latest version (`agents upgrade 1.2.3` for a specific version or dist-tag, `-y` to skip the confirm prompt). The command is `upgrade` on every platform -- do not reach for `agents update`, which updates an installed **agent harness**, not agents-cli (and on macOS, `agents helper update` is a third thing: it reinstalls the keychain helper).
+Already installed? `agents upgrade` updates agi-cli itself to the latest version (`agents upgrade 1.2.3` for a specific version or dist-tag, `-y` to skip the confirm prompt). The command is `upgrade` on every platform -- do not reach for `agents update`, which updates an installed **agent harness**, not agi-cli (and on macOS, `agents helper update` is a third thing: it reinstalls the keychain helper).
 
-Source: [github.com/phnx-labs/agents-cli](https://github.com/phnx-labs/agents-cli)
+Source: [github.com/phnx-labs/agi-cli](https://github.com/phnx-labs/agi-cli)
 
 Also available as `ag` -- all commands work with both `agents` and `ag`.
 
@@ -194,14 +194,14 @@ agents run codex@ "review this branch"
 # Picks the host (14d usage affinity), the harness (installed CLIs weighted by
 # best-account headroom), and the account (balanced) -- all three layers.
 agents run auto "summarize recent commits"
-agents run auto --host yosemite-s0 "fix the flaky test"   # pin the host layer
+agents run auto --device yosemite-s0 "fix the flaky test"   # pin the host layer
 ```
 
 `run auto` excludes any harness whose accounts are all rate-limited or signed out, and exits nonzero with the earliest reset time when nothing anywhere is healthy.
 
 A trailing `@` opens an account picker before either an interactive or prompt-based run. Each installed version shows its account identity, exact version, login state, plan, and every available session, weekly, or monthly limit. Logged-out, rate-limited, and out-of-credit accounts remain visible with the reason they cannot be selected; signed-in accounts whose provider does not expose quota data stay selectable and say `limits unavailable`. The choice pins only that run and does not change your default version.
 
-Account selection is available for Claude, Codex, Gemini, Cursor, Antigravity, Grok, Kimi, Droid, and OpenCode. It requires a terminal and cannot be combined with `--resume`, `--strategy`/`--balanced`, `--lease`, or `--host`/`--device`; profiles and workflows must use their concrete host agent instead.
+Account selection is available for Claude, Codex, Gemini, Cursor, Antigravity, Grok, Kimi, Droid, and OpenCode. It requires a terminal and cannot be combined with `--resume`, `--strategy`/`--balanced`, `--lease`, or `--device`; profiles and workflows must use their concrete host agent instead.
 
 ### Chain agents
 
@@ -215,7 +215,7 @@ Supports plan (read-only), edit, auto, and skip modes, effort levels, JSON outpu
 ### What does `--mode skip` actually do?
 
 Treat `skip` as a last-resort escape hatch. In direct-exec runs (without `--acp`),
-agents-cli forwards the harness's native no-prompt flag; it does not add another
+agi-cli forwards the harness's native no-prompt flag; it does not add another
 safety layer. Prefer `auto` where it adds a safer automatic policy (smart classifier
 on Claude/Copilot, native high-auto mode on Droid, or interactive Kimi), or `edit`
 everywhere else. For headless Kimi, `edit`, `auto`, and `skip` all use the same
@@ -235,7 +235,7 @@ bypass. Harnesses without a native bypass flag reject direct-exec `skip`.
 | Kimi | `--yolo` interactively; no extra flag in headless `-p` runs, which already auto-approve |
 | Droid | `--skip-permissions-unsafe` |
 
-With `--acp`, these native flags are not used. agents-cli instead grants `skip`
+With `--acp`, these native flags are not used. agi-cli instead grants `skip`
 permission requests at the ACP protocol layer: it selects `allow_always` when offered,
 otherwise the first permission option offered by the server. The same last-resort
 warning applies.
@@ -256,7 +256,7 @@ but new scripts should use the explicit `skip` name.
 agents run claude "review this diff" --acp --json
 ```
 
-`--acp` routes through the [Agent Client Protocol](https://github.com/zed-industries/agent-client-protocol) so you get a unified event stream -- `agent_message_chunk`, `tool_call`, `plan_update`, `stop_reason` -- instead of writing a parser per CLI. File writes and shell commands flow through agents-cli, which means `--mode plan` becomes a real sandbox: the write RPC is denied, not just unused.
+`--acp` routes through the [Agent Client Protocol](https://github.com/zed-industries/agent-client-protocol) so you get a unified event stream -- `agent_message_chunk`, `tool_call`, `plan_update`, `stop_reason` -- instead of writing a parser per CLI. File writes and shell commands flow through agi-cli, which means `--mode plan` becomes a real sandbox: the write RPC is denied, not just unused.
 
 ACP adapters are documented for claude, codex, cursor, opencode, openclaw, and grok. Other harnesses keep running on the direct-exec path.
 
@@ -285,6 +285,9 @@ agents sessions a1b2c3d4 --markdown
 # Render a shareable, redacted Markdown transcript with the session preview on top
 agents sessions render a1b2c3d4 -o session.md
 
+# Or publish it as a link in one step (unlisted + redacted by default)
+agents sessions share a1b2c3d4
+
 # Just the last 3 turns, user messages only
 agents sessions a1b2c3d4 --last 3 --include user
 
@@ -369,6 +372,8 @@ Landing on a session cold? `agents sessions <id>` prints a catch-up digest: an i
 
 Sharing a session uses `agents sessions render <id> -o session.md`, not the raw harness JSONL. The document starts with that same preview, then presents user and assistant turns, fenced commands, structured tool arguments, and bounded tool output. Credential-shaped values and local home paths are redacted by default; `--no-redact` is for local-only inspection.
 
+`agents sessions share <id>` goes one step further and publishes that document as a self-contained web page on your own share endpoint, printing the link. It is **unlisted** unless you pass `--public` — a transcript carries file paths, command output, and error text that a plan does not, so it stays out of your public gallery by default, and emails are masked on top of the render's own redaction. The slug is `session-<shortId>`, so re-sharing one session updates one URL.
+
 ### Resume anywhere — and stay resumed
 
 Pick up any past conversation and drop it back into a terminal:
@@ -377,12 +382,12 @@ Pick up any past conversation and drop it back into a terminal:
 agents sessions resume                     # multi-select; packs two sessions per tab
 agents sessions resume "auth middleware"   # pre-filter the pool, then choose
 agents sessions resume --tmux              # into persistent tmux — survives editor restarts
-agents sessions resume --host zion --tmux  # resume on another machine over SSH
-agents resume 019fd0c8-b3e9-77a2-a1a4-444698c4d897  # original harness/version/device/mode
+agents sessions resume --device zion --tmux  # resume on another machine over SSH
+agents sessions resume 019fd0c8-b3e9-77a2-a1a4-444698c4d897  # original harness/version/device/mode
 agents run auto --resume 019fd0c8-b3e9-77a2-a1a4-444698c4d897  # adapt if its account is unavailable
 ```
 
-`agents sessions resume` reopens several sessions in whatever terminal you're in -- auto-detected across iTerm, Ghostty, tmux, and the VSCodium agent-terminal, or forced with `--iterm` / `--ghostty` / `--tmux` / `--vscodium`. `agents resume <id>` resumes one session without requiring you to name its harness: exact IDs take a local SQLite fast path, then resolve fleet-wide and recover on the source device. If the origin version is installed, signed in, healthy, and still owns the indexed transcript, its isolated home performs native resume. Claude launches that native resume from the original project directory recorded before the first turn, so its `projects/<cwd-key>` lookup reaches the conversation even when the session later changed directories. Otherwise a healthy version of the **same harness** starts with `/continue <id>`, which reads the indexed transcript even when the old version home is retained under version trash or the same version number was reinstalled into a new home. It never native-resumes from a different isolated home. Back them with **tmux** and the runs turn durable: detach, close your editor, reboot the GUI -- the session is still alive to `agents tmux attach`. The whole `agents tmux` subsystem (persistent multiplexer sessions that survive editor restarts and can be shared with other tools) sits underneath.
+`agents sessions resume` reopens several sessions in whatever terminal you're in -- auto-detected across iTerm, Ghostty, tmux, and the VSCodium agent-terminal, or forced with `--iterm` / `--ghostty` / `--tmux` / `--vscodium`. `agents sessions resume <id>` resumes one session without requiring you to name its harness: exact IDs take a local SQLite fast path, then resolve fleet-wide and recover on the source device. If the origin version is installed, signed in, healthy, and still owns the indexed transcript, its isolated home performs native resume. Claude launches that native resume from the original project directory recorded before the first turn, so its `projects/<cwd-key>` lookup reaches the conversation even when the session later changed directories. Otherwise a healthy version of the **same harness** starts with `/continue <id>`, which reads the indexed transcript even when the old version home is retained under version trash or the same version number was reinstalled into a new home. It never native-resumes from a different isolated home. Back them with **tmux** and the runs turn durable: detach, close your editor, reboot the GUI -- the session is still alive to `agents tmux attach`. The whole `agents tmux` subsystem (persistent multiplexer sessions that survive editor restarts and can be shared with other tools) sits underneath.
 
 ### Send an agent to the background — and bring it back
 
@@ -419,7 +424,7 @@ agents message tester "also cover the null case"
 ```bash
 agents feed                         # grouped by outcome (ticket/PR/worktree) across the fleet
 agents feed --flat                  # one row per agent (legacy)
-agents feed --host mac-mini         # scope the view to one or more hosts
+agents feed --device mac-mini         # scope the view to one or more hosts
 agents feed --local                 # skip the SSH fan-out
 agents feed --json                  # blocks stamped with their outcome key
 agents feed post --title "Halfway done" "CI green, watching merge"  # title + body
@@ -445,11 +450,11 @@ A stalled session whose tail shows a hard account limit ("You've hit your weekly
 ## Sync the fleet
 
 <p align="center">
-  <img src="assets/fleet-sync.svg" alt="agents apply: reconcile every device to one profile from agents.yaml — install missing agents, sync config, and propagate logins across the fleet." width="100%" />
+  <img src="assets/fleet-sync.svg" alt="agents apply: reconcile every device to one profile from agents.yaml — install missing agents and sync config. Native logins stay on the machine that minted them." width="100%" />
 </p>
 
 
-One machine is set up the way you like it. Make every other machine match -- same agents installed, same config, logins seeded -- in one command.
+One machine is set up the way you like it. Make every other machine match -- same agents installed, same config -- in one command. Native OAuth logins stay on the box that minted them; portable provider accounts move only via `agents accounts sync`.
 
 ```yaml
 # agents.yaml -- add a fleet: block
@@ -458,7 +463,7 @@ fleet:
   defaults:
     agents: [claude@latest, codex@latest, antigravity@latest]
     sync: [user]            # config scopes to reconcile
-    login: sync             # propagate logins where the token is portable
+    login: sync             # surface needs-login; never copies native OAuth
 ```
 
 ```bash
@@ -469,7 +474,7 @@ agents apply --only agents,config   # limit dimensions (agents, config, login)
 agents apply --no-login             # skip login propagation
 ```
 
-`agents apply` (`ag apply`) probes every target over the existing SSH transport, then reconciles it to the profile: installs missing agents, upgrades `agents-cli`, syncs the named config scopes, and **propagates logins** so a host signed in once seeds the fleet -- turning "6 hosts x 8 harnesses = 48 OAuth flows" into one. Portable credential files (claude, codex, grok, kimi, opencode, droid, antigravity) stream to each target over encrypted SSH stdin, never shell-interpolated, and land at `0600`. **Honest boundary:** macOS keychain-bound tokens (claude, antigravity on a Mac target) can't be extracted -- those surface as a one-time manual login, never faked. `--plan` / `--dry-run` shows the full matrix without touching anything.
+`agents apply` (`ag apply`) probes every target over the existing SSH transport, then reconciles it to the profile: installs missing agents, upgrades `agi-cli`, syncs the named config scopes, and **propagates logins** so a host signed in once seeds the fleet -- turning "6 hosts x 8 harnesses = 48 OAuth flows" into one. Portable credential files (claude, codex, grok, kimi, opencode, droid, antigravity) stream to each target over encrypted SSH stdin, never shell-interpolated, and land at `0600`. **Honest boundary:** macOS keychain-bound tokens (claude, antigravity on a Mac target) can't be extracted -- those surface as a one-time manual login, never faked. `--plan` / `--dry-run` shows the full matrix without touching anything.
 
 See [docs/fleet.md](apps/cli/docs/fleet.md) for the manifest schema and reconcile semantics.
 
@@ -516,7 +521,7 @@ Multiple provider accounts to juggle? See [Accounts](#accounts) below.
 ```bash
 # Kimi K2.5 responding inside Claude Code's UI, tools, and skills.
 # No proxy server. No LiteLLM. One OpenRouter key, stored in Keychain.
-agents profiles add kimi
+agents harness add kimi
 agents run kimi "refactor this file"
 ```
 
@@ -545,7 +550,30 @@ auth:
   keychainItem: agents-cli.ollama.token
 ```
 
-Profile YAML has no secrets -- safe to `agents repo push` to a shared repo. `agents profiles presets` lists the full catalog.
+Profile YAML has no secrets -- safe to `agents repo push` to a shared repo. `agents harness list` lists the full catalog.
+
+---
+
+## Named routers
+
+A **router** is a reusable, task-typed allowlist -- which harnesses, which models/tiers per harness, and which linked accounts a task may be routed to. It's a generalization of a profile: a profile is a router pinned to one harness and one account.
+
+```bash
+# Scope a router to two harnesses, capped at a tier
+agents route create research --harness gemini,kimi --tier cheap,default
+
+# Narrow one harness's model set
+agents route allow research kimi kimi-k2
+
+# Only these accounts are eligible when routing under this router
+agents route link-account research gemini personal
+agents route link-account research kimi work
+
+agents route show research
+agents route list --json
+```
+
+Router YAML has no secrets -- safe to `agents repo push` to a shared repo. Harness ids and model/tier tokens are validated on `create`/`allow`: an unknown harness or an unverifiable model id fails loud and writes nothing. Routers resolve as a layered resource (project > user > system, same as profiles).
 
 ---
 
@@ -561,24 +589,24 @@ Dispatch any read-only or config command -- and `agents run` itself -- to anothe
 ```bash
 # Enroll a machine (from ~/.ssh/config, or inline with user@address)
 agents hosts add gpu-box
-agents hosts check gpu-box              # reachable? which agents-cli version?
+agents hosts check gpu-box              # reachable? which agi-cli version?
 
 # Run there instead of locally
-agents run claude --host gpu-box "profile this build"   # headless: follows live by default
-agents run claude --host gpu-box                         # no prompt → interactive TTY over SSH (tmux-backed)
-agents run claude --host gpu-box --copy-creds "fix auth" # copy local runtime creds + Claude token, shred after
+agents run claude --device gpu-box "profile this build"   # headless: follows live by default
+agents run claude --device gpu-box                         # no prompt → interactive TTY over SSH (tmux-backed)
+agents accounts sync work --device gpu-box               # portable provider account only; native OAuth stays local
 agents run claude --device auto "…"                      # affinity-pick host from 14d usage (harness stays claude)
-agents run claude --host auto "…"                        # same — auto is a host value, not a harness name
+agents run claude --device auto "…"                        # same — auto is a host value, not a harness name
 agents view kimi --device all                            # fan out across every registered device (grouped-by-OS roster)
-agents output --device all                               # per-device burn vs shipped output across the fleet
+agents insights output --device all                      # per-device burn vs shipped output across the fleet
 agents view --device all --json                          # machine-readable fleet inventory
 agents hosts ps                         # list dispatched runs + terminal status
 agents hosts stop <id>                  # terminate a hung/detached run (alias: kill)
-agents logs --host gpu-box              # pick a dispatched run — concise summary by default
+agents logs --device gpu-box              # pick a dispatched run — concise summary by default
 agents logs <id> --full                 # the full raw transcript / stdout (token-heavy)
 agents logs <id> -f                     # re-attach to a running one and follow
-agents view claude --host gpu-box       # inspect the remote install
-agents sync --host gpu-box              # make the remote machine current
+agents view claude --device gpu-box       # inspect the remote install
+agents sync --device gpu-box              # make the remote machine current
 agents doctor claude                    # diagnose every installed claude version
 agents doctor claude@latest             # diagnose only the newest installed version
 agents doctor claude@oldest             # diagnose only the oldest installed version
@@ -600,25 +628,29 @@ agents doctor --check --devices         # CI drift gate across every registered
 
 # Your Tailscale fleet, auto-discovered
 agents devices sync                     # ingest `tailscale status`
+agents devices ignore ipad              # sync the dismissal via agents.yaml fleet.discovery
+agents repo push user                    # carry device decisions to the other machines
+agents repo pull user                    # pull and reconcile them into this machine's registry
 agents devices list                     # fleet + headroom: load, mem, idle/busy — which box has room (cache-first)
 agents devices list --live              # force a live probe of every device (alias of --refresh)
 agents devices list --full              # add per-device cores and free/total RAM
 agents devices list --no-stats          # instant: names/addresses only, skip the probe
 agents devices config zion interactive.host zion   # the device agents show YOU artifacts on (★ in the list)
-agents devices config mac-mini agents.max-concurrent 4   # per-device settings (central fleet.devices.<name>.config)
+agents devices config mac-mini agents.max-concurrent 4   # per-device settings (tracked devices/<name>/agents.yaml)
 agents devices config mac-mini scheduler.enabled off     # bare `devices config <name>` opens a settings menu (TTY)
+agents devices config --fleet agents.max-concurrent 2    # fleet-wide default every device inherits
 agents devices config mac-mini notes "runs the releases — don't reboot"   # operator notes, repeat to append
 agents ssh mac-mini                     # hardened SSH: fails fast if offline,
                                         # PowerShell on Windows, password-from-Keychain,
                                         # auto-syncs your terminfo (Ghostty/kitty/…) so
                                         # backspace, colors & clear work on the remote
-agents cp mac-mini:/abs/log.json /tmp/  # fleet file transfer; host:path or abs local
-agents cp -r /tmp/src/ yosemite-s0:~/dst/  # ~ and $HOME expand on the REMOTE, never locally
+scp mac-mini:/abs/log.json /tmp/        # fleet file transfer; host:path or abs local
+scp -r /tmp/src/ yosemite-s0:~/dst/     # ~ and $HOME expand on the REMOTE, never locally
 agents hosts list                       # devices show up here too (one host pool)
-agents hosts add mac-mini --cap gpu     # tag a device for capability routing (--host gpu)
+agents hosts add mac-mini --cap gpu     # tag a device for capability routing (`--device` + `--cap gpu`)
 
 # Hosts as a task backend + scheduled placement
-agents cloud run "nightly benchmark" --host gpu-box --agent claude   # task in cloud ps AND hosts ps
+agents cloud run "nightly benchmark" --device gpu-box --agent claude   # task in cloud ps AND hosts ps
 agents routines add nightly -s "0 2 * * *" -a claude -p "run the sweep" --run-on gpu-box
 ```
 
@@ -659,9 +691,9 @@ email) and naming which harnesses use it — the fast way to see which accounts
 and healthy across every machine. Scope either with `--agents <csv>` / `--device <csv>`, and
 add `--json` for the machine-readable per-host rows.
 
-**Hosts** (`agents hosts`) are git-synced dispatch targets in `agents.yaml`; **devices** (`agents devices`) are your Tailscale machines in a local registry. Both ride SSH and feed one host pool: devices appear in `agents hosts list` and capability routing without a second enrollment. On `--host` runs every `agents run` option is either forwarded (`--effort --env --timeout --loop …`), rejected loud (`--secrets` never crosses SSH implicitly), or consumed locally — nothing silently drops. See [docs/concepts.md](apps/cli/docs/concepts.md#devices--hosts).
+**Hosts** (`agents hosts`) are git-synced dispatch targets in `agents.yaml`; **devices** (`agents devices`) are your Tailscale machines in a local registry. Both ride SSH and feed one host pool: devices appear in `agents hosts list` and capability routing without a second enrollment. On `--device` runs every `agents run` option is either forwarded (`--effort --env --timeout --loop …`), rejected loud (`--secrets` never crosses SSH implicitly), or consumed locally — nothing silently drops. See [docs/concepts.md](apps/cli/docs/concepts.md#devices--hosts).
 
-Every `--host` command rides one multiplexed SSH engine, tuned for driving a fleet from a small laptop: the first call to a machine opens a control socket and every later call reuses it (no repeat TCP+auth handshake), connections carry keepalive so a dropped link dies in ~45 s instead of zombying, and following a remote run polls in a single round-trip per cycle. Measured against a Tailscale-relayed host: repeated calls **~6–7× faster**, dispatch readiness **~2×**, and the follow loop **~21× faster with 50% fewer local ssh spawns**. Design: [docs/ssh-transport.md](apps/cli/docs/ssh-transport.md) · reproduce: `node scripts/bench-ssh.mjs <host>`.
+Every `--device` command rides one multiplexed SSH engine, tuned for driving a fleet from a small laptop: the first call to a machine opens a control socket and every later call reuses it (no repeat TCP+auth handshake), connections carry keepalive so a dropped link dies in ~45 s instead of zombying, and following a remote run polls in a single round-trip per cycle. Measured against a Tailscale-relayed host: repeated calls **~6–7× faster**, dispatch readiness **~2×**, and the follow loop **~21× faster with 50% fewer local ssh spawns**. Design: [docs/ssh-transport.md](apps/cli/docs/ssh-transport.md) · reproduce: `node scripts/bench-ssh.mjs <host>`.
 
 ---
 
@@ -692,7 +724,7 @@ Team state is observable via `agents teams list --json` / `agents teams status -
 
 ## Cloud
 
-Some work shouldn't tie up your laptop. `agents cloud run` hands a task to a managed provider that clones the repo, plans, implements, tests, and opens a PR -- while your terminal stays free. The `host` provider dispatches the same way onto machines you own: `agents cloud run "…" --host gpu-box` (tasks track in `agents cloud ps` and `agents hosts ps` alike).
+Some work shouldn't tie up your laptop. `agents cloud run` hands a task to a managed provider that clones the repo, plans, implements, tests, and opens a PR -- while your terminal stays free. The `host` provider dispatches the same way onto machines you own: `agents cloud run "…" --device gpu-box` (tasks track in `agents cloud ps` and `agents hosts ps` alike).
 
 <p align="center">
   <img src="assets/cloud.svg" alt="agents cloud run dispatches one prompt to a managed provider (Rush, Codex, Cursor, Factory, or Antigravity) that runs while you keep working" width="100%" />
@@ -721,7 +753,7 @@ Five managed backends behind one interface (`agents cloud providers`):
 
 Auto-routes each `--agent` to its native cloud, or pin the backend with `--provider`. Instead of dispatching now, register a run as an **event trigger** with `--on pull_request` (also `push`, `issue_comment`, `workflow_run`) -- it persists as a trigger-bound routine that fires on the event. `--json` on every subcommand for scripting.
 
-The same dispatch is a placement on `agents run`: `agents run claude "fix the flaky e2e" --cloud --repo acme/api` routes through the identical provider registry and tracks in `agents cloud list/status/logs` alike. `--cloud` sits alongside `--host`/`--device`/`--lease` as one of three placements (local, machine, cloud) and is mutually exclusive with them; `--where cloud[:provider]` is the one-door spelling. Agents without a native cloud fail loud unless `--provider` is given.
+The same dispatch is a placement on `agents run`: `agents run claude "fix the flaky e2e" --cloud --repo acme/api` routes through the identical provider registry and tracks in `agents cloud list/status/logs` alike. `--cloud` sits alongside `--device`/`--lease` as one of three placements (local, machine, cloud) and is mutually exclusive with them; `--where cloud[:provider]` is the one-door spelling. Agents without a native cloud fail loud unless `--provider` is given.
 
 ---
 
@@ -814,11 +846,11 @@ A plugin is a directory with a manifest:
   permissions/                     # optional — executable surface
 ```
 
-On sync, agents-cli copies the plugin into each version home's marketplace (`<home>/.claude/plugins/marketplaces/agents-cli/plugins/<name>/`), registers the synthetic marketplace, and flips `settings.json#enabledPlugins[<name>@agents-cli] = true` so Claude / OpenClaw load it.
+On sync, agi-cli copies the plugin into each version home's marketplace (`<home>/.claude/plugins/marketplaces/agents-cli/plugins/<name>/`), registers the synthetic marketplace, and flips `settings.json#enabledPlugins[<name>@agents-cli] = true` so Claude / OpenClaw load it.
 
 ### Executable-surface gate
 
-Plugins that ship `hooks/`, `.mcp.json`, `bin/`, `scripts/`, `settings.json` (non-permissions), or `permissions/` can execute code on session events. agents-cli requires explicit consent before flipping `enabledPlugins`:
+Plugins that ship `hooks/`, `.mcp.json`, `bin/`, `scripts/`, `settings.json` (non-permissions), or `permissions/` can execute code on session events. agi-cli requires explicit consent before flipping `enabledPlugins`:
 
 ```bash
 # Hooks-bearing plugins copy in but stay disabled by default
@@ -839,22 +871,22 @@ Plugins live in the user repo (`~/.agents/plugins/`), not inside any single vers
 
 ## Make it yours
 
-White-label the CLI. `agents setup mine` mints a **personally-named binary** — `jack` instead of `agents` — that _is_ agents-cli: same tool, your name, running the exact feature set you choose. Anyone can mint their own; Jack and Pranjal each get an independent brand.
+White-label the CLI. `agents setup mine` mints a **personally-named binary** — `jack` instead of `agents` — that _is_ agi-cli: same tool, your name, running the exact feature set you choose. Anyone can mint their own; Jack and Pranjal each get an independent brand.
 
 ```bash
 agents setup mine                      # wizard: pick a name, check off what to disable
-agents mine init jack --disable teams cloud   # or non-interactively
+agents setup mine init jack --disable teams cloud   # or non-interactively
 
 jack run claude "hello"                # every agents verb, under your name
 jack --help                            # help, version, and errors all read "jack"
 ```
 
-Manage brands with `agents mine list | toggle | remove`:
+Manage brands with `agents setup mine list | toggle | remove`:
 
 ```bash
-agents mine toggle jack --disable-plugin rush --disable-skill deploy
-agents mine toggle jack --enable teams
-agents mine remove jack --purge
+agents setup mine toggle jack --disable-plugin rush --disable-skill deploy
+agents setup mine toggle jack --enable teams
+agents setup mine remove jack --purge
 ```
 
 Under the hood, `init` drops a pure pass-through shim in `~/.agents/.cache/shims/<name>` (already on `PATH`) that sets `AGENTS_BRAND` and forwards every argument to the same binary — nothing is copied or forked. The brand's config lives in `~/.agents/agents.yaml` (`brands.<name>`), so it rides `agents repo push/pull` across your fleet. Disabling a command hides it **only** under that brand; plain `agents` / `ag` keep every command. Curated skills/plugins/MCP ride a per-brand [resource profile](apps/cli/docs/profiles.md). Full reference: [Make it yours](apps/cli/docs/mine.md).
@@ -977,12 +1009,12 @@ agents accounts add deepinfra --provider deepinfra --auth api-key
 agents accounts set-default claude work   # claude uses `work` when --account is omitted
 agents accounts sync work --device yosemite-s0   # explicitly copy the bundle to a worker device
 agents run claude --account work
-agents profiles add deepinfra --account deepinfra
+agents harness add deepinfra --account deepinfra
 ```
 
 One provider account **is** one `agents secrets` bundle -- `agents accounts add` creates it with secrets policy `never`, so a background agent launch on that account never raises Touch ID. `agents accounts` (no subcommand) lists provider bundles next to harness-native signed-in identities so you see both kinds of credential together; `accounts list` / `inspect <name>` / `set-key <name>` (rotate) / `rename` / `remove` manage a bundle by its stable id, independent of its current label.
 
-Harness-native OAuth logins (Claude Code's own `/login`, `codex login`, and so on) stay exactly where the harness put them -- agents-cli discovers and displays them but never copies, renames, or converts them into a provider bundle. `accounts sync <name> --device <device>` is the only way a provider account crosses machines, and it's explicit: nothing syncs automatically. Selection order for a run is explicit `--account`, then `accounts set-default` for that harness, then the harness's native/balanced account behavior.
+Harness-native OAuth logins (Claude Code's own `/login`, `codex login`, and so on) stay exactly where the harness put them -- agi-cli discovers and displays them but never copies, renames, or converts them into a provider bundle. `accounts sync <name> --device <device>` is the only way a provider account crosses machines, and it's explicit: nothing syncs automatically. Selection order for a run is explicit `--account`, then `accounts set-default` for that harness, then the harness's native/balanced account behavior.
 
 ---
 
@@ -1002,7 +1034,7 @@ agents run claude "charge a test card" --secrets prod-stripe
 ```
 
 <p align="center">
-  <img src="assets/secrets.svg" alt="How agents-cli secrets work: bundle definitions live in the macOS Keychain alongside their values, agents-cli resolves at runtime and injects the env into the child process" width="100%" />
+  <img src="assets/secrets.svg" alt="How agi-cli secrets work: bundle definitions live in the macOS Keychain alongside their values, agi-cli resolves at runtime and injects the env into the child process" width="100%" />
 </p>
 
 Merge order: profile env < `--secrets` < `--env K=V`. A missing keychain item aborts before the child starts.
@@ -1061,14 +1093,14 @@ agents routines add nightly-drain --schedule "0 3 * * *" --agent claude \
   --prompt "Drain the local work queue"
 
 agents routines devices nightly-drain --set yosemite-s0           # one schedule owner
-agents routines list --host yosemite-s0                            # query another device
+agents routines list --device yosemite-s0                            # query another device
 
 # Signed webhook trigger: Linear issue labeled "agent" fires a routine
 agents routines add agent-labeled-issue --on linear:Issue --action update \
   --team-key RUSH --label agent --agent claude \
   --cwd '~' \
   --prompt "Work the Linear issue that was just labeled agent"
-agents webhook serve --secrets-bundle webhooks --port 8787          # /hooks/linear, /hooks/github
+agents daemon webhooks add --secrets-bundle webhooks --port 8787    # supervised receiver: /hooks/linear, /hooks/github
 agents daemon funnel up yosemite-s0 --local-port 8787 --port 443    # public HTTPS ingress
 ```
 
@@ -1160,7 +1192,10 @@ Sources: a command's stdout (`--watch` / `--poll`), an HTTP endpoint (`--poll-ht
 # Publish an HTML artifact to a public link on your own Cloudflare R2 (~$0).
 agents artifacts setup                                      # once: provision bucket + Worker on your CF
 agents artifacts share plan.html --slug fleet --expire 30d  # → https://<base>/fleet
+agents artifacts share plan.html --label "Q3 fleet plan" --meta kind=plan   # human title + structured metadata
 agents artifacts share plan.html --json                     # URL object for plan-render hooks
+agents artifacts share list --agent claude                  # everything published, filterable
+agents artifacts share revisions fleet                      # prior versions kept under a slug
 agents artifacts share status                               # show the endpoint
 agents unshare fleet                                        # take a published link (+ its OG cover) down
 ```
@@ -1177,8 +1212,19 @@ this is effectively free.
 **Fleet mode:** provision one endpoint, then every fleet / cloud / ephemeral agent
 publishes through it with a shared write token — `agents artifacts share join <baseUrl>` uses an
 existing endpoint with no provisioning. `--expire 30d|12h|<date>` auto-expires a link.
-`--json` emits `{ url, coverUrl, expiresAt }` so plan-render automation can publish the
-rendered HTML and post the returned link without scraping terminal text.
+`--json` emits `{ url, coverUrl, expiresAt, label, labelSource }` so plan-render automation can
+publish the rendered HTML and post the returned link without scraping terminal text.
+
+**Every share carries provenance and a title.** Agent/session/host/repo/date are
+captured automatically from the exec env and git — never invented, only sent when
+present. `--label`/`--title` names a share (else one is derived from the HTML
+`<title>`, frontmatter, or filename, with a nudge — never a blocking prompt); `--meta
+key=value` attaches structured metadata (`kind`, `project`, `ticket`, `status`, ...).
+`agents artifacts share list --agent <name> | --session <id> | --label-contains <substr>` filters
+by any of it, so the listing is a real "what have I shared" gallery, not just slugs.
+Republishing an existing slug keeps the prior version as a revision by default
+(`--no-revision` to skip); `agents artifacts share revisions <slug>` shows the retained
+history, newest first.
 
 `agents artifacts share delete <targets...>` (alias `agents unshare`) takes a page down — pass a
 full URL, `<user>/<slug>`, or a bare slug (resolved against your own namespace); several
@@ -1227,7 +1273,7 @@ Two repos with the same shape, different roles:
 
 | Repo | Role | Owner |
 |---|---|---|
-| `~/.agents-system/` | **System repo** — core/built-in skills, commands, hooks, rules, MCP configs, permissions, and profiles that ship with `agents-cli`. The defaults every install gets. | Maintained upstream at [phnx-labs/.agents-system](https://github.com/phnx-labs/.agents-system) |
+| `~/.agents-system/` | **System repo** — core/built-in skills, commands, hooks, rules, MCP configs, permissions, and profiles that ship with `agi-cli`. The defaults every install gets. | Maintained upstream at [phnx-labs/.agents-system](https://github.com/phnx-labs/.agents-system) |
 | `~/.agents/` | **User repo** — your personal additions and overrides. This is what `agents repo push`/`pull` syncs. | You |
 
 **Version pinning:** `agents.yaml` at project root pins which agent version to use (like `.nvmrc` for Node).
@@ -1236,13 +1282,13 @@ Two repos with the same shape, different roles:
 
 See [docs/concepts.md](apps/cli/docs/concepts.md) for the full mental model: DotAgents repos, resource kinds, and how resolution works end-to-end.
 
-Other useful commands: `agents doctor` checks CLI availability and resource sync drift, `agents usage` shows available quota/rate-limit data for installed agents, `agents budget` shows cross-vendor spend caps and current spend-to-cap (and enforces pre-flight estimates + a hard-cap kill-switch on every run — see [docs/observability.md](apps/cli/docs/observability.md#budget-guardrails-agents-budget)), `agents import` adopts an existing unmanaged install, `agents trash` lists and restores soft-deleted version directories, and `agents subagents` installs reusable subagent definitions for parent-agent workflows.
+Other useful commands: `agents doctor` checks CLI availability and resource sync drift, `agents usage` shows available quota/rate-limit data for installed agents, `agents config budget` shows cross-vendor spend caps and current spend-to-cap (and enforces pre-flight estimates + a hard-cap kill-switch on every run — see [docs/observability.md](apps/cli/docs/observability.md#budget-guardrails-agents-budget)), `agents import` adopts an existing unmanaged install, `agents trash` lists and restores soft-deleted version directories, and `agents subagents` installs reusable subagent definitions for parent-agent workflows.
 
 ---
 
 ## Menu bar
 
-On macOS, `agents-cli` puts a status item in your menu bar -- a live glance at what your agents are doing, plus a Spotlight-style bar for filing work without breaking focus.
+On macOS, `agi-cli` puts a status item in your menu bar -- a live glance at what your agents are doing, plus a Spotlight-style bar for filing work without breaking focus.
 
 ```bash
 agents menubar setup       # configure end-to-end: one instance, started at login
@@ -1292,7 +1338,7 @@ Extras clone into `~/.agents-system/.repos/<alias>/` and ship the same layout as
 
 ## Security & Privacy
 
-**The CLI binary has no built-in telemetry or phone-home path.** Routine commands run locally; explicit features such as cloud dispatch and iCloud Keychain sync send only the data needed for the action you invoke. Here's exactly what `agents-cli` stores locally and why.
+**The CLI binary has no built-in telemetry or phone-home path.** Routine commands run locally; explicit features such as cloud dispatch and iCloud Keychain sync send only the data needed for the action you invoke. Here's exactly what `agi-cli` stores locally and why.
 
 ### Event log
 
@@ -1361,7 +1407,7 @@ By default, secrets sync via iCloud Keychain to your other Macs. With `--no-iclo
 
 Which DotAgents resources each agent CLI can load. Source of truth: [src/lib/agents.ts](apps/cli/src/lib/agents.ts) (`capabilities`); gates use `supports(agent, cap, version)` from [src/lib/capabilities.ts](apps/cli/src/lib/capabilities.ts). Full matrix also in [docs/concepts.md](apps/cli/docs/concepts.md).
 
-> **Gemini CLI is hard-deprecated.** Google retired it for free, Pro, and Ultra tiers on **June 18, 2026** (announced at Google I/O 2026); the `gemini` command no longer serves requests on those tiers. agents-cli keeps the legacy `gemini` id only so old sessions/config can still be read. `agents add gemini`, `agents import gemini`, and `agents sync gemini` fail and point to **Antigravity CLI** (`antigravity`), Google's official successor — see [the transition notice](https://developers.googleblog.com/an-important-update-transitioning-gemini-cli-to-antigravity-cli/).
+> **Gemini CLI is hard-deprecated.** Google retired it for free, Pro, and Ultra tiers on **June 18, 2026** (announced at Google I/O 2026); the `gemini` command no longer serves requests on those tiers. agi-cli keeps the legacy `gemini` id only so old sessions/config can still be read. `agents add gemini`, `agents import gemini`, and `agents sync gemini` fail and point to **Antigravity CLI** (`antigravity`), Google's official successor — see [the transition notice](https://developers.googleblog.com/an-important-update-transitioning-gemini-cli-to-antigravity-cli/).
 
 | Agent | Versions | Hooks | MCP | Permissions | Skills | Commands | Plugins | Subagents | Rules | Workflows |
 |-------|----------|-------|-----|-------------|--------|----------|---------|-----------|-------|-----------|
@@ -1383,7 +1429,7 @@ Which DotAgents resources each agent CLI can load. Source of truth: [src/lib/age
 
 **Host CLIs** (`agents cli`) are separate: YAML manifests under `~/.agents/cli/` install binaries onto your PATH (`gh`, `higgsfield`, etc.). They are not copied into per-agent version homes.
 
-### agents-cli features (not agent-native resources)
+### agi-cli features (not agent-native resources)
 
 | Agent | Routines | Teams | Session index |
 |-------|----------|-------|---------------|
@@ -1409,7 +1455,7 @@ Which DotAgents resources each agent CLI can load. Source of truth: [src/lib/age
 | File-based commands | Codex | < 0.117.0 (0.117+ uses command-as-skill) |
 | Plugins | Codex | >= 0.128.0 |
 
-Codex `0.117.0+` no longer reads `.codex/prompts/`; agents-cli converts slash commands into skills so they stay invocable as `$name`. OpenCode's plugin-based hook system is on the roadmap; hooks stay `no` until a writer ships.
+Codex `0.117.0+` no longer reads `.codex/prompts/`; agi-cli converts slash commands into skills so they stay invocable as `$name`. OpenCode's plugin-based hook system is on the roadmap; hooks stay `no` until a writer ships.
 
 Slash commands can declare per-agent/version targeting in frontmatter (`agents:`, `since:`, `until:`). Gating applies when syncing from `~/.agents/commands/` (user/system) into version homes — project `.agents/commands/` files are read in place and are not filtered by `agents:`.
 
@@ -1425,7 +1471,7 @@ Yes. This developer tool is entirely free because we believe developers should h
 
 ### Is this like `nvm` / `mise` / `asdf` for AI agents?
 
-For version management, yes. `agents-cli` reads `agents.yaml` from the project root, walks up the directory tree, and routes to the correct binary per project. But it also manages agent-native resources (skills, MCP servers, commands, hooks, permissions) that language version managers don't touch.
+For version management, yes. `agi-cli` reads `agents.yaml` from the project root, walks up the directory tree, and routes to the correct binary per project. But it also manages agent-native resources (skills, MCP servers, commands, hooks, permissions) that language version managers don't touch.
 
 ### How does version switching actually work?
 
@@ -1447,13 +1493,13 @@ Your choice. We hand off to the original CLI process — use your existing subsc
 
 **No CLI telemetry or phone-home.** API keys come from your shell environment or each agent CLI's existing auth, and remote calls only happen when you invoke a feature that requires them, such as cloud dispatch.
 
-For full transparency: `agents-cli` keeps a local event log at `~/.agents/.cache/logs/` so you can see exactly what agents did on your machine. Logs are owner-readable only (0600) and auto-prune after 7 days. Set `AGENTS_DISABLE_EVENT_LOG=1` to disable. See [Security & Privacy](#security--privacy) for details.
+For full transparency: `agi-cli` keeps a local event log at `~/.agents/.cache/logs/` so you can see exactly what agents did on your machine. Logs are owner-readable only (0600) and auto-prune after 7 days. Set `AGENTS_DISABLE_EVENT_LOG=1` to disable. See [Security & Privacy](#security--privacy) for details.
 
 ### Which platforms?
 
 macOS and Linux. Windows via WSL works but isn't first-class yet.
 
-**macOS-only features:** Keychain-based secrets (`agents secrets`, `agents profiles login`) require macOS. Default iCloud sync for bundles requires macOS + iCloud Keychain enabled; use `--no-icloud-sync` for device-local bundles. On Linux, use environment variables or `.env` files for API keys. Native Linux credential store support is planned.
+**macOS-only features:** Keychain-based secrets (`agents secrets`, `agents harness login`) require macOS. Default iCloud sync for bundles requires macOS + iCloud Keychain enabled; use `--no-icloud-sync` for device-local bundles. On Linux, use environment variables or `.env` files for API keys. Native Linux credential store support is planned.
 
 Interactive tmux-backed runs require tmux 3.2 or newer.
 
@@ -1467,13 +1513,13 @@ Yes -- `agents run` is non-interactive by default. `--yes` auto-accepts prompts,
 
 The auto-update prompt is suppressed automatically when stdin or stdout isn't a TTY. For headless environments where TTY detection misfires (k8s pods that allocate a PTY for stdout, cloud sandbox factories), set `AGENTS_CLI_DISABLE_AUTO_UPDATE=1` to skip the update check entirely -- no prompt, no network call.
 
-agents-cli also prints a one-time "star us on GitHub" line after your first successful `agents run`/`agents teams`. It's already skipped in CI, non-TTY, `--json`, and `--quiet` runs; set `AGENTS_NO_NUDGE=1` to suppress it everywhere.
+agi-cli also prints a one-time "star us on GitHub" line after your first successful `agents run`/`agents teams`. It's already skipped in CI, non-TTY, `--json`, and `--quiet` runs; set `AGENTS_NO_NUDGE=1` to suppress it everywhere.
 
 To update on demand instead of waiting for the prompt, run `agents upgrade` (add `-y` to skip the confirmation, or pass a version/dist-tag to install something other than latest).
 
 ### What happens to my config when I switch versions?
 
-Each version has its own isolated config directory. Switching just repoints a symlink — your per-version config stays untouched. On first migration (if you had a real `~/.claude/` directory before using agents-cli), that gets backed up once to `~/.agents-system/backups/`.
+Each version has its own isolated config directory. Switching just repoints a symlink — your per-version config stays untouched. On first migration (if you had a real `~/.claude/` directory before using agi-cli), that gets backed up once to `~/.agents-system/backups/`.
 
 ### Does session search use RAG or semantic search?
 
@@ -1489,7 +1535,7 @@ Agents are defined in [src/lib/agents.ts](apps/cli/src/lib/agents.ts) -- each is
 
 ### What's the relationship to Phoenix Labs / Rush?
 
-`agents-cli` is an open client maintained by Phoenix Labs. Rush is a separate product. No Rush account required, no upsell.
+`agi-cli` is an open client maintained by Phoenix Labs. Rush is a separate product. No Rush account required, no upsell.
 
 ## This monorepo also contains
 
@@ -1505,8 +1551,8 @@ Agents are defined in [src/lib/agents.ts](apps/cli/src/lib/agents.ts) -- each is
 ## Contributing
 
 ```bash
-git clone https://github.com/phnx-labs/agents-cli
-cd agents-cli/apps/cli
+git clone https://github.com/phnx-labs/agi-cli
+cd agi-cli/apps/cli
 bun install && bun run build && bun test
 ```