agentworks-cli 0.2.1__tar.gz → 0.3.0__tar.gz

{agentworks_cli-0.2.1 → agentworks_cli-0.3.0}/.gitignore

@@ -26,6 +26,7 @@ rulesync.local.jsonc
 rulesync.lock
 
 # Rulesync - generated output (regenerate with: npx rulesync generate)
+.agents/
 CLAUDE.md
 .claude
 .claudeignore
@@ -33,10 +34,6 @@ CLAUDE.md
 .cursor/
 .cursorrules
 .cursorignore
-.github/*
-!.github/workflows
-!.github/ISSUE_TEMPLATE
-!.github/PULL_REQUEST_TEMPLATE.md
 .copilotignore
 AGENTS.md
 GEMINI.md

{agentworks_cli-0.2.1 → agentworks_cli-0.3.0}/CHANGELOG.md

@@ -1,5 +1,69 @@
 # Changelog
 
+## [0.3.0](https://github.com/WayfarerLabs/agentworks/compare/v0.2.1...v0.3.0) (2026-06-01)
+
+
+### ⚠ BREAKING CHANGES
+
+* split completion command into show/install with shell autodetection
+* drop local workspaces; all workspaces are VM-scoped
+
+### Features
+
+* **cli:** add 'aw console' command group ([dc833bd](https://github.com/WayfarerLabs/agentworks/commit/dc833bdc55ee02bb8e36c24a5e0b08fb91bdd0e6))
+* **cli:** Ctrl-C triggers per-op rollback; clean SIGINT exit ([0648b16](https://github.com/WayfarerLabs/agentworks/commit/0648b16f9d98c686c63a59eb1b2cac2cad9f8625))
+* **cli:** Ctrl-C triggers per-op rollback; clean SIGINT exit ([03ab4d0](https://github.com/WayfarerLabs/agentworks/commit/03ab4d0cf7ea4a6a7287443e6e79af6b8b97242c))
+* **cli:** ship 'agw' as a short-name alias for the agentworks binary ([c99c044](https://github.com/WayfarerLabs/agentworks/commit/c99c044ed0073308cc427aaa13f3cb31b82567f5))
+* **completions:** wire console commands for zsh/bash/powershell ([6181cb7](https://github.com/WayfarerLabs/agentworks/commit/6181cb751cc633333eac39b7e10d802507ef313c))
+* **consoles:** add --add-admin-shell flag for legacy vm-console behavior ([f337f38](https://github.com/WayfarerLabs/agentworks/commit/f337f38eba60b7dea78c315dcddf4e01f82940a4))
+* **consoles:** add 'Waiting for session to restart...' status line ([8fc20a7](https://github.com/WayfarerLabs/agentworks/commit/8fc20a7bdbac58f1894e301688f7dbd82b7249b4))
+* **consoles:** announce attach/build/rebuild path in console attach ([17d14aa](https://github.com/WayfarerLabs/agentworks/commit/17d14aa26451aa49ec5f7e592a8835c1d0c1c5d4))
+* **consoles:** hold windows open indefinitely; silent poll with banner when session is down ([10c002c](https://github.com/WayfarerLabs/agentworks/commit/10c002c410646ebe97f678f824eec69c64c92339))
+* **consoles:** infer --vm from sessions, add --all-running, fix variadic positional completions ([11c5742](https://github.com/WayfarerLabs/agentworks/commit/11c574210f00aed8e67ddef6ff91063dd46d9d5b))
+* **consoles:** infer --vm from sessions, add --all-running, fix variadic positional completions ([6bf8308](https://github.com/WayfarerLabs/agentworks/commit/6bf8308f467f5359b23a748d0454d9de56287c43))
+* **consoles:** show 'Waiting for session to restart...' after exit; use 'exited' ([780373b](https://github.com/WayfarerLabs/agentworks/commit/780373b6fe2e39a319c24a6f0bf6c61e73d14ca9))
+* **consoles:** tmux orchestration with shell panes and live sync ([1ebc1b1](https://github.com/WayfarerLabs/agentworks/commit/1ebc1b19d27714bdbfc39eec1951ee8d460c7cd8))
+* **db:** add consoles and console_sessions tables ([f255397](https://github.com/WayfarerLabs/agentworks/commit/f255397310f4e92cb96c82383a8c75baa211dfe0))
+* named consoles with curated session lists ([d7a36c2](https://github.com/WayfarerLabs/agentworks/commit/d7a36c2d8d37fef835deb62f791794c690c26035))
+* **sessions:** add multi_console core orchestration ([a0adfc8](https://github.com/WayfarerLabs/agentworks/commit/a0adfc8dbfea7485639b5fcdb34cdd68ddc8ecee))
+* ship 'agw' as a short-name alias for the agentworks CLI ([32be51a](https://github.com/WayfarerLabs/agentworks/commit/32be51a29e9d34551aa45650b83522ef810d0096))
+* support creating a new agent as part of session create ([f50b7a8](https://github.com/WayfarerLabs/agentworks/commit/f50b7a8b572199306532c75ac9a0530dd028c467))
+* support creating a new agent as part of session create ([7502755](https://github.com/WayfarerLabs/agentworks/commit/7502755e72d345a664d7415214166453bd9db52b))
+
+
+### Bug Fixes
+
+* _rehome_partial_state_hint mentions partial-copy possibility ([d31e55a](https://github.com/WayfarerLabs/agentworks/commit/d31e55af665e4b7fff44ff4188926e0260887e62))
+* accurate install path and dot-source wording in powershell script header ([cf8fa14](https://github.com/WayfarerLabs/agentworks/commit/cf8fa14b19d95b447b60bdef7a2f1773bda42524))
+* clean up agent grants for local workspaces in migration 26 and drop now-dead defensive code ([78b2254](https://github.com/WayfarerLabs/agentworks/commit/78b225420692174276875c22fbbaf5b57b6264e4))
+* **completions:** symlink bash completion under 'agw' so lazy-loading works ([9b32c82](https://github.com/WayfarerLabs/agentworks/commit/9b32c8293bb3d5284d82dabea1ab2b1ff32b58c9))
+* **consoles:** detect probe failure on --all-running; update help/docstring ([b411955](https://github.com/WayfarerLabs/agentworks/commit/b411955c05425530fe746c925bf384d0ffb6a896))
+* **consoles:** drop auto admin-shell window from named consoles ([44d9f37](https://github.com/WayfarerLabs/agentworks/commit/44d9f373fa130d2be2d74808f25eb7f57bb478c0))
+* **consoles:** make placeholder window name collision-proof; warn on list-windows failure ([6d387e1](https://github.com/WayfarerLabs/agentworks/commit/6d387e1931fbd8bc3a0587caca1c4ff9f90d9f0c))
+* **consoles:** retry attach loop with ~10s grace to survive session restart (closes [#51](https://github.com/WayfarerLabs/agentworks/issues/51)) ([98f4354](https://github.com/WayfarerLabs/agentworks/commit/98f43544b04c361cfbc3f17ac4eea16556f6e431))
+* cspell -- Americanize 'normalises'/'Recognises' and allow 'delenv'/'autodetection' ([3432f7d](https://github.com/WayfarerLabs/agentworks/commit/3432f7db1578424be986076d31b3de66024ef856))
+* point grant-recovery hints at the real CLI command ([a2c8189](https://github.com/WayfarerLabs/agentworks/commit/a2c81890f1fa87e149ba1b0c49f2a088643fd025))
+* revert grant-all DB grant on Ctrl-C during group add ([cb7f15b](https://github.com/WayfarerLabs/agentworks/commit/cb7f15bde65c331a65b44144d85f020743be25c5))
+* revert grant-all DB grant on Ctrl-C during the insert too ([1f52b5b](https://github.com/WayfarerLabs/agentworks/commit/1f52b5b6199009cbc47f436e7e7e6f96054c02fc))
+* route group membership through stored linux_group, add migration 22 test ([d0f8dbb](https://github.com/WayfarerLabs/agentworks/commit/d0f8dbbcb80fd53c2495183a0c1542824ca434e7))
+* **sessions:** stop creating duplicate console windows on restart; deprecate 'aw vm console' ([1874426](https://github.com/WayfarerLabs/agentworks/commit/18744269a34120568bd3d8aa1572db5cbf758f2c))
+* surface --shell hint in doctor and call PowerShell wiring a dot-source line ([e3e1672](https://github.com/WayfarerLabs/agentworks/commit/e3e167270db22f8894cf9e45ff1c231ff4093351))
+
+
+### Documentation
+
+* **consoles:** clarify --vm selection matches existing CLI conventions ([8940709](https://github.com/WayfarerLabs/agentworks/commit/8940709138ad4f27a9ab2ea0309fd1923541f653))
+* **consoles:** de-emphasize --vm in primary examples (auto-detected) ([d97e99a](https://github.com/WayfarerLabs/agentworks/commit/d97e99ac453512455f5c3e66fde0b8d3af262d43))
+* **consoles:** soften restart comment and surface deprecation in vm --help ([b658c46](https://github.com/WayfarerLabs/agentworks/commit/b658c46b1a3b6c4c678c10061002e51ce96a162f))
+* distinguish domain-error vs unexpected-error paths in --debug section ([065801e](https://github.com/WayfarerLabs/agentworks/commit/065801e33b55420080149a5ea67de03754d3d71f))
+* name-positional examples in Getting Started and VM command table ([27fe300](https://github.com/WayfarerLabs/agentworks/commit/27fe3009cf43b9743f5bc84ba5adebf798e3c294))
+
+
+### Code Refactoring
+
+* drop local workspaces; all workspaces are VM-scoped ([e6236e6](https://github.com/WayfarerLabs/agentworks/commit/e6236e6c2969cd56efc9bd3cde35bfc37eceb9fc))
+* split completion command into show/install with shell autodetection ([a6d1af4](https://github.com/WayfarerLabs/agentworks/commit/a6d1af4d8bfac4973765f99040f190fcc24dd9fc))
+
 ## [0.2.1](https://github.com/WayfarerLabs/agentworks/compare/v0.2.0...v0.2.1) (2026-05-27)
 
 

{agentworks_cli-0.2.1 → agentworks_cli-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentworks-cli
-Version: 0.2.1
+Version: 0.3.0
 Summary: CLI for orchestrating workspace lifecycle across multiple compute targets
 Project-URL: Homepage, https://github.com/WayfarerLabs/agentworks
 Project-URL: Repository, https://github.com/WayfarerLabs/agentworks
@@ -134,9 +134,9 @@ settings) can be used to control how tools behave within the context of this wor
 The Agentworks workspace mechanism fully supports any number of workspaces mapping to the same
 underlying repository. To simplify administration, each is a full independent clone.
 
-While VM workspaces are the primary supported workspace type, local workspaces can also be created
-on the operator's workstation. Local workspaces do not support agents because the isolation model
-that underpins agent execution requires Linux user management that is only available on VMs.
+Workspaces always live on a VM. An earlier iteration supported local (on-workstation) workspaces,
+but they did not support agents (which require Linux user management only available on VMs), so they
+were removed to keep the model focused.
 
 ### Agents - the Actor
 
@@ -160,6 +160,10 @@ concurrent workloads running across their VMs, workspaces, and agents. Agentwork
 operator to attach to and detach from them as needed to monitor progress or interact with the
 workload, and then to stop, restart, and delete them to manage their lifecycle.
 
+For day-to-day work across many sessions, see [Named consoles](#named-consoles): curated tmux views
+that group the sessions you're actively focused on, optionally with extra shell panes pre-opened in
+each session's window.
+
 ## Key Principles
 
 ### Opinionated Consistency
@@ -236,12 +240,16 @@ Sessions are built on [tmux](https://github.com/tmux/tmux), which provides persi
 sessions that survive disconnects and support attach/detach. Each session maps 1:1 to a tmux session
 on the VM.
 
-Agentworks provides two console layers for interacting with sessions:
+Agentworks provides several console layers for interacting with sessions:
 
 - **Workspace console** (`workspace console`): a tmuxinator-managed tmux session with one window per
-  session in the workspace, plus an admin shell. This is the recommended way to interact with
-  sessions.
-- **VM console** (`vm console`): a dynamically-built tmux session spanning all workspaces on the VM.
+  session in the workspace, plus an admin shell. Good for staying inside a single workspace.
+- **Named consoles** (`console`): persistent, named tmux sessions that aggregate a curated subset of
+  sessions across any workspaces on a VM, with optional extra shell panes per session window.
+  Recommended when you juggle sessions across workspaces or want a focused view of the few you're
+  actively working on.
+- **VM console** (`vm console`, _deprecated_): a dynamically-built tmux session spanning every
+  session on the VM. Replaced by named consoles; will be removed in a future release.
 
 Agent-mode sessions run on per-agent tmux sockets for proper process isolation and terminal resize
 propagation. See the [tmux Architecture](#tmux-architecture) section for details.
@@ -273,8 +281,8 @@ uv run agentworks config init    # creates ~/.config/agentworks/config.toml
 Edit the config file (at minimum, set your SSH key paths), then:
 
 ```bash
-agentworks vm create          # provision + initialize a VM
-agentworks workspace create   # create a workspace on the VM
+agentworks vm create my-vm                       # provision + initialize a VM
+agentworks workspace create my-workspace         # create a workspace on the VM
 agentworks workspace shell my-workspace
 ```
 
@@ -287,23 +295,38 @@ agentworks workspace shell my-workspace
 
 ## Global Options
 
-| Flag                | Description                     |
-| ------------------- | ------------------------------- |
-| `--non-interactive` | Disable all interactive prompts |
+| Flag                | Description                                                                  |
+| ------------------- | ---------------------------------------------------------------------------- |
+| `--non-interactive` | Disable all interactive prompts                                              |
+| `--debug`           | Print the full Python traceback on unhandled errors (also via `AGW_DEBUG=1`) |
 
 When `--non-interactive` is set (or stdin is not a TTY), commands that would normally prompt for
 missing values (VM selection, workspace selection, name generation) will fail with a clear error
 indicating which flag is required. Auto-selection still works: if there is exactly one VM or
 workspace, it is used without prompting.
 
+Domain errors (SSH timeouts, validation failures, missing resources, etc.) surface as a single clean
+line: `Error: <message>`. Truly unexpected failures (internal bugs, OS-level errors, third-party
+library failures) also get a clean single-line message, plus the full traceback appended to
+`~/.config/agentworks/logs/error.log` for debugging. Pass `--debug` (or set `AGW_DEBUG=1`) to print
+the traceback to stderr instead.
+
+Pressing Ctrl-C during a long-running operation triggers best-effort cleanup. Where the operation
+can roll back (e.g. `vm create` during the provisioning phase, `workspace create`, `agent create`,
+`session create`) it undoes the partial DB / on-VM state and prints `Cancelling X... rolling back.`.
+Where rollback isn't possible (`vm reinit`, `agent reinit`, the init phase of `vm create`) it prints
+a recovery hint: the next command to run (`vm reinit`, `vm delete --force`, ...). Every cancellation
+exits with the conventional SIGINT exit code (130).
+
 ## Commands
 
 ### Top-level
 
-| Command                     | Description                  |
-| --------------------------- | ---------------------------- |
-| `agentworks doctor`         | Check environment and config |
-| `agentworks completion zsh` | Output zsh completion script |
+| Command                         | Description                            |
+| ------------------------------- | -------------------------------------- |
+| `agentworks doctor`             | Check environment and config           |
+| `agentworks completion show`    | Print the completion script to stdout  |
+| `agentworks completion install` | Install the completion script in-place |
 
 ### VM Hosts
 
@@ -321,7 +344,7 @@ Manage virtual machines across Lima (local or remote), Azure, and WSL2.
 
 | Command                                          | Description                                |
 | ------------------------------------------------ | ------------------------------------------ |
-| `agentworks vm create`                           | Create a new VM (provision + initialize)   |
+| `agentworks vm create <name>`                    | Create a new VM (provision + initialize)   |
 | `agentworks vm list`                             | List VMs with status and resources         |
 | `agentworks vm describe <name>`                  | Show VM details, workspaces, and event log |
 | `agentworks vm shell <name>`                     | SSH into a VM's home directory             |
@@ -330,12 +353,13 @@ Manage virtual machines across Lima (local or remote), Azure, and WSL2.
 | `agentworks vm reinit <name>`                    | Re-run initialization on a provisioned VM  |
 | `agentworks vm delete <name>`                    | Delete a VM (with confirmation)            |
 | `agentworks vm logs <name>`                      | Show SSH logs for a VM                     |
-| `agentworks vm console <name>`                   | Attach to the VM console                   |
+| `agentworks vm console <name>`                   | _Deprecated_: use `agentworks console`     |
 | `agentworks vm add-git-credential <name> <cred>` | Add or update a git credential             |
 
-`vm create` accepts `--name`, `--platform`, `--vm-host`, `--admin-username`, `--cpus`, `--memory`,
-`--disk`, and `--azure-vm-size`. These are immutable provisioning parameters stored in the database.
-All initialization behavior (packages, install commands, etc.) is driven by config.
+`vm create <name>` takes the VM name as a required positional. Optional flags: `--platform`,
+`--vm-host`, `--admin-username`, `--cpus`, `--memory`, `--disk`, and `--azure-vm-size`. These are
+immutable provisioning parameters stored in the database. All initialization behavior (packages,
+install commands, etc.) is driven by config.
 
 `vm reinit` re-runs the initialization phase using the current config without reprovisioning the VM.
 Changes to config (new packages, different install commands, etc.) are picked up automatically.
@@ -345,28 +369,29 @@ message shows what will be deleted. Pass `--yes` to skip the prompt.
 
 ### Workspaces
 
-Manage workspaces on VMs or locally.
+Manage workspaces on VMs.
 
-| Command                                | Description                          |
-| -------------------------------------- | ------------------------------------ |
-| `agentworks workspace create`          | Create a workspace (VM or `--local`) |
-| `agentworks workspace describe <name>` | Show workspace details and sessions  |
-| `agentworks workspace shell <name>`    | Open a plain shell into a workspace  |
-| `agentworks workspace console <name>`  | Open the workspace console (tmux)    |
-| `agentworks workspace list`            | List workspaces                      |
-| `agentworks workspace copy <source>`   | Copy a workspace to a new location   |
-| `agentworks workspace rehome <name>`   | Move workspace to a new path         |
-| `agentworks workspace repair <name>`   | Repair workspace infrastructure      |
-| `agentworks workspace delete <name>`   | Delete a workspace                   |
+| Command                                     | Description                         |
+| ------------------------------------------- | ----------------------------------- |
+| `agentworks workspace create <name>`        | Create a workspace on a VM          |
+| `agentworks workspace describe <name>`      | Show workspace details and sessions |
+| `agentworks workspace shell <name>`         | Open a plain shell into a workspace |
+| `agentworks workspace console <name>`       | Open the workspace console (tmux)   |
+| `agentworks workspace list`                 | List workspaces                     |
+| `agentworks workspace copy <source> <name>` | Copy a workspace to a new VM        |
+| `agentworks workspace rehome <name>`        | Move workspace to a new path        |
+| `agentworks workspace repair <name>`        | Repair workspace infrastructure     |
+| `agentworks workspace delete <name>`        | Delete a workspace                  |
 
-`workspace create` accepts `--name`, `--vm`, `--local`, `--template`, and `--open-vscode`.
+`workspace create <name>` takes the workspace name as a required positional. Optional flags: `--vm`,
+`--template`, and `--open-vscode`.
 
 `workspace console` opens a tmuxinator session (`ws-<name>-console`) with an admin-shell window plus
 one window per session in the workspace. Pass `--recreate` to kill and rebuild the console. This is
 the recommended way to interact with sessions from within VS Code or any terminal on the VM.
 
-`workspace copy` copies a workspace to a new location. Accepts `--name`, `--vm`, and `--local` (same
-pattern as `workspace create`). Works across VMs, VM to local, and local to VM.
+`workspace copy <source> <name>` copies a workspace to a new VM workspace. Accepts `--vm`. Source
+and destination can be the same VM (a clone) or different VMs.
 
 `workspace delete` requires `--force` if the workspace has sessions. Running sessions are killed
 during deletion. Pass `--yes` to skip the confirmation prompt.
@@ -377,7 +402,7 @@ Manage agents (isolated Linux users) on VMs. Agents are VM-scoped and access wor
 
 | Command                                                      | Description                    |
 | ------------------------------------------------------------ | ------------------------------ |
-| `agentworks agent create [--name] [--vm]`                    | Create an agent on a VM        |
+| `agentworks agent create <name> [--vm]`                      | Create an agent on a VM        |
 | `agentworks agent list [--vm <vm>]`                          | List agents                    |
 | `agentworks agent describe <name>`                           | Show agent details and grants  |
 | `agentworks agent reinit <name>`                             | Re-run agent setup             |
@@ -389,7 +414,8 @@ Manage agents (isolated Linux users) on VMs. Agents are VM-scoped and access wor
 | `agentworks agent shell <name> [--workspace <ws>]`           | Shell into an agent            |
 | `agentworks agent delete <name>`                             | Delete an agent                |
 
-`agent create` accepts `--name`, `--vm`, `--template`, and `--grant-all-workspaces`.
+`agent create <name>` takes the agent name as a required positional. Optional flags: `--vm`,
+`--template`, and `--grant-all-workspaces`.
 
 `agent delete` requires `--force` if the agent has running sessions. Pass `--yes` to skip the
 confirmation prompt.
@@ -401,7 +427,7 @@ Manage sessions (persistent tmux sessions running in workspaces). Session names
 
 | Command                                      | Description                    |
 | -------------------------------------------- | ------------------------------ |
-| `agentworks session create`                  | Create and start a session     |
+| `agentworks session create <name>`           | Create and start a session     |
 | `agentworks session describe <name>`         | Show session details           |
 | `agentworks session list [--workspace <ws>]` | List sessions with status      |
 | `agentworks session attach <name>`           | Attach to a running session    |
@@ -409,25 +435,92 @@ Manage sessions (persistent tmux sessions running in workspaces). Session names
 | `agentworks session restart <name>`          | Restart a session              |
 | `agentworks session delete <name>`           | Stop and delete a session      |
 | `agentworks session logs <name>`             | Dump session scrollback buffer |
-| `agentworks vm console <vm-name>`            | Attach to the VM console       |
+| `agentworks console attach <name>`           | Attach to a named console      |
+
+`session create <name>` takes the session name as a required positional. Optional flags:
+`--workspace`, `--template`, `--admin`, and `--agent`. Workspace and mode (admin vs agent) are
+prompted interactively if omitted; if agents exist on the VM and neither `--admin` nor `--agent` is
+specified, you are prompted to choose. Pass `--new-workspace` to create a workspace on the fly (with
+optional `--workspace-name`, `--workspace-template`, and `--vm`; `--workspace-name` defaults to the
+session name). Pass `--new-agent` to create a new agent for the session (with optional
+`--agent-name` and `--agent-template`; `--agent-name` defaults to the session name); the new agent
+is provisioned on the workspace's VM. When a session created with `--new-workspace` or `--new-agent`
+is later deleted, you are offered the option to delete the workspace and/or agent as well -- the
+workspace if no other sessions remain on it, the agent if it has no other sessions and no explicit
+grants.
+
+### Named consoles
+
+Named consoles are persistent, curated tmux views over sessions on a VM. Each console is its own
+tmux session (`aw-console-<name>`) containing one window per included session, plus any extra shell
+panes you want preloaded into a session's window.
+
+| Command                                                  | Description                                                       |
+| -------------------------------------------------------- | ----------------------------------------------------------------- |
+| `agentworks console create <name> [sessions...]`         | Create a console with the given sessions                          |
+| `agentworks console list`                                | List consoles                                                     |
+| `agentworks console describe <name>`                     | Show membership and shell layout                                  |
+| `agentworks console attach <name>`                       | Attach (builds tmux state on first attach)                        |
+| `agentworks console delete <name>`                       | Tear down and remove the console                                  |
+| `agentworks console add-session <name> <sessions...>`    | Add session windows                                               |
+| `agentworks console remove-session <name> <sessions...>` | Remove session windows                                            |
+| `agentworks console add-shell <name> <session>`          | Add a shell pane to a session window (accepts `--cwd`, `--admin`) |
+
+`console create` accepts:
+
+- `--vm` -- target VM. **Inferred from the listed sessions when omitted**; if the listed sessions
+  span more than one VM, `console create` errors and asks you to pick one with `--vm`. When no
+  sessions are listed (e.g. with `--all` and no explicit specs), VM selection falls back to the
+  standard prompt (auto-picked if you have a single VM, prompted otherwise).
+- `--all` -- include every session on the VM with 0 shells, appended after the explicit specs
+  (alphabetical).
+- `--all-running` -- like `--all` but restricted to sessions whose live tmux state on the VM is OK
+  (one SSH round-trip; same probe `aw session list` uses). Mutually exclusive with `--all`. Requires
+  the VM to be reachable.
+- `--add-admin-shell` -- include a top-level admin-shell window as window 0, matching the legacy
+  `vm console` behavior.
+
+`console list` accepts `--vm` to filter.
+
+Session specs use `name` or `name+N` shorthand, where `N` is the number of default shell panes to
+pre-open in that session's window (running as the session's agent user, cwd = workspace root):
+
+```sh
+# A console with three sessions; the first two get extra shells.
+# VM is inferred from the sessions.
+agentworks console create backend auth-server+2 auth-tests+1 docs
+
+# Same, but also include a top-level admin-shell window (window 0).
+agentworks console create backend auth-server+2 auth-tests+1 docs --add-admin-shell
+
+# Everything currently running on the VM, after the explicit specs.
+agentworks console create live auth-server+2 --all-running
+
+# All sessions on the VM (running or not). Needs --vm since no sessions are
+# named explicitly to infer from.
+agentworks console create everything --vm aw-private --all
+
+# Add an admin shell rooted in a sub-path of the workspace.
+agentworks console add-shell backend auth-server --cwd src/api --admin
+```
 
-`session create` accepts `--name`, `--workspace`, `--template`, `--admin`, and `--agent`. Workspace,
-mode (admin vs agent), and name are prompted interactively if omitted. If agents exist on the VM and
-neither `--admin` nor `--agent` is specified, you are prompted to choose. Pass `--new-workspace` to
-create a workspace on the fly (with optional `--workspace-name`, `--workspace-template`, and
-`--vm`). When a session created with `--new-workspace` is later deleted, you are offered the option
-to delete the workspace as well (if no other sessions remain).
+Memberships and shell layouts persist in the database. `aw console attach` builds the tmux session
+on first attach (or with `--recreate`); subsequent attaches reuse the running tmux session. Adding
+or removing sessions/shells while a console is attached updates the live tmux state immediately
+(best-effort); when the console isn't running on the VM, only the DB is updated and changes appear
+on next attach.
 
 ### tmux Architecture
 
-Each session runs in its own locked-down tmux session on the VM. There are three ways to interact
+Each session runs in its own locked-down tmux session on the VM. There are several ways to interact
 with sessions, at different scopes:
 
-| Method              | Scope          | tmux session name        | Entry point                 |
-| ------------------- | -------------- | ------------------------ | --------------------------- |
-| `session attach`    | One session    | `<session-name>`         | Operator's machine          |
-| `workspace console` | One workspace  | `ws-<workspace>-console` | On-VM or operator's machine |
-| `vm console`        | All workspaces | `vm-console`             | Operator's machine          |
+| Method                    | Scope                            | tmux session name        | Entry point                 |
+| ------------------------- | -------------------------------- | ------------------------ | --------------------------- |
+| `session attach`          | One session                      | `<session-name>`         | Operator's machine          |
+| `workspace console`       | One workspace                    | `ws-<workspace>-console` | On-VM or operator's machine |
+| `console`                 | Curated subset across workspaces | `aw-console-<name>`      | Operator's machine          |
+| `vm console` (deprecated) | All sessions on the VM           | `vm-console`             | Operator's machine          |
 
 #### Session tmux sessions
 
@@ -443,8 +536,9 @@ tmux pane PTY. The socket path is persisted in the database.
 
 `workspace console` uses tmuxinator to create or attach to a `ws-<name>-console` session. The
 tmuxinator config (`.tmuxinator.yml` in the workspace root) is regenerated whenever sessions change,
-so the console always reflects the current set of sessions. This is the recommended way to interact
-with sessions from within VS Code or any terminal on the VM.
+so the console always reflects the current set of sessions. Best for in-VM work scoped to a single
+workspace (e.g. inside VS Code's integrated terminal). For curated views that span workspaces, use a
+named console (`console attach <name>`).
 
 ```text
 ws-myproject-console (tmuxinator, full tmux)
@@ -453,10 +547,32 @@ ws-myproject-console (tmuxinator, full tmux)
   Window 3: myproject-debug            attached to session
 ```
 
-#### VM console
+#### Named console
+
+`console attach <name>` creates or attaches to the `aw-console-<name>` tmux session. Membership and
+per-session shell layout are stored in the database. Each member session becomes a window running
+the same wrapper used by the workspace and VM consoles, plus a configurable number of extra shell
+panes (default user = session's agent user, default cwd = workspace root; override per pane with
+`--cwd` / `--admin` on `console add-shell`).
+
+```text
+aw-console-backend
+  Window 1: auth-server                attached session + 2 agent shells (workspace root)
+  Window 2: auth-tests                 attached session + 1 agent shell
+  Window 3: docs                       attached session only
+```
+
+The tmux session is built lazily on first `attach` (or rebuilt with `--recreate`). Adding or
+removing sessions/shells while the console is attached updates tmux immediately; when offline, only
+the DB is touched and changes appear on next attach. The console does not auto-boot the VM for live
+sync; VM start happens only on explicit `attach`.
 
-`vm console` creates or attaches to the `vm-console` session, which spans all workspaces on the VM.
-This is built dynamically (not via tmuxinator) and is managed from the operator's machine.
+#### VM console (deprecated)
+
+`vm console` creates or attaches to the `vm-console` session, which spans all sessions on the VM.
+Built dynamically (not via tmuxinator). Superseded by named consoles, which let you curate which
+sessions are in scope at any moment instead of seeing every session on the VM. Will be removed in a
+future release.
 
 #### Shells
 
@@ -525,7 +641,7 @@ full reference.
 Key sections:
 
 - `[operator]` -- SSH keys (required), additional authorized keys, SSH config management
-- `[paths]` -- local workspace, VM workspace, and VS Code workspace file directories
+- `[paths]` -- VM workspace and VS Code workspace file directories
 - `[defaults]` -- default platform, VM host
 - `[vm_templates.*]` -- VM resources, apt packages, system install commands, mise
 - `[admin.config]` -- admin user shell, dotfiles, git credentials, user install commands, mise
@@ -609,16 +725,18 @@ log.
 ## Shell Completion
 
 ```bash
-mkdir -p ~/.zfunc
-agentworks completion zsh > ~/.zfunc/_agentworks
+agentworks completion install
 ```
 
-Add to `.zshrc`:
+The shell is autodetected from `$SHELL`; pass `--shell {bash|zsh|powershell}` to override (or when
+autodetection isn't unambiguous, e.g. on Windows). `completion install` writes the script to the
+standard location for that shell. For PowerShell it also appends a dot-source line (`. "..."`) to
+`$PROFILE`. For bash and zsh, if your rc file is missing the loader (`bash-completion` for bash,
+`fpath=(~/.zfunc $fpath)` for plain zsh without a plugin manager), the installer prints a one-line
+note telling you what to add.
 
-```bash
-fpath=(~/.zfunc $fpath)
-autoload -Uz compinit && compinit
-```
+To print the script without installing, use `agentworks completion show` (handy for piping into your
+own config-management flow).
 
 Completions include dynamic VM, workspace, VM host, session, and template name lookups.