Skip to content
daroms-speed-site

For AI agents

The operating manual for an agent (Claude Code or any coding agent): what to read, how to start a site, the contract every site follows and the checks to run before saying done.

Read this documentation as Markdown

Section titled “Read this documentation as Markdown”
  • Every page of the docs site has a raw Markdown twin: append .md to the page name (getting-started.md, agents.md, catalog.md).
  • llms.txt lists every page with a one-line summary; llms-full.txt is the whole documentation and the catalog in one file. Load llms-full.txt once instead of crawling pages.

Inside a generated site

Section titled “Inside a generated site”
  • CLAUDE.md loads the kernel (core/_ai/CLAUDE.core.md, under 60 lines) and the rules digest. Detailed rules load by file path from .claude/rules/.
  • site.spec.md is the brief and the single source of facts; its Journal records decisions, Open facts what is still unknown.
  • core/CATALOG.md lists tokens, components, sections, modules, archetypes and package APIs. Never read core sources.

Start a site

Section titled “Start a site”
Terminal window
npx @daromsart/daroms-speed-site new <slug> --preset vitrine --industry "<industry>" --mood "<two or three words>"
cd <slug> && pnpm dev

Then /dss-site <one-sentence idea> in Claude Code (a checkpoint after each step), or headless for a batch: pnpm dss factory run ./briefs --out ./sites --agent (decisions go to the Journal, the run stops before deploy).

The contract

Section titled “The contract”
What Where
Every visible word content/<page>.ts, typed as const
Pages app/**/page.tsx: metadata and sections only
Sections components/sections/*.tsx: owned code, a // dss-section: stamp and a @catalog line
Look and feel design.dna.ts, then pnpm dss theme; generated theme files are never edited
Pages, modules, deploy, CSP site.manifest.ts, rewritten by the CLI
Forms and mutations server/actions/* through safeAction
Unknown facts [placeholders] plus site.spec.md > Open facts; never invent testimonials, numbers or legal data
Studio credit the footer link to https://daromsart.xyz/ (content/site.ts > footer.credit) stays on every site

Commands

Section titled “Commands”
  • Generate before writing: pnpm dss g page|section, pnpm dss add section <id>, pnpm dss module add <slug>, pnpm dss dna roll, pnpm dss db init.
  • Check: pnpm dss doctor (theme, pages, placeholders, credit, types, lint), pnpm test, pnpm build.
  • Ship: pnpm dss deploy (noindexed preview), pnpm dss deploy --prod (needs the real domain and doctor --strict), then pnpm dss cost.

Guard rails

Section titled “Guard rails”

Hooks refuse a write before it lands and say why in one line: fix the cause, never work around it.

  • DNA token classes only: no hex or rgb, no default Tailwind palette, no inline style.
  • No hard-coded copy in JSX, no em dashes, no generated-copy cliches, no emoji.
  • No any, files under 250 lines, Next.js 16 APIs (proxy.ts, async params, revalidateTag(tag, profile)).
  • Secrets stay server-side; .env* and .dev.vars are never read.
  • A reasoned exception takes a dss-ignore comment on the line.

Headless runs

Section titled “Headless runs”
  • A new folder is not a trusted workspace: Claude Code ignores the project’s permissions.allow. factory run passes the rules on the command line; for a manual claude -p, pass --allowedTools with the rules from .claude/settings.json.
  • Each shell command must match an allow rule: prefer the Read and Grep tools to compound shell pipelines.
  • Done means verified: doctor, tests and build pass, and the result names what could not be checked.