@typeroll/mcp-server 0.7.4

package/dist/tools/preview.js

@@ -0,0 +1,24 @@
+import { z } from 'zod';
+import { ok, withErrorBoundary, versionParam } from './helpers.js';
+function v(version) {
+    return version ? { version } : undefined;
+}
+export const previewTools = [
+    {
+        name: 'get_preview_link',
+        description: 'Mint a short-lived signed URL the user (or your own browser tool) can open to SEE the rendered preview. Internal links inside the preview keep the same token attached, so the agent can navigate the whole site from one mint. Default TTL 15 min, max 24h. Target the preview at a page (page_id), a collection item (collection_name + item_id, resolves via route_template), or a raw slug. Omit all to land on the home page.',
+        inputSchema: {
+            page_id: z.string().optional(),
+            slug: z.string().optional(),
+            collection_name: z.string().optional(),
+            item_id: z.string().optional(),
+            ttl_seconds: z.number().int().min(60).max(86_400).optional(),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const { version, ...body } = args;
+            const res = await client.post(siteId, 'preview-link', body, v(version));
+            return ok(res);
+        }),
+    },
+];

package/dist/tools/redirects.js

@@ -0,0 +1,40 @@
+import { z } from 'zod';
+import { ok, withErrorBoundary, versionParam } from './helpers.js';
+function v(version) {
+    return version ? { version } : undefined;
+}
+export const redirectTools = [
+    {
+        name: 'list_redirects',
+        description: 'List redirect rules (from_path → to_path, status code).',
+        inputSchema: { version: versionParam },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.get(siteId, 'redirects', v(args.version));
+            return ok(res);
+        }),
+    },
+    {
+        name: 'create_redirect',
+        description: 'Create a redirect rule. Defaults to 301; pass status_code=302 for a temporary redirect.',
+        inputSchema: {
+            from_path: z.string().describe('Old path, leading slash (e.g. "/old-about")'),
+            to_path: z.string().describe('Target path or absolute URL'),
+            status_code: z.union([z.literal(301), z.literal(302)]).optional(),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const { version, ...body } = args;
+            const res = await client.post(siteId, 'redirects', body, v(version));
+            return ok(res);
+        }),
+    },
+    {
+        name: 'delete_redirect',
+        description: 'Remove a redirect rule.',
+        inputSchema: { redirect_id: z.string(), version: versionParam },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.del(siteId, `redirects/${encodeURIComponent(args.redirect_id)}`, v(args.version));
+            return ok(res);
+        }),
+    },
+];

package/dist/tools/search.js

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+import { ok, withErrorBoundary, versionParam } from './helpers.js';
+function v(version) {
+    return version ? { version } : undefined;
+}
+export const searchTools = [
+    {
+        name: 'search_pages',
+        description: 'Search page bodies by literal substring or regex. Returns up to 500 matches each with an excerpt around the first hit. Use this to scope a redesign or a bulk replacement before running it.',
+        inputSchema: {
+            contains: z.string().optional().describe('Case-insensitive literal substring'),
+            regex: z.string().optional().describe('JS regex source (without slashes), case-insensitive'),
+            limit: z.number().int().min(1).max(500).optional(),
+            version: versionParam,
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const { version, ...query } = args;
+            const res = await client.get(siteId, 'search', { ...query, ...v(version) });
+            return ok(res);
+        }),
+    },
+];

package/dist/tools/settings.js

