openalmanac 0.2.34 → 0.2.36

package/dist/tools/articles.js

@@ -2,10 +2,19 @@ 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 { 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
@@ -178,7 +187,14 @@ function findDraftCandidates(slug) {
     catch { /* ignore readdir errors */ }
     return matches;
 }
-function resolvePublishCandidate(slug) {
+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);
@@ -186,7 +202,7 @@ function resolvePublishCandidate(slug) {
     }
     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 from the exact community context.`);
+        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];
 }
@@ -218,235 +234,243 @@ export function registerArticleTools(server) {
             community_slug: z.string().optional().describe("Community slug for reading community-owned wiki articles. Omit for global almanac articles."),
         }),
         async execute({ slugs, community_slug }) {
-            if (community_slug) {
-                const results = await Promise.all(slugs.map(async (slug) => {
-                    const resp = await request("GET", `/api/communities/${community_slug}/wiki/${slug}`);
-                    return await resp.json();
-                }));
-                return JSON.stringify({ results }, null, 2);
-            }
-            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. " +
-            "For community wiki stubs, include community_slug on each stub. " +
-            "Idempotent: existing slugs return their current status. Requires login.",
-        parameters: z.object({
-            stubs: coerceJson(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."),
-                community_slug: z.string().optional().describe("Community slug for community-owned stubs. Omit for global stubs."),
-                topics: z.array(z.string()).optional().describe("Topic slugs for community wiki stubs (e.g. ['techniques', 'tools'])."),
-            })).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 },
-            });
+            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 an article to your local workspace for editing. Global articles are saved to ~/.openalmanac/articles/{slug}.md. " +
-            "Community wiki articles are saved to ~/.openalmanac/articles/{community_slug}/{slug}.md. " +
-            "Returns a writing guide covering article structure, infobox format, citations, and quality rules. " +
-            "After editing, use 'publish' to push your changes live.",
+        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({
-            slug: z.string().describe("Article slug (e.g. 'machine-learning')"),
-            community_slug: z.string().optional().describe("Community slug for downloading a community-owned wiki article. " +
-                "Omit for global almanac articles."),
+            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({ slug, community_slug }) {
-            if (!SLUG_RE.test(slug)) {
-                throw new Error(`Invalid slug "${slug}". Must be kebab-case (e.g. 'machine-learning').`);
+        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 apiPath = community_slug
-                ? `/api/communities/${community_slug}/wiki/${slug}`
-                : `/api/articles/${slug}`;
-            const resp = await request("GET", apiPath, {
-                params: { format: "md" },
-            });
-            const markdown = await resp.text();
+            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();
-            // Community articles go in a subdirectory
-            const { dir, filePath, originalPath } = resolveArticlePaths(slug, community_slug);
-            if (community_slug) {
-                mkdirSync(dir, { recursive: true });
+            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}`);
             }
