diff --git a/.agents/skills/brev-cli/SKILL.md b/.agents/skills/brev-cli/SKILL.md
index cb7b7cc2c..f054e4526 100644
--- a/.agents/skills/brev-cli/SKILL.md
+++ b/.agents/skills/brev-cli/SKILL.md
@@ -47,6 +47,9 @@ brev create my-instance --type g5.xlarge
 # List your instances
 brev ls
 
+# List external nodes (a separate list from `brev ls`)
+brev ls nodes
+
 # SSH into an instance (interactive)
 brev shell my-instance
 
@@ -169,6 +172,36 @@ brev copy my-instance:/remote/file ./local-path/
 brev port-forward my-instance -p 8080:8080
 ```
 
+### Listing Instances and Nodes
+`brev ls` covers two separate namespaces. External nodes never appear in
+`brev ls`, so check `brev ls nodes` before concluding a machine doesn't exist.
+
+```bash
+brev ls              # cloud instances
+brev ls instances    # same as above, explicit
+brev ls nodes        # external nodes only (machines registered to the org)
+brev ls orgs         # organizations
+brev ls --json       # machine-readable
+brev ls nodes --json
+```
+
+|  | `brev ls` | `brev ls nodes` |
+|---|---|---|
+| Status values | `RUNNING` / `STOPPED` | `Connected` / `Disconnected` |
+| Columns | NAME, STATUS, BUILD, SHELL, ID, MACHINE, GPU | NAME, STATUS |
+| `stop` / `start` / `delete` | yes | no — Brev doesn't manage their lifecycle |
+
+The two `--json` shapes differ: `brev ls nodes --json` is a top-level array,
+while `brev ls --json` wraps rows in `.workspaces`.
+
+```bash
+brev ls nodes --json | jq -r '.[].name'
+brev ls       --json | jq -r '.workspaces[].name'
+
+# Names of nodes that are currently connected
+brev ls nodes --json | jq -r '.[] | select(.status=="Connected") | .name'
+```
+
 ### Instance Management
 ```bash
 # List instances
@@ -267,6 +300,7 @@ Do this proactively when:
 
 **"Instance not found":**
 - Run `brev ls` to see available instances
+- Run `brev ls nodes` — external nodes are a separate list and never show up in `brev ls`
 - Check if you're in the correct org: `brev org ls`
 
 **"Failed to create instance":**
diff --git a/.agents/skills/brev-cli/reference/commands.md b/.agents/skills/brev-cli/reference/commands.md
index 978de983b..fe91cbbd5 100644
--- a/.agents/skills/brev-cli/reference/commands.md
+++ b/.agents/skills/brev-cli/reference/commands.md
@@ -211,9 +211,17 @@ brev search cpu | brev create my-cpu-box
 List instances in active org.
 
 ```bash
-brev ls [flags]
+brev ls [subcommand] [flags]
 ```
 
+**Subcommands:**
+| Subcommand | Lists |
+|---|---|
+| *(none)* | cloud instances |
+| `instances` | cloud instances (explicit form) |
+| `nodes` | external nodes only |
+| `orgs` | organizations |
+
 **Flags:**
 | Flag | Short | Description |
 |------|-------|-------------|
@@ -221,6 +229,37 @@ brev ls [flags]
 | `--all` | | Show all instances in org |
 | `--json` | | Output as JSON |
 
+#### Instances vs. external nodes
+
+Two separate namespaces — an external node never appears in `brev ls`.
+
+```bash
+$ brev ls
+ NAME         STATUS   BUILD      SHELL  ID         MACHINE         GPU
+ my-instance  RUNNING  COMPLETED  READY  jmorx0saw  n2d-standard-2  -
+
+$ brev ls nodes
+ NAME     STATUS
+ my-node  Connected
+```
+
+|  | `brev ls` | `brev ls nodes` |
+|---|---|---|
+| Status values | `RUNNING` / `STOPPED` | `Connected` / `Disconnected` |
+| Columns | NAME, STATUS, BUILD, SHELL, ID, MACHINE, GPU | NAME, STATUS |
+| `stop` / `start` / `delete` | yes | no |
+
+The two `--json` shapes differ — `brev ls nodes --json` returns a top-level
+array, `brev ls --json` wraps rows in `.workspaces`:
+
+```bash
+brev ls nodes --json | jq -r '.[].name'
+brev ls       --json | jq -r '.workspaces[].name'
+
+# Only the nodes that are currently connected
+brev ls nodes --json | jq -r '.[] | select(.status=="Connected") | .name'
+```
+
 When stdout is piped, outputs instance names only (one per line) for chaining.
 
 ### brev delete