@typeroll/mcp-server 0.7.5 → 0.7.8

package/README.md

@@ -1,20 +1,46 @@
 # @typeroll/mcp-server
 
 Model Context Protocol server for the [Typeroll](https://typeroll.com)
-public API. Lets Claude Code (or any MCP-compatible client) manage a
-Typeroll site through the same tool surface a human agency would use:
-read and write pages, partials, collections, media, redirects, versions;
-trigger deploys; mint preview links.
+public API. Lets Claude (Desktop / claude.ai / Code) manage a Typeroll
+site through the same tool surface a human agency would use: read and
+write pages, partials, collections, media, redirects, versions; trigger
+deploys; mint preview links.
 
 The server is a **thin transport adapter** — every tool wraps one HTTP
-endpoint of the Typeroll REST API. Auth happens at the API layer with
-a site-scoped key; the MCP just carries the bearer through.
+endpoint of the Typeroll REST API. Auth happens at the API layer with a
+site- or org-scoped key; the MCP just carries the bearer through.
 
-## Quick start
+## Two ways to connect
 
-1. **Create an API key** in your Typeroll portal at
-   `/app/sites/{siteId}/settings/api-keys`. The key is shown once at
-   creation — copy it somewhere safe.
+- **Hosted (Claude Desktop / claude.ai) — paste a URL.** No CLI, no
+  Node.js install. In Claude open **Settings → Connectors → Add custom
+  connector** and paste `https://app.typeroll.com/api/mcp`
+  (or `https://<your-self-hosted-portal>/mcp`). Claude opens a consent
+  page; paste your Typeroll API key there.
+- **Stdio (Claude Code) — one `claude mcp add` command.** Best for local
+  dev / agency staff already in a terminal. Instructions below.
+
+This npm package is the stdio transport. The hosted endpoint ships as
+part of the Typeroll portal itself — same tool surface, same package
+under the hood.
+
+## Key scopes
+
+- **Org-scoped key** (created at `/app/settings/api-keys`) — one
+  credential covers every site in your org *and* every site shared into
+  your org. The default for the hosted Claude connector. Stdio works too
+  if you set `TYPEROLL_SITE_ID` so the install binds to one site.
+- **Site-scoped key** (created at `/app/sites/{siteId}/settings/api-keys`) —
+  tighter blast radius for a single-site credential, e.g. one you'd
+  hand to a customer for a self-managed site.
+
+Both look like `typeroll_live_…`; revoke either from the portal and any
+client using it stops working immediately.
+
+## Stdio quick start (Claude Code)
+
+1. **Create an API key** in your Typeroll portal — see the two scope
+   options above. Org-scoped is the right default.
 
 2. **Add the server to Claude Code.** Drop this into `~/.claude.json`
    (or your local `.claude/config.json`):
@@ -46,13 +72,13 @@ a site-scoped key; the MCP just carries the bearer through.
    Claude will call `get_site`, `list_pages`, `list_partials`,
    `list_collections` in sequence and report back.
 
-## Environment variables
+## Environment variables (stdio)
 
 | Var             | Required | Description |
 |-----------------|----------|-------------|
 | `TYPEROLL_API_URL`  | yes      | Base URL of your Typeroll portal. |
-| `TYPEROLL_API_KEY`  | yes      | A `typeroll_live_…` bearer token from the API keys page. |
-| `TYPEROLL_SITE_ID`  | no       | Pin the server to a specific site. Defaults to autodetect (calls `GET /v1/sites` — per-site keys return exactly one). |
+| `TYPEROLL_API_KEY`  | yes      | A `typeroll_live_…` bearer token. |
+| `TYPEROLL_SITE_ID`  | sometimes | Pin to a specific site. Required when using an org-scoped key over stdio (the install can only target one site at a time); auto-detected for site-scoped keys. |
 
 ## What the agent should read first
 

package/dist/index.js

@@ -3,48 +3,31 @@
 //
 // Reads two env vars at startup:
 //   TYPEROLL_API_URL  — base URL of the portal (e.g. https://app.typeroll.com)
-//   TYPEROLL_API_KEY  — a typeroll_live_... bearer token from /app/sites/{id}/settings/api-keys
+//   TYPEROLL_API_KEY  — a typeroll_live_... bearer token from the portal
 //
 // Optionally:
 //   TYPEROLL_SITE_ID  — pre-set the site id. If omitted we discover it by
-//                   calling GET /v1/sites at startup (the v1 keys are
-//                   per-site so that endpoint always returns exactly one).
-//
-// Each tool wraps a single REST endpoint. The MCP server itself does no
-// business logic — that all lives in the portal. This keeps the package
-// boring to maintain and lets the customer's self-hosted portal serve the
-// same MCP without needing two implementations to stay in sync.
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+//                   calling GET /v1/sites at startup. For site-scoped keys
+//                   that endpoint always returns exactly one. For org-scoped
+//                   keys (introduced for the hosted MCP connector) it can
+//                   return many — in that case TYPEROLL_SITE_ID is required
+//                   so this stdio invocation maps onto one specific site.
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { TyperollClient } from './client.js';
-import { pageTools } from './tools/pages.js';
-import { partialTools } from './tools/partials.js';
-import { collectionTools } from './tools/collections.js';
-import { mediaTools } from './tools/media.js';
-import { redirectTools } from './tools/redirects.js';
-import { formTools } from './tools/forms.js';
-import { searchTools } from './tools/search.js';
-import { bulkTools } from './tools/bulk.js';
-import { versionTools } from './tools/versions.js';
-import { deployTools } from './tools/deploy.js';
-import { previewTools } from './tools/preview.js';
-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';
+import { runInstallSkillsCli } from './install-skills.js';
+import { buildServer } from './server.js';
+const VERSION = '0.7.8';
 async function resolveSiteId(client) {
     const fromEnv = process.env.TYPEROLL_SITE_ID?.trim();
     if (fromEnv)
         return fromEnv;
-    // Per-site keys → exactly one site. We fetch it so the agent doesn't
-    // have to know its own site id ahead of time.
     const res = await client.rootGet('sites');
     if (!res.sites || res.sites.length === 0) {
         throw new Error('No sites returned for this API key. Check the key is valid.');
     }
     if (res.sites.length > 1) {
-        throw new Error(`This key authorises ${res.sites.length} sites; set TYPEROLL_SITE_ID to pick one.`);
+        throw new Error(`This key authorises ${res.sites.length} sites; set TYPEROLL_SITE_ID to pick one. ` +
+            'Org-scoped keys span multiple sites — stdio currently binds to one at a time.');
     }
     return res.sites[0].id;
 }
@@ -53,6 +36,18 @@ function bail(message) {
     process.exit(1);
 }
 async function main() {
+    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)
@@ -70,41 +65,11 @@ async function main() {
     catch (e) {
         bail(`Failed to discover site: ${e instanceof Error ? e.message : String(e)}`);
     }
-    const deps = { client, siteId };
-    const server = new McpServer({ name: 'typeroll', version: VERSION }, { capabilities: { tools: {} } });
-    const allTools = [
-        ...siteTools,
-        ...pageTools,
-        ...partialTools,
-        ...blockTypeTools,
-        ...pageBlockTools,
-        ...collectionTools,
-        ...mediaTools,
-        ...redirectTools,
-        ...formTools,
-        ...settingsTools,
-        ...searchTools,
-        ...bulkTools,
-        ...versionTools,
-        ...deployTools,
-        ...previewTools,
-    ];
-    // The SDK's registerTool signature has very deep generic constraints
-    // (ZodRawShape × AnySchema × annotations) that TypeScript can't unify
-    // when we iterate heterogeneous tools at runtime. We cast the bag once
-    // here and rely on our own ToolDef contract for type safety.
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    const register = server.registerTool.bind(server);
-    for (const tool of allTools) {
-        register(tool.name, {
-            description: tool.description,
-            ...(tool.inputSchema ? { inputSchema: tool.inputSchema } : {}),
-        }, 
-        // The SDK's callback gets the args object (when inputSchema is set) or
-        // no args (when it isn't). Both are valid for our handler signature.
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        async (args) => tool.handler(args ?? {}, deps));
-    }
+    const server = buildServer({
+        client,
+        fixedSiteId: siteId,
+        info: { name: 'typeroll', version: VERSION },
+    });
     const transport = new StdioServerTransport();
     await server.connect(transport);
 }

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/server.js

@@ -0,0 +1,129 @@
+// Transport-agnostic MCP server builder. Wraps an McpServer instance with
+// the full Typeroll tool surface and either binds it to a single fixed site
+// (stdio, site-scoped HTTP) or makes it multi-site (org-scoped HTTP).
+//
+// In multi-site mode every tool's input schema gains a required `site_id`
+// argument; the handler wrapper validates that the id is in the allowed
+// list AND that the share's permission level covers the operation (read
+// vs write). This is the plumbing the hosted MCP plan calls out as
+// safety-critical when one connector can touch many sites.
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { pageTools } from './tools/pages.js';
+import { partialTools } from './tools/partials.js';
+import { collectionTools } from './tools/collections.js';
+import { mediaTools } from './tools/media.js';
+import { redirectTools } from './tools/redirects.js';
+import { formTools } from './tools/forms.js';
+import { searchTools } from './tools/search.js';
+import { bulkTools } from './tools/bulk.js';
+import { versionTools } from './tools/versions.js';
+import { deployTools } from './tools/deploy.js';
+import { previewTools } from './tools/preview.js';
+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';
+import { fail } from './tools/helpers.js';
+const PERM_RANK = { read: 0, write: 1, admin: 2 };
+/**
+ * Classify a tool by name into the minimum permission needed. We keep this
+ * conservative — anything that mutates is `write`. The MCP route's per-call
+ * gate then checks `effect <= sitePermission`.
+ *
+ * Naming convention is followed by all 16 tool files: read paths are
+ * `list_*` / `read_*` / `get_*` / `preview_*` / `search_*`; everything else
+ * mutates.
+ */
+function effectFor(name) {
+    if (name.startsWith('list_') ||
+        name.startsWith('read_') ||
+        name.startsWith('get_') ||
+        name.startsWith('batch_read_') ||
+        name.startsWith('preview_') ||
+        name.startsWith('search_')) {
+        return 'read';
+    }
+    return 'write';
+}
+const DEFAULT_INFO = { name: 'typeroll', version: '0.7.8' };
+export function buildServer(options) {
+    if (!options.fixedSiteId && !options.allowedSites) {
+        throw new Error('buildServer: either fixedSiteId or allowedSites must be provided');
+    }
+    if (options.fixedSiteId && options.allowedSites) {
+        throw new Error('buildServer: provide only one of fixedSiteId / allowedSites');
+    }
+    const server = new McpServer(options.info ?? DEFAULT_INFO, {
+        capabilities: { tools: {} },
+    });
+    const allTools = [
+        ...siteTools,
+        ...pageTools,
+        ...partialTools,
+        ...blockTypeTools,
+        ...pageBlockTools,
+        ...collectionTools,
+        ...mediaTools,
+        ...redirectTools,
+        ...formTools,
+        ...settingsTools,
+        ...searchTools,
+        ...bulkTools,
+        ...versionTools,
+        ...deployTools,
+        ...previewTools,
+    ];
+    // SDK's registerTool has deeply-nested generics we can't unify across a
+    // heterogeneous tool list at compile time — same shrug as stdio's index.ts.
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const register = server.registerTool.bind(server);
+    const isMultiSite = !!options.allowedSites;
+    const allowedById = new Map((options.allowedSites ?? []).map((s) => [s.siteId, s]));
+    for (const tool of allTools) {
+        const effect = effectFor(tool.name);
+        let schema = tool.inputSchema;
+        if (isMultiSite) {
+            // Append site_id to the tool's existing input schema. We mutate a copy
+            // so we don't pollute the imported ToolDef.
+            const siteIdField = {
+                site_id: z
+                    .string()
+                    .describe(`Required. The id of the site this call targets. Use list_sites to discover ids; available sites for this connection: ${(options.allowedSites ?? []).map((s) => s.siteId).join(', ') || '(none)'}.`),
+            };
+            schema = { ...(tool.inputSchema ?? {}), ...siteIdField };
+        }
+        register(tool.name, {
+            description: tool.description,
+            ...(schema ? { inputSchema: schema } : {}),
+        }, 
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        async (args) => {
+            const rawArgs = args ?? {};
+            let siteId;
+            if (isMultiSite) {
+                const provided = typeof rawArgs.site_id === 'string' ? rawArgs.site_id.trim() : '';
+                if (!provided) {
+                    return fail(new Error('site_id is required. This connector covers multiple sites; pick one from list_sites.'));
+                }
+                const match = allowedById.get(provided);
+                if (!match) {
+                    return fail(new Error(`site_id "${provided}" is not accessible by this connection. Use list_sites to see allowed ids.`));
+                }
+                if (PERM_RANK[match.permission] < PERM_RANK[effect]) {
+                    return fail(new Error(`Tool "${tool.name}" requires ${effect} permission on site "${provided}"; this connection has ${match.permission}.`));
+                }
+                siteId = provided;
+                // Strip site_id from the args we pass downstream so individual
+                // tool schemas (which don't declare it) don't reject the call.
+                delete rawArgs.site_id;
+            }
+            else {
+                siteId = options.fixedSiteId;
+            }
+            const deps = { client: options.client, siteId };
+            return tool.handler(rawArgs, deps);
+        });
+    }
+    return server;
+}

package/dist/tools/pages.js

@@ -40,14 +40,23 @@ 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 });
         }),
     },
     {

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typeroll/mcp-server",
-  "version": "0.7.5",
+  "version": "0.7.8",
   "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": {
@@ -15,6 +15,12 @@
     "typeroll-mcp": "dist/index.js"
   },
   "main": "./dist/index.js",
+  "exports": {
+    ".": "./dist/index.js",
+    "./server": "./src/server.ts",
+    "./client": "./src/client.ts",
+    "./tools/helpers": "./src/tools/helpers.ts"
+  },
   "files": [
     "dist",
     "AGENTS.md",

package/skills/README.md

@@ -27,13 +27,34 @@ 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/podcast section" | Collection schema with `item_template_html` + `route_template` → seed items → listing page with marker block → deploy. **No per-article `create_page` needed** — items materialise their own URLs. |
+| `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-collection-template.md` | Rich per-item detail pages: audio players, chapter lists, guest cards, image galleries — anything needing loops/nested data | Pre-render HTML into `*_html` fields when Mustache's `{{field}}` / `{{#field}}` aren't enough. Concrete recipes per pattern. |
+| `tr-page-template.md`     | Several pages share structure (category landings, service-detail variants) | Partials + `<x-include>` for HTML mode; formal `PageTemplate` via `set_page_template` for block mode. Refactor existing duplication. |
+| `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-migrate-astro.md`  | "migrate an Astro site", "import from src/content"       | Lifts Astro Content Collections (`src/content/*`) into Typeroll collections — zod schema → field list, frontmatter → field values, markdown body → richtext field. Translates standalone `src/pages/*` into Typeroll pages, maps `src/layouts` chunks into partials. |
+| `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