Absorb the writing-style rules; one word for a survey

[tobert]

Two things, and the first explains the second.

The style pointer has been dead since 2026-08-18

AGENTS.md said: "kaibo adopts kaish's docs/style.md — that guide names kaibo as an adopter… Read it before you write help text or operator docs."

Both halves are false. kaish deleted that file in e22b0be3 ("rearrange files and remove docs/style.md") and folded its content into its own AGENTS.md § "Writing style", which no longer mentions kaibo. So for three weeks every reader told to go read it — a fresh session, a subagent with no kaish checkout, a person — has found nothing. Amy asked whether we'd ever absorbed it, after noticing #183's config prose read "very Claude-compact". This is very plausibly why.

Absorbed into AGENTS.md directly rather than a new docs/style.md (Amy's call): one file, always loaded, nothing to fetch. It costs resident context and the trade is deliberate.

Only what kaibo didn't already have. "Fast and informative failures" is covered by our error-strings paragraph, "Write for model context" by the three-audiences block, and kaish's "Published builtin text" is clap/ParamSchema-specific — we have our own published/internal rule. New:

• Vocabulary choices — small vocabulary, plain words over figures of speech, American spelling. Framed on the reason that actually binds here: our synths are mostly not English-first.
• One term, one meaning — including the rule for a term that differs between published and internal text.
• Provide specific values — the exit code, the size, the default, the condition.
• The example is the rule — show the correct example first; make it carry the rule alone.
• A Terms table, seeded with twelve kaibo terms that carry a guarantee: backend, cast, slot, arm, lane, phase, survey, sweep, dossier, family, allowed set, published. It grows when a collision appears in real prose, not in advance — shaped to receive later analysis rather than to be complete now.

Two deduplications, because one term, one meaning applies to the guide itself: the family ruling restated what the table now defines, and the three-audiences block argued the non-English-first case in full — it now points at Vocabulary choices, where that argument lives once.

sweep and survey were two words for one thing

explore's tool description and CLI help say survey. The operator docs said sweep, 26 times, never defined. A calling agent reads the first and an operator reads the second, so the split was invisible from either seat.

survey wins in published text because it is already resident — it is in the front-door explore description every calling agent pays for each session. sweep stays the internal name in code (~450 uses, its own module). Converted 26 sites across README.md, config.example.toml, config.md, casts.md, rate-limits.md, sandbox-probes.md.

The verb sense is deliberately untouched, which is why this was done by hand rather than with sed. "Omit backend to sweep every configured backend" is ordinary English for iterating over all of something, not kaibo's noun — three sites keep it.

Not converted: ~25 occurrences in tool descriptions and clap doc comments in server.rs/cli.rs. They sit under the 2048-character resident budget and are the text the coming prompt work will most likely rewrite, so renaming them now would collide for no benefit. The Terms table states that the retirement is in progress rather than implying it's finished.

Suite: 1341 passed, 0 failed.

Overlaps #183 in docs/config.example.toml and docs/config.md — both sides now say survey, so the conflict is trivial whichever merges first.

🤖 Generated with Claude Code