creator-kit

Runbook 01

First hour after bootstrap

From a fresh macOS account to a published essay site at <name>-essays.highline.work in under one hour, with a passing ck validate --offline and at least one ledger entry.

You are reading this on a fresh macOS user account that has never seen creator-kit. By the end of this hour you have a published essay site at <your-name>-essays.highline.work returning 200, a passing ck validate --offline, and at least one entry in docs/agent-runtime/ledger.md. You read only this file. You do not need to ask anyone for help.

If something does not work the way the runbook says it will, that is a runbook bug. Open an issue against candlefish-ai/creator-kit with the exact command you ran and the output. Do not skip ahead and improvise. The kit’s contract is that this runbook produces the expected end-state; an improvisation hides a bug.

Pilot recipients (M3 W12)

The first non-Patrick readers of this runbook are Max Zajec (maxzajec, max@candlefish.ai) and Tyler (tyler812, tyler@candlefish.ai). Both have write access to candlefish-ai/creator-kit and Tailscale invites to the candlefish.ai tailnet. If you are Max or Tyler picking this up cold for the W12 pilot: Patrick is the engagement lead, Aaron Westphal is the technical guide, and any friction you hit is the most useful kind of feedback the kit can get — log it as you go in docs/agent-runtime/ledger.md of your scaffolded project, and the kit’s next iteration absorbs the fix. The substrate behind this site (Astro 5 + @aspenas/design-system + Cloudflare Pages) is the proper-tools-not-handwritten posture; the runbook below is its first contact with anyone other than the author.

Prerequisites — 5 minutes

Step 1 — clone and bootstrap, 5 minutes

git clone git@github.com:candlefish-ai/creator-kit.git ~/Work/creator-kit
cd ~/Work/creator-kit
./bootstrap.sh --user <your-name> --email <your-email@candlefish.ai>

The bootstrap installs Homebrew packages idempotently, installs Claude Code, Codex, jq, uv, fswatch, cloudflared, and gh. It writes ~/.creator-kit/profile (mode 600) with your name and email, sets your global git author identity from the profile, and runs make install which symlinks the kit’s seven hooks and three agents into ~/.claude/.

Expected end state: bootstrap exits 0 and prints bin/ck doctor as the next step.

If bootstrap fails on gh auth login: run echo $GITHUB_TOKEN | gh auth login --with-token (using a token with repo scope) and re-run bootstrap.

Step 2 — verify with doctor, 1 minute

./bin/ck doctor

Expected: 11 of 11 PASS, exit 0. The eleven checks are CLI presence (claude, codex, cloudflared, jq, uv, fswatch, gh authenticated), profile (mode 600 with user and email keys), git author email matches profile, the creator-dev agent is symlinked into ~/.claude/agents/, and fonts.candlefish.ai returns 200.

If any check is FAIL, fix that one first before continuing. The most common is gh CLI authenticated — run gh auth login --web (or the keychain-based variant if you have a token cached locally).

Step 3 — scaffold your project, 1 minute

./bin/ck new <your-name>-essays --template essay-series --host <your-name>-essays.highline.work --quarter "M1 W3"

What happens:

  1. The kit copies examples/essay-series/ to ~/Work/<your-name>-essays/.
  2. It runs ck init-runtime against the new project, which renders six templates — CLAUDE.md, docs/agent-runtime/{README,current,known-drift,ledger}.md, docs/contracts/agent-runtime-files.json — with your name, email, surface, and quarter substituted.
  3. It runs git init, sets the per-repo author from your profile, and creates a single initial commit.
  4. It runs ck validate --offline against the fresh tree. Expected: 6 PASS, 0 FLAG, 0 FAIL.

If validate is not all-PASS, the kit has a real bug. Stop and file an issue.

Step 4 — preview locally, 10 minutes

cd ~/Work/<your-name>-essays
uv venv .venv
.venv/bin/python -m pip install -r server/requirements.txt
.venv/bin/uvicorn server.serve:app --port 18210 --reload &
sleep 2
curl -sI http://127.0.0.1:18210/health     # 200 expected
open "http://127.0.0.1:18210/"

The two seed essays are at content/essays/00-on-open-loops.mdx and 01-what-this-site-is.mdx. They are real essays, not lorem ipsum — read them once. They demonstrate the Candlefish register the validate_essays.py validator enforces.

