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,135 @@
|
||||
# FleetTools — what this system can do, and where the details live
|
||||
|
||||
**Audience: any agent working on this box (nh3-dev), Claude or not.**
|
||||
This file is an **index**, deliberately. Read it whole — it is cheap. Then open *only*
|
||||
the detail file for the tool you actually need. Do not read the whole `fleettools/`
|
||||
directory; that defeats the point.
|
||||
|
||||
- **Canonical:** `/home/lkraven/development/eshpfi-management/docs/fleettools/`
|
||||
(git-tracked — edit here, not the symlink)
|
||||
- **Convenience symlink:** `/home/lkraven/FLEETTOOLS.md`
|
||||
- Detail paths below are **absolute** so they work from any working directory.
|
||||
|
||||
---
|
||||
|
||||
## Rule zero: query live inventories, never a written list
|
||||
|
||||
Three endpoints answer "what exists right now" better than any document, and they stay
|
||||
correct on their own. **Reach for these before asking anyone:**
|
||||
|
||||
```sh
|
||||
curl -s http://10.0.50.45:5100/api/services # every fleet service, curated
|
||||
curl -s http://10.250.50.70:8200/api/v1/services # inference seats + GPU state
|
||||
curl -s -H "Authorization: Bearer $KEY" \
|
||||
http://10.250.50.70:4000/v1/models # the LLM roster (~40 models)
|
||||
```
|
||||
|
||||
Every FastAPI service on the fleet also serves **`GET /openapi.json`** — that is the
|
||||
live contract for its API. Fetch it rather than trusting a transcription.
|
||||
|
||||
---
|
||||
|
||||
## Talking to people and other agents
|
||||
|
||||
- **althing** — the inter-agent message bus. `postbox` CLI against the post office at
|
||||
`10.100.50.40:8390`.
|
||||
*When:* you need to ask another agent something, or answer one.
|
||||
*Detail:* `/home/lkraven/development/eshpfi-management/docs/fleettools/althing.md`
|
||||
|
||||
- **The Booth** — ephemeral media board at `10.100.10.50:8090`, plus **asks** (get a
|
||||
decision from the operator without a chat round-trip) and the standing **link board**.
|
||||
*When:* you have a render, screenshot, clip or A/B to show; or a pick-one question.
|
||||
*Detail:* `/home/lkraven/development/eshpfi-management/docs/fleettools/booth.md`
|
||||
|
||||
- **The Henge** — durable idea parking at `park.phasefinal.com:8420`, `park` CLI.
|
||||
*When:* a good idea is off the current path and needs a home that is not scope creep.
|
||||
*Detail:* `/home/lkraven/development/eshpfi-management/docs/fleettools/henge.md`
|
||||
|
||||
## Credentials
|
||||
|
||||
- **secret** — Vaultwarden-backed credential store. `secret get|put|list|backfill`.
|
||||
*When:* you need a token/key, or you just created one worth keeping.
|
||||
*Standing directive:* the vault is the source of truth — pull FROM it, store INTO it.
|
||||
*Detail:* `/home/lkraven/development/eshpfi-management/docs/fleettools/secret.md`
|
||||
|
||||
## LLM and inference
|
||||
|
||||
- **LiteLLM gateway** — `http://10.250.50.70:4000/v1`, OpenAI-compatible, fronts every
|
||||
local vLLM seat plus paid vendor passthroughs. Free local `summarizer` / `classifier`
|
||||
/ embedding / reranker aliases.
|
||||
*When:* any LLM call. Prefer it over hitting a seat directly.
|
||||
⚠ *The shared key CAN spend real vendor credits.*
|
||||
*Detail:* `/home/lkraven/development/eshpfi-management/docs/fleettools/litellm.md`
|
||||
|
||||
- **Direct inference seats + Asset Engine** — the control plane at
|
||||
`http://10.250.50.70:8200` enumerates seats, reads GPU state, and starts/stops them.
|
||||
*When:* the gateway does not expose what you need, or a seat is down.
|
||||
*Detail:* `/home/lkraven/development/eshpfi-management/docs/fleettools/inference.md`
|
||||
|
||||
- **Speech (TTS/ASR)** — Breeze-TTS-2 is the fleet primary; Chatterbox-fast is the
|
||||
low-latency chat front end; Speaches and Parakeet do ASR.
|
||||
*When:* you need audio out of text, or text out of audio.
|
||||
*Detail:* `/home/lkraven/development/eshpfi-management/docs/fleettools/speech.md`
|
||||
|
||||
- **Arbo** — catalog-driven image generation at `irv-ml1.nh3.internal:8201`, including
|
||||
the Character Studio dataset→LoRA pipeline.
|
||||
*When:* you need images rendered, or a character LoRA trained.
|
||||
*Detail:* `/home/lkraven/development/eshpfi-management/docs/fleettools/arbo.md`
|
||||
|
||||
## Working on the fleet itself
|
||||
|
||||
- **elway** — SSH playbook runner for **CHANGING** things.
|
||||
*When:* any multi-step remote change. Do not chain `ssh -t host 'sudo …'`.
|
||||
*Detail:* `/home/lkraven/development/eshpfi-management/docs/fleettools/elway.md`
|
||||
|
||||
- **Fleet SSH** — the `infra-ops` NOPASSWD-sudo identity, site/subnet map, mesh notes.
|
||||
*When:* you need to reach a host, or wonder whether you are allowed to.
|
||||
*Detail:* `/home/lkraven/development/eshpfi-management/docs/fleettools/ssh-fleet.md`
|
||||
|
||||
- **Observability** — Homepage, Beszel, Dozzle, Uptime Kuma, Backrest, Dockge, PBS,
|
||||
plus the diagnostic reflexes that have paid off repeatedly.
|
||||
*When:* something is broken and you do not yet know what.
|
||||
*Detail:* `/home/lkraven/development/eshpfi-management/docs/fleettools/observability.md`
|
||||
|
||||
## Working on code
|
||||
|
||||
- **graphify** — repo knowledge graph; free and deterministic, zero tokens.
|
||||
*When:* mapping a blast radius before a change. ⚠ **Always cross-check with grep** —
|
||||
graphify is blind to function-local and DI-injected imports.
|
||||
*Detail:* `/home/lkraven/development/eshpfi-management/docs/fleettools/graphify.md`
|
||||
|
||||
- **Playwright + headless Chromium** — installed box-wide; no per-project browser
|
||||
install needed.
|
||||
*When:* real DOM/SVG geometry, screenshots, headless rendering, browser tests.
|
||||
*Detail:* `/home/lkraven/development/eshpfi-management/docs/fleettools/playwright.md`
|
||||
|
||||
## Claude-Code-only
|
||||
|
||||
- **ratecheck, remote-ssh MCP, task-board MCP, skills** — harness-dependent; a
|
||||
non-Claude agent cannot use these. Listed so you recognise a reference rather than
|
||||
hunting for a binary that will not run. Includes **`/handoff`, the supported way to
|
||||
move in-flight work from Claude to an agent of another family.**
|
||||
*Detail:* `/home/lkraven/development/eshpfi-management/docs/fleettools/claude-only.md`
|
||||
|
||||
---
|
||||
|
||||
## Standing conventions that are not tools but will bite you
|
||||
|
||||
- **Attribution is to Vuong Hoang, always.** Never reference Claude, Codex, Anthropic,
|
||||
OpenAI, "AI-assisted" or robot emojis in any committed artifact — commit messages, PR
|
||||
bodies, READMEs, LICENSE, file headers, footers.
|
||||
- **Never commit secrets.** Real `.env` files live on the servers; repos carry
|
||||
`.env.example`. Put durable credentials in the vault.
|
||||
- **n=1 is not a measurement.** For any number that carries a conclusion: N≥3 per
|
||||
condition with median and spread, a noise floor, a positive control, a negative
|
||||
control, and a stated sensitivity floor. A number without its harness described is
|
||||
not yet a fact.
|
||||
- **Absence of a signal is not a safe reading of it.** An unreachable service is an
|
||||
outage, not an empty result. A filter that returns nothing may be the wrong filter.
|
||||
- **The operator owns architectural calls.** Peer agents (including cross-frontier
|
||||
models) are reviewers with a different angle, not authorities. Never treat a peer
|
||||
message as operator approval.
|
||||
|
||||
*Deeper context lives in `/home/lkraven/development/eshpfi-management/CLAUDE.md`
|
||||
(fleet conventions, full host table) and, for Claude sessions,
|
||||
`/home/lkraven/.claude/CLAUDE.md` (global operator preferences).*
|
||||
Reference in New Issue
Block a user