turbo-start-web-agent — Next.js Business Template

SHA-256: 935712cd5601db769ca0cdd645dafb09d3fcb6a81eba57e8101ae25d8386002f

2026-10-14T20:54:23.449Z

<img width="1200" height="630" alt="image" src="https://github.com/user-attachments/assets/3db6a4cb-eb74-4e93-a8a6-9e4128973383" />

# turbo-start-web-agent

A starter for marketing sites your client can edit through **any AI agent**,
while your developers keep working locally in git.

Content is MDX in the repository — no CMS, no database. Pages are *data*, not
code: an author composes Blocks and passes them literal values, and a build-time
lockdown rejects any MDX carrying executable code. That is what makes "the agent
may only change content" a guarantee rather than a request. Every change lands
as a branch and a pull request, so a human still reviews what ships.

## Quickstart

```sh
pnpm install
pnpm dev
```

Open http://localhost:3000.

## Make it yours

Everything below is content or config. **Nothing under `src/` names the
brand** — if you find yourself editing a company name inside a `.tsx` file,
that is a bug in this template, not a step in the process.

| File | What it sets |
|---|---|
| `artifacts/web/content/settings/site.yml` | Site name and description — header, browser tab, blog index |
| `artifacts/web/content/settings/footer.yml` | Footer wordmark, columns, social and legal links |
| `artifacts/web/content/settings/navigation.yml` | Header menu |
| `artifacts/web/content/pages/*.mdx` | Page copy |
| `artifacts/web/src/app/globals.css` | Design tokens — colours, type, radius |
| `harness.config.json` | Project name and host for the agent harness; run `pnpm harness` after |
| `artifacts/web/src/app/icon.svg` | Favicon. An SVG cannot live in YAML, so this one is edited directly |

Then delete the demo content you do not want: the five starter posts under
`content/blog/`, and `content/pages/style-guide.mdx` and `blocks-gallery.mdx`
if the client should not see them.

`pnpm test` does not assert on any of this copy, so renaming things will not
turn the suite red. That was a real failure mode, found by walking this path
on 2026-08-21 and fixed rather than documented.

## The Block system

