Move the reasoning out of CLAUDE.md and leave the rules (V-670)

490 lines still loads into every session, and most of them explained a
subsystem rather than constraining an agent. The owner's cap is 200. This
lands at exactly 200.

Four new living docs take what left:

  docs/deployment.md  the two boxes, the resident model, the embedder, STT,
                      the daemon table, who is in compose, the voice wire,
                      mavwaked on workpc, the web UI conventions
  docs/world.md       what replaced "never phones home", why Response.Empty()
                      is the whole gate, the timeouts, Kiwix
  docs/language.md    the LLM output contract and the three Russian mechanisms
  docs/workflow.md    the five stores, the doc tiers, Vikunja, the guards

CLAUDE.md keeps the pointer table and the rules. Every "do not do X", every
path and every owner's call stayed. What went is the before-and-after
narrative behind each one, which is what a living doc is for.

Verified rather than trusted. Every backticked literal in the old file was
diffed against the union of the new ones. Twenty-four came up missing and
three groups were facts rather than narrative, so they were restored:

  - the ecosystem client table (nexusClient, praxisClient, the vendored hexis
    client, the three config keys and their default URLs) into
    docs/ecosystem.md, which did not carry it
  - TestOnlyAGrammarMayDropTheBoundary and TestNamingRecallKeepsTheBoundary
    into docs/routing.md, since they pin the boundary rule in both directions
  - the ipc.Dial vs voice.Dial trap and docs/plans/17 into docs/deployment.md

diff-budget.sh blocked on the changed-line count again. It counts markdown,
which the repo's own pre-commit hook exempts, and this commit touches
nothing else.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013ptwopxyo3Z2kwFckHkLvN

docs/deployment.md

