From b73b04baf05bc38d668ed307e0c87a01e8077ef0 Mon Sep 17 00:00:00 2001
From: "bonk-ai[bot]" <269762587+bonk-ai[bot]@users.noreply.github.com>
Date: Tue, 13 Oct 2026 08:26:58 +0000
Subject: [PATCH] docs: drop the debt and debugging entries #576, #579 and #583
 fixed

tech-debt.md loses items 5 (napi generator pin, fixed by #576) and 10
(lifecycle commentary, fixed by #579) and the bullets that cited them;
item 8 now names #576's agreement test and the proof-runner copy it
leaves out. debugging-guide.md drops the Serve-not-Future entry that
#583's accept loop retired. 15 citations #600 and #601 moved on those
pages are re-pointed by exact text match. The see-also footers on 19
pages drop their hand-written citation counts (AGENTS.md, Counts in
docs), and .vale/warnings.json lowers 25 ceilings to this tree's counts.

docs:check EXIT=0 (240 s), prose:check EXIT=0 (0 errors, 4069 warnings).
---
 .vale/warnings.json                          | 50 ++++++++---------
 docs/analysis/dead-code.md                   | 12 +++--
 docs/analysis/ownership.md                   | 12 +++--
 docs/analysis/risk-hotspots.md               | 12 +++--
 docs/architecture/data-flow.md               | 12 +++--
 docs/architecture/module-map.md              | 12 +++--
 docs/architecture/system-overview.md         | 12 +++--
 docs/behavior/processes.md                   | 12 +++--
 docs/behavior/state-machines.md              | 12 +++--
 docs/diagrams/architecture/components.md     | 12 +++--
 docs/diagrams/behavioral/sequences.md        | 12 +++--
 docs/diagrams/structural/dependency-graph.md | 12 +++--
 docs/insights/business-logic.md              | 12 +++--
 docs/insights/contract-map.md                | 12 +++--
 docs/insights/debugging-guide.md             | 38 +++++++------
 docs/insights/impact-analysis.md             | 12 +++--
 docs/insights/tech-debt.md                   | 57 +++++++++-----------
 docs/reference/cli.md                        | 12 +++--
 docs/reference/public-api.md                 | 12 +++--
 docs/reference/rpc-tools.md                  | 12 +++--
 20 files changed, 187 insertions(+), 162 deletions(-)

diff --git a/.vale/warnings.json b/.vale/warnings.json
index 2deb7f79..9d91abff 100644
--- a/.vale/warnings.json
+++ b/.vale/warnings.json
@@ -5,30 +5,30 @@
     "Google.Headings": 138,
     "Google.LyHyphens": 1,
     "Google.OptionalPlurals": 11,
-    "Google.OxfordComma": 55,
+    "Google.OxfordComma": 53,
     "Google.Quotes": 14,
     "Google.Ranges": 2,
     "Google.Units": 1,
     "Google.Will": 12,
     "Google.WordList": 229,
-    "Google.WordListCase": 138,
+    "Google.WordListCase": 136,
     "Microvms.Counts": 3,
-    "Readability.AutomatedReadability": 37,
-    "Readability.ColemanLiau": 52,
-    "Readability.FleschKincaid": 40,
-    "Readability.FleschReadingEase": 65,
-    "Readability.GunningFog": 30,
-    "Readability.LIX": 59,
-    "Readability.SMOG": 43,
+    "Readability.AutomatedReadability": 35,
+    "Readability.ColemanLiau": 50,
+    "Readability.FleschKincaid": 38,
+    "Readability.FleschReadingEase": 63,
+    "Readability.GunningFog": 26,
+    "Readability.LIX": 58,
+    "Readability.SMOG": 42,
     "ai-tells.AbsoluteAssertions": 1,
-    "ai-tells.AnthropomorphicAdjectives": 3,
+    "ai-tells.AnthropomorphicAdjectives": 1,
     "ai-tells.AnthropomorphicCognition": 12,
     "ai-tells.BareHolds": 8,
     "ai-tells.BareNames": 28,
-    "ai-tells.BareReaches": 19,
-    "ai-tells.CataphoricForecasting": 12,
+    "ai-tells.BareReaches": 17,
+    "ai-tells.CataphoricForecasting": 11,
     "ai-tells.ColonUsage": 547,
-    "ai-tells.ConsequenceClause": 30,
+    "ai-tells.ConsequenceClause": 29,
     "ai-tells.ConsequenceParticiple": 4,
     "ai-tells.ContrastiveNegation": 4,
     "ai-tells.CoordinatedReveal": 3,
@@ -48,28 +48,28 @@
     "ai-tells.FigurativeSurfaces": 7,
     "ai-tells.FigurativeWins": 17,
     "ai-tells.FillerIntensifier": 5,
-    "ai-tells.FormalRegister": 113,
+    "ai-tells.FormalRegister": 112,
     "ai-tells.FormalTransitions": 38,
-    "ai-tells.LabelAndExplain": 9,
+    "ai-tells.LabelAndExplain": 8,
     "ai-tells.MortalityMetaphors": 21,
     "ai-tells.MotionMetaphors": 11,
     "ai-tells.NamedAdjective": 2,
-    "ai-tells.NegatedObject": 54,
+    "ai-tells.NegatedObject": 53,
     "ai-tells.NegatedPair": 3,
     "ai-tells.NegatedSubject": 14,
-    "ai-tells.NounString": 20,
-    "ai-tells.ParallelStaccato": 13,
-    "ai-tells.SemicolonUsage": 298,
+    "ai-tells.NounString": 19,
+    "ai-tells.ParallelStaccato": 12,
+    "ai-tells.SemicolonUsage": 293,
     "ai-tells.ServesAsDodge": 5,
-    "ai-tells.ShipOveruse": 15,
-    "ai-tells.StackedAnaphora": 7,
+    "ai-tells.ShipOveruse": 14,
+    "ai-tells.StackedAnaphora": 6,
     "ai-tells.UnderRegime": 4,
     "ai-tells.UniversalSubject": 5,
-    "ai-tells.VerbTricolon": 144,
-    "proselint.Diacritical": 12,
+    "ai-tells.VerbTricolon": 143,
+    "proselint.Diacritical": 8,
     "proselint.Needless": 1,
-    "write-good.Passive": 519,
-    "write-good.TooWordy": 251,
+    "write-good.Passive": 509,
+    "write-good.TooWordy": 245,
     "write-good.Weasel": 16
   }
 }
