{
  "slug": "ai-builder-guide",
  "title": "AI Builder Guide",
  "description": "A dedicated site at ai.webhouse.app plus 21 modular docs — every AI coding assistant gets one URL to build with @webhouse/cms.",
  "category": "concepts",
  "order": 3,
  "locale": "en",
  "translationGroup": "7634eb7c-76c4-4515-a4a3-9e50ec8df096",
  "helpCardId": null,
  "content": "## One URL for any AI\n\nWhen a developer asks an AI coding assistant (Claude Code, Cursor, Copilot, Gemini, Windsurf) to build a website with **@webhouse/cms**, they can now just say:\n\n> \"Use https://ai.webhouse.app to build it.\"\n\nThe AI fetches that URL and gets a **self-contained Step 0–9 walkthrough**: verify environment → scaffold → plan with the user → edit `cms.config.ts` → create content → wire rendering → SEO → deploy → hand back. The page is served as `text/markdown`, with zero visual chrome — purpose-built for LLM consumption.\n\nAll 21 deep-dive modules live at `ai.webhouse.app/ai/{slug}` if the AI needs depth on a specific topic.\n\n## What ships at ai.webhouse.app\n\n| URL | Purpose |\n|-----|---------|\n| `/ai` | Self-guided Step 0–9 walkthrough. **Start here.** |\n| `/ai/01-getting-started` | Scaffolding + first run |\n| `/ai/02-config-reference` | `defineConfig`, `defineCollection`, collection options |\n| `/ai/03-field-types` | All 21 field types |\n| `/ai/04-blocks` | Block system (hero, features, CTA sections) |\n| `/ai/05-richtext` | TipTap editor, embedded media |\n| `/ai/06-storage-adapters` | Filesystem, GitHub, SQLite |\n| `/ai/07-content-structure` | Document JSON format, content directory layout |\n| `/ai/08-nextjs-patterns` | Pages, layouts, loader functions |\n| `/ai/09-cli-reference` | All CLI commands |\n| `/ai/10-config-example` | Complete real-world `cms.config.ts` |\n| `/ai/11-api-reference` | Programmatic ContentService usage |\n| `/ai/12-admin-ui` | CMS admin setup, Docker, npx |\n| `/ai/13-site-building` | Common mistakes, patterns, rendering |\n| `/ai/14-relationships` | Content relations, resolving, reverse lookups |\n| `/ai/15-seo` | Metadata, JSON-LD, AI SEO |\n| `/ai/16-images` | Image handling, responsive, next/image |\n| `/ai/17-i18n` | Multi-language, locale routing, translation |\n| `/ai/18-deployment` | Vercel, Netlify, GitHub Pages, Fly.io, Cloudflare |\n| `/ai/19-troubleshooting` | Common errors, debugging, FAQ |\n| `/ai/20-interactives` | Data-driven interactive content |\n| `/ai/21-framework-consumers` | Non-TS backends (Java, .NET, PHP, Python, Ruby, Go) |\n| `/ai/llms.txt` | llms.txt standard (for LLM site crawlers) |\n| `/ai/manifest.json` | JSON manifest with all modules + descriptions + endpoints |\n| `/ai/index.json` | Ordered module list |\n\nAll responses set `X-Robots-Tag: noindex` — the AI site is not indexed by traditional search engines. It's there for machines.\n\n## Why a dedicated AI site?\n\nThe 21 modules already exist on [GitHub raw](https://raw.githubusercontent.com/webhousecode/cms/main/docs/ai-guide/index.md), but that's not enough:\n\n1. **Discoverability** — one pretty URL is easier to remember and type than a deep GitHub path.\n2. **Rate limits** — GitHub raw throttles at 60 requests/hour unauthenticated. A fresh AI session that fetches several modules hits that quickly.\n3. **Platform variance** — not every AI coding tool has ergonomic URL-fetch tooling for GitHub paths, but essentially all of them can fetch a plain URL like `ai.webhouse.app`.\n4. **Self-guided entry point** — the existing index is a module list. It assumes the AI already knows what `@webhouse/cms` is. The new `/ai` walkthrough is written for a blank AI session — **\"you are an AI, follow these steps, if you need X fetch Y\"**.\n5. **Machine-readable endpoints** — AI platforms increasingly expect `llms.txt`, structured manifest JSON, and versioning. GitHub raw markdown doesn't provide any of that.\n\n## The walkthrough (`/ai`)\n\nThe walkthrough is structured as a **procedure**, not a reference:\n\n```\nStep 0 — Verify environment\nStep 1 — Scaffold the project (npm create @webhouse/cms@latest)\nStep 2 — Understand the model (document JSON, cms.config.ts, field types)\nStep 3 — Plan the site with the user (5 questions)\nStep 4 — Edit cms.config.ts (kind + description required per collection)\nStep 5 — Create starter content\nStep 6 — Wire up rendering (Next.js / static / non-TS consumer)\nStep 7 — SEO (if relevant)\nStep 8 — Deploy\nStep 9 — Hand back to the user\n\nTroubleshooting — first-pass fixes\nDeep-dive module index\nNon-negotiable rules (8 rules from CLAUDE.md critical rules)\n```\n\nThe AI can complete a basic build **end-to-end without fetching any other module**. Deeper modules are only for specific topics (i18n, complex SEO, non-TS backend).\n\n## How to use it\n\nIn any AI coding tool, paste:\n\n```\nBuild me a website with @webhouse/cms. Start by fetching https://ai.webhouse.app\n```\n\nThe AI will:\n\n1. Fetch `/ai` and follow Step 0 (check `node --version`, ask where to scaffold)\n2. Run `npm create @webhouse/cms@latest` (Step 1)\n3. Explain the model and plan with you (Steps 2–3)\n4. Edit `cms.config.ts`, create content, wire rendering (Steps 4–6)\n5. Fetch specific deep-dive modules as needed (SEO, i18n, deployment)\n6. Hand back a running local site with deploy hooks configured\n\nNo manual CLAUDE.md setup, no copy-pasting config from Stack Overflow, no \"where should I start?\" confusion.\n\n## Works with any AI platform\n\nThe entire site is plain `text/markdown` and `application/json` — every AI coding assistant understands it:\n\n- **Claude Code** — `WebFetch` tool pulls the URL; the long context window handles the full walkthrough\n- **Cursor / Windsurf** — paste the URL; the inline chat fetches it\n- **GitHub Copilot** — chat supports URL context; fetch `/ai` into the prompt\n- **Gemini (IDE extensions)** — URL-aware chat fetches the markdown\n- **Any future platform** — as long as it supports URL fetching, it works\n\n## Machine-readable endpoints\n\nFor programmatic use (MCP servers, agent frameworks, CI pipelines):\n\n```bash\n# Full JSON manifest with all modules + descriptions + endpoints\ncurl https://ai.webhouse.app/ai/manifest.json\n\n# Plain ordered module list\ncurl https://ai.webhouse.app/ai/index.json\n\n# llms.txt standard (for LLM crawlers)\ncurl https://ai.webhouse.app/ai/llms.txt\n```\n\nExample `manifest.json`:\n\n```json\n{\n  \"name\": \"@webhouse/cms AI Builder Site\",\n  \"version\": \"0.1.0\",\n  \"entry\": \"https://ai.webhouse.app/ai\",\n  \"modules\": [\n    { \"slug\": \"01-getting-started\", \"url\": \"...\", \"description\": \"New project, first setup\" },\n    ...\n  ],\n  \"endpoints\": {\n    \"walkthrough\": \"https://ai.webhouse.app/ai\",\n    \"llms_txt\": \"https://ai.webhouse.app/ai/llms.txt\",\n    \"manifest\": \"https://ai.webhouse.app/ai/manifest.json\"\n  }\n}\n```\n\n## Canonical source + fallbacks\n\nIf `ai.webhouse.app` is unreachable, the canonical markdown lives in the CMS monorepo and is served from GitHub raw:\n\n```\nhttps://raw.githubusercontent.com/webhousecode/cms/main/docs/ai-guide/index.md\nhttps://raw.githubusercontent.com/webhousecode/cms/main/docs/ai-guide/01-getting-started.md\n...\n```\n\nEvery scaffolded project also ships with `packages/cms/CLAUDE.md` (slim index, ~180 lines) that references the same modules. So the AI has three redundant paths to the same content:\n\n1. `https://ai.webhouse.app` (this site — primary)\n2. GitHub raw (fallback, rate-limited)\n3. Local `packages/cms/CLAUDE.md` in `node_modules/@webhouse/cms` (offline)\n\n## Dogfooding\n\nThe AI Builder Site itself is built with `@webhouse/cms` — it lives as a route group (`src/app/ai/*`) on [docs.webhouse.app](https://docs.webhouse.app), which is entirely CMS-managed. One site, two audiences: `/docs` for humans, `/ai` for AI agents. Same content model, same deploy pipeline.\n\nThis page (the one you're reading) is a document in the `docs` collection, stored as JSON at `content/docs/ai-builder-guide.json`. It explains the companion AI site that sits next to it. Self-referential, fully editable via the admin UI, and available in both English and Danish.\n\n## Non-negotiable rules\n\nThe walkthrough reinforces eight rules that AI sessions must follow when building with `@webhouse/cms`:\n\n1. Every collection MUST have `kind` and `description`\n2. `cms.config.ts` MUST declare `storage` explicitly (default is SQLite)\n3. NEVER name a collection `site-settings`, `settings`, `config`, `admin`, `media`, `interactives`\n4. `image-gallery` values MUST be `{ url, alt }[]` — never plain strings\n5. Documents MUST have `_fieldMeta: {}`\n6. Slug MUST match filename\n7. Always filter by `status === \"published\"` when rendering\n8. NEVER use CDN scripts (Tailwind, Bootstrap) in static builds — inline CSS only\n\nThese rules prevent the most common AI-generated mistakes we've seen across early builds.",
  "excerpt": "One URL for any AI\n\nWhen a developer asks an AI coding assistant (Claude Code, Cursor, Copilot, Gemini, Windsurf) to build a website with @webhouse/cms, they can now just say:\n\n \"Use https://ai.webhouse.app to build it.\"\n\nThe AI fetches that URL and gets a self-contained Step 0–9 walkthrough: verify",
  "seo": {
    "metaTitle": "AI Builder Guide — webhouse.app Docs",
    "metaDescription": "ai.webhouse.app is a self-guided walkthrough site for any AI coding assistant building with @webhouse/cms. One URL, Step 0-9, all 21 modules, llms.txt + manifest.json."
  },
  "createdAt": "2026-03-30T11:04:41.760Z",
  "updatedAt": "2026-04-16T00:00:00.000Z"
}