@@ -0,0 +1,192 @@
+# Deployment: the boxes, the models, the daemons
+
+*Last verified: 2026-08-09 @ a9b480a*
+
+What runs where, and why each choice was made. `CLAUDE.md` carries only the
+rules. This file carries the reasoning.
+
+## The two boxes
+
+**homesrv** is a Ryzen 5 5600U laptop and the deploy target. It offloads to the
+Vega iGPU over Vulkan (`n_gpu_layers: 99`). Compose passes `/dev/dri` and the
+render gid (993), and without both Vulkan enumerates zero devices and
+llama-server falls back to CPU silently.
+
+**workpc** is the workstation, 16GB of VRAM, reached as `kami@workpc` at
+192.168.1.105. Model work moved there on 2026-08-02 by the owner's call, because
+homesrv cannot grow a GPU.
+
+Three rules govern the seam:
+
+- **The workstation is never assumed up.**
+- **Fall back silently** when it would only do the job better.
+- **Name the gap** when the resident model cannot do the job at all.
+
+A world question goes through `LLMPhraser.PhraseWorld` and returns `worldGap`
+(`cmd/mavend/worldmodel.go`) rather than an invented answer. A box with no
+`workstation` block behaves exactly as it did before the seam. `docs/offload.md`
+says which caller is which.
+
+## The resident model
+
+**Qwen3-1.7B** (`UD-Q4_K_XL`), stock, not yet the CPT'd one. It is a Thinking
+variant, so `n_ctx` is 4096. Reasoning tokens need the room, and 4096 is what
+every score was measured at.
+
+The target is the locally CPT'd Qwen3-1.7B (V-122, training in flight). Stock
+already speaks good Russian. What it gets wrong is the persona. It writes `я рад`
+where Maven needs `рада`.
+
+**Do not bother with sub-500M models.** LFM2.5-230M and 350M were measured on
+2026-07-31 and both are unusable in Russian
+(`docs/evals/2026-07-31-model-bakeoff.md`). Their published IFEval and BFCL
+numbers are English-only.
+
+Model files live in `/mnt/hdd1/llms`, bind-mounted to `/opt/maven/models/llm`.
+That **shadows** the repo's `models/llm/`, so a gguf sitting there is not loaded
+by anything. Swapping the resident model is a one-line change to
+`phraser.model_path` in `deploy/mavend.json`.
+
+The workstation model is gemma-4-E4B as of 2026-08-09, replacing the 12B by the
+owner's call. Keep the 12B gguf. It is the better teacher for label runs, at
+72.7% destination against E4B's 57.6%.
+
+## The embedder
+
+**It stays on homesrv permanently**, because it backs the floor. It is
+multilingual-e5-small, quantized and asymmetric. `EmbedQuery` and `EmbedPassage`
+apply the `query:` and `passage:` prefixes it was trained with. Calling plain
+`Embed` on a note is a bug. See `docs/evals/2026-08-04-recall-e5-small.md`.
+
+The vendored onnxruntime under `deps/` has two copies, and the stale one is
+1.17.1. The live runtime is 1.26.0, and the Go binding asks for API 26. Anything
+shipped to another box needs `deps/onnxruntime-linux-x64-1.26.0`.
+
+## Speech-to-text
+
+`sttSeam` in `cmd/mavend/voicewire.go` builds an `stt.Pair` beside `modelSeam`.
+It prefers CrisperWhisper 2.0 turbo on workpc with mavsttd as the floor. It takes
+only the silent half of the rule, because a worse transcript is still a turn. So
+`stt.Pair` has no `TranscribeRemote` and the fallback is never spoken.
+
+CW2 turbo scores 10.4% WER in Russian against 27.5% for the `ggml-small.bin`
+mavsttd loads, over 200 Golos clips
+(`docs/evals/2026-08-09-crisperwhisper2-russian-wer.md`).
+
+**whisper.cpp cannot load CW2 at all.** It reads its language count off the
+vocabulary size. CW2's 51897 tokens shift seven special token ids. So CW2 is its
+own transformers service on port 8081 (`deploy/cw2/serve.py`).
+`stt.HTTPTranscriber` posts raw PCM to it with a bearer token, because audio is
+the most sensitive thing that crosses this seam. The switch is `workstation.stt`
+in `deploy/mavend.json`, and deleting the block sends every utterance to mavsttd.
+
+**mavgpud runs that service as a second child.** This is not an optimisation.
+CW2 is a ROCm process on the same card, so it registers on the KFD like any
+contender. Under its own systemd unit it made mavgpud evict llama-server every
+few seconds. That took the model arm down for eight minutes on 2026-08-09. The
+card needs one owner. CW2 is on the yield clock and not the idle one. At 1.6GB
+it denies the card to nobody.
+
+Text-to-speech has not moved. piper on homesrv is the only synthesizer.
+
+## The daemons
+
+| Binary | Role |
+|---|---|
+| `mavend` | **Core.** Router, phraser, memory, reminders, digestion tick. Owns the DB and IPC socket. |
+| `mavweb` | HTTP UI and PWA (`/dash`, `/history`, `/trace`, `/notifications`, `/tools`), WebAuthn auth. |
+| `mavsttd` | Speech-to-text (whisper.cpp, CGO). |
+| `mavttsd` | Text-to-speech (piper subprocess). |
+| `mavwaked` | Wake-word and VAD gate. Runs on workpc. |
+| `mavenclient` | Voice loop client (mic, stt, core, tts). Not deployed. |
+| `mavpoll` | Environment poller: netdata alarms, uptime-kuma, zenmoney, wireguard presence. Writes facts, sends nothing. Telegram is `internal/delivery/telegramsink`. |
+| `mavcaldav` | CalDAV calendar sync. |
+| `mavmaild` | Mail reader (IMAP, read-only). Holds the IMAP password, core never sees it. |
+| `mavgpud` | GPU supervisor. **Runs on workpc**, own unit `deploy/mavgpud.service`. Keeps llama-server loaded while the card is free (V-488). Maven never asks it for anything and reads `/health` through `llm.Pair`. |
+| `mavupdate` | Not a daemon. Operator CLI a human runs on the box to deploy a new build. |
+
+Two binaries have no Makefile target and neither is deployed. `mavseal` encrypts
+a live tmpfs working copy back to the ciphertext file when mavend was killed
+before `defer st.Close()` sealed it. `labelgen` runs the stage 0 grammars over
+utterances and prints JSONL, the training data for the routing heads.
+
+Daemons are wired socket-to-socket, not linked. `internal/ipc` is the wire
+protocol. `deploy/mavend.json` sets socket paths, model paths and the phraser and
+embedder blocks, with `${VAR}` expansion from gitignored `deploy/telegram.env`.
+
+### Who is in compose, and who is not
+
+**`docker-compose.yml` runs five**: `mavend`, `mavsttd`, `mavttsd`, `mavweb`,
+`mavpoll`. Count against compose, not against the table above.
+
+`mavmaild` and `mavcaldav` are commented out, each with the reason beside it. The
+first needs a mail account and the second a CalDAV account, and this box has
+neither. Two things ride on the CalDAV absence (V-644). Agenda questions route to
+`IntentQuery` at stage 0, and the `calendar` query source then reads a table
+nobody writes. And `loop.State.CalendarBusy` is fed by the same facts, so the
+gate's "do not nag mid-meeting" is permanently false.
+
+`mavenclient` is still absent. `mavwaked` moved to workpc on 2026-08-09 (V-515).
+
+### The voice wire
+
+`internal/voice` is plaintext with no auth. Its own server doc says production
+binds inside the wg tunnel, because the wg layer is the L0 floor. workpc is not
+a wg peer, it sits on wlan0. So the tunnel is ssh instead.
+
+mavend publishes the voice port to homesrv loopback only, `127.0.0.1:9110`.
+Host 9100 is Vikunja's MCP, hence 9110. The container side stays 9100 so mavweb
+keeps reaching `mavend:9100` by name. `deploy/maven-voice-tunnel.service` on
+workpc forwards it over his key.
+
+**Do not replace this with a LAN bind.** `SurfaceVoice` caps acts at L0, so an
+unauthorized speaker could not run a destructive tool. L0 does not cap reading,
+so they would still hear his facts, notes and calendar read back.
+
+Both `mavwaked` and `mavenclient` speak `voice.Dial`, not `ipc.Dial`. The
+`netaddr` token guards the daemon-to-daemon IPC seam and never touches this one.
+`ipc.Dial` does take `tcp://host:port?token=...`, which is why V-515 was filed
+as a config change. That premise was wrong, and the ssh leg is the correction.
+
+The voice loop belongs on a client machine where the owner is standing, and that
+machine is workpc (V-463, `docs/plans/17-where-the-voice-loop-runs.md`). homesrv
+has a microphone, because it is a laptop, but it is in the wrong room.
+
+### mavwaked on workpc
+
+`deploy/mavwaked.service`, a user unit beside `mavgpud.service`. Two flags are
+deliberate.
+
+`-vad-model` is passed. Silero answers "is this frame speech" where the energy
+floor answers "is this frame loud". It declines white noise at the same RMS, 0
+frames against 68 to 99, and still hears all four spoken fixtures
+(`docs/evals/2026-08-09-silero-vad.md`). It costs 509µs a frame and never touches
+the GPU. A model that will not load is logged and not fatal.
+
+`-barge-in` is not passed. The threshold is room-specific and this room has no
+number yet. Read the "suppressed while speaking" means out of the journal first.
+
+The device is `plughw:0,0` and not `hw:0,0`. The fifine offers 2 channels at
+44100 or 48000 and nothing else, and mavwaked asks arecord for 16kHz mono. Bare
+`hw` dies on "Channels count non available" before a frame is read.
+
+There is no wake word yet (V-487 stage two), so the loop runs open. mavwaked
+connects lazily, so `voicesink` cannot push a nudge to it until it has sent one
+utterance.
+
+**Passwords are read from files, never taken as flag values.** `mavcaldav` uses
+`-pass-file` and `-render-pass-file`. `mavpoll` and `mavmaild` follow the same
+rule.
+
+## Web UI conventions
+
+Server-rendered pages share `cmd/mavweb/static/ui.css` (served at `/ui.css`) and
+the shell partial in `cmd/mavweb/shell.html`. A page opens with
+`{{template "shellTop" "<page-key>"}}` and closes with `{{template "shellBottom"}}`,
+and the key marks the active sidebar link.
+
+Every page is its own embedded `.html` file next to `main.go`. No page markup
+lives in Go, and the sidebar is data (`sidebarSections`, `pageIcon`) the template
+renders. No per-page `<style>` beyond true one-offs. Wrap every table in
+`<div class=scroll>` so wide data pans on a phone. Local preview and headless
+screenshot recipes are in `AGENTS.md`.

