openalmanac 0.3.6 → 0.4.0

package/dist/auth.d.ts

@@ -1,7 +1,7 @@
 declare const API_BASE: string;
 declare const API_KEY_PATH: string;
-declare const ARTICLES_DIR: string;
-export { API_BASE, API_KEY_PATH, ARTICLES_DIR };
+declare const PAGES_DIR: string;
+export { API_BASE, API_KEY_PATH, PAGES_DIR };
 export declare function getApiKey(): string | null;
 export declare function requireApiKey(): string;
 export declare function saveApiKey(key: string): void;

package/dist/auth.js

@@ -5,8 +5,8 @@ import { chmodSync } from "node:fs";
 const API_BASE = process.env.OPENALMANAC_API_BASE || "https://www.openalmanac.org/api/proxy";
 const API_KEY_DIR = join(homedir(), ".openalmanac");
 const API_KEY_PATH = join(API_KEY_DIR, "api_key");
-const ARTICLES_DIR = join(homedir(), ".openalmanac", "articles");
-export { API_BASE, API_KEY_PATH, ARTICLES_DIR };
+const PAGES_DIR = join(homedir(), ".openalmanac", "pages");
+export { API_BASE, API_KEY_PATH, PAGES_DIR };
 export function getApiKey() {
     const envKey = process.env.OPENALMANAC_API_KEY;
     if (envKey)

package/dist/login-core.js

@@ -1,6 +1,7 @@
 import { createServer } from "node:http";
 import { getApiKey, saveApiKey, API_BASE } from "./auth.js";
 import { openBrowser } from "./browser.js";
+import { EXAMPLE_PROMPT } from "./onboarding-copy.js";
 const CONNECT_URL_BASE = "https://openalmanac.org/contribute/connect";
 const LOGIN_TIMEOUT_MS = 120_000;
 function callbackPage(success) {
@@ -118,7 +119,7 @@ function callbackPage(success) {
     <script>
       const steps = [
         { target: 'line1', prefix: '<span class="prompt">$ </span>', text: 'claude', delay: 600 },
-        { target: 'line2', prefix: '<span class="prompt">&gt; </span>', text: 'Use almanac tools to write an article on black holes', delay: 400 },
+        { target: 'line2', prefix: '<span class="prompt">&gt; </span>', text: ${JSON.stringify(EXAMPLE_PROMPT)}, delay: 400 },
       ];
       function type(el, prefix, text, speed, cb) {
         el.style.display = '';

package/dist/onboarding-copy.d.ts

@@ -0,0 +1 @@
+export declare const EXAMPLE_PROMPT = "Let's explore the Demon Slayer wiki using Almanac";

package/dist/onboarding-copy.js

@@ -0,0 +1,14 @@
+// Onboarding copy shared between setup's "next steps" panel and the
+// post-login connected page rendered by `login-core.ts`.
+//
+// The example prompt names a real wiki on purpose: the goal is to teach the
+// new user that wikis exist as the unit Almanac is organized around, not
+// just that the agent can do "research". If the example wiki changes, both
+// surfaces (`setup.ts` next steps + `login-core.ts` terminal mock) update
+// automatically because they consume this single constant.
+//
+// This lives in its own file rather than `setup.ts` to keep `login-core.ts`
+// from depending on the setup TUI module (`setup.ts` already imports
+// `performLogin` from `login-core.ts`, so adding the reverse edge would
+// create a cycle).
+export const EXAMPLE_PROMPT = "Let's explore the Demon Slayer wiki using Almanac";

package/dist/server.js

@@ -20,8 +20,8 @@ export function createServer() {
 │                                                  │
 │   Try asking your agent:                         │
 │                                                  │
-│   → "Write an Almanac article about CORS"        │
-│   → "Improve the Alan Turing article"            │
+│   → "Write an Almanac page about CORS"        │
+│   → "Improve the Alan Turing page"            │
 │                                                  │
 │   Docs: openalmanac.org/contribute               │
 │                                                  │
@@ -32,7 +32,7 @@ export function createServer() {
         name: "OpenAlmanac",
         version: pkg.version,
         instructions: [
-            "OpenAlmanac is an open knowledge base — a Wikipedia anyone can read from and write to through an API. Pages are primarily researched by agents, but humans can edit the pages directly on the platform too. Pages are markdown files with YAML frontmatter, [@key] citation markers, and [[wikilinks]]. Content is organized into wikis, each with topics, pages, and navigation.",
+            "OpenAlmanac is an open knowledge base — a Wikipedia anyone can read from and write to through an API. Pages are markdown files with YAML frontmatter, [@key] citation markers, and [[wikilinks]]. Content is organized into wikis, each with topics, pages, and navigation.",
             "",
             "## How this should feel",
             "",
@@ -48,11 +48,11 @@ 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 pages/stubs exist and their slugs. Then use `[[slug|Display Text]]` wikilink syntax in your response. Dead links auto-create stub pages on publish so round-trip editing stays faithful.",
+            "**Entity links:** Before writing your response, call `search_pages` with the key entity names you plan to mention (e.g. `queries: [\"Theravada Buddhism\", \"Thailand\", \"Angkor Wat\"]`). This returns which pages/stubs exist and their slugs. Then use `[[slug|Display Text]]` wikilink syntax in your response. Dead links auto-create stub pages on publish 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.",
             "",
-            "**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.",
+            "**Keep it efficient:** Batch your entity and image searches into single tool calls (both accept arrays). One `search_pages` 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.",
             "",
@@ -69,21 +69,21 @@ export function createServer() {
             "",
             "## Entry points",
             "",
-            "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.",
+            "The user is here because they want to dive down rabbit holes and learn about things. The page is the end product — a way to package and share what they learned — not the starting point. The conversation IS the experience. The page 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.",
+            "**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 a page\" — 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.",
+            "**Do not suggest writing a page 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 a page. If you suggest it too early, it feels like being funneled into a workflow. Don't mention pages 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.',
             "",
             '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 `list_articles` with `wiki_slug` and `stubs_only: true` to find stubs that need writing.",
+            "**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_pages` with `wiki_slug` and `stubs_only: true` to find stubs that need writing.",
             "",
-            "**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.",
+            "**User wants to edit an existing page** → 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.',
+            '**pages 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 page" or "Wirathu is worth writing up." A single research conversation might produce one page or several. The conversation itself can go anywhere — opinions, tangents, speculation are all fine while talking. The pages that come out of it are encyclopedic: neutral, factual, sourced.',
             "",
             "## Guidelines",
             "",
@@ -96,9 +96,9 @@ export function createServer() {
             "",
             "## Writing flow",
             "",
-            "When you've researched enough and a specific article topic has come into focus:",
+            "When you've researched enough and a specific page topic has come into focus:",
             "",
-            '1. **Align briefly with the user** — Talk about what the article should cover, what to focus on, what angle to take. Not a rigid outline — a quick conversation. "I\'m thinking we cover the history, the Royal Brahmins, daily worship, and the Ramakien — anything you want to add or skip?"',
+            '1. **Align briefly with the user** — Talk about what the page should cover, what to focus on, what angle to take. Not a rigid outline — a quick conversation. "I\'m thinking we cover the history, the Royal Brahmins, daily worship, and the Ramakien — anything you want to add or skip?"',
             "",
             "2. **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.",
             "",
@@ -106,20 +106,20 @@ export function createServer() {
             "",
             "4. **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.",
             "",
-            "   Write the full article body with citation markers [@key]. No wikilinks, no `[[slug|Display Text]]` syntax, no images, no stubs. Just prose and citations. The linking and images come later from subagents who need to read the finished text.",
+            "   Write the full page body with citation markers [@key]. No wikilinks, no `[[slug|Display Text]]` syntax, no images, no stubs. Just prose and citations. The linking and images come later from subagents who need to read the finished text.",
             "",
             "5. **Dispatch four subagents in parallel** — After the draft is complete, dispatch these simultaneously. Each agent has its own guidelines file — tell it to fetch and read that file as its first step. The guidelines file tells the agent what to do, what additional guidelines to fetch, and what format to return results in.",
             "",
-            "   - **Review agent** → tell it to read https://www.openalmanac.org/review-guidelines.md and review the draft at `~/.openalmanac/articles/{wiki_slug}/{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/{wiki_slug}/{slug}.md`",
-            "   - **Image agent** → tell it to read https://www.openalmanac.org/image-guidelines.md and find images for the draft at `~/.openalmanac/articles/{wiki_slug}/{slug}.md`",
-            "   - **Linking agent** → tell it to read https://www.openalmanac.org/linking-guidelines.md and add wikilinks for the draft at `~/.openalmanac/articles/{wiki_slug}/{slug}.md` (dead links become stubs on publish)",
+            "   - **Review agent** → tell it to read https://www.openalmanac.org/review-guidelines.md and review the draft at `~/.openalmanac/pages/{wiki_slug}/{slug}.md`",
+            "   - **Fact-check agent** → tell it to read https://www.openalmanac.org/fact-checking-guidelines.md and fact-check the draft at `~/.openalmanac/pages/{wiki_slug}/{slug}.md`",
+            "   - **Image agent** → tell it to read https://www.openalmanac.org/image-guidelines.md and find images for the draft at `~/.openalmanac/pages/{wiki_slug}/{slug}.md`",
+            "   - **Linking agent** → tell it to read https://www.openalmanac.org/linking-guidelines.md and add wikilinks for the draft at `~/.openalmanac/pages/{wiki_slug}/{slug}.md` (dead links become stubs on publish)",
             "",
             "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. **Publish** — Validate and publish (`publish` with `slugs` and `wiki_slug`). Put per-page change notes in frontmatter as `edit_summary`. Share the exact URL from the publish response when single-page. Use `list_articles` to verify coverage.",
+            "7. **Publish** — Validate and publish (`publish` with `slugs` and `wiki_slug`). Put per-page change notes in frontmatter as `edit_summary`. Share the exact URL from the publish response when single-page. Use `list_pages` 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.",
+            "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 page. Everything reads the draft.",
             "",
             "## Wikilink syntax",
             "",
@@ -160,23 +160,24 @@ export function createServer() {
             "5. **Edit the main page in place.** `download` the auto-created `main-page` and edit the file (don't `new` a fresh `main-page` — the server derives slug from title, so a new scaffold would get a different slug and you'd end up with two homepages).",
             "6. **Seed the topic hierarchy.** `create_topics` with the topics you agreed on.",
             "7. **Wire navigation.** `update_wiki_settings` with a `nav` array. Each NavItem needs exactly one of `page` / `topic` / `link`. Use `auto: {enabled: true}` on topic NavItems to auto-populate children from the topic DAG.",
-            "8. **Seed a few stub pages or first articles.** Stubs are fine — scaffold-and-fill-later is a supported workflow.",
+            "8. **Seed a few stub pages or first pages.** Stubs are fine — scaffold-and-fill-later is a supported workflow.",
+            "   For homepage-style timelines, keep stubs in stub surfaces (`::awaiting-composition` / `::stub-list`) rather than recent-entry timelines — front-page activity should reflect real pages, not auto-created unwritten stubs.",
             "",
             "The conversation drives the shape of the wiki. Don't over-engineer the topic hierarchy or the nav on turn one. Ship a small coherent starting shape and grow it with the user.",
             "",
             "## Technical workflow",
             "",
-            "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.",
+            "Reading and searching pages 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) → `whoami` (confirm identity) → `list_wikis` or `search_articles` (what exists?) → `search_web` + `read_webpage` (research) → `new` (scaffold) or `download` (existing) → edit files under ~/.openalmanac/articles/{wiki_slug}/ → `publish`.",
+            "Core flow: login (once) → `whoami` (confirm identity) → `list_wikis` or `search_pages` (what exists?) → `search_web` + `read_webpage` (research) → `new` (scaffold) or `download` (existing) → edit files under ~/.openalmanac/pages/{wiki_slug}/ → `publish`.",
             "",
-            "After publishing, share the celebration URL when applicable. Use `list_articles` with `wiki_slug` to browse a wiki's pages.",
+            "After publishing, share the celebration URL when applicable. Use `list_pages` with `wiki_slug` to browse a wiki's pages.",
             "",
             "When working with tool results, write down any important information you might need later, as the original tool result may be cleared.",
             "",
             "## Batching writes",
             "",
-            "Most write tools take arrays. Pass a single-element array for one item — there is no separate singular tool. Examples: `create_topics([{ title: \"X\" }])`, `delete_pages({ article_slugs: [\"foo\"] })`, `publish({ slugs: [\"bar\"] })`. Do not call a tool in a loop when an array argument exists.",
+            "Most write tools take arrays. Pass a single-element array for one item — there is no separate singular tool. Examples: `create_topics([{ title: \"X\" }])`, `delete_pages({ page_slugs: [\"foo\"] })`, `publish({ slugs: [\"bar\"] })`. Do not call a tool in a loop when an array argument exists.",
         ].join("\n"),
     });
     registerAuthTools(server);

package/dist/setup.js

@@ -5,57 +5,25 @@ import { fileURLToPath } from "url";
 import { spawnSync } from "child_process";
 import { performLogin } from "./login-core.js";
 import { getAuthStatus } from "./auth.js";
-const TOOL_GROUPS = [
-    {
-        name: "Search & Read",
-        description: "search, read, download, and browse community wiki articles",
-        tools: [
-            "mcp__almanac__search_articles",
-            "mcp__almanac__download",
-            "mcp__almanac__read",
-            "mcp__almanac__list_articles",
-        ],
-    },
-    {
-        name: "Research",
-        description: "web search, read pages, find images",
-        tools: [
-            "mcp__almanac__search_web",
-            "mcp__almanac__read_webpage",
-            "mcp__almanac__search_images",
-            "mcp__almanac__view_images",
-        ],
-    },
-    {
-        name: "Write & Publish",
-        description: "create article drafts and publish edits",
-        tools: [
-            "mcp__almanac__new",
-            "mcp__almanac__publish",
-        ],
-    },
-    {
-        name: "Auth",
-        description: "login and logout",
-        tools: ["mcp__almanac__login", "mcp__almanac__logout"],
-    },
-    {
-        name: "Community",
-        description: "communities and posts",
-        tools: [
-            "mcp__almanac__search_communities",
-            "mcp__almanac__create_community",
-            "mcp__almanac__create_post",
-        ],
-    },
-    {
-        name: "People",
-        description: "search people profiles",
-        tools: ["mcp__almanac__search_people"],
-    },
+import { MCP_TOOL_GROUPS, toClaudePermissionName, } from "./tool-registry.js";
+import { EXAMPLE_PROMPT } from "./onboarding-copy.js";
+// MCP-side permission groups come from the shared tool registry so adding a
+// new MCP tool can never silently leave it un-grouped — see
+// `src/tool-registry.ts` for the contract and `test/tool-registry.test.ts`
+// for the drift check that enforces it.
+function mcpGroupToPermissionGroup(group) {
+    return {
+        name: group.name,
+        description: group.description,
+        tools: group.tools.map(toClaudePermissionName),
+    };
+}
+// Built-in Claude Code tool groups — not MCP tools, so they stay defined
+// here. The user opts into them in the same TUI checkbox screen.
+const CLAUDE_BUILTIN_TOOL_GROUPS = [
     {
         name: "Local Files",
-        description: "read & edit articles in ~/.openalmanac",
+        description: "read & edit pages in ~/.openalmanac",
         tools: [
             "Read(~/.openalmanac/**)",
             "Write(~/.openalmanac/**)",
@@ -68,6 +36,10 @@ const TOOL_GROUPS = [
         tools: ["WebSearch", "WebFetch"],
     },
 ];
+const TOOL_GROUPS = [
+    ...MCP_TOOL_GROUPS.map(mcpGroupToPermissionGroup),
+    ...CLAUDE_BUILTIN_TOOL_GROUPS,
+];
 const AGENTS = [
     { name: "Claude Code", supported: true },
     { name: "Codex", supported: false },
@@ -102,7 +74,7 @@ const LOGO_LINES = [
     "\u2588\u2588\u2551  \u2588\u2588\u2551\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557\u2588\u2588\u2551 \u255a\u2550\u255d \u2588\u2588\u2551\u2588\u2588\u2551  \u2588\u2588\u2551\u2588\u2588\u2551 \u255a\u2588\u2588\u2588\u2588\u2551\u2588\u2588\u2551  \u2588\u2588\u2551\u255a\u2588\u2588\u2588\u2588\u2588\u2588\u2557",
     "\u255a\u2550\u255d  \u255a\u2550\u255d\u255a\u2550\u2550\u2550\u2550\u2550\u2550\u255d\u255a\u2550\u255d     \u255a\u2550\u255d\u255a\u2550\u255d  \u255a\u2550\u255d\u255a\u2550\u255d  \u255a\u2550\u2550\u2550\u255d\u255a\u2550\u255d  \u255a\u2550\u255d \u255a\u2550\u2550\u2550\u2550\u2550\u255d",
 ];
-function printBanner(subtitle = "Write and publish articles with your AI agent") {
+function printBanner(subtitle = "Write and publish pages with your AI agent") {
     process.stdout.write("\n");
     for (let i = 0; i < LOGO_LINES.length; i++) {
         process.stdout.write(`${GRADIENT[i]}${LOGO_LINES[i]}${RST}\n`);
@@ -112,7 +84,7 @@ function printBanner(subtitle = "Write and publish articles with your AI agent")
 function renderHeader(mode = "default") {
     printBanner(mode === "reddit"
         ? "Turn any subreddit into a published wiki"
-        : "Write and publish articles with your AI agent");
+        : "Write and publish pages with your AI agent");
 }
 function printBadge() {
     process.stdout.write(`\n   ${ACCENT_BG} almanac ${RST}\n`);
@@ -1052,45 +1024,46 @@ function printResult(clientsLabel, loginResult, configured, alreadyConfigured, t
     w("");
 }
 function getNextSteps(clientsLabel) {
+    const exampleLine = `${BLUE}"${EXAMPLE_PROMPT}"${RST}`;
     if (clientsLabel === "Claude Code") {
         return [
             `Type ${WHITE_BOLD}claude${RST} to start Claude Code`,
-            `Say ${BLUE}"Let's explore <topic> using Almanac"${RST}`,
+            `Say ${exampleLine}`,
         ];
     }
     if (clientsLabel === "Codex") {
         return [
             `Type ${WHITE_BOLD}codex${RST} to start Codex`,
-            `Ask ${BLUE}"Let's explore <topic> using Almanac"${RST}`,
+            `Ask ${exampleLine}`,
         ];
     }
     if (clientsLabel === "Cursor") {
         return [
             `Open ${WHITE_BOLD}Cursor${RST} in your project`,
-            `Ask ${BLUE}"Let's explore <topic> using Almanac"${RST}`,
+            `Ask ${exampleLine}`,
         ];
     }
     if (clientsLabel === "OpenCode") {
         return [
             `Type ${WHITE_BOLD}opencode${RST} to start OpenCode`,
-            `Ask ${BLUE}"Let's explore <topic> using Almanac"${RST}`,
+            `Ask ${exampleLine}`,
         ];
     }
     if (clientsLabel === "Windsurf") {
         return [
             `Open ${WHITE_BOLD}Windsurf${RST} in your project`,
-            `Ask ${BLUE}"Let's explore <topic> using Almanac"${RST}`,
+            `Ask ${exampleLine}`,
         ];
     }
     if (clientsLabel === "Claude Desktop") {
         return [
             `Open ${WHITE_BOLD}Claude Desktop${RST}`,
-            `Ask ${BLUE}"Let's explore <topic> using Almanac"${RST}`,
+            `Ask ${exampleLine}`,
         ];
     }
     return [
         `Open one of your configured agents in this project`,
-        `Ask ${BLUE}"Let's explore <topic> using Almanac"${RST}`,
+        `Ask ${exampleLine}`,
     ];
 }
 /* ── Entry point ────────────────────────────────────────────────── */

package/dist/tool-registry.d.ts

@@ -0,0 +1,11 @@
+export declare const MCP_TOOL_NAMES: readonly ["search_pages", "search_topics", "list_pages", "download", "new", "publish", "read_page", "delete_pages", "list_topics", "update_topic", "create_topics", "list_wikis", "create_wiki", "get_wiki_settings", "update_wiki_settings", "join_wiki", "get_wiki_membership", "login", "logout", "whoami", "search_web", "read_webpage", "search_images", "view_images"];
+export type McpToolName = (typeof MCP_TOOL_NAMES)[number];
+export declare const INTERACTIVE_TOOL_NAMES: readonly string[];
+export interface McpToolGroup {
+    name: string;
+    description: string;
+    tools: readonly McpToolName[];
+}
+export declare const MCP_TOOL_GROUPS: readonly McpToolGroup[];
+export declare function toClaudePermissionName(name: McpToolName): string;
+export declare const MCP_TOOL_PERMISSION_NAMES: readonly string[];

package/dist/tool-registry.js

@@ -0,0 +1,148 @@
+// Single source of truth for the MCP tools the OpenAlmanac server exposes.
+//
+// This file is the contract that ties three otherwise-independent surfaces
+// together:
+//
+//   1. tools/*.ts                   — the actual `server.addTool({ name: ... })`
+//                                     registrations.
+//   2. setup.ts TOOL_GROUPS         — the permission grouping shown in the
+//                                     `npx openalmanac setup` TUI, written into
+//                                     `~/.claude/settings.json` so a user's
+//                                     agent can call these tools without a
+//                                     per-call approval prompt.
+//   3. gui/config.js                — the Electron app's allow-list passed to
+//                                     the Claude Code SDK.
+//
+// Drift between these three surfaces was a real bug: the rename refactor
+// added `read_page`, `list_wikis`, `create_wiki`, the topic tools, etc., but
+// only (1) was updated. (2) was still grouping the pre-refactor tool set, so
+// users who ran `setup` had to manually approve every wiki/topic call.
+//
+// The drift test in `test/tool-registry.test.ts` walks every register*Tools
+// function with a fake server, collects the names actually registered, and
+// asserts:
+//
+//   - every registered name is in MCP_TOOL_NAMES
+//   - every name in MCP_TOOL_NAMES is actually registered
+//   - every non-INTERACTIVE name appears in exactly one MCP_TOOL_GROUPS entry
+//
+// Adding a new MCP tool means: register it in tools/*.ts, add its name here,
+// and place it in a group below. Skipping any of those three breaks CI.
+export const MCP_TOOL_NAMES = [
+    // Pages
+    "search_pages",
+    "search_topics",
+    "list_pages",
+    "download",
+    "new",
+    "publish",
+    "read_page",
+    "delete_pages",
+    // Topics
+    "list_topics",
+    "update_topic",
+    "create_topics",
+    // Wikis
+    "list_wikis",
+    "create_wiki",
+    "get_wiki_settings",
+    "update_wiki_settings",
+    "join_wiki",
+    "get_wiki_membership",
+    // Account
+    "login",
+    "logout",
+    "whoami",
+    // Research
+    "search_web",
+    "read_webpage",
+    "search_images",
+    "view_images",
+];
+// Tools intentionally excluded from the setup-time permission grant because
+// they require interactive UI / per-call approval. The drift test allows these
+// to be absent from MCP_TOOL_GROUPS — but they must still appear in
+// MCP_TOOL_NAMES if they are actually registered.
+//
+// `register_sources` was a GUI citation-bubble handshake; it is currently
+// commented out in tools/research.ts (REV-62) and therefore not in
+// MCP_TOOL_NAMES. When it comes back, add it both there and here.
+export const INTERACTIVE_TOOL_NAMES = [
+    "register_sources",
+];
+// Permission groupings shown in the setup TUI. Each group is a checkbox the
+// user toggles; checked groups are written into `~/.claude/settings.json`
+// `permissions.allow` so the agent can call them without per-call approval.
+//
+// Group boundaries are user-facing — they should match the user's mental
+// model ("Search & Read", "Write & Publish") rather than the file the tool
+// happens to live in. Every non-INTERACTIVE name in MCP_TOOL_NAMES must
+// appear in exactly one group; the drift test enforces this.
+export const MCP_TOOL_GROUPS = [
+    {
+        name: "Search & Read",
+        description: "search, read, download, and browse pages, topics, and wikis",
+        tools: [
+            "search_pages",
+            "search_topics",
+            "list_pages",
+            "list_topics",
+            "list_wikis",
+            "download",
+            "read_page",
+        ],
+    },
+    {
+        name: "Research",
+        description: "web search, read pages, find and view images",
+        tools: [
+            "search_web",
+            "read_webpage",
+            "search_images",
+            "view_images",
+        ],
+    },
+    {
+        name: "Write & Publish",
+        description: "create, edit, and publish pages and topics",
+        tools: [
+            "new",
+            "publish",
+            "delete_pages",
+            "create_topics",
+            "update_topic",
+        ],
+    },
+    {
+        name: "Wikis",
+        description: "create wikis, configure settings, manage membership",
+        tools: [
+            "create_wiki",
+            "get_wiki_settings",
+            "update_wiki_settings",
+            "join_wiki",
+            "get_wiki_membership",
+        ],
+    },
+    {
+        name: "Account",
+        description: "login, logout, identity",
+        tools: [
+            "login",
+            "logout",
+            "whoami",
+        ],
+    },
+];
+// Convert a bare MCP tool name into the prefixed form Claude Code uses in
+// `~/.claude/settings.json` permissions and the Electron SDK's allow-list.
+//
+// Example: `read_page` → `mcp__almanac__read_page`.
+export function toClaudePermissionName(name) {
+    return `mcp__almanac__${name}`;
+}
+// Full set of allow-list entries for every registered MCP tool, in the
+// `mcp__almanac__*` form Claude Code expects. Consumers (gui/config.js once
+// it's bumped to a registry-aware mcp-ts version) should derive their tool
+// allow-list from this.
+export const MCP_TOOL_PERMISSION_NAMES = MCP_TOOL_NAMES.map(toClaudePermissionName);

package/dist/tools/auth.js

@@ -4,7 +4,7 @@ export function registerAuthTools(server) {
     server.addTool({
         name: "login",
         description: "Log in via browser to connect your account and get a personal API key. This is the required " +
-            "first step before creating or updating articles. Only needs to be called once.\n\n" +
+            "first step before creating or updating pages. Only needs to be called once.\n\n" +
             "If you already have a valid API key, this returns immediately without opening a browser.",
         async execute() {
             const result = await performLogin();

package/dist/tools/pages.js

@@ -2,12 +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 { 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 resolvePageDir(wikiSlug) {
-    return join(ARTICLES_DIR, wikiSlug);
+    return join(PAGES_DIR, wikiSlug);
 }
 function resolvePagePaths(slug, wikiSlug) {
     const dir = resolvePageDir(wikiSlug);
@@ -110,6 +110,10 @@ function formatPublishResults(results, targetSlugs, wiki_slug, dry_run) {
                     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(", ")}`);
                 }
@@ -161,7 +165,7 @@ function formatPublishResults(results, targetSlugs, wiki_slug, dry_run) {
 }
 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({
@@ -213,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.",
@@ -237,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"),
@@ -326,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");
@@ -400,48 +423,18 @@ export function registerPageTools(server) {
             return summary;
         },
     });
-    // propose_article — GUI-only handshake. Commented out 2026-04-23 per REV-62.
-    // Revive when the GUI plan-card proposal flow is in active use.
-    /*
-    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.",
-      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(),
-      }),
-      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.`;
-      },
-    });
-    */
     server.addTool({
-        name: "read_article",
+        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_articles` instead. No authentication needed.",
+            "For discovery, use `search_pages` instead. No authentication needed.",
         parameters: z.object({
             wiki_slug: z.string().describe("Wiki slug"),
-            article_slug: z.string().describe("Page slug"),
+            page_slug: z.string().describe("Page slug"),
         }),
-        async execute({ wiki_slug, article_slug }) {
-            const resp = await request("GET", `/api/w/${wiki_slug}/pages/${article_slug}`);
+        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);
         },
     });
@@ -451,11 +444,11 @@ export function registerPageTools(server) {
             "Accepts multiple slugs and deletes them in sequence. Requires moderator or creator access.",
         parameters: z.object({
             wiki_slug: z.string().describe("Wiki slug"),
-            article_slugs: coerceJson(z.array(z.string()).min(1).max(50)).describe("Page slugs to delete (1-50)"),
+            page_slugs: coerceJson(z.array(z.string()).min(1).max(50)).describe("Page slugs to delete (1-50)"),
         }),
-        async execute({ wiki_slug, article_slugs }) {
+        async execute({ wiki_slug, page_slugs }) {
             const results = [];
-            for (const slug of article_slugs) {
+            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 });
@@ -470,7 +463,7 @@ export function registerPageTools(server) {
             const lines = results.map(r => r.status === "deleted"
                 ? `- ${r.slug}: deleted`
                 : `- ${r.slug}: error — ${r.message}`);
-            return `Deleted ${deleted}/${article_slugs.length} pages.\n\n${lines.join("\n")}`;
+            return `Deleted ${deleted}/${page_slugs.length} pages.\n\n${lines.join("\n")}`;
         },
     });
 }

package/dist/tools/research.js

@@ -4,7 +4,7 @@ import { request } from "../auth.js";
 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"])
@@ -34,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" +
@@ -100,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. " +
+        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" +
@@ -122,7 +123,7 @@ 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.",

package/package.json

@@ -1,22 +1,30 @@
 {
   "name": "openalmanac",
-  "version": "0.3.6",
-  "description": "OpenAlmanac — pull, edit, and push articles to the open knowledge base",
+  "version": "0.4.0",
+  "description": "OpenAlmanac — pull, edit, and push pages to the open knowledge base",
   "type": "module",
   "bin": {
     "openalmanac": "dist/cli.js"
   },
+  "exports": {
+    "./tool-registry": {
+      "types": "./dist/tool-registry.d.ts",
+      "default": "./dist/tool-registry.js"
+    }
+  },
   "scripts": {
     "build": "tsc",
     "dev": "tsc --watch",
-    "start": "node dist/cli.js"
+    "start": "node dist/cli.js",
+    "test": "vitest run",
+    "test:watch": "vitest"
   },
   "keywords": [
     "openalmanac",
     "mcp",
     "knowledge-base",
     "ai",
-    "articles"
+    "pages"
   ],
   "license": "MIT",
   "dependencies": {
@@ -25,8 +33,9 @@
     "zod": "^3.24.0"
   },
   "devDependencies": {
-    "@types/node": "^22.0.0",
-    "typescript": "^5.7.0"
+    "@types/node": "^25.6.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.2.4"
   },
   "engines": {
     "node": ">=18.0.0"

package/skills/reddit-wiki/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: reddit-wiki
 description: Turn any subreddit into a published wiki on Almanac
-allowed-tools: Bash(node ${CLAUDE_SKILL_DIR}/scripts/ingest.js *), mcp__almanac__search_articles, mcp__almanac__search_communities, mcp__almanac__list_articles, mcp__almanac__read, mcp__almanac__download, mcp__almanac__new, mcp__almanac__publish, mcp__almanac__search_web, mcp__almanac__read_webpage, mcp__almanac__search_images, mcp__almanac__view_images, mcp__almanac__register_sources, mcp__almanac__login, mcp__almanac__create_community, Read(~/.openalmanac/**), Write(~/.openalmanac/**), Edit(~/.openalmanac/**)
+allowed-tools: Bash(node ${CLAUDE_SKILL_DIR}/scripts/ingest.js *), mcp__almanac__search_pages, mcp__almanac__list_wikis, mcp__almanac__create_wiki, mcp__almanac__list_pages, mcp__almanac__read_page, mcp__almanac__download, mcp__almanac__new, mcp__almanac__publish, mcp__almanac__search_web, mcp__almanac__read_webpage, mcp__almanac__search_images, mcp__almanac__view_images, mcp__almanac__register_sources, mcp__almanac__login, Read(~/.openalmanac/**), Write(~/.openalmanac/**), Edit(~/.openalmanac/**)
 argument-hint: r/<subreddit>
 ---
 
@@ -18,8 +18,8 @@ Never estimate how long things will take. Do show data sizes so the user knows w
 ## Flow overview
 
 Two phases:
-1. **Foundation** — Plan and write 15-20 core articles with images, citations, and wikilinks
-2. **Deep Absorb** — Process the corpus batch by batch, discovering niche topics and enriching existing articles
+1. **Foundation** — Plan and write 15-20 core pages with images, citations, and wikilinks
+2. **Deep Absorb** — Process the corpus batch by batch, discovering niche topics and enriching existing pages
 
 ## Naming convention
 
@@ -32,9 +32,9 @@ Two phases:
 
 If the user runs `/reddit-wiki` without arguments or asks how it works, explain briefly:
 
-- **What it does:** Takes any subreddit and builds a wiki on Almanac — real articles with citations, images, and links between them. Two phases: a foundation of 15-20 core articles, then a deep pass through the corpus finding niche topics.
+- **What it does:** Takes any subreddit and builds a wiki on Almanac — real pages with citations, images, and links between them. Two phases: a foundation of 15-20 core pages, then a deep pass through the corpus finding niche topics.
 - **What Almanac is:** An open knowledge base anyone can read and write to. Think Wikipedia's depth meets Reddit's community energy.
-- **How it works:** Downloads the subreddit's history, scores posts by quality, then uses AI agents to research and write articles citing the community's own discussions.
+- **How it works:** Downloads the subreddit's history, scores posts by quality, then uses AI agents to research and write pages citing the community's own discussions.
 - **Data storage:** Everything is stored locally at `~/.openalmanac/corpus/<subreddit>/`. The user can delete it anytime after the wiki is published.
 - **Any subreddit:** They can pick any subreddit they're interested in. Some smaller or newer subreddits may not have data available — if that happens, you'll suggest alternatives or nearby subreddits that do have data.
 
@@ -45,8 +45,8 @@ Then end with a single inviting line that asks what they're into and offers to h
 Extract the subreddit name from the argument (strip `r/` prefix if present). Use the bare name for all API calls and file paths. Use `r/<name>` when talking to the user.
 
 Run these three things in parallel (silently — don't narrate the tool calls):
-1. `search_communities("<subreddit_name>")`
-2. `search_articles` with 5-10 key topic terms you'd expect in this community
+1. `list_wikis()` and look for the subreddit wiki slug
+2. `search_pages` with 5-10 key topic terms you'd expect in this community
 3. Get subreddit stats from Arctic Shift:
 
 ```bash
@@ -56,7 +56,7 @@ node ${CLAUDE_SKILL_DIR}/scripts/ingest.js $1 count
 This returns JSON with `total_posts`, `total_comments`, and `estimated_size_mb`.
 
 Now greet the user. Tell them:
-- What already exists on Almanac for this community (articles, stubs, community)
+- What already exists on Almanac for this community (pages, stubs, community)
 - Share something genuinely interesting about it if you know anything
 - Subreddit stats (posts, comments)
 - The two-phase plan (brief — one line each)
@@ -153,18 +153,18 @@ If the `count` command returns 0 posts, the subreddit may not be indexed. In thi
 Read 20-30 corpus entries (prioritize high-score posts) to understand the landscape. Also check what already exists:
 
 ```
-list_articles(community_slug: "<subreddit>", sort: "most_referenced")
+list_pages(wiki_slug: "<subreddit>")
 ```
 
-Identify 15-20 core articles. **Favor nouns over themes** — specific things people would look up, not vague survey topics.
+Identify 15-20 core pages. **Favor nouns over themes** — specific things people would look up, not vague survey topics.
 
 - **~70% nouns:** Specific locks, tools, people, techniques, concepts. "American Lock 1100", "Spool Pin", "Tension Wrench", "LockPickingLawyer". These are the building blocks — what people search for, link to, and learn from.
-- **~30% structural themes:** Only the big ones that serve as entry points and tie nouns together. "Belt System", "Lock Picking Basics". Not vague surveys — each should be a real article that teaches something.
+- **~30% structural themes:** Only the big ones that serve as entry points and tie nouns together. "Belt System", "Lock Picking Basics". Not vague surveys — each should be a real page that teaches something.
 
 Bad: "Security Pin Mechanics" (vague theme, reads like a textbook chapter)
 Good: "Spool Pin", "Serrated Pin", "Mushroom Pin" (specific nouns — then link them from a "Security Pins" overview)
 
-Present them to the user grouped by category, but make clear most articles are about specific things:
+Present them to the user grouped by category, but make clear most pages are about specific things:
 
 ```
 Here's what I'd build for the foundation:
@@ -188,21 +188,21 @@ Include your recommendation. Wait for the user to confirm or adjust.
 
 ### Topics
 
-The groupings you present (Locks, Components, Techniques, Community) become **community topics** on Almanac. Topics show up as categories on the wiki page and each article gets assigned to one. When you scaffold articles, include the topic in the `new()` call.
+The groupings you present (Locks, Components, Techniques, Community) become **community topics** on Almanac. Topics show up as categories on the wiki page and each page gets assigned to one. When you scaffold pages, include the topic in the `new()` call.
 
-Keep topics broad and few (4-7). They're navigation, not a taxonomy. A topic like "Locks" is good. A topic like "European High-Security Disc Detainer Locks" is too specific — that's an article, not a topic.
+Keep topics broad and few (4-7). They're navigation, not a taxonomy. A topic like "Locks" is good. A topic like "European High-Security Disc Detainer Locks" is too specific — that's a page, not a topic.
 
 ### Scaffold entities
 
-Before any writing, scaffold all planned articles as local files:
+Before any writing, scaffold all planned pages as local files:
 
-1. **Check what exists online:** `search_articles` with ALL planned entity names in one batch call
-2. **Check local folder:** Read `~/.openalmanac/articles/<subreddit>/` to see what's already scaffolded
-3. **Create missing:** `new(articles: [{title, community_slug}, ...])` for everything not found
+1. **Check what exists online:** `search_pages` with ALL planned entity names in one batch call
+2. **Check local folder:** Read `~/.openalmanac/pages/<subreddit>/` to see what's already scaffolded
+3. **Create missing:** `new(pages: [{title, slug?, topics?}, ...], wiki_slug: "<subreddit>")` for everything not found
 
 This creates the entity map. Writing agents will check the local folder to know what slugs exist.
 
-### Write articles
+### Write pages
 
 Tell the user what's happening:
 
@@ -215,62 +215,62 @@ Kicking off the writing agents:
   • Agent 4: Community — LockPickingLawyer, Belt System
 ```
 
-Spin up 4-5 parallel writing agents, ~3-4 articles each. Group by theme so related articles are written by the same agent (better cross-referencing).
+Spin up 4-5 parallel writing agents, ~3-4 pages each. Group by theme so related pages are written by the same agent (better cross-referencing).
 
 **Each writing agent's brief must include:**
 
-1. **Which articles to write** (the scaffolded .md files to fill in)
+1. **Which pages to write** (the scaffolded .md files to fill in)
 2. **Corpus entries to read** — point to specific files in `~/.openalmanac/corpus/<subreddit>/` relevant to its topics
 3. **The entity map** — list all scaffolded slugs so the agent uses correct wikilinks
 4. **These citation rules:**
    - Every source MUST have a public URL
-   - Corpus entries have `citation_key` and `source` (Reddit permalink) in their frontmatter — use them as `[@citation_key]` markers and list them in the article's YAML `sources:` array
+   - Corpus entries have `citation_key` and `source` (Reddit permalink) in their frontmatter — use them as `[@citation_key]` markers and list them in the page's YAML `sources:` array
    - Also use `search_web` and `read_webpage` for additional sources beyond Reddit
    - NEVER fabricate a URL. If a source has no public URL, do not use it.
    - Register sources with `register_sources` before writing
 5. **These wikilink rules:**
    - Use `[[slug|Display Text]]` syntax for entities that exist (scaffolded or published)
-   - Before linking to a new entity NOT on the map: `search_articles` to check, then scaffold with `new()` if needed
+   - Before linking to a new entity NOT on the map: `search_pages` to check, then scaffold with `new()` if needed
    - Prefer existing slugs over inventing new ones
 6. **Writing quality:**
    - Fetch guidelines from `https://openalmanac.org/writing-guidelines` using `read_webpage`
    - Write with the community's voice — cite Reddit discussions, not just Wikipedia
    - Include `[@citation_key]` markers throughout, especially for claims from the corpus
-   - Articles should feel like they were written by someone who lives in this community
+   - pages should feel like they were written by someone who lives in this community
 
 **While agents work**, narrate what's happening. Share interesting things you see them finding. Example:
 
 ```
 Agent 2 found a heated 2019 thread about whether LockPickingLawyer's
 speed picks are realistic for beginners — 400 upvotes, great discussion.
-Working that into the article...
+Working that into the page...
 ```
 
 ### Image pass
 
-After all writing agents finish, run parallel haiku-model image agents (one per article):
+After all writing agents finish, run parallel haiku-model image agents (one per page):
 
 Each image agent:
-1. Reads the article
+1. Reads the page
 2. `search_images` for 1-2 hero image queries
 3. `view_images` to verify the best candidate
-4. Adds the image URL to the article's frontmatter as `image_url`
+4. Adds the image URL to the page's frontmatter as `image_url`
 
 ### Publish
 
 ```
-publish(community_slug: "<subreddit>")
+publish(wiki_slug: "<subreddit>")
 ```
 
-This batch-publishes all articles in the community folder. The backend auto-creates stubs from any dead wikilinks in the articles.
+This batch-publishes all pages in the community folder. The backend auto-creates stubs from any dead wikilinks in the pages.
 
 Share the results with enthusiasm:
 
 ```
-17 articles live! The wiki now has 35 articles total, plus
+17 pages live! The wiki now has 35 pages total, plus
 12 new stubs that emerged from wikilinks.
 
-Check it out: openalmanac.org/communities/<subreddit>/wiki
+Check it out: openalmanac.org/w/<subreddit>
 
 You can also browse it in the Almanac desktop app — best way
 to explore and keep contributing.
@@ -302,10 +302,10 @@ For each batch:
 
 1. **Read 50 unabsorbed entries** from the corpus directory (skip any listed in absorb_log)
 2. **Cluster by theme** — what topics do these entries cover?
-3. **Decide:** Create new articles? Enrich existing ones? Both?
-4. **For existing articles:** `download` them first, then expand with new details/sections
-5. **For new articles:** Scaffold → write → add to wiki
-6. **Image pass** on any new articles (haiku agents)
+3. **Decide:** Create new pages? Enrich existing ones? Both?
+4. **For existing pages:** `download` them first, then expand with new details/sections
+5. **For new pages:** Scaffold → write → add to wiki
+6. **Image pass** on any new pages (haiku agents)
 7. **Publish** the batch
 8. **Update absorb_log.json:**
    ```json
@@ -313,7 +313,7 @@ For each batch:
      "entries": {
        "<filename>": {
          "absorbed_at": "<ISO timestamp>",
-         "absorbed_into": ["article-slug-1", "article-slug-2"]
+         "absorbed_into": ["page-slug-1", "page-slug-2"]
        }
      },
      "stats": {
@@ -330,12 +330,12 @@ For each batch:
 Batches 1-5 done. Found some gems:
   • "Lock Lubricants in Cold Weather" — apparently Houdini
     lube freezes below -20°F, community recommends graphite
-  • Expanded the American 1100 article with a detailed
+  • Expanded the American 1100 page with a detailed
     teardown thread from 2017
-  • New article: "Lockpicking Competitions" — there's a
+  • New page: "Lockpicking Competitions" — there's a
     whole competitive scene
 
-3 new articles, 4 enriched. Continuing...
+3 new pages, 4 enriched. Continuing...
 ```
 
 ### When to stop
@@ -348,11 +348,11 @@ Batches 1-5 done. Found some gems:
 Phase 2 complete. Processed X,XXX entries across N batches.
 
 Final wiki:
-  XX articles (was YY)
+  XX pages (was YY)
   XX remaining stubs
   XXX+ citations from the community
 
-openalmanac.org/communities/<subreddit>/wiki
+openalmanac.org/w/<subreddit>
 ```
 
 ## Important rules
@@ -364,14 +364,14 @@ openalmanac.org/communities/<subreddit>/wiki
 - Corpus entries have `citation_key` and `source` in their frontmatter — these are ready to use.
 
 ### Entity linking
-- Always `search_articles` before creating new entities — check what already exists
-- Check the local `~/.openalmanac/articles/<subreddit>/` folder for scaffolded files
+- Always `search_pages` before creating new entities — check what already exists
+- Check the local `~/.openalmanac/pages/<subreddit>/` folder for scaffolded files
 - Only scaffold with `new()` if the entity doesn't exist anywhere
 - Use `[[slug|Display Text]]` wikilink syntax
 - Prefer existing slugs over inventing new ones to avoid duplicates
 
 ### Community creation
-- If the community doesn't exist on Almanac yet, create it with `create_community`
+- If the wiki doesn't exist on Almanac yet, create it with `create_wiki`
 - The description should have personality — capture the community's vibe, not a generic taxonomy
 - Find a good cover image with `search_images`
 
@@ -385,5 +385,5 @@ openalmanac.org/communities/<subreddit>/wiki
 - Don't make small talk or ask personal questions
 - Don't force enthusiasm — if something isn't interesting, don't pretend
 - Don't go silent for long stretches — narrate what's happening
-- Don't ask permission for every article — the user approved the plan, that's consent
+- Don't ask permission for every page — the user approved the plan, that's consent
 - Don't skip Reddit as a source — the corpus IS the community's voice, cite it