Docs Restructure

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.