@@ -0,0 +1,64 @@
+// Settings tools. scripts_head, scripts_body_end, and custom_css ARE
+// writable via the public API (as of mcp-server 0.4.x) — the v1 route
+// accepts them and they round-trip through read_site_settings. Same
+// trust model as user-authored block-type JS: a bearer-token caller
+// takes responsibility for what they ship. The portal chat AI still
+// doesn't expose these fields, so conversation-driven assistants can't
+// smuggle scripts in.
+import { z } from 'zod';
+import { ok, withErrorBoundary } from './helpers.js';
+export const settingsTools = [
+    {
+        name: 'read_site_settings',
+        description: "Read every site setting: name, tagline, logo, favicon, colors, fonts, contact info, social links, default SEO suffix, language, robots_txt, plus the scriptable surfaces scripts_head, scripts_body_end, and custom_css.",
+        handler: withErrorBoundary(async (_args, { client, siteId }) => {
+            const res = await client.get(siteId, 'settings');
+            return ok(res);
+        }),
+    },
+    {
+        name: 'update_site_settings',
+        description: 'Patch site settings. Only the fields you pass change. Nested objects (colors, fonts, contact, social) are shallow-merged. scripts_head / scripts_body_end / custom_css ARE writable here — useful for a global stylesheet across all pages. Whatever you ship in those fields runs verbatim on the rendered site, so treat them as code, not data.',
+        inputSchema: {
+            site_name: z.string().optional(),
+            tagline: z.string().optional(),
+            logo: z.string().optional(),
+            favicon: z.string().optional(),
+            default_seo_suffix: z.string().optional(),
+            language: z.string().optional().describe('BCP-47 tag (e.g. "en", "sv", "en-GB"). Drives <html lang> on the rendered site.'),
+            robots_txt: z.string().optional(),
+            // Scriptable surfaces. Trusted because the caller has an API key.
+            scripts_head: z.string().optional().describe('Raw HTML injected into <head> on every page. Use for analytics, fonts, third-party CSS links.'),
+            scripts_body_end: z.string().optional().describe('Raw HTML injected just before </body> on every page. Use for chat widgets, deferred analytics.'),
+            custom_css: z.string().optional().describe('Global CSS shipped in <style> at the end of <head>. Lets you define site-wide design tokens (CSS variables, @media queries, :hover states) without inlining on every element.'),
+            colors: z.record(z.string()).optional(),
+            fonts: z.record(z.unknown()).optional(),
+            contact: z
+                .object({
+                email: z.string().optional(),
+                phone: z.string().optional(),
+                // address can be a plain string (legacy) OR a structured
+                // PostalAddress for rich Schema.org JSON-LD.
+                address: z
+                    .union([
+                    z.string(),
+                    z.object({
+                        street_address: z.string().optional(),
+                        postal_code: z.string().optional(),
+                        address_locality: z.string().optional(),
+                        address_region: z.string().optional(),
+                        address_country: z.string().optional(),
+                    }).passthrough(),
+                ])
+                    .optional(),
+            })
+                .passthrough()
+                .optional(),
+            social: z.record(z.string()).optional(),
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.patch(siteId, 'settings', args);
+            return ok(res);
+        }),
+    },
+];

package/dist/tools/sites.js

@@ -0,0 +1,35 @@
+// Sites tools — discovery + Site-level identity edits.
+import { z } from 'zod';
+import { ok, withErrorBoundary } from './helpers.js';
+export const siteTools = [
+    {
+        name: 'get_site',
+        description: 'Read this site\'s metadata (id, name, slug, domain, active version) + a urls object covering the production / fallback / preview_base URLs. Useful as a first call to confirm the key is wired up and to learn what URLs the site is reachable at.',
+        handler: withErrorBoundary(async (_args, { client, siteId }) => {
+            const res = await client.get(siteId, '');
+            return ok(res);
+        }),
+    },
+    {
+        name: 'get_site_capabilities',
+        description: "Discover what the site-template renderer supports for this site. Returns a manifest of feature flags (blocks-mode, x-include, collection routes, custom block scripts, dry-run deploys, etc.) plus template_capabilities_version + the core block type ids. Call this when you're about to do something structural (set route_template on a collection, switch a page to blocks-mode, install a custom block type) and want to feature-detect rather than guess. The manifest is platform-wide today; per-site custom templates land later.",
+        handler: withErrorBoundary(async (_args, { client, siteId }) => {
+            const res = await client.get(siteId, 'capabilities');
+            return ok(res);
+        }),
+    },
+    {
+        name: 'update_site',
+        description: 'Edit Site-level identity fields: name (display), slug (drives the {slug}.typeroll-fallback subdomain — kebab-case, 3-48 chars, unique across the org), domain (the customer\'s real hostname; pass "" to clear). For colors / fonts / contact info / tagline use update_site_settings instead.',
+        inputSchema: {
+            name: z.string().min(1).optional(),
+            slug: z.string().optional().describe('Kebab-case identifier, 3-48 chars [a-z0-9-]. Empty string clears.'),
+            domain: z.string().optional().describe('Bare hostname e.g. "example.com". Empty string clears.'),
+            language: z.string().optional().describe('Default content language as a BCP-47 tag (e.g. "en", "sv", "en-GB"). Drives <html lang> and the default for alt-text generation. Empty string clears.'),
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.patch(siteId, '', args);
+            return ok(res);
+        }),
+    },
+];