diff --git a/docs/analysis/dead-code.md b/docs/analysis/dead-code.md
index 81dd6d00..d88d8b8e 100644
--- a/docs/analysis/dead-code.md
+++ b/docs/analysis/dead-code.md
@@ -64,8 +64,10 @@ these uses.
 
 ## See also
 
-- [module map](../architecture/module-map.md): 8 shared source citations
-- [contract map](../insights/contract-map.md): 6 shared source citations
-- [impact analysis](../insights/impact-analysis.md): 5 shared source citations
-- [risk hotspots](risk-hotspots.md): 4 shared source citations
-- [system overview](../architecture/system-overview.md): 4 shared source citations
+These pages cite many of the same source files as this one.
+
+- [module map](../architecture/module-map.md)
+- [contract map](../insights/contract-map.md)
+- [impact analysis](../insights/impact-analysis.md)
+- [risk hotspots](risk-hotspots.md)
+- [system overview](../architecture/system-overview.md)
diff --git a/docs/analysis/ownership.md b/docs/analysis/ownership.md
index 7f68b83c..62863dfb 100644
--- a/docs/analysis/ownership.md
+++ b/docs/analysis/ownership.md
@@ -112,8 +112,10 @@ implementation boundary and evidence. Apply these mitigations during review:
 
 ## See also
 
-- [module map](../architecture/module-map.md): 11 shared source citations
-- [system overview](../architecture/system-overview.md): 9 shared source citations
-- [dependency graph](../diagrams/structural/dependency-graph.md): 7 shared source citations
-- [dead code](dead-code.md): 3 shared source citations
-- [impact analysis](../insights/impact-analysis.md): 3 shared source citations
+These pages cite many of the same source files as this one.
+
+- [module map](../architecture/module-map.md)
+- [system overview](../architecture/system-overview.md)
+- [dependency graph](../diagrams/structural/dependency-graph.md)
+- [dead code](dead-code.md)
+- [impact analysis](../insights/impact-analysis.md)
diff --git a/docs/analysis/risk-hotspots.md b/docs/analysis/risk-hotspots.md
index ff985779..c26dc25f 100644
--- a/docs/analysis/risk-hotspots.md
+++ b/docs/analysis/risk-hotspots.md
@@ -73,8 +73,10 @@ No current per-file diagnostic dataset supports warning or error totals, so this
 
 ## See also
 
-- [module map](../architecture/module-map.md): 12 shared source citations
-- [contract map](../insights/contract-map.md): 8 shared source citations
-- [impact analysis](../insights/impact-analysis.md): 6 shared source citations
-- [dead code](dead-code.md): 4 shared source citations
-- [data flow](../architecture/data-flow.md): 3 shared source citations
+These pages cite many of the same source files as this one.
+
+- [module map](../architecture/module-map.md)
+- [contract map](../insights/contract-map.md)
+- [impact analysis](../insights/impact-analysis.md)
+- [dead code](dead-code.md)
+- [data flow](../architecture/data-flow.md)
diff --git a/docs/architecture/data-flow.md b/docs/architecture/data-flow.md
index f2866493..3cbc962f 100644
--- a/docs/architecture/data-flow.md
+++ b/docs/architecture/data-flow.md
@@ -127,8 +127,10 @@ sequenceDiagram
 
 ## See also
 
-- [contract map](../insights/contract-map.md): 11 shared source citations
-- [processes](../behavior/processes.md): 10 shared source citations
-- [impact analysis](../insights/impact-analysis.md): 10 shared source citations
-- [module map](module-map.md): 9 shared source citations
-- [components](../diagrams/architecture/components.md): 6 shared source citations
+These pages cite many of the same source files as this one.
+
+- [contract map](../insights/contract-map.md)
+- [processes](../behavior/processes.md)
+- [impact analysis](../insights/impact-analysis.md)
+- [module map](module-map.md)
+- [components](../diagrams/architecture/components.md)
diff --git a/docs/architecture/module-map.md b/docs/architecture/module-map.md
index a1a7f245..09e13634 100644
--- a/docs/architecture/module-map.md
+++ b/docs/architecture/module-map.md
@@ -146,8 +146,10 @@ The portable model crate expresses daemon and client behavior as state machines
 
 ## See also
 
