openalmanac 0.4.1 → 0.4.3

package/dist/auth.d.ts

@@ -14,6 +14,7 @@ export type AuthStatus = {
 };
 export declare function getAuthStatus(): Promise<AuthStatus>;
 export declare function buildAuthHeaders(): Record<string, string>;
+export declare function requireValidApiKey(): Promise<void>;
 export declare function request(method: string, path: string, options?: {
     auth?: boolean;
     params?: Record<string, string | number | boolean>;

package/dist/auth.js

@@ -59,6 +59,20 @@ export async function getAuthStatus() {
 export function buildAuthHeaders() {
     return { Authorization: `Bearer ${requireApiKey()}` };
 }
+export async function requireValidApiKey() {
+    const key = requireApiKey();
+    const resp = await fetch(`${API_BASE}/api/users/me`, {
+        headers: { Authorization: `Bearer ${key}` },
+        signal: AbortSignal.timeout(10_000),
+    });
+    if (resp.ok)
+        return;
+    if (resp.status === 401 || resp.status === 403) {
+        throw new Error(`Authentication failed (${resp.status}). Your API key may be invalid or expired. Run 'login' to re-authenticate.`);
+    }
+    const text = await resp.text();
+    throw new Error(`${resp.status} ${resp.statusText}: ${text}`);
+}
 export async function request(method, path, options = {}) {
     const { auth = false, params, json, body, contentType } = options;
     let url = `${API_BASE}${path}`;

package/dist/instructions.js

@@ -1,5 +1,5 @@
 export const SERVER_INSTRUCTIONS = [
-    "OpenAlmanac is an open knowledge base — a Wikipedia anyone can read from and write to through an API. Pages are markdown files with YAML frontmatter, [@key] citation markers, and [[wikilinks]]. Content is organized into wikis, each with topics, pages, and navigation.",
+    "Almanac is an open knowledge base — a Wikipedia anyone can read from and write to through an API. Pages are markdown files with YAML frontmatter, [@key] citation markers, and [[wikilinks]]. Content is organized into wikis, each with topics, pages, and navigation.",
     "",
     "## How this should feel",
     "",
@@ -113,7 +113,7 @@ export const SERVER_INSTRUCTIONS = [
     "",
     "## Working across wikis",
     "",
-    "OpenAlmanac is multi-wiki. Every page lives inside one wiki. Before writing or creating anything, ground yourself:",
+    "Almanac is multi-wiki. Every page lives inside one wiki. Before writing or creating anything, ground yourself:",
     "",
     "- `whoami` → who is the user? Needed to address them and to reason about \"my wikis\".",
     "- `list_wikis` → what wikis exist? Use this BEFORE `create_wiki` so you can suggest contributing to an existing wiki instead of spinning up a parallel one.",
@@ -136,7 +136,7 @@ export const SERVER_INSTRUCTIONS = [
     "",
     "## Technical workflow",
     "",
-    "Reading and searching pages is open. Writing requires an API key (from login). Login creates a personal API key linked to your user account, so contributions are attributed to you.",
+    "All Almanac MCP tools except `login` and `logout` require login. Login creates a personal API key linked to your user account, so MCP reads, research, and contributions are attributed to you.",
     "",
     "Core flow: login (once) → `whoami` (confirm identity) → `list_wikis` or `search_pages` (what exists?) → `search_web` + `read_webpage` (research) → `new` (scaffold) or `download` (existing) → edit files under ~/.openalmanac/pages/{wiki_slug}/ → `publish`.",
     "",

package/dist/onboarding-copy.js

@@ -2,7 +2,7 @@
 // post-login connected page rendered by `login-core.ts`.
 //
 // The example prompt is a starter question on purpose: the goal is to give
-// new users an easy first message that teaches them what OpenAlmanac can do
+// new users an easy first message that teaches them what Almanac can do
 // instead of assuming they already know what to ask. If the example prompt
 // changes, both surfaces (`setup.ts` next steps + `login-core.ts` terminal
 // mock) update automatically because they consume this single constant.

package/dist/server.js

@@ -10,6 +10,7 @@ import { registerTopicTools } from "./tools/topics.js";
 import { registerUserTools } from "./tools/users.js";
 import { getApiKey } from "./auth.js";
 import { SERVER_INSTRUCTIONS } from "./instructions.js";
+import { installMcpToolTracking } from "./tool-tracking.js";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf-8"));
 export function createServer() {
@@ -17,12 +18,12 @@ export function createServer() {
         console.error(`
 ┌──────────────────────────────────────────────────┐
 │                                                  │
-│   Welcome to OpenAlmanac                         │
+│   Welcome to Almanac                             │
 │                                                  │
 │   Try asking your agent:                         │
 │                                                  │
-│   → "Write an Almanac page about CORS"        │
-│   → "Improve the Alan Turing page"            │
+│   → "Write an Almanac page about CORS"           │
+│   → "Improve the Alan Turing page"               │
 │                                                  │
 │   Docs: openalmanac.org/contribute               │
 │                                                  │
@@ -30,10 +31,11 @@ export function createServer() {
 `);
     }
     const server = new FastMCP({
-        name: "OpenAlmanac",
+        name: "Almanac",
         version: pkg.version,
         instructions: SERVER_INSTRUCTIONS,
     });
+    installMcpToolTracking(server, pkg.version);
     registerAuthTools(server);
     registerPageTools(server);
     registerResearchTools(server);

package/dist/setup/clients.js

@@ -254,7 +254,7 @@ export function applyClientSetup(clients, mode) {
     return { configured, alreadyConfigured };
 }
 export function printSetupPlan(clients, options) {
-    const heading = options.dryRun ? "Dry run" : "OpenAlmanac MCP setup";
+    const heading = options.dryRun ? "Dry run" : "Almanac 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");

package/dist/setup/tui.js

@@ -57,6 +57,54 @@ function stepActive(msg) {
 // Strip ANSI codes to measure visible length
 const vis = (s) => s.replace(/\x1b\[[0-9;]*m/g, "").length;
 const w = (s) => process.stdout.write(s + "\n");
+function getBoxInnerWidth(contents, minWidth = 62) {
+    const terminalWidth = process.stdout.columns ?? 80;
+    const available = Math.max(40, terminalWidth - 6);
+    const widest = contents.reduce((max, content) => Math.max(max, vis(content)), 0);
+    return Math.min(Math.max(minWidth, widest), available);
+}
+function boxRow(content, innerW) {
+    const padding = Math.max(0, innerW - vis(content));
+    return `  ${BLUE_DIM}\u2502${RST}${content}${" ".repeat(padding)}${BLUE_DIM}\u2502${RST}`;
+}
+function wrapWithPrefixes(text, firstPrefix, nextPrefix, innerW) {
+    const words = text.split(" ").filter(Boolean);
+    if (words.length === 0)
+        return [firstPrefix];
+    const lines = [];
+    let prefix = firstPrefix;
+    let line = prefix;
+    let hasWord = false;
+    for (const word of words) {
+        const candidate = hasWord ? `${line} ${word}` : `${prefix}${word}`;
+        if (hasWord && vis(candidate) > innerW) {
+            lines.push(line);
+            prefix = nextPrefix;
+            line = `${prefix}${word}`;
+            hasWord = true;
+            continue;
+        }
+        line = candidate;
+        hasWord = true;
+    }
+    lines.push(line);
+    return lines;
+}
+function renderNextStepsBox(lines) {
+    const header = `  ${WHITE_BOLD}Next steps${RST}`;
+    const innerW = getBoxInnerWidth([header, ...lines]);
+    const empty = boxRow("", innerW);
+    w(`  ${BLUE_DIM}\u256d${"─".repeat(innerW)}\u256e${RST}`);
+    w(empty);
+    w(boxRow(header, innerW));
+    w(empty);
+    for (const line of lines) {
+        w(boxRow(line, innerW));
+    }
+    w(empty);
+    w(`  ${BLUE_DIM}\u2570${"─".repeat(innerW)}\u256f${RST}`);
+    w("");
+}
 function renderClientSelect(clients, selected, cursor, mode = "default") {
     process.stdout.write("\x1b[2J\x1b[H");
     renderHeader(mode);
@@ -395,24 +443,9 @@ export function printResult(clientsLabel, loginResult, configured, alreadyConfig
     w(BAR);
     stepDone(`${BLUE}Setup complete${RST}`);
     w("");
-    // Next steps box
-    const innerW = 62;
-    const row = (content) => {
-        const padding = Math.max(0, innerW - vis(content));
-        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);
-    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("");
+    const nextStepLines = nextSteps.flatMap((step, i) => wrapWithPrefixes(step, `  ${BLUE}${i + 1}.${RST}  `, "     ", 62));
+    renderNextStepsBox(nextStepLines);
 }
 function getNextSteps(clientsLabel) {
     const exampleLine = `${BLUE}"${EXAMPLE_PROMPT}"${RST}`;
@@ -477,20 +510,8 @@ export function printRedditResult(agent, loginResult, mcpChanged, toolCount) {
     w(BAR);
     stepDone(`${BLUE}Setup complete${RST}`);
     w("");
-    // Next steps box
-    const innerW = 62;
-    const row = (content) => {
-        const padding = Math.max(0, innerW - vis(content));
-        return `  ${BLUE_DIM}\u2502${RST}${content}${" ".repeat(padding)}${BLUE_DIM}\u2502${RST}`;
-    };
-    const empty = row("");
-    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(empty);
-    w(`  ${BLUE_DIM}\u2570${"─".repeat(innerW)}\u256f${RST}`);
-    w("");
+    renderNextStepsBox([
+        `  ${BLUE}1.${RST}  Type ${WHITE_BOLD}claude${RST} to start Claude Code`,
+    ]);
 }
 /* ── Reddit entry point ────────────────────────────────────────── */

package/dist/tool-registry.js

@@ -1,4 +1,4 @@
-// Single source of truth for the MCP tools the OpenAlmanac server exposes.
+// Single source of truth for the MCP tools the Almanac server exposes.
 //
 // This file is the contract that ties three otherwise-independent surfaces
 // together:

package/dist/tool-tracking.d.ts

@@ -0,0 +1,27 @@
+import type { FastMCP } from "fastmcp";
+type ToolGroup = "read" | "write" | "research" | "wiki_admin" | "account";
+type IntentDomain = "auth" | "page_read" | "page_write" | "search" | "topic_management" | "web_research" | "wiki_management";
+export interface McpToolCallEvent {
+    tool_name: string;
+    tool_group: ToolGroup;
+    intent_domain: IntentDomain;
+    success: boolean;
+    duration_ms: number;
+    mcp_version: string;
+    error_type?: string;
+}
+interface McpToolDefinition {
+    name: string;
+    execute?: (...args: any[]) => unknown;
+    [key: string]: unknown;
+}
+interface ToolTrackingDeps {
+    mcpVersion: string;
+    validateAuth?: () => Promise<void>;
+    trackToolCall?: (event: McpToolCallEvent) => Promise<void>;
+    now?: () => number;
+}
+export declare function postMcpToolCall(event: McpToolCallEvent): Promise<void>;
+export declare function wrapMcpToolDefinition<T extends McpToolDefinition>(definition: T, deps: ToolTrackingDeps): T;
+export declare function installMcpToolTracking(server: FastMCP, mcpVersion: string): FastMCP;
+export {};

package/dist/tool-tracking.js

@@ -0,0 +1,92 @@
+import { request, requireValidApiKey } from "./auth.js";
+const AUTH_EXEMPT_TOOLS = new Set(["login", "logout"]);
+const TOOL_METADATA = {
+    search_pages: { tool_group: "read", intent_domain: "search" },
+    search_topics: { tool_group: "read", intent_domain: "search" },
+    list_pages: { tool_group: "read", intent_domain: "page_read" },
+    list_topics: { tool_group: "read", intent_domain: "page_read" },
+    list_wikis: { tool_group: "read", intent_domain: "wiki_management" },
+    download: { tool_group: "read", intent_domain: "page_read" },
+    read_page: { tool_group: "read", intent_domain: "page_read" },
+    search_web: { tool_group: "research", intent_domain: "web_research" },
+    read_webpage: { tool_group: "research", intent_domain: "web_research" },
+    search_images: { tool_group: "research", intent_domain: "web_research" },
+    view_images: { tool_group: "research", intent_domain: "web_research" },
+    new: { tool_group: "write", intent_domain: "page_write" },
+    publish: { tool_group: "write", intent_domain: "page_write" },
+    delete_pages: { tool_group: "write", intent_domain: "page_write" },
+    create_topics: { tool_group: "write", intent_domain: "topic_management" },
+    update_topic: { tool_group: "write", intent_domain: "topic_management" },
+    create_wiki: { tool_group: "wiki_admin", intent_domain: "wiki_management" },
+    get_wiki_settings: { tool_group: "wiki_admin", intent_domain: "wiki_management" },
+    update_wiki_settings: { tool_group: "wiki_admin", intent_domain: "wiki_management" },
+    join_wiki: { tool_group: "wiki_admin", intent_domain: "wiki_management" },
+    get_wiki_membership: { tool_group: "wiki_admin", intent_domain: "wiki_management" },
+    whoami: { tool_group: "account", intent_domain: "auth" },
+};
+function metadataForTool(toolName) {
+    return TOOL_METADATA[toolName] ?? { tool_group: "account", intent_domain: "auth" };
+}
+function errorType(error) {
+    if (error instanceof Error && error.name)
+        return error.name;
+    return typeof error;
+}
+export async function postMcpToolCall(event) {
+    await request("POST", "/api/mcp/tool-calls", {
+        auth: true,
+        json: event,
+    });
+}
+export function wrapMcpToolDefinition(definition, deps) {
+    if (!definition.execute || AUTH_EXEMPT_TOOLS.has(definition.name)) {
+        return definition;
+    }
+    const execute = definition.execute;
+    const validateAuth = deps.validateAuth ?? requireValidApiKey;
+    const trackToolCall = deps.trackToolCall ?? postMcpToolCall;
+    const now = deps.now ?? Date.now;
+    const metadata = metadataForTool(definition.name);
+    return {
+        ...definition,
+        async execute(...args) {
+            await validateAuth();
+            const startedAt = now();
+            let success = false;
+            let caught;
+            try {
+                const result = await execute(...args);
+                success = true;
+                return result;
+            }
+            catch (error) {
+                caught = error;
+                throw error;
+            }
+            finally {
+                const event = {
+                    tool_name: definition.name,
+                    ...metadata,
+                    success,
+                    duration_ms: Math.max(0, Math.round(now() - startedAt)),
+                    mcp_version: deps.mcpVersion,
+                };
+                if (caught !== undefined) {
+                    event.error_type = errorType(caught);
+                }
+                try {
+                    await trackToolCall(event);
+                }
+                catch {
+                    // Analytics should never change tool behavior.
+                }
+            }
+        },
+    };
+}
+export function installMcpToolTracking(server, mcpVersion) {
+    const addTool = server.addTool.bind(server);
+    server.addTool =
+        (definition) => addTool(wrapMcpToolDefinition(definition, { mcpVersion }));
+    return server;
+}

package/dist/tools/auth.js

@@ -4,7 +4,7 @@ export function registerAuthTools(server) {
     server.addTool({
         name: "login",
         description: "Log in via browser to connect your account and get a personal API key. This is the required " +
-            "first step before creating or updating pages. Only needs to be called once.\n\n" +
+            "first step before using Almanac MCP tools. Only needs to be called once.\n\n" +
             "If you already have a valid API key, this returns immediately without opening a browser.",
         async execute() {
             const result = await performLogin();

package/dist/tools/pages/index.js

@@ -10,8 +10,8 @@ import { WRITING_GUIDE } from "./writing-guide.js";
 export function registerPageTools(server) {
     server.addTool({
         name: "search_pages",
-        description: "Search OpenAlmanac pages and stubs across all wikis. Use to check existence, find slugs for wikilinks, " +
-            "or discover content. Optional wiki filter to scope results. No authentication needed.",
+        description: "Search Almanac pages and stubs across all wikis. Use to check existence, find slugs for wikilinks, " +
+            "or discover content. Optional wiki filter to scope results. Requires login.",
         parameters: z.object({
             queries: coerceJson(z.array(z.string()).min(1).max(20)).describe("Search queries (1-20)"),
             wiki: z.string().optional().describe("Filter to a specific wiki slug"),
@@ -28,7 +28,7 @@ export function registerPageTools(server) {
             };
             if (wiki)
                 body.wiki = wiki;
-            const resp = await request("POST", "/api/search/batch", { json: body });
+            const resp = await request("POST", "/api/search/batch", { auth: true, json: body });
             const data = (await resp.json());
             const byQuery = {};
             for (const set of data.results) {
@@ -39,8 +39,8 @@ export function registerPageTools(server) {
     });
     server.addTool({
         name: "search_topics",
-        description: "Search OpenAlmanac topics across all wikis. Use to discover topic slugs and topic pages. " +
-            "Optional wiki filter to scope results. No authentication needed.",
+        description: "Search Almanac topics across all wikis. Use to discover topic slugs and topic pages. " +
+            "Optional wiki filter to scope results. Requires login.",
         parameters: z.object({
             queries: coerceJson(z.array(z.string()).min(1).max(20)).describe("Search queries (1-20)"),
             wiki: z.string().optional().describe("Filter to a specific wiki slug"),
@@ -54,7 +54,7 @@ export function registerPageTools(server) {
                 };
                 if (wiki)
                     params.wiki = wiki;
-                const resp = await request("GET", "/api/search", { params });
+                const resp = await request("GET", "/api/search", { auth: true, params });
                 results[q] = await resp.json();
             }
             return JSON.stringify(results, null, 2);
@@ -64,7 +64,7 @@ export function registerPageTools(server) {
         name: "list_pages",
         description: "Browse pages in a wiki. Structured listing, not fuzzy search. " +
             "Use to see what exists, find stubs, or discover pages by topic. " +
-            "Each returned page includes topic objects with both slug and title.",
+            "Each returned page includes topic objects with both slug and title. Requires login.",
         parameters: z.object({
             wiki_slug: z.string().describe("Wiki slug"),
             topic: z.string().optional().describe("Filter by topic slug"),
@@ -78,7 +78,7 @@ export function registerPageTools(server) {
                 params.topic = topic;
             if (stubs_only)
                 params.stub = true;
-            const resp = await request("GET", `/api/w/${wiki_slug}/pages`, { params });
+            const resp = await request("GET", `/api/w/${wiki_slug}/pages`, { auth: true, params });
             return JSON.stringify(await resp.json(), null, 2);
         },
     });
@@ -272,13 +272,13 @@ export function registerPageTools(server) {
         description: "Read a single page by slug. Returns the full page JSON including content, topics, sources, and infobox. " +
             "No side effects — use this to read a page without downloading it to disk or joining the wiki. " +
             "For editing, use `download` instead (it writes local files and handles ref tokens). " +
-            "For discovery, use `search_pages` instead. No authentication needed.",
+            "For discovery, use `search_pages` instead. Requires login.",
         parameters: z.object({
             wiki_slug: z.string().describe("Wiki slug"),
             page_slug: z.string().describe("Page slug"),
         }),
         async execute({ wiki_slug, page_slug }) {
-            const resp = await request("GET", `/api/w/${wiki_slug}/pages/${page_slug}`);
+            const resp = await request("GET", `/api/w/${wiki_slug}/pages/${page_slug}`, { auth: true });
             return JSON.stringify(await resp.json(), null, 2);
         },
     });

package/dist/tools/topics.js

@@ -4,13 +4,14 @@ import { coerceJson } from "../utils.js";
 export function registerTopicTools(server) {
     server.addTool({
         name: "list_topics",
-        description: "List topics in a wiki. Returns flat list or graph (nodes + edges). No authentication needed.",
+        description: "List topics in a wiki. Returns flat list or graph (nodes + edges). Requires login.",
         parameters: z.object({
             wiki_slug: z.string().describe("Wiki slug"),
             format: z.enum(["flat", "graph"]).default("flat").describe("Response format"),
         }),
         async execute({ wiki_slug, format }) {
             const resp = await request("GET", `/api/w/${wiki_slug}/topics`, {
+                auth: true,
                 params: { format },
             });
             return JSON.stringify(await resp.json(), null, 2);

package/dist/tools/wikis.js

@@ -1,6 +1,18 @@
 import { z } from "zod";
 import { request } from "../auth.js";
 import { coerceJson } from "../utils.js";
+const MAX_IMAGE_URL_LENGTH = 2048;
+const httpImageUrlSchema = z.string()
+    .max(MAX_IMAGE_URL_LENGTH)
+    .refine((value) => !value.startsWith("data:") && !value.includes("base64,"), "Use an http(s) image URL, not inline image data")
+    .refine((value) => value.startsWith("http://") || value.startsWith("https://"), "Image URL must start with http:// or https://");
+const coverImageUrlSchema = z.string()
+    .max(MAX_IMAGE_URL_LENGTH)
+    .refine((value) => value.startsWith("linear-gradient(") ||
+    value.startsWith("http://") ||
+    value.startsWith("https://"), "Cover image must be an http(s) URL or gallery gradient")
+    .refine((value) => value.startsWith("linear-gradient(") ||
+    (!value.startsWith("data:") && !value.includes("base64,")), "Use an http(s) image URL, not inline image data");
 // Mirrors backend `NavItem` in src/schemas/wiki_settings_schemas.py. The
 // refinement matches the `exactly_one_target` @model_validator there —
 // agents get a clear error pre-flight instead of a 422 round-trip.
@@ -34,7 +46,7 @@ const navItemSchema = z.lazy(() => z.object({
 const themeSchema = z.object({
     accent_color: z.string().optional(),
     name_font: z.string().optional(),
-    logo_url: z.string().optional(),
+    logo_url: httpImageUrlSchema.nullable().optional(),
     cover_tint_intensity: z.number().optional(),
     logo_tint_intensity: z.number().optional(),
     cover_y_offset: z.number().optional(),
@@ -42,12 +54,13 @@ const themeSchema = z.object({
 export function registerWikiTools(server) {
     server.addTool({
         name: "list_wikis",
-        description: "List every wiki on OpenAlmanac. Use before creating a new wiki so you can suggest contributing to an existing one. The global almanac has slug `global` and is excluded by default — pass `include_global: true` to include it. No authentication needed.",
+        description: "List every wiki on Almanac. Use before creating a new wiki so you can suggest contributing to an existing one. The global almanac has slug `global` and is excluded by default — pass `include_global: true` to include it. Requires login.",
         parameters: z.object({
             include_global: z.boolean().default(false).describe("Include the global almanac wiki in results"),
         }),
         async execute({ include_global }) {
             const resp = await request("GET", "/api/wikis", {
+                auth: true,
                 params: { include_global },
             });
             return JSON.stringify(await resp.json(), null, 2);
@@ -71,23 +84,23 @@ export function registerWikiTools(server) {
     });
     server.addTool({
         name: "get_wiki_settings",
-        description: "Read a wiki's details and settings (nav, cover, theme). No authentication needed.",
+        description: "Read a wiki's details and settings (nav, cover, theme). Requires login.",
         parameters: z.object({
             wiki_slug: z.string().describe("Wiki slug"),
         }),
         async execute({ wiki_slug }) {
-            const resp = await request("GET", `/api/w/${wiki_slug}`);
+            const resp = await request("GET", `/api/w/${wiki_slug}`, { auth: true });
             return JSON.stringify(await resp.json(), null, 2);
         },
     });
     server.addTool({
         name: "update_wiki_settings",
-        description: "Update a wiki's settings. Pass any combination of `nav`, `cover_image_url`, and `theme` — omitted fields are preserved (the backend uses exclude_unset merge). For example, `{nav: [...]}` updates navigation only without touching theme or cover_image_url. Each NavItem must have exactly one of `page`, `topic`, or `link`. Use `auto` (only on topic items) to auto-populate children from the topic DAG. Requires moderator access.",
+        description: "Update a wiki's settings. Pass any combination of `nav`, `cover_image_url`, and `theme` — omitted fields are preserved (the backend uses exclude_unset merge). For example, `{nav: [...]}` updates navigation only without touching theme or cover_image_url. `cover_image_url` accepts http(s) image URLs or gallery gradients; `theme.logo_url` accepts http(s) image URLs. Do not pass inline base64/data image strings. Each NavItem must have exactly one of `page`, `topic`, or `link`. Use `auto` (only on topic items) to auto-populate children from the topic DAG. Requires moderator access.",
         parameters: z.object({
             wiki_slug: z.string().describe("Wiki slug"),
             settings: coerceJson(z.object({
                 nav: z.array(navItemSchema).optional(),
-                cover_image_url: z.string().optional(),
+                cover_image_url: coverImageUrlSchema.nullable().optional(),
                 theme: themeSchema.optional(),
             })).describe("Settings to update"),
         }),

package/package.json

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