Writing Style & Quality Bar

How every page here is written. This is a standard, not a suggestion — the QC checklist at the bottom is a gate, not a vibe. Capabilities (plugins, components, tokens) live in Site Authoring Capabilities; this page is the voice + structure.

AI agents — read this first

Cursor, Claude, Codex, and other agents: follow AGENTS.md + Writing style + Authoring capabilities first. Optional digest: AI writing contract when that page exists and is fresh (compare to astro.config.mjs / package.json — see starlight-content-author skill). Editorial color, plugin mechanics, and the mandatory visual warrant test are binding regardless of system_docs.

Provenance

Adapted from the “Ward” documentation standard. Its principles (density, action-first, numbered steps, QC gate, anti-patterns) are kept. Its Notion-specific mechanics are translated, not dropped: Ward’s color-coded heading backgrounds become the editorial heading hierarchy below (a tiered band system in the brand palette, not 6 clashing colors); its callout color codes become Starlight admonitions; its toggles become <details>.

Voice

• Concise, high density. Every word earns its place. Cut filler (“in order to” → “to”).
• Active voice, action-first. Lead with the action, then the why if it’s not obvious.
• Tight paragraphs — 3–5 sentences max; if one runs longer, split it or turn it into a list. Walls of text are a defect.
• Sparing emoji. This is an editorial site, not a Notion page. An occasional sidebar icon is fine; emoji-per-bullet is not.
• Reuse before you write. Check existing docs, _INBOX/2-Research/, and existing components/templates before authoring something new.

Reader profiles (write for all of these at once)

Every page serves several readers in one layout — not separate versions. Structure is the accessibility layer:

Profile	What they need from the page	How we serve it
Beginners / new to the concept	Plain terms, no assumed jargon, “done” defined	TL;DR or intro states goal + who + done-when; define terms on first use; link to Learn concepts for depth
ADHD-friendly execution	One idea per block, visible progress, no buried actions	Numbered steps; short paragraphs; checklists with - [ ]; :::next / :::start; est-time in frontmatter where relevant
OCD / perfectionists / “did I miss anything?”	Exhaustive gates, nothing implicit	Checklists at step bottoms; # Expected: after commands; explicit skip/optional in <details>; ledger-style “verify” bullets
Visual learners	See the shape before the details	Warrant-test diagrams; numbered correspondence (step 3 in prose = node 3 in diagram); one hero visual per major section
Text-first learners	Scannable prose + tables	Dense but short paragraphs; comparison tables; glossary rows; don’t replace prose with diagram-only pages
Structure seekers	Predictable sections per doc type	Use the doc-type spine for that kind — same headings every time so they know where to look

Confidence, not clutter: “Max granularity” for beginners means don’t skip trivial steps (open the folder, save the file) — not repeating the same callout on every step. Actor legend (🤖/👤/🔀) once per playbook; :::note[For beginners and agents] once under TL;DR on step pages.

Structure

1. Numbered steps for any procedure. If text introduces an action, it’s a numbered step — not a bare heading.
2. Sub-steps are indented numbered lists under their parent step.
3. Dividers (---) between major H2 sections and after an opening summary callout.
4. Reach for lists to break up density — numbered lists for sequences/procedures, bullets for unordered sets. When a paragraph stacks 3+ parallel points, it’s a list, not prose. (Just don’t bullet a single idea or wrap every sentence — that’s Notion-decoration, not structure.)
5. Lead each page with one or two sentences of what it is and who it’s for.
6. No callout immediately after a heading. The first block under ## or ### must be prose (at least one sentence) — not a ::: admonition. Section context (especially ## Background) belongs in paragraphs; use callouts for actor legend, per-step “who does this”, tips, and gates — after that intro sentence.
7. No back-to-back callouts. Never place two admonitions / ::: blocks directly adjacent — put prose (or a heading) between them. Two stacked callouts are a smell: merge them into one, or add the content that justifies two. (A :::note[Who does this] sits after the step’s intro sentence — never against another callout.)

Formatting toolkit (headings, lists, emphasis)

