From 95e74271530b01a4e1d6fcd142cc2661b96dc846 Mon Sep 17 00:00:00 2001
From: claude <no-reply@agents.claude.kvmx.ru>
Date: Tue, 11 Aug 2026 10:12:57 +0400
Subject: [PATCH 1/6] Ask for a token before spending the card (V-673)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

mavgpud reverse-proxied every path to llama-server with no authentication on
a LAN port. Any client on the network could submit model work, hold the model
resident by touching the idle clock, and read /slots, which returns the
prompts of whoever else was using the card.

It now reads a bearer token from token_file and requires it on every request,
/health included: /health reports whether the card is loaded and free, which
is what someone deciding to take it would ask. A listen address reachable
from the network with no token is a startup failure rather than a downgrade
to loopback. homesrv is the client and it is on the LAN, so a loopback
default would look safe and take the model arm down.

Beyond the token: an allowlist of the five paths Maven calls, so a leaked
token buys the model API and not llama-server's admin surface; a body cap and
an in-flight cap on the proxy; and header and idle timeouts on the server.
No read or write timeout — a completion on this card legitimately takes
minutes.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ESv8hqNPseYt1CnotZpqDz
---
 cmd/mavgpud/auth.go | 145 ++++++++++++++++++++++++++++++++++++++++++++
 cmd/mavgpud/main.go |  50 ++++++++++++++-
 deploy/mavgpud.json |   9 +++
 3 files changed, 201 insertions(+), 3 deletions(-)
 create mode 100644 cmd/mavgpud/auth.go

diff --git a/cmd/mavgpud/auth.go b/cmd/mavgpud/auth.go
new file mode 100644
index 0000000..fe2cfba
--- /dev/null
+++ b/cmd/mavgpud/auth.go
@@ -0,0 +1,145 @@
+package main
+
+import (
+	"crypto/sha256"
+	"crypto/subtle"
+	"fmt"
+	"net"
+	"net/http"
+	"os"
+	"strings"
+)
+
+// The boundary in front of the card.
+//
+// mavgpud has to listen on the LAN, because homesrv is the client and a
+// loopback default takes the model arm down. That makes this the one hop on the
+// workstation anything on the network could reach, and until 2026-08-11 it
+// reverse-proxied every path to llama-server unauthenticated: any client could
+// spend the card, hold the model resident by touching the idle clock, and read
+// /slots, which carries the prompts of whoever else was using it.
+//
+// So: a bearer token every request must carry, read from a file, and a path
+// allowlist so a token that leaks buys the model API and not the admin one. The
+// CW2 transcriber beside this daemon has worked this way since it shipped; this
+// is the same arrangement, not a new one.
+
+// readToken loads the bearer token. The file holds the token and nothing else,
+// trailing newline allowed. A path that is set and unreadable is fatal to the
+// caller: a supervisor that silently ran without its boundary is the failure
+// this exists to prevent.
+func readToken(path string) (string, error) {
+	b, err := os.ReadFile(path)
+	if err != nil {
+		return "", fmt.Errorf("token_file: %w", err)
+	}
+	tok := strings.TrimSpace(string(b))
+	if tok == "" {
+		return "", fmt.Errorf("token_file %s is empty", path)
+	}
+	return tok, nil
+}
+
+// loopbackListen reports whether addr can only be reached from this machine.
+// An empty or wildcard host is not loopback, which is the case that matters:
+// ":8080" is the shipped default and it answers the whole LAN.
+func loopbackListen(addr string) bool {
+	host, _, err := net.SplitHostPort(addr)
+	if err != nil {
+		host = addr
+	}
+	host = strings.Trim(host, "[]")
+	if host == "" {
+		return false
+	}
+	if host == "localhost" {
+		return true
+	}
+	ip := net.ParseIP(host)
+	return ip != nil && ip.IsLoopback()
+}
+
+// allowed is what a token buys. Everything llama-server exposes beyond this is
+// refused, because the endpoints Maven does not call are the expensive ones to
+// hand out: /slots returns other callers' prompts, and its save/restore actions
+// write files chosen by the request.
+//
+// Adding a caller means adding its path here. That is deliberate — the list is
+// short because Maven's use of the workstation is.
+var allowed = map[string]string{
+	"/v1/chat/completions": http.MethodPost,
+	"/v1/completions":      http.MethodPost,
+	"/v1/embeddings":       http.MethodPost,
+	"/v1/models":           http.MethodGet,
+	"/props":               http.MethodGet,
+}
+
+// requireToken authenticates, then bounds. Order matters: an unauthenticated
+// client must not be able to make this daemon allocate a body buffer.
+//
+// /health is not exempt. It reports whether the card is loaded and free, which
+// is exactly what someone deciding whether to take it from him would ask.
+func requireToken(token string, maxBody int64, next http.Handler) http.Handler {
+	want := sha256.Sum256([]byte(token))
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		got := sha256.Sum256([]byte(bearer(r)))
+		if subtle.ConstantTimeCompare(got[:], want[:]) != 1 {
+			w.Header().Set("WWW-Authenticate", "Bearer")
+			http.Error(w, "unauthorized", http.StatusUnauthorized)
+			return
+		}
+		r.Body = http.MaxBytesReader(w, r.Body, maxBody)
+		next.ServeHTTP(w, r)
+	})
+}
+
+// bearer pulls the credential out of the header. A malformed header yields the
+// empty string, which fails the comparison like any other wrong token — there
+// is no separate error for it, because telling a caller *how* it was wrong is
+// the only thing a probe learns from a 401.
+func bearer(r *http.Request) string {
+	h := r.Header.Get("Authorization")
+	const prefix = "Bearer "
+	if len(h) <= len(prefix) || !strings.EqualFold(h[:len(prefix)], prefix) {
+		return ""
+	}
+	return strings.TrimSpace(h[len(prefix):])
+}
+
+// allowlist refuses a path the model arm does not use. It answers 404 rather
+// than 403 so a scan cannot map llama-server's surface through this hop.
+func allowlist(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		method, ok := allowed[r.URL.Path]
+		if !ok {
+			http.NotFound(w, r)
+			return
+		}
+		if r.Method != method {
+			w.Header().Set("Allow", method)
+			http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
+			return
+		}
+		next.ServeHTTP(w, r)
+	})
+}
+
+// limitInflight caps concurrent proxied requests. A waiter leaves when its own
+// context ends, so a client that gave up does not keep a slot: llama-server
+// runs with -np 1 and queueing here is cheaper than queueing inside the child
+// with a body held in memory on both sides.
+func limitInflight(n int, next http.Handler) http.Handler {
+	if n <= 0 {
+		return next
+	}
+	slots := make(chan struct{}, n)
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		select {
+		case slots <- struct{}{}:
+			defer func() { <-slots }()
+			next.ServeHTTP(w, r)
+		case <-r.Context().Done():
+			http.Error(w, "client went away", http.StatusServiceUnavailable)
+		}
+	})
+}
diff --git a/cmd/mavgpud/main.go b/cmd/mavgpud/main.go
index d2cb76e..6e9c704 100644
--- a/cmd/mavgpud/main.go
+++ b/cmd/mavgpud/main.go
@@ -36,6 +36,21 @@ type config struct {
 	Listen    string `json:"listen"`     // what Maven talks to
 	LlamaAddr string `json:"llama_addr"` // where llama-server binds
 	LlamaBin  string `json:"llama_bin"`
+
+	// TokenFile holds the bearer token every request must carry. It is a path
+	// and never the token itself, the rule mavpoll, mavmaild and the CW2
+	// transcriber already follow: a secret in a committed config is a secret
+	// in the history. Empty is allowed only on a loopback Listen, and
+	// requireToken is where that is decided.
+	TokenFile string `json:"token_file,omitempty"`
+
+	// MaxBody bounds a proxied request body. A completion is a prompt, and a
+	// prompt that does not fit here would not fit the context window either.
+	MaxBody int64 `json:"max_body_bytes,omitempty"`
+	// MaxInflight bounds how many proxied requests reach llama-server at once.
+	// It runs with -np 1, so anything above a handful only queues inside the
+	// child while holding a connection and a body in memory here.
+	MaxInflight int `json:"max_inflight,omitempty"`
 	// LlamaArgs must include the flags that bind LlamaAddr. They are passed
 	// through untouched so the model, context size and layer count stay the
 	// owner's business and not this daemon's schema.
@@ -88,6 +103,8 @@ func defaults() config {
 		MinFreeVRAM: 15 << 30,
 		EvictAfter:  2,
 		StartAfter:  5,
+		MaxBody:     8 << 20,
+		MaxInflight: 4,
 	}
 }
 
@@ -123,6 +140,20 @@ func main() {
 		log.Fatal("mavgpud: llama_bin is required")
 	}
 
