openalmanac 0.3.2 → 0.3.4

package/dist/setup.js

@@ -137,6 +137,9 @@ const CLAUDE_CODE_MCP = join(CLAUDE_DIR, "mcp.json"); // Claude Code local MCP c
 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 OPENCODE_DIR = join(homedir(), ".config", "opencode");
+const OPENCODE_JSON = join(OPENCODE_DIR, "opencode.json");
+const OPENCODE_JSONC = join(OPENCODE_DIR, "opencode.jsonc");
 const WINDSURF_MCP_JSON = join(homedir(), ".codeium", "mcp_config.json");
 function ensureDir(dir) {
     if (!existsSync(dir))
@@ -160,6 +163,7 @@ const SUPPORTED_CLIENT_IDS = [
     "claude-desktop",
     "codex",
     "cursor",
+    "opencode",
     "windsurf",
 ];
 const SUPPORTED_CLIENTS = {
@@ -256,6 +260,36 @@ const SUPPORTED_CLIENTS = {
             ],
         }),
     },
+    opencode: {
+        id: "opencode",
+        name: "OpenCode",
+        selectionLabel: "OpenCode",
+        detect: () => hasCommand("opencode") ||
+            existsSync(OPENCODE_JSON) ||
+            existsSync(OPENCODE_JSONC) ||
+            existsSync(OPENCODE_DIR),
+        configure: (mode) => {
+            const path = getOpenCodeConfigPath();
+            return {
+                changed: configureOpenCodeFile(path, mode),
+                snippets: [
+                    {
+                        path,
+                        content: jsonSnippet({
+                            "$schema": "https://opencode.ai/config.json",
+                            mcp: {
+                                almanac: {
+                                    type: "local",
+                                    command: [ALMANAC_MCP_ENTRY.command, ...ALMANAC_MCP_ENTRY.args],
+                                    enabled: true,
+                                },
+                            },
+                        }),
+                    },
+                ],
+            };
+        },
+    },
     windsurf: {
         id: "windsurf",
         name: "Windsurf",
@@ -340,6 +374,7 @@ function normalizeClientId(value) {
         desktop: "claude-desktop",
         codex: "codex",
         cursor: "cursor",
+        opencode: "opencode",
         windsurf: "windsurf",
     };
     const normalized = aliases[value];
@@ -390,6 +425,13 @@ function isClaudeDesktopInstalled() {
 function jsonSnippet(data) {
     return JSON.stringify(data, null, 2);
 }
+function getOpenCodeConfigPath() {
+    if (existsSync(OPENCODE_JSON))
+        return OPENCODE_JSON;
+    if (existsSync(OPENCODE_JSONC))
+        return OPENCODE_JSONC;
+    return OPENCODE_JSON;
+}
 function codexSnippet() {
     return [
         "[mcp_servers.almanac]",
@@ -401,6 +443,12 @@ function isAlmanacCurrent(server) {
     return (server?.command === "npx" &&
         JSON.stringify(server.args) === JSON.stringify(ALMANAC_MCP_ENTRY.args));
 }
+function isOpenCodeAlmanacCurrent(entry) {
+    return (entry?.type === "local" &&
+        entry?.enabled === true &&
+        JSON.stringify(entry.command) ===
+            JSON.stringify([ALMANAC_MCP_ENTRY.command, ...ALMANAC_MCP_ENTRY.args]));
+}
 function configureJsonMcpFile(path, mode) {
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     const json = readJson(path);
@@ -428,6 +476,29 @@ function configureCodexToml(path, mode) {
     }
     return true;
 }
+function configureOpenCodeFile(path, mode) {
+    const current = readJsonWithComments(path);
+    if (!current.$schema) {
+        current.$schema = "https://opencode.ai/config.json";
+    }
+    const mcp = isRecord(current.mcp) ? current.mcp : {};
+    if (!isRecord(current.mcp)) {
+        current.mcp = mcp;
+    }
+    if (isOpenCodeAlmanacCurrent(mcp.almanac)) {
+        return false;
+    }
+    mcp.almanac = {
+        type: "local",
+        command: [ALMANAC_MCP_ENTRY.command, ...ALMANAC_MCP_ENTRY.args],
+        enabled: true,
+    };
+    if (mode === "apply") {
+        ensureDir(dirname(path));
+        writeJson(path, current);
+    }
+    return true;
+}
 function readToml(path) {
     try {
         return readFileSync(path, "utf-8");
@@ -436,6 +507,72 @@ function readToml(path) {
         return "";
     }
 }
+function readJsonWithComments(path) {
+    try {
+        const raw = readFileSync(path, "utf-8");
+        const parsed = JSON.parse(stripJsonComments(raw));
+        return isRecord(parsed) ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+function stripJsonComments(input) {
+    let result = "";
+    let inString = false;
+    let inLineComment = false;
+    let inBlockComment = false;
+    let escaped = false;
+    for (let i = 0; i < input.length; i++) {
+        const char = input[i];
+        const next = input[i + 1];
+        if (inLineComment) {
+            if (char === "\n") {
+                inLineComment = false;
+                result += char;
+            }
+            continue;
+        }
+        if (inBlockComment) {
+            if (char === "*" && next === "/") {
+                inBlockComment = false;
+                i++;
+            }
+            continue;
+        }
+        if (inString) {
+            result += char;
+            if (escaped) {
+                escaped = false;
+            }
+            else if (char === "\\") {
+                escaped = true;
+            }
+            else if (char === "\"") {
+                inString = false;
+            }
+            continue;
+        }
+        if (char === "/" && next === "/") {
+            inLineComment = true;
+            i++;
+            continue;
+        }
+        if (char === "/" && next === "*") {
+            inBlockComment = true;
+            i++;
+            continue;
+        }
+        if (char === "\"") {
+            inString = true;
+        }
+        result += char;
+    }
+    return result;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
 function upsertCodexServer(content) {
     const sectionName = "mcp_servers.almanac";
     const header = `[${sectionName}]`;
@@ -934,6 +1071,12 @@ function getNextSteps(clientsLabel) {
             `Ask ${BLUE}"Let's explore <topic> using Almanac"${RST}`,
         ];
     }
+    if (clientsLabel === "OpenCode") {
+        return [
+            `Type ${WHITE_BOLD}opencode${RST} to start OpenCode`,
+            `Ask ${BLUE}"Let's explore <topic> using Almanac"${RST}`,
+        ];
+    }
     if (clientsLabel === "Windsurf") {
         return [
             `Open ${WHITE_BOLD}Windsurf${RST} in your project`,

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,511 @@
+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 } from "../auth.js";
+import { validateArticle, parseFrontmatter } from "../validate.js";
+import { openBrowser } from "../browser.js";
+const SLUG_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+function slugify(title) {
+    return title
+        .toLowerCase()
+        .normalize("NFD")
+        .replace(/[\u0300-\u036f]/g, "")
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .replace(/-{2,}/g, "-");
+}
+/**
+ * Workaround for Claude Agent SDK MCP transport bug (#18260):
+ * Array/object parameters are sometimes serialized as JSON strings
+ * instead of native values. This preprocessor coerces them back.
+ */
+function coerceJson(schema) {
+    return z.preprocess((val) => {
+        if (typeof val === "string") {
+            try {
+                return JSON.parse(val);
+            }
+            catch {
+                return val;
+            }
+        }
+        return val;
+    }, schema);
+}
+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 });
+}
+function resolveArticleDir(communitySlug) {
+    return communitySlug ? join(ARTICLES_DIR, communitySlug) : ARTICLES_DIR;
+}
+function resolveArticlePaths(slug, communitySlug) {
+    const dir = resolveArticleDir(communitySlug);
+    return {
+        dir,
+        filePath: join(dir, `${slug}.md`),
+        originalPath: join(dir, `.${slug}.original.md`),
+    };
+}
+function findDraftCandidates(slug) {
+    const matches = [];
+    const root = resolveArticlePaths(slug);
+    if (existsSync(root.filePath)) {
+        matches.push({ communitySlug: null, filePath: root.filePath, originalPath: root.originalPath });
+    }
+    try {
+        const dirs = readdirSync(ARTICLES_DIR).filter((d) => {
+            try {
+                return statSync(join(ARTICLES_DIR, d)).isDirectory();
+            }
+            catch {
+                return false;
+            }
+        });
+        for (const communitySlug of dirs) {
+            const scoped = resolveArticlePaths(slug, communitySlug);
+            if (existsSync(scoped.filePath)) {
+                matches.push({ communitySlug, filePath: scoped.filePath, originalPath: scoped.originalPath });
+            }
+        }
+    }
+    catch { /* ignore readdir errors */ }
+    return matches;
+}
+function resolvePublishCandidate(slug, communitySlug) {
+    if (communitySlug) {
+        const paths = resolveArticlePaths(slug, communitySlug);
+        if (!existsSync(paths.filePath)) {
+            throw new Error(`File not found: ${paths.filePath}\nUse download to get an existing article or new to create a scaffold.`);
+        }
+        return { communitySlug, ...paths };
+    }
+    const matches = findDraftCandidates(slug);
+    if (matches.length === 0) {
+        const fallback = resolveArticlePaths(slug);
+        throw new Error(`File not found: ${fallback.filePath}\nUse download to get an existing article or new to create a scaffold.`);
+    }
+    if (matches.length > 1) {
+        const paths = matches.map((match) => `  - ${match.filePath}`).join("\n");
+        throw new Error(`Multiple local drafts found for slug "${slug}". Publish is ambiguous.\n${paths}\nRemove the duplicate draft or publish with community_slug set.`);
+    }
+    return matches[0];
+}
+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. " +
+            "Pass community_slug to restrict results to articles owned by that community wiki (does not include global articles). No authentication needed.",
+        parameters: z.object({
+            queries: coerceJson(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)"),
+            community_slug: z.string().optional().describe("Optional community slug. When set, results are restricted to articles owned by that community wiki only — global articles are excluded. Omit to search all of OpenAlmanac."),
+        }),
+        async execute({ queries, limit, include_stubs, community_slug }) {
+            const json = { queries, limit, include_stubs };
+            if (community_slug)
+                json.community_slug = community_slug;
+            const resp = await request("POST", "/api/search/batch", { json });
+            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: coerceJson(z.array(z.string()).min(1).max(20)).describe("Article slugs to read (1-20)"),
+            community_slug: z.string().optional().describe("Community slug for reading community-owned wiki articles. Omit for global almanac articles."),
+        }),
+        async execute({ slugs, community_slug }) {
+            const json = { slugs };
+            if (community_slug)
+                json.community_slug = community_slug;
+            const resp = await request("POST", "/api/articles/batch", { json });
+            return JSON.stringify(await resp.json(), null, 2);
+        },
+    });
+    server.addTool({
+        name: "download",
+        description: "Download articles to your local workspace for editing. " +
+            "Global articles: ~/.openalmanac/articles/{slug}.md. Community wiki: ~/.openalmanac/articles/{community_slug}/{slug}.md. " +
+            "Returns a writing guide on first call. After editing, use publish to push changes.",
+        parameters: z.object({
+            slugs: coerceJson(z.array(z.string()).min(1).max(50)).describe("Article slugs to download (1-50)"),
+            community_slug: z.string().optional().describe("Community slug for community-owned wiki articles"),
+        }),
+        async execute({ slugs, community_slug }) {
+            for (const slug of slugs) {
+                if (!SLUG_RE.test(slug)) {
+                    throw new Error(`Invalid slug "${slug}". Must be kebab-case (e.g. 'machine-learning').`);
+                }
+            }
+            const json = { slugs };
+            if (community_slug)
+                json.community_slug = community_slug;
+            const resp = await request("POST", "/api/articles/batch-download", { json });
+            const data = (await resp.json());
+            ensureArticlesDir();
+            const lines = [];
+            for (const slug of slugs) {
+                if (data.errors[slug]) {
+                    lines.push(`FAILED ${slug}: ${data.errors[slug]}`);
+                    continue;
+                }
+                const markdown = data.articles[slug];
+                if (!markdown) {
+                    lines.push(`FAILED ${slug}: missing from response`);
+                    continue;
+                }
+                const { dir, filePath, originalPath } = resolveArticlePaths(slug, community_slug);
+                if (community_slug) {
+                    mkdirSync(dir, { recursive: true });
+                }
+                writeFileSync(filePath, markdown, "utf-8");
+                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."
+                    : "";
+                lines.push(`Downloaded "${title}" to ${filePath}\n${wordCount} words, ${frontmatter.sources?.length ?? 0} sources.${stubNote}`);
+            }
+            return [lines.join("\n"), "", WRITING_GUIDE].join("\n");
+        },
+    });
+    server.addTool({
+        name: "new",
+        description: "Scaffold new articles locally. Creates .md files with YAML frontmatter and empty bodies. " +
+            "Provide explicit slugs when you know the canonical ID; otherwise they are auto-derived from titles. For community wiki articles, provide community_slug. " +
+            "After writing content, use publish to go live.",
+        parameters: z.object({
+            articles: coerceJson(z.array(z.object({
+                title: z.string().describe("Article title"),
+                slug: z.string().optional().describe("Optional explicit kebab-case slug. Encouraged when you know the canonical ID."),
+                topics: z.array(z.string()).optional().describe("Topic slugs for community wiki articles"),
+            })).min(1).max(50)).describe("Articles to scaffold (1-50)"),
+            community_slug: z.string().optional().describe("Community slug for community-owned wiki articles"),
+        }),
+        async execute({ articles, community_slug }) {
+            if (community_slug && !SLUG_RE.test(community_slug)) {
+                throw new Error(`Invalid community_slug "${community_slug}". Must be kebab-case.`);
+            }
+            ensureArticlesDir();
+            let dir = ARTICLES_DIR;
+            if (community_slug) {
+                dir = join(ARTICLES_DIR, community_slug);
+                mkdirSync(dir, { recursive: true });
+            }
+            const created = [];
+            const skipped = [];
+            for (const item of articles) {
+                const slug = item.slug || slugify(item.title);
+                if (!slug) {
+                    skipped.push(`(empty slug from title: "${item.title}")`);
+                    continue;
+                }
+                if (!SLUG_RE.test(slug)) {
+                    skipped.push(`"${item.title}" → invalid slug "${slug}"`);
+                    continue;
+                }
+                const filePath = join(dir, `${slug}.md`);
+                if (existsSync(filePath)) {
+                    skipped.push(`${slug}.md already exists — skipped`);
+                    continue;
+                }
+                const meta = { article_id: slug, title: item.title };
+                if (community_slug)
+                    meta.community_slug = community_slug;
+                if (item.topics && item.topics.length > 0)
+                    meta.topics = item.topics;
+                meta.sources = [];
+                const frontmatter = yamlStringify(meta);
+                const scaffold = `---\n${frontmatter}---\n\n`;
+                writeFileSync(filePath, scaffold, "utf-8");
+                created.push(filePath);
+            }
+            const parts = [
+                created.length > 0 ? `Created ${created.length} file(s):\n${created.map((p) => `  - ${p}`).join("\n")}` : "No new files created.",
+                skipped.length > 0 ? `Skipped:\n${skipped.map((s) => `  - ${s}`).join("\n")}` : "",
+                WRITING_GUIDE,
+            ];
+            return parts.filter(Boolean).join("\n\n");
+        },
+    });
+    server.addTool({
+        name: "publish",
+        description: "Validate and publish articles from your local workspace. " +
+            "Provide specific slugs, or a community_slug to publish all articles in that community folder. " +
+            "Empty-body files become stubs. Dead wikilinks auto-create stubs on the server. " +
+            "Put edit_summary in frontmatter for per-article change descriptions. Requires login.",
+        parameters: z.object({
+            slugs: coerceJson(z.array(z.string()).min(1).max(50)).optional()
+                .describe("Specific article slugs to publish"),
+            community_slug: z.string().optional()
+                .describe("Publish all .md files in this community folder under ~/.openalmanac/articles/"),
+        }),
+        async execute({ slugs, community_slug }) {
+            if (!slugs?.length && !community_slug) {
+                throw new Error("Provide slugs or community_slug (explicit intent required).");
+            }
+            const tasks = [];
+            if (community_slug && !slugs?.length) {
+                if (!SLUG_RE.test(community_slug)) {
+                    throw new Error(`Invalid community_slug "${community_slug}". Must be kebab-case.`);
+                }
+                const dir = join(ARTICLES_DIR, community_slug);
+                if (!existsSync(dir)) {
+                    throw new Error(`Community folder not found: ${dir}`);
+                }
+                const files = readdirSync(dir).filter((f) => f.endsWith(".md") && !f.startsWith("."));
+                if (files.length === 0) {
+                    throw new Error(`No .md files in ${dir}`);
+                }
+                for (const f of files) {
+                    const slug = f.replace(/\.md$/i, "");
+                    tasks.push({ slug, communitySlug: community_slug, ...resolveArticlePaths(slug, community_slug) });
+                }
+            }
+            else if (slugs?.length) {
+                for (const slug of slugs) {
+                    if (!SLUG_RE.test(slug)) {
+                        throw new Error(`Invalid slug "${slug}". Must be kebab-case (e.g. 'machine-learning').`);
+                    }
+                    tasks.push({ slug, ...resolvePublishCandidate(slug, community_slug ?? undefined) });
+                }
+            }
+            const validationLines = [];
+            const validArticles = [];
+            for (const task of tasks) {
+                const raw = readFileSync(task.filePath, "utf-8");
+                const errors = validateArticle(raw);
+                if (errors.length > 0) {
+                    const lines = errors.map((e) => `  ${e.field}: ${e.message}`);
+                    validationLines.push(`FAILED ${task.slug}: Validation failed (${errors.length} error${errors.length > 1 ? "s" : ""}):\n${lines.join("\n")}`);
+                }
+                else {
+                    validArticles.push({ slug: task.slug, markdown: raw });
+                }
+            }
+            const inGui = process.env.OPENALMANAC_GUI === "1";
+            const resultLines = [...validationLines];
+            let okCount = 0;
+            if (validArticles.length > 0) {
+                const resp = await request("POST", "/api/articles/batch-publish", {
+                    auth: true,
+                    json: { articles: validArticles },
+                });
+                const data = (await resp.json());
+                for (const r of data.results) {
+                    if (r.status === "failed") {
+                        resultLines.push(`FAILED ${r.slug}: ${r.error ?? "unknown error"}`);
+                        continue;
+                    }
+                    okCount += 1;
+                    const task = tasks.find((t) => t.slug === r.slug);
+                    if (task) {
+                        try {
+                            unlinkSync(task.filePath);
+                        }
+                        catch (e) {
+                            if (e.code !== "ENOENT") {
+                                resultLines.push(`Note: could not remove local draft for ${r.slug}: ${e.message}`);
+                            }
+                        }
+                        try {
+                            unlinkSync(task.originalPath);
+                        }
+                        catch (e) {
+                            if (e.code !== "ENOENT") {
+                                resultLines.push(`Note: could not remove original copy for ${r.slug}: ${e.message}`);
+                            }
+                        }
+                    }
+                    resultLines.push(`OK ${r.slug}: ${r.status}\n${JSON.stringify(r, null, 2)}`);
+                    if (!inGui && tasks.length === 1 && r.canonical_path) {
+                        const articleUrl = `https://www.openalmanac.org${r.canonical_path}?celebrate=true`;
+                        openBrowser(articleUrl);
+                    }
+                }
+            }
+            const urlHint = inGui
+                ? "\n\nThe article(s) have been published! Let the user know they're live. Do not send them to a web URL."
+                : tasks.length > 1
+                    ? "\n\n(Opening browser skipped for batch publish — share URLs from results above.)"
+                    : "";
+            return `Published ${okCount}/${tasks.length}.\n\n${resultLines.join("\n\n")}${urlHint}`;
+        },
+    });
+    server.addTool({
+        name: "list_articles",
+        description: "Browse a community's wiki articles. Structured listing, not fuzzy search. " +
+            "Use this to see what exists, find stubs to fill, or discover most-referenced gaps.",
+        parameters: z.object({
+            community_slug: z.string().describe("Community slug"),
+            topic: z.string().optional().describe("Filter by topic slug"),
+            sort: z.enum(["recent", "most_referenced"]).default("recent").describe("Sort order"),
+            stubs_only: z.boolean().default(false).describe("Only return stubs"),
+            limit: z.number().min(1).max(200).default(50).describe("Max results (1-200)"),
+        }),
+        async execute({ community_slug, topic, sort, stubs_only, limit }) {
+            const params = { sort, stubs_only, limit };
+            if (topic)
+                params.topic = topic;
+            const resp = await request("GET", `/api/communities/${community_slug}/wiki`, { params });
+            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.`;
+        },
+    });
+}

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,101 @@
+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 to discover communities by topic. 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)"),
+            cover_image_url: z.string().url().optional().describe("Hero/banner image URL. Use search_images to find a compelling image first."),
+            cover_image_position: z.number().min(0).max(100).optional().describe("Vertical focal point of cover image (0=top, 50=center, 100=bottom)"),
+        }),
+        async execute({ name, slug, description, cover_image_url, cover_image_position }) {
+            const json = { name, slug, description };
+            if (cover_image_url)
+                json.cover_image_url = cover_image_url;
+            if (cover_image_position !== undefined)
+                json.cover_image_position = cover_image_position;
+            const resp = await request("POST", "/api/communities", {
+                auth: true,
+                json,
+            });
+            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)}`;
+        },
+    });
+}

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

@@ -20,44 +20,50 @@ function coerceJson(schema) {
     }, schema);
 }
 export function registerResearchTools(server) {
-    // Discriminated union on `source` — each source's schema only surfaces its own
-    // options, so agents get typed autocomplete instead of an opaque options bag.
-    //
-    // Adding a new source (e.g. hackernews) = append another z.object variant with
-    // its own `source: z.literal(...)` and per-source fields. No existing schema
-    // changes.
-    const WebSearchInput = z.object({
-        source: z.literal("web").describe("Generic web search via Google/Serper. Use for general references, news, docs."),
-        query: z.string().min(1).describe("Search terms. Supports quoted phrases and site: operators."),
-        limit: z.number().int().min(1).max(20).default(10).describe("Max results (1-20, default 10)."),
-    });
-    const RedditSearchInput = z.object({
-        source: z.literal("reddit").describe("Search Reddit — use when the user wants community perspectives, subreddit consensus, lived experiences, or ranked-by-engagement content. Goes through a residential proxy so it sees past Reddit's anti-scraping."),
-        subreddit: z.string().optional().describe("Subreddit name without the 'r/' prefix (e.g. 'Harvard'). Omit to search across all of Reddit. Case-insensitive."),
-        query: z.string().optional().describe("Optional full-text search terms. Omit to return the subreddit's sorted listing (top posts of the year, etc.)."),
+    const SearchWebInput = z.object({
+        source: z.enum(["web", "reddit"]).describe("Search source. Use 'web' for Google/Serper and 'reddit' for community perspectives via Reddit."),
+        query: z.string().min(1).optional().describe("Search terms. Required for source='web'. Optional for source='reddit' — omit it there to return a sorted subreddit listing."),
+        subreddit: z.string().optional().describe("Reddit-only. Subreddit name without the 'r/' prefix (e.g. 'Harvard'). Omit to search across all of Reddit."),
         sort: z.enum(["top", "hot", "new", "rising", "controversial", "relevance", "comments"])
-            .default("top")
-            .describe("For listings: 'top'/'hot'/'new'/'rising'/'controversial'. For searches: 'relevance'/'top'/'new'/'comments'. Default 'top'."),
+            .optional()
+            .describe("Reddit-only. Listing/search sort. Defaults to 'top'. Use 'relevance' or 'comments' only when query is present."),
         time_range: z.enum(["hour", "day", "week", "month", "year", "all"])
-            .default("year")
-            .describe("Time window for top/controversial listings and all searches. Default 'year'."),
-        limit: z.number().int().min(1).max(100).default(25).describe("Max posts to return (1-100, default 25)."),
+            .optional()
+            .describe("Reddit-only. Time window for top/controversial listings and all searches. Defaults to 'year'."),
+        limit: z.number().int().min(1).max(100).optional().describe("Result limit. For source='web' defaults to 10 and must be <= 20. For source='reddit' defaults to 25 and can be up to 100."),
+    }).superRefine((input, ctx) => {
+        if (input.source === "web") {
+            if (!input.query?.trim()) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    path: ["query"],
+                    message: "query is required when source='web'",
+                });
+            }
+            if (input.limit !== undefined && input.limit > 20) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    path: ["limit"],
+                    message: "limit must be <= 20 when source='web'",
+                });
+            }
+        }
     });
     server.addTool({
         name: "search_web",
-        description: "Search the web or a specific community source (Reddit). Discriminated on `source`:\n\n" +
+        description: "Search the web or a specific community source (Reddit). Pick the source with the `source` field:\n\n" +
             "- `source: \"web\"` — general web search via Google. Use for news, docs, scholarly references.\n" +
             "- `source: \"reddit\"` — Reddit-aware search returning posts with score, flair, num_comments, permalink. " +
             "Use when the user is asking about community perspectives, subreddit consensus, or 'what do people think about X'.\n\n" +
-            "Each source exposes its own parameters — follow the schema for the source you pick. " +
+            "Use only the fields relevant to the source you pick. " +
             "Rate limit: 10/min. Requires API key.",
-        parameters: z.discriminatedUnion("source", [WebSearchInput, RedditSearchInput]),
+        parameters: SearchWebInput,
         async execute(input) {
             if (input.source === "reddit") {
                 const params = {
-                    sort: input.sort,
-                    time_range: input.time_range,
-                    limit: input.limit,
+                    sort: input.sort ?? "top",
+                    time_range: input.time_range ?? "year",
+                    limit: input.limit ?? 25,
                 };
                 if (input.subreddit)
                     params.subreddit = input.subreddit;
@@ -71,7 +77,7 @@ export function registerResearchTools(server) {
             }
             const resp = await request("GET", "/api/research/search", {
                 auth: true,
-                params: { query: input.query, limit: input.limit },
+                params: { query: input.query.trim(), limit: input.limit ?? 10 },
             });
             return JSON.stringify(await resp.json(), null, 2);
         },

package/dist/tools/topics.js

@@ -46,6 +46,34 @@ export function registerTopicTools(server) {
             return JSON.stringify(await resp.json(), null, 2);
         },
     });
+    server.addTool({
+        name: "update_topic",
+        description: "Update a topic's title, description, or image. Requires wiki moderator role.",
+        parameters: z.object({
+            wiki_slug: z.string().describe("Wiki slug"),
+            topic_slug: z.string().describe("Slug of the topic to update"),
+            title: z.string().optional().describe("New title (also updates slug)"),
+            description: z.string().optional().describe("New description"),
+            image_url: z
+                .string()
+                .url()
+                .max(2048)
+                .nullable()
+                .optional()
+                .describe("Topic image URL (https:// or http://). Pass null to clear."),
+        }),
+        async execute({ wiki_slug, topic_slug, title, description, image_url }) {
+            const body = {};
+            if (title !== undefined)
+                body.title = title;
+            if (description !== undefined)
+                body.description = description;
+            if (image_url !== undefined)
+                body.image_url = image_url;
+            const resp = await request("PATCH", `/api/w/${wiki_slug}/topics/${topic_slug}`, { auth: true, json: body });
+            return JSON.stringify(await resp.json(), null, 2);
+        },
+    });
     server.addTool({
         name: "create_topics_batch",
         description: "Batch create topics in a wiki. Useful for bootstrapping a topic hierarchy. Requires wiki membership.",

package/package.json

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