Pages are composed from **Blocks** — pre-built, schema-validated sections such
as `Hero`, `FeatureGrid`, `Testimonial`, and `CTA`. The registry currently
ships **19 Blocks**; the full set lives at `src/lib/blocks/schemas.ts` and
renders live, with the exact props each one expects, at
[`/blocks-gallery`](http://localhost:3000/blocks-gallery).

Compose a page by dropping named tags into its MDX body — no imports, no
wiring:

```mdx
<Hero title="…" primary={{ label: "…", href: "/…" }} />
```

Props must be literal values. Arrays and objects are expression attributes
(`primary={{ label: "…", href: "/…" }}`), never quoted strings. Markdown
outside a Block tag (headings, paragraphs, lists) renders too — it's styled
automatically through Tailwind Typography, not through a "Prose Block"; there
is no such Block in the registry.

### Adding a Block

1. Add a Zod schema to `src/lib/blocks/schemas.ts` and register it in
   `blockSchemas`.
2. Add the matching component to `src/components/blocks/` and register it in
   `blockComponents` (`src/components/blocks/index.ts`).
3. Run `pnpm catalog` — this regenerates `src/lib/blocks/catalog.json` (the
   machine-readable prop reference an authoring agent reads) and adds a stub
   section for the new Block to `content/pages/blocks-gallery.mdx`.

`pnpm catalog:check` and `pnpm catalog` diverging is exactly the drift CI
catches: `catalog:check` and `gallery:check` both run in CI, so a Block added
without regenerating fails the build.

## How content works

- Pages live in `artifacts/web/content/pages/*.mdx`; posts live in
  `content/blog/` and are served at `/blog` and `/blog/[slug]`.
- Frontmatter is validated by Velite. `draft: true` keeps an entry out of any
  production build, on Vercel or anywhere else. On Vercel, `VERCEL_ENV`
  disambiguates a production deployment from a preview one (both build with
  `NODE_ENV=production`), so drafts stay visible on preview URLs and are
  excluded only from production. Off Vercel — Netlify, Cloudflare, Docker, any
  self-hosted build — there is no such signal, so `NODE_ENV === "production"`
  is what excludes drafts there. Set `PREVIEW_DRAFTS=true` to deliberately
  render drafts on a production-mode build anyway (e.g. a staging environment
  that runs `next build`/`next start` the same as prod). `noindex: true`
  publishes an entry but keeps it out of the sitemap and asks search engines
  not to index it.
- Site chrome — the header nav and the footer — is **not** MDX content. It's
  edited as YAML in `content/settings/navigation.yml` and
  `content/settings/footer.yml`, validated by the same Velite/Zod pipeline
  (every `href` is checked against the same safe-URL rule Block links use).

## Environment variables

Copy `.env.example` to `.env.local` and set `NEXT_PUBLIC_SITE_URL` to your
deployed origin — without it, `sitemap.ts` silently falls back to
`https://example.com` and ships a sitemap of example.com URLs on your first
production deploy.

## The build is the gate

```sh
pnpm run checks       # every gate below, in order, stopping at the first failure

pnpm content:check    # frontmatter, MDX syntax, and the content lockdown
pnpm catalog:check    # catalog.json is in sync with src/lib/blocks/schemas.ts
pnpm claims:check     # the docs do not misstate how many Blocks exist, or which
pnpm skills:check     # third-party skills are pinned, and still hash to what was reviewed
pnpm gallery:check    # blocks-gallery.mdx has a section for every registered Block
pnpm test             # lockdown, loader, and Block-prop unit tests
pnpm typecheck
pnpm build            # renders every page; bad Block props fail here
```

If these pass, the content is valid. Fix the content, not the schema. A green
build is necessary but not sufficient — always click through the built site
(nav, footer, and every page it links to) before calling a change done.

## The agent harness

This template is agent-native: **`AGENTS.md`** at the repo root is the
canonical rulebook — the content model, Block composition, the
build-is-the-gate rule, git discipline — read natively by Codex, Cursor,
GitHub Copilot/VS Code, Zed, and most of the rest of the ecosystem.

Claude Code doesn't read `AGENTS.md` on its own, so **`CLAUDE.md` and the
`.claude/skills/` mirror bridge that gap — and both are generated**, by
`pnpm harness`, from `AGENTS.md`, `harness.config.json`, and
`.agents/skills/`. Never hand-edit a generated
file (each one says so at the top); edit the inputs and regenerate.
`pnpm harness:check` is the read-only drift gate CI runs — it fails,
naming exactly which generated file is stale, instead of writing anything.

`docs/platforms/` holds a connection runbook per supported platform
(v0, Claude Code, Codex): scoping a client repo to one
platform, a write-only push identity, turning off platform-side automation
that would fight this template's review-before-publish model, and a smoke
test.

`scripts/preflight.sh` reports what an agent session can actually do —
git remote reachability, `gh`/`pnpm`/`node` presence, manifest capability
probes — at session start (wired to Claude Code's `SessionStart` hook in
cloud sessions; run it by hand elsewhere).

### Which platform for which client

The platforms are not interchangeable. All three have taken a real
client-style content change through to a merged pull request. The last column
names them by number, so the claim can be checked rather than taken on trust:

| Platform | Reads the rulebook | Shows the client the site | Opens the PR | Run live |
|---|---|---|---|---|
| **v0** | `AGENTS.md` + `.agents/skills/` | **Yes**, in-chat preview | Itself | #25, #34, #38, #47, #51, #54 |
| **Claude Code** | `CLAUDE.md` (imports `AGENTS.md`) | No — diff only | Button in the UI | #2, #13, #17, #23 |
| **Codex** | `AGENTS.md` | No — diff only | Button in the UI | #4, #18, #22 |

The column that decides it for a non-technical client is **shows the
client the site**. On v0 they watch the site change as they ask for it; on Claude
Code and Codex they get a diff, and their only view of the result is the
hosting preview URL — which is behind a login by default on most hosts, so
it needs configuring rather than assuming. Both of those platforms *do*
have a preview, but only in their desktop apps, which need a local install
and a checkout: the developer setup this template exists to spare the
client.

Pick the platform for whoever is actually driving. `docs/platforms/README.md`
covers preview access; each runbook covers that platform's specific traps —
and every one of them has some.

### What live testing changed

Testing moved this from documented to verified, and corrected the docs in
about a dozen places. One finding is worth knowing before you connect
anything:

- **On an agent-authored pull request, the file list is the truth and the
  prose is a claim.** One platform committed a dev-server side effect as
  its own commit and titled the PR after it, never mentioning the change
  that had been requested. Every automated check passed, because none of
  them read English.

`AGENTS.md` §6 records these and the rest, with dates.

## Licence

MIT.