hakuto CLAUDE.md

Hakuto — plugin development

Hakuto is a Claude Code plugin that scaffolds and builds Astro + Cloudflare sites. This file is memory for working on the plugin. It is not shipped to generated sites.

Two audiences — know which tree you are editing

Tree	Who loads it	Effect of a change
skills/, agents/, commands/	Claude Code, when the plugin is installed	Changes agent behaviour on the next /plugin update hakuto
scaffold/	Copied into an empty directory by /hakuto:init	Changes what new sites get
scaffold/CLAUDE.md	The generated site's agent	A shipped artifact — not this repo's memory

Existing sites never pick up scaffold changes on their own. Anything they need requires a versioned entry in the Migration Registry in skills/scaffold-sync/SKILL.md.

Commands

bun is not on PATH — it comes from devenv/direnv. From scaffold/:

export PATH="$PWD/.devenv/profile/bin:$PATH"   # or: devenv shell
bun install
bun run check                    # astro check — type errors
bun run build                    # → dist/client
bun test test/dev-smoke.test.ts  # worker + static serving smoke (4 tests)

Never pipe a bun command straight into tail/head. A missing bun exits 127, but a pipeline reports the tail's status, so a build that never ran looks like it passed and && happily continues. Grep the output for command not found — don't trust the exit code.

Gotchas

• Do not hand-edit version in .claude-plugin/plugin.json. .github/workflows/bump-plugin-version.yml bumps the minor on every PR automatically.
• scaffold/AGENTS.md is regenerated by every build (@nuasite/agent-summary) and leaves the tree dirty. git checkout scaffold/AGENTS.md before committing unless the change is intended. Its meta-description regex content=["']([^"']*)["'] truncates at the first apostrophe (0.0.36), so descriptions in that file are unreliable — read the real string out of dist/client/.
• _headers rules scoped to / match the homepage only. / is an exact path, not a prefix, and it fails silently — no build error, no deploy error. Site-wide rules go under /*. Verify with curl -sI <origin>/some/inner/page/, never curl -sI <origin>/, which passes either way.
• public/ and src/pages/ share a URL namespace. public/robots.txt and src/pages/robots.txt.ts cannot coexist — deleting the public/ file is part of the change, not cleanup afterwards.
• JSON-LD must not be HTML-escaped. <script type="application/ld+json"> is a raw-text element, so entities are never decoded and ' reaches consumers literally. See scaffold/src/components/Schema.astro — it escapes < only, and that is deliberate.