Use Markdown structure first; reach for Starlight components when they add scanability (.mdx only). Live reference: Worked example — Build an MCP server · Examples shelf.

Headings (# → ####)

Level	Role	Example
# H1	Page title (from title frontmatter — do not repeat in body)	—
## H2	Major sections — teal band	## What you'll learn, ## Before you start, ## Summary
### H3	Subsections under one H2 — gold band	### 1. Generate the index, ### Keyword search
#### H4	Rare detail under H3 — amber band (smallest)	A single sub-point; if you need many, split the page

Rules: sequential levels only (## then ###, never ## → ####); one visual idea per heading; verb-first headings on procedural sub-steps.

Lists — pick the right shape

Need	Use	Example
Unordered set (no sequence)	- bullets	Prerequisites, feature lists, “gotchas”
Ordered procedure (plain .md)	1. numbered list	Short sequences inside a ### step
Nested detail	Indented sub-bullets or sub-numbers	- Parent → - Child (2 spaces indent)
Tight UI procedure (.mdx)	<Steps> wrapping <ol>	3–8 substeps with one action each — component library
Playbook progress (multi-page)	<Stepper> / phase nav	Wired on playbook hubs — not on every guide
Verification / “did I miss anything?”	- [ ] task list	Checklists, sign-off gates
Glanceable matrix	Markdown table	Comparisons, command lookup

When a paragraph stacks 3+ parallel points, make it a list. Don’t bullet every sentence (Notion-decoration).

Emphasis & highlights

Intent	Use	Not
First mention of a term	**bold**	ALL CAPS
Code, paths, flags	`inline code`	bold for file names
Status in prose (.mdx)	<Badge text="…" variant="…" />	emoji badges
Evidence / labels (.mdx)	<span class="zaj-badge zaj-badge--current">	hand-colored text
Callout / highlight block	:::tip, :::note, :::caution, :::danger	colored HTML spans
Optional deep detail	<details><summary>…</summary>…</details>	hiding required steps

Bold marks the keyword in a sentence once; don’t bold whole paragraphs.

Components vs markdown (.mdx)

Situation	Prefer
Hub of next links	<CardGrid> + <LinkCard>
Folder layout after a build	<FileTree> + caption
Same steps, different tools	<Tabs> / <PackageManagers>
Entry / exit of a page	:::start / :::next
Section is teaching + long prose	## + paragraphs + diagram — not forced <Steps>

See Starlight mechanics and Doc-type spines for which spine uses which building blocks.

Playbook step pages (required shape)

Any step / procedural page — numbered playbook steps (stepNumber in frontmatter under build/playbooks/), plus step-guides, SOPs, and runbooks that walk through a procedure — uses one consistent heading spine, beginner-readable and agent-parseable:

1. ## TL;DR — the first section after frontmatter (a plain heading, not a :::summary callout). Lead with the goal/objective — one sentence naming the outcome this step achieves — then who it’s for and what “done” looks like (1–3 sentences total). Directly under it, a :::note[For beginners and agents]: read the TL;DR → do the steps in order → run the checklist before advancing; agents treat an unchecked box as a blocker and cite command output (# Expected:).
2. ## Background (optional) — context, prerequisites, or scope before acting. Plain prose under the heading — not a callout. Omit the section when it isn’t needed; the spine is then just ## TL;DR → ## Steps (two section headings, plus the checklist).
3. ## Steps — the procedure, as ### sub-steps whose headings are action-oriented (verb-first): ### 1. Set up the GitHub CLI (gh), not ### 1. GitHub CLI. Under each sub-step heading, write 1–2 sentences on what it does and why, then the action. After every command code block, show the expected result — a # Expected: comment inside the block and/or an indented bullet list beneath it (- Expected: you should see …). Steps are 🤖 agent-doable by default; add a :::note[Who does this] callout (below) only for 👤 User / 🔀 mix steps.
4. ## Checklist — at the bottom, intro “Do not mark this step done until every box below is checked,” then - [ ] items only (no ✅ prose gates, no bare ## Gate). End the page with a :::next[Next step] link to the next step (or phase hub).

“Who does this” — flag the human’s manual parts. Steps are 🤖 agent-doable by default, so a pure-agent step needs no marker. Add a compact :::note[Who does this] callout only when a step needs a 👤 User action (browser, password, dashboard, API key, OAuth) or is a 🔀 mix — placed right after the step’s intro sentence. State the legend once near the top of the playbook (a :::note with these sub-bullets), not on every page or step:

• 🤖 Agent — an AI assistant can run it in the terminal.
• 👤 User — a person only (browser clicks, passwords, dashboards).
• 🔀 User + Agent — a mix.

Write the steps tool-agnostic: they read the same whether a person follows them alone or an AI assistant does — the callout only flags where a human must act. Keep it a compact one-liner, and never stack two callouts back-to-back (see Structure).

Rename, don’t duplicate: an old :::summary[TL;DR] callout becomes the ## TL;DR heading; ## Completion checklist becomes ## Checklist; legacy ## Gate / ✅ lines become - [ ] checklist items. Template: Playbook step template.

Doc-type page spines

Use the spine that matches kind and shelf (see content architecture). Templates live under Templates. Do not force a playbook step shape on a handbook or cheatsheet.

Type	Shelf	Required / typical sections	Template
Playbook step	Build	## TL;DR → optional ## Background → ## Steps → ## Checklist + :::next	playbook-step
Playbook overview	Build	Outcome → stage diagram → phase <Stepper> → phase CardGrid → related playbooks	playbook-overview · example
Playbook phase hub	Build	Phase purpose → diagram/FileTree → phase <Stepper> → kit shortcut → sub-step list	playbook-phase-hub · example
Runbook	Build	## TL;DR (one operation) → ## Prerequisites → ## Commands → ## Verify → optional ## Rollback	runbook
SOP	Build	## Purpose → ## Scope & roles → ## Procedure → ## Evidence / records → ## Checklist	sop
Checklist	Build	Intro (what this verifies) → grouped - [ ] sections → ## Sign-off	checklist
Blueprint	Build	Problem → constraints → decisions → architecture diagram → open questions	blueprint
Handbook hub	Learn	Eyebrow → map/diagram → CardGrid → chapter table	handbook-hub
Handbook chapter	Learn	Why it matters → concept sections (each with diagram if warranted) → comparison table → :::tip / Related	handbook-concept
Guide	Learn	:::start → ## What you'll learn → ## Before you start → numbered ## sections → ## Summary	guide · example
Concept	Learn	One-sentence definition → ## Why it exists → ## How it works (diagram) → ## When to use / avoid	concept
Research	Learn	Question → sources/method → findings → implications → links	research
Case study	Learn	Context → what happened → decisions → outcome → reuse	case-study
Kit page	Resources	What it shortcuts → Prerequisites → Download → ## Steps → <FileTree> → placeholders → Verify → playbook links	kit-page · example
Cheatsheet	Resources	One-line scope → tables / command lists → link to playbook/runbook for context	cheatsheet
Reference meta	Resources	Purpose → inventory/table → usage → related	reference-meta
Asset starter hub	Resources	One asset per page; hub lists files + when to use	template-starter-hub

Playbook set: overview · phase hub · step — three templates, not one. See Build templates registry.

When a type isn’t listed, pick the closest spine and note the choice in the intake ledger — don’t invent a one-off structure without reason.

Code, file trees, and build pages

When the page involves creating, moving, or wiring code or folders:

1. <FileTree> (.mdx) — show the target tree after the change (what exists when done), not only a single file. Pair with a one-line caption: “After this step, your repo looks like this.”
2. One command block per action — language set; # Expected: or - Expected: after every runnable command.
3. Visual for flow — if the change spans multiple files or services, add a Mermaid sequence/graph or a ~/components/diagrams/* figure (see Visual inventory).
4. Dev ergonomics in technical docs — when the source discusses debugging or ops, include a short Dev notes subsection (collapsible <details> is fine): where logs live, what to grep, env-specific flags, “safe to retry” vs “stop and rollback.” Prefer modular, scalable patterns in examples (small functions, clear boundaries) — not monolithic paste-ins.

Never link _INBOX/ paths or machine-specific absolute paths from published pages.

Visual inventory — reuse before you draw

Shipped diagram components (~/components/diagrams/, gallery in Doc components):

Component	Use when
DiagramFigure	Frame + caption for any inline SVG
RuntimeOwnership	Single runtime authority / request flow
PackageBoundary	What talks to what / ownership
StageFlow	Horizontal pipeline (labels only)
LayerStack	Tiers / layers
StepStack	Vertical numbered procedure
Timeline	Phases over time
PatternPair	Before↔after or don’t-do / do-instead
ContentDecisionTree	Branching decisions

Also: Mermaid fences (orthogonal stepAfter), .zaj-diagram-* inline SVG classes in diagrams.css.

Encourage new visuals when no component fits — add a parameterized .astro under src/components/diagrams/ rather than a screenshot. Run the full visual QC gate in authoring-capabilities before ship.

Engineering & source hygiene (technical content)

When intake material describes application code, deploy scripts, or agent config (not just prose docs):

• Sources outside _INBOX/ — still classify, ledger, and route; never paste vendor dumps verbatim into published pages without synthesis.
• Modular & scalable — examples should match how the repo actually ships: small units, clear boundaries, no god-files; call out extension points.
• Best-practice bar — auth/secrets via env (placeholders in docs); idempotent scripts where possible; migrations and rollbacks called out explicitly.
• Debugging & logging in dev — document where to look (log path, storage/logs, Vite overlay, --verbose flags) and what success looks like in output — same # Expected: discipline as shell commands.

These belong in Background, Dev notes, or handbook sections — not as a substitute for numbered steps on procedural pages.

Heading hierarchy

This is the on-brand translation of Ward’s colored heading backgrounds. You do not add colors yourself — the theme styles each Markdown level automatically (theme.css §3), so heading depth reads at a glance without garish per-level color tags:

Level	Renders as	Use for
# H1	Big editorial display + coral band (page title from frontmatter; don’t repeat # in body)	One per page.
## H2	Teal section band — accent rail + left-anchored wash	Major sections (Ward’s H1/H2 role).
### H3	Gold section band — same pattern, smaller	Sub-sections under an H2.
#### H4	Amber detail band — smallest wash	Rare. Frequent #### means split the page rather than nest deeper.

Rules:

1. Never skip a level (no ## → ####). Depth must be earned.
2. One # per page. Subsequent sections start at ##.
3. If you reach for #### often, split the page — deep nesting is the docs-site equivalent of Ward’s “H5/H6 = restructure” signal.
4. Don’t fake heading color with inline HTML/styles. The level is the color. For an emphasised callout, use an admonition (below), not a tinted heading.

Editorial color & badges (plugins + theme)

Agents and authors get color from structure, not from picking hex values.

Automatic (no extra markup)

Mechanism	What colors	How to set
## / ### / ####	Teal band / gold bar / muted kicker	Markdown level only (theme.css §3)
<p class="eyebrow">…</p>	Gold uppercase kicker	Once near top of hub/long pages
status: frontmatter	Badge on page title	current · target · future · draft — starlight-heading-badges
sidebar.badge	Colored label in nav	{ text: …, variant: tip|note|caution|danger|success }

Author chooses type (still token-themed)

Mechanism	Use for	Syntax
Starlight admonitions	Info / tip / caution / danger	:::note … or <Aside type="tip"> in .mdx
GitHub alerts	Same, in plain .md	> [!NOTE] — starlight-github-alerts
Custom blocks	Ideas, decisions, page structure	:::idea · :::decision · :::start · :::next · :::summary — starlight-markdown-blocks
<Badge> component	Inline status in prose	.mdx — see Component library
zaj-badge--* spans	Evidence-style inline labels	<span class="zaj-badge zaj-badge--current"> in .mdx

Never hand-apply #hex, style="color:…", or Notion-style colored text on headings.

Starlight mechanics (use these, not Notion-isms)

Ward’s color-coded callouts and toggles map to native Starlight features (heading colors are handled by the hierarchy above):

You want	Use	Not
Emphasis box	:::note / :::tip / :::caution / :::danger (or > [!NOTE] via starlight-github-alerts)	Inline-tinted headings / Notion color tags
Status on a heading/page	status: current|target|future|draft (heading badges)	Manual color tags
Collapsible / optional detail	<details><summary>…</summary>…</details>	Notion toggles
Brand color anywhere	a --zaj-* / --sl-* token	Hardcoded hex
Diagram	Mermaid fence or a diagrams/*.astro SVG	Pasted raster screenshot of a diagram
Hub of links / a CTA	<CardGrid> + <LinkCard> / <LinkButton> (.mdx)	A bare bullet list of links on a landing page
Per-tool alternatives (npm/pnpm, IDEs, envs)	<Tabs> / <PackageManagers> (.mdx)	Repeating near-identical blocks
A tight numbered procedure	<Steps> wrapping an <ol> (.mdx)	Bare headings as fake steps
Directory / file structure	<FileTree> (.mdx)	Hand-drawn ASCII tree

Admonition mapping (from Ward’s callout colors): info/highlight → :::note or :::tip; warning → :::caution; critical/blocker → :::danger; success/next-step → :::tip.

Built-in components beat raw markup — but only when they’re clearer. The full gallery and regression checklist is the Component library (skim it after editing tokens/theme). Components render only in .mdx: rename .md→.mdx (same slug) and add import … from '@astrojs/starlight/components'. A ## section that carries its own prose + code is a section, not a <Steps> item — don’t force it.

Visuals are mandatory where warranted

A page is not prose-only by default. Run the warrant test: if a section conveys a process (≥2 ordered steps), a structure/relationship (parts that own/use/reference each other — vocabulary maps, ownership, “what talks to what”), or a change over time (phases, before↔after), it must carry a diagram. A concept, relationship, or architecture page that ships as pure prose is incomplete, not done — treat it like a failing build. Pick the lightest tool that clears the bar: a Mermaid fence (works in .md) for an arbitrary relationship graph, a diagrams/*.astro component for an editorial pipeline / ownership / tier / timeline visual, or hand-authored inline SVG for something fully bespoke. The trigger→tool decision table lives in Reusable Doc Components. Only a single definition, one fact, a linear narrative, or a flat list may stay prose or a table.

Code blocks

• Always set the language for highlighting.
• Add # Expected: to show expected output, # Note: for context.
• Inside a numbered step, indent the fence so it doesn’t break the numbering.
• Word wrap is on by default site-wide (bash/sh/zsh use terminal-style wrap). Readers can switch one block at a time to horizontal scroll via that frame’s toolbar button (reload restores wrap). To force scroll for wide output tables, add wrap=false on the opening fence.

cd app
npm run build   # Expected: build completes, Pagefind index generated, exit 0

Frontmatter completeness

Fill every relevant frontmatter field (the docs-site analogue of “fill all fields”): title, description, sidebar (order/label/badge), and the optional taxonomy where it applies — kind, collection, category, subcategory, tags, status, plus playbook/template fields. Unknown-but-needed → leave it out rather than guessing; don’t ship a placeholder string.

Security

Never put secrets in docs — no API keys, license/purchase codes, tokens, passwords, or real credentials in prose, code blocks, or frontmatter. Use clearly-marked placeholders (<YOUR_TOKEN>) and reference a secrets manager.

Pre-publish QC checklist (the gate)

Run this before declaring a page done. The build is part of it.

Inbox & multi-extract (when source is _INBOX/ or enriching)

• Classified — shelf + type match content architecture; corpus check done (new vs enrich existing).
• Ledger row — source recorded in _INBOX/2-Research/<topic>/COVERAGE.md with status + target slug(s); skip only with explicit reason.
• Multi-extract — one primary target + peels (runbook, cheatsheet, concept…) link back; no verbatim duplicate across types.
• Doc-type spine — page follows the template for its kind (playbook step, runbook, handbook, guide, etc.); not a one-off heading soup.

Page template files (when editing zajlibrary/authoring/content-system/resources/templates/page-templates/)

• When to use + Design rationale (≥4 bullets grounded in cited sources).

• ## Sources is the last section — ≥3 external links + writing-style spines link.

• Copy-paste skeleton fenced block present; anti-patterns listed where applicable.

• Reader profiles — TL;DR/intro covers goal + who + done; steps numbered; checklist for perfectionist/ADHD closure; diagram where visual learners need shape.

• Formatting toolkit — sequential ##/###; lists/tables where parallel; bold/code/admonitions used correctly; <Steps>/<FileTree> on .mdx when warranted (toolkit).

• File tree — any page that creates/wires multi-file structure includes <FileTree> (.mdx) showing the result tree.

• AI contract (agents only): AI writing contract checklist satisfied — editorial color via structure/badges/admonitions, plugins used correctly, warrant test per section.

• Step pages (stepNumber): spine ## TL;DR (goal/objective first) → ## Background (optional, prose only — no callout under the heading) → ## Steps → ## Checklist; ### sub-steps are action-oriented (verb-first) with a 1–2 sentence intro; every command block shows expected results (# Expected: comment and/or - Expected: bullets beneath); 👤 You / 🤖 Agent tags where ownership isn’t obvious; :::note[For beginners and agents] under TL;DR; - [ ] items + :::next[Next step] at bottom (no :::summary[TL;DR], no bare ## Gate / ✅).

• Leads with what-it-is / who-it’s-for in 1–2 sentences (TL;DR covers this on playbook steps).

• Heading levels are sequential (one #, no skipped levels, #### is rare) — depth carries the hierarchy; no inline-tinted/faked headings.

• Every procedure uses numbered steps, not bare headings.

• Paragraphs are ≤ 5 sentences; parallel/dense points are broken into bullets or numbered lists; no walls of text.

• --- dividers between major sections.

• Admonitions (:::note/tip/caution/danger) and structural callouts (:::start, :::next, :::summary) used where they clarify entry, exit, or recap — correct type, not decoration.

• On .mdx pages, used built-in components where they beat raw markdown (CardGrid/LinkCard hubs, Steps, Tabs/PackageManagers, FileTree) — see the Component library; didn’t force one where prose or a table is clearer.

• Visual-warrant check: every section that conveys a process, a structure/relationship, or change-over-time carries a diagram — a concept/relationship/architecture page shipping as pure prose is INCOMPLETE (run the warrant test; decide with the doc-components table).

• No hardcoded colors; any visual themes via tokens and works in light and dark.

• Diagrams are Mermaid or a diagrams/*.astro SVG (themed, responsive viewBox, role/title/desc) — never a screenshot of a diagram. Flow connectors use 90° elbows (orthogonal routing; site Mermaid default stepAfter). Lane discipline: routes stay in gutters outside node boxes, stagger parallel edges, edges-before-nodes z-order — see doc-components → Lane discipline. See AGENTS.md → “Custom visuals & components”.

• Relevant frontmatter filled (title, description, sidebar, kind/collection/category/subcategory/tags/status where applicable).

• No secrets anywhere.

• Internal links resolve; cd app && npm run build is green (starlight-links-validator enforces links).

Anti-patterns (do not ship)

• Walls of text; actions buried inside prose instead of numbered steps.
• Callout as the first block under a section heading (put prose first — see Structure).
• Back-to-back callouts with no prose between them (merge them, or add the content that justifies two).
• Skipped heading levels, multiple # per page, or faking a heading’s emphasis with inline color/HTML instead of using the level + an admonition.
• Emoji-per-bullet / Notion-style decoration on a public editorial page.
• Hardcoded hex colors, or a visual that breaks in dark mode.
• A pasted screenshot where a Mermaid or SVG diagram belongs.
• Diagonal or bezier-curved flow arrows where orthogonal elbows are required.
• Inventing a category (e.g. guides/) instead of using the live topics.
• Referencing an installed-but-unwired plugin as if it works (see capabilities).
• Over-engineering: a custom component when a Mermaid fence or admonition does the job.