openalmanac 0.3.6 → 0.4.1

package/dist/tools/pages/writing-guide.js

@@ -0,0 +1,56 @@
+export const WRITING_GUIDE = `
+## Page structure
+
+\`\`\`yaml
+---
+title: Page Title
+wiki: wiki-slug
+topics: [topic-one, topic-two]
+sources:
+  - key: example-source
+    url: https://example.com
+    title: Source Title
+    accessed_date: "2025-01-15"
+infobox:
+  header:
+    image_url: https://...
+    subtitle: Short tagline
+    details:
+      - key: Born
+        value: January 1, 1990
+---
+
+Page body with [@key] citation markers and [[wikilinks]]...
+\`\`\`
+
+## Wikilinks
+
+- Write natural text in double brackets: [[spool pins]], [[pin tumbler locks]]
+- Display text: [[spool-pins|spool pins]]
+- Cross-wiki: [[global:reddit|Reddit]], [[lockpicking:spool-pins|spool pins]]
+
+## Citations
+
+- Mark claims with [@key] after punctuation
+- Keys must be kebab-case with at least one hyphen
+- Every source must be referenced; every reference must have a source
+
+## Quoting
+
+For any string value with punctuation, quotes, or special characters (common in \`sources[].title\`), use YAML block-literal syntax:
+
+\`\`\`yaml
+sources:
+  - key: farza-yc
+    title: |-
+      "I'm joining Y Combinator, again" — Farza Majeed
+    url: https://...
+\`\`\`
+
+This sidesteps every YAML escaping rule. If you skip this, inner double quotes or em-dashes will break the parser.
+
+## Images
+
+Use search_images to find relevant images. Syntax: \`![Caption](url "position")\`
+Positions: "right" (default), "left", "center". Every image needs a descriptive caption.
+`.trim();

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.1",
+  "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