agentworks-cli 0.5.0__tar.gz → 0.7.0__tar.gz

{agentworks_cli-0.5.0 → agentworks_cli-0.7.0}/CHANGELOG.md

@@ -1,5 +1,119 @@
 # Changelog
 
+## [0.7.0](https://github.com/WayfarerLabs/agentworks/compare/v0.6.0...v0.7.0) (2026-06-24)
+
+
+### Features
+
+* **agents:** agent shell uses direct agent SSH ([edccd6f](https://github.com/WayfarerLabs/agentworks/commit/edccd6f4a66700afa372210b30eceb676cac16af))
+* **agents:** authorized_keys + operator ssh config for agent users ([7991dc3](https://github.com/WayfarerLabs/agentworks/commit/7991dc37186c59542f8e18367831b7b9878ed13d))
+* **agents:** typed error on pre-rollout agent SSH + reviewer cleanups ([edc5552](https://github.com/WayfarerLabs/agentworks/commit/edc555233acf30d10b8a98075db4f5c1c065cbc8))
+* **cli:** AW_-prefixed env vars with legacy fallback ([ceb9e05](https://github.com/WayfarerLabs/agentworks/commit/ceb9e057f48eca5b230618d768aee0e777cb1636))
+* **cli:** AW_-prefixed env vars with legacy fallback ([62617b9](https://github.com/WayfarerLabs/agentworks/commit/62617b97e5951fa91e89a718cad5babc8ea872d4))
+* **doctor:** Secrets and Env health groups (Phase 5 - FRD R6) ([8a6dbf7](https://github.com/WayfarerLabs/agentworks/commit/8a6dbf750e8c628997a723168ab706d6eb668f45))
+* **doctor:** summary row for configured secret backends ([0dd4fe9](https://github.com/WayfarerLabs/agentworks/commit/0dd4fe9fdb4faa5fde7ebfcd379ee3dda71f3ae8))
+* **env:** `agw env show` command (Phase 5) ([06f25b6](https://github.com/WayfarerLabs/agentworks/commit/06f25b6505c96d30cdc7a2ec2cf7ef7ee4a97860))
+* **env:** env package + secrets config loaders (Phase 2) ([9c61284](https://github.com/WayfarerLabs/agentworks/commit/9c61284a5efc89c2b751a1de9e4ea182ecc83a5b))
+* **env:** env vars + pluggable secret backends (env-and-secrets SDD) ([fa67409](https://github.com/WayfarerLabs/agentworks/commit/fa67409b2ec7fa48807bffcfa9987dda057141a5))
+* **env:** wire env+secrets prelude into session create/restart (Phase 3) ([91f32db](https://github.com/WayfarerLabs/agentworks/commit/91f32dbcf0e758f645e026da7cbb345e014b8614))
+* **provisioning:** defensive 'ensure agentworks files sourced' step ([29128aa](https://github.com/WayfarerLabs/agentworks/commit/29128aa862bf88d1ac73ed63cccfd3737779eeb8))
+* **secrets:** add agw secret list for backend mapping discovery ([048f189](https://github.com/WayfarerLabs/agentworks/commit/048f189e6474a7c9eaf2c4b51f0f6ba0f1779dce))
+* **secrets:** add SecretMappingError for hard-miss backends ([29823e7](https://github.com/WayfarerLabs/agentworks/commit/29823e75234a05c548bcdd4a1cd14f9c3bf6c851))
+* **secrets:** eager-prompting orchestration module (Phase 6.1) ([4d28390](https://github.com/WayfarerLabs/agentworks/commit/4d28390a94163083e483d073162554969cdb67c9))
+* **secrets:** eager-resolve + env threading in vm/agent shell+exec (Phase 6.5) ([423512f](https://github.com/WayfarerLabs/agentworks/commit/423512f3c49634c723bb19473303426ded49aeb6))
+* **secrets:** eager-resolve in agent create/reinit (Phase 6.4) ([691d7bd](https://github.com/WayfarerLabs/agentworks/commit/691d7bd24092ad44a48464e47f4e51865b500fce))
+* **secrets:** eager-resolve in console build + restore_session (Phase 6.2b) ([e0690ca](https://github.com/WayfarerLabs/agentworks/commit/e0690ca6e65a904b8d953392a6d357fdb4b92580))
+* **secrets:** eager-resolve in session + console paths (Phase 6.2) ([ae6e68d](https://github.com/WayfarerLabs/agentworks/commit/ae6e68d2e72f31293edd19317c4b1158a14b62f4))
+* **secrets:** eager-resolve in vm create/reinit (Phase 6.3) ([41a9d43](https://github.com/WayfarerLabs/agentworks/commit/41a9d435e90b8c57048b485f00dd521ae98344a3))
+* **secrets:** Phase 1 - secrets package foundations ([1a79952](https://github.com/WayfarerLabs/agentworks/commit/1a799521c75fc40b990f825381eec0cbc595ecf6))
+* **secrets:** thread env through agent setup runners (Phase 6.4b) ([e92bb4b](https://github.com/WayfarerLabs/agentworks/commit/e92bb4bb76ac9161e3d59224377d68f4ad337fac))
+* **secrets:** thread env through vm provisioning runners (Phase 6.3b) ([0e2ef33](https://github.com/WayfarerLabs/agentworks/commit/0e2ef334c4ca612c313a360ed830583b77c26fca))
+* **sessions:** create agent-mode tmux sessions via direct agent SSH ([389141f](https://github.com/WayfarerLabs/agentworks/commit/389141f5f5a14549b7db8541a1f33144a0fe97ca))
+* **ssh:** add agent_exec_target ExecTarget builder ([8452262](https://github.com/WayfarerLabs/agentworks/commit/8452262e0c985301a81dc12574cb165d2d3ba135))
+* **vm:** expose provisioner shell via 'vm shell --provisioner' ([f2ee07f](https://github.com/WayfarerLabs/agentworks/commit/f2ee07f9b91fb2a2e3d18726f0ead6963552261e))
+* **vms:** apply VM hardening at vm create + vm reinit ([81b6dcf](https://github.com/WayfarerLabs/agentworks/commit/81b6dcf235e382b6b6ce4ce2b91994d8c1ee28a5))
+* **vms:** deploy VM-side env-and-secrets fragments (Phase 4) ([61238b0](https://github.com/WayfarerLabs/agentworks/commit/61238b01e2d6c32be205064e1c90d815d8335a1b))
+* **vms:** detect tailscaled DNS latch and abort phase B with heal hint ([3b289c8](https://github.com/WayfarerLabs/agentworks/commit/3b289c8287a6782dafe083c2b77dc0457fb5ea8f))
+
+
+### Bug Fixes
+
+* **agents:** always write the agent's ~/.agentworks-rc.sh ([4c8f602](https://github.com/WayfarerLabs/agentworks/commit/4c8f602c8b3d81f7bab0bb89489142928a54c01a))
+* **agents:** always write the agent's ~/.agentworks-rc.sh ([0f10e9c](https://github.com/WayfarerLabs/agentworks/commit/0f10e9c6e2c938db5d2d6f838060f51e586e1a9b))
+* **agents:** rename stale ExecTarget annotation to Transport ([cd78049](https://github.com/WayfarerLabs/agentworks/commit/cd78049ceabd808909f2c5c4fc73c77b84c31847))
+* **agents:** rename stale ExecTarget annotation to Transport ([86b0e89](https://github.com/WayfarerLabs/agentworks/commit/86b0e89cbf9a7611b85e42c4d0098aa35f534be9))
+* **agents:** stop overwriting ~/.zshrc with a hardcoded PS1 ([c79a916](https://github.com/WayfarerLabs/agentworks/commit/c79a91623ad9ff2efc42d9b3ddf26c78022d3e71))
+* **agents:** wrap claude/dotfiles commands in login shell for agent PATH ([0fa1cd5](https://github.com/WayfarerLabs/agentworks/commit/0fa1cd55fc756a27aee7cb77edbceeaaf617a50f))
+* **agents:** wrap mise install/prune in login shell too ([aace97d](https://github.com/WayfarerLabs/agentworks/commit/aace97d2775d12afb8dd1690e5f191be7d059f10))
+* **doctor:** simplify secret preview, honor prompt opt-out ([ba1f583](https://github.com/WayfarerLabs/agentworks/commit/ba1f5837e76cd85113ba9acb61ab4ac2777dc5a6))
+* **env:** doctor.py legacy-aware credential check + both-set note + removal-timeline doc ([101c645](https://github.com/WayfarerLabs/agentworks/commit/101c6450039e56f685bc5023163d03329dce5664))
+* **initializer:** identity-profile zsh mirror on fresh VMs ([c0cbd27](https://github.com/WayfarerLabs/agentworks/commit/c0cbd278588538dfedec0deb1561a6325cca4b6e))
+* **logging:** route operation tracebacks to the per-op log ([bb7ea7e](https://github.com/WayfarerLabs/agentworks/commit/bb7ea7e3f2472f6a268bc77cb0b7f1aaf5c0ce87))
+* **logging:** route operation tracebacks to the per-op log ([ec1ab02](https://github.com/WayfarerLabs/agentworks/commit/ec1ab02467e4e459210bf1dafe4f1b464115c5ba))
+* **secrets:** PromptSource must respect backend_mappings.prompt=false ([bedb2ee](https://github.com/WayfarerLabs/agentworks/commit/bedb2ee6eb1655c9b0fd4ec651177bcfbbcabae0))
+* **ssh:** coalesce SetEnv pairs into one -o argument ([94f54f8](https://github.com/WayfarerLabs/agentworks/commit/94f54f87364fc9942979ea86f313f05ed77a615a))
+* **ssh:** dispatch interactive() across non-SSH transports ([3aa48a8](https://github.com/WayfarerLabs/agentworks/commit/3aa48a8dccd33e1596b5fbd60a83858b8fbd02a6))
+* **ssh:** wrap remote-lima interactive in login shell for PATH ([3e4b83c](https://github.com/WayfarerLabs/agentworks/commit/3e4b83ce2450a07eef826ef38580d32dcbc44251))
+* **transports:** default mid-create identity_file to operator key ([3b84132](https://github.com/WayfarerLabs/agentworks/commit/3b8413291240904c2463aad87e9645982c7921d3))
+* **vm:** auto-attach/detach Azure public IP for 'vm shell --provisioner' ([a1621f9](https://github.com/WayfarerLabs/agentworks/commit/a1621f92fe7370502bdb71da96e802c1a0d15fe0))
+* **vm:** point Proxmox provisioner-shell users at web UI serial console ([31d9045](https://github.com/WayfarerLabs/agentworks/commit/31d90458848a6341ee4690b309d7b148e2ed36bc))
+* **vms:** announce DNS check before the lookup pauses ([f358898](https://github.com/WayfarerLabs/agentworks/commit/f3588986c3b6cefca8e6dc0701b9e010b7e9ff85))
+* **vms:** order tailscaled after systemd-resolved to fix DNS race ([905d00a](https://github.com/WayfarerLabs/agentworks/commit/905d00a73087a0aa0c6fee385801ab40a2e2666b))
+* **vms:** restore tailscale_host guard on exec_vm + round-2 review nits ([59c7d9a](https://github.com/WayfarerLabs/agentworks/commit/59c7d9a9cd47a76781ec6c140fbd72d53ea16948))
+* **vms:** tailscaled DNS race fix and vm-shell provisioner flag ([dc147f8](https://github.com/WayfarerLabs/agentworks/commit/dc147f8a8d383eb0487051539cd492b896ea6805))
+* **vms:** warn that heal kills SSH session over Tailscale ([8fb56b4](https://github.com/WayfarerLabs/agentworks/commit/8fb56b438ffee2140c74706d4cb5b33e7a48a24c))
+* **vm:** warn instead of block on failed-init for 'vm shell' ([c84adff](https://github.com/WayfarerLabs/agentworks/commit/c84adfffd0b53e6bd012f5c0fc41401376af4434))
+
+
+### Documentation
+
+* address Copilot feedback on PR [#107](https://github.com/WayfarerLabs/agentworks/issues/107) (proper noun, EDITOR/VISUAL, doctor scope, tmux detach hint) ([b4ed925](https://github.com/WayfarerLabs/agentworks/commit/b4ed925beb62cccbcb732dc4244d5358cdd4a3f3))
+* **env:** document env + secrets in sample config and READMEs (Phase 5) ([adc32d7](https://github.com/WayfarerLabs/agentworks/commit/adc32d71b43499bebcb2328c6b73a3f9317607a0))
+* move walkthrough to cli/, collapse top-level Tmux subsections ([34dbcc2](https://github.com/WayfarerLabs/agentworks/commit/34dbcc2edd52520941805256a695d8eaa9311a4d))
+* rename remaining env_var references to env-var ([7ec1af8](https://github.com/WayfarerLabs/agentworks/commit/7ec1af86bb3ad528da2fa13772910cbbf4976542))
+* rewrite tmux detach hint to not overpromise on prefix override ([343f729](https://github.com/WayfarerLabs/agentworks/commit/343f72959f4dd7c92c97d9e89486bf01900091ec))
+* **sample-config:** #toml comment convention for uncomment-in-place ([04d6803](https://github.com/WayfarerLabs/agentworks/commit/04d6803478f7988929643bf297215809da943f1d))
+* **sample-config:** inline env tables with resources, lift secrets up ([06c1c61](https://github.com/WayfarerLabs/agentworks/commit/06c1c61a50993904880141a14c5e330744db327e))
+* **sdd:** address phase-7 review (tradeoffs, sync-ssh-config, SSH-alias placement) ([8e1c9bd](https://github.com/WayfarerLabs/agentworks/commit/8e1c9bd9d7da3e99fdd891a3b8e85d3ab09b29d8))
+* **sdd:** direct-user-ssh-access SDD ([ef1281f](https://github.com/WayfarerLabs/agentworks/commit/ef1281fb3ed1df7bf37f0eeb7252d3a9515c76d4))
+* **sdd:** drop stale nerftools references from env-and-secrets SDD ([c2b9fc4](https://github.com/WayfarerLabs/agentworks/commit/c2b9fc469bfc487c9ef90c0de961c3841590fd56))
+* **sdd:** lock env-and-secrets SDD ([672b7fa](https://github.com/WayfarerLabs/agentworks/commit/672b7fa953f4815138c50da0f66654caaee5d17c))
+* **sdd:** phase 7 deliverables (two ADR drafts + cli/README SSH alias surface) ([c984705](https://github.com/WayfarerLabs/agentworks/commit/c984705546e8a029d8cca916f0231562c0c1c21b))
+* **secrets:** clarify when PromptSource opt-out adds value ([6bc31bf](https://github.com/WayfarerLabs/agentworks/commit/6bc31bf8a14c01026aa1904f5d8dd7111fc2b92c))
+* **secrets:** tighten _agent_secret_targets docstring (Phase 6.4 polish) ([5d6b9e2](https://github.com/WayfarerLabs/agentworks/commit/5d6b9e27e3f35a4216cbebf350a2ee866d50b4ae))
+* tighten READMEs to project-vs-CLI split ([2021699](https://github.com/WayfarerLabs/agentworks/commit/2021699f4f09ec7fab9cdd51eb829e960df0c851))
+* tighten tmux detach hint to two lines ([4b549ce](https://github.com/WayfarerLabs/agentworks/commit/4b549ce2f810e7c1f13ef8ea58616b17e4e22aef))
+
+## [0.6.0](https://github.com/WayfarerLabs/agentworks/compare/v0.5.0...v0.6.0) (2026-06-06)
+
+
+### Features
+
+* **console:** aw-session-vertical layout + focus session pane on build ([6932505](https://github.com/WayfarerLabs/agentworks/commit/6932505f78d821d1ec2ddd45cc37d74f1cedccb5))
+* **console:** aw-session-vertical layout + focus session pane on build ([aa8270c](https://github.com/WayfarerLabs/agentworks/commit/aa8270cdf31df6512e95c450606056f48a91202d))
+* **vms:** wrap every VM-touching command in keep_vm_active ([8fa8e46](https://github.com/WayfarerLabs/agentworks/commit/8fa8e4600abc125d6f3e1fefc36202336de9c306))
+* **wsl2:** bind keepalive subprocess to Win32 Job Object for orphan-proof cleanup ([08a4833](https://github.com/WayfarerLabs/agentworks/commit/08a4833481ce2146bc784cdfd83baece39b62542))
+* **wsl2:** surface idle-shutdown prevention enter/exit on the keepalive ([f41e926](https://github.com/WayfarerLabs/agentworks/commit/f41e9263976b0267f2cbe1b400177a6dbfe8d937))
+
+
+### Bug Fixes
+
+* address Copilot review on PR [#95](https://github.com/WayfarerLabs/agentworks/issues/95) ([e45322d](https://github.com/WayfarerLabs/agentworks/commit/e45322db28b4ae9b0043699efcbbf84e4782dcc7))
+* **ci:** make WSL2 keepalive code portable to the Linux CI runner ([9de3776](https://github.com/WayfarerLabs/agentworks/commit/9de377623c3207cc13330543394b3874dfeadf23))
+* **ci:** satisfy lint-files and ruff on the WSL2 branch ([482646d](https://github.com/WayfarerLabs/agentworks/commit/482646dd42b7cd0d002ca2c4d836afe1bf2e90d4))
+* **console:** focus session pane on restore-session no-op path too ([78dad70](https://github.com/WayfarerLabs/agentworks/commit/78dad70c7ea3905eb1ffe338011b9423c078a65e))
+* **console:** hand-computed tmux layout string for exact aw-session-vertical geometry ([014613b](https://github.com/WayfarerLabs/agentworks/commit/014613ba058f4c30a8d48257eb7f00f7176209fc))
+* **console:** pane-index sort + silent single-pane no-op + doc fixes ([b14ce2c](https://github.com/WayfarerLabs/agentworks/commit/b14ce2cd781733f72accf04c8e89d1e5eaf721aa))
+* **wsl2:** address agentworks-reviewer feedback on PR [#95](https://github.com/WayfarerLabs/agentworks/issues/95) ([65c66cc](https://github.com/WayfarerLabs/agentworks/commit/65c66cc1b560ed660b56fa59b21fcf4c80003189))
+* **wsl2:** close keepalive subprocess stderr PIPE on both exit paths ([4271772](https://github.com/WayfarerLabs/agentworks/commit/42717727e0940a043eb457383acfadf7a7c3613b))
+* **wsl2:** rehabilitate broken provisioning and add platform-wide keepalive ([177edff](https://github.com/WayfarerLabs/agentworks/commit/177edffc56fa38ccb3c62b6f2e1379707dba966c))
+* **wsl2:** tolerate already-dead keepalive subprocess + drop redundant local import ([67cc239](https://github.com/WayfarerLabs/agentworks/commit/67cc239ef3fbd2888ea498f6610d357f289837a3))
+
+
+### Documentation
+
+* **console:** clarify multi_console_layout module docstring re Config dep ([6031039](https://github.com/WayfarerLabs/agentworks/commit/6031039b95f08bb55bddab211a4a72cc33c8acb5))
+
 ## [0.5.0](https://github.com/WayfarerLabs/agentworks/compare/v0.4.0...v0.5.0) (2026-06-05)
 
 

{agentworks_cli-0.5.0 → agentworks_cli-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentworks-cli
-Version: 0.5.0
+Version: 0.7.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
@@ -11,7 +11,6 @@ Requires-Python: >=3.12
 Requires-Dist: azure-identity>=1.25.1
 Requires-Dist: azure-mgmt-compute>=37.0.1
 Requires-Dist: azure-mgmt-network>=29.0.0
-Requires-Dist: nerftools>=1.1.0
 Requires-Dist: typer>=0.24.1
 Description-Content-Type: text/markdown
 
@@ -36,11 +35,39 @@ The everyday command is `agw`. The longer form `agentworks` is also installed if
 type it out; examples throughout this document use `agw`.
 
 ```bash
+# Initial setup
 agw config init                          # creates ~/.config/agentworks/config.toml
-# edit the config; at minimum set your SSH key paths
-agw vm create my-vm                      # provision + initialize a VM
-agw workspace create my-workspace        # create a workspace on the VM
-agw workspace shell my-workspace
+agw config edit                          # opens the config in your $EDITOR (or $VISUAL) to fill in required fields
+agw doctor                               # sanity-checks installed tools, Tailscale, config validity, and the local DB
+
+# Create a VM, workspace, agent, and session to see how the pieces fit together
+agw vm create my-vm
+agw workspace create my-workspace --vm my-vm
+agw agent create my-agent --vm my-vm
+agw session create my-session --workspace my-workspace --agent my-agent
+
+# Attach to the session's tmux session to drive it
+agw session attach my-session
+# Use tmux's 'detach' command (default Ctrl-b unless overridden by config) to disconnect while
+# leaving everything running on the VM.
+agw session attach my-session    # You'll pick up right where you left off
+agw session stop my-session      # Sessions can be stopped (or can exit on their own)
+agw session list
+agw session restart my-session
+agw session attach my-session
+agw session delete my-session    # When you're done with it. Agent and workspace are preserved.
+
+# Alternatively, you can create ephemeral workspaces and agents along with your sessions
+agw session create my-ephemeral-session --vm my-vm --new-workspace --new-agent
+agw session attach my-ephemeral-session
+agw session delete my-ephemeral-session    # This will prompt you to delete the associated workspace and agent, too
+
+# Finally, create two sessions and a named console
+agw session create s1 --vm my-vm --new-workspace --new-agent
+agw session create s2 --vm my-vm --new-workspace --new-agent
+agw console create my-console s1 s2+1      # The + syntax gives you extra shells as that agent
+agw console attach my-console
+agw console delete my-console              # Extra shells are lost but sessions are preserved
 ```
 
 ## Prerequisites
@@ -48,7 +75,8 @@ agw workspace shell my-workspace
 - Python 3.12+ (uv will install one for you if needed)
 - [uv](https://docs.astral.sh/uv/) or [pipx](https://pipx.pypa.io/) for installation
 - [Tailscale](https://tailscale.com/) installed and connected (for VM workspaces)
-- One of: [Lima](https://lima-vm.io/), Azure CLI (`az`), or WSL2 (for VM provisioning)
+- One of: [Lima](https://lima-vm.io/), Azure CLI (`az`), [Proxmox](https://www.proxmox.com/), or
+  WSL2 (for VM provisioning)
 
 ## Global Options
 
@@ -104,6 +132,14 @@ bypass the confirmation prompt.
 
 Manage virtual machines across Lima (local or remote), Azure, and WSL2.
 
+> **Note on WSL2:** WSL2 distros share the Windows workstation's lifecycle. They idle-shut after
+> ~60s of no `wsl.exe` activity (`vmIdleTimeout` in `.wslconfig`) and do not survive workstation
+> shutdown or sleep. agentworks holds a `wsl.exe` keepalive for the duration of each VM-touching
+> command, so individual `agw` operations work cleanly, but agents and sessions on WSL2 are not
+> suitable for unattended background workflows. Use a different provisioner that provides true
+> long-lived VMs (e.g. Lima, Azure, Proxmox, etc.) if you need a VM that survives independent of
+> your workstation.
+
 | Command                                   | Description                                |
 | ----------------------------------------- | ------------------------------------------ |
 | `agw vm create <name>`                    | Create a new VM (provision + initialize)   |
@@ -129,6 +165,18 @@ Changes to config (new packages, different install commands, etc.) are picked up
 `vm delete` requires `--force` if the VM has workspaces, agents, or sessions. The confirmation
 message shows what will be deleted. Pass `--yes` to skip the prompt.
 
+`agw vm shell` is the agentworks-wrapped entry point; for raw SSH (VS Code Remote-SSH, `scp`, etc.),
+use the `awvm--<vm>` alias documented under [Direct SSH aliases](#direct-ssh-aliases).
+
+`agw vm shell --provisioner` opens the same shell over the platform-native transport
+(`limactl shell` for Lima, `wsl.exe` for WSL2, SSH via a temporarily-attached public IP for Azure)
+instead of Tailscale. Useful when Tailscale itself is the thing you need to reach the VM to fix (the
+issue #117 latched DNS state is the canonical case: its heal involves restarting tailscaled, which
+would terminate a Tailscale-SSH session mid-sequence). On Azure, a public IP is attached for the
+duration of the session and detached on exit. Proxmox isn't supported by this flag because the QEMU
+guest agent's exec interface is one-shot and non-interactive; use the Proxmox web UI's serial
+console (`VM > Console` in the Proxmox VE web UI) as the equivalent escape hatch.
+
 ### Workspaces
 
 Manage workspaces on VMs.
@@ -162,25 +210,55 @@ during deletion. Pass `--yes` to skip the confirmation prompt.
 
 Manage agents (isolated Linux users) on VMs. Agents are VM-scoped and access workspaces via grants.
 
-| Command                                      | Description                    |
-| -------------------------------------------- | ------------------------------ |
-| `agw agent create <name> [--vm]`             | Create an agent on a VM        |
-| `agw agent list [--vm <vm>]`                 | List agents                    |
-| `agw agent describe <name>`                  | Show agent details and grants  |
-| `agw agent reinit <name>`                    | Re-run agent setup             |
-| `agw agent grant-workspaces <name> <ws>...`  | Grant workspace access         |
-| `agw agent grant-workspaces <name> --all`    | Grant access to all workspaces |
-| `agw agent revoke-workspaces <name> <ws>...` | Revoke workspace access        |
-| `agw agent revoke-workspaces <name> --all`   | Revoke all explicit grants     |
-| `agw agent shell <name> [--workspace <ws>]`  | Shell into an agent            |
-| `agw agent delete <name>`                    | Delete an agent                |
+| Command                                      | Description                              |
+| -------------------------------------------- | ---------------------------------------- |
+| `agw agent create <name> [--vm]`             | Create an agent on a VM                  |
+| `agw agent list [--vm <vm>]`                 | List agents                              |
+| `agw agent describe <name>`                  | Show agent details and grants            |
+| `agw agent reinit <name>`                    | Re-run agent setup                       |
+| `agw agent grant-workspaces <name> <ws>...`  | Grant workspace access                   |
+| `agw agent grant-workspaces <name> --all`    | Grant access to all workspaces           |
+| `agw agent revoke-workspaces <name> <ws>...` | Revoke workspace access                  |
+| `agw agent revoke-workspaces <name> --all`   | Revoke all explicit grants               |
+| `agw agent shell <name> [--workspace <ws>]`  | Open an interactive shell as the agent   |
+| `agw agent exec <name> -- <cmd...>`          | Run a one-shot command non-interactively |
+| `agw agent delete <name>`                    | Delete an agent                          |
 
 `agent create <name>` takes the agent name as a required positional. Optional flags: `--vm`,
 `--template`, and `--grant-all-workspaces`.
 
+`agent shell` and `agent exec` both SSH directly as the agent's Linux user. `agent shell` opens an
+interactive login shell (sources the agent's profile; pass `--workspace <ws>` to `cd` into a granted
+workspace first). `agent exec` runs a single command non-interactively but still wraps it in the
+agent's login shell so the agent's `PATH` (mise shims, `~/.local/bin`, etc.) is in scope. Useful for
+scripted invocations like `agw agent exec myagent -- claude -p "..."`.
+
 `agent delete` requires `--force` if the agent has running sessions. Pass `--yes` to skip the
 confirmation prompt.
 
+`agw agent shell` / `agw agent exec` are agentworks-wrapped entry points; for raw SSH access to an
+agent (e.g. from VS Code Remote-SSH or `scp`), use the `awagent--<agent>` alias documented under
+[Direct SSH aliases](#direct-ssh-aliases).
+
+### Direct SSH aliases
+
+Agentworks maintains operator-side SSH config entries for both VMs and agents under
+`~/.ssh/config.d/agentworks.conf` (or inline in `~/.ssh/config` if `ssh_config_dir = false`):
+
+| Alias shape        | Lands you as           | Use cases                                         |
+| ------------------ | ---------------------- | ------------------------------------------------- |
+| `awvm--<vm>`       | The VM's admin user    | `ssh awvm--myvm`, `scp file awvm--myvm:~/`        |
+| `awagent--<agent>` | The agent's Linux user | `ssh awagent--claude`, VS Code Remote-SSH targets |
+
+The agent alias is keyed on the agent's operator-facing name (the same name you use in
+`agw agent ...` commands), not on the on-VM Linux user (which is an implementation detail). The
+prefixes are configurable via `operator.ssh_host_prefix` (default `awvm--`) and
+`operator.ssh_agent_host_prefix` (default `awagent--`).
+
+Entries are rebuilt declaratively from the database on every agent / VM lifecycle operation, so a
+fresh `agw agent create` or `agw vm delete` keeps the file in sync without manual intervention. Run
+`agw config sync-ssh-config` to force a rebuild.
+
 ### Sessions
 
 Manage sessions (persistent tmux sessions running in workspaces). Session names are globally unique
@@ -296,8 +374,8 @@ 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 |
 | `console`                 | Curated subset across workspaces | `aw-console-<name>`      | Operator's machine          |
+| `workspace console`       | One workspace                    | `ws-<workspace>-console` | On-VM or operator's machine |
 | `vm console` (deprecated) | All sessions on the VM           | `vm-console`             | Operator's machine          |
 
 #### Session tmux sessions
@@ -310,21 +388,6 @@ creation, session management, and the command prompt are selectively unbound.
 Agent-mode sessions run on a per-agent tmux socket so the agent's shell connects directly to the
 tmux pane PTY. The socket path is persisted in the database.
 
-#### Workspace console
-
-`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. 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)
-  Window 1: admin-shell                login shell for the admin user
-  Window 2: myproject-claude           attached to session
-  Window 3: myproject-debug            attached to session
-```
-
 #### Named console
 
 `console attach <name>` creates or attaches to the `aw-console-<name>` tmux session. Membership and
@@ -347,6 +410,21 @@ the DB is touched and changes appear on next attach. The mutation commands (`add
 attach/repair commands (`attach`, `restore-session`) do start a stopped VM, since their job is to
 bring live state up.
 
+#### Workspace console
+
+`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. 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)
+  Window 1: admin-shell                login shell for the admin user
+  Window 2: myproject-claude           attached to session
+  Window 3: myproject-debug            attached to session
+```
+
 #### VM console (deprecated)
 
 `vm console` creates or attaches to the `vm-console` session, which spans all sessions on the VM.
@@ -386,9 +464,9 @@ description = "Claude Code interactive session"
 ```
 
 Template commands support `{{session_name}}` and `{{workspace_name}}` variable substitution
-(double-brace syntax, consistent with nerftools manifests). The optional `restart_command` is used
-by `session restart` -- useful for tools like Claude Code where `--resume` picks up the previous
-conversation. If omitted, the regular `command` is used.
+(double-brace syntax). The optional `restart_command` is used by `session restart` -- useful for
+tools like Claude Code where `--resume` picks up the previous conversation. If omitted, the regular
+`command` is used.
 
 ### Catalog
 
@@ -409,7 +487,7 @@ Browse and inspect the built-in catalog of installable tools.
 | `agw config init`                   | Create a sample config file                  |
 | `agw config edit`                   | Open config in `$EDITOR`                     |
 | `agw config sample`                 | Print the sample config to stdout            |
-| `agw config sync-ssh-config`        | Rebuild SSH config entries for all VMs       |
+| `agw config sync-ssh-config`        | Rebuild SSH config entries for VMs + agents  |
 | `agw config sync-vscode-workspaces` | Regenerate .code-workspace files for all VMs |
 
 ## Configuration
@@ -429,8 +507,11 @@ Key sections:
 - `[session.config]` -- session defaults (history limit)
 - `[session_templates.*]` -- session templates with variable substitution
 - `[workspace_templates.*]` -- workspace templates with inheritance
-- `[named_console]` -- named-console layout (tmux preset name)
+- `[named_console]` -- named-console layout (tmux preset names + `aw-session-vertical`)
 - `[git_credentials.*]` -- git credential providers (GitHub, Azure DevOps)
+- `[<scope>.env]` -- env vars at vm / workspace / admin / agent / session scope
+- `[secrets.*]` -- secret declarations referenced by `{ secret = "name" }` env entries
+- `[secret_backends.*]` / `[secret_config]` -- active secret backend chain
 - `[apt_sources.*]` -- user-defined third-party apt repositories
 - `[apt_packages.*]` -- user-defined named apt package sets
 - `[system_install_commands.*]` -- user-defined system-level install commands
@@ -438,41 +519,103 @@ Key sections:
 - `[azure]` -- Azure-specific settings
 - `[proxmox]` -- Proxmox VE API settings
 
-### Mise (Polyglot Tool Manager)
-
-Agentworks installs [mise](https://mise.jdx.dev/) by default on all VMs for managing CLI tools
-(terraform, adr-tools, node, etc.) with optional lockfile-based integrity verification. See
-[Using mise](../docs/guides/mise.md) for the full guide.
+### Environment Variables and Secrets
 
-### Nerf Tools (Claude Code Plugin)
+Env tables can be declared at five scopes; for any given session the merged value is computed in
+this precedence order (highest scope wins; identity vars win over everything):
 
-Agentworks can build and deploy a Claude Code plugin containing "nerf tools" -- scoped,
-safety-constrained wrappers for CLI operations like git, az, and other tools. Nerf tools enforce
-guardrails (validated parameters, restricted flags, pre-flight checks) so AI agents operate safely.
+```text
+session > (agent | admin) > workspace > vm           (AGENTWORKS_* identity overrides all)
+```
 
-Enable in your VM template:
+Admin and agent scopes are mutually exclusive: a shell opened as the admin user (e.g.
+`agw vm shell`) sees admin scope; an agent-mode session sees agent scope. Each scope is a TOML table
+mapping env-var name to either a plaintext string or `{ secret = "<name>" }`:
 
 ```toml
-[vm_templates.default]
-nerf_build_claude_plugin = true
+[vm_templates.default.env]
+HTTP_PROXY = "http://proxy:3128"
+NPM_TOKEN = { secret = "npm-token" }
+
+[admin.env]
+EDITOR = "nvim"
 ```
 
-This builds the plugin to `nerf_home_dir/claude-plugin/` during VM init. To auto-install the plugin
-for users, add to admin or agent config:
+Every `{ secret = "<name>" }` reference must point to a `[secrets.<name>]` declaration. Active
+backends (and their precedence order) are listed in `[secret_config].backends`. Today the
+implemented backends are:
+
+- `env-var` -- reads from the operator's process env. Default convention is
+  `AW_SECRET_<UPPER_SNAKE_CASE>`, overridable per secret via
+  `[secrets.<name>].backend_mappings.env-var = "CUSTOM_NAME"`.
+- `prompt` -- interactive prompt; batched at the start of the CLI run.
+
+**Eager prompting (FRD R4):** every command that opens new shells resolves all needed secrets up
+front, before any state mutation. The set of secrets is computed from the command's static filters
+(positional targets, `--vm`, `--workspace`, `--agent`, etc.) -- dynamic predicates like
+`--all-stopped` apply later, so the prompted set may over-approximate. Non-interactive mode (no TTY
+or `--non-interactive`) surfaces missing secrets as `SecretUnavailableError` with a per-secret hint
+naming which backends were tried. Commands that join existing shells (`session attach`,
+`session list`, `console attach` against a live tmux session, `console add-sessions`) consume no
+secrets per FRD R4 / R5.
+
+**Miss semantics:** what "not found" means depends on the backend. Conventional sources (`env-var`,
+`prompt`) treat a missing value as a soft miss and fall through to the next backend in the chain --
+a `GITHUB_TOKEN` env var that isn't set is just-not-set, not a config error. Persistent-store
+backends (1Password, Vault when implemented) will treat an explicit mapping that doesn't resolve as
+a hard miss: they raise `SecretMappingError` and the chain halts so a wrong `op://` URI doesn't
+quietly fall through to a prompt that masks the real problem.
+
+Inspect the merged result for any context with `agw env show`:
 
-```toml
-[admin.config]
-nerf_install_claude_plugin = true
+```bash
+agw env show --session my-session              # secrets redacted as <from secret: name>
+agw env show --vm my-vm --reveal-secrets       # resolves through the active backend chain
 ```
 
-The plugin provides skills that document available tools, and operator commands for managing
-permissions (`/nerftools:nerfctl-grant-allow`, `/nerftools:nerfctl-grant-deny`, etc.). Custom tool
-manifests can be added via `nerf_addl_manifests`.
+Inspect how each active backend would resolve each declared secret (e.g. "which env var name does
+this secret read from?") with `agw secret list`:
 
-Plugin identity (name, marketplace metadata) is defined in agentworks' own `nerf-config.yaml` and
-loaded via the nerftools config API. The version is a date-based build stamp that changes on each
-reinit. The build always emits an embedded marketplace so the plugin directory is installable
-standalone via `claude plugin marketplace add`.
+```bash
+agw secret list
+# NAME           env-var                  prompt
+# ----           -------                  ------
+# github-token   AW_SECRET_GITHUB_TOKEN   enabled
+# force-prompt   disabled                 enabled
+# api-key        OPENAI_API_KEY           enabled
+```
+
+Columns are the active backends in `[secret_config].backends` precedence order. Cells show each
+backend's static lookup identifier (env var name, vault path, `op://` URI) or `disabled` / `enabled`
+for backends with an explicit opt-out or no static identifier (prompt). Values are never resolved.
+
+`agw doctor`'s Secrets group leads with one row naming the active backend chain
+(`Configured backends: env-var, prompt`). Then one row per declared secret showing whether the chain
+would resolve it (`would resolve via env-var`, `would resolve via prompt`, or
+`not available in any backend`). Per-secret config-validity findings round out the group: unused
+secret declarations and `backend_mappings.<kind>` entries pointing at undeclared or inactive
+backends. `AGENTWORKS_*` identity overrides surface in the Configuration group (they're a
+config-load warning). Broken `{ secret = "..." }` references are caught earlier as a hard
+config-load error before doctor runs.
+
+### Mise (Polyglot Tool Manager)
+
+Agentworks installs [mise](https://mise.jdx.dev/) by default on all VMs for managing CLI tools
+(terraform, adr-tools, node, etc.) with optional lockfile-based integrity verification. See
+[Using mise](../docs/guides/mise.md) for the full guide.
+
+### Claude Code Plugins
+
+Agentworks can register Claude Code marketplaces and install plugins automatically per user (admin
+and per-agent). Configure via `claude_marketplaces` and `claude_plugins` in `admin.config` or any
+`agent_templates.*`. Requires the `claude` CLI on PATH (typically installed via
+`user_install_commands`). To install nerftools this way:
+
+```toml
+[admin.config]
+claude_marketplaces = ["https://github.com/WayfarerLabs/nerftools#4.1.0"]
+claude_plugins = ["nerftools-default@nerftools"]
+```
 
 ### Built-in Catalog
 
@@ -528,7 +671,10 @@ forward-only and run automatically.
 
 ## Environment Variables
 
-| Variable                      | Description                                     |
-| ----------------------------- | ----------------------------------------------- |
-| `TAILSCALE_AUTH_KEY`          | Tailscale auth key (skips prompt)               |
-| `GIT_CREDENTIALS_<CRED_NAME>` | Git credential for `<CRED_NAME>` (skips prompt) |
+| Variable                         | Description                                                                               |
+| -------------------------------- | ----------------------------------------------------------------------------------------- |
+| `AW_TAILSCALE_AUTH_KEY`          | Tailscale auth key (skips prompt). Legacy `TAILSCALE_AUTH_KEY` still read; warns once.    |
+| `AW_GIT_CREDENTIALS_<CRED_NAME>` | Git credential for `<CRED_NAME>`. Legacy `GIT_CREDENTIALS_<CRED_NAME>` still read; warns. |
+
+Legacy env-var names continue to work with a one-time deprecation warning per process per name, and
+will be removed in a future release.