+	// A LAN listener with no token is refused rather than downgraded to
+	// loopback. Downgrading would look like a safe default and would take the
+	// model arm down instead: homesrv is the client and it is on the LAN.
+	var token string
+	if cfg.TokenFile != "" {
+		var err error
+		if token, err = readToken(cfg.TokenFile); err != nil {
+			log.Fatalf("mavgpud: %v", err)
+		}
+	} else if !loopbackListen(cfg.Listen) {
+		log.Fatalf("mavgpud: listen %s is reachable from the network and token_file is unset — "+
+			"set token_file, or listen on 127.0.0.1 and accept that Maven cannot reach it", cfg.Listen)
+	}
+
 	base := "http://" + cfg.LlamaAddr
 	run := newRunner("llama-server", cfg.LlamaBin, cfg.LlamaArgs, base+"/health")
 	sup := &supervisor{
@@ -145,7 +176,20 @@ func main() {
 	if err != nil {
 		log.Fatalf("mavgpud: llama_addr: %v", err)
 	}
-	srv := &http.Server{Addr: cfg.Listen, Handler: sup.handler(target)}
+	var h http.Handler = sup.handler(target)
+	if token != "" {
+		h = requireToken(token, cfg.MaxBody, h)
+	}
+	srv := &http.Server{
+		Addr:    cfg.Listen,
+		Handler: h,
+		// A slow-loris client holds a connection and a header buffer for free
+		// otherwise. No ReadTimeout or WriteTimeout: a completion legitimately
+		// takes minutes on this card, and either one would cut it off.
+		ReadHeaderTimeout: 10 * time.Second,
+		IdleTimeout:       60 * time.Second,
+		MaxHeaderBytes:    1 << 16,
+	}
 	go func() {
 		log.Printf("mavgpud: listening on %s, model %s", cfg.Listen, cfg.LlamaBin)
 		if err := srv.ListenAndServe(); err != nil && err != http.ErrServerClosed {
@@ -203,14 +247,14 @@ func (s *supervisor) handler(target *url.URL) http.Handler {
 		w.Header().Set("Content-Type", "application/json")
 		_, _ = w.Write([]byte(`{"status":"ok"}`))
 	})
-	mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
+	mux.Handle("/", allowlist(limitInflight(s.cfg.MaxInflight, http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		if !s.run.isReady() {
 			http.Error(w, "model not loaded", http.StatusServiceUnavailable)
 			return
 		}
 		s.touch()
 		proxy.ServeHTTP(w, r)
-	})
+	}))))
 	return mux
 }
 
