Neighbors can suggest a default. They cannot answer for the user.

Send a message that contains only:

1. The tone you inferred from neighboring pages, in one line (how formal, how much setup, second person or not).
2. One question with options: use that tone, more casual, more formal, or the user names another.

If the harness has an AskQuestion (or similar) tool, use it. If it does not, use a numbered list.

Then pick one path:

Default: stop. This message is the entire turn. End the turn. Do not write page content.

Skip the wait: continue in this same turn. Use this path only when one of these is true:

• This conversation already has the user's tone choice, including an explicit "match the existing pages".
• The user said "use sane defaults", "just write it", or "don't ask questions". Still STATE the inferred tone in one line, then continue.
• Tiny copy edit, same carve-out as the persona gate.

On this path, do not end the turn. After you state the tone (or after a tiny copy edit, with no question), continue to Phase 2.

These are not skips:

• "I can tell from the neighbors."
• "The site already has a voice."
• "Tone does not matter for a reference page."
• "I'll match neighbors and mention it later." </HARD-GATE>

Phase 2: write like a human

Do not write page content until the persona gate has passed, the tone gate has passed, and simple-english plus i-have-adhd are loaded.

The tone gate is the heading above this one. Run that gate first. Then load the two skills. Then write.

Legibility is the goal, above everything else.

• Keep it digestible. No walls of text, no huge paragraphs. Break ideas into small pieces. Give the smallest amount of info that does the job.
• Sentences follow simple-english (pragmatic mode). Do not inline a weaker substitute.
• Keep markdown light. Lists are fine. Bold headings on every line are not. Let the words carry the page.
• Prefer plain ASCII and normal keyboard characters over fancy glyphs. Write the way a person types.
• Second person, action first. Start with what the reader has now and what they will have at the end. No "In this guide we will explore..." openings. Just start.
• Shape the page with i-have-adhd: the first line is something the reader can do, multi-step work is numbered, a list longer than 5 is split, the page ends on a visible win.

Lead with the problem, then solve it

Every page opens with the problem the reader came for, in their own words, before any API. Name the situation they are stuck in. Then say in a sentence or two how the feature solves it. Only after that do you go into the technical parts and the code.

A reader who sees the problem first knows in seconds whether they are on the right page. A reader who hits an API signature first has to reverse-engineer what it is even for.

The first line of the how is the next action (from i-have-adhd). The problem still comes first so they know they are on the right page.

Bad:
  Call useInterrupts() and pass a resolver. The resolver runs once per
  pending item inside a transaction...

Good:
  Some tool calls shouldn't run without a human saying yes: moving money,
  deleting data. An interrupt pauses the run for that decision, then picks up
  where it left off. Here is how to gate a tool behind an approval:

  [code]

The order for a guide is problem, one-line fix, then the how (steps, snippets, API). Keep the problem to a couple of sentences, not a background essay. The code shows how it is solved, so do not narrate the solution in prose first.

Show, do not tell

Do not explain in four paragraphs what one sentence and a code block can show. Readers grasp a diff or a snippet faster than prose.

Bad:
  Three paragraphs describing how the config object accepts a
  middleware array, what each slot does, and how ordering works.

Good:
  Add your middleware to the `middleware` array. Order runs top to bottom:

  const app = createApp({
    middleware: [auth, logging],
  })

One good runnable example beats a page of description. Every code sample must run when copied, not need imagination to fill gaps.

List anything that is a list

The moment a sentence covers more than one item, option, store, flag, or step, it becomes a list. Do not chain them into a paragraph with commas and semicolons. A reader scanning a bulleted list finds their item in a second. In a paragraph they have to read the whole thing to learn it does not apply to them.

The tell is a sentence that names two or more things and says something about each. Cut it into one bullet per thing, one or two sentences each.

Bad:
  Each store is independent. Provide only the ones you need. For chat:
  `messages` for the transcript, `runs` for run lifecycle, `interrupts` for
  durable approvals (needs `runs`), `metadata` for namespaced key/value state.
  For generation: `generationRuns` for the run lifecycle, plus `artifacts` and
  `blobs` to keep generated bytes.

Good:
  Each store is independent, so provide only the ones you need.

  For chat:

  - `messages`: the transcript.
  - `runs`: run lifecycle.
  - `interrupts`: durable approvals. Needs `runs`.
  - `metadata`: namespaced key/value state.

  For generation:

  - `generationRuns`: run lifecycle for a generation.
  - `artifacts` + `blobs`: keep the generated bytes.

Which form to reach for:

