diff --git a/docs/cost.md b/docs/cost.md
index 4cad43b..475f2cc 100644
--- a/docs/cost.md
+++ b/docs/cost.md
@@ -50,6 +50,10 @@ always reference [anthropic pricing](https://docs.anthropic.com/en/docs/about-cl
 
 on pro or max, **you don't pay per token.** the lore.db cost estimates are hypothetical: they show what your usage would cost at API list prices, not what you actually pay. legacy `~/.claude/mine.db` is auto-migrated by lore on first run.
 
+
+
+**note (current)**: billing mechanics and cache hit rate optimization may have changed in versions after v2.1.122. always run `/lore` to measure your actual session costs, and `/doctor` to verify your plan's token limits and billing method. anthropic pricing page is the source of truth for current rates.
+
 ### why caching still matters on a flat plan
 
 even though you don't pay per token, caching affects:
diff --git a/docs/session-workflow.md b/docs/session-workflow.md
index e44bae3..559a598 100644
--- a/docs/session-workflow.md
+++ b/docs/session-workflow.md
@@ -72,6 +72,10 @@ the data says: sessions that hit compaction average 1.7 compactions. if you're c
 
 **verification note**: verify current compact vs clear behavior against [official claude code docs](https://code.claude.com/docs/en/overview) before relying on these percentages in new versions.
 
+
+
+**note (current)**: compaction and context management behavior may have evolved since v2.1.122. run `/doctor` to check your current version's compaction strategy and cache state. percentages cited are session-specific analytics; actual compaction rates depend on your model selection and effort level.
+
 ## ending a session
 
 when a session ends (ctrl+c, `/exit`, or timeout), two things fire:
diff --git a/docs/tips/context-management.md b/docs/tips/context-management.md
index ac6c8c5..8cc490f 100644
--- a/docs/tips/context-management.md
+++ b/docs/tips/context-management.md
@@ -53,6 +53,12 @@ good: "the bug is in src/auth/token.ts around line 140, the JWT expiry check"
 
 
 
+
+
+### 6. verify compaction behavior with /doctor
+
+compaction strategy and cache prefix stability may differ across versions and billing methods (subscription vs API vs Bedrock/Vertex). run `/doctor` to check your active session's compaction strategy. if you're on a different platform or version, the percentages in this doc may not apply.
+
 ### 6. use single-file grep reads efficiently
 
 v2.1.160 removed the read-after-grep requirement for single-file `grep`/`egrep`/`fgrep` commands. if claude greps a single file to understand it before editing, that single grep now satisfies the read-before-edit check. this saves a separate Read call and keeps context tighter.
diff --git a/docs/tips/hooks-v2.md b/docs/tips/hooks-v2.md
index 180ade8..7308636 100644
--- a/docs/tips/hooks-v2.md
+++ b/docs/tips/hooks-v2.md
@@ -16,6 +16,10 @@ hooks come in five flavors now (v2.1.118 added `mcp_tool`). pick the wrong one a
 
 ---
 
+
+
+**hook stability note**: hook types and parameters are stable as of v2.1.122, but platform support varies. bedrock, vertex AI, and microsoft foundry may not support all hook types equally. run `/doctor` to check which hook types are available on your platform.
+
 ## version-specific features
 
 ### managed settings in hooks (v2.1.175+)