openalmanac 0.2.59 → 0.3.2

package/dist/setup.js

@@ -166,6 +166,7 @@ const SUPPORTED_CLIENTS = {
     "claude-code": {
         id: "claude-code",
         name: "Claude Code",
+        selectionLabel: "Claude Code",
         detect: () => hasCommand("claude") || existsSync(CLAUDE_JSON) || existsSync(CLAUDE_DIR),
         configure: (mode) => {
             const snippets = [
@@ -195,6 +196,7 @@ const SUPPORTED_CLIENTS = {
     "claude-desktop": {
         id: "claude-desktop",
         name: "Claude Desktop",
+        selectionLabel: "Claude Desktop",
         detect: () => {
             const path = getClaudeDesktopConfigPath();
             return Boolean(path && (existsSync(path) || isClaudeDesktopInstalled()));
@@ -221,6 +223,7 @@ const SUPPORTED_CLIENTS = {
     codex: {
         id: "codex",
         name: "Codex",
+        selectionLabel: "Codex",
         detect: () => hasCommand("codex") || existsSync(CODEX_CONFIG) || existsSync(join(homedir(), ".codex")),
         configure: (mode) => ({
             changed: configureCodexToml(CODEX_CONFIG, mode),
@@ -235,6 +238,7 @@ const SUPPORTED_CLIENTS = {
     cursor: {
         id: "cursor",
         name: "Cursor",
+        selectionLabel: "Cursor",
         detect: () => hasCommand("cursor-agent") ||
             existsSync(CURSOR_MCP_JSON) ||
             existsSync(join(homedir(), ".cursor")),
@@ -255,6 +259,7 @@ const SUPPORTED_CLIENTS = {
     windsurf: {
         id: "windsurf",
         name: "Windsurf",
+        selectionLabel: "Windsurf",
         detect: () => hasCommand("windsurf") ||
             existsSync(WINDSURF_MCP_JSON) ||
             existsSync(join(homedir(), ".codeium")),
@@ -550,29 +555,30 @@ function configurePermissions(tools) {
         writeJson(SETTINGS_JSON, settings);
     return tools.length;
 }
-/* ── Agent selection screen ─────────────────────────────────────── */
-function renderAgentSelect(_cursor, mode = "default") {
+/* ── Client selection screen ────────────────────────────────────── */
+function renderClientSelect(clients, selected, cursor, mode = "default") {
     process.stdout.write("\x1b[2J\x1b[H");
     renderHeader(mode);
     printBadge();
     w("");
-    stepActive(`Select your agent`);
+    stepActive(`Select where to install Almanac`);
     w(BAR);
-    for (const agent of AGENTS) {
-        if (agent.supported) {
-            w(`  ${DIM}\u2502${RST}   ${BLUE}\u276f${RST} ${BLUE}\u25cf${RST} ${BOLD}${agent.name}${RST}`);
-        }
-        else {
-            w(`  ${DIM}\u2502${RST}     ${DIM}\u25cb ${agent.name}${"  "}coming soon${RST}`);
-        }
+    for (let i = 0; i < clients.length; i++) {
+        const client = clients[i];
+        const arrow = i === cursor ? `${BLUE}\u276f${RST}` : " ";
+        const check = selected[i] ? `${BLUE}\u2713${RST}` : " ";
+        const label = i === cursor ? `${BOLD}${client.selectionLabel ?? client.name}${RST}` : client.selectionLabel ?? client.name;
+        w(`  ${DIM}\u2502${RST}   ${arrow} [${check}] ${label}`);
     }
     w(BAR);
-    w(`  ${DIM}\u2502${RST}   ${BLUE}${BOLD}[enter]${RST} confirm  ${DIM}[q] quit${RST}`);
+    w(`  ${DIM}\u2502${RST}   ${BLUE}${BOLD}[space]${RST} toggle  ${BLUE}${BOLD}[\u2191\u2193]${RST} move  ${BLUE}${BOLD}[a]${RST} all  ${BLUE}${BOLD}[enter]${RST} confirm  ${DIM}[q] quit${RST}`);
     w("");
 }
-function runAgentSelect(mode = "default") {
+function runClientSelect(clients, mode = "default") {
     return new Promise((resolve) => {
-        renderAgentSelect(0, mode);
+        const selected = clients.map(() => true);
+        let cursor = 0;
+        renderClientSelect(clients, selected, cursor, mode);
         process.stdin.setRawMode(true);
         process.stdin.resume();
         process.stdin.setEncoding("utf-8");
@@ -588,16 +594,38 @@ function runAgentSelect(mode = "default") {
                 console.log("\n  Setup cancelled.\n");
                 process.exit(0);
             }
-            if (key === "\r" || key === "\n") {
+            if (key === "\x1b[A" || key === "k") {
+                cursor = (cursor - 1 + clients.length) % clients.length;
+            }
+            else if (key === "\x1b[B" || key === "j") {
+                cursor = (cursor + 1) % clients.length;
+            }
+            else if (key === " ") {
+                selected[cursor] = !selected[cursor];
+            }
+            else if (key === "a") {
+                const all = selected.every(Boolean);
+                selected.fill(!all);
+            }
+            else if (key === "\r" || key === "\n") {
                 cleanup();
-                const supported = AGENTS.find((a) => a.supported);
-                resolve(supported.name);
+                const chosen = clients.filter((_, index) => selected[index]);
+                if (chosen.length === 0) {
+                    console.log("\n  Select at least one client.\n");
+                    process.exit(1);
+                }
+                resolve(chosen);
                 return;
             }
+            renderClientSelect(clients, selected, cursor, mode);
         };
         process.stdin.on("data", onData);
     });
 }
+async function runAgentSelect(mode = "default") {
+    const [client] = await runClientSelect([SUPPORTED_CLIENTS["claude-code"]], mode);
+    return client.name;
+}
 /* ── Login step ─────────────────────────────────────────────────── */
 function loginLabel(result) {
     if (result.status === "already")
@@ -780,16 +808,16 @@ async function runLoginStep(agent, mcpChanged, toolCount, mode = "default") {
 }
 /* ── Tool permissions TUI ───────────────────────────────────────── */
 const MAX_NAME = Math.max(...TOOL_GROUPS.map((g) => g.name.length));
-function renderToolSelect(selected, cursor, agent, mcpChanged, mode = "default") {
+function renderToolSelect(selected, cursor, clientsLabel, mcpChanged, mode = "default") {
     process.stdout.write("\x1b[2J\x1b[H");
     renderHeader(mode);
     printBadge();
     w("");
-    stepDone(`Agent \u2192 ${WHITE_BOLD}${agent}${RST}`);
+    stepDone(`Clients \u2192 ${WHITE_BOLD}${clientsLabel}${RST}`);
     w(BAR);
     stepDone(`MCP server ${mcpChanged ? "configured" : `${DIM}already configured${RST}`}`);
     w(BAR);
-    stepActive(`Select tool permissions  ${DIM}deselect any you'd rather approve manually${RST}`);
+    stepActive(`Select Claude Code tool permissions  ${DIM}deselect any you'd rather approve manually${RST}`);
     w(BAR);
     for (let i = 0; i < TOOL_GROUPS.length; i++) {
         const arrow = i === cursor ? `${BLUE}\u276f${RST}` : " ";
@@ -803,11 +831,11 @@ function renderToolSelect(selected, cursor, agent, mcpChanged, mode = "default")
     w(`  ${DIM}\u2502${RST}   ${BLUE}${BOLD}[space]${RST} toggle  ${BLUE}${BOLD}[\u2191\u2193]${RST} move  ${BLUE}${BOLD}[a]${RST} all  ${BLUE}${BOLD}[enter]${RST} confirm  ${DIM}[q] quit${RST}`);
     w("");
 }
-function runToolSelect(agent, mcpChanged, mode = "default") {
+function runToolSelect(clientsLabel, mcpChanged, mode = "default") {
     return new Promise((resolve) => {
         const selected = TOOL_GROUPS.map(() => true);
         let cursor = 0;
-        renderToolSelect(selected, cursor, agent, mcpChanged, mode);
+        renderToolSelect(selected, cursor, clientsLabel, mcpChanged, mode);
         process.stdin.setRawMode(true);
         process.stdin.resume();
         process.stdin.setEncoding("utf-8");
@@ -843,7 +871,7 @@ function runToolSelect(agent, mcpChanged, mode = "default") {
                 resolve(tools);
                 return;
             }
-            renderToolSelect(selected, cursor, agent, mcpChanged, mode);
+            renderToolSelect(selected, cursor, clientsLabel, mcpChanged, mode);
         };
         process.stdin.on("data", onData);
     });
@@ -926,7 +954,7 @@ function getNextSteps(clientsLabel) {
 /* ── Entry point ────────────────────────────────────────────────── */
 export async function runSetup() {
     const options = parseSetupArgs(process.argv.slice(3));
-    const clients = resolveClients(options);
+    let clients = resolveClients(options);
     if (options.print || options.dryRun) {
         printSetupPlan(clients, options);
         process.exit(0);
@@ -937,13 +965,17 @@ export async function runSetup() {
     }
     const skipTui = options.yes;
     const interactive = process.stdin.isTTY && !skipTui;
+    if (interactive && options.clients.length === 0) {
+        clients = await runClientSelect(clients);
+    }
+    const clientsLabel = clients.map((client) => client.name).join(", ");
     const setupSummary = applyClientSetup(clients, "apply");
     const permissionClient = clients.find((client) => client.supportsPermissions);
     let tools = [];
     if (permissionClient) {
         const mcpChanged = setupSummary.configured.includes(permissionClient.name);
         if (interactive) {
-            tools = await runToolSelect(permissionClient.name, mcpChanged);
+            tools = await runToolSelect(clientsLabel, mcpChanged);
         }
         else {
             tools = TOOL_GROUPS.flatMap((g) => g.tools);
@@ -952,7 +984,6 @@ export async function runSetup() {
     const count = tools.length > 0 ? configurePermissions(tools) : 0;
     const permissionCount = permissionClient ? count : null;
     let loginResult;
-    const clientsLabel = clients.map((client) => client.name).join(", ");
     if (interactive) {
         loginResult = await runLoginStep(clientsLabel, setupSummary.configured.length > 0, permissionCount);
     }

package/dist/tools/research.js

@@ -20,30 +20,79 @@ function coerceJson(schema) {
     }, schema);
 }
 export function registerResearchTools(server) {
+    // Discriminated union on `source` — each source's schema only surfaces its own
+    // options, so agents get typed autocomplete instead of an opaque options bag.
+    //
+    // Adding a new source (e.g. hackernews) = append another z.object variant with
+    // its own `source: z.literal(...)` and per-source fields. No existing schema
+    // changes.
+    const WebSearchInput = z.object({
+        source: z.literal("web").describe("Generic web search via Google/Serper. Use for general references, news, docs."),
+        query: z.string().min(1).describe("Search terms. Supports quoted phrases and site: operators."),
+        limit: z.number().int().min(1).max(20).default(10).describe("Max results (1-20, default 10)."),
+    });
+    const RedditSearchInput = z.object({
+        source: z.literal("reddit").describe("Search Reddit — use when the user wants community perspectives, subreddit consensus, lived experiences, or ranked-by-engagement content. Goes through a residential proxy so it sees past Reddit's anti-scraping."),
+        subreddit: z.string().optional().describe("Subreddit name without the 'r/' prefix (e.g. 'Harvard'). Omit to search across all of Reddit. Case-insensitive."),
+        query: z.string().optional().describe("Optional full-text search terms. Omit to return the subreddit's sorted listing (top posts of the year, etc.)."),
+        sort: z.enum(["top", "hot", "new", "rising", "controversial", "relevance", "comments"])
+            .default("top")
+            .describe("For listings: 'top'/'hot'/'new'/'rising'/'controversial'. For searches: 'relevance'/'top'/'new'/'comments'. Default 'top'."),
+        time_range: z.enum(["hour", "day", "week", "month", "year", "all"])
+            .default("year")
+            .describe("Time window for top/controversial listings and all searches. Default 'year'."),
+        limit: z.number().int().min(1).max(100).default(25).describe("Max posts to return (1-100, default 25)."),
+    });
     server.addTool({
         name: "search_web",
-        description: "Search the web for sources to cite in articles. Use this to find references before writing. Requires API key. Rate limit: 10/min.",
-        parameters: z.object({
-            query: z.string().describe("Search terms"),
-            limit: z.number().default(10).describe("Max results (1-20, default 10)"),
-        }),
-        async execute({ query, limit }) {
+        description: "Search the web or a specific community source (Reddit). Discriminated on `source`:\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" +
+            "Each source exposes its own parameters — follow the schema for the source you pick. " +
+            "Rate limit: 10/min. Requires API key.",
+        parameters: z.discriminatedUnion("source", [WebSearchInput, RedditSearchInput]),
+        async execute(input) {
+            if (input.source === "reddit") {
+                const params = {
+                    sort: input.sort,
+                    time_range: input.time_range,
+                    limit: input.limit,
+                };
+                if (input.subreddit)
+                    params.subreddit = input.subreddit;
+                if (input.query)
+                    params.query = input.query;
+                const resp = await request("GET", "/api/research/reddit/search", {
+                    auth: true,
+                    params,
+                });
+                return JSON.stringify(await resp.json(), null, 2);
+            }
             const resp = await request("GET", "/api/research/search", {
                 auth: true,
-                params: { query, limit },
+                params: { query: input.query, limit: input.limit },
             });
             return JSON.stringify(await resp.json(), null, 2);
         },
     });
     server.addTool({
         name: "read_webpage",
-        description: "Fetch a webpage and return its content as markdown. Use this to read sources found via search_web before citing them in articles. Supports web pages, PDFs, and YouTube videos. Requires API key. Rate limit: 5/min.",
+        description: "Fetch a 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" +
+            "- **YouTube videos** — returns title, description, transcript when available.\n" +
+            "- **PDFs** — extracts text.\n" +
+            "- **LinkedIn posts/profiles** — uses the LinkedIn scraper.\n" +
+            "- **Everything else** — generic web scrape with Firecrawl/Jina fallback.\n\n" +
+            "Requires API key. Rate limit: 5/min.",
         parameters: z.object({
-            url: z.string().describe("URL to read"),
+            url: z.string().url().describe("Full URL to read. For Reddit threads, use the canonical reddit.com/r/{sub}/comments/{id}/... form."),
             max_length: z
                 .number()
+                .int()
+                .min(1000)
                 .default(20000)
-                .describe("Max characters to return (default 20000). Use higher values for long-form sources."),
+                .describe("Max characters to return (default 20000). Increase for long-form sources; response is truncated with a note when it hits the cap."),
         }),
         async execute({ url, max_length }) {
             const resp = await request("GET", "/api/research/read", {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openalmanac",
-  "version": "0.2.59",
+  "version": "0.3.2",
   "description": "OpenAlmanac — pull, edit, and push articles to the open knowledge base",
   "type": "module",
   "bin": {

package/dist/tools/articles.d.ts

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

package/dist/tools/articles.js

@@ -1,401 +0,0 @@
-import { z } from "zod";
-import { readFileSync, writeFileSync, mkdirSync, readdirSync, statSync, existsSync, unlinkSync } from "node:fs";
-import { join } from "node:path";
-import { stringify as yamlStringify } from "yaml";
-import { request, ARTICLES_DIR, getAuthStatus } from "../auth.js";
-import { validateArticle, parseFrontmatter } from "../validate.js";
-import { openBrowser } from "../browser.js";
-const SLUG_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
-const WRITING_GUIDE = `
-## Article structure
-
-\`\`\`yaml
----
-article_id: the-slug
-title: Article Title
-sources:
-  - key: example-source-title
-    url: https://example.com
-    title: Source Title
-    accessed_date: "2025-01-15"
-infobox:
-  header:
-    image_url: https://...         # optional hero image
-    subtitle: Short tagline
-    details:
-      - key: Born
-        value: January 1, 1990
-      - key: Occupation
-        value: Scientist
-    links:
-      - https://example.com
-  sections:
-    - type: timeline               # chronological events
-      title: Career Timeline
-      items:
-        - primary: "Started company"
-          period: "2010"
-          location: "San Francisco"
-    - type: list                   # key figures, works, features
-      title: Known For
-      items:
-        - title: First achievement
-        - title: Second achievement
-          subtitle: Additional detail
-    - type: tags                   # inline tags/chips
-      title: Genres
-      items:
-        - Rock
-        - Jazz
-    - type: grid                   # image grid
-      title: Gallery
-      items:
-        - title: Caption
-          image_url: https://...
-    - type: table                  # structured comparison
-      title: Statistics
-      items:
-        headers:
-          - Name
-          - Value
-        rows:
-          - cells:
-              - Height
-              - "6'2\\""
-    - type: key_value              # simple key-value pairs
-      title: Quick Facts
-      items:
-        - key: Population
-          value: "1.4 billion"
----
-
-Article body with [@key] citation markers...
-\`\`\`
-
-## Infobox
-
-Include an infobox for any article about a person, place, organization, event, or concept. Pick the section types that fit — you don't need all six.
-
-## Citations
-
-- Mark claims with [@key] after punctuation: "The population is 1.4 billion.[@who-world-population]"
-- Keys must be kebab-case with at least one hyphen (e.g. 'nytimes-climate-report', 'who-malaria-2024')
-- Generate keys BibTeX-style: {domain}-{title-words} (e.g. 'arxiv-attention-is-all')
-- Every source in the sources list must be referenced at least once in the body with [@key]
-- Every [@key] marker must have a matching source with that key
-- Display numbers are computed automatically from first-appearance order — just use the keys
-
-## Images
-
-Use search_images to find relevant images. Images render as figures with visible captions.
-
-**Syntax:** \`![Caption text](url "position")\`
-
-Positions: \`"right"\` (default if omitted), \`"left"\`, \`"center"\`
-
-\`\`\`markdown
-![Alan Turing in 1930, aged 18](https://upload.wikimedia.org/...)
-
-The early life of Alan Turing began...
-
-![Panoramic view of Bletchley Park](https://upload.wikimedia.org/... "center")
-\`\`\`
-
-**Caption rules:**
-- Every image MUST have a descriptive caption — it is displayed below the image
-- Describe what the image shows: "Alan Turing in 1930, aged 18" not "Photo"
-- Include dates, context, or attribution when relevant
-
-**Placement:** 1-3 images per major section, spread throughout. First image near the top.
-For the infobox hero image, use \`infobox.header.image_url\` in frontmatter instead.
-
-External image URLs are auto-persisted on publish — no extra steps needed.
-
-## Writing quality
-
-- Every sentence should contain a specific fact the reader didn't know
-- No filler phrases ("It is worth noting", "In today's world", "Throughout history")
-- No promotional language ("revolutionary", "groundbreaking", "game-changing")
-- No inflated significance ("one of the most important", "changed the world forever")
-- No vague attribution ("many experts say", "it is widely regarded")
-- No formulaic conclusions ("In conclusion", "continues to shape")
-- Write like a concise encyclopedia, not a blog post
-`.trim();
-function ensureArticlesDir() {
-    mkdirSync(ARTICLES_DIR, { recursive: true });
-}
-export function registerArticleTools(server) {
-    server.addTool({
-        name: "search_articles",
-        description: "Search existing OpenAlmanac articles and stubs. Accepts multiple queries for batch lookup. " +
-            "Use this to check if articles or stubs exist before creating them, or to find entity slugs for wikilinks. " +
-            "Results include 'stub' field (true/false) and 'entity_type' field. No authentication needed.",
-        parameters: z.object({
-            queries: z.array(z.string()).min(1).max(20).describe("Search queries (1-20)"),
-            limit: z.number().default(5).describe("Max results per query (1-50, default 5)"),
-            include_stubs: z.boolean().default(true).describe("Include stub articles in results (default true)"),
-        }),
-        async execute({ queries, limit, include_stubs }) {
-            const resp = await request("POST", "/api/search/batch", {
-                json: { queries, limit, include_stubs },
-            });
-            return JSON.stringify(await resp.json(), null, 2);
-        },
-    });
-    server.addTool({
-        name: "read",
-        description: "Read article content from OpenAlmanac. Returns the content, sources, and metadata for each slug. " +
-            "Use this to reference or summarize existing articles in conversation. " +
-            "For editing articles locally, use 'download' instead. No authentication needed.",
-        parameters: z.object({
-            slugs: z.array(z.string()).min(1).max(20).describe("Article slugs to read (1-20)"),
-        }),
-        async execute({ slugs }) {
-            const resp = await request("POST", "/api/articles/batch", {
-                json: { slugs },
-            });
-            return JSON.stringify(await resp.json(), null, 2);
-        },
-    });
-    server.addTool({
-        name: "create_stubs",
-        description: "Create stub articles — placeholders for entities that don't have full articles yet. " +
-            "Use this for every entity (person, organization, topic, etc.) mentioned in an article. " +
-            "Idempotent: existing slugs return their current status. Requires login.",
-        parameters: z.object({
-            stubs: z.array(z.object({
-                slug: z
-                    .string()
-                    .min(1)
-                    .max(500)
-                    .describe("Unique kebab-case identifier. For people with LinkedIn: use their vanity ID (e.g. 'john-smith-4a8b2c1'). " +
-                    "For others: descriptive kebab-case (e.g. 'reinforcement-learning', 'openai')"),
-                title: z.string().describe("Display title (e.g. 'John Smith', 'Reinforcement Learning')"),
-                entity_type: z
-                    .enum(["person", "organization", "topic", "event", "creative_work", "place"])
-                    .optional()
-                    .describe("Entity type: 'person' for individuals, 'organization' for companies/institutions/nonprofits, " +
-                    "'topic' for concepts/fields/technologies, 'event' for conferences/historical events, " +
-                    "'creative_work' for books/papers/films/software, 'place' for cities/countries/landmarks"),
-                headline: z
-                    .string()
-                    .optional()
-                    .describe("Short headline (e.g. 'Professor of CS at MIT', 'AI research laboratory')"),
-                image_url: z.string().url().optional().describe("Image URL for the entity"),
-                summary: z
-                    .string()
-                    .optional()
-                    .describe("2-4 sentence summary of the entity. This becomes the stub page content. " +
-                    "Be informative — include key facts, dates, and context."),
-            })).min(1).max(50).describe("Stubs to create (1-50)"),
-        }),
-        async execute({ stubs }) {
-            const resp = await request("POST", "/api/articles/stubs", {
-                auth: true,
-                json: { stubs },
-            });
-            return JSON.stringify(await resp.json(), null, 2);
-        },
-    });
-    server.addTool({
-        name: "download",
-        description: "Download an article to your local workspace for editing. The file is saved to ~/.openalmanac/articles/{slug}.md " +
-            "with YAML frontmatter. Returns a writing guide covering article structure, infobox format, citations, and quality rules. " +
-            "After editing, use 'publish' to push your changes live.",
-        parameters: z.object({
-            slug: z.string().describe("Article slug (e.g. 'machine-learning')"),
-        }),
-        async execute({ slug }) {
-            if (!SLUG_RE.test(slug)) {
-                throw new Error(`Invalid slug "${slug}". Must be kebab-case (e.g. 'machine-learning').`);
-            }
-            const resp = await request("GET", `/api/articles/${slug}`, {
-                params: { format: "md" },
-            });
-            const markdown = await resp.text();
-            ensureArticlesDir();
-            const filePath = join(ARTICLES_DIR, `${slug}.md`);
-            writeFileSync(filePath, markdown, "utf-8");
-            const originalPath = join(ARTICLES_DIR, `.${slug}.original.md`);
-            writeFileSync(originalPath, markdown, "utf-8");
-            const { frontmatter, content } = parseFrontmatter(markdown);
-            const title = frontmatter.title || "(untitled)";
-            const wordCount = content.trim().split(/\s+/).filter(Boolean).length;
-            const isStub = frontmatter.stub === true;
-            const stubNote = isStub
-                ? "\n\nThis is a STUB article — a placeholder that hasn't been fully written yet. " +
-                    "Fill in the content body with a complete article, then push to publish."
-                : "";
-            return `Downloaded "${title}" to ${filePath}\n${wordCount} words, ${frontmatter.sources?.length ?? 0} sources.${stubNote}\n\n${WRITING_GUIDE}`;
-        },
-    });
-    server.addTool({
-        name: "new",
-        description: "Create a new article scaffold in your local working directory (~/.openalmanac/articles/). " +
-            "The file is created with YAML frontmatter and an empty body. Returns a writing guide covering article structure, infobox format, citations, and quality rules. " +
-            "Edit the file to add content and sources, then use publish to go live.",
-        parameters: z.object({
-            slug: z
-                .string()
-                .describe("Unique kebab-case identifier (e.g. 'machine-learning'). Pattern: ^[a-z0-9]+(-[a-z0-9]+)*$"),
-            title: z.string().describe("Article title"),
-        }),
-        async execute({ slug, title }) {
-            if (!SLUG_RE.test(slug)) {
-                throw new Error(`Invalid slug "${slug}". Must be kebab-case (e.g. 'machine-learning'). Pattern: ^[a-z0-9]+(-[a-z0-9]+)*$`);
-            }
-            ensureArticlesDir();
-            const filePath = join(ARTICLES_DIR, `${slug}.md`);
-            if (existsSync(filePath)) {
-                throw new Error(`File already exists: ${filePath}\nUse download to refresh it, or publish to push changes.`);
-            }
-            const frontmatter = yamlStringify({ article_id: slug, title, sources: [] });
-            const scaffold = `---\n${frontmatter}---\n\n`;
-            writeFileSync(filePath, scaffold, "utf-8");
-            return `Created ${filePath}\n\n${WRITING_GUIDE}`;
-        },
-    });
-    server.addTool({
-        name: "publish",
-        description: "Validate and publish an article from your local workspace. Reads ~/.openalmanac/articles/{slug}.md, " +
-            "validates content and sources, and publishes to OpenAlmanac. Requires login.",
-        parameters: z.object({
-            slug: z.string().describe("Article slug matching the filename (without .md)"),
-            change_title: z.string().optional().describe("Short title for the change (e.g. 'Added early life section')"),
-            change_description: z.string().optional().describe("Longer description of what changed and why"),
-        }),
-        async execute({ slug, change_title, change_description }) {
-            if (!SLUG_RE.test(slug)) {
-                throw new Error(`Invalid slug "${slug}". Must be kebab-case (e.g. 'machine-learning').`);
-            }
-            const filePath = join(ARTICLES_DIR, `${slug}.md`);
-            let raw;
-            try {
-                raw = readFileSync(filePath, "utf-8");
-            }
-            catch {
-                throw new Error(`File not found: ${filePath}\nUse download to get an existing article or new to create a scaffold.`);
-            }
-            // Local validation
-            const errors = validateArticle(raw);
-            if (errors.length > 0) {
-                const lines = errors.map((e) => `  ${e.field}: ${e.message}`);
-                throw new Error(`Validation failed (${errors.length} error${errors.length > 1 ? "s" : ""}):\n${lines.join("\n")}\n\nFix the file and try again.`);
-            }
-            // Inject change_title/change_description into frontmatter if provided
-            let body = raw;
-            if (change_title || change_description) {
-                const { frontmatter, content } = parseFrontmatter(raw);
-                if (change_title)
-                    frontmatter.change_title = change_title;
-                if (change_description)
-                    frontmatter.change_description = change_description;
-                const newFrontmatter = yamlStringify(frontmatter);
-                body = `---\n${newFrontmatter}---\n${content}`;
-            }
-            const resp = await request("PUT", `/api/articles/${slug}`, {
-                auth: true,
-                body,
-                contentType: "text/markdown",
-            });
-            const data = (await resp.json());
-            const articleUrl = `https://www.openalmanac.org/article/${slug}?celebrate=true`;
-            openBrowser(articleUrl);
-            // Clean up local files after successful publish
-            let cleanupWarning = "";
-            try {
-                unlinkSync(filePath);
-            }
-            catch (e) {
-                if (e.code !== "ENOENT") {
-                    cleanupWarning = `\nNote: could not remove local draft: ${e.message}`;
-                }
-            }
-            try {
-                unlinkSync(join(ARTICLES_DIR, `.${slug}.original.md`));
-            }
-            catch (e) {
-                if (e.code !== "ENOENT") {
-                    cleanupWarning += `\nNote: could not remove original copy: ${e.message}`;
-                }
-            }
-            return `Pushed successfully.\n\nArticle URL (share this exact link with the user): ${articleUrl}${cleanupWarning}\n\n${JSON.stringify(data, null, 2)}`;
-        },
-    });
-    server.addTool({
-        name: "requested_articles",
-        description: "List requested articles — stubs that are referenced by the most articles but haven't been fully written yet. " +
-            "Use this to find high-demand topics to write about. No authentication needed.",
-        parameters: z.object({
-            limit: z.number().default(20).describe("Max results (1-200, default 20)"),
-            offset: z.number().default(0).describe("Pagination offset (default 0)"),
-        }),
-        async execute({ limit, offset }) {
-            const resp = await request("GET", "/api/articles/requested", {
-                params: { limit, offset },
-            });
-            return JSON.stringify(await resp.json(), null, 2);
-        },
-    });
-    server.addTool({
-        name: "propose_article",
-        description: "Propose an article before writing it. Call this when you've researched enough and a specific article topic has come into focus. " +
-            "Structures your proposal with a user-facing summary and a detailed brief. " +
-            "The client environment determines what happens next — in GUI environments the user sees a plan card with options, " +
-            "in CLI environments you'll get a response telling you to proceed with writing. " +
-            "Do not start writing an article without proposing first.",
-        parameters: z.object({
-            summary: z.string().describe("User-facing summary: title, key sections, angle. Markdown. Concise — 3-5 bullet points."),
-            details: z.string().describe("Full handoff brief for the background agent. Include: all sources, key facts, user preferences, angle, what to avoid, related articles. Be thorough."),
-            title: z.string().describe("Proposed article title"),
-            slug: z.string().describe("Proposed article slug (kebab-case)"),
-            _userChoice: z.enum(["background", "here", "expired", "already_in_progress"]).optional().describe("Internal field set by GUI client. Never set this manually."),
-        }),
-        async execute({ summary, details, title, slug, _userChoice }) {
-            if (!SLUG_RE.test(slug)) {
-                throw new Error(`Invalid slug "${slug}". Must be kebab-case (e.g. 'machine-learning'). Pattern: ^[a-z0-9]+(-[a-z0-9]+)*$`);
-            }
-            if (_userChoice === "background") {
-                return `Article "${title}" is now being written in a background process. Continue exploring with the user. Do not write this article in this conversation.`;
-            }
-            if (_userChoice === "expired") {
-                return `The user navigated away before responding to the proposal. Proposal expired. Continue the conversation naturally.`;
-            }
-            if (_userChoice === "already_in_progress") {
-                return `Article "${title}" is already being generated in a background process. No action needed.`;
-            }
-            // "here" OR no _userChoice (CLI default) — proceed with writing
-            return `Article Proposal: ${title}\n\n${summary}\n\nProceed with writing this article following the writing flow in your instructions.`;
-        },
-    });
-    server.addTool({
-        name: "status",
-        description: "Show login status and list all article files in your local working directory (~/.openalmanac/articles/). " +
-            "Shows auth state, filename, title, file size, and last modified time.",
-        async execute() {
-            ensureArticlesDir();
-            const auth = await getAuthStatus();
-            const authLine = auth.loggedIn
-                ? `Logged in as ${auth.name}.`
-                : "Not logged in. Use login to authenticate.";
-            const files = readdirSync(ARTICLES_DIR).filter((f) => f.endsWith(".md") && !f.startsWith("."));
-            if (files.length === 0) {
-                return `${authLine}\n\nLocal articles (0 files in ${ARTICLES_DIR}):\n  (none — use download or new to get started)`;
-            }
-            const rows = [];
-            for (const file of files) {
-                const filePath = join(ARTICLES_DIR, file);
-                const stat = statSync(filePath);
-                const raw = readFileSync(filePath, "utf-8");
-                const { frontmatter } = parseFrontmatter(raw);
-                const title = frontmatter.title || "(untitled)";
-                const size = stat.size < 1024
-                    ? `${stat.size}B`
-                    : `${(stat.size / 1024).toFixed(1)}KB`;
-                const modified = stat.mtime.toISOString().slice(0, 16).replace("T", " ");
-                rows.push(`  ${file}  —  "${title}"  (${size}, modified ${modified})`);
-            }
-            return `${authLine}\n\nLocal articles (${files.length} file(s) in ${ARTICLES_DIR}):\n${rows.join("\n")}`;
-        },
-    });
-}

package/dist/tools/communities.d.ts

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

package/dist/tools/communities.js

@@ -1,127 +0,0 @@
-import { z } from "zod";
-import { request } from "../auth.js";
-export function registerCommunityTools(server) {
-    server.addTool({
-        name: "search_communities",
-        description: "Search or list OpenAlmanac communities. Returns community names, descriptions, and member counts. " +
-            "Use this after pushing an article to find relevant communities for auto-linking. No authentication needed.",
-        parameters: z.object({
-            query: z
-                .string()
-                .optional()
-                .describe("Search term (case-insensitive match on name, slug, or description). Omit to list all."),
-            sort: z
-                .enum(["popular", "newest"])
-                .default("popular")
-                .describe("Sort order (default: popular)"),
-            limit: z
-                .number()
-                .min(1)
-                .max(100)
-                .default(20)
-                .describe("Max results (1-100, default 20)"),
-        }),
-        async execute({ query, sort, limit }) {
-            const params = { sort, limit };
-            if (query)
-                params.query = query;
-            const resp = await request("GET", "/api/communities", { params });
-            const data = (await resp.json());
-            const communities = data.communities.map((c) => ({
-                slug: c.slug,
-                name: c.name,
-                description: c.description,
-                member_count: c.member_count,
-                created_at: c.created_at,
-            }));
-            return `Found ${data.total} communities:\n\n${JSON.stringify(communities, null, 2)}`;
-        },
-    });
-    server.addTool({
-        name: "create_community",
-        description: "Create a new OpenAlmanac community. Requires login and at least 1 published article. " +
-            "Communities are spaces where articles can be curated and discussed around a topic.",
-        parameters: z.object({
-            name: z.string().min(1).max(100).describe("Community name (1-100 chars)"),
-            slug: z
-                .string()
-                .min(1)
-                .max(100)
-                .regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/)
-                .describe("Unique kebab-case identifier (e.g. 'machine-learning')"),
-            description: z
-                .string()
-                .min(1)
-                .max(2000)
-                .describe("What the community is about (1-2000 chars)"),
-        }),
-        async execute({ name, slug, description }) {
-            const resp = await request("POST", "/api/communities", {
-                auth: true,
-                json: { name, slug, description },
-            });
-            const data = (await resp.json());
-            const communityUrl = `https://www.openalmanac.org/communities/${slug}`;
-            return `Community created!\n\nURL: ${communityUrl}\n\n${JSON.stringify(data, null, 2)}`;
-        },
-    });
-    server.addTool({
-        name: "create_post",
-        description: "Create a post in an OpenAlmanac community. Requires login and community membership. " +
-            "If you get a 403 error, you need to join the community first.",
-        parameters: z.object({
-            community_slug: z.string().describe("Community slug (e.g. 'machine-learning')"),
-            title: z.string().min(1).max(300).describe("Post title (1-300 chars)"),
-            body: z.string().max(10000).default("").describe("Post body (max 10000 chars)"),
-            flair: z
-                .enum(["discussion", "article-request", "question", "announcement"])
-                .optional()
-                .describe("Post flair/category"),
-        }),
-        async execute({ community_slug, title, body, flair }) {
-            const json = { title, body };
-            if (flair)
-                json.flair = flair;
-            const resp = await request("POST", `/api/communities/${community_slug}/posts`, {
-                auth: true,
-                json,
-            });
-            const data = (await resp.json());
-            const postUrl = `https://www.openalmanac.org/communities/${community_slug}/post/${data.id}`;
-            return `Post created!\n\nURL: ${postUrl}\n\n${JSON.stringify(data, null, 2)}`;
-        },
-    });
-    server.addTool({
-        name: "link_article",
-        description: "Link an article to one or more communities. Use this after pushing an article to connect it " +
-            "with relevant communities. Call search_communities first to find matching communities. " +
-            "Idempotent — already-linked articles are reported but don't cause errors. Requires login.",
-        parameters: z.object({
-            article_id: z.string().describe("Article slug/ID to link (e.g. 'machine-learning')"),
-            community_slugs: z
-                .array(z.string())
-                .min(1)
-                .max(50)
-                .describe("List of community slugs to link the article to (max 50)"),
-        }),
-        async execute({ article_id, community_slugs }) {
-            const resp = await request("POST", `/api/articles/${article_id}/auto-link`, {
-                auth: true,
-                json: { community_slugs },
-            });
-            const data = (await resp.json());
-            const lines = [];
-            if (data.linked.length > 0) {
-                lines.push(`Linked to ${data.linked.length} communities: ${data.linked.join(", ")}`);
-            }
-            if (data.failed.length > 0) {
-                const failLines = data.failed.map((f) => `  ${f.slug}: ${f.reason}`);
-                lines.push(`Failed (${data.failed.length}):\n${failLines.join("\n")}`);
-            }
-            if (lines.length === 0) {
-                lines.push("No communities to link.");
-            }
-            return lines.join("\n\n");
-        },
-    });
-}

package/dist/tools/people.d.ts

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

package/dist/tools/people.js

@@ -1,20 +0,0 @@
-import { z } from "zod";
-import { request } from "../auth.js";
-export function registerPeopleTools(server) {
-    server.addTool({
-        name: "search_people",
-        description: "Search for people to find their canonical slug for linking. Returns candidates with name, headline, " +
-            "image, and location. Use the returned slug when creating stubs and [[links]] for people. Requires login.",
-        parameters: z.object({
-            query: z.string().describe("Search terms (e.g. 'John Smith MIT professor')"),
-            limit: z.number().min(1).max(10).default(5).describe("Max results (1-10, default 5)"),
-        }),
-        async execute({ query, limit }) {
-            const resp = await request("GET", "/api/people/search", {
-                auth: true,
-                params: { query, limit },
-            });
-            return JSON.stringify(await resp.json(), null, 2);
-        },
-    });
-}