diff --git a/docs/core-data-structures/compaction.md b/docs/core-data-structures/compaction.md
index eae8d2e727..f6cdfd5b8b 100644
--- a/docs/core-data-structures/compaction.md
+++ b/docs/core-data-structures/compaction.md
@@ -54,7 +54,8 @@ interface CompactionResult {
 Automatic callers state why policy is running; implementations may treat confirmed overflow more aggressively than ordinary pressure.
 
 ```ts type-equiv
-export type CompactionTrigger = 'pressure' | 'context-overflow'
+/** Why automatic policy is asking a backend to consider compaction. */
+type CompactionTrigger = 'pressure' | 'context-overflow'
 ```
 
 `CompactService` exposes `compactIfNeeded(agent, trigger, signal)` for automatic `pressure` or `context-overflow` policy, returning `null` when no safe work exists, and `compactRegion(...)` for an explicit inclusive surface range. Implementations must forward the supplied signal to summarization. The seam owns no pricing API: the singleton [`ctx.tokenMeter`](token-meter.md) directly owns estimation and replay, while `dsh-compact-basic` owns retention, event sequencing, routed summarization calls, and their configuration.
diff --git a/docs/core-data-structures/core.md b/docs/core-data-structures/core.md
index 4d32b7796f..0eaede9345 100644
--- a/docs/core-data-structures/core.md
+++ b/docs/core-data-structures/core.md
@@ -446,12 +446,14 @@ type ContinuationDecision =
 `agent/request-error` receives the original `RequestError`, whose optional provider-neutral `code` supports stable routing without message parsing:
 
 ```ts type-equiv
+/** Model-request failure with an optional machine-routable provider code. */
 type RequestError = Error & { code?: string }
 ```
 
 It returns a `RequestErrorDecision`; `retry` opens a new numbered step after the recovery listener's durable mutation, while `fail` preserves that error:
 
 ```ts type-equiv
+/** Failed-request recovery decision; `retry` opens another numbered step while listeners delegate by calling `next()`. */
 type RequestErrorDecision = { action: 'fail' } | { action: 'retry' }
 ```