-- [contract map](../insights/contract-map.md): 41 shared source citations
-- [impact analysis](../insights/impact-analysis.md): 31 shared source citations
-- [processes](../behavior/processes.md): 20 shared source citations
-- [business logic](../insights/business-logic.md): 18 shared source citations
-- [risk hotspots](../analysis/risk-hotspots.md): 12 shared source citations
+These pages cite many of the same source files as this one.
+
+- [contract map](../insights/contract-map.md)
+- [impact analysis](../insights/impact-analysis.md)
+- [processes](../behavior/processes.md)
+- [business logic](../insights/business-logic.md)
+- [risk hotspots](../analysis/risk-hotspots.md)
diff --git a/docs/architecture/system-overview.md b/docs/architecture/system-overview.md
index e3fd81a4..0e1ccf92 100644
--- a/docs/architecture/system-overview.md
+++ b/docs/architecture/system-overview.md
@@ -71,8 +71,10 @@ flowchart LR
 
 ## See also
 
-- [dependency graph](../diagrams/structural/dependency-graph.md): 19 shared source citations
-- [module map](module-map.md): 12 shared source citations
-- [ownership](../analysis/ownership.md): 9 shared source citations
-- [impact analysis](../insights/impact-analysis.md): 8 shared source citations
-- [contract map](../insights/contract-map.md): 7 shared source citations
+These pages cite many of the same source files as this one.
+
+- [dependency graph](../diagrams/structural/dependency-graph.md)
+- [module map](module-map.md)
+- [ownership](../analysis/ownership.md)
+- [impact analysis](../insights/impact-analysis.md)
+- [contract map](../insights/contract-map.md)
diff --git a/docs/behavior/processes.md b/docs/behavior/processes.md
index 7860a03e..21d4c2db 100644
--- a/docs/behavior/processes.md
+++ b/docs/behavior/processes.md
@@ -205,8 +205,10 @@ Entry point: `crates/agentd/src/fs.rs:1450`
 
 ## See also
 
-- [contract map](../insights/contract-map.md): 25 shared source citations
-- [module map](../architecture/module-map.md): 20 shared source citations
-- [impact analysis](../insights/impact-analysis.md): 19 shared source citations
-- [business logic](../insights/business-logic.md): 11 shared source citations
-- [debugging guide](../insights/debugging-guide.md): 11 shared source citations
+These pages cite many of the same source files as this one.
+
+- [contract map](../insights/contract-map.md)
+- [module map](../architecture/module-map.md)
+- [impact analysis](../insights/impact-analysis.md)
+- [business logic](../insights/business-logic.md)
+- [debugging guide](../insights/debugging-guide.md)
diff --git a/docs/behavior/state-machines.md b/docs/behavior/state-machines.md
index 765d3ab1..c5f8bd35 100644
--- a/docs/behavior/state-machines.md
+++ b/docs/behavior/state-machines.md
@@ -331,8 +331,10 @@ Defined at: `crates/model/src/wrap.rs:256-263`
 
 ## See also
 
-- [module map](../architecture/module-map.md): 9 shared source citations
-- [data flow](../architecture/data-flow.md): 2 shared source citations
-- [system overview](../architecture/system-overview.md): 2 shared source citations
-- [processes](processes.md): 2 shared source citations
-- [components](../diagrams/architecture/components.md): 2 shared source citations
+These pages cite many of the same source files as this one.
+
+- [module map](../architecture/module-map.md)
+- [data flow](../architecture/data-flow.md)
+- [system overview](../architecture/system-overview.md)
+- [processes](processes.md)
+- [components](../diagrams/architecture/components.md)
diff --git a/docs/diagrams/architecture/components.md b/docs/diagrams/architecture/components.md
index 76aaca6d..3f333f96 100644
--- a/docs/diagrams/architecture/components.md
+++ b/docs/diagrams/architecture/components.md
@@ -105,8 +105,10 @@ classDiagram
 
 ## See also
 
-- [contract map](../../insights/contract-map.md): 9 shared source citations
-- [module map](../../architecture/module-map.md): 8 shared source citations
-- [processes](../../behavior/processes.md): 8 shared source citations
-- [business logic](../../insights/business-logic.md): 7 shared source citations
-- [impact analysis](../../insights/impact-analysis.md): 7 shared source citations
+These pages cite many of the same source files as this one.
+
+- [contract map](../../insights/contract-map.md)
+- [module map](../../architecture/module-map.md)
+- [processes](../../behavior/processes.md)
+- [business logic](../../insights/business-logic.md)
+- [impact analysis](../../insights/impact-analysis.md)
diff --git a/docs/diagrams/behavioral/sequences.md b/docs/diagrams/behavioral/sequences.md
index 437a1f30..bdf2d9c0 100644
--- a/docs/diagrams/behavioral/sequences.md
+++ b/docs/diagrams/behavioral/sequences.md
@@ -149,8 +149,10 @@ sequenceDiagram
 
 ## See also
 
-- [processes](../../behavior/processes.md): 6 shared source citations
-- [contract map](../../insights/contract-map.md): 6 shared source citations
-- [module map](../../architecture/module-map.md): 5 shared source citations
-- [components](../architecture/components.md): 5 shared source citations
-- [data flow](../../architecture/data-flow.md): 4 shared source citations
+These pages cite many of the same source files as this one.
+
+- [processes](../../behavior/processes.md)
+- [contract map](../../insights/contract-map.md)
+- [module map](../../architecture/module-map.md)
+- [components](../architecture/components.md)
+- [data flow](../../architecture/data-flow.md)
diff --git a/docs/diagrams/structural/dependency-graph.md b/docs/diagrams/structural/dependency-graph.md
index 3471bb58..6107114a 100644
--- a/docs/diagrams/structural/dependency-graph.md
+++ b/docs/diagrams/structural/dependency-graph.md
@@ -167,8 +167,10 @@ fields, and getter receivers. The supported Node versions provide this API level
 
 ## See also
 