package/dist/tools/versions.js

@@ -0,0 +1,52 @@
+// Version (branch) tools.
+import { z } from 'zod';
+import { ok, withErrorBoundary } from './helpers.js';
+export const versionTools = [
+    {
+        name: 'list_versions',
+        description: 'List versions (main + branches).',
+        handler: withErrorBoundary(async (_args, { client, siteId }) => {
+            const res = await client.get(siteId, 'versions');
+            return ok(res);
+        }),
+    },
+    {
+        name: 'create_branch',
+        description: 'Create a copy-on-write branch from main (or the version passed in `base`). New branches default to robots_blocked:true. Pass the new branch\'s id as ?version= on subsequent calls to read/write against it.',
+        inputSchema: {
+            name: z.string().min(1),
+            base: z.string().optional().describe('Source version id; defaults to main.'),
+        },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.post(siteId, 'versions', args);
+            return ok(res);
+        }),
+    },
+    {
+        name: 'read_version',
+        description: 'Read one version\'s metadata.',
+        inputSchema: { version_id: z.string() },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.get(siteId, `versions/${encodeURIComponent(args.version_id)}`);
+            return ok(res);
+        }),
+    },
+    {
+        name: 'delete_branch',
+        description: 'Discard a branch (main cannot be deleted).',
+        inputSchema: { version_id: z.string() },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.del(siteId, `versions/${encodeURIComponent(args.version_id)}`);
+            return ok(res);
+        }),
+    },
+    {
+        name: 'merge_branch',
+        description: 'Promote a branch\'s overrides + tombstones onto main. The branch is left in place so you can keep iterating; delete_branch removes it when you\'re done.',
+        inputSchema: { version_id: z.string() },
+        handler: withErrorBoundary(async (args, { client, siteId }) => {
+            const res = await client.post(siteId, `versions/${encodeURIComponent(args.version_id)}/merge`);
+            return ok(res);
+        }),
+    },
+];

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@typeroll/mcp-server",
+  "version": "0.7.4",
+  "description": "Model Context Protocol server for the Typeroll public API. Use with Claude Code or any MCP-compatible client to manage a Typeroll site.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/bootingbots/typeroll.git",
+    "directory": "packages/mcp-server"
+  },
+  "homepage": "https://github.com/bootingbots/typeroll/tree/main/packages/mcp-server#readme",
+  "bugs": "https://github.com/bootingbots/typeroll/issues",
+  "type": "module",
+  "bin": {
+    "typeroll-mcp": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "files": [
+    "dist",
+    "AGENTS.md",
+    "README.md",
+    "skills"
+  ],
+  "scripts": {
+    "build": "tsc -p .",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.6.0",
+    "vitest": "^4.1.7"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "mcp",
+    "typeroll",
+    "claude",
+    "model-context-protocol"
+  ]
+}

package/skills/README.md