• Bullets for a set where order does not matter: options, stores, fields, reasons, gotchas.
• Numbered steps for a sequence the reader performs in order.
• A table when every item has the same two or three attributes to compare (name, meaning, when to use).
• A paragraph only for a single idea that genuinely flows as prose. One thought, two or three sentences, no embedded set.

Keep bullets short and parallel: the same grammatical shape, the item in code or bold at the front, the explanation after it. A bullet that grows past two sentences wants to be its own subsection.

If a list grows past five items, split it. Put "do now" first. Put the rest on a later page, or under "later". That is the i-have-adhd cap, not a style preference.

Page shape for a guide

Problem, fix, steps, done.

• Open with the problem the reader has, in their words, and what they will have at the end.
• Say in a sentence how the feature solves it.
• Walk through steps they can follow and test as they go, with the code doing the explaining.
• End when they reach the goal. Show what now works. Do not close with a vague "next steps" dump.

Reference pages (props, types, signatures) stay scannable and link back to the guide that shows them in use.

Write for the reader, not the history

Docs describe what exists now. The reader never saw the old design, the earlier name, the draft PR, or the API you replaced along the way. Do not make them read about it.

Never justify the current API by comparing it to a version that did not ship. A line like "instead of useAssistant, this uses usePlugin, which makes more sense because..." is noise to someone who never knew useAssistant existed. Cut it and just describe usePlugin.

Bad:
  We renamed useAssistant to usePlugin and moved the tools onto it,
  so instead of calling assistant.addTool you now use plugin.tools.

Good:
  Register tools on the plugin with plugin.tools:

  const plugin = usePlugin({ tools: [search] })

Ban this framing from the output: "instead of X", "we renamed", "previously called", "this replaces the old", "unlike the earlier", and any transitional name that never reached a release.

The one exception is a real migration. If users had X in a shipped, public release and you are moving them to Y, a short "Migrating from X" note is worth writing, because those readers actually used X. A name that only lived in a branch or a draft is not that. When unsure whether an old name shipped, leave it out.

Don't leak the build process

The doc is read by someone who just arrived. They never saw the pull request, the refactor, or the conversation where the design was decided (including a conversation with an agent while writing the code and the docs). Write as if the current design was always the design. Anything that only makes sense to someone who watched it change is noise to the reader.

Cut rejected alternatives. If a discussion weighed option A against option B and picked B, the doc documents B. It never names A, never says B is "better than" A, never says A "is no longer needed." The reader is not choosing between them; they use what shipped.

Bad:
  We use a plain JSON Schema here instead of zod, since it is lighter
  and zod is no longer a dependency.

Good:
  Pass the tool's input shape as a JSON Schema:

  [code]

Do not explain what something is not, when the reader never thought it was. If a piece moved out of a module during a refactor, the doc for its new home does not warn against the old arrangement. A reader who never knew locks lived inside persistence is only confused by a paragraph insisting locks are not a persistence store and must not be passed in as one. State what the thing is now, in its own terms.

Bad (in the locks doc):
  Locks are not a persistence store. Do not pass a lock into the stores
  map. That used to be possible but is wrong now.

Good (in the locks doc):
  A lock coordinates work across instances. Wire it with withLocks:

  [code]

The test: read the sentence as a brand-new user. If it answers a question they would never ask ("wait, was this somewhere else before?") or defends a choice they never knew existed, delete it. The doc has no memory of how it got here.

Forbidden

Never use these. Ever. This list has no exceptions: not "the neighboring pages use them", not "the repo's house style uses them", not "it reads better here".

• Em dashes and en dashes: the long — and the shorter –. Rewrite the sentence with a comma, colon, period, or parentheses instead.
• Separator glyphs like × or ·.
• The pattern "It's not X: it's Y." and the "Not just X, but Y" three-part build-up.
• The phrases "key insight", "gap", and variations of them.

If you catch yourself reaching for one of these, stop and rewrite the sentence in plain words.

Before you call a page done, search your own added text for —, –, ×, and ·. If a hit survived, you rationalized it. Fix it. Flagging it in your summary is not a substitute for fixing it.

Then run the simple-english self-check on the same added text.

Cross-linking and placement

• Put new pages where they fit the reader's path, grouped by what the reader is doing ("Building with React"), not by code layer ("Frontend Package API"). Update the site's nav or index so the page is reachable. An orphan page does not ship.
• Link related pages at the moment they help, inline in the flow, not as a "Related" dump at the bottom.
• Cross-linking goes both ways. When you add a page, update the older pages that should point into it.
• Do not over-link. One well-placed "need X? see Y" beats a list of maybes.

Red flags