openalmanac 0.2.34 → 0.2.35

package/dist/auth.d.ts

@@ -16,7 +16,7 @@ export declare function getAuthStatus(): Promise<AuthStatus>;
 export declare function buildAuthHeaders(): Record<string, string>;
 export declare function request(method: string, path: string, options?: {
     auth?: boolean;
-    params?: Record<string, string | number>;
+    params?: Record<string, string | number | boolean>;
     json?: unknown;
     body?: string;
     contentType?: string;

package/dist/server.js

@@ -47,7 +47,7 @@ export function createServer() {
             "",
             "Your answers should feel like living knowledge — with linked entities and images, not plain text walls.",
             "",
-            "**Entity links:** Before writing your response, call `search_articles` with the key entity names you plan to mention (e.g. `queries: [\"Theravada Buddhism\", \"Thailand\", \"Angkor Wat\"]`). This returns which articles/stubs exist and their slugs. Then use `[[slug|Display Text]]` wikilink syntax in your response for entities that exist. These render as orange links the user can click to navigate. Only link entities that actually exist in the knowledge base — don't guess slugs.",
+            "**Entity links:** Before writing your response, call `search_articles` with the key entity names you plan to mention (e.g. `queries: [\"Theravada Buddhism\", \"Thailand\", \"Angkor Wat\"]`). This returns which articles/stubs exist and their slugs. Then use `[[slug|Display Text]]` wikilink syntax in your response. Published articles preserve wikilinks in storage; dead links auto-create stub articles on publish (community wikis) so round-trip editing stays faithful.",
             "",
             "**Images:** Use `search_images` to find 1-2 relevant images for your response. Include them using the figure syntax: `![Descriptive caption](image_url \"position\")` where position is `right`, `left`, or `center`. Always write a descriptive caption. Use `view_images` to verify candidates before including them.",
             "",
@@ -78,7 +78,7 @@ export function createServer() {
             "",
             'Example: User says "I\'m interested in UX." Don\'t say "Would you like to focus on history, applications, or companies?" Instead, research and say: "So UX was coined by Don Norman at Apple in 1993, but the practice goes back to Henry Dreyfuss in the 1950s designing telephone handsets by measuring thousands of human bodies. There\'s also the dark patterns side — Ryanair\'s checkout flow got studied in academic papers as a case study in hostile design. And there\'s the curb cut effect — features designed for disabled users that end up benefiting everyone. What pulls you?"',
             "",
-            "**User has no topic** → Talk to them. What are they into — a movie they just watched, a hobby, something from work, a place they visited, a news story that caught their eye? Once you have a thread, research it and come back with real information. You can also use requested_articles to find stubs with high demand (many articles link to them), research a few, and share what you find.",
+            "**User has no topic** → Talk to them. What are they into — a movie they just watched, a hobby, something from work, a place they visited, a news story that caught their eye? Once you have a thread, research it and come back with real information. You can also use `list_articles` with `sort: \"most_referenced\"` and `stubs_only: true` on a community wiki to find high-demand stubs.",
             "",
             "**User wants to edit an existing article** → Download it and read it. Look for what's *interesting but underdeveloped* — a one-sentence mention of a controversy probably has a whole story behind it. Share what you find and propose going deeper.",
             "",
@@ -103,7 +103,7 @@ export function createServer() {
             "",
             "3. **Read the writing guidelines** — Fetch https://www.openalmanac.org/writing-guidelines.md and https://www.openalmanac.org/ai-patterns-to-avoid.md before writing a single word.",
             "",
-            "4. **Scaffold** — Use `new` to create the article file. List ALL sources you've gathered in the frontmatter before writing any body text. Don't discard sources — if you read it during research and it's relevant, include it.",
+            "4. **Scaffold** — Use `new` with one or more `{ title, slug?, topics? }` entries. Provide `slug` when you know the canonical ID; otherwise it is auto-derived from the title. For community wikis pass `community_slug`. List ALL sources you've gathered in the frontmatter before writing any body text. Don't discard sources — if you read it during research and it's relevant, include it.",
             "",
             "5. **Write a pure text draft** — This whole process (writing, review, fact-check, images, linking) takes a few minutes. Let the user know in a fun way that they can step away — and that once it's ready, you're happy to discuss any edits or polishing.",
             "",
@@ -114,11 +114,11 @@ export function createServer() {
             "   - **Review agent** → tell it to read https://www.openalmanac.org/review-guidelines.md and review the draft at `~/.openalmanac/articles/{slug}.md`",
             "   - **Fact-check agent** → tell it to read https://www.openalmanac.org/fact-checking-guidelines.md and fact-check the draft at `~/.openalmanac/articles/{slug}.md`",
             "   - **Image agent** → tell it to read https://www.openalmanac.org/image-guidelines.md and find images for the draft at `~/.openalmanac/articles/{slug}.md`",
-            "   - **Linking agent** → tell it to read https://www.openalmanac.org/linking-guidelines.md and create stubs/wikilinks for the draft at `~/.openalmanac/articles/{slug}.md`",
+            "   - **Linking agent** → tell it to read https://www.openalmanac.org/linking-guidelines.md and add wikilinks for the draft at `~/.openalmanac/articles/{slug}.md` (dead links become stubs on publish — no manual `create_stubs` step)",
             "",
             "7. **Integrate** — Present the review and fact-check feedback to the user. Then fix everything in one pass: review issues, fact-check corrections, add images, add wikilinks.",
             "",
-            "8. **Publish** — Validate and publish. Share the exact URL from the publish response (it includes a celebration page). Then search_communities for relevant communities and suggest linking.",
+            "8. **Publish** — Validate and publish (`publish` with `slugs` or `community_slug` to batch). Put per-article change notes in frontmatter as `edit_summary` (maps to the API). Share the exact URL from the publish response when single-article. For community wikis, use `list_articles` to verify coverage.",
             "",
             "Why this order: the draft must be finished before subagents run. The linking agent needs to see what entities are actually in the text. The image agent needs to match images to specific content. The review agent needs the complete article. Everything reads the draft.",
             "",
@@ -126,9 +126,9 @@ export function createServer() {
             "",
             "Reading and searching articles 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.",
             "",
-            "Core flow: login (once) → search_articles (check if exists) → search_web + read_webpage (research) → new (scaffold) or download (existing) → edit ~/.openalmanac/articles/{slug}.md → publish (validate & publish).",
+            "Core flow: login (once) → search_articles (check if exists) → search_web + read_webpage (research) → `new` (batch scaffold, auto slugs) or `download` (batch) → edit files under ~/.openalmanac/articles/ → `publish` (slugs or community_slug for folder batch).",
             "",
-            "After publishing, share the celebration URL. Then call search_communities, suggest relevant ones, and link_article if the user confirms.",
+            "After publishing, share the celebration URL when applicable. Community-owned articles are created under a community path — use `list_articles` to browse a community wiki.",
             "",
             "When working with tool results, write down any important information you might need later, as the original tool result may be cleared.",
         ].join("\n"),

package/dist/setup.js

@@ -6,32 +6,31 @@ import { getAuthStatus } from "./auth.js";
 const TOOL_GROUPS = [
     {
         name: "Search & Read",
-        description: "search articles, download, view status",
+        description: "search, read, download, and browse community wiki articles",
         tools: [
             "mcp__almanac__search_articles",
             "mcp__almanac__download",
             "mcp__almanac__read",
-            "mcp__almanac__status",
-            "mcp__almanac__requested_articles",
+            "mcp__almanac__list_articles",
         ],
     },
     {
         name: "Research",
-        description: "web search, read pages, find images",
+        description: "web search, read pages, register sources, find images",
         tools: [
             "mcp__almanac__search_web",
             "mcp__almanac__read_webpage",
+            "mcp__almanac__register_sources",
             "mcp__almanac__search_images",
             "mcp__almanac__view_images",
         ],
     },
     {
         name: "Write & Publish",
-        description: "create articles, publish edits, stubs",
+        description: "create article drafts and publish edits",
         tools: [
             "mcp__almanac__new",
             "mcp__almanac__publish",
-            "mcp__almanac__create_stubs",
         ],
     },
     {
@@ -41,12 +40,11 @@ const TOOL_GROUPS = [
     },
     {
         name: "Community",
-        description: "communities, posts, article linking",
+        description: "communities and posts",
         tools: [
             "mcp__almanac__search_communities",
             "mcp__almanac__create_community",
             "mcp__almanac__create_post",
-            "mcp__almanac__link_article",
         ],
     },
     {

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");
-        },
-    });
 }

package/dist/tools/research.js

@@ -133,13 +133,13 @@ export function registerResearchTools(server) {
     server.addTool({
         name: "register_sources",
         description: "Register sources you plan to cite in your response. Call this BEFORE writing your response text. " +
-            "Each source becomes a clickable citation bubble when you use [@key] markers in your text. " +
-            "Collect sources from your read_webpage calls and any subagent results, then register them all in one call.",
+            "In GUI explore sessions this updates the source registry used for citation bubbles. " +
+            "Use [@key] markers in your response to cite them.",
         parameters: z.object({
             sources: coerceJson(z.array(z.object({
-                key: z.string().describe("Citation key — kebab-case, BibTeX-style: {domain}-{title-words} (e.g. 'nytimes-climate-report')"),
+                key: z.string().describe("Citation key — kebab-case, BibTeX-style: {domain}-{title-words}"),
                 url: z.string().describe("Source URL"),
-                title: z.string().describe("Source title — include publication name after em dash (e.g. 'Climate Report — The New York Times')"),
+                title: z.string().describe("Source title — include publication name after an em dash when relevant"),
             })).min(1)).describe("Sources to register for citation"),
         }),
         async execute({ sources }) {

package/package.json

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