openalmanac 0.2.28 → 0.2.30

package/dist/server.js

@@ -31,7 +31,7 @@ export function createServer() {
         name: "OpenAlmanac",
         version: pkg.version,
         instructions: [
-            "OpenAlmanac is an open knowledge base — a Wikipedia anyone can read from and write to through an API. Articles are markdown files with YAML frontmatter and [N] citation markers mapped to sources.",
+            "OpenAlmanac is an open knowledge base — a Wikipedia anyone can read from and write to through an API. Articles are markdown files with YAML frontmatter and [@key] citation markers mapped to named sources.",
             "",
             "## How this should feel",
             "",
@@ -95,28 +95,30 @@ export function createServer() {
             "",
             "## Writing flow",
             "",
-            "When the user agrees to write an article:",
+            "When you've researched enough and a specific article topic has come into focus:",
             "",
             '1. **Align briefly with the user** — Talk about what the article should cover, what to focus on, what angle to take. Not a rigid outline — a quick conversation. "I\'m thinking we cover the history, the Royal Brahmins, daily worship, and the Ramakien — anything you want to add or skip?"',
             "",
-            "2. **Read the writing guidelines** — Fetch https://www.openalmanac.org/writing-guidelines.md and https://www.openalmanac.org/ai-patterns-to-avoid.md before writing a single word.",
+            "2. **Propose the article** — Call `propose_article` with your summary (title, key sections, angle — 3-5 bullet points) and a detailed brief (all sources, key facts, user preferences, angle, what to avoid, related articles). Do not start writing an article without proposing first. The client environment determines what happens next — in some environments the user will see a plan card with options (write here vs. run in background), in others you'll get a text response telling you to proceed. Follow whatever the tool response says.",
             "",
-            "3. **Scaffold** — Use `new` to create the article file. List ALL sources you've gathered in the frontmatter before writing any body text. Don't discard sources — if you read it during research and it's relevant, include it.",
+            "3. **Read the writing guidelines** — Fetch https://www.openalmanac.org/writing-guidelines.md and https://www.openalmanac.org/ai-patterns-to-avoid.md before writing a single word.",
             "",
-            "4. **Write a pure text draft** — This whole process (writing, review, fact-check, images, linking) takes a few minutes. Let the user know in a fun way that they can step away — and that once it's ready, you're happy to discuss any edits or polishing.",
+            "4. **Scaffold** — Use `new` to create the article file. List ALL sources you've gathered in the frontmatter before writing any body text. Don't discard sources — if you read it during research and it's relevant, include it.",
             "",
-            "   Write the full article body with citation markers [N]. No wikilinks, no `[[slug|Display Text]]` syntax, no images, no stubs. Just prose and citations. The linking and images come later from subagents who need to read the finished text.",
+            "5. **Write a pure text draft** — This whole process (writing, review, fact-check, images, linking) takes a few minutes. Let the user know in a fun way that they can step away — and that once it's ready, you're happy to discuss any edits or polishing.",
             "",
-            "5. **Dispatch four subagents in parallel** — After the draft is complete, dispatch these simultaneously. Each agent has its own guidelines file — tell it to fetch and read that file as its first step. The guidelines file tells the agent what to do, what additional guidelines to fetch, and what format to return results in.",
+            "   Write the full article body with citation markers [@key]. No wikilinks, no `[[slug|Display Text]]` syntax, no images, no stubs. Just prose and citations. The linking and images come later from subagents who need to read the finished text.",
+            "",
+            "6. **Dispatch four subagents in parallel** — After the draft is complete, dispatch these simultaneously. Each agent has its own guidelines file — tell it to fetch and read that file as its first step. The guidelines file tells the agent what to do, what additional guidelines to fetch, and what format to return results in.",
             "",
             "   - **Review agent** → tell it to read https://www.openalmanac.org/review-guidelines.md and review the draft at `~/.openalmanac/articles/{slug}.md`",
             "   - **Fact-check agent** → tell it to read https://www.openalmanac.org/fact-checking-guidelines.md and fact-check the draft at `~/.openalmanac/articles/{slug}.md`",
             "   - **Image agent** → tell it to read https://www.openalmanac.org/image-guidelines.md and find images for the draft at `~/.openalmanac/articles/{slug}.md`",
             "   - **Linking agent** → tell it to read https://www.openalmanac.org/linking-guidelines.md and create stubs/wikilinks for the draft at `~/.openalmanac/articles/{slug}.md`",
             "",
-            "6. **Integrate** — Present the review and fact-check feedback to the user. Then fix everything in one pass: review issues, fact-check corrections, add images, add wikilinks.",
+            "7. **Integrate** — Present the review and fact-check feedback to the user. Then fix everything in one pass: review issues, fact-check corrections, add images, add wikilinks.",
             "",
-            "7. **Publish** — Validate and publish. Share the exact URL from the publish response (it includes a celebration page). Then search_communities for relevant communities and suggest linking.",
+            "8. **Publish** — Validate and publish. Share the exact URL from the publish response (it includes a celebration page). Then search_communities for relevant communities and suggest linking.",
             "",
             "Why this order: the draft must be finished before subagents run. The linking agent needs to see what entities are actually in the text. The image agent needs to match images to specific content. The review agent needs the complete article. Everything reads the draft.",
             "",

package/dist/setup.js

@@ -159,7 +159,7 @@ function configureMcp() {
     if (!desktop.mcpServers)
         desktop.mcpServers = {};
     if (!isAlmanacCurrent(desktop.mcpServers.almanac)) {
-        desktop.mcpServers.almanac = ALMANAC_MCP_ENTRY;
+        desktop.mcpServers.almanac = { ...ALMANAC_MCP_ENTRY };
         writeJson(CLAUDE_JSON, desktop);
         changed = true;
     }
@@ -170,7 +170,7 @@ function configureMcp() {
     if (!code.mcpServers)
         code.mcpServers = {};
     if (!isAlmanacCurrent(code.mcpServers.almanac)) {
-        code.mcpServers.almanac = ALMANAC_MCP_ENTRY;
+        code.mcpServers.almanac = { ...ALMANAC_MCP_ENTRY };
         writeJson(CLAUDE_CODE_MCP, code);
         changed = true;
     }
@@ -277,7 +277,7 @@ async function runLoginStep(agent, mcpChanged, toolCount) {
     const priorSteps = () => {
         stepDone(`Agent \u2192 ${WHITE_BOLD}${agent}${RST}`);
         w(BAR);
-        stepDone(`MCP server ${mcpChanged ? `added to ${DIM}~/.claude.json${RST}` : `${DIM}already configured${RST}`}`);
+        stepDone(`MCP server ${mcpChanged ? "configured" : `${DIM}already configured${RST}`}`);
         w(BAR);
         stepDone(`${BLUE}${toolCount}${RST} tool${toolCount !== 1 ? "s" : ""} allowed`);
         w(BAR);
@@ -431,7 +431,7 @@ function renderToolSelect(selected, cursor, agent, mcpChanged) {
     w("");
     stepDone(`Agent \u2192 ${WHITE_BOLD}${agent}${RST}`);
     w(BAR);
-    stepDone(`MCP server ${mcpChanged ? `added to ${DIM}~/.claude.json${RST}` : `${DIM}already configured${RST}`}`);
+    stepDone(`MCP server ${mcpChanged ? "configured" : `${DIM}already configured${RST}`}`);
     w(BAR);
     stepActive(`Select tool permissions  ${DIM}deselect any you'd rather approve manually${RST}`);
     w(BAR);
@@ -500,7 +500,7 @@ function printResult(agent, loginResult, mcpChanged, toolCount) {
     w("");
     stepDone(`Agent \u2192 ${WHITE_BOLD}${agent}${RST}`);
     w(BAR);
-    stepDone(`MCP server ${mcpChanged ? `added to ${DIM}~/.claude.json${RST}` : `${DIM}already configured${RST}`}`);
+    stepDone(`MCP server ${mcpChanged ? "configured" : `${DIM}already configured${RST}`}`);
     w(BAR);
     stepDone(`${BLUE}${toolCount}${RST} tool${toolCount !== 1 ? "s" : ""} allowed in ${DIM}~/.claude/settings.json${RST}`);
     w(BAR);

package/dist/tools/articles.js

@@ -14,7 +14,8 @@ const WRITING_GUIDE = `
 article_id: the-slug
 title: Article Title
 sources:
-  - url: https://example.com
+  - key: example-source-title
+    url: https://example.com
     title: Source Title
     accessed_date: "2025-01-15"
 infobox:
@@ -68,7 +69,7 @@ infobox:
           value: "1.4 billion"
 ---
 
-Article body with [1] citation markers...
+Article body with [@key] citation markers...
 \`\`\`
 
 ## Infobox
@@ -77,10 +78,12 @@ Include an infobox for any article about a person, place, organization, event, o
 
 ## Citations
 
-- Mark claims with [N] after punctuation: "The population is 1.4 billion.[1]"
-- Number sequentially starting at [1]
-- Every source in the sources list must be referenced at least once in the body
-- Every [N] marker must have a matching source
+- 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
 
@@ -308,6 +311,37 @@ export function registerArticleTools(server) {
             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/). " +

package/dist/validate.js

@@ -1,7 +1,8 @@
 import { parse as parseYaml } from "yaml";
 const SLUG_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
 const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
-const MARKER_RE = /\[(\d+)\]/g;
+const KEY_RE = /^[a-z0-9]+-[a-z0-9]+(-[a-z0-9]+)*$/;
+const CITE_RE = /\[@([a-z0-9]+-[a-z0-9]+(?:-[a-z0-9]+)*)\]/g;
 export function parseFrontmatter(raw) {
     const match = raw.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
     if (!match) {
@@ -39,8 +40,26 @@ export function validateArticle(raw) {
         errors.push({ field: "sources", message: "Sources must be an array" });
     }
     else {
+        const seenKeys = new Set();
         for (let i = 0; i < sources.length; i++) {
             const s = sources[i];
+            // key validation
+            const key = s.key;
+            if (!key || typeof key !== "string") {
+                errors.push({ field: `sources[${i}].key`, message: "Key is required" });
+            }
+            else if (!KEY_RE.test(key)) {
+                errors.push({
+                    field: `sources[${i}].key`,
+                    message: `Key "${key}" must be kebab-case with at least one hyphen (e.g. 'nytimes-climate-report')`,
+                });
+            }
+            else if (seenKeys.has(key)) {
+                errors.push({ field: `sources[${i}].key`, message: `Duplicate key "${key}"` });
+            }
+            else {
+                seenKeys.add(key);
+            }
             if (!s.url || typeof s.url !== "string") {
                 errors.push({ field: `sources[${i}].url`, message: "URL is required" });
             }
@@ -61,44 +80,30 @@ export function validateArticle(raw) {
                 errors.push({ field: `sources[${i}].accessed_date`, message: "Must be YYYY-MM-DD format" });
             }
         }
-    }
-    // citation markers
-    const markerNums = new Set();
-    let match;
-    while ((match = MARKER_RE.exec(content)) !== null) {
-        markerNums.add(parseInt(match[1], 10));
-    }
-    if (markerNums.size > 0) {
-        const sorted = [...markerNums].sort((a, b) => a - b);
-        if (sorted[0] !== 1) {
-            errors.push({ field: "citations", message: "Citation markers must start at [1]" });
+        // citation markers — collect all [@key] references from content
+        const citedKeys = new Set();
+        for (const match of content.matchAll(CITE_RE)) {
+            citedKeys.add(match[1]);
         }
-        for (let i = 1; i < sorted.length; i++) {
-            if (sorted[i] !== sorted[i - 1] + 1) {
+        // cross-check: every [@key] in body must have a matching source
+        for (const key of citedKeys) {
+            if (!seenKeys.has(key)) {
                 errors.push({
                     field: "citations",
-                    message: `Gap in citation markers: [${sorted[i - 1]}] → [${sorted[i]}]`,
+                    message: `[@${key}] referenced in content but no source has key "${key}"`,
                 });
-                break;
             }
         }
-        // cross-check markers vs sources
-        if (Array.isArray(sources)) {
-            const maxMarker = sorted[sorted.length - 1];
-            if (maxMarker > sources.length) {
+        // cross-check: every source key must be referenced at least once
+        for (let i = 0; i < sources.length; i++) {
+            const s = sources[i];
+            const key = s.key;
+            if (key && typeof key === "string" && !citedKeys.has(key)) {
                 errors.push({
-                    field: "citations",
-                    message: `Citation [${maxMarker}] referenced but only ${sources.length} source(s) provided`,
+                    field: `sources[${i}]`,
+                    message: `Source "${key}" is never referenced with [@${key}] in the content`,
                 });
             }
-            for (let i = 0; i < sources.length; i++) {
-                if (!markerNums.has(i + 1)) {
-                    errors.push({
-                        field: `sources[${i}]`,
-                        message: `Source ${i + 1} is never referenced with [${i + 1}] in the content`,
-                    });
-                }
-            }
         }
     }
     return errors;

package/package.json

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