openalmanac 0.3.5 → 0.4.0

package/dist/tools/pages.js

@@ -2,34 +2,12 @@ import { z } from "zod";
 import { readFileSync, writeFileSync, mkdirSync, readdirSync, existsSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
 import { stringify as yamlStringify } from "yaml";
-import { request, ARTICLES_DIR } from "../auth.js";
-import { validateArticle } from "../validate.js";
+import { request, PAGES_DIR } from "../auth.js";
 import { openBrowser } from "../browser.js";
+import { coerceJson } from "../utils.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, "-");
-}
-function coerceJson(schema) {
-    return z.preprocess((val) => {
-        if (typeof val === "string") {
-            try {
-                return JSON.parse(val);
-            }
-            catch {
-                return val;
-            }
-        }
-        return val;
-    }, schema);
-}
 function resolvePageDir(wikiSlug) {
-    return join(ARTICLES_DIR, wikiSlug);
+    return join(PAGES_DIR, wikiSlug);
 }
 function resolvePagePaths(slug, wikiSlug) {
     const dir = resolvePageDir(wikiSlug);
@@ -76,14 +54,118 @@ Page body with [@key] citation markers and [[wikilinks]]...
 - Keys must be kebab-case with at least one hyphen
 - Every source must be referenced; every reference must have a source
 
+## Quoting
+
+For any string value with punctuation, quotes, or special characters (common in \`sources[].title\`), use YAML block-literal syntax:
+
+\`\`\`yaml
+sources:
+  - key: farza-yc
+    title: |-
+      "I'm joining Y Combinator, again" — Farza Majeed
+    url: https://...
+\`\`\`
+
+This sidesteps every YAML escaping rule. If you skip this, inner double quotes or em-dashes will break the parser.
+
 ## Images
 
 Use search_images to find relevant images. Syntax: \`![Caption](url "position")\`
 Positions: "right" (default), "left", "center". Every image needs a descriptive caption.
 `.trim();
+function formatPublishResults(results, targetSlugs, wiki_slug, dry_run) {
+    const allAutoStubs = new Set();
+    const lines = [];
+    let okCount = 0;
+    let errorCount = 0;
+    for (let i = 0; i < results.length; i++) {
+        const r = results[i];
+        const slug = targetSlugs[i] ?? r.slug;
+        if (dry_run && r.plan) {
+            const plan = r.plan;
+            const hasError = plan.validation.status === "failed" ||
+                !plan.authorization.can_write ||
+                plan.action === "error";
+            if (hasError) {
+                errorCount++;
+                const reasons = [];
+                for (const e of plan.validation.errors) {
+                    reasons.push(`${e.field}: ${e.message}`);
+                }
+                if (!plan.authorization.can_write && plan.authorization.reason) {
+                    reasons.push(`auth: ${plan.authorization.reason}`);
+                }
+                lines.push(`- ${slug}: **error** — ${reasons.join("; ")}`);
+            }
+            else {
+                okCount++;
+                let line = `- ${plan.slug}: **${plan.action}**`;
+                if (plan.renamed_from)
+                    line += ` (rename: ${plan.renamed_from} → ${plan.slug})`;
+                const details = [];
+                if (plan.source_keys.referenced.length > 0) {
+                    details.push(`${plan.source_keys.referenced.length} source(s)`);
+                }
+                if (plan.wikilinks.will_auto_stub.length > 0) {
+                    details.push(`${plan.wikilinks.will_auto_stub.length} new stub(s)`);
+                    plan.wikilinks.will_auto_stub.forEach(s => allAutoStubs.add(s));
+                }
+                const inBatchLinks = plan.wikilinks.in_batch ?? [];
+                if (inBatchLinks.length > 0) {
+                    details.push(`${inBatchLinks.length} in-batch link(s)`);
+                }
+                if (plan.source_keys.orphaned.length > 0) {
+                    details.push(`missing source key(s): ${plan.source_keys.orphaned.join(", ")}`);
+                }
+                if (plan.source_keys.unreferenced.length > 0) {
+                    details.push(`unreferenced source(s): ${plan.source_keys.unreferenced.join(", ")}`);
+                }
+                if (details.length > 0)
+                    line += ` (${details.join(", ")})`;
+                lines.push(line);
+            }
+        }
+        else {
+            // Real publish result
+            if (r.status === "error") {
+                errorCount++;
+                lines.push(`- ${r.slug}: **error** — ${r.error}`);
+            }
+            else {
+                okCount++;
+                // Clean up local files — pre-rename slug names the file
+                const fileSlug = r.renamed_from ?? slug;
+                const { filePath, refPath } = resolvePagePaths(fileSlug, wiki_slug);
+                try {
+                    unlinkSync(filePath);
+                }
+                catch { /* ok */ }
+                try {
+                    unlinkSync(refPath);
+                }
+                catch { /* ok */ }
+                let line = `- ${r.slug}: **${r.status}**`;
+                if (r.renamed_from)
+                    line += ` (renamed from ${r.renamed_from})`;
+                if (r.stubs_created?.length) {
+                    r.stubs_created.forEach(s => allAutoStubs.add(s));
+                }
+                lines.push(line);
+            }
+        }
+    }
+    const verb = dry_run ? "Dry-run" : "Published";
+    const summary = `${verb}: ${okCount}/${targetSlugs.length} OK${errorCount > 0 ? `, ${errorCount} error(s)` : ""}.`;
+    const parts = [summary, "", ...lines];
+    if (allAutoStubs.size > 0) {
+        const stubVerb = dry_run ? "Stubs that will be auto-created" : "Stubs auto-created";
+        parts.push("", `${stubVerb}: ${[...allAutoStubs].join(", ")}`);
+    }
+    return parts.join("\n");
+}
 export function registerPageTools(server) {
     server.addTool({
-        name: "search_articles",
+        name: "search_pages",
         description: "Search OpenAlmanac pages and stubs across all wikis. Use to check existence, find slugs for wikilinks, " +
             "or discover content. Optional wiki filter to scope results. No authentication needed.",
         parameters: z.object({
@@ -135,7 +217,7 @@ export function registerPageTools(server) {
         },
     });
     server.addTool({
-        name: "list_articles",
+        name: "list_pages",
         description: "Browse pages in a wiki. Structured listing, not fuzzy search. " +
             "Use to see what exists, find stubs, or discover pages by topic. " +
             "Each returned page includes topic objects with both slug and title.",
@@ -159,7 +241,7 @@ export function registerPageTools(server) {
     server.addTool({
         name: "download",
         description: "Download pages to your local workspace for editing. " +
-            "Files go to ~/.openalmanac/articles/{wiki_slug}/{slug}.md with a .ref sidecar. " +
+            "Files go to ~/.openalmanac/pages/{wiki_slug}/{slug}.md with a .ref sidecar. " +
             "After editing, use publish to push changes. The .ref file is system-managed — don't edit it.",
         parameters: z.object({
             slugs: coerceJson(z.array(z.string()).min(1).max(50)).describe("Page slugs to download"),
@@ -187,11 +269,19 @@ export function registerPageTools(server) {
     server.addTool({
         name: "new",
         description: "Scaffold new pages locally. Creates .md files with YAML frontmatter and empty bodies. " +
-            "No .ref file is created (new pages). After writing content, use publish to go live.",
+            "No .ref file is created (new pages). After writing content, use publish to go live.\n\n" +
+            "Passing `slug` is an identity claim, not just a filename hint. The server will honor it " +
+            "at publish time instead of deriving a slug from the title. " +
+            "If no slug is provided, the server derives the slug from the title at publish.\n\n" +
+            "To edit the auto-generated main-page created by create_wiki, do NOT use `new` — " +
+            "use `download` with slug `main-page` to get the page and its ref token, then edit and publish. " +
+            "Publishing without a ref token is a create operation and will fail with a slug collision " +
+            "because main-page already exists.",
         parameters: z.object({
             pages: coerceJson(z.array(z.object({
                 title: z.string().describe("Page title"),
-                slug: z.string().optional().describe("Optional explicit slug"),
+                slug: z.string().optional().describe("Optional explicit slug (kebab-case). When provided, the server uses this slug " +
+                    "at publish instead of deriving one from the title."),
                 topics: z.array(z.string()).optional().describe("Topic slugs"),
             })).min(1).max(50)).describe("Pages to scaffold"),
             wiki_slug: z.string().describe("Wiki slug"),
@@ -202,17 +292,37 @@ export function registerPageTools(server) {
             const created = [];
             const skipped = [];
             for (const item of pages) {
-                const slug = item.slug || slugify(item.title);
-                if (!slug || !SLUG_RE.test(slug)) {
-                    skipped.push(`"${item.title}" → invalid slug "${slug}"`);
-                    continue;
+                // If an explicit slug is provided, validate it and use it for the filename.
+                // If none is provided, derive a simple filename from the title for local
+                // convenience only — the server will derive the authoritative slug from
+                // the title at publish time.
+                let fileSlug;
+                if (item.slug) {
+                    if (!SLUG_RE.test(item.slug)) {
+                        skipped.push(`"${item.title}" → invalid slug "${item.slug}"`);
+                        continue;
+                    }
+                    fileSlug = item.slug;
+                }
+                else {
+                    // Local filename only — server derives from title at publish.
+                    fileSlug = item.title
+                        .toLowerCase()
+                        .replace(/[^a-z0-9]+/g, "-")
+                        .replace(/^-+|-+$/g, "")
+                        .replace(/-{2,}/g, "-") || "untitled";
                 }
-                const filePath = join(dir, `${slug}.md`);
+                const filePath = join(dir, `${fileSlug}.md`);
                 if (existsSync(filePath)) {
-                    skipped.push(`${slug}.md already exists`);
+                    skipped.push(`${fileSlug}.md already exists`);
                     continue;
                 }
                 const meta = { title: item.title, wiki: wiki_slug };
+                // Embed explicit slug in frontmatter so the server binds it at publish.
+                // Without this, changing the title would change the slug; with it, the
+                // server uses this slug regardless of the title's derived form.
+                if (item.slug)
+                    meta.slug = item.slug;
                 if (item.topics?.length)
                     meta.topics = item.topics;
                 meta.sources = [];
@@ -220,9 +330,28 @@ export function registerPageTools(server) {
                 writeFileSync(filePath, `---\n${frontmatter}---\n\n`, "utf-8");
                 created.push(filePath);
             }
+            // Scaffold-time nudge: check if any created pages have matching slugs
+            // in the global wiki (Almanac). Fires before writing so the agent can
+            // decide to cross-link instead of writing a duplicate treatment.
+            const nudges = [];
+            if (created.length > 0 && wiki_slug !== "global") {
+                const createdSlugs = created.map(p => p.split("/").pop().replace(".md", ""));
+                for (const slug of createdSlugs) {
+                    try {
+                        const res = await request("GET", `/api/w/global/pages/${slug}`);
+                        if (res.ok) {
+                            const page = await res.json();
+                            nudges.push(`Note: Almanac already has a page "${page.title ?? slug}" (slug: ${slug}). ` +
+                                `Write your own treatment for this wiki, or cross-link with [[global:${slug}]] instead.`);
+                        }
+                    }
+                    catch { /* page doesn't exist in global wiki — no nudge */ }
+                }
+            }
             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")}` : "",
+                nudges.length > 0 ? nudges.join("\n") : "",
                 WRITING_GUIDE,
             ];
             return parts.filter(Boolean).join("\n\n");
@@ -232,13 +361,19 @@ export function registerPageTools(server) {
         name: "publish",
         description: "Publish pages from your local workspace. Reads .md files and their .ref sidecars, " +
             "sends to the API. Pages with .ref are updates; pages without are new. " +
-            "Dead wikilinks auto-create stubs. Put edit_summary in frontmatter for change descriptions. Requires login.",
+            "Dead wikilinks auto-create stubs. Put edit_summary in frontmatter for change descriptions. Requires login.\n\n" +
+            "Set dry_run=true to plan without committing: the backend validates frontmatter, checks authorization, " +
+            "resolves wikilinks, cross-checks citation keys, and detects renames — all read-only. " +
+            "Caveats: plan reflects state at time of check — permissions and slug availability may change before real publish. " +
+            "Rename detection shows the slug derived from the current title; subsequent title edits can change this.",
         parameters: z.object({
             slugs: coerceJson(z.array(z.string()).min(1).max(50)).optional()
                 .describe("Specific page slugs to publish"),
             wiki_slug: z.string().describe("Wiki slug"),
+            dry_run: z.boolean().default(false).optional()
+                .describe("When true, plan all pages without committing any changes"),
         }),
-        async execute({ slugs, wiki_slug }) {
+        async execute({ slugs, wiki_slug, dry_run }) {
             const dir = resolvePageDir(wiki_slug);
             // Determine which files to publish
             let targetSlugs;
@@ -262,95 +397,73 @@ export function registerPageTools(server) {
                     throw new Error(`File not found: ${filePath}`);
                 }
                 const content = readFileSync(filePath, "utf-8");
-                const errors = validateArticle(content);
-                if (errors.length > 0) {
-                    throw new Error(`Validation failed for ${slug}:\n${errors.map(e => `  ${e.field}: ${e.message}`).join("\n")}`);
-                }
                 const ref = existsSync(refPath) ? readFileSync(refPath, "utf-8").trim() : null;
                 pages.push({ content, ref });
             }
-            const resp = await request("POST", `/api/w/${wiki_slug}/publish`, {
+            const endpoint = dry_run
+                ? `/api/w/${wiki_slug}/publish?dry_run=true`
+                : `/api/w/${wiki_slug}/publish`;
+            const resp = await request("POST", endpoint, {
                 auth: true,
                 json: { pages },
             });
             const results = (await resp.json());
-            // Clean up local files for successful publishes
-            const lines = [];
-            let okCount = 0;
-            for (const r of results) {
-                if (r.status === "error") {
-                    lines.push(`FAILED ${r.slug}: ${r.error}`);
-                    continue;
-                }
-                okCount++;
-                // The local file was named with the pre-rename slug. The server returns
-                // `renamed_from` on rename so we can clean up the right file without
-                // relying on request/response index parity.
-                const published_slug = r.renamed_from ?? r.slug;
-                const { filePath, refPath } = resolvePagePaths(published_slug, wiki_slug);
-                try {
-                    unlinkSync(filePath);
-                }
-                catch { /* ok */ }
-                try {
-                    unlinkSync(refPath);
-                }
-                catch { /* ok */ }
-                let detail = `OK ${r.slug}: ${r.status}`;
-                if (r.renamed_from)
-                    detail += ` (renamed from ${r.renamed_from})`;
-                if (r.stubs_created?.length)
-                    detail += `\n  Stubs created: ${r.stubs_created.join(", ")}`;
-                lines.push(detail);
-                // Open browser for single publish
-                if (targetSlugs.length === 1 && process.env.OPENALMANAC_GUI !== "1") {
+            const summary = formatPublishResults(results, targetSlugs, wiki_slug, dry_run ?? false);
+            // Open browser on single-page publish success (non-GUI, non-dry-run).
+            if (!dry_run && targetSlugs.length === 1 && process.env.OPENALMANAC_GUI !== "1") {
+                const r = results[0];
+                if (r && r.status !== "error") {
+                    const resultSlug = r.slug;
                     const url = wiki_slug === "global"
-                        ? `https://www.openalmanac.org/page/${r.slug}?celebrate=true`
-                        : `https://www.openalmanac.org/w/${wiki_slug}/${r.slug}?celebrate=true`;
+                        ? `https://www.openalmanac.org/page/${resultSlug}?celebrate=true`
+                        : `https://www.openalmanac.org/w/${wiki_slug}/${resultSlug}?celebrate=true`;
                     openBrowser(url);
                 }
             }
-            return `Published ${okCount}/${targetSlugs.length}.\n\n${lines.join("\n\n")}`;
+            return summary;
         },
     });
     server.addTool({
-        name: "propose_article",
-        description: "Propose an article before writing it. Structures your proposal with a user-facing summary and a detailed brief. " +
-            "Do not start writing without proposing first.",
+        name: "read_page",
+        description: "Read a single page by slug. Returns the full page JSON including content, topics, sources, and infobox. " +
+            "No side effects — use this to read a page without downloading it to disk or joining the wiki. " +
+            "For editing, use `download` instead (it writes local files and handles ref tokens). " +
+            "For discovery, use `search_pages` instead. No authentication needed.",
         parameters: z.object({
-            summary: z.string().describe("User-facing summary (3-5 bullet points)"),
-            details: z.string().describe("Full handoff brief with all sources, key facts, angle"),
-            title: z.string().describe("Proposed title"),
-            slug: z.string().describe("Proposed slug (kebab-case)"),
-            wiki_slug: z.string().default("global").describe("Wiki slug"),
-            _userChoice: z.enum(["background", "here", "expired", "already_in_progress"]).optional(),
+            wiki_slug: z.string().describe("Wiki slug"),
+            page_slug: z.string().describe("Page slug"),
         }),
-        async execute({ summary, details, title, slug, wiki_slug, _userChoice }) {
-            if (_userChoice === "background") {
-                return `Article "${title}" is now being written in a background process.`;
-            }
-            if (_userChoice === "expired") {
-                return `Proposal expired. Continue the conversation naturally.`;
-            }
-            if (_userChoice === "already_in_progress") {
-                return `Article "${title}" is already being generated.`;
-            }
-            return `Article Proposal: ${title}\n\n${summary}\n\nProceed with writing this article following the writing flow in your instructions.`;
+        async execute({ wiki_slug, page_slug }) {
+            const resp = await request("GET", `/api/w/${wiki_slug}/pages/${page_slug}`);
+            return JSON.stringify(await resp.json(), null, 2);
         },
     });
     server.addTool({
-        name: "resolve",
-        description: "Check if pages exist before writing wikilinks. Returns status (found/stub/not_found) for each target. " +
-            "Use this to verify links before publishing.",
+        name: "delete_pages",
+        description: "⚠️ Permanently deletes pages. Cannot be undone. Confirm with user before calling. " +
+            "Accepts multiple slugs and deletes them in sequence. Requires moderator or creator access.",
         parameters: z.object({
             wiki_slug: z.string().describe("Wiki slug"),
-            targets: coerceJson(z.array(z.string()).min(1).max(50)).describe("Link targets to resolve"),
+            page_slugs: coerceJson(z.array(z.string()).min(1).max(50)).describe("Page slugs to delete (1-50)"),
         }),
-        async execute({ wiki_slug, targets }) {
-            const resp = await request("POST", `/api/w/${wiki_slug}/resolve`, {
-                json: { targets },
-            });
-            return JSON.stringify(await resp.json(), null, 2);
+        async execute({ wiki_slug, page_slugs }) {
+            const results = [];
+            for (const slug of page_slugs) {
+                try {
+                    // DELETE returns 204 No Content on success
+                    await request("DELETE", `/api/w/${wiki_slug}/pages/${slug}`, { auth: true });
+                    results.push({ slug, status: "deleted" });
+                }
+                catch (err) {
+                    const message = err instanceof Error ? err.message : String(err);
+                    results.push({ slug, status: "error", message });
+                }
+            }
+            const deleted = results.filter(r => r.status === "deleted").length;
+            const lines = results.map(r => r.status === "deleted"
+                ? `- ${r.slug}: deleted`
+                : `- ${r.slug}: error — ${r.message}`);
+            return `Deleted ${deleted}/${page_slugs.length} pages.\n\n${lines.join("\n")}`;
         },
     });
 }

package/dist/tools/research.js

@@ -1,27 +1,10 @@
 import { z } from "zod";
 import { imageContent } from "fastmcp";
 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);
-}
+import { coerceJson } from "../utils.js";
 export function registerResearchTools(server) {
     const SearchWebInput = z.object({
-        source: z.enum(["web", "reddit"]).describe("Search source. Use 'web' for Google/Serper and 'reddit' for community perspectives via Reddit."),
+        source: z.enum(["web", "reddit"]).describe("Search source. Use 'web' for Google/Serper and 'reddit' for public perspectives via Reddit."),
         query: z.string().min(1).optional().describe("Search terms. Required for source='web'. Optional for source='reddit' — omit it there to return a sorted subreddit listing."),
         subreddit: z.string().optional().describe("Reddit-only. Subreddit name without the 'r/' prefix (e.g. 'Harvard'). Omit to search across all of Reddit."),
         sort: z.enum(["top", "hot", "new", "rising", "controversial", "relevance", "comments"])
@@ -51,40 +34,41 @@ export function registerResearchTools(server) {
     });
     server.addTool({
         name: "search_web",
-        description: "Search the web or a specific community source (Reddit). Pick the source with the `source` field:\n\n" +
+        description: "Search the web or Reddit. Pick the source with the `source` field:\n\n" +
             "- `source: \"web\"` — general web search via Google. Use for news, docs, scholarly references.\n" +
             "- `source: \"reddit\"` — Reddit-aware search returning posts with score, flair, num_comments, permalink. " +
-            "Use when the user is asking about community perspectives, subreddit consensus, or 'what do people think about X'.\n\n" +
+            "Use when the user is asking about public perspectives, subreddit consensus, or 'what do people think about X'.\n\n" +
             "Use only the fields relevant to the source you pick. " +
             "Rate limit: 10/min. Requires API key.",
         parameters: SearchWebInput,
         async execute(input) {
             if (input.source === "reddit") {
-                const params = {
+                const body = {
+                    source: "reddit",
                     sort: input.sort ?? "top",
                     time_range: input.time_range ?? "year",
                     limit: input.limit ?? 25,
                 };
                 if (input.subreddit)
-                    params.subreddit = input.subreddit;
+                    body.subreddit = input.subreddit;
                 if (input.query)
-                    params.query = input.query;
-                const resp = await request("GET", "/api/research/reddit/search", {
+                    body.query = input.query;
+                const resp = await request("POST", "/api/research/search", {
                     auth: true,
-                    params,
+                    json: body,
                 });
                 return JSON.stringify(await resp.json(), null, 2);
             }
-            const resp = await request("GET", "/api/research/search", {
+            const resp = await request("POST", "/api/research/search", {
                 auth: true,
-                params: { query: input.query.trim(), limit: input.limit ?? 10 },
+                json: { source: "web", query: input.query.trim(), limit: input.limit ?? 10 },
             });
             return JSON.stringify(await resp.json(), null, 2);
         },
     });
     server.addTool({
         name: "read_webpage",
-        description: "Fetch a URL and return its content as markdown. Routes automatically based on URL:\n" +
+        description: "Read an external URL and return its content as markdown. Routes automatically based on URL:\n" +
             "- **Reddit threads** (reddit.com/r/{sub}/comments/{id}/...) — returns the post plus top-level threaded comments with scores and authors, via a residential proxy.\n" +
             "- **Reddit wiki pages** (reddit.com/r/{sub}/wiki/...) — returns the wiki page as markdown with revision metadata.\n" +
             "- **YouTube videos** — returns title, description, transcript when available.\n" +
@@ -117,11 +101,11 @@ export function registerResearchTools(server) {
     });
     server.addTool({
         name: "search_images",
-        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). " +
+        description: "Search for images to include in pages. Accepts multiple queries for batch lookup. Returns image URLs, titles, dimensions, and licensing info. " +
+            "Three sources: 'google' (broad web images, default), 'unsplash' (high-quality stock photos), and 'wikimedia' (free, open-licensed from Wikimedia Commons). " +
             "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" +
+            "External image URLs are automatically persisted when you publish the page — no extra steps needed.\n\n" +
+            "## Using images in pages\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" +
             "Position options (in the title/quotes):\n" +
@@ -139,13 +123,13 @@ export function registerResearchTools(server) {
             "- Bad: `![Logo](url)` — Good: `![The OpenAI logo, a stylized spiral](url)`\n\n" +
             "**Placement rules:**\n" +
             "- Place 1-3 images per major section — don't overload\n" +
-            "- First image should appear near the top, illustrating the article's subject\n" +
+            "- First image should appear near the top, illustrating the page's subject\n" +
             "- Spread images throughout, not clustered together\n" +
             "- For the infobox hero image, set `infobox.header.image_url` in frontmatter instead\n\n" +
             "Requires login. Rate limit: 10/min.",
         parameters: z.object({
             queries: coerceJson(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)"),
+            source: z.enum(["wikimedia", "google", "unsplash"]).default("google").describe("Image source: 'google' (broad web images, default), 'unsplash' (high-quality stock photos), or 'wikimedia' (free, open-licensed)"),
             limit: z.number().default(5).describe("Max results per query (1-10, default 5)"),
         }),
         async execute({ queries, source, limit }) {
@@ -186,20 +170,25 @@ export function registerResearchTools(server) {
             return { content };
         },
     });
+    // register_sources — GUI citation-bubble handshake. Commented out 2026-04-23 per REV-62.
+    // Revive when the GUI citation-bubble flow is re-wired.
+    /*
     server.addTool({
-        name: "register_sources",
-        description: "Register sources you plan to cite in your response. Call this BEFORE writing your response text. " +
-            "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}"),
-                url: z.string().describe("Source URL"),
-                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 }) {
-            return `Registered ${sources.length} source${sources.length === 1 ? "" : "s"}. Use [@key] markers in your response to cite them.`;
-        },
+      name: "register_sources",
+      description:
+        "Register sources you plan to cite in your response. Call this BEFORE writing your response text. " +
+        "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}"),
+          url: z.string().describe("Source URL"),
+          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 }) {
+        return `Registered ${sources.length} source${sources.length === 1 ? "" : "s"}. Use [@key] markers in your response to cite them.`;
+      },
     });
+    */
 }