openalmanac 0.2.57 → 0.2.59

package/dist/setup.js

@@ -2,6 +2,7 @@ import { readFileSync, writeFileSync, mkdirSync, existsSync, cpSync } from "fs";
 import { homedir } from "os";
 import { join, dirname } from "path";
 import { fileURLToPath } from "url";
+import { spawnSync } from "child_process";
 import { performLogin } from "./login-core.js";
 import { getAuthStatus } from "./auth.js";
 const TOOL_GROUPS = [
@@ -131,9 +132,12 @@ const vis = (s) => s.replace(/\x1b\[[0-9;]*m/g, "").length;
 const w = (s) => process.stdout.write(s + "\n");
 /* ── File helpers ───────────────────────────────────────────────── */
 const CLAUDE_DIR = join(homedir(), ".claude");
-const CLAUDE_JSON = join(homedir(), ".claude.json"); // Claude Desktop
-const CLAUDE_CODE_MCP = join(CLAUDE_DIR, "mcp.json"); // Claude Code
+const CLAUDE_JSON = join(homedir(), ".claude.json"); // Claude Code user-scoped MCP config
+const CLAUDE_CODE_MCP = join(CLAUDE_DIR, "mcp.json"); // Claude Code local MCP config
 const SETTINGS_JSON = join(CLAUDE_DIR, "settings.json");
+const CODEX_CONFIG = join(homedir(), ".codex", "config.toml");
+const CURSOR_MCP_JSON = join(homedir(), ".cursor", "mcp.json");
+const WINDSURF_MCP_JSON = join(homedir(), ".codeium", "mcp_config.json");
 function ensureDir(dir) {
     if (!existsSync(dir))
         mkdirSync(dir, { recursive: true });
@@ -151,34 +155,379 @@ function writeJson(path, data) {
 }
 /* ── Step 1 — MCP server ───────────────────────────────────────── */
 const ALMANAC_MCP_ENTRY = { command: "npx", args: ["-y", "openalmanac@latest"] };
+const SUPPORTED_CLIENT_IDS = [
+    "claude-code",
+    "claude-desktop",
+    "codex",
+    "cursor",
+    "windsurf",
+];
+const SUPPORTED_CLIENTS = {
+    "claude-code": {
+        id: "claude-code",
+        name: "Claude Code",
+        detect: () => hasCommand("claude") || existsSync(CLAUDE_JSON) || existsSync(CLAUDE_DIR),
+        configure: (mode) => {
+            const snippets = [
+                {
+                    path: CLAUDE_JSON,
+                    content: jsonSnippet({
+                        mcpServers: {
+                            almanac: { ...ALMANAC_MCP_ENTRY },
+                        },
+                    }),
+                },
+                {
+                    path: CLAUDE_CODE_MCP,
+                    content: jsonSnippet({
+                        mcpServers: {
+                            almanac: { ...ALMANAC_MCP_ENTRY },
+                        },
+                    }),
+                },
+            ];
+            const changedPrimary = configureJsonMcpFile(CLAUDE_JSON, mode);
+            const changedSecondary = configureJsonMcpFile(CLAUDE_CODE_MCP, mode);
+            return { changed: changedPrimary || changedSecondary, snippets };
+        },
+        supportsPermissions: true,
+    },
+    "claude-desktop": {
+        id: "claude-desktop",
+        name: "Claude Desktop",
+        detect: () => {
+            const path = getClaudeDesktopConfigPath();
+            return Boolean(path && (existsSync(path) || isClaudeDesktopInstalled()));
+        },
+        configure: (mode) => {
+            const path = getClaudeDesktopConfigPath();
+            if (!path)
+                return { changed: false, snippets: [] };
+            return {
+                changed: configureJsonMcpFile(path, mode),
+                snippets: [
+                    {
+                        path,
+                        content: jsonSnippet({
+                            mcpServers: {
+                                almanac: { ...ALMANAC_MCP_ENTRY },
+                            },
+                        }),
+                    },
+                ],
+            };
+        },
+    },
+    codex: {
+        id: "codex",
+        name: "Codex",
+        detect: () => hasCommand("codex") || existsSync(CODEX_CONFIG) || existsSync(join(homedir(), ".codex")),
+        configure: (mode) => ({
+            changed: configureCodexToml(CODEX_CONFIG, mode),
+            snippets: [
+                {
+                    path: CODEX_CONFIG,
+                    content: codexSnippet(),
+                },
+            ],
+        }),
+    },
+    cursor: {
+        id: "cursor",
+        name: "Cursor",
+        detect: () => hasCommand("cursor-agent") ||
+            existsSync(CURSOR_MCP_JSON) ||
+            existsSync(join(homedir(), ".cursor")),
+        configure: (mode) => ({
+            changed: configureJsonMcpFile(CURSOR_MCP_JSON, mode),
+            snippets: [
+                {
+                    path: CURSOR_MCP_JSON,
+                    content: jsonSnippet({
+                        mcpServers: {
+                            almanac: { ...ALMANAC_MCP_ENTRY },
+                        },
+                    }),
+                },
+            ],
+        }),
+    },
+    windsurf: {
+        id: "windsurf",
+        name: "Windsurf",
+        detect: () => hasCommand("windsurf") ||
+            existsSync(WINDSURF_MCP_JSON) ||
+            existsSync(join(homedir(), ".codeium")),
+        configure: (mode) => ({
+            changed: configureJsonMcpFile(WINDSURF_MCP_JSON, mode),
+            snippets: [
+                {
+                    path: WINDSURF_MCP_JSON,
+                    content: jsonSnippet({
+                        mcpServers: {
+                            almanac: { ...ALMANAC_MCP_ENTRY },
+                        },
+                    }),
+                },
+            ],
+        }),
+    },
+};
+function parseSetupArgs(argv) {
+    const options = {
+        all: false,
+        clients: [],
+        dryRun: false,
+        print: false,
+        yes: false,
+    };
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg === "--all") {
+            options.all = true;
+            continue;
+        }
+        if (arg === "--print") {
+            options.print = true;
+            continue;
+        }
+        if (arg === "--dry-run") {
+            options.dryRun = true;
+            continue;
+        }
+        if (arg === "--yes" || arg === "-y") {
+            options.yes = true;
+            continue;
+        }
+        if (arg === "--client") {
+            const value = argv[i + 1];
+            if (!value) {
+                throw new Error("Missing value for --client");
+            }
+            i++;
+            options.clients.push(...parseClientList(value));
+            continue;
+        }
+        if (arg.startsWith("--client=")) {
+            options.clients.push(...parseClientList(arg.slice("--client=".length)));
+            continue;
+        }
+        throw new Error(`Unknown setup flag: ${arg}`);
+    }
+    if (options.all && options.clients.length > 0) {
+        throw new Error("Use either --all or --client, not both");
+    }
+    options.clients = Array.from(new Set(options.clients));
+    return options;
+}
+function parseClientList(value) {
+    return value
+        .split(",")
+        .map((part) => part.trim().toLowerCase())
+        .filter(Boolean)
+        .map((part) => normalizeClientId(part));
+}
+function normalizeClientId(value) {
+    const aliases = {
+        claude: "claude-code",
+        "claude-code": "claude-code",
+        "claude-desktop": "claude-desktop",
+        desktop: "claude-desktop",
+        codex: "codex",
+        cursor: "cursor",
+        windsurf: "windsurf",
+    };
+    const normalized = aliases[value];
+    if (!normalized) {
+        throw new Error(`Unsupported client "${value}". Supported clients: ${SUPPORTED_CLIENT_IDS.join(", ")}`);
+    }
+    return normalized;
+}
+function hasCommand(command) {
+    const checker = process.platform === "win32" ? "where" : "which";
+    const result = spawnSync(checker, [command], { stdio: "ignore" });
+    return result.status === 0;
+}
+function getClaudeDesktopConfigPath() {
+    if (process.platform === "darwin") {
+        return join(homedir(), "Library", "Application Support", "Claude", "claude_desktop_config.json");
+    }
+    if (process.platform === "linux") {
+        return join(homedir(), ".config", "Claude", "claude_desktop_config.json");
+    }
+    if (process.platform === "win32") {
+        const appData = process.env.APPDATA;
+        if (!appData)
+            return null;
+        return join(appData, "Claude", "claude_desktop_config.json");
+    }
+    return null;
+}
+function isClaudeDesktopInstalled() {
+    if (process.platform === "darwin") {
+        return (existsSync("/Applications/Claude.app") ||
+            existsSync(join(homedir(), "Applications", "Claude.app")));
+    }
+    if (process.platform === "linux") {
+        return (existsSync("/usr/share/applications/claude.desktop") ||
+            existsSync(join(homedir(), ".local", "share", "applications", "claude.desktop")) ||
+            existsSync("/opt/Claude/claude"));
+    }
+    if (process.platform === "win32") {
+        const localAppData = process.env.LOCALAPPDATA;
+        const programFiles = process.env.ProgramFiles;
+        return Boolean((localAppData &&
+            existsSync(join(localAppData, "Programs", "Claude", "Claude.exe"))) ||
+            (programFiles && existsSync(join(programFiles, "Claude", "Claude.exe"))));
+    }
+    return false;
+}
+function jsonSnippet(data) {
+    return JSON.stringify(data, null, 2);
+}
+function codexSnippet() {
+    return [
+        "[mcp_servers.almanac]",
+        `command = ${tomlString(ALMANAC_MCP_ENTRY.command)}`,
+        `args = ${tomlArray(ALMANAC_MCP_ENTRY.args)}`,
+    ].join("\n");
+}
 function isAlmanacCurrent(server) {
     return (server?.command === "npx" &&
         JSON.stringify(server.args) === JSON.stringify(ALMANAC_MCP_ENTRY.args));
 }
-function configureMcp() {
-    let changed = false;
-    // Claude Desktop — ~/.claude.json
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    const desktop = readJson(CLAUDE_JSON);
-    if (!desktop.mcpServers)
-        desktop.mcpServers = {};
-    if (!isAlmanacCurrent(desktop.mcpServers.almanac)) {
-        desktop.mcpServers.almanac = { ...ALMANAC_MCP_ENTRY };
-        writeJson(CLAUDE_JSON, desktop);
-        changed = true;
-    }
-    // Claude Code — ~/.claude/mcp.json
-    ensureDir(CLAUDE_DIR);
+function configureJsonMcpFile(path, mode) {
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    const code = readJson(CLAUDE_CODE_MCP);
-    if (!code.mcpServers)
-        code.mcpServers = {};
-    if (!isAlmanacCurrent(code.mcpServers.almanac)) {
-        code.mcpServers.almanac = { ...ALMANAC_MCP_ENTRY };
-        writeJson(CLAUDE_CODE_MCP, code);
-        changed = true;
+    const json = readJson(path);
+    if (!json.mcpServers)
+        json.mcpServers = {};
+    if (isAlmanacCurrent(json.mcpServers.almanac)) {
+        return false;
     }
-    return changed;
+    if (mode === "apply") {
+        ensureDir(dirname(path));
+        json.mcpServers.almanac = { ...ALMANAC_MCP_ENTRY };
+        writeJson(path, json);
+    }
+    return true;
+}
+function configureCodexToml(path, mode) {
+    const current = readToml(path);
+    const next = upsertCodexServer(current);
+    if (current.trim() === next.trim()) {
+        return false;
+    }
+    if (mode === "apply") {
+        ensureDir(dirname(path));
+        writeFileSync(path, next.endsWith("\n") ? next : next + "\n");
+    }
+    return true;
+}
+function readToml(path) {
+    try {
+        return readFileSync(path, "utf-8");
+    }
+    catch {
+        return "";
+    }
+}
+function upsertCodexServer(content) {
+    const sectionName = "mcp_servers.almanac";
+    const header = `[${sectionName}]`;
+    const nextBody = [
+        `command = ${tomlString(ALMANAC_MCP_ENTRY.command)}`,
+        `args = ${tomlArray(ALMANAC_MCP_ENTRY.args)}`,
+    ];
+    const lines = content === "" ? [] : content.split(/\r?\n/);
+    const start = lines.findIndex((line) => line.trim() === header);
+    if (start === -1) {
+        const prefix = content.trimEnd();
+        const block = [header, ...nextBody].join("\n");
+        return prefix === "" ? block + "\n" : `${prefix}\n\n${block}\n`;
+    }
+    let end = lines.length;
+    for (let i = start + 1; i < lines.length; i++) {
+        if (/^\s*\[.+\]\s*$/.test(lines[i])) {
+            end = i;
+            break;
+        }
+    }
+    const existingBody = lines.slice(start + 1, end);
+    const preserved = existingBody.filter((line) => {
+        const trimmed = line.trim();
+        return !trimmed.startsWith("command =") && !trimmed.startsWith("args =");
+    });
+    const replacement = [header, ...nextBody, ...preserved];
+    const updated = [...lines.slice(0, start), ...replacement, ...lines.slice(end)];
+    return updated.join("\n").replace(/\n{3,}/g, "\n\n").replace(/\s+$/, "") + "\n";
+}
+function tomlString(value) {
+    return JSON.stringify(value);
+}
+function tomlArray(values) {
+    return `[${values.map((value) => tomlString(value)).join(", ")}]`;
+}
+function detectClients() {
+    return SUPPORTED_CLIENT_IDS.map((id) => SUPPORTED_CLIENTS[id]).filter((client) => client.detect());
+}
+function resolveClients(options) {
+    if (options.clients.length > 0) {
+        return options.clients.map((id) => SUPPORTED_CLIENTS[id]);
+    }
+    const detected = detectClients();
+    if (options.all)
+        return detected;
+    return detected;
+}
+function applyClientSetup(clients, mode) {
+    const configured = [];
+    const alreadyConfigured = [];
+    for (const client of clients) {
+        const result = client.configure(mode);
+        if (result.changed) {
+            configured.push(client.name);
+        }
+        else {
+            alreadyConfigured.push(client.name);
+        }
+    }
+    return { configured, alreadyConfigured };
+}
+function printSetupPlan(clients, options) {
+    const heading = options.dryRun ? "Dry run" : "OpenAlmanac MCP setup";
+    process.stdout.write(`${heading}\n\n`);
+    if (clients.length === 0) {
+        process.stdout.write("No supported clients detected. Use --client <name> to force a target or --print to inspect supported snippets.\n");
+        if (options.print) {
+            process.stdout.write("\nSupported clients:\n");
+            for (const id of SUPPORTED_CLIENT_IDS) {
+                process.stdout.write(`- ${SUPPORTED_CLIENTS[id].name}\n`);
+            }
+        }
+        return;
+    }
+    const mode = options.print ? "print" : "dry-run";
+    for (const client of clients) {
+        const result = client.configure(mode);
+        const status = result.changed
+            ? options.print
+                ? "snippet"
+                : "would configure"
+            : "already configured";
+        process.stdout.write(`- ${client.name}: ${status}\n`);
+        if (options.print) {
+            for (const snippet of result.snippets) {
+                process.stdout.write(`  Path: ${snippet.path}\n`);
+                process.stdout.write(`${indentBlock(snippet.content, "    ")}\n`);
+            }
+        }
+    }
+}
+function indentBlock(content, prefix) {
+    return content
+        .split("\n")
+        .map((line) => `${prefix}${line}`)
+        .join("\n");
 }
 /* ── Step 2 — Permissions ──────────────────────────────────────── */
 function configurePermissions(tools) {
@@ -278,12 +627,15 @@ function waitForKey(prompt) {
     });
 }
 async function runLoginStep(agent, mcpChanged, toolCount, mode = "default") {
+    const label = agent.includes(",") ? "Clients" : "Agent";
     const priorSteps = () => {
-        stepDone(`Agent \u2192 ${WHITE_BOLD}${agent}${RST}`);
+        stepDone(`${label} \u2192 ${WHITE_BOLD}${agent}${RST}`);
         w(BAR);
         stepDone(`MCP server ${mcpChanged ? "configured" : `${DIM}already configured${RST}`}`);
-        w(BAR);
-        stepDone(`${BLUE}${toolCount}${RST} tool${toolCount !== 1 ? "s" : ""} allowed`);
+        if (toolCount !== null) {
+            w(BAR);
+            stepDone(`${BLUE}${toolCount}${RST} tool${toolCount !== 1 ? "s" : ""} allowed`);
+        }
         w(BAR);
     };
     function renderLoginChoice(name, cursor) {
@@ -497,17 +849,21 @@ function runToolSelect(agent, mcpChanged, mode = "default") {
     });
 }
 /* ── Result screen ──────────────────────────────────────────────── */
-function printResult(agent, loginResult, mcpChanged, toolCount) {
+function printResult(clientsLabel, loginResult, configured, alreadyConfigured, toolCount) {
     process.stdout.write("\x1b[2J\x1b[H");
     printBanner();
     printBadge();
     w("");
-    stepDone(`Agent \u2192 ${WHITE_BOLD}${agent}${RST}`);
+    stepDone(`Clients \u2192 ${WHITE_BOLD}${clientsLabel}${RST}`);
     w(BAR);
-    stepDone(`MCP server ${mcpChanged ? "configured" : `${DIM}already configured${RST}`}`);
+    stepDone(`Configured \u2192 ${configured.length > 0 ? configured.join(", ") : `${DIM}none${RST}`}`);
     w(BAR);
-    stepDone(`${BLUE}${toolCount}${RST} tool${toolCount !== 1 ? "s" : ""} allowed in ${DIM}~/.claude/settings.json${RST}`);
+    stepDone(`Already configured \u2192 ${alreadyConfigured.length > 0 ? alreadyConfigured.join(", ") : `${DIM}none${RST}`}`);
     w(BAR);
+    if (toolCount > 0) {
+        stepDone(`${BLUE}${toolCount}${RST} tool${toolCount !== 1 ? "s" : ""} allowed in ${DIM}~/.claude/settings.json${RST}`);
+        w(BAR);
+    }
     stepDone(loginLabel(loginResult));
     w(BAR);
     stepDone(`${BLUE}Setup complete${RST}`);
@@ -519,37 +875,86 @@ function printResult(agent, loginResult, mcpChanged, toolCount) {
         return `  ${BLUE_DIM}\u2502${RST}${content}${" ".repeat(padding)}${BLUE_DIM}\u2502${RST}`;
     };
     const empty = row("");
+    const nextSteps = getNextSteps(clientsLabel);
     w(`  ${BLUE_DIM}\u256d${"─".repeat(innerW)}\u256e${RST}`);
     w(empty);
     w(row(`  ${WHITE_BOLD}Next steps${RST}`));
     w(empty);
-    w(row(`  ${BLUE}1.${RST}  Type ${WHITE_BOLD}claude${RST} to start Claude Code`));
-    w(row(`  ${BLUE}2.${RST}  Say ${BLUE}"Let's explore <topic> using Almanac"${RST}`));
+    for (let i = 0; i < nextSteps.length; i++) {
+        w(row(`  ${BLUE}${i + 1}.${RST}  ${nextSteps[i]}`));
+    }
     w(empty);
     w(`  ${BLUE_DIM}\u2570${"─".repeat(innerW)}\u256f${RST}`);
     w("");
 }
+function getNextSteps(clientsLabel) {
+    if (clientsLabel === "Claude Code") {
+        return [
+            `Type ${WHITE_BOLD}claude${RST} to start Claude Code`,
+            `Say ${BLUE}"Let's explore <topic> using Almanac"${RST}`,
+        ];
+    }
+    if (clientsLabel === "Codex") {
+        return [
+            `Type ${WHITE_BOLD}codex${RST} to start Codex`,
+            `Ask ${BLUE}"Let's explore <topic> using Almanac"${RST}`,
+        ];
+    }
+    if (clientsLabel === "Cursor") {
+        return [
+            `Open ${WHITE_BOLD}Cursor${RST} in your project`,
+            `Ask ${BLUE}"Let's explore <topic> using Almanac"${RST}`,
+        ];
+    }
+    if (clientsLabel === "Windsurf") {
+        return [
+            `Open ${WHITE_BOLD}Windsurf${RST} in your project`,
+            `Ask ${BLUE}"Let's explore <topic> using Almanac"${RST}`,
+        ];
+    }
+    if (clientsLabel === "Claude Desktop") {
+        return [
+            `Open ${WHITE_BOLD}Claude Desktop${RST}`,
+            `Ask ${BLUE}"Let's explore <topic> using Almanac"${RST}`,
+        ];
+    }
+    return [
+        `Open one of your configured agents in this project`,
+        `Ask ${BLUE}"Let's explore <topic> using Almanac"${RST}`,
+    ];
+}
 /* ── Entry point ────────────────────────────────────────────────── */
 export async function runSetup() {
-    const skipTui = process.argv.includes("--yes") || process.argv.includes("-y");
-    const interactive = process.stdin.isTTY && !skipTui;
-    let agent = "Claude Code";
-    if (interactive) {
-        agent = await runAgentSelect();
+    const options = parseSetupArgs(process.argv.slice(3));
+    const clients = resolveClients(options);
+    if (options.print || options.dryRun) {
+        printSetupPlan(clients, options);
+        process.exit(0);
     }
-    const mcpChanged = configureMcp();
-    let tools;
-    if (interactive) {
-        tools = await runToolSelect(agent, mcpChanged);
+    if (clients.length === 0) {
+        printSetupPlan(clients, options);
+        process.exit(0);
     }
-    else {
-        tools = TOOL_GROUPS.flatMap((g) => g.tools);
+    const skipTui = options.yes;
+    const interactive = process.stdin.isTTY && !skipTui;
+    const setupSummary = applyClientSetup(clients, "apply");
+    const permissionClient = clients.find((client) => client.supportsPermissions);
+    let tools = [];
+    if (permissionClient) {
+        const mcpChanged = setupSummary.configured.includes(permissionClient.name);
+        if (interactive) {
+            tools = await runToolSelect(permissionClient.name, mcpChanged);
+        }
+        else {
+            tools = TOOL_GROUPS.flatMap((g) => g.tools);
+        }
     }
-    const count = configurePermissions(tools);
-    // Login step (last — so when they return from browser, everything is done)
+    const count = tools.length > 0 ? configurePermissions(tools) : 0;
+    const permissionCount = permissionClient ? count : null;
     let loginResult;
+    const clientsLabel = clients.map((client) => client.name).join(", ");
     if (interactive) {
-        loginResult = await runLoginStep(agent, mcpChanged, count);
+        loginResult = await runLoginStep(clientsLabel, setupSummary.configured.length > 0, permissionCount);
     }
     else {
         try {
@@ -563,7 +968,7 @@ export async function runSetup() {
             loginResult = { status: "skipped" };
         }
     }
-    printResult(agent, loginResult, mcpChanged, count);
+    printResult(clientsLabel, loginResult, setupSummary.configured, setupSummary.alreadyConfigured, count);
     process.exit(0);
 }
 /* ── Skill installation ────────────────────────────────────────── */
@@ -629,7 +1034,8 @@ export async function runRedditSetup() {
     if (interactive) {
         agent = await runAgentSelect("reddit");
     }
-    const mcpChanged = configureMcp();
+    const claudeSetup = SUPPORTED_CLIENTS["claude-code"].configure("apply");
+    const mcpChanged = claudeSetup.changed;
     let tools;
     if (interactive) {
         tools = await runToolSelect(agent, mcpChanged, "reddit");

package/dist/tools/articles.d.ts

@@ -0,0 +1,2 @@
+import { FastMCP } from "fastmcp";
+export declare function registerArticleTools(server: FastMCP): void;

package/dist/tools/articles.js

@@ -0,0 +1,401 @@
+import { z } from "zod";
+import { readFileSync, writeFileSync, mkdirSync, readdirSync, statSync, existsSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { stringify as yamlStringify } from "yaml";
+import { request, ARTICLES_DIR, getAuthStatus } from "../auth.js";
+import { validateArticle, parseFrontmatter } from "../validate.js";
+import { openBrowser } from "../browser.js";
+const SLUG_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+const WRITING_GUIDE = `
+## Article structure
+
+\`\`\`yaml
+---
+article_id: the-slug
+title: Article Title
+sources:
+  - key: example-source-title
+    url: https://example.com
+    title: Source Title
+    accessed_date: "2025-01-15"
+infobox:
+  header:
+    image_url: https://...         # optional hero image
+    subtitle: Short tagline
+    details:
+      - key: Born
+        value: January 1, 1990
+      - key: Occupation
+        value: Scientist
+    links:
+      - https://example.com
+  sections:
+    - type: timeline               # chronological events
+      title: Career Timeline
+      items:
+        - primary: "Started company"
+          period: "2010"
+          location: "San Francisco"
+    - type: list                   # key figures, works, features
+      title: Known For
+      items:
+        - title: First achievement
+        - title: Second achievement
+          subtitle: Additional detail
+    - type: tags                   # inline tags/chips
+      title: Genres
+      items:
+        - Rock
+        - Jazz
+    - type: grid                   # image grid
+      title: Gallery
+      items:
+        - title: Caption
+          image_url: https://...
+    - type: table                  # structured comparison
+      title: Statistics
+      items:
+        headers:
+          - Name
+          - Value
+        rows:
+          - cells:
+              - Height
+              - "6'2\\""
+    - type: key_value              # simple key-value pairs
+      title: Quick Facts
+      items:
+        - key: Population
+          value: "1.4 billion"
+---
+
+Article body with [@key] citation markers...
+\`\`\`
+
+## Infobox
+
+Include an infobox for any article about a person, place, organization, event, or concept. Pick the section types that fit — you don't need all six.
+
+## Citations
+
+- Mark claims with [@key] after punctuation: "The population is 1.4 billion.[@who-world-population]"
+- Keys must be kebab-case with at least one hyphen (e.g. 'nytimes-climate-report', 'who-malaria-2024')
+- Generate keys BibTeX-style: {domain}-{title-words} (e.g. 'arxiv-attention-is-all')
+- Every source in the sources list must be referenced at least once in the body with [@key]
+- Every [@key] marker must have a matching source with that key
+- Display numbers are computed automatically from first-appearance order — just use the keys
+
+## Images
+
+Use search_images to find relevant images. Images render as figures with visible captions.
+
+**Syntax:** \`![Caption text](url "position")\`
+
+Positions: \`"right"\` (default if omitted), \`"left"\`, \`"center"\`
+
+\`\`\`markdown
+![Alan Turing in 1930, aged 18](https://upload.wikimedia.org/...)
+
+The early life of Alan Turing began...
+
+![Panoramic view of Bletchley Park](https://upload.wikimedia.org/... "center")
+\`\`\`
+
+**Caption rules:**
+- Every image MUST have a descriptive caption — it is displayed below the image
+- Describe what the image shows: "Alan Turing in 1930, aged 18" not "Photo"
+- Include dates, context, or attribution when relevant
+
+**Placement:** 1-3 images per major section, spread throughout. First image near the top.
+For the infobox hero image, use \`infobox.header.image_url\` in frontmatter instead.
+
+External image URLs are auto-persisted on publish — no extra steps needed.
+
+## Writing quality
+
+- Every sentence should contain a specific fact the reader didn't know
+- No filler phrases ("It is worth noting", "In today's world", "Throughout history")
+- No promotional language ("revolutionary", "groundbreaking", "game-changing")
+- No inflated significance ("one of the most important", "changed the world forever")
+- No vague attribution ("many experts say", "it is widely regarded")
+- No formulaic conclusions ("In conclusion", "continues to shape")
+- Write like a concise encyclopedia, not a blog post
+`.trim();
+function ensureArticlesDir() {
+    mkdirSync(ARTICLES_DIR, { recursive: true });
+}
+export function registerArticleTools(server) {
+    server.addTool({
+        name: "search_articles",
+        description: "Search existing OpenAlmanac articles and stubs. Accepts multiple queries for batch lookup. " +
+            "Use this to check if articles or stubs exist before creating them, or to find entity slugs for wikilinks. " +
+            "Results include 'stub' field (true/false) and 'entity_type' field. No authentication needed.",
+        parameters: z.object({
+            queries: z.array(z.string()).min(1).max(20).describe("Search queries (1-20)"),
+            limit: z.number().default(5).describe("Max results per query (1-50, default 5)"),
+            include_stubs: z.boolean().default(true).describe("Include stub articles in results (default true)"),
+        }),
+        async execute({ queries, limit, include_stubs }) {
+            const resp = await request("POST", "/api/search/batch", {
+                json: { queries, limit, include_stubs },
+            });
+            return JSON.stringify(await resp.json(), null, 2);
+        },
+    });
+    server.addTool({
+        name: "read",
+        description: "Read article content from OpenAlmanac. Returns the content, sources, and metadata for each slug. " +
+            "Use this to reference or summarize existing articles in conversation. " +
+            "For editing articles locally, use 'download' instead. No authentication needed.",
+        parameters: z.object({
+            slugs: z.array(z.string()).min(1).max(20).describe("Article slugs to read (1-20)"),
+        }),
+        async execute({ slugs }) {
+            const resp = await request("POST", "/api/articles/batch", {
+                json: { slugs },
+            });
+            return JSON.stringify(await resp.json(), null, 2);
+        },
+    });
+    server.addTool({
+        name: "create_stubs",
+        description: "Create stub articles — placeholders for entities that don't have full articles yet. " +
+            "Use this for every entity (person, organization, topic, etc.) mentioned in an article. " +
+            "Idempotent: existing slugs return their current status. Requires login.",
+        parameters: z.object({
+            stubs: z.array(z.object({
+                slug: z
+                    .string()
+                    .min(1)
+                    .max(500)
+                    .describe("Unique kebab-case identifier. For people with LinkedIn: use their vanity ID (e.g. 'john-smith-4a8b2c1'). " +
+                    "For others: descriptive kebab-case (e.g. 'reinforcement-learning', 'openai')"),
+                title: z.string().describe("Display title (e.g. 'John Smith', 'Reinforcement Learning')"),
+                entity_type: z
+                    .enum(["person", "organization", "topic", "event", "creative_work", "place"])
+                    .optional()
+                    .describe("Entity type: 'person' for individuals, 'organization' for companies/institutions/nonprofits, " +
+                    "'topic' for concepts/fields/technologies, 'event' for conferences/historical events, " +
+                    "'creative_work' for books/papers/films/software, 'place' for cities/countries/landmarks"),
+                headline: z
+                    .string()
+                    .optional()
+                    .describe("Short headline (e.g. 'Professor of CS at MIT', 'AI research laboratory')"),
+                image_url: z.string().url().optional().describe("Image URL for the entity"),
+                summary: z
+                    .string()
+                    .optional()
+                    .describe("2-4 sentence summary of the entity. This becomes the stub page content. " +
+                    "Be informative — include key facts, dates, and context."),
+            })).min(1).max(50).describe("Stubs to create (1-50)"),
+        }),
+        async execute({ stubs }) {
+            const resp = await request("POST", "/api/articles/stubs", {
+                auth: true,
+                json: { stubs },
+            });
+            return JSON.stringify(await resp.json(), null, 2);
+        },
+    });
+    server.addTool({
+        name: "download",
+        description: "Download an article to your local workspace for editing. The file is saved to ~/.openalmanac/articles/{slug}.md " +
+            "with YAML frontmatter. Returns a writing guide covering article structure, infobox format, citations, and quality rules. " +
+            "After editing, use 'publish' to push your changes live.",
+        parameters: z.object({
+            slug: z.string().describe("Article slug (e.g. 'machine-learning')"),
+        }),
+        async execute({ slug }) {
+            if (!SLUG_RE.test(slug)) {
+                throw new Error(`Invalid slug "${slug}". Must be kebab-case (e.g. 'machine-learning').`);
+            }
+            const resp = await request("GET", `/api/articles/${slug}`, {
+                params: { format: "md" },
+            });
+            const markdown = await resp.text();
+            ensureArticlesDir();
+            const filePath = join(ARTICLES_DIR, `${slug}.md`);
+            writeFileSync(filePath, markdown, "utf-8");
+            const originalPath = join(ARTICLES_DIR, `.${slug}.original.md`);
+            writeFileSync(originalPath, markdown, "utf-8");
+            const { frontmatter, content } = parseFrontmatter(markdown);
+            const title = frontmatter.title || "(untitled)";
+            const wordCount = content.trim().split(/\s+/).filter(Boolean).length;
+            const isStub = frontmatter.stub === true;
+            const stubNote = isStub
+                ? "\n\nThis is a STUB article — a placeholder that hasn't been fully written yet. " +
+                    "Fill in the content body with a complete article, then push to publish."
+                : "";
+            return `Downloaded "${title}" to ${filePath}\n${wordCount} words, ${frontmatter.sources?.length ?? 0} sources.${stubNote}\n\n${WRITING_GUIDE}`;
+        },
+    });
+    server.addTool({
+        name: "new",
+        description: "Create a new article scaffold in your local working directory (~/.openalmanac/articles/). " +
+            "The file is created with YAML frontmatter and an empty body. Returns a writing guide covering article structure, infobox format, citations, and quality rules. " +
+            "Edit the file to add content and sources, then use publish to go live.",
+        parameters: z.object({
+            slug: z
+                .string()
+                .describe("Unique kebab-case identifier (e.g. 'machine-learning'). Pattern: ^[a-z0-9]+(-[a-z0-9]+)*$"),
+            title: z.string().describe("Article title"),
+        }),
+        async execute({ slug, title }) {
+            if (!SLUG_RE.test(slug)) {
+                throw new Error(`Invalid slug "${slug}". Must be kebab-case (e.g. 'machine-learning'). Pattern: ^[a-z0-9]+(-[a-z0-9]+)*$`);
+            }
+            ensureArticlesDir();
+            const filePath = join(ARTICLES_DIR, `${slug}.md`);
+            if (existsSync(filePath)) {
+                throw new Error(`File already exists: ${filePath}\nUse download to refresh it, or publish to push changes.`);
+            }
+            const frontmatter = yamlStringify({ article_id: slug, title, sources: [] });
+            const scaffold = `---\n${frontmatter}---\n\n`;
+            writeFileSync(filePath, scaffold, "utf-8");
+            return `Created ${filePath}\n\n${WRITING_GUIDE}`;
+        },
+    });
+    server.addTool({
+        name: "publish",
+        description: "Validate and publish an article from your local workspace. Reads ~/.openalmanac/articles/{slug}.md, " +
+            "validates content and sources, and publishes to OpenAlmanac. Requires login.",
+        parameters: z.object({
+            slug: z.string().describe("Article slug matching the filename (without .md)"),
+            change_title: z.string().optional().describe("Short title for the change (e.g. 'Added early life section')"),
+            change_description: z.string().optional().describe("Longer description of what changed and why"),
+        }),
+        async execute({ slug, change_title, change_description }) {
+            if (!SLUG_RE.test(slug)) {
+                throw new Error(`Invalid slug "${slug}". Must be kebab-case (e.g. 'machine-learning').`);
+            }
+            const filePath = join(ARTICLES_DIR, `${slug}.md`);
+            let raw;
+            try {
+                raw = readFileSync(filePath, "utf-8");
+            }
+            catch {
+                throw new Error(`File not found: ${filePath}\nUse download to get an existing article or new to create a scaffold.`);
+            }
+            // Local validation
+            const errors = validateArticle(raw);
+            if (errors.length > 0) {
+                const lines = errors.map((e) => `  ${e.field}: ${e.message}`);
+                throw new Error(`Validation failed (${errors.length} error${errors.length > 1 ? "s" : ""}):\n${lines.join("\n")}\n\nFix the file and try again.`);
+            }
+            // Inject change_title/change_description into frontmatter if provided
+            let body = raw;
+            if (change_title || change_description) {
+                const { frontmatter, content } = parseFrontmatter(raw);
+                if (change_title)
+                    frontmatter.change_title = change_title;
+                if (change_description)
+                    frontmatter.change_description = change_description;
+                const newFrontmatter = yamlStringify(frontmatter);
+                body = `---\n${newFrontmatter}---\n${content}`;
+            }
+            const resp = await request("PUT", `/api/articles/${slug}`, {
+                auth: true,
+                body,
+                contentType: "text/markdown",
+            });
+            const data = (await resp.json());
+            const articleUrl = `https://www.openalmanac.org/article/${slug}?celebrate=true`;
+            openBrowser(articleUrl);
+            // Clean up local files after successful publish
+            let cleanupWarning = "";
+            try {
+                unlinkSync(filePath);
+            }
+            catch (e) {
+                if (e.code !== "ENOENT") {
+                    cleanupWarning = `\nNote: could not remove local draft: ${e.message}`;
+                }
+            }
+            try {
+                unlinkSync(join(ARTICLES_DIR, `.${slug}.original.md`));
+            }
+            catch (e) {
+                if (e.code !== "ENOENT") {
+                    cleanupWarning += `\nNote: could not remove original copy: ${e.message}`;
+                }
+            }
+            return `Pushed successfully.\n\nArticle URL (share this exact link with the user): ${articleUrl}${cleanupWarning}\n\n${JSON.stringify(data, null, 2)}`;
+        },
+    });
+    server.addTool({
+        name: "requested_articles",
+        description: "List requested articles — stubs that are referenced by the most articles but haven't been fully written yet. " +
+            "Use this to find high-demand topics to write about. No authentication needed.",
+        parameters: z.object({
+            limit: z.number().default(20).describe("Max results (1-200, default 20)"),
+            offset: z.number().default(0).describe("Pagination offset (default 0)"),
+        }),
+        async execute({ limit, offset }) {
+            const resp = await request("GET", "/api/articles/requested", {
+                params: { limit, offset },
+            });
+            return JSON.stringify(await resp.json(), null, 2);
+        },
+    });
+    server.addTool({
+        name: "propose_article",
+        description: "Propose an article before writing it. Call this when you've researched enough and a specific article topic has come into focus. " +
+            "Structures your proposal with a user-facing summary and a detailed brief. " +
+            "The client environment determines what happens next — in GUI environments the user sees a plan card with options, " +
+            "in CLI environments you'll get a response telling you to proceed with writing. " +
+            "Do not start writing an article without proposing first.",
+        parameters: z.object({
+            summary: z.string().describe("User-facing summary: title, key sections, angle. Markdown. Concise — 3-5 bullet points."),
+            details: z.string().describe("Full handoff brief for the background agent. Include: all sources, key facts, user preferences, angle, what to avoid, related articles. Be thorough."),
+            title: z.string().describe("Proposed article title"),
+            slug: z.string().describe("Proposed article slug (kebab-case)"),
+            _userChoice: z.enum(["background", "here", "expired", "already_in_progress"]).optional().describe("Internal field set by GUI client. Never set this manually."),
+        }),
+        async execute({ summary, details, title, slug, _userChoice }) {
+            if (!SLUG_RE.test(slug)) {
+                throw new Error(`Invalid slug "${slug}". Must be kebab-case (e.g. 'machine-learning'). Pattern: ^[a-z0-9]+(-[a-z0-9]+)*$`);
+            }
+            if (_userChoice === "background") {
+                return `Article "${title}" is now being written in a background process. Continue exploring with the user. Do not write this article in this conversation.`;
+            }
+            if (_userChoice === "expired") {
+                return `The user navigated away before responding to the proposal. Proposal expired. Continue the conversation naturally.`;
+            }
+            if (_userChoice === "already_in_progress") {
+                return `Article "${title}" is already being generated in a background process. No action needed.`;
+            }
+            // "here" OR no _userChoice (CLI default) — proceed with writing
+            return `Article Proposal: ${title}\n\n${summary}\n\nProceed with writing this article following the writing flow in your instructions.`;
+        },
+    });
+    server.addTool({
+        name: "status",
+        description: "Show login status and list all article files in your local working directory (~/.openalmanac/articles/). " +
+            "Shows auth state, filename, title, file size, and last modified time.",
+        async execute() {
+            ensureArticlesDir();
+            const auth = await getAuthStatus();
+            const authLine = auth.loggedIn
+                ? `Logged in as ${auth.name}.`
+                : "Not logged in. Use login to authenticate.";
+            const files = readdirSync(ARTICLES_DIR).filter((f) => f.endsWith(".md") && !f.startsWith("."));
+            if (files.length === 0) {
+                return `${authLine}\n\nLocal articles (0 files in ${ARTICLES_DIR}):\n  (none — use download or new to get started)`;
+            }
+            const rows = [];
+            for (const file of files) {
+                const filePath = join(ARTICLES_DIR, file);
+                const stat = statSync(filePath);
+                const raw = readFileSync(filePath, "utf-8");
+                const { frontmatter } = parseFrontmatter(raw);
+                const title = frontmatter.title || "(untitled)";
+                const size = stat.size < 1024
+                    ? `${stat.size}B`
+                    : `${(stat.size / 1024).toFixed(1)}KB`;
+                const modified = stat.mtime.toISOString().slice(0, 16).replace("T", " ");
+                rows.push(`  ${file}  —  "${title}"  (${size}, modified ${modified})`);
+            }
+            return `${authLine}\n\nLocal articles (${files.length} file(s) in ${ARTICLES_DIR}):\n${rows.join("\n")}`;
+        },
+    });
+}

package/dist/tools/communities.d.ts

@@ -0,0 +1,2 @@
+import { FastMCP } from "fastmcp";
+export declare function registerCommunityTools(server: FastMCP): void;

package/dist/tools/communities.js

@@ -0,0 +1,127 @@
+import { z } from "zod";
+import { request } from "../auth.js";
+export function registerCommunityTools(server) {
+    server.addTool({
+        name: "search_communities",
+        description: "Search or list OpenAlmanac communities. Returns community names, descriptions, and member counts. " +
+            "Use this after pushing an article to find relevant communities for auto-linking. No authentication needed.",
+        parameters: z.object({
+            query: z
+                .string()
+                .optional()
+                .describe("Search term (case-insensitive match on name, slug, or description). Omit to list all."),
+            sort: z
+                .enum(["popular", "newest"])
+                .default("popular")
+                .describe("Sort order (default: popular)"),
+            limit: z
+                .number()
+                .min(1)
+                .max(100)
+                .default(20)
+                .describe("Max results (1-100, default 20)"),
+        }),
+        async execute({ query, sort, limit }) {
+            const params = { sort, limit };
+            if (query)
+                params.query = query;
+            const resp = await request("GET", "/api/communities", { params });
+            const data = (await resp.json());
+            const communities = data.communities.map((c) => ({
+                slug: c.slug,
+                name: c.name,
+                description: c.description,
+                member_count: c.member_count,
+                created_at: c.created_at,
+            }));
+            return `Found ${data.total} communities:\n\n${JSON.stringify(communities, null, 2)}`;
+        },
+    });
+    server.addTool({
+        name: "create_community",
+        description: "Create a new OpenAlmanac community. Requires login and at least 1 published article. " +
+            "Communities are spaces where articles can be curated and discussed around a topic.",
+        parameters: z.object({
+            name: z.string().min(1).max(100).describe("Community name (1-100 chars)"),
+            slug: z
+                .string()
+                .min(1)
+                .max(100)
+                .regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/)
+                .describe("Unique kebab-case identifier (e.g. 'machine-learning')"),
+            description: z
+                .string()
+                .min(1)
+                .max(2000)
+                .describe("What the community is about (1-2000 chars)"),
+        }),
+        async execute({ name, slug, description }) {
+            const resp = await request("POST", "/api/communities", {
+                auth: true,
+                json: { name, slug, description },
+            });
+            const data = (await resp.json());
+            const communityUrl = `https://www.openalmanac.org/communities/${slug}`;
+            return `Community created!\n\nURL: ${communityUrl}\n\n${JSON.stringify(data, null, 2)}`;
+        },
+    });
+    server.addTool({
+        name: "create_post",
+        description: "Create a post in an OpenAlmanac community. Requires login and community membership. " +
+            "If you get a 403 error, you need to join the community first.",
+        parameters: z.object({
+            community_slug: z.string().describe("Community slug (e.g. 'machine-learning')"),
+            title: z.string().min(1).max(300).describe("Post title (1-300 chars)"),
+            body: z.string().max(10000).default("").describe("Post body (max 10000 chars)"),
+            flair: z
+                .enum(["discussion", "article-request", "question", "announcement"])
+                .optional()
+                .describe("Post flair/category"),
+        }),
+        async execute({ community_slug, title, body, flair }) {
+            const json = { title, body };
+            if (flair)
+                json.flair = flair;
+            const resp = await request("POST", `/api/communities/${community_slug}/posts`, {
+                auth: true,
+                json,
+            });
+            const data = (await resp.json());
+            const postUrl = `https://www.openalmanac.org/communities/${community_slug}/post/${data.id}`;
+            return `Post created!\n\nURL: ${postUrl}\n\n${JSON.stringify(data, null, 2)}`;
+        },
+    });
+    server.addTool({
+        name: "link_article",
+        description: "Link an article to one or more communities. Use this after pushing an article to connect it " +
+            "with relevant communities. Call search_communities first to find matching communities. " +
+            "Idempotent — already-linked articles are reported but don't cause errors. Requires login.",
+        parameters: z.object({
+            article_id: z.string().describe("Article slug/ID to link (e.g. 'machine-learning')"),
+            community_slugs: z
+                .array(z.string())
+                .min(1)
+                .max(50)
+                .describe("List of community slugs to link the article to (max 50)"),
+        }),
+        async execute({ article_id, community_slugs }) {
+            const resp = await request("POST", `/api/articles/${article_id}/auto-link`, {
+                auth: true,
+                json: { community_slugs },
+            });
+            const data = (await resp.json());
+            const lines = [];
+            if (data.linked.length > 0) {
+                lines.push(`Linked to ${data.linked.length} communities: ${data.linked.join(", ")}`);
+            }
+            if (data.failed.length > 0) {
+                const failLines = data.failed.map((f) => `  ${f.slug}: ${f.reason}`);
+                lines.push(`Failed (${data.failed.length}):\n${failLines.join("\n")}`);
+            }
+            if (lines.length === 0) {
+                lines.push("No communities to link.");
+            }
+            return lines.join("\n\n");
+        },
+    });
+}

package/dist/tools/pages.js

@@ -283,8 +283,10 @@ export function registerPageTools(server) {
                     continue;
                 }
                 okCount++;
-                // Delete local .md and .ref
-                const published_slug = r.renamed_from ? targetSlugs[results.indexOf(r)] : r.slug;
+                // The local file was named with the pre-rename slug. The server returns
+                // `renamed_from` on rename so we can clean up the right file without
+                // relying on request/response index parity.
+                const published_slug = r.renamed_from ?? r.slug;
                 const { filePath, refPath } = resolvePagePaths(published_slug, wiki_slug);
                 try {
                     unlinkSync(filePath);

package/dist/tools/people.d.ts

@@ -0,0 +1,2 @@
+import { FastMCP } from "fastmcp";
+export declare function registerPeopleTools(server: FastMCP): void;

package/dist/tools/people.js

@@ -0,0 +1,20 @@
+import { z } from "zod";
+import { request } from "../auth.js";
+export function registerPeopleTools(server) {
+    server.addTool({
+        name: "search_people",
+        description: "Search for people to find their canonical slug for linking. Returns candidates with name, headline, " +
+            "image, and location. Use the returned slug when creating stubs and [[links]] for people. Requires login.",
+        parameters: z.object({
+            query: z.string().describe("Search terms (e.g. 'John Smith MIT professor')"),
+            limit: z.number().min(1).max(10).default(5).describe("Max results (1-10, default 5)"),
+        }),
+        async execute({ query, limit }) {
+            const resp = await request("GET", "/api/people/search", {
+                auth: true,
+                params: { query, limit },
+            });
+            return JSON.stringify(await resp.json(), null, 2);
+        },
+    });
+}

package/dist/tools/wikis.js

@@ -119,13 +119,13 @@ export function registerWikiTools(server) {
             nav: coerceJson(z.array(navItemSchema)).describe("Nav items"),
         }),
         async execute({ wiki_slug, nav }) {
-            // Get current settings, merge nav
-            const getResp = await request("GET", `/api/w/${wiki_slug}`);
-            const wiki = (await getResp.json());
-            const settings = { ...wiki.settings, nav };
+            // Single atomic PATCH — the backend's update_settings service uses
+            // model_dump(exclude_unset=True) to merge partial bodies, so sending
+            // only {nav} doesn't touch theme or cover_image_url. Previously this
+            // did a GET-then-PATCH, which raced with concurrent settings updates.
             const resp = await request("PATCH", `/api/w/${wiki_slug}/settings`, {
                 auth: true,
-                json: settings,
+                json: { nav },
             });
             return JSON.stringify(await resp.json(), null, 2);
         },

package/dist/validate.js

@@ -2,13 +2,13 @@ import { parse as parseYaml } from "yaml";
 import { z, ZodError } from "zod";
 // ── Primitives ──────────────────────────────────────────────────
 const sourceKeyRe = /^[a-z0-9]+-[a-z0-9]+(-[a-z0-9]+)*$/;
-const isoDateRe = /^\d{4}-\d{2}-\d{2}$/;
-// YAML can deserialize `accessed_date: 2026-04-17` as a Date object or leave
-// it as a string depending on quoting. Backend Pydantic coerces both to a
-// `date`; we accept both shapes here.
+// Match pydantic's `date` coercion: a bare YYYY-MM-DD date, OR any ISO-8601
+// datetime prefix — pydantic accepts "2026-04-17T00:00:00Z" as a date. yaml
+// may deserialize either as a `Date` object or a string.
+const isoDateLikeRe = /^\d{4}-\d{2}-\d{2}([T ].*)?$/;
 const accessedDateSchema = z.union([
     z.date(),
-    z.string().regex(isoDateRe, "Must be YYYY-MM-DD"),
+    z.string().regex(isoDateLikeRe, "Must be YYYY-MM-DD (optionally with an ISO time suffix)"),
 ]);
 // ── Source — mirrors backend/src/schemas/source_schemas.py ──────
 export const sourceSchema = z.object({
@@ -36,6 +36,10 @@ const headerBlockSchema = z.object({
     // `list` section with ListItem.link.
     links: z.array(z.string()).default([]),
 }).strict();
+// Matches `default_factory=HeaderBlock` on the pydantic model. A factory
+// (not a literal) so each default produces a fresh object — preventing
+// shared-reference aliasing if a caller mutates the default.
+const emptyHeader = () => ({ details: [], links: [] });
 const timelineItemSchema = z.object({
     primary: z.string(),
     secondary: z.string().nullable().optional(),
@@ -105,7 +109,7 @@ const sectionSchema = z.discriminatedUnion("type", [
     keyValueSectionSchema,
 ]);
 export const infoboxSchema = z.object({
-    header: headerBlockSchema.default({ details: [], links: [] }),
+    header: headerBlockSchema.default(emptyHeader),
     sections: z.array(sectionSchema).default([]),
 }).strict();
 // ── Frontmatter — mirrors backend PagePublishFrontmatter ────────

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openalmanac",
-  "version": "0.2.57",
+  "version": "0.2.59",
   "description": "OpenAlmanac — pull, edit, and push articles to the open knowledge base",
   "type": "module",
   "bin": {