-- [system overview](../../architecture/system-overview.md): 19 shared source citations
-- [contract map](../../insights/contract-map.md): 13 shared source citations
-- [module map](../../architecture/module-map.md): 12 shared source citations
-- [impact analysis](../../insights/impact-analysis.md): 9 shared source citations
-- [ownership](../../analysis/ownership.md): 7 shared source citations
+These pages cite many of the same source files as this one.
+
+- [system overview](../../architecture/system-overview.md)
+- [contract map](../../insights/contract-map.md)
+- [module map](../../architecture/module-map.md)
+- [impact analysis](../../insights/impact-analysis.md)
+- [ownership](../../analysis/ownership.md)
diff --git a/docs/insights/business-logic.md b/docs/insights/business-logic.md
index a8809afd..2224f2de 100644
--- a/docs/insights/business-logic.md
+++ b/docs/insights/business-logic.md
@@ -118,8 +118,10 @@ The report charges snapshot reads on launch, compute for a recorded running phas
 
 ## See also
 
-- [module map](../architecture/module-map.md): 18 shared source citations
-- [contract map](contract-map.md): 17 shared source citations
-- [impact analysis](impact-analysis.md): 14 shared source citations
-- [processes](../behavior/processes.md): 11 shared source citations
-- [components](../diagrams/architecture/components.md): 7 shared source citations
+These pages cite many of the same source files as this one.
+
+- [module map](../architecture/module-map.md)
+- [contract map](contract-map.md)
+- [impact analysis](impact-analysis.md)
+- [processes](../behavior/processes.md)
+- [components](../diagrams/architecture/components.md)
diff --git a/docs/insights/contract-map.md b/docs/insights/contract-map.md
index d76bf27f..b4b23994 100644
--- a/docs/insights/contract-map.md
+++ b/docs/insights/contract-map.md
@@ -616,8 +616,10 @@ Mitigation: retain separate collected-response and streaming implementations wit
 
 ## See also
 
-- [module map](../architecture/module-map.md): 41 shared source citations
-- [impact analysis](impact-analysis.md): 41 shared source citations
-- [processes](../behavior/processes.md): 25 shared source citations
-- [business logic](business-logic.md): 17 shared source citations
-- [dependency graph](../diagrams/structural/dependency-graph.md): 13 shared source citations
+These pages cite many of the same source files as this one.
+
+- [module map](../architecture/module-map.md)
+- [impact analysis](impact-analysis.md)
+- [processes](../behavior/processes.md)
+- [business logic](business-logic.md)
+- [dependency graph](../diagrams/structural/dependency-graph.md)
diff --git a/docs/insights/debugging-guide.md b/docs/insights/debugging-guide.md
index c5307b22..c2772576 100644
--- a/docs/insights/debugging-guide.md
+++ b/docs/insights/debugging-guide.md
@@ -3,7 +3,7 @@
 Start with the reported error class and the command's structured result. The CLI maps
 library errors to stable exit codes; daemon status details travel separately as `data.kind`.
 This distinction separates a failed workload from a failed platform operation.
-`crates/microvms-cli/src/exit.rs:79-102`, `crates/microvms-cli/src/exit.rs:318-327`
+`crates/microvms-cli/src/exit.rs:79-102`, `crates/microvms-cli/src/exit.rs:319-328`
 
 ## Failure-mode index
 
@@ -16,14 +16,14 @@ This distinction separates a failed workload from a failed platform operation.
 | An image reports a failed state | The failed version or its builds may carry the cause | Read the reported `stateReason` details and the build log group; the client gathers version and build reasons | `crates/microvms-app/src/control/image.rs:600-620`, `crates/microvms-app/src/control/image.rs:637-667` |
 | `ERR_LAUNCH_DIED` while waiting for a lifecycle state | The service reported a state in the wait's failure set | Read the state and `stateReason` included in the error before treating it as a connection problem | `crates/microvms-app/src/control/microvm.rs:675-681`, `crates/microvms-app/src/control/microvm.rs:698-714` |
 | `ERR_WINDOW_CLOSED` on resume | The service refused the resume, and `GetMicrovm` reports the VM gone: it ended first, and nothing brings it back | Read the state and `stateReason` in the error before you launch a new VM. A VM ended with `microvm terminate` gets the same refusal as one the platform ended, so the error can't say which ended it. The idle policy's `suspendedDurationSeconds` ends a VM it suspended, and `maximumDurationInSeconds` ends any VM; an explicit suspend could still resume past the window (measured 2026-10-12, us-east-1) | `crates/microvms-app/src/control/microvm.rs:819-852`, `crates/microvms-app/src/sandbox.rs:1694-1700` |
-| Control requests return 503 before bootstrap | The daemon has no installed run token yet | Read `bootstrapped` from health and distinguish `NotBootstrapped` from a permanent refusal | `crates/agentd/src/auth.rs:68-80`, `crates/protocol/src/health.rs:20`, `crates/microvms-domain/src/error.rs:384-388` |
+| Control requests return 503 before bootstrap | The daemon has no installed run token yet | Read `bootstrapped` from health and distinguish `NotBootstrapped` from a permanent refusal | `crates/agentd/src/auth.rs:68-80`, `crates/protocol/src/health.rs:20`, `crates/microvms-domain/src/error.rs:386-390` |
 | A write returns 507 | The destination filesystem is below its configured reserve | Read the available and reserved byte values in the response, then inspect `health.disk`; missing disk data means unmeasurable | `crates/agentd/src/fs.rs:97-123`, `crates/protocol/src/health.rs:21-34` |
 | `ERR_EXEC_FAILED` | The workload completed with a nonzero exit status | Inspect the workload's stdout, stderr, exit code, and signal before investigating infrastructure | `crates/microvms-cli/src/exit.rs:97-102`, `crates/protocol/src/exec.rs:56-68` |
 | An exec reports `timed_out: true` | The daemon execution deadline expired | Inspect `timeout_sec` and the result note; this deadline signals the process group | `crates/protocol/src/exec.rs:63-66`, `crates/microvms-app/src/session/exec.rs:190-195` |
