[bonk-ai]

What and why

The 30 pull requests merged since 279f28f (#618 to #655) moved lines in the source files the hand-written pages cite, so 610 path:line citations on 19 pages pointed a few lines off while still resolving, which docs:check cannot see. This re-points them. Eight citations sat in sentences the new code makes false or incomplete, so those sentences change with them, each worded from the code it cites. The branch starts from main at 9eef8f0; only Markdown under docs/ and the ceilings in .vale/warnings.json change.

How each move was found

For every citation, blame-shift-citations-2026-10-12.py (in the nightly job's workspace) takes the doc line's git blame commit as its baseline, reads the cited block there, and looks for the same text at HEAD. It reported 647 citations whose block is no longer at the cited lines: 460 with one exact match elsewhere, 121 with several, and 66 with none. Each match was then checked against git's own line mapping: git diff -U0 <baseline> HEAD -- <file> maps every cited line outside a changed hunk to its HEAD line, and a citation moves only when that mapped range is one of the exact-text matches. That settled 580 rows. The CONTRIBUTING.md:146 row is an example mutants.out line, not a citation, and stays.

A second pass found two citations the first one counts as current. cli.md:577 (--state-dir) and cli.md:757 (--delete-image) cite an #[arg(long)] line that still sits at the cited number, while the field it belonged to moved nine lines down. The probe now also reports a repeated line that matches at its own number, and the same diff mapping moved exactly those two.

Of the 67 rows without a settled match, comparing with version numbers normalized cleared 29 Cargo.toml rows whose cited lines are right and only carry a new version or feature. A read-only audit of the other 38, each against its doc sentence, found 7 still right, 23 moved, and 8 contradicted.

Moves by page

Page	Moves
docs/reference/cli.md	182
docs/behavior/processes.md	102
docs/reference/rpc-tools.md	58
docs/diagrams/behavioral/sequences.md	33
docs/insights/contract-map.md	32
docs/diagrams/architecture/components.md	30
docs/diagrams/structural/dependency-graph.md	27
docs/architecture/data-flow.md	23
docs/insights/debugging-guide.md	21
docs/architecture/system-overview.md	20
docs/analysis/risk-hotspots.md	19
docs/insights/business-logic.md	17
docs/reference/public-api.md	15
docs/insights/impact-analysis.md	12
docs/analysis/dead-code.md	7
docs/insights/tech-debt.md	6
docs/behavior/state-machines.md	3
docs/architecture/module-map.md	2
docs/analysis/ownership.md	1

Most cite crates/microvms-cli/src/cli.rs, crates/microvms-app/src/sandbox.rs, crates/agentd/src/exec.rs and crates/microvms-app/src/session/mod.rs. On cli.md, every flag bullet's citation was read back at HEAD: 483 land on the #[arg] of a field named for the bullet's flag, and the other four are fields spelled differently from their flag (--tag is tags, --for is for_sec, and --egress-network-connector is egress_network_connectors twice). On dependency-graph.md, each third-party crate's table citation lands on that crate's declaration line, and each workspace crate's row cites the dependency line it describes.

The changed sentences

• docs/architecture/data-flow.md, upload step 3: Session::upload_file now calls upload::upload (crates/microvms-app/src/session/mod.rs:534-541), which reads GET /v1/health once per session and, with the default-user header present, runs id -u; id -g as that user (crates/microvms-app/src/session/upload.rs:57-102). With no header or a root default user it calls files::upload_file directly. Otherwise root stages the bytes in a private directory, hands them to the default user, and an exec as that user installs them (crates/microvms-app/src/session/upload.rs:104-166).
• docs/architecture/data-flow.md, launch step 6: Sandbox::wait_until_running now waits through wait_for_sandbox_launch and wait_for_launch_inner (crates/microvms-app/src/control/microvm.rs:628-689), so the citation moves there from wait_for_state. The sentence itself still holds.
• docs/diagrams/behavioral/sequences.md: the launch wait's "running VM" return is "RUNNING" => return Ok(got) in that loop (crates/microvms-app/src/control/microvm.rs:655).
• docs/behavior/processes.md, resume step 4: a handle that still holds Running now reads the service state first (crates/microvms-app/src/sandbox.rs:1683-1714), and a VM the service reports as ended records Terminated and fails with WindowClosed, before the not-suspended check (crates/microvms-app/src/sandbox.rs:1715).
• docs/architecture/module-map.md: agentd's module list gained poweroff ("Optional guest shutdown, performed by the daemon after observed group completion", crates/agentd/src/poweroff.rs:2), so the agentd sentence names that responsibility and the page's module pointers gain poweroff.rs:2.
• docs/insights/contract-map.md: the StartRequest shape gains poweroff_on_exit with its skip_serializing_if = "is_false" attribute (crates/protocol/src/exec.rs:284-285).
• docs/reference/rpc-tools.md: the optional StartRequest fields gain poweroff_on_exit; the dispatcher serves GET /v1/health through health_response (crates/agentd/src/routes.rs:179), and a new paragraph names its two headers, microvms-default-user-configured and microvm-poweroff-on-exit (crates/agentd/src/routes.rs:414-429, crates/protocol/src/health.rs:9-16), and the client check that reads the second (crates/microvms-app/src/session/mod.rs:462-477).

Splitting the rpc-tools.md intro sentence removed one semicolon, and the branch's warning counts sit below four ceilings in .vale/warnings.json, so those ceilings drop to the counts: Readability.AutomatedReadability 35 to 34, Readability.FleschKincaid 38 to 37, ai-tells.SemicolonUsage 293 to 291, and write-good.Passive 509 to 507.

Evidence

• mise run docs:check on this branch: EXIT=0 in 149 s; astro check 0 errors, and vitest 15 files, 223 tests passed.
• mise run prose:check on this branch: EXIT=0 in 41 s, "Prose: 0 errors, 4063 warnings, 0 suggestions." tools/prose.py --lint on main and on this branch differ only in one fewer ai-tells.SemicolonUsage warning on rpc-tools.md.
• Seeded-fault anchors: no transform in verify/guards/faults/*.toml names an edited file.
• Every moved range was dumped with its first and last HEAD lines in the job's evidence directory (moves-verify-2026-10-15.txt, moves-audited-verify-2026-10-15.txt, hand-edits-verify-2026-10-15.txt), and every audited move and changed sentence was read by hand.
• mise run pr-body:check -- --body <this body>: PR_BODY_LINE
• mise run check on main at 9eef8f0: EXIT=0 in 330 s. Not rerun on this branch, which changes only Markdown under docs/ and one JSON ceiling file; prose:check is the check tier that reads them.

Guards

None: this adds no guard.

Follow-ups

• docs/diagrams/structural/dependency-graph.md:97 lists nix with 5 edges; crates/agentd/src/poweroff.rs:63 adds a sixth source path, and the declaration gained the reboot feature (crates/agentd/Cargo.toml:63). The page's edge counts are hand-written, which AGENTS.md's counts rule leaves to whoever regenerates the page.
• crates/agentd/Cargo.toml now declares rustix, and dependency-graph.md does not show it.
• docs/insights/contract-map.md's StartRequest consumer list does not name crates/microvms-app/src/session/upload.rs:17, which builds one for the ownership handoff.

Platform claims

• Not applicable: this changes no claim about AWS behavior.

Scope

• This is not an orchestrator or a fork implementation
  (see docs/STRATEGY.md).