Restructure docs across pages

The failure this skill prevents: an agent asked to "streamline this page" reorders its sections, collapses them into accordions, retitles them, and tabulates them, thirty times over, while the page gets longer. The page was never the problem. Three of its sections already existed on sibling pages.

Single-page skills cannot see that. add-docs-page owns one page's lifecycle and docs-edit owns one page's diff. This skill owns the question they cannot ask: is this content on the right page at all?

AGENTS.md holds the navigation map, the style guide, and the frontmatter rules. This skill covers the procedure around them and does not repeat them.

Step 1. Establish the page family

A page almost never lives alone. Find its siblings before reading it closely:

ls src/langsmith/llm-gateway*.mdx          # a flat-file family
ls src/oss/deepagents/                     # a directory family
grep -n '"langsmith/llm-gateway' src/docs.json   # what the nav groups together

The nav grouping is the better signal when the two disagree: pages a reader moves between are the pages whose content can be confused.

Then list every heading in the family, so you are working from the whole shape rather than one file:

grep -n '^## ' src/langsmith/llm-gateway*.mdx

Step 2. Build a duplication map before writing anything

This is the step that does the work. For each H2 in the page you were asked to fix, search the rest of the family for the same content:

grep -rn 'LANGSMITH_GATEWAY' src/langsmith/ --include=*.mdx
grep -rn 'Use a regional gateway' src/ --include=*.mdx

Search for the distinctive noun, env var, or endpoint in the section, not for its heading. Duplicated content is usually retitled, which is why heading searches miss it.

Record for each section: does this topic already live somewhere else, and where? Two copies that have drifted apart are the strongest finding available. It means no page owns the topic, so both copies are edited independently and readers get contradictions. In one real case the quickstart claimed TypeScript support for three providers while the sibling page said "Python only."

Report the map before editing anything. "Three of these six sections duplicate llm-gateway-api-formats" is the finding. The restructure is downstream of it.

Step 3. Assign one home per topic

For each topic in the map, pick the single page that should own it:

• Prefer a page that already exists. A new page is warranted when the topic has no home and does not fit an existing one, not when it merely needs somewhere to go.
• Prefer the page a reader would search for, not the page the content happens to sit on.

• Keep the most-linked URL. Check before choosing, because inbound links decide which file survives a merge of two pages:

  grep -rn '(/langsmith/llm-gateway)' src/ --include=*.mdx | wc -l

  Folding content into the well-linked page and retiring the other one is usually cheaper than the reverse.

Step 4. Cut, do not relocate

A section that duplicates a sibling gets deleted and replaced with one sentence pointing at the owner. It does not get moved, collapsed into an accordion, or shortened in place. An accordion still costs the reader the decision of whether to open it.

Content that has no home yet moves. Content that has one is already written.

When you delete a section whose facts differ from the sibling's, the difference is a bug in one of them. Resolve it against the source before deleting, or you silently pick a winner. See docs-edit for the verification procedure.

Step 5. Mechanics

Retiring, renaming, or creating a page means navigation entries, redirects, and inbound links. add-docs-page covers all of it, including the anchor-stability and snippet traps. Follow it rather than improvising here.

Two additional things a restructure breaks that a single-page edit does not:

• Section anchors other pages link to. Moving a section moves its anchor. Grep for #the-anchor across src/ before the move and repoint every hit. A <Step> or <Accordion> can carry an explicit id to preserve a landing spot that is no longer a heading.
• Cross-page pointers that now point at the wrong page. After moving a topic, the sibling pages that used to reference its old location need repointing, not just the page you edited.

Step 6. Verify

make lint_prose FILES="<changed files>"
make build
make broken-links-with-anchors
python3 scripts/check_removed_pages_redirects.py --base-ref origin/main src/docs.json

Read broken-links-with-anchors by skipping to the ⎿ lines; those are the only real failures. Compare the count against the same command on origin/main so a pre-existing baseline is not read as a regression.

Then review the prose with the docs-review skill, scoped to the files this pass changed.

Step 7. Report what moved

State, per page, what was deleted, what moved, and what was added, with before and after line counts. A restructure that cannot show a page getting shorter has not restructured anything, and the line counts are what show the reviewer whether it did.

Name what you deleted rather than only what you wrote. A reviewer who asked for a shorter page needs to see the cuts to agree with them.

Scope

Stay inside the page family named in the request. A restructure surfaces adjacent problems: stale model IDs, legacy version numbers, and the same duplication one directory over. Report them, and ask before widening the sweep. Fixing sixteen instances across a page family is a reasonable follow-on inside one pull request. Fixing six hundred across the corpus is a separate pull request and probably a tracked issue, because some instances are deliberate and some live in generated files.

Checklist

• Page family established from src/docs.json, not guessed from filenames.
• Duplication map built and reported before any edit.
• One owner chosen per topic; most-linked URL identified before merging pages.
• Duplicated sections deleted and replaced with a pointer, not relocated.
• Conflicting facts between copies resolved against source, not by picking one.
• Redirects, nav entries, inbound links, and section anchors all updated.
• Verification commands run, ⎿ count compared against origin/main.
• Report gives per-page before and after line counts.
• Anything outside the page family reported, not swept, unless asked.