-| A wait reports `ERR_TIMEOUT` | A client-side deadline elapsed | Check whether the error is the client wait deadline before assuming the exec stopped; `ExecTimeout` leaves the VM and exec untouched | `crates/microvms-domain/src/error.rs:397-402` |
-| An exec reports `truncated: true` | A captured stream reached the daemon's output cap | Compare expected output volume with `AGENTD_MAX_OUTPUT_BYTES`; the default is 8 MiB per stream | `crates/protocol/src/exec.rs:69-72`, `crates/agentd/src/config.rs:25-27`, `crates/agentd/src/config.rs:107`, `crates/agentd/src/config.rs:148-149` |
-| An exec reports `writers_may_be_alive: true` | A descendant kept an output pipe open after the direct child exited | Check background processes and `AGENTD_OUTPUT_LINGER_SECS`; the flag means the linger deadline expired before EOF | `crates/protocol/src/exec.rs:73-77`, `crates/agentd/src/exec.rs:1460-1477`, `crates/agentd/src/config.rs:151-152` |
-| The output stream emits `gap` | Replay bytes were evicted or a live subscriber lagged | Record `from` and `to`, then reattach from the last received offset if useful. Output already outside the replay window cannot be recovered through the stream | `crates/protocol/src/exec.rs:339-344`, `crates/agentd/src/exec.rs:182-189`, `crates/agentd/src/exec.rs:641-653` |
+| A wait reports `ERR_TIMEOUT` | A client-side deadline elapsed | Check whether the error is the client wait deadline before assuming the exec stopped; `ExecTimeout` leaves the VM and exec untouched | `crates/microvms-domain/src/error.rs:399-404` |
+| An exec reports `truncated: true` | A captured stream reached the daemon's output cap | Compare expected output volume with `AGENTD_MAX_OUTPUT_BYTES`; the default is 8 MiB per stream | `crates/protocol/src/exec.rs:69-72`, `crates/agentd/src/config.rs:25-27`, `crates/agentd/src/config.rs:124`, `crates/agentd/src/config.rs:166-167` |
+| An exec reports `writers_may_be_alive: true` | A descendant kept an output pipe open after the direct child exited | Check background processes and `AGENTD_OUTPUT_LINGER_SECS`; the flag means the linger deadline expired before EOF | `crates/protocol/src/exec.rs:73-77`, `crates/agentd/src/exec.rs:1464-1481`, `crates/agentd/src/config.rs:169-170` |
+| The output stream emits `gap` | Replay bytes were evicted or a live subscriber lagged | Record `from` and `to`, then reattach from the last received offset if useful. Output already outside the replay window cannot be recovered through the stream | `crates/protocol/src/exec.rs:341-346`, `crates/agentd/src/exec.rs:182-189`, `crates/agentd/src/exec.rs:641-653` |
 | A stdin write returns 409 | The exec was started without a writable stdin pipe | Enable `stdin: true` when starting a new exec | `crates/agentd/src/exec.rs:724-731` |
 | A stdin write returns 410 | The pipe closed after EOF or the child exited | Treat that input stream as closed; retrying the same write cannot reopen it | `crates/agentd/src/exec.rs:772-781` |
 | A stdin write returns 408 | The child did not drain the pipe within the write timeout | Reconcile possible partial delivery before retrying; the response explicitly warns that some bytes may have been written | `crates/agentd/src/exec.rs:815-825` |
@@ -35,15 +35,15 @@ This distinction separates a failed workload from a failed platform operation.
 | Surface | Where it emits | What to grep for | Citation |
 | --- | --- | --- | --- |
 | Daemon logging | JSON on stdout, with targets; `AGENTD_LOG` selects the filter and defaults to `info` | `agentd listening`, `addr`, `version` | `crates/agentd/src/main.rs:83-85`, `crates/agentd/src/main.rs:90-102` |
-| Configuration warnings | The daemon log | `ignoring unparseable configuration value`, with `key` and `raw`; the daemon retains the default | `crates/agentd/src/config.rs:135-139`, `crates/agentd/src/config.rs:199-206` |
-| Exec diagnostics | The daemon log | `exec stream subscriber lagged`, `wait on exec child failed`, `exec exceeded its timeout and its process group was signalled` | `crates/agentd/src/exec.rs:648`, `crates/agentd/src/exec.rs:1485-1493` |
+| Configuration warnings | The daemon log | `ignoring unparseable configuration value`, with `key` and `raw`; the daemon retains the default | `crates/agentd/src/config.rs:153-157`, `crates/agentd/src/config.rs:239-246` |
+| Exec diagnostics | The daemon log | `exec stream subscriber lagged`, `wait on exec child failed`, `exec exceeded its timeout and its process group was signalled` | `crates/agentd/src/exec.rs:648`, `crates/agentd/src/exec.rs:1489-1497` |
 | Disk-pressure diagnostics | The daemon log and the 507 response body | `refusing a write`, `path`, `available`, `reserve` | `crates/agentd/src/fs.rs:106-121` |
 | Shutdown diagnostics | The daemon log | `SIGTERM received; draining`, `interrupt received; draining`, `cannot listen for SIGTERM` | `crates/agentd/src/serve.rs:127-139` |
 | Build log locator | `microvm logs <image-name>` returns the group and an AWS CLI tail command; it does not fetch log events | `data.logGroup`, `data.tailCommand`, `data.tailRequires`; `data.lines` is null | `crates/microvms-cli/src/commands/local.rs:778-804` |
 | Daemon health | The health response | `version`, `bootstrapped`, `disk`, `busy`, `execs`; `busy` tracks unfinished execs rather than results awaiting acknowledgment | `crates/protocol/src/health.rs:19-34`, `crates/protocol/src/health.rs:63-88` |
 | CLI failure envelope | Structured command output; normal progress is separate from stdout | `code`, `error`, `finding`, `suggestions`, `data.kind` | `crates/microvms-cli/src/envelope.rs:20-31`, `crates/microvms-cli/src/main.rs:22-24` |
 | CLI streamed exec | NDJSON on stdout with a compact terminal envelope | Event records followed by the `microvm.exec.stream` envelope; do not parse it as one JSON document | `crates/microvms-cli/src/envelope.rs:33-49` |
