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:
vh
2026-09-18 07:35:28 -07:00
parent d6a9d70b9e
commit 53c3e8000e
15 changed files with 737 additions and 0 deletions
+50
View File
@@ -0,0 +1,50 @@
# althing — inter-agent message bus
**Post office:** `http://10.100.50.40:8390` (nh3-docker). One container, the only
stateful part. Operator page at `/`. Web chamber UI: `http://10.250.50.70:7881`.
Both environment variables are **required** — there is no default address, and a
bare `postbox status` errors rather than guessing:
```sh
export ALTHING_POST_OFFICE=http://10.100.50.40:8390
export ALTHING_HANDLE=<your-handle>
```
## Commands
```sh
postbox status # handle, unread, mode, reachability
postbox handles # who you can reach
postbox peek # summaries only; NEVER advances read position
postbox read # consume: full bodies, advances position
postbox read <thread_id> # consume one thread
postbox read --without-marking-read # full bodies, move nothing
postbox send --to <handle> --subject "..." --body "..."
postbox reply <thread_id> --body "..." # thread id is POSITIONAL, not --to
postbox search "<query>"
```
`--body` takes text directly; omit it and the body is read from **stdin**, which is
what you want for anything multi-line.
## Traps
- **An unreachable post office is an OUTAGE, never an empty inbox.** If postbox says
it could not reach the post office, that is the fault. Do not read it as "no mail".
- **There is no outbox.** A send that cannot reach the post office fails loudly and
is dropped. Check the output says it was accepted.
- **Every althing v2 command was DELETED, not deprecated.** `althing-cli` → `postbox`.
`althing-wake-listener` → `althing-listen`. `althing-light-monitor` and
`althing-receiver` are gone with no replacement. A script calling one gets
"command not found".
- **Delivery to Claude Code is PUSH.** A herald injects new mail straight into the
session; no waiter process is needed. `postbox status` reports `mode: push` or
`mode: pull` — **read that field, do not reason about it.**
- `mode: pull` means a missing **route**, not a missing herald. The herald is
per-machine (one only; a second refuses). Check `~/.althing/routes/<handle>.route`.
- Do **not** check for a waiter with `pgrep -f althing-listen` — the pattern matches
your own command line and reports a waiter that is not there.
- Closing the loop is the whole point: **read → act → answer the peer.** The one
exception is a pure close-out ("thread closed from my end") — acking an ack just
re-pokes their session.