esh-pfi-infrastructure/docs/fleettools/FLEETTOOLS.md

# 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`

- **Blender** — Blender 5.2 LTS on fv-ml1 GPU 3 (borrowed, on demand). `scripts/blender-run` for
  headless one-shot renders and conversions; `scripts/blender-mcp` for agent-driven scenes
  (register per task).
  *When:* 3D rendering, STL → image, scene building.
  *Detail:* `/home/lkraven/development/eshpfi-management/docs/fleettools/blender.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, 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).*