When you are ready to write your own, add content/essays/02-<your-slug>.mdx with the same frontmatter shape. The validator will run on your essay automatically as part of ck validate --offline.

Kill the local uvicorn before continuing: kill %1.

Step 5 — write your first real essay, 15 to 30 minutes

Replace content/essays/00-on-open-loops.mdx with one of yours, or add a new file. The frontmatter requirements are:

---
title: <sentence-case title, no terminal period>
slug: <lower-kebab-case>
date: 2026-05-02              # ISO-8601
tags: [register, candlefish]  # YAML list
summary: <one sentence — load-bearing claim>
---

The voice rules validate_essays.py enforces (run python3 validate_essays.py in the project root any time):

When the validator returns PASS, commit:

git add content/essays
git commit -m "feat: add <slug>"

Step 6 — provision the publish secret, 3 minutes

The Basic Auth password lives in ~/.config/<your-name>-essays.env, mode 600. It is never committed.

PROJECT_SLUG=<your-name>-essays
mkdir -p ~/.config && cat > ~/.config/$PROJECT_SLUG.env <<EOF
export ARCH_USER=<your-name>
export ARCH_PASSWORD=$(python3 -c 'import secrets; print(secrets.token_urlsafe(24))')
export ARCH_PORT=18210
EOF
chmod 600 ~/.config/$PROJECT_SLUG.env

Save the password somewhere durable (1Password, etc) so you can share with anyone who needs to view the surface.

Step 7 — publish, 5 minutes

ck publish                  # dry-run first (default)
ck publish --execute        # actually launches the surface

What --execute does:

  1. Renders serve.py, run-service.sh, the launchd plist, and the cloudflared ingress rule into .deploy/.
  2. Copies the plist to ~/Library/LaunchAgents/ and bootstraps it under gui/$(id -u).
  3. Splices the cloudflared ingress rule into ~/.cloudflared/config.yml above the catch-all 404.
  4. Kickstarts com.cloudflared so the new rule takes effect.
  5. Waits up to 90 seconds for https://<your-name>-essays.highline.work/health to return 200.
  6. Appends a publish row to docs/agent-runtime/ledger.md.

If step 5 times out, run ck publish --diagnose — that prints the four standard checks (DNS, cloudflared launchd state, auth-pair env file, surface health) so you can see which step broke. The most common failures are: cloudflared tunnel route dns <tunnel> <surface> was never run (one-time DNS step), the surface is on fonts.candlefish.ai’s allowlist but its CSS request is being CORS-blocked, or the tunnel auth has expired. The publishing runbook covers each failure mode in detail.

Step 8 — verify and run the live validator, 2 minutes

curl -I https://<your-name>-essays.highline.work/health
# expect: HTTP/2 200, body {"status":"ok"}

ck validate --live           # adds the live-route checks to the offline pass

Once ck validate --live returns zero FAIL rows and the ledger has at least two entries (the scaffold row from ck new plus the publish row from ck publish --execute), the M1 ship-test gate is met. You have moved from no kit to live published surface in under one hour.

Step 9 — append a closing ledger entry, 1 minute

cat >> docs/agent-runtime/ledger.md <<EOF

- $(date -u +%Y-%m-%dT%H:%M:%SZ) human: first-hour runbook complete. Surface at https://<your-name>-essays.highline.work/ returning 200; ck validate --live PASS; <N> essays published.
EOF
git add docs/agent-runtime/ledger.md
git commit -m "chore: ledger — first-hour runbook complete"
git remote add origin git@github.com:<your-handle>/<your-name>-essays.git    # if not already
git push -u origin main

The ledger is the cross-agent baton. Whoever picks up your project next — Codex during a drift-closing run, Claude during a synthesis pass, you yourself in a week — reads the ledger first.

What you do not need to do

What to do when the runbook breaks

If a step does not produce the documented output, file the runbook bug. Do not improvise around it; the next reader inherits whatever workaround you build. The kit’s contract is that this file works end-to-end on a clean account.

Running this on a colleague’s machine

Same runbook. The kit is parameterized by --user and --email from the start, so there is nothing in bootstrap.sh, ck doctor, or any subsequent step that hardcodes one creator’s identity. The first creator’s surface and the second creator’s surface coexist on the same machine because cloudflared rules are per-hostname and launchd plists are per-project-slug.

See also