diff --git a/config.lua b/config.lua
index 724468b..cc3c08b 100644
--- a/config.lua
+++ b/config.lua
@@ -264,4 +264,24 @@ return {
     -- Requires the external `tree-sitter` CLI plus configured parser-
     -- directories with cloned + built `tree-sitter-<lang>` grammars
     -- (see `:highlight on` for the install hints).
+
+    -- Phase 7 (docs/PHASE7.md): cost / usage observability. broker.lua
+    -- captures `usage` (+ `cost` for cloud) from every chat/chat_stream
+    -- call and routes via ctx:add_usage to a per-session accumulator.
+    -- `:cost` / `:cost detail` / `:cost reset` surface the totals.
+    -- The `cost` block below configures OPTIONAL warn thresholds —
+    -- a single status line fires the first time the cumulative
+    -- crosses each threshold. Default off. Useful when paid cloud
+    -- presets are in play so runaway-cost sessions get a nudge.
+    --
+    -- cost = {
+    --     warn_at_dollars = 0.50,    -- one-shot warn when cumulative cost crosses
+    --     warn_at_tokens  = 100000,  -- one-shot warn when cumulative tokens crosses
+    -- },
+    --
+    -- Both flags are independent (R4 — first-to-fire doesn't suppress
+    -- the other); `:cost reset` re-arms both. Per-turn usage is also
+    -- written to session/*.jsonl (assistant-turn `usage` field) for
+    -- after-the-fact scripting; cross-session aggregation deferred
+    -- to a future phase (Q-C2).
 }
diff --git a/docs/PHASE7.md b/docs/PHASE7.md
index 0c3d5d1..d01b208 100644
--- a/docs/PHASE7.md
+++ b/docs/PHASE7.md
@@ -2,7 +2,7 @@
 
 **Project:** aish — AI-augmented conversational shell
 **Document:** Phase 7 Requirements, Architecture & Design Decisions
-**Status:** Plan + review fold-in (tree at `0f14dc1`)
+**Status:** Implement (6 commits landed: 7364963, 7b4a9be, 8adebd5, b30212a, 0d6ff93, this)
 **Date:** 2026-05-16
 
 **Review findings (independent Sonnet agent, 2026-05-16) — 3 BLOCKERs