Against a self-hosted Honcho 3.0.11 every read path came back empty while
the server was healthy and full of derived facts: the plugin parsed a
`conclusions`/`summary` shape the API no longer emits.
- honcho-client: typed models for the real schema — `PeerContext`
(`representation` markdown + `peer_card`), `SessionContext` (`summary` as
an object, `peer_representation`), wrapped `PeerCard` (a bare array on PUT
is a 422, which also broke `honcho_profile` writes).
- plugin: the turn-time injection and `honcho_context` read the
representation; `honcho_search` and the page's /search now use
`conclusions/query` (observer/observed scoping inside `filters`) — a real
ranked semantic search with fact ids, which `peer_context?search_query`
never provided; /overview returns card + representation + conclusions.
- compose: pin the Honcho image by digest (3.0.11) — ghcr publishes no v3
semver tags, and an untracked `:latest` pull is what drifted the schema.
- tests: fixture tests from payloads captured on the live server, plus an
env-gated live smoke test (HONCHO_E2E_URL/_WS/_PEER, `cargo test
-p honcho-client -- --ignored`) — run it before any future Honcho bump.
The opt-in page gains a debug panel, once the user's saved flag is on:
service status (reachability, latency, the caller's own processing
queue, with the specific Honcho error when something is wrong), a full
overview (peer card, derived facts with ids, summary) and one text
field with two actions — search (raw ranked facts) and ask (Honcho's
server-side LLM answers), plus an in-page mini-guide.
Every endpoint gates on the per-user opt-in server-side, fail closed,
and derives the peer from the authenticated Caller — never from the
request body — since the workspace is shared. Honcho 404s are
translated per-endpoint as 'no memory yet' rather than failures.
CLAUDE.md had grown to 152 KB (~21k words, ~40k tokens) and is loaded into
every coding-agent session. The cost is not the cache read, it is attention:
the rules that are genuinely invariant were drowning in the mechanics of
subsystems that most tasks never touch.
The split criterion is blast radius, not importance. A rule a change anywhere
could violate stays in CLAUDE.md — the commit rule, the production/schema
constraint, domain neutrality, the event-bus rule, the crate boundaries, and
the module map. The mechanism of one subsystem moves to dev-docs/, opened on
entry to that subsystem via a routing table at the top of CLAUDE.md.
Nothing was rewritten: every section was moved verbatim by line range and
verified line-by-line against the original. The only edits are cross-reference
repairs ("see the DB section" -> a link), the promotion of headings in the
extracted files, and a condensed "Current state" whose full text now lives in
dev-docs/users-auth-and-boot.md.
CLAUDE.md: 152 KB -> 31 KB. Twelve subsystem files plus an index under
dev-docs/, which now carries the same standing rule as docs/ and CHANGELOG.md:
a change to a subsystem updates its dev-doc in the same change.
No CHANGELOG entry: this is documentation for coding agents with no observable
effect on the application.