-            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."
-                : "";
-            return `Downloaded "${title}" to ${filePath}\n${wordCount} words, ${frontmatter.sources?.length ?? 0} sources.${stubNote}\n\n${WRITING_GUIDE}`;
+            return [lines.join("\n"), "", WRITING_GUIDE].join("\n");
         },
     });
     server.addTool({
         name: "new",
-        description: "Create a new article scaffold in your local working directory (~/.openalmanac/articles/). " +
-            "For community wiki articles, provide community_slug and optional topics — the file is saved under " +
-            "~/.openalmanac/articles/{community_slug}/{slug}.md. " +
-            "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.",
+        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({
-            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"),
-            community_slug: z.string().optional().describe("Community slug for community-owned wiki articles (e.g. 'lockpicking'). " +
-                "Omit for global almanac articles."),
-            topics: coerceJson(z.array(z.string()).default([])).describe("Topic slugs for community wiki articles (e.g. ['techniques', 'tools']). " +
-                "Topics are community-specific categories."),
+            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({ slug, title, community_slug, topics }) {
-            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]+)*$`);
-            }
+        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();
-            // Community articles are saved in a subdirectory
             let dir = ARTICLES_DIR;
             if (community_slug) {
                 dir = join(ARTICLES_DIR, community_slug);
                 mkdirSync(dir, { recursive: true });
             }
-            const filePath = join(dir, `${slug}.md`);
-            if (existsSync(filePath)) {
-                throw new Error(`File already exists: ${filePath}\nUse download to refresh it, or publish to push changes.`);
+            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 meta = { article_id: slug, title };
-            if (community_slug)
-                meta.community_slug = community_slug;
-            if (topics && topics.length > 0)
-                meta.topics = topics;
-            meta.sources = [];
-            const frontmatter = yamlStringify(meta);
-            const scaffold = `---\n${frontmatter}---\n\n`;
-            writeFileSync(filePath, scaffold, "utf-8");
-            return `Created ${filePath}\n\n${WRITING_GUIDE}`;
+            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 an article from your local workspace. Reads ~/.openalmanac/articles/{slug}.md or the matching community draft, " +
-            "validates content and sources, and publishes to OpenAlmanac. Requires login.",
+        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({
-            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"),
+            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({ 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 { communitySlug, filePath, originalPath } = resolvePublishCandidate(slug);
-            const raw = readFileSync(filePath, "utf-8");
-            // 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 canonicalPath = typeof data.canonical_path === "string"
-                ? data.canonical_path
-                : communitySlug
-                    ? `/communities/${communitySlug}/wiki/${slug}`
-                    : `/article/${slug}`;
-            const articleUrl = `https://www.openalmanac.org${canonicalPath}?celebrate=true`;
-            const inGui = process.env.OPENALMANAC_GUI === "1";
-            // Skip browser open when running inside the GUI — it handles navigation itself
-            if (!inGui) {
-                openBrowser(articleUrl);
+        async execute({ slugs, community_slug }) {
+            if (!slugs?.length && !community_slug) {
+                throw new Error("Provide slugs or community_slug (explicit intent required).");
             }
-            // Clean up local files after successful publish
-            let cleanupWarning = "";
-            try {
-                unlinkSync(filePath);
+            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) });
+                }
             }
-            catch (e) {
-                if (e.code !== "ENOENT") {
-                    cleanupWarning = `\nNote: could not remove local draft: ${e.message}`;
+            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) });
                 }
             }
-            try {
-                unlinkSync(originalPath);
+            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 });
+                }
             }
-            catch (e) {
-                if (e.code !== "ENOENT") {
-                    cleanupWarning += `\nNote: could not remove original copy: ${e.message}`;
+            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 urlLine = inGui
-                ? "The article has been published! Let the user know it's live. Do not send them to a web URL."
-                : `Article URL (share this exact link with the user): ${articleUrl}`;
-            return `Pushed successfully.\n\n${urlLine}${cleanupWarning}\n\n${JSON.stringify(data, null, 2)}`;
+            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: "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.",
+        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({
-            limit: z.number().default(20).describe("Max results (1-200, default 20)"),
-            offset: z.number().default(0).describe("Pagination offset (default 0)"),
+            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({ limit, offset }) {
-            const resp = await request("GET", "/api/articles/requested", {
-                params: { limit, offset },
-            });
+        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);
         },
     });
@@ -481,61 +505,4 @@ export function registerArticleTools(server) {
             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("."));
-            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})`);
-            }
-            try {
-                const dirs = readdirSync(ARTICLES_DIR).filter((entry) => {
-                    try {
-                        return statSync(join(ARTICLES_DIR, entry)).isDirectory();
-                    }
-                    catch {
-                        return false;
-                    }
-                });
-                for (const communitySlug of dirs) {
-                    const dir = join(ARTICLES_DIR, communitySlug);
-                    const communityFiles = readdirSync(dir).filter((f) => f.endsWith(".md") && !f.startsWith("."));
-                    for (const file of communityFiles) {
-                        const filePath = join(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(`  ${communitySlug}/${file}  —  "${title}"  (${size}, modified ${modified})`);
-                    }
-                }
-            }
-            catch { /* ignore subdir scan errors */ }
-            if (rows.length === 0) {
-                return `${authLine}\n\nLocal articles (0 files in ${ARTICLES_DIR}):\n  (none — use download or new to get started)`;
-            }
-            return `${authLine}\n\nLocal articles (${rows.length} file(s) in ${ARTICLES_DIR}):\n${rows.join("\n")}`;
-        },
-    });
 }

package/dist/tools/communities.js

@@ -1,28 +1,10 @@
 import { z } from "zod";
 import { request } from "../auth.js";
-/**
- * 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);
-}
 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.",
+            "Use this to discover communities by topic. No authentication needed.",
         parameters: z.object({
             query: z
                 .string()
@@ -72,11 +54,18 @@ export function registerCommunityTools(server) {
                 .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 }) {
+        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: { name, slug, description },
+                json,
             });
             const data = (await resp.json());
             const communityUrl = `https://www.openalmanac.org/communities/${slug}`;
@@ -109,37 +98,4 @@ export function registerCommunityTools(server) {
             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: coerceJson(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");
-        },
-    });
 }