@@ -0,0 +1,63 @@
+# Typeroll skills for Claude Code
+
+Boilerplate skills that pair with [`@typeroll/mcp-server`](../packages/mcp-server/README.md).
+Each one is a self-contained markdown file the agent reads when its
+description matches the user's request. Recipes call MCP tools; the agent
+adapts them to the specific job.
+
+## Installation
+
+Copy whichever skills you need into your Claude Code skills directory.
+Either:
+
+```bash
+# project-scoped (recommended)
+mkdir -p .claude/skills
+cp skills/*.md .claude/skills/
+
+# or user-scoped (available in every project)
+cp skills/*.md ~/.claude/skills/
+```
+
+Symlinks work too, so you can stay in sync with the upstream:
+
+```bash
+ln -s "$PWD/skills/tr-migrate-wp.md" ~/.claude/skills/
+```
+
+## The skills
+
+| File | When it triggers | What it does |
+|---|---|---|
+| `tr-migrate-wp.md`     | "migrate from WordPress", a wp-json URL is mentioned | Walks the WP REST, rebuilds each page in the target's design, transfers media, sets redirects, leaves everything as drafts for review |
+| `tr-content-write.md`  | "write a page about…", "draft copy for…"            | Discovery first (settings + sample pages), then drafts in the site's voice, previews, iterates |
+| `tr-images.md`         | "make an image / hero / illustration", media uploads | Generates locally → signed upload URL → metadata patch → embed |
+| `tr-directory.md`      | Building a directory site, importing structured data | Schema → items → per-item URLs via `route_template` → listing page → preview → deploy |
+| `tr-redesign-branch.md`| "redesign", "modernize", anything site-wide-design   | Branch-isolated work with preview links, merge when approved |
+
+## Prerequisites for every skill
+
+1. `@typeroll/mcp-server` configured in `.claude.json` with a valid
+   `TYPEROLL_API_KEY` and `TYPEROLL_API_URL`.
+2. The agent has read `AGENTS.md` (ships with the MCP package — see
+   `node_modules/@typeroll/mcp-server/AGENTS.md` after install, or
+   reference it directly).
+
+If those are missing, every skill will fail at the first MCP call with
+"Missing bearer token" or "Invalid or revoked token".
+
+## Authoring more
+
+Skills are markdown files that the agent loads on demand. Each one
+should include:
+
+- A `description:` frontmatter explaining when to load it (Claude uses
+  this to pick the right skill).
+- A clear set of preconditions (what MCP tools must work, what state the
+  agent needs to know).
+- A numbered recipe with concrete tool calls.
+- A "Pitfalls" section that captures lessons learned across customer
+  jobs.
+
+Keep them under ~150 lines so the agent reads them quickly. If a skill
+balloons, split it.

package/skills/tr-content-write.md

@@ -0,0 +1,105 @@
+---
+name: tr-content-write
+description: Use when the user asks to write, draft, or rewrite a page on a Typeroll site. Loads the site's design conventions before writing so the new content matches the existing voice and style.
+---
+
+# Write a page that fits the site
+
+The default failure mode for an AI writing a page is "good generic
+HTML in the wrong voice." This skill makes the discovery step
+non-optional.
+
+## Recipe
+
+### 1. Always discover first
+
+```
+get_site                          # site name (use it in copy)
+read_site_settings                # tagline, contact info, brand colors
+read_partial partial_id="header"  # what other pages exist in the nav
+list_pages limit=5
+batch_read_pages page_ids=[<2-3 representative pages>]
+```
+
+Read the actual HTML of an existing page. Note:
+- Heading structure (single `<h1>` per page? subtitle pattern?)
+- Whether the site uses CSS variables (`var(--color-primary)`) or
+  hardcoded values
+- Tone (sober, playful, technical, marketing-y)
+- Length conventions (do existing pages run 200 words or 2000?)
+- Whether internal links use absolute or relative URLs
+
+### 2. Ask for the brief
+
+If the user hasn't told you, ask:
+
+- **Topic + purpose**: what's the page for, who's it for?
+- **Key points**: must-include facts, calls to action
+- **Target length**: short landing vs. long-form
+- **Audience**: anything specific (existing customers, agencies,
+  developers)
+- **Reference page**: is there an existing page to match in tone or
+  structure?
+
+### 3. Draft
+
+Write in semantic HTML, matching the site's conventions you observed
+in step 1:
+
+- Use `<section>`, `<article>`, `<h1>`/`<h2>`, `<p>`, `<ul>` — avoid
+  div soup.
+- Match the existing site's class naming or CSS variable usage. Don't
+  introduce a new design system mid-page.
+- Insert images via `<img src="https://cdn..." alt="...">` — use
+  `list_media` to find existing images first; only generate new ones
+  if necessary (see `tr-images` skill).
+- Default status: `draft`. Don't auto-publish unless the user said so.
+
+### 4. Create or update
+
+```
+# New page:
+create_page title="..." slug="..." html_content="<full body>"
+            status="draft" kind="page"
+            seo_title="..." seo_description="..."
+
+# Or update an existing one:
+update_page page_id=<id> patch={ html_content: "..." }
+```
+
+For an existing page, `read_page` first and preserve the existing
+structure — replace one section at a time rather than rewriting the
+whole body, unless the user explicitly asked for a full redo.
+
+### 5. Preview + iterate
+
+```
+get_preview_link page_id=<id>
+```
+
+Show the URL to the user. Iterate on feedback. Common rounds:
+shortening, adding a CTA, tweaking SEO description.
+
+### 6. Status change is the user's call
+
+Don't `update_page status:"published"` without an explicit "looks
+good, publish it" from the user. Same for `trigger_deploy`.
+
+## SEO conventions worth knowing
+
+- **`kind: "article"`** for blog posts and news. Switches to
+  `og:type=article` + emits Article JSON-LD. Set `author` too — empty
+  author = no Person schema = no author rich-result eligibility.
+- **SEO title** target 50-60 chars. Past 60 Google truncates.
+- **Meta description** target 150-160 chars. Don't write fluff to
+  fill it; Google rewrites descriptions when they go off-topic.
+- **OG image** per page matters for shareable content. For articles
+  especially.
+
+## Pitfalls
+
+- Reading 0 pages and just inventing a design is the most common
+  failure. Always sample at least one existing page first.
+- Skipping the brief and producing 1000 words of plausible filler when
+  the user wanted a 200-word landing. Ask up front.
+- Auto-publishing. Don't.

