The Content Kit: Every Block, and When to Use It

Why this page exists

This site can render eleven content blocks beyond ordinary prose. They were built, then went unused long enough that nobody remembered they existed. The page that demonstrated them, content/articles/test-content-blocks.md, was deleted on 2026-08-01 in a commit that replaced a placeholder content corpus with on-topic articles — a reasonable cleanup that had the side effect of deleting the only page proving all eleven blocks still rendered. This page, added five days later, exists so that can't happen silently again.

So this page is a fixture. Every block below is live. If one renders as raw text or a grey box, the kit has broken and this page is where we find out, before a reader does.

It is also a style note. Each block is paired with the case it is actually for, because a block used because it exists is worse than the paragraph it replaced.

Callouts

Four kinds. Use them for something a reader must not miss while skimming — not for emphasis you could get from a sentence.

Use tip for a shortcut that saves real time

The fastest way to find whether a claim in this corpus is still live is to read the ruling off disk rather than from a summary. Summaries are instruments; the file is the ground.

Use info for context that is genuinely optional

Stafford Beer's Viable System Model dates from 1972. Nothing about the agent era invented it — the agent era made it applicable.

Use warn where a reader can lose something

A green gate proves that something ran. It does not prove the thing that ran was the thing you meant. Most of the craft is closing that gap cheaply enough that you do it every time.

Use pitfall for the mistake people actually make

Counting how many agents you can run instead of how much of their output you can check. The second number is the one that caps the firm.

Steps

For a sequence where order is load-bearing — doing step three first would fail. Not for a list.

Write the claim down first

Before running anything, state what you expect to be true. A check written after the result is a description, not a test.

Run the smallest thing that could falsify it

Not the whole suite. The single command whose failure would prove you wrong.

Record the number, not the impression

"It seemed fine" survives no handoff. "Eleven files, all hashes matched" survives every handoff.

Tabs

For the same task on different platforms or stacks, where a reader needs exactly one branch.

bash

shasum -a 256 file.md

Diagrams

For structure a sentence would take a paragraph to describe — layers, flows, dependencies. Rendered from mermaid in the house palette.

The verification loop, as a gate rather than a habit

Checkpoints

For a self-test after a concept that people routinely get wrong. One question, immediate answer.

Quick check — What caps the size of a zero-employee organization?

Solutions

For an answer a reader should attempt before seeing — or for FAQ entries that would otherwise bury the page in text.

Run commands

For a command a reader will actually paste, with the platform differences already resolved.

Terminal

make dev

Files changed

For a walkthrough where knowing which files moved is half the explanation.

Files changed

content/articles/the-content-kit.md

tailwind.config.ts

Scrollycoding

For an artifact built up in stages, where each addition is easier to understand against the version before it. Expensive to write; use it where the accumulation is the point.

Start with the claim

A SOW claim with no check attached is an assertion.

Bind it to a commit

Now it is locatable, but still not falsifiable.

Add the check that could fail

Now it is a claim someone else can destroy, which is the only kind worth filing.

That check still leaves one honest gap open: a passing hash check proves the nine files on disk are byte-identical to the manifest, not that they are the correct nine files for what shipped. A manifest generated from the wrong commit would pass this exact check while being wrong. The fix for that is a second, independent claim (manifest generated from the same commit the check names), not a stronger version of this one — a single check can only prove what it actually measures.

yaml

claim: the-fonts-are-vendored
state: SHIPPED

Start with the claim

A SOW claim with no check attached is an assertion.

yaml

claim: the-fonts-are-vendored
state: SHIPPED

Bind it to a commit

Now it is locatable, but still not falsifiable.

yaml

claim: the-fonts-are-vendored
state: SHIPPED
commit: 96dd367

Add the check that could fail

Now it is a claim someone else can destroy, which is the only kind worth filing.

yaml

claim: the-fonts-are-vendored
state: SHIPPED
commit: 96dd367
check: "shasum -a 256 -c FONTS.manifest -> 9 ttf OK, OFL.txt OK"

Tables

Ordinary markdown, no directive needed. For comparison across a shared set of attributes — if the columns do not apply to every row, write prose instead.

Block	Use it when	Do not use it for
Callout	A reader must not miss it while skimming	Emphasis a sentence would carry
Steps	Order is load-bearing	An unordered list
Tabs	Same task, different platform	Unrelated alternatives
Diagram	Structure needs seeing	Decoration
Checkpoint	A concept people get wrong	Testing recall of trivia
Solution	The reader should attempt first	Hiding your weakest section
Scrolly	The accumulation is the point	Any three code blocks

The rule under all of it

A block earns its place by doing something prose cannot. Breaking up a wall of text is not that job — if a section needs breaking up, it usually needs cutting instead.

Read the definition page

The canonical explanation of the term, and the audit that produced it.