Merge pull request 'docs: correct FreeBSD cost mode skill details (Sam & Codex)' (#3) from fix/freebsd-cost-skill-accuracy into main

Reviewed-on: #3

skills/freebsd/freebsd-cost-optimization.md

@@ -17,18 +17,22 @@ Colibri supports three cost modes that control context window usage:
 
 ## When to escalate
 
-The daemon auto-escalates fast→smart→max when compaction alone cannot keep the
-session within budget. This is intent, not a policy engine — the thresholds are
-fixed in `colibri-daemon/src/cost.rs`:
+The daemon auto-escalates fast→smart→max when the current session budget is
+exceeded or compaction cannot free enough space. This is intent, not a policy
+engine — the thresholds are fixed in `colibri-daemon/src/cost.rs`:
 
-- fast: budget 4K tokens, compact at 80%
-- smart: budget 16K tokens, compact at 75%
-- max: budget 64K tokens, compact at 90%
+| Mode  | Session budget  | Uncompacted turns | Tool result limit |
+| ----- | --------------- | ----------------- | ----------------- |
+| fast  | 500,000 bytes   | 5                 | 4,000 bytes       |
+| smart | 2,000,000 bytes | 20                | 16,000 bytes      |
+| max   | 8,000,000 bytes | 100               | unlimited         |
 
 ## Operator tips
 
-- Set `COLIBRI_COST_MODE=fast` in `/etc/rc.conf` for disposable worker agents.
-- Use `colibri set-cost-mode smart` via the CLI for interactive sessions.
-- Monitor cache-hit rate via `colibri status` — if it drops below 50%,
-  consider escalating to the next mode.
+- Set `colibri_cost_mode="fast"` in `/etc/rc.conf` for disposable worker agents;
+  the FreeBSD rc.d script exports it as `COLIBRI_COST_MODE`.
+- Use the MCP write-gated `colibri_set_cost_mode` tool, or the daemon socket
+  `{"cmd":"set-cost-mode","mode":"smart"}`, for runtime intent changes.
+- Treat runtime `set-cost-mode` as acknowledgement-only until persistent live
+  config mutation is designed; verify the active mode with `colibri status`.
 - On FreeBSD live USB, the default is `smart` to balance cost and capability.