openalmanac 0.2.24 → 0.2.26

package/dist/server.js

@@ -38,6 +38,18 @@ export function createServer() {
             "",
             "Keep researching throughout. Do not answer from memory when you could search and give a better answer. The user will notice when you stop looking things up.",
             "",
+            "## Enriching your responses",
+            "",
+            "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.",
+            "",
+            "**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.",
+            "",
+            "**Keep it efficient:** Batch your entity and image searches into single tool calls (both accept arrays). One `search_articles` call with 5-10 entity names and one `search_images` call is typical — don't make separate calls for each entity.",
+            "",
+            "**When to skip enrichment:** For short clarifying responses, follow-up questions, or casual conversation, don't search for entities or images. Enrich substantive, informational responses only.",
+            "",
             "### Example — bad (performing enthusiasm):",
             '> "Did you know that Bangkok\'s full name is the longest city name in the world? It\'s fascinating — here are some key findings I\'ve identified about Thailand\'s Hindu influence..."',
             "",
@@ -53,6 +65,8 @@ export function createServer() {
             "",
             "The user is here because they want to dive down rabbit holes and learn about things. The article is the end product — a way to package and share what they learned — not the starting point. The conversation IS the experience. The article comes when there's enough depth and the user wants to share it.",
             "",
+            "**Always start by talking, then research, then talk again.** Don't silently start searching. Acknowledge what the user said, tell them you're going to dig in: \"That's a really interesting area — let me do some research and then let's explore this together.\" Then research, then come back and TALK about what you found. Share the interesting parts, the surprising details, the different angles. The user should feel like you're exploring together, not like you disappeared into a factory. This applies even if the user explicitly says \"write an article\" — the exploration comes first.",
+            "",
             "**Do not suggest writing an article on the first turn, or even the first few turns.** Your job at the start is to explore the topic — research it, share what you find, follow the user's questions. The exploration itself is what makes them want to keep going. Only after you've gone deep enough and specific subjects have come into focus should you propose an article. If you suggest it too early, it feels like being funneled into a workflow. Don't mention articles every turn either — suggest once, and if the user doesn't bite, keep exploring.",
             "",
             '**User has a broad interest** ("UX design", "religion in Thailand") → Don\'t ask "what angle do you want?" — research it and come back with real information about different directions. Give enough specific detail about each direction that the user can feel which one pulls them. Then follow their curiosity deeper.',
@@ -61,7 +75,7 @@ export function createServer() {
             "",
             "**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 wants to edit an existing article** → Pull 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.",
+            "**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.",
             "",
             '**Articles emerge from research naturally.** As you research and talk, specific subjects will come into focus — a person with a fascinating story, a place with layers of history, a concept that deserves its own explanation. When you notice one of these has enough depth, say so: "the Erawan Shrine could be its own article" or "Wirathu is worth writing up." A single research conversation might produce one article or several. The conversation itself can go anywhere — opinions, tangents, speculation are all fine while talking. The articles that come out of it are encyclopedic: neutral, factual, sourced.',
             "",
@@ -97,7 +111,7 @@ export function createServer() {
             "",
             "6. **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.",
             "",
-            "7. **Push** — Validate and publish. Share the exact URL from the push response (it includes a celebration page). Then search_communities for relevant communities and suggest linking.",
+            "7. **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.",
             "",
             "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.",
             "",
@@ -105,7 +119,7 @@ export function createServer() {
             "",
             "Reading and searching articles is open. Writing requires an API key (from login). Login registers an agent linked to your human user, so contributions are attributed to both.",
             "",
-            "Core flow: login (once) → search_articles (check if exists) → search_web + read_webpage (research) → new (scaffold) or pull (download existing) → edit ~/.openalmanac/articles/{slug}.md → push (validate & publish).",
+            "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).",
             "",
             "After publishing, share the celebration URL. Then call search_communities, suggest relevant ones, and link_article if the user confirms.",
             "",

package/dist/setup.js

@@ -6,10 +6,11 @@ import { getAuthStatus } from "./auth.js";
 const TOOL_GROUPS = [
     {
         name: "Search & Read",
-        description: "search articles, pull, view status",
+        description: "search articles, download, view status",
         tools: [
             "mcp__almanac__search_articles",
-            "mcp__almanac__pull",
+            "mcp__almanac__download",
+            "mcp__almanac__read",
             "mcp__almanac__status",
             "mcp__almanac__requested_articles",
         ],
@@ -21,16 +22,16 @@ const TOOL_GROUPS = [
             "mcp__almanac__search_web",
             "mcp__almanac__read_webpage",
             "mcp__almanac__search_images",
-            "mcp__almanac__view_image",
+            "mcp__almanac__view_images",
         ],
     },
     {
         name: "Write & Publish",
-        description: "create articles, push edits, stubs",
+        description: "create articles, publish edits, stubs",
         tools: [
             "mcp__almanac__new",
-            "mcp__almanac__push",
-            "mcp__almanac__create_stub",
+            "mcp__almanac__publish",
+            "mcp__almanac__create_stubs",
         ],
     },
     {

package/dist/tools/articles.js

@@ -106,7 +106,7 @@ The early life of Alan Turing began...
 **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 push — no extra steps needed.
+External image URLs are auto-persisted on publish — no extra steps needed.
 
 ## Writing quality
 
@@ -124,84 +124,81 @@ function ensureArticlesDir() {
 export function registerArticleTools(server) {
     server.addTool({
         name: "search_articles",
-        description: "Search existing OpenAlmanac articles and stubs. Use this to check if an article or stub already exists before creating one. " +
-            "Results include a 'stub' field (true/false) and 'entity_type' field. No authentication needed.",
+        description: "Search existing OpenAlmanac articles and stubs. Accepts multiple queries for batch lookup. " +
+            "Use this to check if articles or stubs exist before creating them, or to find entity slugs for wikilinks. " +
+            "Results include 'stub' field (true/false) and 'entity_type' field. No authentication needed.",
         parameters: z.object({
-            query: z.string().describe("Search terms"),
-            limit: z.number().default(10).describe("Max results (1-100, default 10)"),
-            page: z.number().default(1).describe("Page number, 1-indexed (default 1)"),
+            queries: z.array(z.string()).min(1).max(20).describe("Search queries (1-20)"),
+            limit: z.number().default(5).describe("Max results per query (1-50, default 5)"),
             include_stubs: z.boolean().default(true).describe("Include stub articles in results (default true)"),
         }),
-        async execute({ query, limit, page, include_stubs }) {
-            const params = { query, limit, page };
-            if (!include_stubs)
-                params.include_stubs = "false";
-            const resp = await request("GET", "/api/search", { params });
+        async execute({ queries, limit, include_stubs }) {
+            const resp = await request("POST", "/api/search/batch", {
+                json: { queries, limit, include_stubs },
+            });
             return JSON.stringify(await resp.json(), null, 2);
         },
     });
     server.addTool({
-        name: "create_stub",
-        description: "Create a stub article — a placeholder for an entity that doesn't have a full article yet. " +
-            "Use this for every entity (person, organization, topic, etc.) you mention in an article. " +
-            "Stubs should include a meaningful summary and headline. " +
-            "Idempotent: if the slug already exists, returns the existing article/stub. Requires login.",
+        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({
-            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().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."),
+            slugs: z.array(z.string()).min(1).max(20).describe("Article slugs to read (1-20)"),
         }),
-        async execute({ slug, title, entity_type, headline, image_url, summary }) {
-            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]+)*$`);
-            }
-            const json = { slug, title };
-            if (entity_type)
-                json.entity_type = entity_type;
-            if (headline)
-                json.headline = headline;
-            if (image_url)
-                json.image_url = image_url;
-            if (summary)
-                json.summary = summary;
-            const resp = await request("POST", "/api/articles/stub", {
+        async execute({ slugs }) {
+            const resp = await request("POST", "/api/articles/batch", {
+                json: { slugs },
+            });
+            return JSON.stringify(await resp.json(), null, 2);
+        },
+    });
+    server.addTool({
+        name: "create_stubs",
+        description: "Create stub articles — placeholders for entities that don't have full articles yet. " +
+            "Use this for every entity (person, organization, topic, etc.) mentioned in an article. " +
+            "Idempotent: existing slugs return their current status. Requires login.",
+        parameters: z.object({
+            stubs: z.array(z.object({
+                slug: z
+                    .string()
+                    .min(1)
+                    .max(500)
+                    .describe("Unique kebab-case identifier. For people with LinkedIn: use their vanity ID (e.g. 'john-smith-4a8b2c1'). " +
+                    "For others: descriptive kebab-case (e.g. 'reinforcement-learning', 'openai')"),
+                title: z.string().describe("Display title (e.g. 'John Smith', 'Reinforcement Learning')"),
+                entity_type: z
+                    .enum(["person", "organization", "topic", "event", "creative_work", "place"])
+                    .optional()
+                    .describe("Entity type: 'person' for individuals, 'organization' for companies/institutions/nonprofits, " +
+                    "'topic' for concepts/fields/technologies, 'event' for conferences/historical events, " +
+                    "'creative_work' for books/papers/films/software, 'place' for cities/countries/landmarks"),
+                headline: z
+                    .string()
+                    .optional()
+                    .describe("Short headline (e.g. 'Professor of CS at MIT', 'AI research laboratory')"),
+                image_url: z.string().url().optional().describe("Image URL for the entity"),
+                summary: z
+                    .string()
+                    .optional()
+                    .describe("2-4 sentence summary of the entity. This becomes the stub page content. " +
+                    "Be informative — include key facts, dates, and context."),
+            })).min(1).max(50).describe("Stubs to create (1-50)"),
+        }),
+        async execute({ stubs }) {
+            const resp = await request("POST", "/api/articles/stubs", {
                 auth: true,
-                json,
+                json: { stubs },
             });
-            const data = (await resp.json());
-            const statusMsg = data.status === "created"
-                ? "Stub created."
-                : data.status === "stub_exists"
-                    ? "Stub already exists."
-                    : "Full article already exists.";
-            return `${statusMsg} Slug: ${slug}\nUse [[${slug}|${title}]] to link to this entity.\n\n${JSON.stringify(data, null, 2)}`;
+            return JSON.stringify(await resp.json(), null, 2);
         },
     });
     server.addTool({
-        name: "pull",
-        description: "Download an article from OpenAlmanac to your local working directory (~/.openalmanac/articles/). " +
-            "The file is saved as {slug}.md with YAML frontmatter. Returns a writing guide covering article structure, infobox format, citations, and quality rules. " +
-            "Edit the file locally, then use push to publish changes.",
+        name: "download",
+        description: "Download an article to your local workspace for editing. The file is saved to ~/.openalmanac/articles/{slug}.md " +
+            "with YAML frontmatter. Returns a writing guide covering article structure, infobox format, citations, and quality rules. " +
+            "After editing, use 'publish' to push your changes live.",
         parameters: z.object({
             slug: z.string().describe("Article slug (e.g. 'machine-learning')"),
         }),
@@ -228,7 +225,7 @@ export function registerArticleTools(server) {
         name: "new",
         description: "Create a new article scaffold in your local working directory (~/.openalmanac/articles/). " +
             "The file is created with YAML frontmatter and an empty body. Returns a writing guide covering article structure, infobox format, citations, and quality rules. " +
-            "Edit the file to add content and sources, then use push to publish.",
+            "Edit the file to add content and sources, then use publish to go live.",
         parameters: z.object({
             slug: z
                 .string()
@@ -242,7 +239,7 @@ export function registerArticleTools(server) {
             ensureArticlesDir();
             const filePath = join(ARTICLES_DIR, `${slug}.md`);
             if (existsSync(filePath)) {
-                throw new Error(`File already exists: ${filePath}\nUse pull to refresh it, or push to publish changes.`);
+                throw new Error(`File already exists: ${filePath}\nUse download to refresh it, or publish to push changes.`);
             }
             const frontmatter = yamlStringify({ article_id: slug, title, sources: [] });
             const scaffold = `---\n${frontmatter}---\n\n`;
@@ -251,9 +248,9 @@ export function registerArticleTools(server) {
         },
     });
     server.addTool({
-        name: "push",
-        description: "Validate and publish a local article to OpenAlmanac. Reads the file from ~/.openalmanac/articles/{slug}.md, " +
-            "validates locally (frontmatter, citations, sources), then pushes via the API. Requires login.",
+        name: "publish",
+        description: "Validate and publish an article from your local workspace. Reads ~/.openalmanac/articles/{slug}.md, " +
+            "validates content and sources, and publishes to OpenAlmanac. Requires login.",
         parameters: z.object({
             slug: z.string().describe("Article slug matching the filename (without .md)"),
             change_title: z.string().optional().describe("Short title for the change (e.g. 'Added early life section')"),
@@ -266,7 +263,7 @@ export function registerArticleTools(server) {
                 raw = readFileSync(filePath, "utf-8");
             }
             catch {
-                throw new Error(`File not found: ${filePath}\nUse pull to download an existing article or new to create a scaffold.`);
+                throw new Error(`File not found: ${filePath}\nUse download to get an existing article or new to create a scaffold.`);
             }
             // Local validation
             const errors = validateArticle(raw);
@@ -323,7 +320,7 @@ export function registerArticleTools(server) {
                 : "Not logged in. Use login to authenticate.";
             const files = readdirSync(ARTICLES_DIR).filter((f) => f.endsWith(".md"));
             if (files.length === 0) {
-                return `${authLine}\n\nLocal articles (0 files in ${ARTICLES_DIR}):\n  (none — use pull or new to get started)`;
+                return `${authLine}\n\nLocal articles (0 files in ${ARTICLES_DIR}):\n  (none — use download or new to get started)`;
             }
             const rows = [];
             for (const file of files) {

package/dist/tools/research.js

@@ -43,10 +43,10 @@ export function registerResearchTools(server) {
     });
     server.addTool({
         name: "search_images",
-        description: "Search for images to include in articles. Returns image URLs, titles, dimensions, and licensing info. " +
+        description: "Search for images to include in articles. Accepts multiple queries for batch lookup. Returns image URLs, titles, dimensions, and licensing info. " +
             "Two sources: 'wikimedia' (free, open-licensed images from Wikimedia Commons — preferred) and 'google' (broader web images via Google). " +
-            "Use descriptive search terms. After searching, call view_image on promising candidates to see what they actually show before using them. " +
-            "External image URLs are automatically persisted when you push the article — no extra steps needed.\n\n" +
+            "Use descriptive search terms. After searching, call view_images on promising candidates to see what they actually show before using them. " +
+            "External image URLs are automatically persisted when you publish the article — no extra steps needed.\n\n" +
             "## Using images in articles\n\n" +
             "Images render as figures with visible captions. The alt text becomes the caption — make it descriptive.\n\n" +
             "**Syntax:** `![Caption text](url \"position\")`\n\n" +
@@ -70,37 +70,46 @@ export function registerResearchTools(server) {
             "- For the infobox hero image, set `infobox.header.image_url` in frontmatter instead\n\n" +
             "Requires login. Rate limit: 10/min.",
         parameters: z.object({
-            query: z.string().describe("Descriptive search terms for the image (e.g. 'Apollo 11 moon landing photograph')"),
+            queries: z.array(z.string()).min(1).max(10).describe("Image search queries (1-10)"),
             source: z.enum(["wikimedia", "google"]).default("wikimedia").describe("Image source: 'wikimedia' (free, open-licensed — preferred) or 'google' (broader coverage)"),
-            limit: z.number().default(10).describe("Max results (1-30, default 10)"),
+            limit: z.number().default(5).describe("Max results per query (1-10, default 5)"),
         }),
-        async execute({ query, source, limit }) {
-            const resp = await request("GET", "/api/research/images", {
+        async execute({ queries, source, limit }) {
+            const resp = await request("POST", "/api/research/images/batch", {
                 auth: true,
-                params: { query, source, limit },
+                json: { queries, source, limit },
             });
             return JSON.stringify(await resp.json(), null, 2);
         },
     });
     server.addTool({
-        name: "view_image",
-        description: "View an image to verify it's suitable for an article. Use after search_images to inspect candidate images " +
-            "before including them. Returns the image so you can see what it actually shows and write an accurate caption.",
+        name: "view_images",
+        description: "View images to verify they're suitable. Use after search_images to inspect candidates " +
+            "before including them. Returns each image so you can see what it shows and write accurate captions.",
         parameters: z.object({
-            url: z.string().url().describe("Image URL to view (use image_url or thumbnail_url from search_images results)"),
+            urls: z.array(z.string().url()).min(1).max(10).describe("Image URLs to view (1-10)"),
         }),
-        async execute({ url }) {
-            try {
-                return {
-                    content: [
-                        await imageContent({ url }),
-                        { type: "text", text: `Image URL: ${url}` },
-                    ],
-                };
-            }
-            catch {
-                return `Failed to fetch image from ${url}. The URL may be invalid, inaccessible, or not an image.`;
+        async execute({ urls }) {
+            const results = await Promise.allSettled(urls.map(async (url) => {
+                try {
+                    return { url, image: await imageContent({ url }) };
+                }
+                catch {
+                    return { url, error: `Failed to fetch image from ${url}` };
+                }
+            }));
+            const content = [];
+            for (const result of results) {
+                const val = result.status === "fulfilled" ? result.value : { url: "unknown", error: "Failed" };
+                if ("image" in val) {
+                    content.push(val.image);
+                    content.push({ type: "text", text: `Image URL: ${val.url}` });
+                }
+                else {
+                    content.push({ type: "text", text: val.error });
+                }
             }
+            return { content };
         },
     });
 }

package/package.json

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