Diffusion cookbook authoring contract

Use this contract for every model page under docs/cookbook/diffusion/<Vendor>/<Model>.mdx.

Opening structure

Import and render the shared tag widget immediately after frontmatter:

import { DiffusionModelTags } from '/src/snippets/diffusion/model-tags.jsx';

<DiffusionModelTags tags={["video + audio", "text-to-video", "reference control", "4–15 seconds"]} />

Use 4–6 tags, ordered from broad to specific:

1. output modality or product class;
2. primary request modes;
3. the capability that differentiates the model;
4. an important scale, latency, duration, resolution, or architecture fact.

Do not spend tags on generic claims such as native, fast, high quality, or SGLang. Attention backends, Cache-DiT, and online quantization are feature overlays, not model identity, unless a published checkpoint is intrinsically tied to that format.

The page must start with ## 1. Quick start: keep installation to one runnable command, add at most one short orientation paragraph, and render the scoped command builder before detailed capability tables or deployment commentary. A reader should reach a generated Serve command without scrolling through model background first.

Follow it with ## 2. Model capabilities and 2–3 short paragraphs:

• paragraph 1: what the model does and where it is genuinely strong;
• paragraph 2: when to choose it and the most important limitation or tradeoff;
• optional paragraph/table: checkpoint or mode routing that a user must understand before serving.

Keep the capability lead between roughly 45 and 180 words. Replace marketing superlatives with concrete capabilities. A reader should learn more than “this is a powerful image/video model,” but should not have to read the architecture section to choose the right model.

Scoped command builder

New diffusion pages use templates/diffusion-config.jsx.tmpl and opt into the shared commandBuilder renderer. Setup, Server, and Request choices share one semantic selection and one command composer; do not create a second command engine or assemble fragments in MDX.

Classify every dimension by lifecycle:

• scope: "base": the visible Setup tab—hardware-independent required decisions such as checkpoint weights and request mode. Hardware, Nodes × GPUs/node, and the recommended verified deployment are supplied by the shared builder.
• scope: "serve": startup flags such as placement, attention, precision, encoder scheduling, and graph execution. They modify only the complete Serve command.
• scope: "request": sampling fields such as quality and outputs. They modify only the complete Request command.

Keep the topology registry small and honest. verifiedRecipes contains only exact end-to-end runs on that hardware and resource shape. autoTopology(selection) may construct a legal custom shape, but resolveDeployment must mark it unverified unless it exactly matches a recipe. validateTopology returns static errors for impossible world-size, head, partition, or placement combinations; errors disable both Copy actions. Never silently label a nearby GPU or topology as verified.

Expose topology-dependent best values explicitly. A Server row may remain Auto, but its summary and generated flag must show the effective policy—for example, encoder auto resolving to replicate across nodes. Reserve disabled for combinations that cannot work (a kernel the platform does not ship, a mode the checkpoint cannot serve); an option that runs but has not been through a verification round should declare soft instead, which keeps it selectable and labels the pick as unverified. Keep torch.compile and similarly narrow experiments in the detailed prose until they have a broadly compatible recipe.

Each dimension should provide a concise description, an optional quality label, and a learnMore anchor. Each option should provide at most two lines of decision-relevant explanation, its exact flags/stripPrefixes/env/hints, and a disabled (with disableReason), soft (with softReason), or verifiedWhen predicate when support is conditional — the reason strings are user-facing: blocked options flash theirs under the row on tap and expose it as a tooltip. The builder stores all semantic choices in the URL hash; active scope, expanded state, head address, and node rank stay local.

Legacy configs without commandBuilder continue to use the old matrix renderer. Do not migrate an existing page opportunistically; use the new schema for new diffusion models and deliberate model-by-model migrations.

Review checklist

• tags render before section 1 and describe the model rather than the runtime;
• Quick start puts installation and the generated commands before detailed model background;
• the capability section explains strength and boundary without marketing filler;
• checkpoint variants and request modes are unambiguous;
• Setup keeps both commands visible as a deployment overview; Server and Request each show only the command controlled by that scope;
• command bodies grow naturally up to their collapsed limit and do not reserve empty height;
• topology-dependent recommended defaults are explicit in the setting summary and generated command;
• legal custom topologies are Unverified and copyable; statically illegal combinations block Copy;
• attention, quantization, caching, compile, and similar orthogonal features have explicit quality contracts and verified scopes;
• unverified hardware or performance claims are absent;
• node docs/scripts/check_cookbook_configs.mjs and Mintlify validation pass.