Authoring Conventions

Vidar the Patient — Master of Craft

In one breath

Markdown flattens space; the Book adds visual and interactive structure on top. This page catalogs the patterns officers reach for to make chapters scannable, layered, and genuinely readable — and the audience-driven convention for when to produce a self-contained HTML deliverable instead of a markdown document.

By the end of this page you’ll know:

• The eight-element skeleton every chapter follows (and why it is non-negotiable)
• Which Starlight components to reach for, and when each earns its weight
• The audience-driven rule for officer→regent deliverables: HTML vs markdown

---

The base skeleton

Every chapter follows the eight-element skeleton defined in Start Here:

Element	What it does
Persona byline	Who is teaching this domain
In one breath	The essential idea — two sentences maximum
Learning objectives	What the reader will understand after reading
Body	The full explanation in the officer’s voice
See it as	A parable that makes the abstraction stick
Worked example	Something concrete and traceable
Recap	Three bullets — the chapter compressed
What changed	Links to the Changelog entries that touch this chapter

These elements are not decoration. They are the contract that keeps the Book teachable as the codebase evolves. Do not skip them.

---

Pattern catalogue

The skeleton is the floor. The patterns below are the additional elements you reach for when the content calls for them. Each one has a cost — it asks the reader to switch modes. Use it when that switch earns a better outcome than prose would.

Callouts — for signal, not decoration

Callouts render as coloured blocks. They stop the eye. Use them sparingly; every extra callout diminishes the ones that matter.

Callout	Use	Frequency
:::note[In one breath]	The essential-idea opener	Once per chapter, always
:::tip[See it as]	The parable	Once per chapter, always
:::caution[Watch out]	A genuine gotcha that wastes hours	Only when real
:::danger[Hard stop]	A safety/security constraint	Only for irreversible things

Callouts are not headers. Do not use them as section dividers or for general emphasis. A chapter with five cautions has no cautions.

---

Mermaid — for structure that prose can’t convey

Good fit: state machines, data flows, call sequences, system topology. Bad fit: anything that needs two columns, a table, or prose labels longer than three words.

Mermaid diagrams inherit the Book’s dark theme automatically via the rehypeMermaid plugin (strategy: 'inline-svg'). You do not need to configure colours.

---

Tabs — for code in multiple contexts

Use <Tabs> when you are showing the same concept in multiple languages or platforms and the reader only needs one at a time.

Rust

// Tauri command — the backend half
#[tauri::command]
pub fn list_groups(state: State<AppState>) -> Vec<Group> {
    state.db.lock().unwrap().list_groups()
}

TypeScript

// Frontend call via generated Tauri bindings
import { listGroups } from '../bindings';

const groups = await listGroups();

Tabs hide information — the content in every inactive tab is invisible. Use them only when a reader on Platform A has no reason to read Platform B. Do not use tabs just to break up long content.

---

Collapsible — for deep dives specialists need

Use <details> for content that most readers can skip but specialists need. The summary line must tell the reader what they are skipping — “More details” is not a summary.

Full Rust type definition for Group

pub struct Group {
    pub id: Uuid,
    pub name: String,
    pub owner_id: Uuid,
    pub members: Vec<GroupMember>,
    pub currency: String,
    pub created_at: DateTime<Utc>,
    pub updated_at: DateTime<Utc>,
}

pub struct GroupMember {
    pub user_id: Uuid,
    pub role: GroupRole,
    pub joined_at: DateTime<Utc>,
}

Good fit: the full error message, the complete schema, the edge-case proof, the config flag table. Bad fit: anything a general reader needs to follow the chapter.

---

Card grid — for overview mode

Use <CardGrid> to give a section-at-a-glance or to present a set of alternatives at the same conceptual level.

For structure

Mermaid. State machines, data flows, topology. Inline SVG, dark-themed automatically.

For code

Tabs. Multi-platform examples where the reader needs exactly one path.

For reference

Collapsible. Full schemas, error messages, edge-case proofs. Specialists expand; generalists skip.

For comparison

Table. Before/after, option A vs B. Two columns, headers name the axis.

---

Steps — for sequential processes

Use <Steps> for processes where order matters and skipping a step breaks the outcome. Do not use <Steps> for a list of concepts — use a numbered list for that.

1. Run ensure-worktree.sh CAS-<N> --slug <slug> to create the worktree from master.
2. Implement in the worktree. Never commit to the main clone.
3. Run cargo test to regenerate TypeScript bindings from ts-rs annotations.
4. Open the PR from the worktree branch. Include a DONE-PROBE artifact.
5. Request review via the structured @-mention protocol. Reviewer merges on approval.

---

Side-by-side — for before/after

A two-column table is the right shape for before/after comparisons and for A vs B options.

Before CAS-3702	After CAS-3702
Feature pages had no byline	Every page opens with the officer’s byline
Content started with a heading	Content starts with the In one breath callout
No consistent closing	Three-bullet Recap at the end of every chapter
No Changelog link	## What changed on every page

Do not use tables for tabular data with more than four columns — a table that wide is a maintenance problem and unreadable on a phone. Use <FileTree> for directory structure; use prose for narrative lists.

---

Inline SVG — when Mermaid isn’t enough