-| Python exception | The raised exception instance | `code`, `wire_kind`, `retryable` | `bindings/microvms-py/src/errors.rs:151-166` |
+| Python exception | The raised exception instance | `code`, `wire_kind`, `retryable` | `bindings/microvms-py/src/errors.rs:153-168` |
 | Node exception | The error cause chain | `cause.message` and `cause.cause.message` | `bindings/microvms-js/src/errors.rs:35-44` |
 | Local run ledger | A JSON record read by `microvm ls` | `runId`, `region`, `imageIdentifier`, `microvmId`, `leaked` | `crates/microvms-cli/src/ledger.rs:35-48`, `crates/microvms-cli/src/commands/local.rs:52-58` |
 
@@ -51,7 +51,7 @@ This distinction separates a failed workload from a failed platform operation.
 
 1. **Preserve the structured error and exit status.** Read the coarse `ERR_*` class, then
    `data.kind`, `finding`, and `suggestions`. Retryability comes from the error class, not a
-   search for words in its message. `crates/microvms-cli/src/envelope.rs:20-31`, `crates/microvms-domain/src/error.rs:174-179`
+   search for words in its message. `crates/microvms-cli/src/envelope.rs:20-31`, `crates/microvms-domain/src/error.rs:176-181`
 2. **Separate workload failure from infrastructure failure.** An `ERR_EXEC_FAILED` means
    the workload exited nonzero. Inspect its exit code, signal, stdout, and stderr before
    changing deployment settings. `crates/microvms-cli/src/exit.rs:97-102`, `crates/protocol/src/exec.rs:56-68`
@@ -85,7 +85,7 @@ comments beside the behavior they explain.
 - **A configuration override that never applied:** an unparseable environment value leaves
   the default in place. Signal: an `ignoring unparseable configuration value` warning.
   Mitigation: inspect the logged key and value before tuning timeouts or limits again.
-  `crates/agentd/src/config.rs:135-139`, `crates/agentd/src/config.rs:199-206`
+  `crates/agentd/src/config.rs:153-157`, `crates/agentd/src/config.rs:239-246`
 - **A simulator deadline racing a real child:** simulated time advances independently of a
   subprocess's wall clock. Signal: test-only missing output and `writers_may_be_alive`.
   Mitigation: synchronize the child with stdin reads, or give its real pipe drain an
@@ -94,15 +94,13 @@ comments beside the behavior they explain.
   fails even when the command succeeds. Signal: a parser error after valid event records.
   Mitigation: consume NDJSON events and the compact terminal envelope separately.
   `crates/microvms-cli/src/envelope.rs:33-49`
-- **A misleading server compiler error:** a generic listener without `L::Addr: Debug` can
-  make `Serve` appear not to implement `Future`. Signal: that error while modifying the
-  generic serving path. Mitigation: preserve the listener address bound.
-  `crates/agentd/src/serve.rs:14-26`
 
 ## See also
 
-- [contract map](contract-map.md): 13 shared source citations
-- [impact analysis](impact-analysis.md): 13 shared source citations
-- [processes](../behavior/processes.md): 11 shared source citations
-- [module map](../architecture/module-map.md): 10 shared source citations
-- [business logic](business-logic.md): 7 shared source citations
+These pages cite many of the same source files as this one.
+
+- [contract map](contract-map.md)
+- [impact analysis](impact-analysis.md)
+- [processes](../behavior/processes.md)
+- [module map](../architecture/module-map.md)
+- [business logic](business-logic.md)
diff --git a/docs/insights/impact-analysis.md b/docs/insights/impact-analysis.md
index 99e9d249..8e0cbd42 100644
--- a/docs/insights/impact-analysis.md
+++ b/docs/insights/impact-analysis.md
@@ -280,8 +280,10 @@ Defined at: `crates/microvms-cli/src/manifest.rs:51-117`.
 
 ## See also
 
