docs(fleettools): Albok page + index entry (draft by albok-dev, Prime's ask); albok MCP in claude-only; task-board marked mothballed
This commit is contained in:
@@ -45,6 +45,15 @@ live contract for its API. Fetch it rather than trusting a transcription.
|
||||
*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`
|
||||
|
||||
## Knowledge
|
||||
|
||||
- **Albok** — the fleet knowledgebase at `http://albok.nh3.internal:8392`: every repo's persistent
|
||||
memory, the stash, and the library (books by chapter, papers, concepts). `albok` CLI; `albok-mcp`
|
||||
for Claude Code.
|
||||
*When:* before you decide something, check whether it was already decided, tried or measured,
|
||||
anywhere in the fleet.
|
||||
*Detail:* `/home/lkraven/development/eshpfi-management/docs/fleettools/albok.md`
|
||||
|
||||
## Credentials
|
||||
|
||||
- **secret** — Vaultwarden-backed credential store. `secret get|put|list|backfill`.
|
||||
@@ -117,7 +126,7 @@ live contract for its API. Fetch it rather than trusting a transcription.
|
||||
|
||||
## Claude-Code-only
|
||||
|
||||
- **ratecheck, remote-ssh MCP, skills** — harness-dependent; a
|
||||
- **ratecheck, remote-ssh MCP, albok 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.**
|
||||
|
||||
@@ -0,0 +1,59 @@
|
||||
# Albok — the fleet knowledgebase
|
||||
|
||||
**Service:** `http://albok.nh3.internal:8392` (= `10.100.50.44:8392`, albok-service on nh3-albok)
|
||||
**CLI:** `albok` · **MCP (Claude Code):** `albok-mcp`, registered at user scope · **Owner:** `albok-dev` (althing)
|
||||
|
||||
One searchable store of what the fleet knows: every repo's `persistent-memory.md` (entries, detail
|
||||
files, archives), the stash, and the library (books by chapter, papers, extracted concepts). Search
|
||||
is hybrid (vector + keyword) and LLM-free.
|
||||
|
||||
## Access
|
||||
|
||||
Every nh3-dev shell carries `ALBOK_SERVICE` and `ALBOK_TOKEN` — the shared **`fleet-agents` read
|
||||
token**: `fleet/*` (memory, stash) and `library/*` (fiction, nonfiction). It reads no personal wing.
|
||||
A shell older than 2026-10-16 may lack them; open a new one. A handle that needs more grants asks
|
||||
infra-ops for its own token.
|
||||
|
||||
```sh
|
||||
albok status # the wings this token reads, and their states
|
||||
albok search "why did we drop the reset endpoint" # --wing fleet/memory --top-k 20 --facet key=value
|
||||
albok read <object_id> # pristine bytes to stdout; lineage notes on stderr
|
||||
albok sidecar <object_id> # provenance: repo, file, commit, section, entry date
|
||||
albok related <object_id> # links, similar, same source, shared concepts — each with its reason
|
||||
```
|
||||
|
||||
Claude Code sessions get the same verbs as tools (`albok_search`, `albok_read`, `albok_sidecar`,
|
||||
`albok_related`, `albok_status`, …). Codex and Grok use the CLI.
|
||||
|
||||
## Reading the answers right
|
||||
|
||||
- **Never threshold on score.** The null floor (~0.031) sits just under real hits (~0.033); rank, don't cut.
|
||||
- **Coverage is reported, read it.** A reply lists `searched`, `locked` and `degraded` wings: an
|
||||
empty result over a degraded wing is not "nothing exists". An unreachable service is an
|
||||
outage, never an empty result (the client says which).
|
||||
- **Hidden by default:** objects classed `adult`, `personal` or `secret` are hidden from every
|
||||
reader; `--include CLASS` opts back in only where the token holds that class grant.
|
||||
- **Supersession is declared, not inferred.** Every object has a permanent `uid` (in every search hit).
|
||||
A read of an entry names what supersedes it (`superseded by …`); an empty lineage means "none
|
||||
declared", not "current". When your new memory entry replaces an older one, end it with
|
||||
`Supersedes [[<uid>]]` (the old entry's uid; a detail file may be named by its stem) and leave
|
||||
the old entry as written.
|
||||
|
||||
## Writing into it (nobody writes to the service directly)
|
||||
|
||||
Nemi, albok's ingester, walks every source hourly on nh3-dev (a user timer, a few minutes past the hour):
|
||||
|
||||
| You want to add | Do this |
|
||||
|---|---|
|
||||
| a decision, lesson or state for a repo | write it in that repo's `persistent-memory.md` under `~/development/` (Nemi reads the file on disk; commit it as usual) |
|
||||
| raw material (a transcript, an article) | `/stash` (Claude) or a file in `~/stash/` with its frontmatter |
|
||||
| a note for the operator's personal inbox (a personal wing: the fleet token cannot read it back) | a markdown file in `/srv/nemi/inbox/` |
|
||||
| a book | `scp book.epub lkraven@nh3-dev:/srv/nemi/books/fiction/` (or `nonfiction/`): validated, then shelved into `~/library/` and ingested the same hour, or moved to `rejected/` beside a reason file (`not_epub`, `drm`, `duplicate`, …); `LOG` records every decision |
|
||||
|
||||
## When to reach for it
|
||||
|
||||
Before you decide something, check whether it was already decided, tried or measured, in this repo
|
||||
or any other. Before you research a game-design, cognition or fiction question, check the library.
|
||||
|
||||
*Detail:* `~/development/albok/README.md`, `packages/albok-client/README.md` (CLI and MCP),
|
||||
`packages/albok-nemi/README.md` (sources, the book drop). Health: `scripts/albok-check` in that repo.
|
||||
@@ -42,13 +42,18 @@ stdout a non-tty and sudo skips the PTY.
|
||||
regexes and `bash -c` walks past it. `SSH_MCP_STRICT_ALLOWLIST=1` makes
|
||||
`~/.config/remote-ssh-mcp/config.json`'s `allowedHosts` authoritative.
|
||||
|
||||
## task-board MCP
|
||||
## albok MCP
|
||||
|
||||
`task_start` / `task_update` / `task_wait` / `task_complete` to surface work in
|
||||
progress at `http://10.250.50.70:7878/`. When you launch background shells, call
|
||||
`task_set_shells` with one short description each (and again with `[]` when they
|
||||
finish) — the board turns orange so the operator can tell the session is parked on
|
||||
background work rather than stalled on them.
|
||||
`albok-mcp`, registered at **user** scope (2026-10-16: `claude mcp add --scope user albok -- /home/lkraven/.local/bin/albok-mcp`).
|
||||
Tools `albok_search` / `albok_read` / `albok_sidecar` / `albok_related` / `albok_status` / …, the same verbs as the
|
||||
`albok` CLI (see `albok.md`). It reads `ALBOK_SERVICE` and `ALBOK_TOKEN` from the environment the session inherits
|
||||
(`~/.zshenv` sources `~/.config/secrets/env.sh`); no token is written into `~/.claude.json`. A session started
|
||||
from a shell older than that wiring gets a "no token" error from the tools: start a new session.
|
||||
|
||||
## task-board MCP — MOTHBALLED (2026-09-24)
|
||||
|
||||
Superseded by the High Seat (SVOS) and ledger; the container is stopped. **Do not call `task_*` tools** or
|
||||
wire its hooks into new sessions. Its data and stack are kept for a one-command bring-back (eshpfi CLAUDE.md).
|
||||
|
||||
## Skills
|
||||
|
||||
|
||||
Reference in New Issue
Block a user