openalmanac 0.2.3 → 0.2.5

package/dist/tools/articles.js

@@ -5,6 +5,85 @@ import { stringify as yamlStringify } from "yaml";
 import { request, ARTICLES_DIR } from "../auth.js";
 import { validateArticle, parseFrontmatter } from "../validate.js";
 const SLUG_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+const WRITING_GUIDE = `
+## Article structure
+
+\`\`\`yaml
+---
+article_id: the-slug
+title: Article Title
+sources:
+  - url: https://example.com
+    title: Source Title
+infobox:
+  header:
+    image_url: https://...         # optional hero image
+    subtitle: Short tagline
+    details:
+      - key: Born
+        value: January 1, 1990
+      - key: Occupation
+        value: Scientist
+    links:
+      - label: Official site
+        url: https://...
+  sections:
+    - type: timeline               # chronological events
+      title: Career Timeline
+      items:
+        - primary: "2010"
+          value: Started company
+    - type: list                   # bullet list
+      title: Known For
+      items:
+        - value: First achievement
+        - value: Second achievement
+    - type: tags                   # inline tags/chips
+      title: Genres
+      items:
+        - value: Rock
+        - value: Jazz
+    - type: grid                   # image grid
+      title: Gallery
+      items:
+        - image_url: https://...
+          value: Caption
+    - type: table                  # rows with label+value
+      title: Statistics
+      items:
+        - label: Height
+          value: "6'2\\""
+    - type: key_value              # simple key-value pairs
+      title: Quick Facts
+      items:
+        - key: Population
+          value: "1.4 billion"
+---
+
+Article body with [1] 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 [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
+
+## 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 });
 }
@@ -27,7 +106,8 @@ export function registerArticleTools(server) {
     server.addTool({
         name: "pull",
         description: "Download an article from OpenAlmanac to your local working directory (~/.openalmanac/articles/). " +
-            "The file is saved as {slug}.md with YAML frontmatter. Edit the file locally, then use push to publish changes.",
+            "The file is saved as {slug}.md with YAML frontmatter. Returns a writing guide covering article structure, infobox format, citations, and quality rules. " +
+            "Edit the file locally, then use push to publish changes.",
         parameters: z.object({
             slug: z.string().describe("Article slug (e.g. 'machine-learning')"),
         }),
@@ -42,13 +122,14 @@ export function registerArticleTools(server) {
             const { frontmatter, content } = parseFrontmatter(markdown);
             const title = frontmatter.title || "(untitled)";
             const wordCount = content.trim().split(/\s+/).filter(Boolean).length;
-            return `Pulled "${title}" to ${filePath}\n${wordCount} words, ${frontmatter.sources?.length ?? 0} sources.\nEdit the file, then use push to publish.`;
+            return `Pulled "${title}" to ${filePath}\n${wordCount} words, ${frontmatter.sources?.length ?? 0} sources.\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. Edit the file to add content and sources, then use push to publish.",
+            "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 push to publish.",
         parameters: z.object({
             slug: z
                 .string()
@@ -67,7 +148,7 @@ export function registerArticleTools(server) {
             const frontmatter = yamlStringify({ article_id: slug, title, sources: [] });
             const scaffold = `---\n${frontmatter}---\n\n`;
             writeFileSync(filePath, scaffold, "utf-8");
-            return `Created ${filePath}\nEdit the file to add content and sources, then use push to publish.`;
+            return `Created ${filePath}\n\n${WRITING_GUIDE}`;
         },
     });
     server.addTool({

package/package.json

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