docs/ecosystem.md

@@ -30,6 +30,12 @@ Maven is the user-facing control center, but not the source of truth for identit
 
 Maven provides the human interface over the other systems.
 
+| Service | Owns | Maven's client | Configured at |
+|---|---|---|---|
+| **Nexus** | Canonical entity ids, names, aliases, relationships. Projects, services, devices, people, pets, places. | `nexusClient` in `cmd/mavend/ecosystem.go`, `POST /api/v1/resolve` | `nexus.url` (`http://nexus:9740`) |
+| **Praxis** | Operational attention and item lifecycle. What needs looking at, what changed, what is unresolved. | `praxisClient`, the HTTP tools API under `/api/v1/tools/` | `praxis.url` (`http://praxis:8989`) |
+| **Hexis** | The capability registry and the only path to executing anything. | vendored `github.com/kami/hexis/pkg/client` | `hexis.url` (`http://hexis:9741`) |
+
 It is responsible for:
 
 - interpreting Russian and English utterances

docs/language.md

@@ -0,0 +1,74 @@
+# Language: what the model emits, and how Russian is matched
+
+*Last verified: 2026-08-09 @ a9b480a*
+
+Two contracts live here. What a model call is allowed to return, and which
+mechanism is allowed to recognise a Russian word.
+
+## The LLM output contract
+
+All phrasing paths emit `{"response":"...","mood":"..."}`. They fall back to
+plain text when the model skips the JSON.
+
+**One parser, `parseResponseMood` in `internal/phraser/parse.go`.** Every path
+reaches it: the six `LLMPhraser` methods, `PhraseWorld`, and
+`Replier.PhraseReply`. `cmd/mavend/replier_llm.go` wraps the last of those,
+holds the stub fallback, and parses nothing itself. Mood is a fixed enum.
+
+The router prompt is a separate contract:
+
+```text
+[{"intent":<enum>, key?, value?, text?, verb?}, ...]
+```
+
+over 7 intents: `fact, reminder, note, query, act, chat, system`.
+`llm/check_prompt_parity.py` in the training workspace enforces that the Go
+prompt and the relabelling prompt stay identical. They diverged once, and the
+relabelled set then taught a head the Go router never asks for.
+
+## Russian patterns: three mechanisms, no fourth
+
+Hand-written Russian stem patterns were swept out on 2026-08-04 by the owner's
+call. A regex whose output is a fact or a route is the defect. A regex over
+structured input, such as HTML, MIME, JSON, a URL or an argv list, is not.
+
+Before writing a Russian word list, pick one of these.
+
+### `internal/lexicon`, for closed classes
+
+`lexicon_ru_v1.json` holds interrogatives, capture verbs, reminder verbs,
+cardinals, day offsets, parts of day, weekdays, months and spoken hours.
+Editing a word is a data change and there is exactly one copy. Months used to
+live in three files and drifted between them.
+
+Cardinals carry the oblique forms, because a spoken time declines. `в семь` and
+`к семи` are one hour.
+
+### `internal/morph`, for grammar
+
+From the vendored golem Russian dictionary. `IsVerbForm` and `SameWord`.
+
+Lemma matching is BROADER than stem-plus-one-ending. A verb slot that means the
+imperative must be matched exactly. `говори` and `говорил` share a
+lemma and only one of them is a command
+(`cmd/mavend/quiet_toggle.go`).
+
+### `cmd/mavend/topics.go` and the embedder, for open sets
+
+Use these when the question is what a turn is ABOUT. Frozen seeds per subject
+plus a real `other` class, scored against the turn's own query vector.
+
+Same shape as the personal boundary in `personalboundary.go`, with one
+difference. A topic must clear the runner-up by `topicMargin`, because a false
+claim here spends a network scan rather than one honest "не знаю". The old
+keyword tests stay as the offline floor.
+
+### The ecosystem trio
+
+Use it when the answer is not in the utterance at all. Identity is Nexus's,
+never a local pattern.
+
+## Seeds are scoring data
+
+Editing one moves a recogniser. Re-measure against the `TestONNX*` tests rather
+than eyeballing the change.