-- [contract map](contract-map.md): 41 shared source citations
-- [module map](../architecture/module-map.md): 31 shared source citations
-- [processes](../behavior/processes.md): 19 shared source citations
-- [business logic](business-logic.md): 14 shared source citations
-- [debugging guide](debugging-guide.md): 13 shared source citations
+These pages cite many of the same source files as this one.
+
+- [contract map](contract-map.md)
+- [module map](../architecture/module-map.md)
+- [processes](../behavior/processes.md)
+- [business logic](business-logic.md)
+- [debugging guide](debugging-guide.md)
diff --git a/docs/insights/tech-debt.md b/docs/insights/tech-debt.md
index 3de1f16a..71d1572d 100644
--- a/docs/insights/tech-debt.md
+++ b/docs/insights/tech-debt.md
@@ -22,12 +22,10 @@ implementation defects.
 | 2 | Shared parity cases need a review-supplied failing-first proof: the automated proof finder recognizes language test functions rather than corpus entries. Add corpus support without duplicating each case across language suites. | missing tests | M | `CONTRIBUTING.md:210-216`, `tools/fail-to-pass.py:29-36` |
 | 3 | The CLI owns persistent ledger and history formats. Moving their reusable behavior below the CLI would let other adapters share it; preserve their different retention semantics. | wrong abstraction | L | `AGENTS.md:110-116`, `crates/microvms-cli/src/ledger.rs:28-48`, `crates/microvms-cli/src/history.rs:5-14` |
 | 4 | Default parity intentionally omits string, zero, and `None` defaults, while TypeScript defaults appear only in prose. Expand the contract representation before asserting option-level consistency. | missing tests | M | `tools/check-parity.py:72-86` |
-| 5 | Declaration generation resolves `@napi-rs/cli@3` afresh, so an upstream release can change the expected declarations without a repository change. Pin the generator used by the task and package build together. | version pin | S | `.config/mise/tasks/contracts.toml:270-295`, `bindings/microvms-js/package.json:51-54` |
-| 6 | Formal tasks deliberately omit strict verification; their success means no error-severity findings, not a fully verified specification. Reduce unresolved findings before strengthening the gate. | missing tests | L | `.config/mise/tasks/trace.toml:3-13`, `tools/check-spec.sh:4-9` |
-| 7 | *Judgment call:* formal requirements remain outside the local `check` task and need a separately installed checker. A reproducible optional verification environment would make this tier easier to run without changing the ordinary local gate. | missing tests | M | `.config/mise/tasks/trace.toml:11-28`, `.config/mise/tasks/check.toml:11-43`, `tools/check-spec.sh:15-24` |
-| 8 | The Maturin version is repeated in stub generation, binding builds, and proof-runner commands. Centralize its ownership or assert agreement to keep coordinated upgrades from drifting. | duplicated logic | S | `tools/generate-py-stubs.py:84-89`, `.config/mise/tasks/test.toml:89-104`, `tools/fail-to-pass.py:101-107` |
-| 9 | The daemon port default is independently declared by control, session, and daemon configuration. Give the shared default an owner while preserving the existing public paths. | duplicated logic | S | `crates/microvms-app/src/control/mod.rs:118-119`, `crates/microvms-app/src/session/proxy.rs:84-85`, `crates/agentd/src/config.rs:101-104` |
-| 10 | Lifecycle commentary says `Sandbox` cannot address a VM launched elsewhere, while `Sandbox::adopt` now supports that workflow. Rewrite the rationale around the current ownership model before using it to guide a refactor. | dead code adjacent | S | `crates/microvms-cli/src/commands/lifecycle.rs:10-18`, `crates/microvms-app/src/sandbox.rs:1338-1345` |
+| 5 | Formal tasks deliberately omit strict verification; their success means no error-severity findings, not a fully verified specification. Reduce unresolved findings before strengthening the gate. | missing tests | L | `.config/mise/tasks/trace.toml:3-13`, `tools/check-spec.sh:4-9` |
+| 6 | *Judgment call:* formal requirements remain outside the local `check` task and need a separately installed checker. A reproducible optional verification environment would make this tier easier to run without changing the ordinary local gate. | missing tests | M | `.config/mise/tasks/trace.toml:11-28`, `.config/mise/tasks/check.toml:11-43`, `tools/check-spec.sh:15-24` |
+| 7 | The Maturin version is repeated in stub generation, binding builds, and proof-runner commands. A unit test checks that the binding builds and the release workflow use the stub generator's pin, and the proof runner's copy is outside that test. Add it, or centralize ownership, before the next upgrade. | duplicated logic | S | `tools/generate-py-stubs.py:84-89`, `.config/mise/tasks/test.toml:89-104`, `tools/fail-to-pass.py:101-108`, `tools/test_check_release_builds.py:91-105` |
+| 8 | The daemon port default is independently declared by control, session, and daemon configuration. Give the shared default an owner while preserving the existing public paths. | duplicated logic | S | `crates/microvms-app/src/control/mod.rs:118-119`, `crates/microvms-app/src/session/proxy.rs:84-85`, `crates/agentd/src/config.rs:118-121` |
 
 ## Explicit markers
 
@@ -82,20 +80,19 @@ Cost: M for a reproducible optional environment; L to strengthen the verificatio
 
 ### Generator versions have multiple owners
 
-The declaration task deliberately resolves a moving major version, while the
-Python stub generator uses an exact version repeated in other build commands.
-Both choices create coordination work: one admits upstream changes between runs,
-and the other requires synchronized edits during upgrades
-(`.config/mise/tasks/contracts.toml:293-306`, `tools/generate-py-stubs.py:84-89`).
+The Python stub generator pins an exact Maturin release, and the binding builds
+and the proof runner repeat it. Upgrading Maturin means editing each copy
+(`tools/generate-py-stubs.py:84-89`). One unit test checks that the binding builds
+and the release workflow use the generator's pin
+(`tools/test_check_release_builds.py:91-105`), and the proof runner's copy isn't in
+that test's list.
 
 Shows up in:
 
-- `.config/mise/tasks/contracts.toml:293-306`: a declaration check that anticipates generator changes.
-- `bindings/microvms-js/package.json:51-54`: the package's own generator constraint.
 - `.config/mise/tasks/test.toml:89-104`: repeated Python build-tool version.
