openalmanac 0.3.5 → 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               │
 │                                                  │
@@ -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,32 +96,30 @@ 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. **Propose the article** — Call `propose_article` with your summary (title, key sections, angle — 3-5 bullet points) and a detailed brief (all sources, key facts, user preferences, angle, what to avoid, related articles). Do not start writing an article without proposing first. The client environment determines what happens next — in some environments the user will see a plan card with options (write here vs. run in background), in others you'll get a text response telling you to proceed. Follow whatever the tool response says.",
+            "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.",
             "",
-            "3. **Read the writing guidelines** — Fetch https://www.openalmanac.org/writing-guidelines.md and https://www.openalmanac.org/ai-patterns-to-avoid.md before writing a single word.",
+            "3. **Scaffold** — Use `new` with one or more `{ title, slug?, topics? }` entries and a `wiki_slug`. Provide `slug` when you know the canonical ID; otherwise it is auto-derived from the title. List ALL sources you've gathered in the frontmatter before writing any body text. Don't discard sources — if you read it during research and it's relevant, include it.",
             "",
-            "4. **Scaffold** — Use `new` with one or more `{ title, slug?, topics? }` entries and a `wiki_slug`. Provide `slug` when you know the canonical ID; otherwise it is auto-derived from the title. List ALL sources you've gathered in the frontmatter before writing any body text. Don't discard sources — if you read it during research and it's relevant, include it.",
+            "4. **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.",
             "",
-            "5. **Write a pure text draft** — This whole process (writing, review, fact-check, images, linking) takes a few minutes. Let the user know in a fun way that they can step away — and that once it's ready, you're happy to discuss any edits or polishing.",
+            "   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.",
             "",
-            "   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.",
+            "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.",
             "",
-            "6. **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/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)",
             "",
-            "   - **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)",
+            "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. **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_pages` to verify coverage.",
             "",
-            "8. **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.",
-            "",
-            "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,21 +158,26 @@ export function createServer() {
             "3. **Brainstorm structure with the user.** Be conversational, not a form-filler. Propose a few natural topics the wiki might have (3-6 bullet points max), what the scope is, what the voice/angle is. Ask what resonates. Don't write prose yet.",
             "4. **Create the wiki.** `create_wiki` with title + description. The server auto-scaffolds a `main-page` with default homepage directives.",
             "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_batch` with the topics you agreed on.",
+            "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({ 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,58 +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, register sources, find images",
-        tools: [
-            "mcp__almanac__search_web",
-            "mcp__almanac__read_webpage",
-            "mcp__almanac__register_sources",
-            "mcp__almanac__search_images",
-            "mcp__almanac__view_images",
-        ],
-    },
-    {
-        name: "Write & Publish",
-        description: "create 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/**)",
@@ -69,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 },
@@ -103,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`);
@@ -113,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`);
@@ -1053,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();