Mermaid covers most diagrams. When you need custom layout, colour, or interactive detail that Mermaid cannot express, write SVG directly in the MDX source.

<svg viewBox="0 0 320 80" xmlns="http://www.w3.org/2000/svg" role="img"
     aria-label="Officer to regent delivery path">
  <rect x="10" y="20" width="90" height="40" rx="4"
        fill="#1e1e2e" stroke="#7c3aed" stroke-width="1.5"/>
  <text x="55" y="44" text-anchor="middle" fill="#c4b5fd" font-size="11"
        font-family="monospace">Officer</text>
  <line x1="100" y1="40" x2="210" y2="40" stroke="#7c3aed" stroke-width="1.5"/>
  <polygon points="210,35 220,40 210,45" fill="#7c3aed"/>
  <rect x="220" y="20" width="90" height="40" rx="4"
        fill="#1e1e2e" stroke="#16a34a" stroke-width="1.5"/>
  <text x="265" y="44" text-anchor="middle" fill="#86efac" font-size="11"
        font-family="monospace">Regent</text>
</svg>

Hand-rolled SVG must match the Book’s colour palette (background #1e1e2e, accent #7c3aed, text #c4b5fd). Include a role="img" and aria-label for accessibility. Use Mermaid by default; reach for SVG only when Mermaid’s layout engine cannot produce what you need.

---

The layered-detail pattern

Every chapter already has a built-in layering without any extra components:

• Scan — read only the callouts (In one breath → See it as → Recap). A reader who scans should leave with the essential idea intact.
• Orient — read the learning objectives and section headings.
• Read — the full body.
• Reference — expand collapsibles.

When writing, ask: “What does a reader get if they only read the three callouts?” That answer should be complete and standalone. If it is not, the callouts are not doing their job.

---

The officer→regent deliverable convention

This section is about artifacts officers send to the regent for human review — not about chapter authoring. The rule here governs format, not structure.

The audience-driven rule

Artifact	Primary reader	Format
Proposal, audit, diagnosis, distill	Regent (human review)	Self-contained HTML
PR explainer for regent-reviewed epics	Regent (human review)	Self-contained HTML
Multi-option decision, dashboard, research	Regent (human review)	Self-contained HTML
Spec, plan.md, CAS body, commit message	Agent or tooling	Markdown
Status update, routine comment, watch tick	Agents + incidental regent	Markdown

The dividing line: human-in-the-loop + review-heavy = HTML. AI↔AI + routine = markdown.

This is judgment, not a rigid rule. A one-sentence status update stays markdown even if the regent reads it. A ten-section architecture proposal becomes HTML even if an agent processes it first. The question is: “Will this reader experience this differently in a browser than as a markdown block?”

What “self-contained HTML” means

A single .html file that:

• Renders completely in a browser without external assets (CSS and JS inlined, or CDN-linked from a stable source)
• Is served via the Book/keep CF Pages gate — phone-viewable, CF-Access-gated, same gate as /keep
• Does not require a running dev server or a markdown renderer

The regent reads these on his phone. Phone-viewable means: no horizontal scroll, readable without zooming, all actions reachable with a thumb.

The PR explainer pattern

For regent-reviewed PRs and epics — not every officer↔officer handoff — produce an HTML explainer covering:

1. What changed — the user-visible delta, one paragraph.
2. Why — the motivation, constraint, or decision that drove it.
3. How — key implementation choices, with architecture notes for anything surprising.
4. What to verify — the specific path the regent should follow to confirm it works.

Scannable. Headed. Phone-first layout. The regent is reading between things.

Token cost: an HTML explainer runs ~2 000 extra tokens per production. Produce one for epics and regent-reviewed PRs. Skip it for officer↔officer handoffs.

What this convention is not

This is not a /html skill. Do not build a template, a codegen step, or a procedure that auto-fires on every deliverable.

The pattern is a vocabulary you internalize. The first time you produce an HTML proposal, ask: “Will the regent read this differently in a browser?” The answer shapes the next decision. Over-proceduralizing this is the failure mode — the value comes from the judgment, not the mechanic.

---

See it as

A carpenter knows when to reach for a chisel and when to reach for a plane. They do not consult a decision tree — they have spent years reading wood. These authoring patterns are the same: a catalogue you internalize, not a flowchart you follow. The first time you write a tab, ask yourself whether the reader will actually switch tabs. The first time you produce an HTML deliverable, ask whether the regent will genuinely read it differently than he’d read a markdown block. The answer guides the next decision.

Recap

• Every chapter follows the eight-element skeleton; the patterns above add expressiveness on top of it without replacing any element.
• HTML for review-heavy human-facing deliverables (proposals, audits, distills, PR explainers); markdown for AI↔AI, routine, and diffable artifacts. This is judgment, not a rigid rule.
• The pattern catalogue is a vocabulary to internalize, not a checklist to run. Reach for each element only when it genuinely serves the reader who will actually read the artifact.

What changed

These conventions were introduced in CAS-3792, building on:

• CAS-3702 — the eight-element skeleton backfilled across all 70+ chapters
• CAS-3757 — the curated reading path that established the sidebar arc
• CAS-3701 — Mermaid diagram support added to the Book

See: CHANGELOG → 2026-05-19