@typeroll/mcp-server 0.7.4 → 0.7.7

package/dist/index.js

@@ -17,6 +17,7 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { TyperollClient } from './client.js';
+import { runInstallSkillsCli } from './install-skills.js';
 import { pageTools } from './tools/pages.js';
 import { partialTools } from './tools/partials.js';
 import { collectionTools } from './tools/collections.js';
@@ -32,7 +33,7 @@ import { blockTypeTools } from './tools/block-types.js';
 import { pageBlockTools } from './tools/page-blocks.js';
 import { settingsTools } from './tools/settings.js';
 import { siteTools } from './tools/sites.js';
-const VERSION = '0.1.0';
+const VERSION = '0.7.7';
 async function resolveSiteId(client) {
     const fromEnv = process.env.TYPEROLL_SITE_ID?.trim();
     if (fromEnv)
@@ -53,6 +54,20 @@ function bail(message) {
     process.exit(1);
 }
 async function main() {
+    // Subcommand dispatch. These run without any of the MCP-server env-var
+    // validation below, since they don't talk to the portal.
+    const argv = process.argv.slice(2);
+    if (argv[0] === 'install-skills') {
+        const code = await runInstallSkillsCli(argv.slice(1));
+        process.exit(code);
+    }
+    if (argv[0] === '--help' || argv[0] === '-h' || argv[0] === 'help') {
+        console.error('Usage:');
+        console.error('  typeroll-mcp                              Start the MCP server (reads TYPEROLL_API_URL and TYPEROLL_API_KEY)');
+        console.error('  typeroll-mcp install-skills <dir> [-f]    Copy bundled skill files to <dir>');
+        console.error('  typeroll-mcp --help                       Show this help');
+        process.exit(0);
+    }
     const apiUrl = process.env.TYPEROLL_API_URL?.trim();
     const apiKey = process.env.TYPEROLL_API_KEY?.trim();
     if (!apiUrl)

package/dist/install-skills.js

@@ -0,0 +1,130 @@
+// install-skills subcommand for the typeroll-mcp CLI.
+//
+// Copies the bundled skill markdown files from this package's `skills/`
+// directory into a destination directory the user provides. Used to seed
+// `.claude/skills/` (project scope) or `~/.claude/skills/` (user scope) so
+// Claude Code picks up Typeroll-specific skill recipes.
+//
+// This subcommand does NOT need TYPEROLL_API_URL / TYPEROLL_API_KEY — it's a
+// pure file copy. Putting the dispatch in index.ts before the env-var
+// validation is the only thing that matters for that.
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+// Resolve the bundled skills directory. At runtime this file lives at
+// <package>/dist/install-skills.js (after tsc); skills/ is a sibling of dist/.
+// fileURLToPath gives us a real OS path that works on every platform.
+function skillsDir() {
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    return path.resolve(here, '..', 'skills');
+}
+/**
+ * Copy all `tr-*.md` files from the bundled skills directory to `dest`.
+ * Returns a summary so callers can render output. Throws on filesystem errors
+ * the caller didn't ask for.
+ */
+export async function installSkills(opts) {
+    const source = opts.sourceDir ?? skillsDir();
+    const force = opts.force ?? false;
+    // Validate the source dir exists. If this fails the package install is
+    // broken (skills/ missing from the tarball) — surface clearly.
+    try {
+        const stat = await fs.stat(source);
+        if (!stat.isDirectory()) {
+            throw new Error(`bundled skills path is not a directory: ${source}`);
+        }
+    }
+    catch (e) {
+        const reason = e instanceof Error ? e.message : String(e);
+        throw new Error(`could not find bundled skills directory at ${source}: ${reason}`);
+    }
+    // Resolve destination. Create it if missing (mkdir -p semantics).
+    const dest = path.resolve(opts.dest);
+    await fs.mkdir(dest, { recursive: true });
+    // Only copy tr-*.md — README.md in skills/ is package-internal, not a skill.
+    const entries = await fs.readdir(source);
+    const skillFiles = entries.filter((f) => f.startsWith('tr-') && f.endsWith('.md')).sort();
+    const copied = [];
+    const skipped = [];
+    for (const file of skillFiles) {
+        const target = path.join(dest, file);
+        if (!force) {
+            try {
+                await fs.access(target);
+                skipped.push(file);
+                continue;
+            }
+            catch {
+                // File doesn't exist — proceed to copy.
+            }
+        }
+        await fs.copyFile(path.join(source, file), target);
+        copied.push(file);
+    }
+    return { destination: dest, copied, skipped };
+}
+/**
+ * CLI entry point — parses argv (after the subcommand token has been
+ * removed) and prints human-readable output. Returns exit code.
+ */
+export async function runInstallSkillsCli(args) {
+    let dest;
+    let force = false;
+    for (const arg of args) {
+        if (arg === '--force' || arg === '-f') {
+            force = true;
+        }
+        else if (arg === '--help' || arg === '-h') {
+            printHelp();
+            return 0;
+        }
+        else if (!dest && !arg.startsWith('-')) {
+            dest = arg;
+        }
+        else {
+            console.error(`typeroll-mcp install-skills: unrecognised argument: ${arg}`);
+            printHelp();
+            return 1;
+        }
+    }
+    if (!dest) {
+        console.error('typeroll-mcp install-skills: missing destination directory.');
+        printHelp();
+        return 1;
+    }
+    try {
+        const result = await installSkills({ dest, force });
+        const total = result.copied.length + result.skipped.length;
+        console.log(`typeroll-mcp: installed skills to ${result.destination}`);
+        console.log(`  copied:  ${result.copied.length}/${total}`);
+        if (result.skipped.length > 0) {
+            console.log(`  skipped: ${result.skipped.length} (already exist; rerun with --force to overwrite)`);
+            for (const f of result.skipped)
+                console.log(`    - ${f}`);
+        }
+        if (result.copied.length > 0) {
+            for (const f of result.copied)
+                console.log(`    + ${f}`);
+        }
+        return 0;
+    }
+    catch (e) {
+        const reason = e instanceof Error ? e.message : String(e);
+        console.error(`typeroll-mcp install-skills: ${reason}`);
+        return 1;
+    }
+}
+function printHelp() {
+    console.error('');
+    console.error('Usage: npx @typeroll/mcp-server install-skills <destination> [--force]');
+    console.error('');
+    console.error('Copies bundled Typeroll skill markdown files to the destination directory.');
+    console.error('');
+    console.error('Common destinations:');
+    console.error('  .claude/skills          Project-scoped (recommended)');
+    console.error('  ~/.claude/skills        User-scoped (available in every project)');
+    console.error('');
+    console.error('Options:');
+    console.error('  --force, -f             Overwrite files that already exist');
+    console.error('  --help,  -h             Show this help');
+}

package/dist/tools/pages.js

@@ -7,11 +7,12 @@ function v(version) {
 export const pageTools = [
     {
         name: 'list_pages',
-        description: 'List pages on the active site. Returns id, title, slug, status, and SEO summary. Supports filtering by status and forward-cursor pagination.',
+        description: 'List pages on the active site. Returns id, title, slug, status, and SEO summary (no html_content by default — use read_page or batch_read_pages for body content). Supports filtering by status and forward-cursor pagination. Pass full=true to include html_content + blocks in the response.',
         inputSchema: {
             status: z.enum(['draft', 'review', 'unlisted', 'published', 'all']).optional(),
             limit: z.number().int().min(1).max(200).optional(),
             cursor: z.string().optional(),
+            full: z.boolean().optional().describe('Set true to include html_content + blocks. Default false (summary only) to avoid large payloads on sites with many pages.'),
             version: versionParam,
         },
         handler: withErrorBoundary(async (args, { client, siteId }) => {
@@ -19,6 +20,7 @@ export const pageTools = [
                 status: args.status,
                 limit: args.limit,
                 cursor: args.cursor,
+                full: args.full ? 'true' : undefined,
                 ...v(args.version),
             });
             return ok(res);
@@ -38,23 +40,37 @@ export const pageTools = [
     },
     {
         name: 'batch_read_pages',
-        description: 'Read up to 200 pages in a single call. Use to bulk-load context before a redesign sweep.',
+        description: 'Read up to 200 pages in a single call. Returns pages_by_id — a map keyed by page_id for easy lookup — plus a not_found list. Use to bulk-load context before a redesign sweep.',
         inputSchema: {
             page_ids: z.array(z.string()).min(1).max(200),
             version: versionParam,
         },
         handler: withErrorBoundary(async (args, { client, siteId }) => {
             const res = await client.post(siteId, 'pages/batch-read', { page_ids: args.page_ids }, v(args.version));
-            return ok(res);
+            // Transform array → map keyed by page_id for ergonomic access.
+            const pages_by_id = {};
+            const not_found = [];
+            for (const entry of res.pages ?? []) {
+                if (entry.found && entry.page)
+                    pages_by_id[entry.page_id] = entry.page;
+                else
+                    not_found.push(entry.page_id);
+            }
+            return ok({ pages_by_id, not_found });
         }),
     },
     {
         name: 'create_page',
-        description: 'Create a new page. Defaults to blocks-mode (recommended) — the new page seeds with a heading + prose block built from the title. Pass content_mode="html" to opt out. Slug is derived from title when omitted; default status is "draft". Returns the created page.',
+        description: 'Create a new page. Defaults to html mode — pass html_content to set the body. ' +
+            'Slug is derived from the title when omitted. Default status is "draft". ' +
+            'Homepage convention: pass slug="" (empty string) or omit slug and set title to "Home"; ' +
+            'the server stores it under id "home" with slug "". ' +
+            'Do NOT pass slug="/"; strip leading slashes from slugs (use "about", not "/about"). ' +
+            'Returns the created page including html_content.',
         inputSchema: {
             title: z.string().min(1),
-            slug: z.string().optional(),
-            content_mode: z.enum(['blocks', 'html']).optional().describe('Default "blocks". "html" stores body in html_content; "blocks" stores a Block[] tree.'),
+            slug: z.string().optional().describe('URL slug without leading slash (e.g. "about", "services/design"). Empty string "" = homepage.'),
+            content_mode: z.enum(['blocks', 'html']).optional().describe('Default "html". "html" stores body in html_content; "blocks" stores a Block[] tree (note: blocks mode pages render as empty until the block editor ships — use html mode for all real content).'),
             html_content: z.string().optional().describe('Body HTML — only used when content_mode="html".'),
             blocks: z.array(z.any()).optional().describe('Block tree — only used when content_mode="blocks". Omit to get the default heading+prose seed.'),
             status: z.enum(['draft', 'review', 'unlisted', 'published']).optional(),

package/dist/tools/partials.js

@@ -54,14 +54,19 @@ export const partialTools = [
     },
     {
         name: 'replace_partial',
-        description: 'Full replace of a global block (PUT). Use this when you want to set every field including auto-inferring kind from id.',
+        description: 'Full replace of a global block (PUT). Pass html_content (and optionally name/status) directly — no wrapper object needed. ' +
+            'kind is auto-inferred from partial_id ("header" → header, "footer" → footer, anything else → free). ' +
+            'For incremental edits (changing one field without replacing the whole block) use update_partial instead.',
         inputSchema: {
-            partial_id: z.string(),
-            partial: z.object({ html_content: z.string() }).passthrough(),
+            partial_id: z.string().describe('"header", "footer", or a free-block kebab-id.'),
+            html_content: z.string().describe('Full HTML for the block. Replaces any existing content.'),
+            name: z.string().optional().describe('Human-readable label shown in the UI.'),
+            status: z.enum(['draft', 'published']).optional(),
             version: versionParam,
         },
         handler: withErrorBoundary(async (args, { client, siteId }) => {
-            const res = await client.put(siteId, `partials/${encodeURIComponent(args.partial_id)}`, args.partial, v(args.version));
+            const { version, partial_id, ...fields } = args;
+            const res = await client.put(siteId, `partials/${encodeURIComponent(partial_id)}`, fields, v(version));
             return ok(res);
         }),
     },

package/dist/tools/search.js

@@ -6,10 +6,13 @@ function v(version) {
 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.',
+        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. ' +
+            'Pass either "contains" (case-insensitive literal) or "regex" (JS regex source without slashes) — not both. ' +
+            'Example: search_pages({"contains": "kontakta oss"}) finds every page mentioning that phrase. ' +
+            'Example: search_pages({"regex": "\\\\d{3}-\\\\d{3}"}) finds pages with phone-number patterns.',
         inputSchema: {
-            contains: z.string().optional().describe('Case-insensitive literal substring'),
-            regex: z.string().optional().describe('JS regex source (without slashes), case-insensitive'),
+            contains: z.string().optional().describe('Case-insensitive literal substring. Example: "kontakta oss"'),
+            regex: z.string().optional().describe('JS regex source without surrounding slashes, case-insensitive. Example: "\\\\d{3}-\\\\d{3}" matches phone patterns.'),
             limit: z.number().int().min(1).max(500).optional(),
             version: versionParam,
         },

package/dist/tools/settings.js

@@ -18,7 +18,12 @@ export const settingsTools = [
     },
     {
         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.',
+        description: 'Patch site settings. Only the fields you pass change. ' +
+            'Pass fields at the TOP LEVEL of the object — do NOT wrap in a "settings" key. ' +
+            'Example: {"site_name": "Acme", "colors": {"primary": "#ff0"}} not {"settings": {...}}. ' +
+            'Nested objects (colors, fonts, contact, social) are shallow-merged into the existing value. ' +
+            'Unknown top-level keys return a 400 error listing the valid fields. ' +
+            'scripts_head / scripts_body_end / custom_css ARE writable here — useful for a global stylesheet across all pages.',
         inputSchema: {
             site_name: z.string().optional(),
             tagline: z.string().optional(),

package/package.json

@@ -1,18 +1,18 @@
 {
   "name": "@typeroll/mcp-server",
-  "version": "0.7.4",
+  "version": "0.7.7",
   "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",
+    "url": "git+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"
+    "typeroll-mcp": "dist/index.js"
   },
   "main": "./dist/index.js",
   "files": [

package/skills/README.md

@@ -27,13 +27,31 @@ ln -s "$PWD/skills/tr-migrate-wp.md" ~/.claude/skills/
 
 ## The skills
 
+### Bygga och designa
+
+| File | When it triggers | What it does |
+|---|---|---|
+| `tr-new-site.md`       | "create a new site", "bootstrap a site for…"        | Settings → header/footer partials → homepage → inner pages → deploy. Full setup recipe. |
+| `tr-brand.md`          | "create a brand", "choose colors", "design the look"| Palette recipes by mood, typography pairings, CSS variable setup, preview. |
+| `tr-redesign-branch.md`| "redesign", "modernize", anything site-wide-design   | Branch-isolated work with preview links, merge when approved. |
+| `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. |
+
+### Funktioner
+
+| File | When it triggers | What it does |
+|---|---|---|
+| `tr-blog.md`           | "add a blog", "set up news", "article section"      | Collection schema → seed items → listing page → per-article pages → nav update → deploy. |
+| `tr-forms.md`          | "contact form", "add a form", "booking form"        | Form definition → embed HTML with signed token → inline JS feedback → deploy. |
+| `tr-directory.md`      | Building a directory site, importing structured data | Schema → items → per-item URLs via `route_template` → listing page → preview → deploy. |
+| `tr-seo.md`            | "SEO", "meta descriptions", "structured data"       | Audit → fix titles/descriptions → OG images → JSON-LD → robots.txt → deploy. |
+
+### Importera innehåll
+
 | 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 |
+| `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-import-url.md`     | "import from Squarespace/Wix/Webflow", any non-WP URL| Fetch → clean → adapt to target design → media transfer → draft pages → redirects → deploy. |
 
 ## Prerequisites for every skill
 

package/skills/tr-blog.md

@@ -0,0 +1,177 @@
+---
+name: tr-blog
+description: Use when the user wants to set up a blog, news section, or article feed on a Typeroll site. Triggers on "add a blog", "set up news", "article section", "create posts", "inlägg", "nyheter", or when the user wants to manage a list of dated articles.
+---
+
+# Set up a blog / news section
+
+Typeroll doesn't have a built-in blog — instead the AI writes listing HTML
+directly into a page, sourced from a collection. This skill wires the whole
+flow: collection schema → seed items → listing page → individual item URLs
+via `route_template` → deploy.
+
+## Preconditions
+
+- Site exists with working header/footer.
+- You know the desired collection name (e.g. `blog`, `news`, `artiklar`).
+
+## Recipe
+
+### 1. Create the collection
+
+```
+create_collection {
+  "name": "blog",
+  "label_singular": "Artikel",
+  "label_plural": "Artiklar",
+  "slug_field": "slug",
+  "sort_field": "date",
+  "sort_dir": "desc",
+  "route_template": "/blog/{slug}",
+  "fields": [
+    {"name": "title",    "type": "text",     "label": "Rubrik",    "required": true},
+    {"name": "slug",     "type": "text",     "label": "URL-slug",  "required": true},
+    {"name": "date",     "type": "date",     "label": "Datum",     "required": true},
+    {"name": "author",   "type": "text",     "label": "Författare"},
+    {"name": "excerpt",  "type": "textarea", "label": "Ingress"},
+    {"name": "body",     "type": "richtext", "label": "Brödtext"},
+    {"name": "image",    "type": "image",    "label": "Omslagsbild"},
+    {"name": "tags",     "type": "text",     "label": "Taggar (kommaseparerade)"}
+  ]
+}
+```
+
+**Field name rule:** ASCII only, lowercase. `ä→a`, `ö→o`, `å→a`.
+
+### 2. Seed with real content
+
+Add 2–3 initial articles. Use `create_collection_item`:
+
+```
+create_collection_item collection="blog" fields={
+  "title":   "Vår designfilosofi",
+  "slug":    "var-designfilosofi",
+  "date":    "2025-05-15",
+  "author":  "Anna Lindström",
+  "excerpt": "Vi tror på enkelhet med syfte — varje beslut ska kunna motiveras.",
+  "body":    "<p>...</p>",
+  "image":   "https://cdn.typeroll.com/..."
+}
+```
+
+If `image` is a URL, upload it first via `upload_media_from_url` and use
+the returned CDN URL.
+
+### 3. List all items for the listing page
+
+```
+list_collection_items collection="blog"
+```
+
+Use the response to generate the listing HTML. The static site has no
+template engine — the HTML is the listing.
+
+### 4. Create the listing page
+
+Build HTML manually from the collection items. Include all the data you
+want visible without a detail click. Example structure:
+
+```html
+<section class="blog-listing">
+  <div class="container">
+    <h1 class="section-title">Artiklar</h1>
+    <div class="blog-grid">
+      <!-- one .blog-card per item -->
+      <article class="blog-card">
+        <a href="/blog/var-designfilosofi">
+          <img src="https://cdn.typeroll.com/..." alt="Omslagsbild">
+          <div class="blog-card__body">
+            <time class="blog-card__date">15 maj 2025</time>
+            <h2 class="blog-card__title">Vår designfilosofi</h2>
+            <p class="blog-card__excerpt">Vi tror på enkelhet med syfte...</p>
+            <span class="blog-card__cta">Läs mer →</span>
+          </div>
+        </a>
+      </article>
+    </div>
+  </div>
+</section>
+<style>
+.blog-grid{display:grid;grid-template-columns:repeat(auto-fill,minmax(300px,1fr));gap:2rem}
+.blog-card{border:1px solid var(--color-surface);border-radius:0.5rem;overflow:hidden}
+.blog-card a{text-decoration:none;display:block;color:var(--color-text)}
+.blog-card img{width:100%;aspect-ratio:16/9;object-fit:cover}
+.blog-card__body{padding:1.5rem}
+.blog-card__date{font-size:0.8rem;color:var(--color-text-light);display:block;margin-bottom:0.5rem}
+.blog-card__title{font-family:var(--font-heading);font-size:1.25rem;margin-bottom:0.5rem}
+.blog-card__excerpt{color:var(--color-text-light);font-size:0.9rem;margin-bottom:1rem}
+.blog-card__cta{color:var(--color-accent);font-size:0.85rem;font-weight:600}
+</style>
+```
+
+```
+create_page title="Artiklar" slug="blog"
+            html_content="<listing HTML>"
+            content_mode="html" status="published"
+```
+
+### 5. Create individual article pages
+
+Each collection item with `route_template: "/blog/{slug}"` gets its own
+URL at deploy time IF you create a matching page for each article. Create
+one page per article:
+
+```
+create_page title="Vår designfilosofi" slug="blog/var-designfilosofi"
+            html_content="<full article HTML>"
+            content_mode="html" kind="article"
+            author="Anna Lindström"
+            seo_title="Vår designfilosofi — Acme Studio"
+            seo_description="Ingress here"
+            status="published"
+```
+
+The slug `blog/var-designfilosofi` maps to URL `/blog/var-designfilosofi`.
+
+**Important:** Typeroll does NOT auto-generate detail pages from collection
+items. You write the detail HTML per article — this gives full control over
+the design but means each article is a separate `create_page` call.
+
+### 6. Update nav to link to the blog
+
+Read the header partial and add a "Blog" or "Artiklar" link:
+```
+read_partial partial_id="header"
+replace_partial partial_id="header" html_content="<updated with blog link>"
+```
+
+### 7. Keep listings in sync
+
+When new articles are added later, the AI must:
+1. `create_collection_item` with the article data
+2. `create_page` for the article's detail URL
+3. Re-read the full collection via `list_collection_items`
+4. Regenerate the listing HTML and `update_page` the listing page
+
+Or call `regenerate_collection_listing collection="blog"` if the site has
+that route configured — it reruns the listing generation.
+
+### 8. Deploy
+
+```
+trigger_deploy
+get_deploy_status job_id=<id>
+```
+
+## Pitfalls
+
+- **Listing page goes stale.** Every new article needs the listing page
+  regenerated. There's no auto-sync; you must update the HTML.
+- **Don't use non-ASCII field names.** `datum` not `datum`, `rubrik` not
+  `Rubrik` as the field name. The `label` can be anything; the `name` must
+  be `[a-z][a-z0-9_-]*`.
+- **Article slugs must be globally unique.** `/blog/` prefix in the slug
+  avoids collisions with non-blog pages.
+- **`route_template` is decorative without matching pages.** The template
+  declares the URL structure; actual routing depends on pages existing at
+  those paths. Always create the page.