openalmanac 0.3.5 → 0.4.0

package/dist/tools/topics.js

@@ -1,18 +1,6 @@
 import { z } from "zod";
 import { request } from "../auth.js";
-function coerceJson(schema) {
-    return z.preprocess((val) => {
-        if (typeof val === "string") {
-            try {
-                return JSON.parse(val);
-            }
-            catch {
-                return val;
-            }
-        }
-        return val;
-    }, schema);
-}
+import { coerceJson } from "../utils.js";
 export function registerTopicTools(server) {
     server.addTool({
         name: "list_topics",
@@ -28,24 +16,6 @@ export function registerTopicTools(server) {
             return JSON.stringify(await resp.json(), null, 2);
         },
     });
-    server.addTool({
-        name: "create_topic",
-        description: "Create a topic in a wiki. Topics are lightweight categories — pages can belong to multiple topics. Requires wiki membership.",
-        parameters: z.object({
-            wiki_slug: z.string().describe("Wiki slug"),
-            title: z.string().describe("Topic title"),
-            description: z.string().default("").describe("Topic description"),
-            image_url: z.string().url().max(2048).optional().describe("Topic image URL (https:// or http://)"),
-            parent_slugs: coerceJson(z.array(z.string())).default([]).describe("Parent topic slugs"),
-        }),
-        async execute({ wiki_slug, title, description, image_url, parent_slugs }) {
-            const resp = await request("POST", `/api/w/${wiki_slug}/topics`, {
-                auth: true,
-                json: { title, description, image_url, parent_slugs },
-            });
-            return JSON.stringify(await resp.json(), null, 2);
-        },
-    });
     server.addTool({
         name: "update_topic",
         description: "Update a topic's title, description, or image. Requires wiki moderator role.",
@@ -75,8 +45,8 @@ export function registerTopicTools(server) {
         },
     });
     server.addTool({
-        name: "create_topics_batch",
-        description: "Batch create topics in a wiki. Useful for bootstrapping a topic hierarchy. Requires wiki membership.",
+        name: "create_topics",
+        description: "Create one or more topics in a wiki. Topics are lightweight categories — pages can belong to multiple topics. Pass a single-element array for one topic: `[{ title: \"Security Pins\" }]`. Useful for bootstrapping a topic hierarchy. Requires wiki membership.",
         parameters: z.object({
             wiki_slug: z.string().describe("Wiki slug"),
             topics: coerceJson(z.array(z.object({
@@ -84,7 +54,7 @@ export function registerTopicTools(server) {
                 description: z.string().default(""),
                 image_url: z.string().url().max(2048).optional(),
                 parent_slugs: z.array(z.string()).default([]),
-            })).min(1).max(100)).describe("Topics to create"),
+            })).min(1).max(100)).describe("Topics to create (N=1 is fully supported)"),
         }),
         async execute({ wiki_slug, topics }) {
             const resp = await request("POST", `/api/w/${wiki_slug}/topics/batch`, {

package/dist/tools/wikis.js

@@ -1,18 +1,6 @@
 import { z } from "zod";
 import { request } from "../auth.js";
-function coerceJson(schema) {
-    return z.preprocess((val) => {
-        if (typeof val === "string") {
-            try {
-                return JSON.parse(val);
-            }
-            catch {
-                return val;
-            }
-        }
-        return val;
-    }, schema);
-}
+import { coerceJson } from "../utils.js";
 // Mirrors backend `NavItem` in src/schemas/wiki_settings_schemas.py. The
 // refinement matches the `exactly_one_target` @model_validator there —
 // agents get a clear error pre-flight instead of a 422 round-trip.
@@ -94,7 +82,7 @@ export function registerWikiTools(server) {
     });
     server.addTool({
         name: "update_wiki_settings",
-        description: "Update a wiki's settings (nav, cover_image_url, theme). Each NavItem must have exactly one of `page`, `topic`, or `link`. Use `auto` (only on topic items) to auto-populate children from the topic DAG. Requires moderator access.",
+        description: "Update a wiki's settings. Pass any combination of `nav`, `cover_image_url`, and `theme` — omitted fields are preserved (the backend uses exclude_unset merge). For example, `{nav: [...]}` updates navigation only without touching theme or cover_image_url. Each NavItem must have exactly one of `page`, `topic`, or `link`. Use `auto` (only on topic items) to auto-populate children from the topic DAG. Requires moderator access.",
         parameters: z.object({
             wiki_slug: z.string().describe("Wiki slug"),
             settings: coerceJson(z.object({
@@ -112,22 +100,32 @@ export function registerWikiTools(server) {
         },
     });
     server.addTool({
-        name: "update_nav",
-        description: "Update just the navigation tree for a wiki. Shorthand for updating settings.nav. Requires moderator access.",
+        name: "join_wiki",
+        description: "Join a wiki as a member. After joining you can create and edit pages. Requires login.",
         parameters: z.object({
             wiki_slug: z.string().describe("Wiki slug"),
-            nav: coerceJson(z.array(navItemSchema)).describe("Nav items"),
         }),
-        async execute({ wiki_slug, nav }) {
-            // Single atomic PATCH — the backend's update_settings service uses
-            // model_dump(exclude_unset=True) to merge partial bodies, so sending
-            // only {nav} doesn't touch theme or cover_image_url. Previously this
-            // did a GET-then-PATCH, which raced with concurrent settings updates.
-            const resp = await request("PATCH", `/api/w/${wiki_slug}/settings`, {
-                auth: true,
-                json: { nav },
-            });
-            return JSON.stringify(await resp.json(), null, 2);
+        async execute({ wiki_slug }) {
+            const resp = await request("POST", `/api/w/${wiki_slug}/join`, { auth: true });
+            const data = (await resp.json());
+            const role = data.role ?? "member";
+            return `Joined wiki "${wiki_slug}" as ${role}.`;
+        },
+    });
+    server.addTool({
+        name: "get_wiki_membership",
+        description: "Check your membership status in a wiki. Returns your role if you are a member. Requires login.",
+        parameters: z.object({
+            wiki_slug: z.string().describe("Wiki slug"),
+        }),
+        async execute({ wiki_slug }) {
+            const resp = await request("GET", `/api/w/${wiki_slug}/membership/me`, { auth: true });
+            const data = (await resp.json());
+            if (!data.is_member) {
+                return `You are not a member of "${wiki_slug}".`;
+            }
+            const role = data.role ?? "member";
+            return `You are a member of "${wiki_slug}" as ${role}.`;
         },
     });
 }

package/dist/utils.d.ts

@@ -0,0 +1,7 @@
+import { z } from "zod";
+/**
+ * Workaround for Claude Agent SDK MCP transport bug (#18260):
+ * Array/object parameters are sometimes serialized as JSON strings
+ * instead of native values. This preprocessor coerces them back.
+ */
+export declare function coerceJson<T extends z.ZodTypeAny>(schema: T): z.ZodEffects<T, T["_output"], unknown>;

package/dist/utils.js

@@ -0,0 +1,19 @@
+import { z } from "zod";
+/**
+ * Workaround for Claude Agent SDK MCP transport bug (#18260):
+ * Array/object parameters are sometimes serialized as JSON strings
+ * instead of native values. This preprocessor coerces them back.
+ */
+export function coerceJson(schema) {
+    return z.preprocess((val) => {
+        if (typeof val === "string") {
+            try {
+                return JSON.parse(val);
+            }
+            catch {
+                return val;
+            }
+        }
+        return val;
+    }, schema);
+}

package/package.json

@@ -1,22 +1,30 @@
 {
   "name": "openalmanac",
-  "version": "0.3.5",
-  "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

package/dist/tools/articles.d.ts

@@ -1,2 +0,0 @@
-import { FastMCP } from "fastmcp";
-export declare function registerArticleTools(server: FastMCP): void;