package/skills/tr-directory.md

@@ -0,0 +1,214 @@
+---
+name: tr-directory
+description: Use when the user wants to build a directory site or import a structured dataset (restaurants, products, events, agencies, etc.) where each item should have its own URL. Covers collection schema creation, per-item URLs via route_template, listing page, deploy.
+---
+
+# Build a directory site from external data
+
+Typeroll collections support per-item URLs: every published item
+in a collection with a `route_template` materialises as its own static
+page at build time. This is the right pattern when you have hundreds
+of similar entities (restaurants, products, listings, profiles).
+
+## Big-picture flow
+
+1. **Data source** → 2. **Collection schema** → 3. **Items** → 4. **Listing page**
+→ 5. **Preview** → 6. **Deploy**
+
+You drive everything from Claude Code locally — the scrape, the data
+shaping, the writes. The MCP just receives the final shape.
+
+## Recipe
+
+### 1. Get the data
+
+Whatever source the user has — scraped CSV, public API, vendor feed,
+manual research, another LLM's output. Normalise to a flat shape:
+one object per item with stable, kebab-case field names.
+
+```jsonc
+[
+  {
+    "title": "Joe's Pizza",
+    "slug": "joes-pizza",
+    "address": "123 Main St, Anytown",
+    "phone": "+1-555-0100",
+    "cuisine": "italian",
+    "rating": 4.5,
+    "image": "https://...",        // optional: a hosted image URL
+    "excerpt": "Family-run since 1987...",
+    "body": "<p>Long-form description with HTML.</p>"
+  }
+]
+```
+
+The `slug` field is what populates `route_template`. Make it
+kebab-case, unique within the dataset. If the source doesn't have one,
+derive from `title`: lowercase, replace non-alphanumeric with `-`,
+collapse consecutive dashes.
+
+### 2. Decide the URL structure with the user
+
+Common patterns:
+
+- `/restaurants/{slug}` (default — simple, predictable)
+- `/r/{slug}` (compact)
+- `/{cuisine}/{slug}` (categorised)
+- `/dir/{slug}` (short prefix to avoid collisions with page slugs)
+
+Pick one before creating the collection — changing `route_template`
+later renames every URL and requires redirect rules.
+
+### 3. Create the collection schema
+
+```
+create_collection
+  name="restaurants"
+  label_singular="Restaurant"
+  label_plural="Restaurants"
+  icon="🍕"
+  fields=[
+    {"name":"title","label":"Name","type":"text","required":true},
+    {"name":"slug","label":"Slug","type":"text","required":true},
+    {"name":"address","label":"Address","type":"text"},
+    {"name":"phone","label":"Phone","type":"text"},
+    {"name":"cuisine","label":"Cuisine","type":"text"},
+    {"name":"rating","label":"Rating","type":"number"},
+    {"name":"image","label":"Image URL","type":"text"},
+    {"name":"excerpt","label":"Excerpt","type":"textarea"},
+    {"name":"body","label":"Body","type":"richtext"}
+  ]
+  slug_field="slug"
+  sort_field="title"
+  sort_dir="asc"
+  route_template="/restaurants/{slug}"
+  item_template_html="<article class=\"directory-item\">
+    <header>
+      <h1>{{title}}</h1>
+      {{cuisine}} · ⭐ {{rating}}
+    </header>
+    <img src=\"{{image}}\" alt=\"{{title}}\" />
+    <address>{{address}} · <a href=\"tel:{{phone}}\">{{phone}}</a></address>
+    <section class=\"description\">{{{body}}}</section>
+  </article>"
+```
+
+The `item_template_html` is what renders for each item. `{{field}}`
+HTML-escapes; `{{{field}}}` leaves raw (use for richtext bodies that
+intentionally carry HTML).
+
+### 4. Bulk-import items
+
+Loop over your data array. For each item:
+
+```
+create_collection_item
+  collection="restaurants"
+  fields={ title:"Joe's Pizza", slug:"joes-pizza", ... }
+  status="published"
+```
+
+For larger datasets (1000+), batch outside the MCP — spawn 5 parallel
+`create_collection_item` calls at a time, watch the 60-writes/min rate
+limit (you'll hit it on big imports, the API returns 429 with
+`Retry-After`).
+
+Set `status: "draft"` for items the user still needs to review; only
+published items get static pages.
+
+### 5. Build a listing page
+
+Items have per-item URLs but not a default index. Create one with a
+marker pair that `regenerate_collection_listing` will keep up to date:
+
+```
+create_page
+  title="Restaurants"
+  slug="restaurants"
+  status="published"
+  html_content="<h1>All restaurants</h1>
+    <!-- typeroll:listing:restaurants -->
+    <!-- /typeroll:listing:restaurants -->
+  "
+```
+
+Then populate (and refresh whenever items change) with one call:
+
+```
+regenerate_collection_listing
+  collection="restaurants"
+  page_id="restaurants"
+  item_template="<article class=\"directory-card\">
+    <h2><a href=\"{{url}}\">{{title}}</a></h2>
+    <p>{{cuisine}} · ⭐ {{rating}}</p>
+    <p>{{address}}</p>
+  </article>"
+  wrap_open="<div class=\"directory-grid\">"
+  wrap_close="</div>"
+```
+
+`{{field}}` substitutes HTML-escaped, `{{{field}}}` raw (for richtext
+fields), `{{url}}` resolves through the collection's `route_template`.
+The tool replaces only what's between the marker pair — anything before
+or after the markers stays put.
+
+When the customer adds a new restaurant later, the agent re-runs the
+same `regenerate_collection_listing` call and the index updates. No
+diff-the-HTML-by-hand, no stale listings.
+
+(When the block editor lands, you'll be able to drop in a "collection
+listing" block instead of hand-writing this. For now, raw HTML.)
+
+### 6. Preview an item
+
+```
+get_preview_link collection_name="restaurants" item_id="<id>"
+```
+
+Returns a URL the user can open. Internal links inside the preview
+stay inside the preview surface, so navigating to another item works.
+
+### 7. Deploy
+
+```
+trigger_deploy
+get_deploy_status job_id=<id>
+```
+
+Each published item gets its own URL in the static build, with
+`sitemap.xml` automatically including them all.
+
+## Pitfalls
+
+- **Slugs must be unique within the collection** — duplicates cause
+  build failures (two pages claiming the same URL). De-dupe before
+  importing.
+- **Don't reuse `slug` across collections without thinking.**
+  `/restaurants/joes` and `/products/joes` are fine; just avoid
+  `/joes` for both (collection items vs. pages don't collide because
+  pages always win, but two collections sharing a `slug_field=slug`
+  with the same `route_template` is a foot-gun).
+- **Required fields.** `route_template="/restaurants/{slug}"` will
+  silently skip items where `slug` is missing. Check
+  `list_collection_items` after import — if you imported 500 and the
+  listing only shows 480, look at the dropped 20's source data.
+- **Template too clever.** Substitution is plain `{{field}}` — no
+  loops, no conditionals. If your design needs more, prefer flat
+  fields (`star_html`, `rating_label`) prebuilt in the data step.
+- **Field type changes drift data.** Adding a new field after import
+  is fine; renaming one orphans the old data on every item. Plan the
+  schema before import.
+
+## Mixing scraped + generated content
+
+The whole point of the local-agent model: you can blend sources.
+
+- Scrape addresses + phone from a yellow-pages site.
+- Generate excerpt + body from a local Claude pass over the raw
+  scraped HTML.
+- Generate hero images per item via `tr-images`.
+- All three merged into one `create_collection_item` per record.
+
+Keep a local manifest (`./directory-state.json`) of what's been
+imported so a partial run is resumable. The MCP doesn't track that
+state — your local script does.