[Vivswan]

What this changes

before   docs/upgrading/v2-to-v3.md                        1298 lines, two under the 1300-line cap

after    docs/upgrading/v2-to-v3.md                         142   index: intro, summary table grouped by area, order of operations
         docs/upgrading/v2-to-v3/run.md                     242   sections 1, 4, 5, 6, 7, 8, 10, 13, 18, 22, 25, 26, 33, 34, 61
         docs/upgrading/v2-to-v3/settings-file.md           107   sections 2, 16, 32, 53
         docs/upgrading/v2-to-v3/layering.md                253   sections 3, 24, 28, 29, 30, 31
         docs/upgrading/v2-to-v3/sections.md                 76   sections 11, 12, 14, 15, 17, 19, 20
         docs/upgrading/v2-to-v3/refusals-repository.md     125   sections 37, 38, 39, 40, 44, 45
         docs/upgrading/v2-to-v3/refusals-lists.md          266   sections 36, 41, 42, 43, 46, 47, 48, 49, 50, 51, 52, 55, 57
         docs/upgrading/v2-to-v3/library.md                 196   sections 9, 23, 27, 35, 54, 56, 58, 60
         docs/upgrading/v2-to-v3/releases.md                 37   sections 21, 59

One summary row, before and after:

before   | `defaults-file` is a fallback | ... | ... under [section 1](#1-the-defaults-file-fallback) |

after    ## Run inputs and outputs

         The detail is in [v2-to-v3/run.md](v2-to-v3/run.md).

         | Break | v2 | v3 | What the old form does now |
         | `defaults-file` is a fallback | ... | ... under [section 1](v2-to-v3/run.md#1-the-defaults-file-fallback) |

How

• Each numbered section moves verbatim to one area page, keeping its number, title, and anchor.
• The index keeps the intro, the grouped summary table, and the order of operations.
• Only links moved: a cross-page section link gains its page, a ../ link gains a level.
• Two over-cap paragraphs are reshaped into bullets, a table, and quoted output.
• The docs tests walk docs/ recursively, so one path change covers the new pages.

Proof

• Heading census: 61 numbered headings before and after, identical; ## headings 62 -> 70.
• Line census: every old non-blank line lands on exactly one page after link normalization, bar the two reshaped paragraphs; new lines are structural, plus the row for 61.
• Tests: docs guides and readme suites green, 265 pass.
• Probe: docs-probe clean over all nine pages.

Technical details

• Grant: one region of test/docs/guides.test.ts, the readFileSync path in the wrapper-key fence assertion, repointed to docs/upgrading/v2-to-v3/settings-file.md.
• Corrected, forced by the move: the intro count and the missing row for section 61, which the base added without a summary row.
• Reshaped paragraphs: section 60's opening paragraph (110 words) is five bullets with bold lead-ins; section 61's opening paragraph (263 words) is a short paragraph, a grammar table, and its two output lines quoted in text fences; every fact kept.
• Area headings are plain text with the page link in the line under them, since the heading test refuses links in headings.
• The 8 area headings are the only ## headings added; the 62 old ones are kept with their text.
• Width: markdown is exempt from the fleet's 256 line cap; the old page carried 156 lines over it, the pages carry 159.
• Anchor census: the 61 section anchors are unchanged and each resolves on its page; the 6 cross-page section links and 16 ../../ links resolve (the anchor test).
• Front matter: every area page quotes its title, since two carry a colon.
• Line census detail: 966 non-blank lines before the split, 1045 after it; the one old line not carried over by the split is the count sentence, replaced by its sixty-one form; the reshape then replaced the two paragraphs with their devices.
• Probe cap: 70 words per paragraph or list item.
• Line accounting: docs/upgrading/v2-to-v3.md +98 -1254; the eight pages +1302 -0; test/docs/guides.test.ts +1 -1.
• Files: docs/upgrading/v2-to-v3.md, docs/upgrading/v2-to-v3/{run,settings-file,layering,sections,refusals-repository,refusals-lists,library,releases}.md, test/docs/guides.test.ts.
• Stack: the base is refactor/discovery-picomatch, the branch of the PR that adds section 61.

[github-actions]

File size check

0 over a hard cap (fails), 10 warning(s).

File	Size	Tier	Cap
.github/scripts/gen-inputs-table.ts:54	11 comment lines	warn	10
.github/scripts/release-pipeline.ts:1	34 comment lines (header)	warn	25
.github/scripts/release-pipeline.ts:453	14 comment lines	warn	10
src/discovery/discover.ts:91	11 comment lines	warn	10
src/github/secret-scan.ts:45	11 comment lines	warn	10
src/sections/contract/errors.ts:13	14 comment lines	warn	10
src/sections/shared/roles.ts:43	13 comment lines	warn	10
test/e2e/generators.ts	2634 lines	warn	2560
test/e2e/generators.ts:1667	12 comment lines	warn	10
test/sections/refusal-messages.test.ts:61	19 comment lines	warn	10

Split the file, wrap the line, shorten or exempt the comment, or list the path in .file-size-allow.local with a # reason.

5 managed file(s) skipped; repo-platform owns them.