docs/routing.md

@@ -353,6 +353,11 @@ stage 0 grammar may drop it (owner's call, V-666, 2026-08-09).
 one of those could stop implying the others. `definitionQueryPattern` claims "кто
 такой X", so the 2026-08-07 case is still anchored and still answered.
 
+`queryWalk` reads `SourceAnchored` for the query source marked `boundary: true`
+and no other. Every other guesser still comes off the turn, whoever named the
+destination. `TestOnlyAGrammarMayDropTheBoundary` and
+`TestNamingRecallKeepsTheBoundary` pin both directions.
+
 ### The destination fixture
 
 `want_source` on `eval.Case` is a pointer, because the destination has three

docs/workflow.md

@@ -0,0 +1,80 @@
+# Session workflow: the five stores and the guards
+
+*Last verified: 2026-08-09 @ a9b480a*
+
+How a session starts, where each kind of writing belongs, and what the hooks
+refuse. `CLAUDE.md` carries the commands. This file carries the reasoning.
+
+## Five stores
+
+Each owns something the others must not hold.
+
+| Store | Holds | Lifetime |
+|---|---|---|
+| Vikunja task | goal, constraints, assumption ledger, status | durable |
+| `CLAUDE.md`, `AGENTS.md` | what an agent must know before touching code | durable |
+| `docs/` | design, measurements, decisions | durable |
+| `TASK.md` | the brief for this branch, written by `task start`, immutable | one branch |
+| `HANDOFF.md` | only what the next agent needs to resume | one session |
+
+`TASK.md` and `.task/` are excluded through `.git/info/exclude`. `HANDOFF.md` is
+gitignored and injected at session start. If a line in the handoff would still
+matter next week, it is in the wrong file.
+
+## Doc tiers
+
+Tiered by path, so staleness is visible from the filename.
+
+- Files directly under `docs/` are living. They carry a
+  `Last verified: <date> @ <sha>` line and are corrected in place.
+- Files under `docs/evals/` are dated measurements and are never edited after
+  the day. A newer number is a new file, not an edit.
+- Files under `docs/archive/` are dead and read by nobody by default.
+
+## Vikunja
+
+This repo is project **Maven** (ID 2). MCP at `http://localhost:9100/mcp`, or
+`http://192.168.1.104:9100/mcp` from workpc. Feature, bug and deploy tasks go
+there.
+
+A task holds the goal, the constraints and the assumption ledger. A session
+without a task id cannot be resumed by anyone, so a session with none asks for
+one first.
+
+**Close a finished task with `done: true` and nothing else** (owner's call,
+2026-08-07). Do not write a completion summary into the description on the way
+out. It is lost anyway, and the durable record is the commit messages and the
+merged PR. `update_task` carrying a `description` resets `done` to false, which
+is why a write-up ever took two calls.
+
+## The branch tool
+
+`~/.local/bin/task` owns the branch, the commit identity and the PR. One task,
+one session, one PR.
+
+```sh
+task start <vikunja-id>   # branch off origin/master, write TASK.md, fetch review comments
+task pr                   # push, open or refresh the PR, label Vikunja, notify
+task comments             # re-pull this branch's review comments into .task/
+```
+
+`/pickup` opens a session and `/wrap` closes it. Wrap at roughly half context
+rather than letting the session compact.
+
+## Guards
+
+Two hooks in `.githooks/`, tracked, wired with `core.hooksPath`. A fresh clone
+needs `git config core.hooksPath .githooks`.
+
+- `pre-commit` refuses master, and refuses more than 300 changed lines in
+  non-markdown files. Markdown is exempt and may land as one batch.
+- `commit-msg` requires the subject to end with `(V-<id>)`. `V-` and not `#`,
+  because Gitea autolinks `#123` to a Gitea issue, which is the wrong tracker.
+
+Two more guards live outside the repo, in `~/.claude/hooks/`. `diff-budget.sh`
+blocks further edits past 600 changed lines on a `task/` branch.
+`prose_lint_hook.py` checks prose on every write. Both measure against
+`origin/master`, so a local master that is ahead of the remote makes the diff
+budget read high.
+
+`--no-verify` exists. Using it means saying why in the commit body.

docs/world.md

@@ -0,0 +1,71 @@
+# The world chain
+
+*Last verified: 2026-08-09 @ a9b480a*
+
+What happens when the answer is not his. `CLAUDE.md` carries the boundary rule.
+This file carries the mechanism and the measurements behind it.
+
+## What replaced "never phones home"
+
+That promise was deprecated on 2026-07-31 by the owner's call. A 1.7B does not
+know enough to answer world questions, so she reads external sources. Four rules
+replaced it:
+
+- **No telemetry, no cloud model, no third-party account.** That part never
+  changes. Nothing about Maven is reported to anyone and inference stays on the
+  box.
+- **The owner's data first, then the world.** Every source reading his facts,
+  notes, calendar, tasks or house runs before anything outside. The personal
+  boundary sits between them. Reading beats recalling for a small model.
+- **The owner's notes and facts are never search input.** Only the utterance
+  goes out. Never the persona block, the history, or matched notes.
+- **External search is allowed and off unless configured**, like weather and
+  telegram. The code default is off. `deploy/mavend.json` ships a `search`
+  block, so it is on for this box and deleting the block turns it off again.
+
+**Live search leads and the ZIMs are the fallback** (owner's call, 2026-08-02).
+A self-hosted SearXNG answers first. The Kiwix ZIMs on homesrv answer when the
+search is empty, unreachable, or the line is down.
+
+## The gate is emptiness and nothing else
+
+`Response.Empty()` is the whole gate. There is no quality threshold in front of
+it. Four signals were tried and none separates a real question from an invented
+one.
+
+Token overlap was the closest and it still fails. "столица Франции" would lose
+its answer, because the answer is Париж and that word is not in the question
+(`docs/evals/2026-08-05-search-quality-signals.md`).
+
+**The embedder is not a fifth signal.** Query-to-passage cosine measures topic
+and not whether the passage answers. The two sets overlap
+(`docs/evals/2026-08-09-kiwix-topic-retrieval.md`).
+
+## Timeouts
+
+The connect phase alone is capped at `dialTimeout`, 1.5s, because a blackholed
+host once cost the owner 8 seconds. A slow instance that did connect keeps the
+full 8 (`docs/evals/2026-08-05-kiwix-offline-fallback.md`).
+
+## Kiwix
+
+**A Russian question reads `wikipedia_ru_all_maxi_2026-02` verbatim** through
+`kiwix.book_ru`. The RU→EN rewriter is the workaround for an English book and is
+skipped there. Kiwix catalog names come from the filename, not the `<name>`
+field.
+
+**Kiwix ranks by keyword overlap.** Never send it a whole sentence. `kiwix.Topic`
+drops the narrative request, the interrogative and a verb behind one.
+
+`kiwix.TitlePath` tries the exact article first, since a ZIM is addressable by
+title and a wrong title is a 404. `TitleCandidates` tries the spoken form and
+then the capitalized one. Both apply on the verbatim path alone. The rewriter
+already reduces a question, and reducing twice takes the topic off its input
+(V-668).
+
+## Which source answered
+
+**The claiming query source is readable on `/chat`** as a badge beside the
+reply. It is carried on `ipc.ChatReply.Source` and noted by `noteQuerySource` in
+`cmd/mavend/querysource.go`. It rides the context, so `handleText` keeps the one
+string signature the mic, telegram and the web share.