Enable tidy

Tidy is cairn’s optional AI copy-edit, built on Claude. Turning tidy on is a developer task: add a tidy block to site.config.yaml and set an Anthropic API key as a Worker secret. Editors then work with tidy from the toolbar. See Write in the editor for that side.

If you haven’t declared your adapter yet, start with Define an adapter and schema. Tidy is off by default, and turning it on is a deliberate per-site choice: every call it makes is a real, billed request to Anthropic’s API, so there’s no “just try it” setting to leave on by accident.

Turn tidy on in the site config

Add a tidy block to site.config.yaml, the committed config parseSiteConfig reads at build:

tidy:
  enabled: true

That one line is a complete config. enabled defaults to false, so tidy stays off until you set it, and every other field falls back to a sensible default:

enabled and model are developer-tier facts: set them once in the file, and the in-admin settings screen shows both back to you read-only. conventions is the field an editor actually touches day to day, set from that same screen rather than by hand-editing YAML. See what changes for editors, below.

Set the Anthropic API key as a Worker secret

Tidy calls the Anthropic API directly from the Worker, so it needs an API key. The key is a secret, so it doesn’t go in site.config.yaml or in a plain vars entry in wrangler.jsonc. Set it with wrangler:

npx wrangler secret put ANTHROPIC_API_KEY

wrangler dev reads a .dev.vars file instead of asking Cloudflare for the secret, so local development needs the same key there:

ANTHROPIC_API_KEY=sk-ant-...

Keep .dev.vars out of version control the same way you would any other local secret file.

ANTHROPIC_API_KEY is the one member of CairnPlatformBindings that’s optional. Every other binding is required, so a forgotten one fails at compile time instead of surfacing as a runtime error later. Leaving tidy off means you can skip the secret entirely. Turning tidy on without setting the secret fails closed: the action refuses every request with fail(503), and the editor sees tidy report itself unavailable.

Verify the wiring

cairn-doctor runs a config.tidy-key check whenever tidy.enabled is true:

npx cairn-doctor

When a literal key value is readable locally, typically your .dev.vars during local development, the doctor actively verifies it with a zero-token call to Anthropic and reports valid or invalid distinctly. When the key lives only as a deployed Worker secret, invisible to any command-line tool, the check falls back to confirming the name is referenced somewhere it would be if it were a plain var, and says so honestly rather than claiming a verification it can’t do. See the doctor’s check table for the exact condition and what makes it skip.

The real test is running tidy once. Open an entry in the admin, invoke tidy on a paragraph, and confirm it comes back with proposals. With observability on, a successful call logs tidy.done with the model and the token usage. A broken key instead logs tidy.error, or refuses outright before the call ever goes out. Log events covers the whole tidy.* family, and Read cairn’s logs covers querying them on a deployed Worker.

Know what a tidy run costs

Every tidy call spends tokens on the Anthropic API, and cairn caps both the input and the output, so a run has a known cost ceiling.

• Tidy runs only when an editor triggers it, over the whole draft or a selected passage. Nothing calls the model on a timer or in the background.
• A request over roughly 24,000 characters (about 6,000 input tokens) is refused before the model is reached; the editor tidies a selection instead of the whole draft.
• The output cap exceeds what proofreading that input needs, so a run can return a full rewrite.
• Model choice is the main lever. claude-sonnet-4-6 favors judgment on subtler fixes, and claude-haiku-4-5 runs faster for less. Current per-token pricing lives on Anthropic’s pricing page.
• Local development costs nothing: cairn’s dev wiring, as the showcase template ships it, injects a stubbed Anthropic client, so building and testing never reaches the real API.

See what changes for editors

Once tidy.enabled is true and the key resolves, the in-admin settings screen (/admin/settings) drops its gate note and opens the conventions editor: the per-convention toggles an editor sets for their own site, saved straight back into site.config.yaml’s tidy.conventions block. The developer-tier facts you just set, whether tidy is on, whether the key is set, and which model, show there too, read-only. The settings screen also actively probes the key, so a revoked or mistyped one surfaces its own distinct note there instead of quietly claiming success because a value is merely present. It reuses a recent probe’s result for a few minutes rather than reaching Anthropic on every single load.

If a tidy call ever fails because Anthropic rejects the key, the Tidy control disappears from the editor for a while rather than staying live to fail again. cairn treats a present-but-broken key as absent, not as a disabled control left in place. The settings screen handles a broken key the same way. It comes back on its own a short while after the key starts working again, or immediately on the next successful call, whichever comes first; nothing you do in the editor forces the recheck.

Past that screen, tidy is an editing feature the editor drives from the toolbar. That flow, and tidy’s remit of small fixes that never touch voice or structure, is Write in the editor’s tidy section.