Update docs to help agents handle full lifecycle

.agents/skills/brev-cli/SKILL.md

@@ -137,6 +137,14 @@ brev create my-instance --startup-script 'pip install torch'
 brev create my-instance --dry-run
 ```
 
+**Instance lifecycle after create:** BUILDING -> RUNNING -> SHELL `READY`. STATUS `RUNNING`
+alone is not usable - wait for the SHELL column to show `READY` in `brev ls` before
+`exec`/`shell`, and retry the first connection (sshd can refuse for another minute or two
+after `READY`). The create readiness poll can end with a spurious-looking `ErrorForbidden`
+even though the instance provisions fine - treat it as benign and watch `brev ls` instead.
+Stop/start preserves the disk (venv, payload) but can change the **public IP** - re-run
+`brev refresh` and re-resolve any direct endpoints after a restart.
+
 ### Instance Access
 ```bash
 # SSH into instance (interactive shell)
@@ -153,6 +161,14 @@ brev exec my-instance @/path/to/script.sh
 # Run on multiple instances
 brev exec instance1 instance2 instance3 "nvidia-smi"
 
+# Long-running commands (training runs etc.): brev exec holds the session until the
+# command exits - even for `nohup ... &` children - so launch long jobs fully detached
+# and poll a completion marker instead of holding the session:
+brev exec my-instance @launch.sh   # launch.sh ends with:
+#   setsid nohup python train.py > train.log 2>&1 < /dev/null & disown
+#   (and the job appends e.g. `echo DONE >> ~/progress.log` when finished)
+brev exec my-instance "grep -c DONE ~/progress.log"   # cheap poll
+
 # Open in editor
 brev open my-instance           # default editor
 brev open my-instance code      # VS Code
@@ -234,6 +250,14 @@ brev invite
 3. **Instance Cleanup** ([prompts/cleanup.md](prompts/cleanup.md))
    - List instances → Identify unused → Delete
 
+## How Billing Works
+
+- Billing is **per-second** and only while the instance is RUNNING - BUILDING/provisioning
+  time is not billed, and there is no round-up to whole hours.
+- A **STOPPED instance still accrues storage charges** until it is deleted - stopped is not
+  free. Delete instances when the work is done.
+- Usage/billing data lags real time - numbers checked right after teardown may still grow.
+
 ## Safety Rules - CRITICAL
 
 **NEVER do these without explicit user confirmation:**

.agents/skills/brev-cli/prompts/cleanup.md

@@ -17,7 +17,8 @@ Parse output to identify:
 ## Step 2: Identify Candidates for Cleanup
 
 Look for:
-- Stopped instances (not in use)
+- Stopped instances (not in use) - note: **stopped instances still accrue storage charges**
+  until deleted, so surface them even if they look parked deliberately
 - Old instances (name suggests temporary use)
 - Test/dev instances
 

.agents/skills/brev-cli/prompts/ml-training.md

@@ -93,7 +93,14 @@ brev exec <name> "python -c 'import torch; print(torch.cuda.is_available())'"
 
 Options:
 1. **Interactive:** `brev shell <name>` then run manually
-2. **Background:** `brev exec <name> "nohup python train.py > training.log 2>&1 &"`
+2. **Background:** launch fully detached - `brev exec` holds the session until the command
+   exits, even for `nohup ... &` children, so a plain `nohup ... &` hangs the exec call for
+   the whole training run. Use a launcher script that detaches and writes a completion marker:
+   ```bash
+   # launch.sh (run with: brev exec <name> @launch.sh)
+   setsid nohup python train.py > training.log 2>&1 < /dev/null & disown
+   ```
+   with the training command appending `echo DONE >> ~/progress.log` when finished.
 3. **Editor:** `brev open <name> cursor`
 
 ## Step 8: Monitor
@@ -102,8 +109,11 @@ Options:
 # Check GPU usage
 brev exec <name> "nvidia-smi"
 
-# Check training logs
-brev exec <name> "tail -f training.log"
+# Check recent training logs (avoid tail -f via exec - it never exits)
+brev exec <name> "tail -n 50 training.log"
+
+# Check for completion
+brev exec <name> "grep -c DONE ~/progress.log"
 ```
 
 ## Cleanup Reminder

.agents/skills/brev-cli/reference/commands.md

@@ -343,6 +343,11 @@ Prefix a file path with `@` to run a local script on the remote instance:
 - `@setup.sh` - relative path from current directory
 - `@/absolute/path/script.sh` - absolute path
 - The script is read locally and executed remotely
+
+**Long-running commands:** `brev exec` holds the session until the command exits,
+including for `nohup ... &` children. For long jobs (training runs), have the script
+detach fully (`setsid nohup <job> > run.log 2>&1 < /dev/null & disown`) and write a
+completion marker (`echo DONE >> ~/progress.log`) that later `brev exec` calls can poll.
 - Works with any shell script
 
 **Examples:**