docs: add FleetTools — an agent-family-agnostic index of fleet capability
Every agent on nh3-dev — Claude, Codex, Grok, Aider — needs the same answers: what runs here, how do I call it, what will bite me. Until now that lived in ~/.claude/CLAUDE.md, which only Claude sessions load, and it was interleaved with operator preferences that other families have no use for. Two-tier by design, matching the persistent-memory split: FLEETTOOLS.md is a 135-line index an agent reads whole, and each entry links to a detail file it opens only when it actually needs that tool. Reading the index costs about a fifth of reading the tree. Detail paths are absolute so they resolve from any working directory, since a non-Claude agent will cat the path rather than follow a markdown link. ~/FLEETTOOLS.md symlinks to the index for discovery. Rule zero is that live inventories get queried, not transcribed: Homepage /api/services, asset-engine /api/v1/services, LiteLLM /v1/models, and every FastAPI seat's /openapi.json. A copied service table would be stale within a month and this repo already has a standing rule against second copies that drift. Contents verified against the running fleet rather than copied from existing docs: binaries resolved on PATH, seven endpoints probed live, the LiteLLM roster counted at 40 models where the old note said ~30. No credentials are included; the vault and its CLI are pointed at instead.
This commit is contained in:
@@ -0,0 +1,33 @@
|
||||
# elway — SSH playbook runner (CHANGING things)
|
||||
|
||||
**Path:** `~/development/eshpfi-management/scripts/elway` (not on PATH)
|
||||
|
||||
```sh
|
||||
scripts/elway <host> --playbook playbooks/<name>.yaml
|
||||
```
|
||||
|
||||
Write a playbook under `playbooks/` instead of chaining `ssh -t host 'sudo …'`.
|
||||
Handles sudo once lazily, gives structured pass/change/fail reporting, supports
|
||||
idempotency via `creates:` / `when:` / `changed_when:`, and does file upload.
|
||||
|
||||
**Template:** `~/development/eshpfi-management/playbooks/elway-smoke.yaml`
|
||||
|
||||
## The split — pick by what you are doing
|
||||
|
||||
| | tool | why |
|
||||
|---|---|---|
|
||||
| **CHANGING** something | `scripts/elway` | idempotency, sudo handling, file transfer, structured results |
|
||||
| **LOOKING at** something | `remote-ssh` MCP (Claude) or plain `ssh` | no ceremony; a persistent shell where `cd` and exports survive |
|
||||
|
||||
Neither replaces the other. Reconnaissance — the `docker ps` / `grep` / `curl`
|
||||
questions — does not warrant authoring a playbook.
|
||||
|
||||
## Traps
|
||||
|
||||
- **Deploys must converge, not accrete.** The staging directory must be OUTSIDE the
|
||||
rsync target; inside, it becomes a silently frozen source. Verify CONTENT, not
|
||||
liveness.
|
||||
- **`pkill -f <pattern>` over ssh kills your own shell** when the pattern matches your
|
||||
own argv (exit 255). Kill by explicit PID or pidfile.
|
||||
- **Never run destructive fs operations on a variable path.** `rm` / `shred` /
|
||||
`mv`-over take LITERAL paths, one per line. No loops, no variables.
|
||||
Reference in New Issue
Block a user