diff --git a/deploy/mavgpud.json b/deploy/mavgpud.json
index 2738a5c..e4d272d 100644
--- a/deploy/mavgpud.json
+++ b/deploy/mavgpud.json
@@ -1,5 +1,14 @@
 {
   "listen": ":8080",
+  "//token_file": [
+    "The bearer token every request must carry. homesrv is the client and it",
+    "is on the LAN, so this port cannot be loopback and the token is what",
+    "stops anything else on the network spending the card or reading /slots.",
+    "A path, never the token: mavgpud refuses to start when listen is",
+    "reachable from the network and this is unset.",
+    "Same value as MAVEN_GPU_TOKEN in homesrv's deploy/telegram.env."
+  ],
+  "token_file": "/home/kami/.config/mavgpud.token",
   "llama_addr": "127.0.0.1:10000",
   "llama_bin": "llama-server",
   "//llama_args": [

From 1c13d2265bfb26fe92af5e6ebee66cafacabec3a Mon Sep 17 00:00:00 2001
From: claude <no-reply@agents.claude.kvmx.ru>
Date: Tue, 11 Aug 2026 10:13:10 +0400
Subject: [PATCH 2/6] Score the boundary against wrong credentials, not just
 right ones (V-673)

Every shape of wrong credential gets a case: no header, wrong token, a prefix
of the token, the token with no scheme, and Basic. Plus the two the allowlist
exists for, /slots and its save action, and the caps.

The readiness test now posts to /v1/chat/completions. The allowlist sits in
front of the readiness check and answers 405 to a method mavgpud never
serves, so the old GET measured the allowlist rather than the 503.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ESv8hqNPseYt1CnotZpqDz
---
 cmd/mavgpud/auth_test.go | 180 +++++++++++++++++++++++++++++++++++++++
 cmd/mavgpud/gpu_test.go  |   6 +-
 2 files changed, 184 insertions(+), 2 deletions(-)
 create mode 100644 cmd/mavgpud/auth_test.go

diff --git a/cmd/mavgpud/auth_test.go b/cmd/mavgpud/auth_test.go
new file mode 100644
index 0000000..830b0d4
--- /dev/null
+++ b/cmd/mavgpud/auth_test.go
@@ -0,0 +1,180 @@
+package main
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"strings"
+	"sync"
+	"testing"
+)
+
+// ok is what the boundary is protecting: anything that reaches it has spent
+// the card.
+func ok(w http.ResponseWriter, r *http.Request) { w.WriteHeader(http.StatusTeapot) }
+
+func TestRequireTokenRefusesEveryWrongCredential(t *testing.T) {
+	h := requireToken("s3cret", 1<<20, http.HandlerFunc(ok))
+	cases := []struct {
+		name string
+		auth string
+		want int
+	}{
+		{"no header", "", http.StatusUnauthorized},
+		{"wrong token", "Bearer wrong", http.StatusUnauthorized},
+		{"prefix of the token", "Bearer s3cre", http.StatusUnauthorized},
+		{"token with no scheme", "s3cret", http.StatusUnauthorized},
+		{"basic auth", "Basic czNjcmV0", http.StatusUnauthorized},
+		{"right token", "Bearer s3cret", http.StatusTeapot},
+		{"scheme is case-insensitive", "bearer s3cret", http.StatusTeapot},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			r := httptest.NewRequest(http.MethodGet, "/health", nil)
+			if tc.auth != "" {
+				r.Header.Set("Authorization", tc.auth)
+			}
+			w := httptest.NewRecorder()
+			h.ServeHTTP(w, r)
+			if w.Code != tc.want {
+				t.Errorf("status %d, want %d", w.Code, tc.want)
+			}
+		})
+	}
+}
+
+// The 401 must not say which part was wrong. A probe that can tell a malformed
+// header from a wrong token learns the header shape for free.
+func TestUnauthorizedSaysNothingUseful(t *testing.T) {
+	h := requireToken("s3cret", 1<<20, http.HandlerFunc(ok))
+	w := httptest.NewRecorder()
+	h.ServeHTTP(w, httptest.NewRequest(http.MethodGet, "/health", nil))
+	if got := strings.TrimSpace(w.Body.String()); got != "unauthorized" {
+		t.Errorf("body %q, want %q", got, "unauthorized")
+	}
+	if got := w.Header().Get("WWW-Authenticate"); got != "Bearer" {
+		t.Errorf("WWW-Authenticate %q, want Bearer", got)
+	}
+}
+
+// The body cap applies to an authenticated request. An unauthenticated one
+// never gets far enough to allocate anything.
+func TestRequireTokenCapsTheBody(t *testing.T) {
+	var read error
+	h := requireToken("t", 8, http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		buf := make([]byte, 64)
+		for read == nil {
+			if _, read = r.Body.Read(buf); read != nil {
+				break
+			}
+		}
+	}))
+	r := httptest.NewRequest(http.MethodPost, "/v1/chat/completions", strings.NewReader(strings.Repeat("x", 4096)))
+	r.Header.Set("Authorization", "Bearer t")
+	h.ServeHTTP(httptest.NewRecorder(), r)
+	if read == nil || !strings.Contains(read.Error(), "too large") {
+		t.Errorf("read error %v, want the body cap", read)
+	}
+}
+
+func TestAllowlistRefusesWhatMavenDoesNotCall(t *testing.T) {
+	h := allowlist(http.HandlerFunc(ok))
+	cases := []struct {
+		method, path string
+		want         int
+	}{
+		{http.MethodPost, "/v1/chat/completions", http.StatusTeapot},
+		{http.MethodGet, "/v1/models", http.StatusTeapot},
+		// /slots returns the prompts of whoever else is using the card, and
+		// its actions write files the request names.
+		{http.MethodGet, "/slots", http.StatusNotFound},
+		{http.MethodPost, "/slots/0?action=save", http.StatusNotFound},
+		{http.MethodGet, "/", http.StatusNotFound},
+		{http.MethodGet, "/v1/chat/completions", http.StatusMethodNotAllowed},
+	}
+	for _, tc := range cases {
+		t.Run(tc.method+" "+tc.path, func(t *testing.T) {
+			w := httptest.NewRecorder()
+			h.ServeHTTP(w, httptest.NewRequest(tc.method, tc.path, nil))
+			if w.Code != tc.want {
+				t.Errorf("status %d, want %d", w.Code, tc.want)
+			}
+		})
+	}
+}
+
+func TestLimitInflightCapsConcurrency(t *testing.T) {
+	const cap = 2
+	var mu sync.Mutex
+	now, peak := 0, 0
+	release := make(chan struct{})
+	h := limitInflight(cap, http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		mu.Lock()
+		now++
+		if now > peak {
+			peak = now
+		}
+		mu.Unlock()
+		<-release
+		mu.Lock()
+		now--
+		mu.Unlock()
+	}))
+
+	var wg sync.WaitGroup
+	for i := 0; i < 8; i++ {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			h.ServeHTTP(httptest.NewRecorder(), httptest.NewRequest(http.MethodPost, "/v1/chat/completions", nil))
+		}()
+	}
+	// Let the first wave arrive, then drain. The assertion is the peak, and a
+	// peak that never reached the cap still cannot exceed it.
+	close(release)
+	wg.Wait()
+	if peak > cap {
+		t.Errorf("%d requests in flight at once, cap is %d", peak, cap)
+	}
+}
+
+func TestLoopbackListen(t *testing.T) {
+	cases := map[string]bool{
+		":8080":              false, // the shipped default, and the whole LAN
+		"0.0.0.0:8080":       false,
+		"[::]:8080":          false,
+		"192.168.1.105:8080": false,
+		"127.0.0.1:8080":     true,
+		"[::1]:8080":         true,
+		"localhost:8080":     true,
+	}
+	for addr, want := range cases {
+		if got := loopbackListen(addr); got != want {
+			t.Errorf("loopbackListen(%q) = %v, want %v", addr, got, want)
+		}
+	}
+}
+
+func TestReadToken(t *testing.T) {
+	dir := t.TempDir()
+	good := filepath.Join(dir, "tok")
+	if err := os.WriteFile(good, []byte("  abc123\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	got, err := readToken(good)
+	if err != nil || got != "abc123" {
+		t.Errorf("readToken = %q, %v; want abc123", got, err)
+	}
+
+	blank := filepath.Join(dir, "blank")
+	if err := os.WriteFile(blank, []byte("\n\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := readToken(blank); err == nil {
+		t.Error("an empty token file is not a token")
+	}
+	if _, err := readToken(filepath.Join(dir, "absent")); err == nil {
+		t.Error("a missing token file is not a token")
+	}
+}
diff --git a/cmd/mavgpud/gpu_test.go b/cmd/mavgpud/gpu_test.go
index 52dc07d..8e0a8e8 100644
--- a/cmd/mavgpud/gpu_test.go
+++ b/cmd/mavgpud/gpu_test.go
@@ -104,9 +104,11 @@ func TestHealthAndProxyRefuseWhenNotReady(t *testing.T) {
 	s := &supervisor{run: newRunner("fake", "/bin/true", nil, "")}
 	h := s.handler(mustURL(t, "http://127.0.0.1:1"))
 
-	for _, path := range []string{"/health", "/v1/chat/completions"} {
+	// The completion is a POST because the allowlist is in front of the
+	// readiness check now, and it answers 405 to a method it never serves.
+	for path, method := range map[string]string{"/health": http.MethodGet, "/v1/chat/completions": http.MethodPost} {
 		w := httptest.NewRecorder()
-		h.ServeHTTP(w, httptest.NewRequest(http.MethodGet, path, nil))
+		h.ServeHTTP(w, httptest.NewRequest(method, path, nil))
 		if w.Code != http.StatusServiceUnavailable {
 			t.Errorf("%s with no model: got %d, want 503", path, w.Code)
 		}

From 5596cdddbcd1a96e44a35e3b05d1bc589b688812 Mon Sep 17 00:00:00 2001
From: claude <no-reply@agents.claude.kvmx.ru>
Date: Tue, 11 Aug 2026 10:13:10 +0400
Subject: [PATCH 3/6] Sign the completion and the probe with the same token
 (V-673)

llm.Client carries a bearer credential and sets it on the completion, and
Pair signs the /health probe with it too. An unsigned probe would answer 401,
Pair would read that as a card that is busy, and every workstation turn would
fall back to the resident model with nothing naming why.

The token comes from workstation.token, expanded from MAVEN_GPU_TOKEN like
every other secret in that file. Missing, and voicewire says so at startup:
the fallback is silent by design and this failure would otherwise be
invisible.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ESv8hqNPseYt1CnotZpqDz
---
 cmd/mavend/voicewire.go        |  7 ++++++-
 deploy/mavend.json             |  1 +
 deploy/telegram.env.example    |  9 +++++++++
 internal/config/workstation.go |  7 +++++++
 internal/llm/client.go         | 26 ++++++++++++++++++++++++++
 internal/llm/remote.go         |  3 +++
 internal/llm/remote_test.go    | 32 ++++++++++++++++++++++++++++++++
 7 files changed, 84 insertions(+), 1 deletion(-)

diff --git a/cmd/mavend/voicewire.go b/cmd/mavend/voicewire.go
index f3a2f7f..f476128 100644
--- a/cmd/mavend/voicewire.go
+++ b/cmd/mavend/voicewire.go
@@ -386,8 +386,13 @@ func modelSeam(cfg *config.Config, resident *llm.Client) (router.Completer, *llm
 		return resident, nil
 	}
 	ws := cfg.Workstation
+	remote := llm.New(ws.URL, time.Duration(ws.Timeout))
+	remote.SetToken(ws.Token)
+	if ws.Token == "" {
+		log.Printf("voice: no workstation.token — mavgpud refuses an unauthenticated request, so this reads as a card that is always busy")
+	}
 	pair := llm.NewPair(
-		llm.New(ws.URL, time.Duration(ws.Timeout)),
+		remote,
 		resident,
 		ws.Health,
 		time.Duration(ws.Probe),
diff --git a/deploy/mavend.json b/deploy/mavend.json
index aa0d95b..349d163 100644
--- a/deploy/mavend.json
+++ b/deploy/mavend.json
@@ -94,6 +94,7 @@
   ],
   "workstation": {
     "url": "http://192.168.1.105:8080",
+    "token": "${MAVEN_GPU_TOKEN}",
     "probe": "15s",
     "timeout": "90s",
     "stt": {
diff --git a/deploy/telegram.env.example b/deploy/telegram.env.example
index 8542bcf..3717da7 100644
--- a/deploy/telegram.env.example
+++ b/deploy/telegram.env.example
@@ -10,3 +10,12 @@ TELEGRAM_CHAT_ID=
 #   ntfy token add --expires=never maven
 # Read access is not needed — mavend publishes and never subscribes.
 NTFY_TOKEN=
+
+# Bearer token for mavgpud, the workstation's GPU supervisor (V-673). It fronts
+# the big model on a LAN port, so the token is the whole boundary in front of
+# the card. Any long random string; mint one with:
+#   openssl rand -hex 32
+# The same value goes in a file on workpc, named by token_file in
+# deploy/mavgpud.json. Unset here and every workstation turn falls back to the
+# resident model, because mavgpud answers 401 and Maven reads that as down.
+MAVEN_GPU_TOKEN=
diff --git a/internal/config/workstation.go b/internal/config/workstation.go
index 6fab688..6b34d2a 100644
--- a/internal/config/workstation.go
+++ b/internal/config/workstation.go
@@ -27,6 +27,13 @@ type WorkstationConfig struct {
 	// signal, so it must be the supervisor's endpoint and not llama-server's.
 	Health string `json:"health,omitempty"`
 
+	// Token — the bearer credential mavgpud requires, expanded from the
+	// environment like every other secret here. It is what stops anything on
+	// the LAN spending the card, so a URL that is not loopback needs one.
+	// Wrong or missing reads as a workstation that is down, and Maven falls
+	// back to the resident model.
+	Token string `json:"token,omitempty"`
+
 	// Probe — how often admission is re-checked. 0 ⇒ DefaultWorkstationProbe.
 	// Nothing on the hot path waits for it: the answer is cached and read
 	// atomically, so this only sets how late Maven notices the card came back.
diff --git a/internal/llm/client.go b/internal/llm/client.go
index 4d77ae6..bc93b36 100644
--- a/internal/llm/client.go
+++ b/internal/llm/client.go
@@ -51,6 +51,10 @@ type Client struct {
 	base string
 	swap SwapGate
 	http *http.Client
+	// token — the bearer credential for a server that asks for one. Empty for
+	// the resident model, which is reached over loopback on the same box.
+	// mavgpud on the workstation requires it: that hop is on the LAN.
+	token string
 
 	// gate / background — priority on the single llama-server slot. Set once
 	// at wiring time (SetGate), read on every request. nil gate ⇒ no gating,
@@ -101,6 +105,27 @@ func New(baseURL string, timeout time.Duration) *Client {
 	return &Client{base: baseURL, http: &http.Client{Timeout: timeout}}
 }
 
+// SetToken installs the bearer credential this client sends. Wiring-time, like
+// SetGate: an empty token means the server is not asking for one.
+func (c *Client) SetToken(t string) {
+	c.mu.Lock()
+	c.token = t
+	c.mu.Unlock()
+}
+
+// authorize adds the credential when there is one. Exported to the package so
+// the Pair prober signs /health with the same token as the completion — a
+// probe that answers 401 would otherwise read as a workstation that is down,
+// and Maven would fall back forever without saying why.
+func (c *Client) authorize(req *http.Request) {
+	c.mu.RLock()
+	t := c.token
+	c.mu.RUnlock()
+	if t != "" {
+		req.Header.Set("Authorization", "Bearer "+t)
+	}
+}
+
 // SetBaseURL re-points the client at another llama-server. Safe to call while
 // requests are in flight: a request that already read the old base finishes
 // against the old base (or fails, and every caller of Complete has a fallback),
@@ -196,6 +221,7 @@ func (c *Client) Complete(ctx context.Context, r Req) (string, error) {
 		return "", err
 	}
 	req.Header.Set("Content-Type", "application/json")
+	c.authorize(req)
 	httpResp, err := c.http.Do(req)
 	if err != nil {
 		return "", err
diff --git a/internal/llm/remote.go b/internal/llm/remote.go
index 30b1143..69b19ba 100644
--- a/internal/llm/remote.go
+++ b/internal/llm/remote.go
@@ -132,6 +132,9 @@ func (p *Pair) probe(ctx context.Context) {
 		p.set(false)
 		return
 	}
+	if p.remote != nil {
+		p.remote.authorize(req)
+	}
 	resp, err := p.http.Do(req)
 	if err != nil {
 		p.set(false)
diff --git a/internal/llm/remote_test.go b/internal/llm/remote_test.go
index 3169b42..787b627 100644
--- a/internal/llm/remote_test.go
+++ b/internal/llm/remote_test.go
@@ -250,3 +250,35 @@ func TestNoFloorIsAnError(t *testing.T) {
 		t.Fatalf("err = %v, want ErrNoFloor", err)
 	}
 }
+
+// The workstation is behind mavgpud, which requires a bearer token on the
+// completion and on /health alike. A probe that did not carry it would answer
+// 401, Pair would read that as a card that is busy, and every turn would fall
+// back to the resident model with nothing in the log naming why.
+func TestPairSignsTheProbeAndTheCompletion(t *testing.T) {
+	seen := make(chan string, 2)
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		seen <- r.Header.Get("Authorization")
+		if r.URL.Path == "/health" {
+			return
+		}
+		_, _ = w.Write([]byte(`{"choices":[{"message":{"content":"ok"}}]}`))
+	}))
+	defer srv.Close()
+
+	remote := New(srv.URL, time.Second)
+	remote.SetToken("s3cret")
+	p := NewPair(remote, New(srv.URL, time.Second), srv.URL+"/health", time.Hour)
+	p.probe(context.Background())
+	if !p.Available() {
+		t.Fatal("the probe did not admit an answering workstation")
+	}
+	if _, err := p.Complete(context.Background(), Req{User: "привет"}); err != nil {
+		t.Fatalf("complete: %v", err)
+	}
+	for i := 0; i < 2; i++ {
+		if got := <-seen; got != "Bearer s3cret" {
+			t.Errorf("request %d carried %q, want the bearer token", i, got)
+		}
+	}
+}

From 9bb342569bc4f3556279cd6ab080dcbf7741696b Mon Sep 17 00:00:00 2001
From: claude <no-reply@agents.claude.kvmx.ru>
Date: Tue, 11 Aug 2026 10:13:10 +0400
Subject: [PATCH 4/6] Write down why the GPU port cannot be loopback (V-673)

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ESv8hqNPseYt1CnotZpqDz
---
 docs/deployment.md |  2 +-
 docs/offload.md    | 13 +++++++++++++
 2 files changed, 14 insertions(+), 1 deletion(-)

diff --git a/docs/deployment.md b/docs/deployment.md
index daa6dd7..3b0ed05 100644
--- a/docs/deployment.md
+++ b/docs/deployment.md
@@ -102,7 +102,7 @@ Text-to-speech has not moved. piper on homesrv is the only synthesizer.
 | `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`. |
+| `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`. Its LAN port needs a bearer token in the file named by `token_file`, matching `MAVEN_GPU_TOKEN` on homesrv, or it refuses to start (V-673). |
 | `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
diff --git a/docs/offload.md b/docs/offload.md
index 922f709..f51fc1c 100644
--- a/docs/offload.md
+++ b/docs/offload.md
@@ -105,6 +105,19 @@ how we find out whether the blind spot is real.
 untouched. The model, the context size, the layer count and the MTP flags are the
 owner's business and not this daemon's schema.
 
+**The port carries a bearer token and cannot be loopback** (V-673). homesrv is
+the client, so this hop is on the LAN. Until 2026-08-11 anything on the network
+could spend the card, hold the model resident by touching the idle clock, and
+read `/slots`, which returns other callers' prompts. mavgpud now reads
+`token_file` and refuses to start when the listen address is reachable from the
+network without one. Downgrading to loopback instead would look safe and take
+the model arm down. Maven sends the same token from `workstation.token`, on the
+completion and on the `/health` probe alike. An unsigned probe answers 401,
+which Pair reads as a busy card, so a missing token degrades to the resident
+model rather than breaking a turn. The proxy also
+allowlists the five paths Maven calls, so a leaked token buys the model API and
+not llama-server's admin surface.
+
 **Every GPU service on that box belongs under this supervisor**, added to
 `cmd/mavgpud` rather than to systemd beside it. The rule was learned on
 2026-08-09. The CW2 transcriber ran as its own user unit and registered on the

From c0f4074a5df94ed96d0fe5cc0273ecdeb4da405f Mon Sep 17 00:00:00 2001
From: claude <no-reply@agents.claude.kvmx.ru>
Date: Tue, 11 Aug 2026 10:41:54 +0400
Subject: [PATCH 5/6] Give the audit's open findings a home and a trigger
 (V-674)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Nineteen of the twenty findings were open, and they lived in an untracked
audit.md at the repo root that no next session would have read. The one that
is closed, the unauthenticated mavgpud proxy, went out as V-673.

The report is now a frozen measurement under docs/evals/, dated and never
edited again — including when a finding it names gets fixed. The live state
moved to docs/caveats/, one entry per limit, each carrying its Vikunja id and
the condition that makes it worth fixing. A caveat with no revisit trigger is
a complaint, so every entry has one. Closing a limit deletes its entry rather
than editing the measurement that found it.

Two directory indexes come with it. docs/CLAUDE.md states the tier rule the
repo already followed by convention: living docs corrected in place, evals
frozen by date, caveats deleted when fixed. docs/caveats/CLAUDE.md indexes the
nineteen by claim and severity, because an index of filenames adds nothing a
directory listing does not.

Tasks V-675 through V-693 carry the plans. The doc line and the tracker now
join in both directions.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ESv8hqNPseYt1CnotZpqDz
---
 docs/CLAUDE.md                      |  30 ++++
 docs/caveats/CLAUDE.md              |  47 +++++
 docs/caveats/config.md              |  21 +++
 docs/caveats/dependencies.md        |  17 ++
 docs/caveats/external-inputs.md     |  20 +++
 docs/caveats/invariants.md          |  27 +++
 docs/caveats/layering.md            |  25 +++
 docs/caveats/security.md            |  26 +++
 docs/caveats/storage.md             |  30 ++++
 docs/caveats/transport.md           |  34 ++++
 docs/caveats/workers.md             |  23 +++
 docs/evals/2026-08-10-repo-audit.md | 261 ++++++++++++++++++++++++++++
 12 files changed, 561 insertions(+)
 create mode 100644 docs/CLAUDE.md
 create mode 100644 docs/caveats/CLAUDE.md
 create mode 100644 docs/caveats/config.md
 create mode 100644 docs/caveats/dependencies.md
 create mode 100644 docs/caveats/external-inputs.md
 create mode 100644 docs/caveats/invariants.md
 create mode 100644 docs/caveats/layering.md
 create mode 100644 docs/caveats/security.md
 create mode 100644 docs/caveats/storage.md
 create mode 100644 docs/caveats/transport.md
 create mode 100644 docs/caveats/workers.md
 create mode 100644 docs/evals/2026-08-10-repo-audit.md

diff --git a/docs/CLAUDE.md b/docs/CLAUDE.md
new file mode 100644
index 0000000..0113a06
--- /dev/null
+++ b/docs/CLAUDE.md
@@ -0,0 +1,30 @@
+# docs/
+
+Everything an agent needs that is not a rule and not code. `CLAUDE.md` at the
+root carries the rules and points here. Nothing here restates a rule.
+
+The tier is the path, so staleness is visible from the filename.
+
+| path | holds | lifetime |
+| --- | --- | --- |
+| `docs/*.md` | living. One file per subsystem: the reasoning, corrected in place. Each carries `Last verified: <date> @ <sha>`. | until it is wrong |
+| `docs/evals/` | dated measurements, one file per measurement. **Never edited after the day.** A newer number is a new file. | forever |
+| `docs/caveats/` | known limits, one entry per limit, each with a task id and a revisit trigger. Indexed in `docs/caveats/CLAUDE.md`. | until fixed, then deleted |
+| `docs/plans/` | the plan for one piece of work, frozen once it starts | until the work lands |
+| `docs/archive/` | dead. Read by nobody by default. | forever |
+
+## Rules for this directory
+
+* One fact, one home. A measurement is cited from a living doc, never copied
+  into it. The two drift the moment they are both edited.
+* A living doc is corrected in place and its `Last verified` line moves with the
+  correction. Do not append a changelog to it.
+* A number in prose with no `docs/evals/` file behind it is an opinion.
+* Fixing something deletes its caveat. It does not edit the eval that found it.
+
+## Where a subsystem's reasoning lives
+
+`routing.md`, `language.md`, `world.md`, `offload.md`, `deployment.md`,
+`ecosystem.md`, `workflow.md`, `design.md`, `rearchitecture.md`,
+`determinism.md`, `protocol.md`, `handler-wiring.md`, `operations.md`, `qa.md`.
+The root `CLAUDE.md` says which one to read before touching what.
diff --git a/docs/caveats/CLAUDE.md b/docs/caveats/CLAUDE.md
new file mode 100644
index 0000000..0046ea2
--- /dev/null
+++ b/docs/caveats/CLAUDE.md
@@ -0,0 +1,47 @@
+# docs/caveats/
+
+One entry per known limit: something broken, deferred or unsafe that a session
+will otherwise walk into. An entry names what fails, who it costs, and the
+condition that makes it worth fixing.
+
+Two things do not belong here. The evidence is a dated file under `docs/evals/`.
+The reasoning behind a subsystem is its living doc directly under `docs/`. A
+caveat is the pointer between them plus the trigger.
+
+## Rules for this directory
+
+* One file per area, one `##` section per limit, each carrying its task id.
+* **A caveat with no revisit trigger is a complaint.** Give it one or delete it.
+* Closing a limit deletes its entry. It does not edit it to say "fixed", and it
+  never edits the frozen measurement it came from. The durable record of a fix
+  is the commit and the subsystem's living doc.
+* An entry whose task is closed but whose limit is still live is the failure
+  mode to watch for. The id joins the two directions, so check both.
+
+## Index
+
+Every entry below came from the 2026-08-10 deep audit
+(`docs/evals/2026-08-10-repo-audit.md`). One of the twenty findings, the
+unauthenticated mavgpud proxy, was fixed as V-673 and has no entry.
+
+| limit | severity |
+| --- | --- |
+| [Go 1.25.5 and x/text 0.14.0 carry 20 reachable advisories](dependencies.md#toolchain) | high |
+| [Anyone past the proxy can enroll a passkey](security.md#enrollment) | high |
+| [Passkey credentials are rewritten in place](security.md#credentials) | medium |
+| [An empty STT transcript reads as a successful one](external-inputs.md#stt) | medium |
+| [Open-Meteo's empty body becomes 0°C](external-inputs.md#weather) | medium |
+| [Dialogue persistence errors are swallowed](storage.md#dialogue) | medium |
+| [The reminder transition is a lost update](storage.md#reminders) | medium |
+| [A recall miss scans two whole tables](storage.md#recall) | medium |
+| [Closing a TCP listener can strand Accept](transport.md#accept) | medium |
+| [PTT reads an unbounded body](transport.md#ptt) | medium |
+| [mavweb errors cannot be traced](transport.md#errors) | medium |
+| [Fact enrichment is a 20-call serial waterfall](workers.md#enrichment) | medium |
+| [A suppressed nudge is phrased anyway](workers.md#nudges) | medium |
+| [heads_path may equal model_path](invariants.md#heads) | medium |
+| [baselineGrammars is mirrored by hand](invariants.md#grammars) | medium |
+| [Committed absolute paths pin the build to this box](config.md#paths) | medium |
+| [The env example omits deployed variables](config.md#secrets) | medium |
+| [Domain packages depend on store and IPC types](layering.md#dtos) | low |
+| [Eleven symbols are unreachable](layering.md#deadcode) | low |
diff --git a/docs/caveats/config.md b/docs/caveats/config.md
new file mode 100644
index 0000000..41ccd5b
--- /dev/null
+++ b/docs/caveats/config.md
@@ -0,0 +1,21 @@
+# Configuration and environment
+
+## Committed absolute paths pin the build to this box [#690] {#paths}
+
+Costs: `go.mod` replaces Hexis with `/home/kami/apps/hexis`, `start-maven.sh`
+hardcodes the checkout and the data directory, and `deploy/mavgpud.json` holds
+workstation model and Python paths. Vendoring hides the `go.mod` problem for an
+ordinary build. `-mod=mod`, `go mod tidy` and a fresh checkout all fail.
+Revisit when: anyone clones this repo elsewhere, or a `tidy` is needed.
+Workaround: build only from this checkout, with the vendor directory.
+
+## The env example omits deployed variables [#691] {#secrets}
+
+Costs: a fresh deploy can lose remote speech-to-text or ambient authentication
+and run on fallback behaviour with an apparently valid config. Three variables
+are referenced and undocumented: `MAVEN_STT_TOKEN`, `MAVEN_AMBIENT_TOKEN` and
+`CW2_TOKEN`. V-673 added `MAVEN_GPU_TOKEN` to the example.
+It is not silent. The loader logs which variables were unset and says whatever
+they configure is off. What is missing is a startup failure.
+Revisit when: the box is redeployed from scratch, or a new secret is added.
+Workaround: read that log line at startup.
diff --git a/docs/caveats/dependencies.md b/docs/caveats/dependencies.md
new file mode 100644
index 0000000..7e161cb
--- /dev/null
+++ b/docs/caveats/dependencies.md
@@ -0,0 +1,17 @@
+# Dependencies
+
+## Go 1.25.5 and x/text 0.14.0 carry 20 reachable advisories [#682] {#toolchain}
+
+Costs: `govulncheck` found 20 reachable advisories, one in `x/text` and 19 in
+the standard library. They include template XSS, parser denial of service and
+TLS issues. Reachable traces run through the ONNX embedder's normalization,
+mavweb's HTML rendering, email header decoding and the mavgpud proxy. The
+vendored toolchain was built 2025-11-26.
+Revisit when: now. This is the highest-severity open entry and the fix is
+mechanical, so it ages badly for no reason.
+Workaround: none.
+
+None of `staticcheck`, `govulncheck` or `deadcode` is installed on this box or
+wired into a make target. `make audit` is a git-grep inventory over loc, todo,
+stubs, docs, tests and gaps. **Do not read it as a static-analysis gate.** That
+gate is part of this entry.
diff --git a/docs/caveats/external-inputs.md b/docs/caveats/external-inputs.md
new file mode 100644
index 0000000..1da6c33
--- /dev/null
+++ b/docs/caveats/external-inputs.md
@@ -0,0 +1,20 @@
+# External inputs
+
+What arrives from a service Maven does not run, and what happens when it
+arrives malformed. The shared shape: a JSON decode into value fields cannot
+tell "absent" from "zero", so a degraded response becomes a confident answer.
+
+## An empty STT transcript reads as a successful one [#675] {#stt}
+
+Costs: one dropped voice turn per malformed 200 from workpc. The mavsttd floor
+is never asked, because `stt.Pair` falls back on a non-nil error alone.
+Revisit when: CW2 returns a 200 with no text. Sooner if a proxy is put between
+homesrv and port 8081.
+Workaround: none. It is silent by design and the fallback is never spoken.
+
+## Open-Meteo's empty body becomes 0°C [#676] {#weather}
+
+Costs: he is told the weather is clear and 0°C when the service answered
+nothing. Distinct from V-589, which covered the HTTP status and not the body.
+Revisit when: a weather answer is reported as wrong, or the geocoder changes.
+Workaround: none.
diff --git a/docs/caveats/invariants.md b/docs/caveats/invariants.md
new file mode 100644
index 0000000..ebab2c6
--- /dev/null
+++ b/docs/caveats/invariants.md
@@ -0,0 +1,27 @@
+# Unguarded invariants
+
+`CLAUDE.md` names these as load-bearing. Nothing enforces either one. A rule
+that lives only in prose gets broken by whoever did not read the prose. Both of
+these fail silently when broken.
+
+`tokenizerRev` and `preRouteLadder` were checked and need nothing. The rev is
+baked into the embedder key, so a bump triggers re-embedding. A missing ladder
+rung is observable in the decision record.
+
+## heads_path may equal model_path [#692] {#heads}
+
+Costs: the routing heads then score with the same graph the resident e5-small
+uses, and recall degrades. There is no error and no log line, so it reads as
+ordinary drift rather than a misconfiguration.
+Revisit when: `deploy/mavend.json` is edited by hand, or a fine-tuned heads
+graph is swapped in.
+Workaround: check the two keys by eye. That is the whole guard today.
+
+## baselineGrammars is mirrored by hand [#693] {#grammars}
+
+Costs: the eval fixture restates the stage 0 rule set in the daemon's order,
+and its own comment says so. Three test files score against it. A grammar added
+to `buildRouter` alone means every routing measurement scores a set nobody
+runs. `CLAUDE.md` warns about this failure by name.
+Revisit when: the next stage 0 grammar is added. That is when it bites.
+Workaround: add to both lists, which is what the rule already says.
diff --git a/docs/caveats/layering.md b/docs/caveats/layering.md
new file mode 100644
index 0000000..effbad5
--- /dev/null
+++ b/docs/caveats/layering.md
@@ -0,0 +1,25 @@
+# Layering and dead surface
+
+Neither entry breaks anything today. Both make a later change cost more than it
+should, which is why they are low and not medium.
+
+## Domain packages depend on store and IPC types [#685] {#dtos}
+
+Costs: dialogue exposes `store.DialogueSessionRow` in its port, the pure
+morning planner takes a `store.Fact`, and auth policy imports IPC method and
+caller types. There is no Go import cycle. A schema change reaches further than
+it should.
+Revisit when: the dialogue or fact schema changes, or a second transport
+appears beside IPC.
+Workaround: none needed. It compiles and it is correct.
+
+## Eleven symbols are unreachable [#686] {#deadcode}
+
+Costs: extra API and test surface, and comments that claim callers which no
+longer exist. Three of the eleven must not be deleted. `HisGender` is a
+documented seam tied to V-399. `AudioDuration` duplicates `internal/audio` and
+should call it. `CountWord` is a one-line alias nobody uses and can go.
+Revisit when: `deadcode` is wired into the audit gate, which needs the
+allowlist this entry describes. **An unannotated list invites deleting the
+three above.**
+Workaround: none needed.
diff --git a/docs/caveats/security.md b/docs/caveats/security.md
new file mode 100644
index 0000000..8a6b65e
--- /dev/null
+++ b/docs/caveats/security.md
@@ -0,0 +1,26 @@
+# Security
+
+Both entries are mavweb's passkey seam. Assertion itself is sound and is not
+the problem: `userVerification` is required, and a sign count that does not
+increase is rejected.
+
+## Anyone past the proxy can enroll a passkey [#683] {#enrollment}
+
+Costs: registration is gated on nothing, so any client that reaches mavweb can
+enroll its own key and become him. Step-up is worse than per-client: one
+process-global `assertedAt` means every client inherits the same five-minute
+window after any successful assertion. The voice WebSocket accepts every
+origin, which makes cross-site use easier. V-317 covers which routes are gated
+and V-605 covers challenge-map growth. Neither covers this.
+Revisit when: mavweb is reachable from anything but the tunnel, and before any
+new credential is enrolled.
+Workaround: the reverse proxy is the only boundary today. That is the finding.
+
+## Passkey credentials are rewritten in place [#684] {#credentials}
+
+Costs: `os.WriteFile` over the live file. A crash, a full disk or an
+interrupted write corrupts every enrolled credential at once, and mavweb will
+not start afterwards.
+Revisit when: a second credential is enrolled, since the blast radius grows
+with the count. Sooner if the box loses power unexpectedly.
+Workaround: back the file up before enrolling.
diff --git a/docs/caveats/storage.md b/docs/caveats/storage.md
new file mode 100644
index 0000000..3f139dc
--- /dev/null
+++ b/docs/caveats/storage.md
@@ -0,0 +1,30 @@
+# Storage
+
+The DB seam: what it loses quietly, and what it reads more of than it needs.
+
+## Dialogue persistence errors are swallowed [#677] {#dialogue}
+
+Costs: restart continuity can vanish with nothing in the log, and a failed
+delete can bring stale conversation state back. Current-turn dialogue is
+unaffected, which is why this has never been noticed.
+Revisit when: a restart is reported as losing context. Sooner if a turn starts
+reading dialogue rows back to him.
+Workaround: none. The failure is invisible from outside.
+
+## The reminder transition is a lost update [#678] {#reminders}
+
+Costs: a concurrent fire and cancel both succeed and the last writer wins.
+Medium today because cancellation has no surface. High the moment V-622 adds
+one, and V-622 does not describe this invariant.
+Revisit when: V-622 starts, whichever comes first.
+Workaround: none, but the window is small while nothing can cancel.
+
+## A recall miss scans two whole tables [#681] {#recall}
+
+Costs: every missed recall reads all of `memory_vectors` and then decodes and
+sorts every note vector. Not an N+1, and the memory scan is cheap per losing
+row on purpose. The duplicated decode is the legacy notes path alone.
+Revisit when: the note count makes a miss measurably slow. Also when the two
+exclusion filters are proven to agree. `QueryNotes` uses `notHisWordsSQL` and
+`Search` uses `memory.NonRecallPrefix`. The fallback cannot go until they match.
+Workaround: none needed at today's row counts.
diff --git a/docs/caveats/transport.md b/docs/caveats/transport.md
new file mode 100644
index 0000000..449007e
--- /dev/null
+++ b/docs/caveats/transport.md
@@ -0,0 +1,34 @@
+# Transport
+
+The HTTP and socket seams. What a client can do to them, and what a shutdown
+can do to us.
+
+## Closing a TCP listener can strand Accept [#679] {#accept}
+
+Costs: during close, both `errc` and `done` are ready in `acceptLoop`'s select.
+Go picks uniformly. So roughly one close in two leaves a waiting `Accept`
+blocked forever on a TCP seam. Unix sockets are unaffected.
+Revisit when: a daemon is seen hanging on shutdown, or before any new TCP
+listener is added.
+Workaround: the process usually exits anyway, which hides it.
+
+## PTT reads an unbounded body [#688] {#ptt}
+
+Costs: `handlePTT` does an unlimited `io.ReadAll`, and mavweb sets no header or
+idle timeouts. A client can force unbounded allocation or hold a connection
+open. mavgpud's half of this was fixed in V-673.
+Revisit when: mavweb is reachable from anything but the tunnel.
+Workaround: mavweb is not LAN-exposed today.
+
+`/ws` rides along with this entry. It never calls `SetReadLimit`, so the
+dependency default of 32,768 bytes applies, about a second of audio. Nothing
+reaches it: the browser posts PCM to `/api/ptt`, and only `handlers_test.go`
+opens `/ws`. It gets a caller and a real limit, or it gets deleted.
+
+## mavweb errors cannot be traced [#689] {#errors}
+
+Costs: some handlers return the raw internal error, which discloses internals.
+Others return a generic one with no identifier, which cannot be joined to its
+log line. There is no request-id middleware to join them.
+Revisit when: a reported UI failure cannot be found in the log.
+Workaround: read the log by timestamp.
diff --git a/docs/caveats/workers.md b/docs/caveats/workers.md
new file mode 100644
index 0000000..ddaca75
--- /dev/null
+++ b/docs/caveats/workers.md
@@ -0,0 +1,23 @@
+# Background workers
+
+Both entries are a tick doing expensive work it did not need to do.
+
+## Fact enrichment is a 20-call serial waterfall [#680] {#enrichment}
+
+Costs: each fact is resolved in turn and each ecosystem call can spend ten
+seconds. A slow but reachable Nexus holds one tick for minutes, so the worker
+stops observing its configured interval. V-647 covered the duplicate queue
+scan, not this.
+Revisit when: Nexus gets slow, or when a batch-resolution endpoint exists.
+Workaround: an unreachable Nexus is fine. It is the slow-but-answering case
+that hurts.
+
+## A suppressed nudge is phrased anyway [#687] {#nudges}
+
+Costs: `PhraseNudge` runs before the dedupe is known. The `continue` meant to
+skip it is the last statement in the loop body. Every tick that
+keeps suppressing the same rule pays the resident model again. The comment
+above it claims the opposite.
+Revisit when: digestion ticks show up in the model's load, or when nudge rules
+grow past a handful.
+Workaround: none.
diff --git a/docs/evals/2026-08-10-repo-audit.md b/docs/evals/2026-08-10-repo-audit.md
new file mode 100644
index 0000000..e4e8788
--- /dev/null
+++ b/docs/evals/2026-08-10-repo-audit.md
@@ -0,0 +1,261 @@
+# Repository deep-audit report
+
+Date: 2026-08-10
+Revised: 2026-08-11, a verification pass over every cited line. Six claims were
+wrong as first written and are corrected in place. Two findings were added.
+
+Frozen 2026-08-11, V-674. A dated measurement is never edited after the day,
+and that holds for a finding which later gets fixed. The live state of each one
+sits in `docs/caveats/` with its task id. The fix sits in the subsystem's living
+doc under `docs/`. Read this file for the evidence, not for what is still true.
+
+Read-only audit complete. I found **20 issue-specific candidates not represented by a matching Vikunja task**: **3 High, 15 Medium, 2 Low**. No code or Vikunja tasks were changed.
+
+I compared all 366 tasks in Maven project 2. Existing items such as V-317, V-589, V-597, V-603, V-605, V-608, V-643 and V-647 were excluded except where a new finding is clearly separate.
+
+## 1. Unhandled edge cases and silent failures
+
+### Empty STT responses suppress the local fallback
+
+**A — Location:** `internal/stt/http.go:85` accepts `{}` as a successful transcript and returns empty text at line 89. `internal/stt/pair.go:143` only falls back when `err != nil`.
+
+**B — Severity:** Medium. A malformed `200 OK` from the workstation silently drops a voice turn instead of invoking `mavsttd`.
+
+**C — Proposed fix:** Require nonblank transcript text and a valid confidence range; treat missing required fields as an error so `Pair` falls back. Bound the response decoder and add `{}`, `{"text":""}`, oversized-body and invalid-confidence tests.
+
+### Open-Meteo can report invented zero-degree weather
+
+**A — Location:** `internal/weather/openmeteo.go:47` uses value fields, while line 95 accepts `{}` and line 100 interprets it as WMO 0 and 0°C.
+
+**B — Severity:** Medium. A valid JSON error/degraded response becomes plausible but false weather. This is separate from V-589, which covered HTTP status handling.
+
+**C — Proposed fix:** Make `current_weather` and its required members pointer/nullable fields, validate presence and ranges, and cap both forecast and geocoder bodies.
+
+### Dialogue persistence errors disappear completely
+
+**A — Location:** Corrupt rows are silently skipped at `internal/dialogue/session.go:127`; delete failures are discarded at line 191; marshal and save failures are swallowed at lines 201 and 209.
+
+**B — Severity:** Medium. Restart continuity can silently vanish, while failed deletes can resurrect stale conversation state.
+
+**C — Proposed fix:** Return or report persistence errors with session ID and operation; quarantine/delete corrupt rows; use bounded contexts instead of `context.Background()`. Keep current-turn availability, but expose the lost restart guarantee through logs/metrics.
+
+## 2. Concurrency and race conditions
+
+### Reminder state transition is a read-then-write lost update
+
+**A — Location:** `internal/store/reminders.go:172` reads `pending`, then line 182 updates without checking the old state.
+
+**B — Severity:** Medium now; High once V-622 adds cancellation surfaces. Concurrent fire/cancel operations can both succeed and the last writer wins. This invariant is not described in V-622.
+
+**C — Proposed fix:** Use one conditional statement: `UPDATE ... WHERE id=? AND status='pending'`; inspect `RowsAffected`, then distinguish not-found from invalid transition. Add simultaneous fired/cancelled tests under `-race`.
+
+### TCP listener shutdown can leave `Accept` blocked forever
+
+**A — Location:** `internal/netaddr/netaddr.go:180` waits only on `conns` and `errc`. During close, line 201 may select the already-closed `done` branch without publishing the listener error; `Close` at line 225 does not wake `Accept`.
+
+**B — Severity:** Medium. During close both `errc` and `done` are ready in `acceptLoop`'s select and Go picks uniformly, so roughly one close in two strands a waiting `Accept` forever on a TCP seam.
+
+**C — Proposed fix:** Add `case <-l.done: return nil, net.ErrClosed` to `Accept`, and make error/channel closure ownership explicit. Test an in-flight `Accept` concurrently with `Close`.
+
+## 3. Data fetching: waterfalls and duplicated scans
+
+### Fact enrichment performs a serial 20-call network waterfall
+
+**A — Location:** `cmd/mavend/factenrichment.go:160` resolves each fact sequentially; line 223 makes the Nexus call. Each request can consume ten seconds at `cmd/mavend/ecosystem.go:63`.
+
+**B — Severity:** Medium. A slow-but-reachable Nexus can hold one tick for roughly 20 × 10s, preventing the worker from observing its intended interval. V-647 only covered the duplicate queue scan.
+
+**C — Proposed fix:** Prefer a Nexus batch-resolution endpoint. Otherwise use bounded concurrency, such as four workers, while preserving per-fact backoff and the 20-attempt ceiling.
+
+### A recall miss scans two whole tables
+
+**A — Location:** The query source table runs embed, memory and notes in order at `cmd/mavend/actions_query.go:161` through line 164. `MemoryStore.Search` scans every row of `memory_vectors` at `internal/store/memory.go:82`; a miss then calls the legacy notes query at `cmd/mavend/actions_query.go:718`, which decodes every note vector at `internal/store/notes.go:63` and sorts the whole table at line 69.
+
+**B — Severity:** Medium at scale. This is not an N+1. It is two full scans per missed recall. The memory scan is already cheap per losing row on purpose, costing one dot product read off the stored bytes with no `[]float32` materialized, so the duplicated decode cost is the notes path alone. Both recall widths are tiny (`memoryRecallWidth` 3, `noteRecallWidth` 5), so the work is in the scan, not the result set. V-581 is a generic sweep of this file, but does not identify this issue.
+
+**C — Proposed fix:** Establish the invariant that every recallable note exists in `memory_vectors`, then remove the fallback. `internal/store/backfill.go` already rewrites note rows into the unified index, so the backfill exists; what is missing is proof that the two exclusion filters agree, since `QueryNotes` filters on `notHisWordsSQL` while `Search` filters on `memory.NonRecallPrefix`. Until they do, query only notes missing from the unified index and rank with the existing bounded top-K heap.
+
+## 4. Dependency health and version pinning
+
+### Reachable published vulnerabilities in the pinned toolchain and `x/text`
+
+**A — Location:** `go.mod:3` and `Makefile:7` pin Go 1.25.5; `go.mod:25` pins `x/text` 0.14.0. Reachable traces include normalization at `internal/router/onnxembedder.go:364`, HTML rendering at `cmd/mavweb/shell.go:154`, email header decoding at `internal/email/message.go:244`, and reverse proxying at `cmd/mavgpud/main.go:212`.
+
+**B — Severity:** High. `govulncheck` found **20 reachable advisories**: one in `x/text` and 19 in the Go standard library, including template XSS, parser complexity/DoS and TLS issues. The official database says `x/text` before 0.39.0 can loop on invalid UTF-8; Go 1.25.12 contains the accumulated security corrections. See [GO-2026-5970](https://pkg.go.dev/vuln/GO-2026-5970), [GO-2026-4980](https://pkg.go.dev/vuln/GO-2026-4980), and the [Go release history](https://go.dev/doc/devel/release#go1.25.0).
+
+**C — Proposed fix:** Upgrade the vendored toolchain to at least 1.25.12, preferably current 1.26.5 after compatibility testing; upgrade `x/text` to at least 0.39.0/current 0.40.0; tidy and re-vendor. Add `govulncheck ./...` to the repository gate.
+
+No dependency was three major versions behind. The remaining direct updates were minor/patch releases. `.opencode`'s `npm audit` reported zero vulnerabilities and no peer conflicts.
+
+## 5. Security exposure
+
+### WebAuthn enrollment is open and step-up state is process-global
+
+**A — Location:** Registration endpoints have no existing-credential or bootstrap authorization at `cmd/mavweb/webauthn.go:92` and line 103. `RegisterBegin` also answers GET, while `RegisterFinish` requires POST. A single server-wide session is created at `cmd/mavweb/main.go:170`, backed by one `assertedAt` timestamp at `internal/webauthn/session.go:20`. The voice WebSocket accepts every origin at `cmd/mavweb/voiceproxy.go:48`.
+
+**B — Severity:** High, and scoped to enrollment and session binding. Assertion itself is sound. `internal/webauthn/webauthn.go:221` requests `userVerification: "required"`, and line 304 rejects a sign count that did not increase. What is broken is that any client past the reverse proxy can enroll its own key, and that after any successful assertion every client inherits the same five-minute step-up window. The wildcard WebSocket origin makes cross-site use easier. V-317 covers which routes are gated, and V-605 covers challenge-map growth, not enrollment or session binding.
+
+**C — Proposed fix:** Permit first enrollment only through a local/one-time bootstrap ceremony; require an already-authenticated credential for subsequent enrollment. Bind step-up to a signed, HttpOnly, SameSite browser session and exact RP origin. Restrict WebSocket origins and add CSRF/origin validation to mutating routes.
+
+### `mavgpud` exposes an unauthenticated GPU/model proxy on the LAN
+
+**Closed 2026-08-11, V-673.** The reasoning now lives in `docs/offload.md`,
+beside the rest of the workstation seam, and `docs/deployment.md` carries the
+operational line in the daemon table. This block is a pointer, not a second
+home: read those, not this.
+
+- Boundary and limits: `cmd/mavgpud/auth.go`, wired in `cmd/mavgpud/main.go`.
+- Client half: `internal/llm/client.go`, `internal/llm/remote.go`,
+  `internal/config/workstation.go`, `cmd/mavend/voicewire.go`.
+- Deploy: `token_file` in `deploy/mavgpud.json`, `MAVEN_GPU_TOKEN` in
+  `deploy/telegram.env.example`.
+- Commits: `95e7427`, `1c13d22`, `5596cdd`, `9bb3425`.
+
+**Deploy step, not yet done:** write the token to
+`/home/kami/.config/mavgpud.token` on workpc and put the same value in
+`MAVEN_GPU_TOKEN` on homesrv, before restarting either side. mavgpud refuses to
+start without it, and a homesrv missing it falls back to the resident model.
+
+### Passkey credential persistence is not crash-atomic
+
+**A — Location:** `cmd/mavweb/credentials.go:36` serializes the full credential map and overwrites the live file directly with `os.WriteFile` at line 41.
+
+**B — Severity:** Medium. A crash, disk-full event or interrupted write can corrupt every enrolled credential and prevent mavweb from starting.
+
+**C — Proposed fix:** Write a `0600` temporary file in the same directory, `fsync`, rename atomically, then sync the directory. Preserve the last known-good file and test simulated write failures.
+
+No new tracked hardcoded keys, raw user-concatenated SQL, `eval`, or shell execution of untrusted strings were found. The historical DB-key exposure is already covered by V-12.
+
+## 6. Circular dependencies and layering
+
+### Domain packages depend directly on storage/wire DTOs
+
+**A — Location:** Dialogue imports `store` and exposes `store.DialogueSessionRow` in its port at `internal/dialogue/session.go:9` and line 75. The pure morning planner accepts `store.Fact` at `internal/morning/plan.go:72`. Auth policy imports IPC method and caller types at `internal/auth/policy.go:8` and `internal/auth/scope.go:33`.
+
+**B — Severity:** Low. There is no current Go import cycle, but domain changes are coupled to database and IPC schema changes.
+
+**C — Proposed fix:** Make domain packages own their DTOs and ports—dialogue persistence records, morning evidence, auth operation/caller identity—and adapt them in store/IPC/cmd wiring.
+
+No circular Go imports were found; compilation and `go vet` both succeeded.
+
+## 7. Dead code and zombie endpoints
+
+### Eleven production symbols are unreachable
+
+**A — Location:** `deadcode` found:
+
+- `cmd/mavwaked/vad.go:244` — `PCMToF32`
+- `cmd/mavwaked/vad.go:265` — `AudioDuration`
+- `internal/crawl/watch.go:86` — `Watcher.Watches`
+- `internal/phraser/confirm.go:137` — `IsC`
+- `internal/phraser/plural.go:13` — `CountWord`
+- `internal/phraser/eval/checks.go:80` — `HisGender`
+- `internal/update/update.go:363` — `WithClock`
+- `internal/voice/errors.go:72` — `jsonMarshal`
+- `internal/voice/errors.go:73` — `jsonUnmarshal`
+- `internal/webauthn/cbor.go:98` — `cborValue.At`
+- `internal/worker/server.go:64` — `Server.SetSynthesizer`
+
+Three of the eleven do not want deleting, and the 2026-08-11 pass checked each:
+
+- `internal/phraser/eval/checks.go:80` `HisGender` is deliberately exposed and deliberately uncalled. The comment at line 72 ties the trio to V-399, and `cmd/mavend/personaguard.go:94` states why this one is not run on a phrased message. Deleting it removes a documented seam.
+- `cmd/mavwaked/vad.go:265` `AudioDuration` duplicates what `internal/audio` already computes. Call that instead of deleting the body.
+- `internal/phraser/plural.go:13` `CountWord` is a one-line alias for `say.CountWord`, and every real caller already uses `say` directly. Safe to delete outright.
+
+**B — Severity:** Low. They increase API and test surface, and some comments claim callers that no longer exist.
+
+**C — Proposed fix:** Delete the genuinely obsolete symbols. Where one is an intended extension seam, add the actual caller and a contract test, or record why it stays. Add `deadcode ./...` with an explicit allowlist to the audit gate, since an unannotated list invites deleting the three above.
+
+The repository history begins on 2026-07-03, so a six-month rotten-feature-flag check is not yet applicable. One zombie HTTP route does exist: `/ws` is wired at `cmd/mavweb/main.go:235` and no shipped client reaches it, since the browser posts to `/api/ptt`. Section 8 carries the detail.
+
+## 8. Performance hot paths and memory/resource leaks
+
+### Digest dedupe happens after paying the LLM cost
+
+**A — Location:** `cmd/mavend/tick_digest.go:147` calls `PhraseNudge` before `EnqueueDigestEntry` reports the dedupe at line 153. The `else if deduped { continue }` is the last statement in the loop body, so it changes nothing.
+
+**B — Severity:** Medium. Every tick that continues suppressing the same rule can invoke the model again, contrary to the cache claim in the preceding comment.
+
+**C — Proposed fix:** Check for a live pending entry by stable rule/candidate fingerprint before phrasing, or persist/cache the phrased result with a TTL. Add a test asserting one phraser call across repeated suppressed ticks.
+
+### PTT reads an unbounded body and neither server sets header or idle limits
+
+**A — Location:** `handlePTT` performs an unlimited `io.ReadAll` at `cmd/mavweb/voiceproxy.go:125`. Mavweb and mavgpud construct servers without header or idle limits at `cmd/mavweb/main.go:242` and `cmd/mavgpud/main.go:148`. Separately, `handleWS` never calls `conn.SetReadLimit`, so the dependency default of 32,768 bytes applies at `vendor/github.com/coder/websocket/read.go:92`, about one second of 16kHz mono PCM.
+
+**B — Severity:** Medium for the HTTP side. A client can force unbounded body allocation or hold a connection open indefinitely. Low for the WebSocket read limit, because `/ws` has no caller: the browser client posts PCM to `/api/ptt` at `cmd/mavweb/static/app.js:114`, and `/ws` is wired at `cmd/mavweb/main.go:235` but reached only from `handlers_test.go`. The 64MiB `maxFrame` at `cmd/mavweb/voiceproxy.go:27` is not an unapplied declaration. It caps the mavend voice wire at line 194 and line 212, which is the "either direction" its comment names.
+
+**C — Proposed fix:** Use `http.MaxBytesReader` for PTT and return 413 on overflow. Configure `ReadHeaderTimeout`, `IdleTimeout` and header limits on both servers. Decide `/ws` separately: either give it an audio-duration read limit and a client, or delete it. See section 7.
+
+## 9. Error propagation and user feedback
+
+### Mavweb has no consistent, traceable error contract
+
+**A — Location:** Some handlers expose raw internal errors, such as `cmd/mavweb/tools.go:57`, `cmd/mavweb/routines.go:58` and `cmd/mavweb/webauthn.go:122`. Others return generic errors without a request/incident identifier, such as `cmd/mavweb/facts.go:90`. No HTTP request-ID middleware was found.
+
+**B — Severity:** Medium. Raw errors can disclose implementation details, while generic errors cannot be correlated with the correct log entry.
+
+**C — Proposed fix:** Add a central `writeProblem`/error-page helper with a stable error code and generated request ID; log the full wrapped error server-side and return only a sanitized message plus the ID. Carry the ID into IPC/ecosystem correlation where possible.
+
+## 10. Configuration drift and environment assumptions
+
+### Committed absolute paths make builds and deployment host-specific
+
+**A — Location:** `go.mod:31` replaces Hexis with `/home/kami/apps/hexis`. `start-maven.sh:11` hardcodes the Maven checkout and line 40 hardcodes the data directory. `deploy/mavgpud.json:12` and line 35 contain workstation-specific model/Python paths.
+
+**B — Severity:** Medium. Vendoring masks the `go.mod` problem for ordinary builds, but `-mod=mod`, tidy and fresh non-Kami checkouts fail. Deployment files cannot be reused safely on another host.
+
+**C — Proposed fix:** Pin a real Hexis module revision; keep local replacement in an uncommitted `go.work`. Derive script root from the script location and make data paths configurable. Split mavgpud into a committed template plus host-local override.
+
+### Environment examples do not cover deployed variables
+
+**A — Location:** Active config references `MAVEN_STT_TOKEN` at `deploy/mavend.json:101`, Compose references `MAVEN_AMBIENT_TOKEN` at `docker-compose.yml:109`, and the GPU service expects `CW2_TOKEN` at `deploy/mavgpud.service:15`. `deploy/telegram.env.example:5` documents only Telegram and ntfy. The loader deliberately converts missing variables to empty settings at `internal/config/config.go:333`.
+
+**B — Severity:** Medium. A fresh deployment can lose remote STT or ambient authentication and run on fallback behavior despite apparently valid config. It is not silent: `internal/config/config.go:340` logs which variables were unset and states that whatever they configure is off. What is missing is a startup failure and an example file naming them.
+
+**C — Proposed fix:** Maintain one canonical secret manifest/example covering every referenced variable, or service-specific examples with validation. Fail startup when an enabled integration lacks its required secret; permit empty variables only for explicitly disabled blocks.
+
+No production/staging debug-mode or mock-gateway drift was found.
+
+## 11. Declared invariants with no guard
+
+`CLAUDE.md` names several rules as load-bearing. Two of them are enforced by
+nothing, which the first pass missed because it audited generic categories only.
+
+### `heads_path` may equal `model_path` and nothing objects
+
+**A — Location:** `cmd/mavend/voicewire.go:168` reads `cfg.Voice.Embedder.HeadsPath` and loads it without comparing it to the model path. The rule is stated at `internal/config/voice.go:41`, which says the heads graph is a fine-tuned COPY, and again in `CLAUDE.md`.
+
+**B — Severity:** Medium. Pointing both keys at the same file degrades recall, because the routing heads then score with the same graph the resident e5-small uses. There is no error and no log line, so the failure looks like ordinary recall drift.
+
+**C — Proposed fix:** Reject the config at load when `heads_path` equals `model_path` after path cleaning. A daemon that cannot route well should refuse to start rather than answer worse.
+
+### `baselineGrammars` mirrors `buildRouter` by hand
+
+**A — Location:** `internal/router/eval/eval_test.go:263` restates the stage 0 rule set in the daemon's order, and its own comment says so. `claims_test.go:30`, `heads_test.go:76` and `eval_test.go:221` all score against it. Nothing compares the two lists.
+
+**B — Severity:** Medium. A grammar added to `buildRouter` and not to the fixture means every routing measurement scores a set nobody runs, which is the failure mode `CLAUDE.md` warns about by name.
+
+**C — Proposed fix:** Export the grammar set from one place and have both `buildRouter` and the fixture consume it, or add a test that diffs the two by grammar name and fails on drift.
+
+`tokenizerRev` and `preRouteLadder` were checked and need nothing.
+`internal/router/onnxembedder.go:91` bakes the rev into the embedder key, so a
+bump changes the key and triggers re-embedding. `cmd/mavend/voice.go:278` passes
+`preRouteLadder` to `decision.Expect`, so a missing rung is observable.
+
+## Cross-cutting subsystem candidates
+
+The recurring findings suggest five reusable patterns:
+
+- A bounded, required-field-validating JSON client for STT, weather, ecosystem and model calls.
+- Authenticated remote-service middleware providing token checks, body limits, concurrency limits and correlation IDs.
+- Atomic state-transition helpers using conditional SQL and `RowsAffected`.
+- A uniform HTTP problem/error envelope.
+- A repository health gate combining `staticcheck`, `govulncheck`, `deadcode` and dependency audits.
+
+## Validation
+
+- `make fmt-check` and `make vet` passed. `make audit` passed too, but it is a git-grep inventory over loc, todo, stubs, docs, tests and gaps (`scripts/audit.sh`), not a static-analysis gate. Do not read it as one.
+- `staticcheck`, `govulncheck`, `deadcode`, tracked-secret and history scans and npm audit were run out of tree. None of the three Go analyzers is installed on this box or wired into any make target, which is the argument for section 4's proposed gate.
+- The advisory version numbers in section 4 could not be re-checked offline on 2026-08-11. `deps/go/go/VERSION` reads `go1.25.5`, built 2025-11-26, so the eight-month gap behind current supports the upgrade claim.
+- The first whole-tree race run failed once in `cmd/mavend` while analyzers were compiling concurrently; a fresh isolated `go test -race -count=1 ./cmd/mavend` passed in 100.6 seconds, so the transient result was not counted as a defect.
+- The pre-existing `deploy/mavwaked.service` modification and untracked `deploy/asoundrc` remained untouched.

From d1b851923923e66c54f5ce903a73b8bd15c14fdc Mon Sep 17 00:00:00 2001
From: claude <no-reply@agents.claude.kvmx.ru>
Date: Tue, 11 Aug 2026 10:43:06 +0400
Subject: [PATCH 6/6] Point the root file at the two new indexes (V-674)

A file nobody can find is dead weight, and the pointer table is the only
place anyone looks.

The 600-line diff budget blocked this two-line edit. Kami raised it for the
branch rather than splitting: 250 of the 621 lines are the audit report moved
into docs/evals/ verbatim, which is a copy of an untracked file and not new
writing.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ESv8hqNPseYt1CnotZpqDz
---
 CLAUDE.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/CLAUDE.md b/CLAUDE.md
index 78b0890..fcc52ad 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -17,6 +17,8 @@ under `docs/`. Read that doc before changing the subsystem.
 | `docs/ecosystem.md` | touching Nexus, Praxis or Hexis |
 | `docs/rearchitecture.md`, `docs/design.md` | changing the shape of anything |
 | `docs/workflow.md` | the five stores, the doc tiers, the guards |
+| `docs/caveats/` | a known limit, its task id and its revisit trigger |
+| `docs/CLAUDE.md` | which tier a doc belongs in, and what each one holds |
 | `AGENTS.md` | local preview, screenshots, model downloads |
 
 ## What Maven is