@typeroll/mcp-server 0.7.5 → 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

@@ -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.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": {

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.

package/skills/tr-brand.md

@@ -0,0 +1,169 @@
+---
+name: tr-brand
+description: Use when the user asks to create a brand identity, design system, or visual style for a site. Triggers on "create a brand", "design the look", "choose colors", "pick fonts", "make it look like [reference]", or "rebrand the site". Produces a cohesive palette, typography scale, and CSS custom properties applied to an existing site.
+---
+
+# Design a brand identity for a Typeroll site
+
+This skill turns a brief (or a reference URL/screenshot) into a complete
+visual design system applied to the site's settings and partials.
+
+## Preconditions
+
+- Site exists and MCP is configured.
+- You have at least one of: industry, mood words, reference URL, existing
+  logo colors, or competitor sites to contrast with.
+
+## Step 1 — Gather context
+
+Ask (or infer from the brief):
+
+1. **Industry + audience.** Law firm → formal, trust. Café → warm, approachable.
+   Tech startup → clean, modern. Interior design → refined, editorial.
+2. **Mood words.** 3–5 adjectives the brand should feel: "minimal, Nordic,
+   calm" or "bold, energetic, playful".
+3. **Reference.** A URL, a screenshot, or a competitor they like (and what
+   they want to be different from it).
+4. **Must-keep.** Existing logo color? Legal industry color conventions?
+
+If the user provided a URL, fetch it and note the dominant colors,
+typeface categories, and layout density.
+
+## Step 2 — Build the palette
+
+A Typeroll site uses 7 color tokens:
+
+| Token | Role | Design rule |
+|---|---|---|
+| `primary` | Brand identity. CTA buttons, active nav, links. | High contrast on `background`. |
+| `secondary` | Header, footer, darker sections. | Darker or more neutral than primary. |
+| `accent` | Highlights, price tags, badges, hover states. | High-energy complement. |
+| `background` | Page background. | Near-white for light themes, near-black for dark. |
+| `surface` | Cards, input boxes, code blocks. | Slightly off from `background`. |
+| `text` | Body copy. | ≥4.5:1 contrast ratio on `background`. |
+| `text_light` | Secondary labels, captions, placeholders. | ≥3:1 on `background`. |
+
+**Palette recipes by mood:**
+
+*Nordic / minimal:*
+```
+primary: #1f2a30   secondary: #142027   accent: #c9b89a
+background: #faf8f4  surface: #f2ede5  text: #1f2a30  text_light: #7a7265
+```
+
+*Warm / artisan:*
+```
+primary: #3d2b1f   secondary: #2a1d14   accent: #c8860a
+background: #fdf6ee  surface: #f7ede0  text: #1a1008  text_light: #8a7060
+```
+
+*Modern / tech:*
+```
+primary: #2563eb   secondary: #1e293b   accent: #f59e0b
+background: #ffffff  surface: #f8fafc  text: #0f172a  text_light: #64748b
+```
+
+*Editorial / dark:*
+```
+primary: #e2c08d   secondary: #0f0f0f   accent: #e2c08d
+background: #0f0f0f  surface: #1a1a1a  text: #f5f5f0  text_light: #a0a090
+```
+
+Check WCAG contrast ratios mentally: text on background must be ≥4.5:1.
+The online tool `https://webaim.org/resources/contrastchecker/` is useful
+but not accessible during a tool call — reason about perceived contrast
+instead (light grey on white = bad; dark grey on white = fine).
+
+## Step 3 — Choose typefaces
+
+Pick from high-quality Google Fonts pairings:
+
+| Heading | Body | Mood |
+|---|---|---|
+| Cormorant Garamond | Raleway | Luxury, editorial |
+| Playfair Display | Source Sans 3 | Classic, readable |
+| DM Serif Display | DM Sans | Contemporary, clean |
+| Fraunces | Mulish | Artisan, craft |
+| Syne | Inter | Bold, modern |
+| Plus Jakarta Sans | Plus Jakarta Sans | Clean, versatile |
+| Libre Baskerville | Libre Franklin | Traditional, trustworthy |
+
+Same font for heading and body is fine if it has enough weight variation
+(Inter at 700 + 400 works well).
+
+`size_base` should be 16 for most sites; 17–18 for text-heavy editorial
+sites; 15 for dense dashboards.
+
+## Step 4 — Apply to the site
+
+One call sets everything:
+
+```
+update_site_settings {
+  "colors": { ...all 7 tokens },
+  "fonts":  { "heading": "...", "body": "...", "size_base": 16 },
+  "custom_css": "/* optional: utility classes or @keyframes */"
+}
+```
+
+Read back to confirm: `read_site_settings`.
+
+## Step 5 — Update partials to use the new palette
+
+Partials that hardcoded hex colors need updating. Fetch the header:
+
+```
+read_partial partial_id="header"
+```
+
+If it has hardcoded colors, replace them with CSS variable references
+(`var(--color-primary)`) and call `replace_partial`:
+
+```
+replace_partial partial_id="header" html_content="<updated HTML>"
+```
+
+Same for footer.
+
+## Step 6 — Custom CSS for advanced tokens (optional)
+
+If the brand needs things beyond the 7 base tokens — e.g. a gradient,
+a special border radius, or a branded highlight color — add them via
+`custom_css`:
+
+```css
+:root {
+  --brand-gradient: linear-gradient(135deg, var(--color-primary), var(--color-accent));
+  --radius-brand: 2px;                    /* sharp corners for formal brands */
+  --letter-spacing-display: -0.03em;     /* tight tracking for display headings */
+}
+```
+
+Then reference `var(--brand-gradient)` etc. in page HTML and partials.
+
+## Step 7 — Preview
+
+```
+get_preview_link
+```
+
+Open in browser. Check:
+- Colors render as intended (not "undefined" or missing)
+- Fonts load (Google Fonts link is in `<head>`)
+- Nav text is readable against header background
+- Body text has sufficient contrast
+
+## Pitfalls
+
+- **Don't set colors without checking the header contrast.** If `primary`
+  is light, white nav text becomes unreadable. Either darken `primary` or
+  make the header use `secondary`.
+- **Custom_css is global.** Rules here apply to every page. Keep it to
+  `:root {}` token additions and truly global utilities. Page-specific
+  styles go in the page's HTML `<style>` block.
+- **Google Fonts load time.** Two different font families is fine; three
+  adds measurable LCP impact. Stick to two families with variable-font
+  versions when possible.
+- **Dark themes need dark surface too.** Setting `background: #0f0f0f`
+  but leaving `surface: #f8fafc` (white) breaks every card/input. Always
+  update all 7 tokens as a set.