-- `tools/fail-to-pass.py:101-113`: binding build commands repeated in the proof runner.
+- `tools/fail-to-pass.py:101-108`: the binding build command repeated in the proof runner.
 
-Cost: S. Establish a shared version source or an agreement check before the next upgrade.
+Cost: S. Add the proof runner's copy to the agreement test, or derive it from the generator's pin.
 
 ### Persistent formats live above the shared implementation
 
@@ -114,30 +111,26 @@ Shows up in:
 
 Cost: L. Move reusable behavior with compatibility coverage for existing records.
 
-### Explanations and repeated constants need an owner
+### The daemon port default needs an owner
 
-The lifecycle module's launch-only explanation predates the supported adoption
-workflow. Independently, the daemon port default appears in control, session, and
-daemon configuration. These are different forms of the same maintenance cost:
-changing a contract requires finding copies that the type system does not connect
-(`crates/microvms-cli/src/commands/lifecycle.rs:10-18`,
-`crates/microvms-app/src/sandbox.rs:1338-1345`,
-`crates/microvms-app/src/control/mod.rs:118-119`).
+The daemon port default appears in control, session, and daemon configuration.
+Changing it requires finding copies that the type system does not connect
+(`crates/microvms-app/src/control/mod.rs:118-119`).
 
 Shows up in:
 
-- `crates/microvms-cli/src/commands/lifecycle.rs:10-18`: the old ownership rationale.
-- `crates/microvms-app/src/sandbox.rs:1338-1345`: the adoption workflow that requires a revised explanation.
 - `crates/microvms-app/src/control/mod.rs:118-119`: control's port default.
 - `crates/microvms-app/src/session/proxy.rs:84-85`: session's port default.
-- `crates/agentd/src/config.rs:101-104`: the daemon's port default.
+- `crates/agentd/src/config.rs:118-121`: the daemon's port default.
 
-Cost: S for the explanation and shared constant; preserve compatibility re-exports.
+Cost: S for a shared constant; preserve compatibility re-exports.
 
 ## See also
 
-- [debugging guide](debugging-guide.md): 5 shared source citations
-- [contract map](contract-map.md): 4 shared source citations
-- [impact analysis](impact-analysis.md): 4 shared source citations
-- [module map](../architecture/module-map.md): 3 shared source citations
-- [business logic](business-logic.md): 3 shared source citations
+These pages cite many of the same source files as this one.
+
+- [debugging guide](debugging-guide.md)
+- [contract map](contract-map.md)
+- [impact analysis](impact-analysis.md)
+- [module map](../architecture/module-map.md)
+- [business logic](business-logic.md)
diff --git a/docs/reference/cli.md b/docs/reference/cli.md
index e4bf5484..764fe5d1 100644
--- a/docs/reference/cli.md
+++ b/docs/reference/cli.md
@@ -1060,8 +1060,10 @@ Flags:
 
 ## See also
 
-- [processes](../behavior/processes.md): 7 shared source citations
-- [contract map](../insights/contract-map.md): 6 shared source citations
-- [module map](../architecture/module-map.md): 5 shared source citations
-- [impact analysis](../insights/impact-analysis.md): 5 shared source citations
-- [risk hotspots](../analysis/risk-hotspots.md): 3 shared source citations
+These pages cite many of the same source files as this one.
+
+- [processes](../behavior/processes.md)
+- [contract map](../insights/contract-map.md)
+- [module map](../architecture/module-map.md)
+- [impact analysis](../insights/impact-analysis.md)
+- [risk hotspots](../analysis/risk-hotspots.md)
diff --git a/docs/reference/public-api.md b/docs/reference/public-api.md
index da286336..e0b0782c 100644
--- a/docs/reference/public-api.md
+++ b/docs/reference/public-api.md
@@ -355,8 +355,10 @@ Uploads tar bytes for extraction under the requested remote directory.
 
 ## See also
 
-- [contract map](../insights/contract-map.md): 11 shared source citations
-- [module map](../architecture/module-map.md): 8 shared source citations
-- [processes](../behavior/processes.md): 7 shared source citations
-- [impact analysis](../insights/impact-analysis.md): 7 shared source citations
-- [system overview](../architecture/system-overview.md): 5 shared source citations
+These pages cite many of the same source files as this one.
+
+- [contract map](../insights/contract-map.md)
+- [module map](../architecture/module-map.md)
+- [processes](../behavior/processes.md)
+- [impact analysis](../insights/impact-analysis.md)
+- [system overview](../architecture/system-overview.md)
diff --git a/docs/reference/rpc-tools.md b/docs/reference/rpc-tools.md
index 6b3bcae0..4dcc808e 100644
--- a/docs/reference/rpc-tools.md
+++ b/docs/reference/rpc-tools.md
@@ -304,8 +304,10 @@ Uploads and extracts an uncompressed tar archive into the requested directory. `
 
 ## See also
 
-- [module map](../architecture/module-map.md): 11 shared source citations
-- [impact analysis](../insights/impact-analysis.md): 7 shared source citations
-- [processes](../behavior/processes.md): 4 shared source citations
-- [business logic](../insights/business-logic.md): 4 shared source citations
-- [debugging guide](../insights/debugging-guide.md): 4 shared source citations
+These pages cite many of the same source files as this one.
+
+- [module map](../architecture/module-map.md)
+- [impact analysis](../insights/impact-analysis.md)
+- [processes](../behavior/processes.md)
+- [business logic](../insights/business-logic.md)
+- [debugging guide](../insights/debugging-guide.md)