Audit fixes: 13 of 14 findings

COMPACTION.md

@@ -2,9 +2,19 @@
 
 Status: **SHIPPED (CLI), 2026-06-10.** Auto-compaction + manual `/compact` are
 live. memcode used to send the FULL append-only `ChatState.messages` every turn;
-now, at a safe turn boundary, when the estimated prompt exceeds the budget
-(`MEMCODE_COMPACT_BUDGET`, default ~45K; `off` disables), the older turns are
-summarized by Anthropic into a warm block and only the last ~8 turns stay raw.
+now, at a safe turn boundary, when the estimated prompt exceeds the budget, the
+older turns are summarized into a warm block and only the last ~8 turns stay raw.
+
+**The budget is window-RELATIVE, not a constant.** It is 85% of the serving
+model's learned input capacity, falling back to 80% of the catalog window before
+any turn has revealed it. The whole window minus headroom is the budget: context
+pressure (evictions, the cache busts and re-reads they cause) is the expensive
+failure, and resident tokens ride cheaply as cache reads.
+`MEMCODE_COMPACT_BUDGET` is an explicit override (`off` disables compaction) and
+`MEMCODE_CONTEXT_SOFT_CAP` lowers the ceiling for cost-capped setups; there is
+deliberately no built-in absolute clip. An earlier revision of this document
+named a ~45K default, which is exactly the kind of absolute constant the current
+design rejects.
 
 ## Where it lives (built)
 
@@ -14,7 +24,8 @@ summarized by Anthropic into a warm block and only the last ~8 turns stay raw.
   (`compaction_test.go`): facts-survive, adjacency-never-broken, boundary-only.
 - `internal/agent/runtime/compact.go` — orchestration: `compactBudget`,
   `compactIfNeeded` (auto, fired from `Submit` before the turn is assembled),
-  `Compact` (manual /compact), the Anthropic-forced summarizer call, the
+  `Compact` (manual /compact), the summarizer call (`compact` is a utility
+  purpose, so it rides the catalog's `utility_model` rather than the pin), the
   synthetic summary turn, telemetry + episodic-log write.
 - `compact` mode + `compactDoctrine` in `internal/doctrine/prompts.go` (the
   compactor prompt is composed client-side by the doctrine composer, like every
@@ -96,7 +107,9 @@ session still compacts to stay cheap and fast. Coarse is fine.
 
 ## Hard rules
 
-1. **Compactor model = Anthropic** (v1). A bad summary becomes the session's truth.
+1. **The compactor model is the catalog's `utility_model`.** A bad summary
+   becomes the session's truth, so this is one of the few calls that does not
+   ride the user's pin.
    (Later: the cheap lane may summarize low-risk tool output.)
 2. **Tool-use adjacency is sacred.** Never split an assistant tool_use from its
    tool_result. Only compact at a completed boundary (no pending tool call).

README.md

@@ -32,11 +32,11 @@ Run `memcode` in a repo and you get a full terminal coding agent.
 
 **It remembers.** Ask it to pick up where you left off last week and it can. It knows your repo's layout, what has been tried before, and the preferences you have corrected it on. Memory lives in `.memcode`, so it travels with the repo and your whole team benefits.
 
-**Pick a model or let it decide.** Out of the box it uses cheap models for routine work and strong models when the task is hard or risky. Pin any model with `/model` when you want control.
+**One model, and it stays put.** You pick the model your session runs on and nothing swaps it out mid-task. Change it any time with `/model`. Sub-agents and scouts can run on a cheaper model of your choosing, so the expensive one is spent where you decided it should be.
 
 **Reads the room.** When you are correcting it, it slows down, asks before acting, and stops cutting corners. When things are calm it stays out of your way.
 
-**Plan first when it matters.** `/plan` researches your codebase, drafts an approach, and gets a second model's review before you approve it. Execution then sticks to what you approved.
+**Plan first when it matters.** `/plan` researches your codebase and drafts an approach for you to approve, and execution then sticks to what you approved. Send the draft to a second model for review first when the stakes are worth it.
 
 **Work in parallel.** Hand off side quests to sub-agents and background jobs, keep working, and check on them with `/jobs` and `/tail`.
 
@@ -121,7 +121,7 @@ The user manual lives at [memcode.ai/docs](https://memcode.ai/docs):
 
 Internals and reference docs live in this repo:
 
-- [ROUTING.md](ROUTING.md): how Automatic mode picks models.
+- [ROUTING.md](ROUTING.md): how the session model is chosen, and what happens when a provider fails.
 - [HOOKS.md](HOOKS.md): the hook surface.
 - [COMPACTION.md](COMPACTION.md): context compaction.
 - [docs/gateway/README.md](docs/gateway/README.md): gateway operations and channel secrets.