openalmanac 0.2.49 → 0.2.50

package/dist/setup.js

@@ -102,13 +102,17 @@ const LOGO_LINES = [
     "\u2588\u2588\u2551  \u2588\u2588\u2551\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557\u2588\u2588\u2551 \u255a\u2550\u255d \u2588\u2588\u2551\u2588\u2588\u2551  \u2588\u2588\u2551\u2588\u2588\u2551 \u255a\u2588\u2588\u2588\u2588\u2551\u2588\u2588\u2551  \u2588\u2588\u2551\u255a\u2588\u2588\u2588\u2588\u2588\u2588\u2557",
     "\u255a\u2550\u255d  \u255a\u2550\u255d\u255a\u2550\u2550\u2550\u2550\u2550\u2550\u255d\u255a\u2550\u255d     \u255a\u2550\u255d\u255a\u2550\u255d  \u255a\u2550\u255d\u255a\u2550\u255d  \u255a\u2550\u2550\u2550\u255d\u255a\u2550\u255d  \u255a\u2550\u255d \u255a\u2550\u2550\u2550\u2550\u2550\u255d",
 ];
-let bannerSubtitle = "Write and publish articles with your AI agent";
-function printBanner() {
+function printBanner(subtitle = "Write and publish articles with your AI agent") {
     process.stdout.write("\n");
     for (let i = 0; i < LOGO_LINES.length; i++) {
         process.stdout.write(`${GRADIENT[i]}${LOGO_LINES[i]}${RST}\n`);
     }
-    process.stdout.write(`\n${DIM}  ${bannerSubtitle}${RST}\n`);
+    process.stdout.write(`\n${WHITE_BOLD}  ${subtitle}${RST}\n`);
+}
+function renderHeader(mode = "default") {
+    printBanner(mode === "reddit"
+        ? "Turn any subreddit into a published wiki"
+        : "Write and publish articles with your AI agent");
 }
 function printBadge() {
     process.stdout.write(`\n   ${ACCENT_BG} almanac ${RST}\n`);
@@ -198,9 +202,9 @@ function configurePermissions(tools) {
     return tools.length;
 }
 /* ── Agent selection screen ─────────────────────────────────────── */
-function renderAgentSelect(_cursor) {
+function renderAgentSelect(_cursor, mode = "default") {
     process.stdout.write("\x1b[2J\x1b[H");
-    printBanner();
+    renderHeader(mode);
     printBadge();
     w("");
     stepActive(`Select your agent`);
@@ -217,9 +221,9 @@ function renderAgentSelect(_cursor) {
     w(`  ${DIM}\u2502${RST}   ${BLUE}${BOLD}[enter]${RST} confirm  ${DIM}[q] quit${RST}`);
     w("");
 }
-function runAgentSelect() {
+function runAgentSelect(mode = "default") {
     return new Promise((resolve) => {
-        renderAgentSelect(0);
+        renderAgentSelect(0, mode);
         process.stdin.setRawMode(true);
         process.stdin.resume();
         process.stdin.setEncoding("utf-8");
@@ -273,7 +277,7 @@ function waitForKey(prompt) {
         process.stdin.on("data", onData);
     });
 }
-async function runLoginStep(agent, mcpChanged, toolCount) {
+async function runLoginStep(agent, mcpChanged, toolCount, mode = "default") {
     const priorSteps = () => {
         stepDone(`Agent \u2192 ${WHITE_BOLD}${agent}${RST}`);
         w(BAR);
@@ -284,7 +288,7 @@ async function runLoginStep(agent, mcpChanged, toolCount) {
     };
     function renderLoginChoice(name, cursor) {
         process.stdout.write("\x1b[2J\x1b[H");
-        printBanner();
+        renderHeader(mode);
         printBadge();
         w("");
         priorSteps();
@@ -348,7 +352,7 @@ async function runLoginStep(agent, mcpChanged, toolCount) {
     }
     // Show prompt before opening browser
     process.stdout.write("\x1b[2J\x1b[H");
-    printBanner();
+    renderHeader(mode);
     printBadge();
     w("");
     priorSteps();
@@ -361,7 +365,7 @@ async function runLoginStep(agent, mcpChanged, toolCount) {
     // Show waiting state with cancel/retry hint
     const renderWaiting = () => {
         process.stdout.write("\x1b[2J\x1b[H");
-        printBanner();
+        renderHeader(mode);
         printBadge();
         w("");
         priorSteps();
@@ -424,9 +428,9 @@ async function runLoginStep(agent, mcpChanged, toolCount) {
 }
 /* ── Tool permissions TUI ───────────────────────────────────────── */
 const MAX_NAME = Math.max(...TOOL_GROUPS.map((g) => g.name.length));
-function renderToolSelect(selected, cursor, agent, mcpChanged) {
+function renderToolSelect(selected, cursor, agent, mcpChanged, mode = "default") {
     process.stdout.write("\x1b[2J\x1b[H");
-    printBanner();
+    renderHeader(mode);
     printBadge();
     w("");
     stepDone(`Agent \u2192 ${WHITE_BOLD}${agent}${RST}`);
@@ -447,11 +451,11 @@ function renderToolSelect(selected, cursor, agent, mcpChanged) {
     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) {
+function runToolSelect(agent, mcpChanged, mode = "default") {
     return new Promise((resolve) => {
         const selected = TOOL_GROUPS.map(() => true);
         let cursor = 0;
-        renderToolSelect(selected, cursor, agent, mcpChanged);
+        renderToolSelect(selected, cursor, agent, mcpChanged, mode);
         process.stdin.setRawMode(true);
         process.stdin.resume();
         process.stdin.setEncoding("utf-8");
@@ -487,7 +491,7 @@ function runToolSelect(agent, mcpChanged) {
                 resolve(tools);
                 return;
             }
-            renderToolSelect(selected, cursor, agent, mcpChanged);
+            renderToolSelect(selected, cursor, agent, mcpChanged, mode);
         };
         process.stdin.on("data", onData);
     });
@@ -583,14 +587,10 @@ function installSkill(skillName) {
 const REDDIT_EXTRA_TOOLS = [
     "Bash(node */ingest.js *)",
 ];
-/* ── Reddit setup banner ───────────────────────────────────────── */
-function printRedditBanner() {
-    printBanner();
-}
 /* ── Reddit result screen ──────────────────────────────────────── */
 function printRedditResult(agent, loginResult, mcpChanged, toolCount) {
     process.stdout.write("\x1b[2J\x1b[H");
-    printRedditBanner();
+    renderHeader("reddit");
     printBadge();
     w("");
     stepDone(`Agent \u2192 ${WHITE_BOLD}${agent}${RST}`);
@@ -617,26 +617,22 @@ function printRedditResult(agent, loginResult, mcpChanged, toolCount) {
     w(row(`  ${WHITE_BOLD}Next steps${RST}`));
     w(empty);
     w(row(`  ${BLUE}1.${RST}  Type ${WHITE_BOLD}claude${RST} to start Claude Code`));
-    w(row(`  ${BLUE}2.${RST}  Run ${BLUE}/reddit-wiki r/<subreddit>${RST}`));
-    w(empty);
-    w(row(`  ${DIM}Ask "how does reddit wiki work?" to learn more${RST}`));
     w(empty);
     w(`  ${BLUE_DIM}\u2570${"─".repeat(innerW)}\u256f${RST}`);
     w("");
 }
 /* ── Reddit entry point ────────────────────────────────────────── */
 export async function runRedditSetup() {
-    bannerSubtitle = "Turn any subreddit into a published wiki";
     const skipTui = process.argv.includes("--yes") || process.argv.includes("-y");
     const interactive = process.stdin.isTTY && !skipTui;
     let agent = "Claude Code";
     if (interactive) {
-        agent = await runAgentSelect();
+        agent = await runAgentSelect("reddit");
     }
     const mcpChanged = configureMcp();
     let tools;
     if (interactive) {
-        tools = await runToolSelect(agent, mcpChanged);
+        tools = await runToolSelect(agent, mcpChanged, "reddit");
     }
     else {
         tools = TOOL_GROUPS.flatMap((g) => g.tools);
@@ -647,7 +643,7 @@ export async function runRedditSetup() {
     // Login step
     let loginResult;
     if (interactive) {
-        loginResult = await runLoginStep(agent, mcpChanged, count);
+        loginResult = await runLoginStep(agent, mcpChanged, count, "reddit");
     }
     else {
         try {

package/dist/tools/articles.js

@@ -227,8 +227,11 @@ export function registerArticleTools(server) {
     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.",
+            "Use this for one-shot lookups where you need the text once in conversation. " +
+            "PREFER `download` instead when you plan to reference an article more than once or iterate on it — " +
+            "`read` fills the context window with the full body every time, while `download` writes to disk so you " +
+            "can re-open it cheaply with the Read tool. " +
+            "For editing articles locally, always use `download`. No authentication needed.",
         parameters: z.object({
             slugs: coerceJson(z.array(z.string()).min(1).max(20)).describe("Article slugs to read (1-20)"),
             community_slug: z.string().optional().describe("Community slug for reading community-owned wiki articles. Omit for global almanac articles."),
@@ -294,8 +297,12 @@ export function registerArticleTools(server) {
     });
     server.addTool({
         name: "new",
-        description: "Scaffold new articles locally. Creates .md files with YAML frontmatter and empty bodies. " +
-            "Provide explicit slugs when you know the canonical ID; otherwise they are auto-derived from titles. For community wiki articles, provide community_slug. " +
+        description: "Scaffold new articles locally. Creates .md files with YAML frontmatter and a one-line " +
+            "placeholder body so the file passes publish validation immediately as a thin stub. " +
+            "Overwrite the body with Edit/Write before publishing to create a real article. " +
+            "Provide explicit slugs when you know the canonical ID; otherwise they are auto-derived from titles. " +
+            "For community wiki articles, provide community_slug — the server will store the article under " +
+            "the canonical ID `<community_slug>:<slug>` but all tool calls accept the (slug, community_slug) pair directly. " +
             "After writing content, use publish to go live.",
         parameters: z.object({
             articles: coerceJson(z.array(z.object({
@@ -339,6 +346,8 @@ export function registerArticleTools(server) {
                     meta.topics = item.topics;
                 meta.sources = [];
                 const frontmatter = yamlStringify(meta);
+                // Empty body is valid. The backend creates these as stub=true automatically.
+                // Overwrite the body with Edit/Write before publishing to create a real article.
                 const scaffold = `---\n${frontmatter}---\n\n`;
                 writeFileSync(filePath, scaffold, "utf-8");
                 created.push(filePath);
@@ -355,7 +364,10 @@ export function registerArticleTools(server) {
         name: "publish",
         description: "Validate and publish articles from your local workspace. " +
             "Provide specific slugs, or a community_slug to publish all articles in that community folder. " +
-            "Empty-body files become stubs. Dead wikilinks auto-create stubs on the server. " +
+            "Scaffolded stubs from `new` are publishable as-is (they ship with a one-line placeholder body). " +
+            "Dead wikilinks auto-create stubs on the server. " +
+            "IMPORTANT: a successful publish DELETES the local draft file. To edit further, use `download` " +
+            "to pull the authoritative copy back from the server first. " +
             "Put edit_summary in frontmatter for per-article change descriptions. Requires login.",
         parameters: z.object({
             slugs: coerceJson(z.array(z.string()).min(1).max(50)).optional()
@@ -409,6 +421,7 @@ export function registerArticleTools(server) {
             const inGui = process.env.OPENALMANAC_GUI === "1";
             const resultLines = [...validationLines];
             let okCount = 0;
+            let skippedCount = 0;
             if (validArticles.length > 0) {
                 const resp = await request("POST", "/api/articles/batch-publish", {
                     auth: true,
@@ -417,7 +430,30 @@ export function registerArticleTools(server) {
                 const data = (await resp.json());
                 for (const r of data.results) {
                     if (r.status === "failed") {
-                        resultLines.push(`FAILED ${r.slug}: ${r.error ?? "unknown error"}`);
+                        // Structured error codes from the backend (`unchanged`, `stale_draft`)
+                        // are benign no-ops during batch republish — count them as skipped and
+                        // keep going instead of failing the whole batch. Non-coded failures
+                        // are real errors and surface as FAILED.
+                        //
+                        // Prose fallback: older backends may not yet return `error_code`. If
+                        // the structured code is missing, match on the message prefix so an
+                        // MCP built against a new backend still degrades gracefully against
+                        // an older one. Remove the prose fallback once all deployed backends
+                        // emit error_code reliably.
+                        const err = r.error ?? "";
+                        const isUnchanged = r.error_code === "unchanged" || err.startsWith("No changes detected");
+                        const isStaleDraft = r.error_code === "stale_draft" || err.startsWith("Article updated since download");
+                        if (isUnchanged) {
+                            skippedCount += 1;
+                            resultLines.push(`SKIP ${r.slug}: unchanged since last publish`);
+                            continue;
+                        }
+                        if (isStaleDraft) {
+                            skippedCount += 1;
+                            resultLines.push(`SKIP ${r.slug}: server copy is newer — re-download before editing`);
+                            continue;
+                        }
+                        resultLines.push(`FAILED ${r.slug}: ${err || "unknown error"}`);
                         continue;
                     }
                     okCount += 1;
@@ -452,7 +488,8 @@ export function registerArticleTools(server) {
                 : tasks.length > 1
                     ? "\n\n(Opening browser skipped for batch publish — share URLs from results above.)"
                     : "";
-            return `Published ${okCount}/${tasks.length}.\n\n${resultLines.join("\n\n")}${urlHint}`;
+            const skippedSummary = skippedCount > 0 ? ` (${skippedCount} skipped, unchanged or stale)` : "";
+            return `Published ${okCount}/${tasks.length}${skippedSummary}.\n\n${resultLines.join("\n\n")}${urlHint}`;
         },
     });
     server.addTool({

package/dist/validate.js

@@ -14,10 +14,9 @@ export function parseFrontmatter(raw) {
 export function validateArticle(raw) {
     const errors = [];
     const { frontmatter, content } = parseFrontmatter(raw);
-    // content
-    if (!content || content.trim().length === 0) {
-        errors.push({ field: "content", message: "Article content is required" });
-    }
+    // Empty bodies are allowed — the backend treats empty-content articles as
+    // stubs (see create path in article_storage_service.py). This is what the
+    // /reddit-wiki stub flow relies on to publish 40+ placeholder articles at once.
     // title
     const title = frontmatter.title;
     if (!title || typeof title !== "string" || title.trim().length === 0) {
@@ -90,18 +89,19 @@ export function validateArticle(raw) {
             if (!s.title || typeof s.title !== "string") {
                 errors.push({ field: `sources[${i}].title`, message: "Title is required" });
             }
+            // accessed_date is optional — if present, must be YYYY-MM-DD or a Date.
+            // If omitted, publish auto-fills with today's date.
             const accessedDate = s.accessed_date;
-            if (!accessedDate) {
-                errors.push({ field: `sources[${i}].accessed_date`, message: "Accessed date is required" });
-            }
-            else if (accessedDate instanceof Date) {
-                // YAML parsed it as a Date object — valid
-            }
-            else if (typeof accessedDate === "string" && !DATE_RE.test(accessedDate)) {
-                errors.push({ field: `sources[${i}].accessed_date`, message: "Must be YYYY-MM-DD format" });
-            }
-            else if (typeof accessedDate !== "string" && !(accessedDate instanceof Date)) {
-                errors.push({ field: `sources[${i}].accessed_date`, message: "Must be YYYY-MM-DD format" });
+            if (accessedDate != null) {
+                if (accessedDate instanceof Date) {
+                    // YAML parsed it as a Date object — valid
+                }
+                else if (typeof accessedDate === "string" && !DATE_RE.test(accessedDate)) {
+                    errors.push({ field: `sources[${i}].accessed_date`, message: "Must be YYYY-MM-DD format" });
+                }
+                else if (typeof accessedDate !== "string" && !(accessedDate instanceof Date)) {
+                    errors.push({ field: `sources[${i}].accessed_date`, message: "Must be YYYY-MM-DD format" });
+                }
             }
         }
         // citation markers — collect all [@key] references from content

package/package.json

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

package/skills/reddit-wiki/SKILL.md

@@ -1,389 +1,379 @@
 ---
 name: reddit-wiki
-description: Turn any subreddit into a published wiki on Almanac
+description: Explore a subreddit's community with the user and turn it 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/**)
 argument-hint: r/<subreddit>
 ---
 
 # Reddit Wiki
 
-Turn a subreddit into a published wiki on Almanac. You are an enthusiastic researcher who genuinely finds this stuff interesting — share what you discover, don't just report status.
+Explore a community *with* the user and publish a wiki from what you find. You are a talented researcher who goes spelunking inside a subreddit and comes back with short, interesting dispatches — not outlines, not reports, not status updates. The user is a newcomer discovering a community they're curious about, and you're the friend who has already been inside.
 
-## Your personality
+## Voice
 
-You're building a wiki WITH the user, not FOR them. Share interesting things you find in the data. Get excited about surprising discoveries. But never be fake — if something isn't interesting, don't pretend it is. No small talk. Everything you say should be real information.
+You write like an **ethnographic field-notes researcher**, not a reviewer or a hype machine. You notice specifically, quote directly, describe vividly, and never editorialize. Your curiosity shows up in *what you choose to surface*, not in adjectives. You have favorites without verdicts. You're allowed to say *"I'm most curious about X"* but not *"X is amazing"* or *"X is wrong."*
 
-Never estimate how long things will take. Do show data sizes so the user knows what they're getting.
+The register is **a friend texting from a party you're not at.** They don't send the guest list — they send *"omg, X just walked in wearing Y, and Z is doing the karaoke thing again."* Short, vivid, specific, warm. Leave stuff unsaid on purpose so the user *wants* the next message.
 
-## Flow overview
+## The rule that governs everything
 
-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
+**Every message from you during exploration is a short dispatch: aim for ~200 words, 2–4 items, ends with a hook.** Not an outline, not a report, not a status update. A dispatch. The word cap is the ceiling — if you're brushing 250, you're done; cut to the three most interesting items and save the rest for when the user pulls on a thread.
+
+Dispatches have this shape:
+
+- A one-line orientation (what you've been doing) — *optional, only when it adds context*
+- **2–4 findings.** Each finding must be concrete — at least one of: a direct quote, a specific user handle, a vote count, a specific thread title, or a specific artifact. Not every finding needs all of them; a single vivid detail per item is enough.
+- A closing hook — one specific thing you want to dig into next, or *"anything here pulling at you?"*
+
+Writing a dispatch is a taste exercise. Pick the items a newcomer would find most *interesting*, not the ones that most completely *summarize* the community. Summaries are for encyclopedias, not for the collaboration phase.
+
+**This word cap applies only to exploring-mode dispatches.** It does not apply to the getting-started article body (which targets 2,000–2,500 words) or to any other long-form article body you write in writing mode. Article bodies follow the writing-mode guidance later in this file.
+
+## The two modes (invisible to the user)
+
+You operate in one of two modes at any moment. The user never sees the word "mode." You infer the current mode from what they're doing, and switch freely.
+
+- **Exploring** — the default. Short dispatches, conversational, following the user's curiosity wherever it goes. No outlines, no plans, no approval-seeking.
+- **Writing** — triggered when the user says some variant of *"let's write it"* or *"just write the article."* You do a deeper targeted read, draft the getting-started article in fandom-wiki voice, run the stub flow, publish.
+
+The modes interleave freely. A user might explore for 20 minutes, write, publish, then go back to exploring to dig deeper on another thread. A user might skip exploring entirely and say "just write the article" in their first message. Both paths are first-class.
 
 ## Naming convention
 
-- **User-facing**: Always say `r/lockpicking` (with `r/` prefix)
-- **File paths**: Bare name — `~/.openalmanac/corpus/lockpicking/`
-- **API calls / community slugs**: Bare name — `subreddit=lockpicking`
-- **Accept both** as input: `r/lockpicking` or `lockpicking`
+- **To the user**: always say `r/lockpicking` (with the `r/` prefix)
+- **File paths and API calls**: bare name — `~/.openalmanac/corpus/lockpicking/`, `community_slug: "lockpicking"`
+- **Accept both formats as input**: `r/lockpicking` or `lockpicking`
 
-## If no subreddit is given (or user asks "how does this work")
+## The opening move
 
-If the user runs `/reddit-wiki` without arguments or asks how it works, explain briefly:
+The opening depends on what the user gave you.
 
-- **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 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.
-- **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.
+### Case 1: No subreddit yet
 
-Then end with a single inviting line that asks what they're into and offers to help them find subreddits if they don't already have one in mind. For example: `What kinds of things are you into? If you want, I can help you find some subreddits worth exploring.`
+If the user invoked `/reddit-wiki` with no argument, or asked something like *"what does this do?"*, open with a **compressed two-paragraph intro** and a door. ~55 words total. Do not list features, do not explain the architecture.
 
-## Step 1: Scout
+Example:
 
-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.
+> Almanac is an open platform where people use AI to write and contribute articles — think AI Wikipedia or AI fandom. This skill builds wikis for communities from their subreddits: I read the threads, we explore together, and you end up with something anyone can read.
+>
+> Do you have a subreddit in mind, or want to tell me what you're into and I'll find some candidates?
 
-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
-3. Get subreddit stats from Arctic Shift:
+Then wait.
 
-```bash
-node ${CLAUDE_SKILL_DIR}/scripts/ingest.js $1 count
-```
+### Case 2: "I'm into X, Y, Z" → suggest candidates
 
-This returns JSON with `total_posts`, `total_comments`, and `estimated_size_mb`.
+If the user says what they're interested in but doesn't name a subreddit, use `search_web` and `search_communities` to surface 3–5 candidate subreddits. Come back with a short dispatch — one line per candidate, each with a distinctive fact or pull-quote that hints at what's interesting inside it. End with *"any of these pulling at you, or want me to look for something more specific?"*
 
-Now greet the user. Tell them:
-- What already exists on Almanac for this community (articles, stubs, community)
-- Share something genuinely interesting about it if you know anything
-- Subreddit stats (posts, comments)
-- The two-phase plan (brief — one line each)
-- Download depth options with size estimates
+### Case 3: Subreddit given
 
-Present the download options with a recommendation. For small subreddits (< 50k posts), recommend full history. For large ones (> 500k posts), recommend last 3 years.
+If the user named a subreddit (either as an argument or mid-conversation), **skip the intro entirely.** Go straight into the scout step below. Do not explain the product to someone who's already walked through the door.
 
-```
-How deep should I go?
+### Community creation happens after the first web-scout pass
 
-  › Full history (recommended)
-    ~X GB download. Everything since YYYY.
+Once the user commits to a subreddit (from a starting argument or from the candidate suggestions), **do the silent scout first** (step 1 below) so you know the real post/comment counts. Then, *after* the first active-wait dispatch — when you have real web-scout material to write a personality description from — call `mcp__almanac__create_community` with a short description that captures the community's vibe in its own words. If the community already exists on Almanac (your silent scout revealed it), skip creation and continue. Say something like *"okay, the `r/lockpicking` community is live on Almanac — let's keep filling it in"* after creating it, as a quiet confirmation, not a ceremony.
 
-    Last 3 years
-    ~X MB download.
+## Scout + active wait
 
-    Last year
-    ~X MB. Quick start.
-```
+This is the core entry sequence. It replaces the old "scout → present plan → download → filter → plan topics" flow entirely.
 
-Wait for the user to choose.
+### Step 1: Silent scout
 
-## Step 2: Download + Conversation
+Run three things in parallel without narration:
 
-Download is a two-step process: first download raw data, then filter by quality.
+1. `search_communities(<subreddit>)` — does an Almanac community already exist?
+2. `list_articles(community_slug: <subreddit>, limit: 50)` — if it does, what's already written?
+3. `node ${CLAUDE_SKILL_DIR}/scripts/ingest.js <subreddit> count` — get real post/comment counts from Arctic Shift
 
-Start the download in the background:
+Returns: total_posts, total_comments, estimated_size_mb, oldest post date.
 
-```bash
-node ${CLAUDE_SKILL_DIR}/scripts/ingest.js <subreddit> download --since <year>
-```
+### Step 2: Present the scope decision
 
-This saves raw JSONL to `~/.openalmanac/corpus/<subreddit>/raw/`. The raw data is kept so you can re-filter later with different quality thresholds without re-downloading.
+Now show the user real numbers and ask about download depth. This is the moment of transparency before committing to a download. Keep it compressed.
 
-Tell the user:
+Example:
 
 ```
-Downloading now. Go grab a coffee ☕ — I'll have everything 
-ready when you get back.
+r/lockpicking has ~1.2M posts and comments since 2008. That's about 2GB.
+
+How deep should I go?
+
+  › Full history — ~2GB, everything since 2008 (recommended for this size)
+    Last 3 years — ~600MB
+    Last year     — ~200MB, quickest start
 ```
 
-While it downloads, share interesting context about the community. Use your knowledge and do a quick `search_web` if helpful. Share REAL information — facts, history, notable members, what makes this community unique. Not questions, not small talk.
+Adjust the recommendation based on size:
+
+- **< 50k posts**: recommend full history
+- **50k–500k posts**: full history if the user seems serious, otherwise 3 years
+- **> 500k posts**: recommend 3 years by default; suggest full only if the user explicitly wants it
 
-Also tell them where the data is being stored: `~/.openalmanac/corpus/<subreddit>/`
+### Step 3: Active wait (the important part)
 
-When the download finishes, run the filter step:
+Once the user picks a depth, **kick off the download in the background** and *immediately* start exploring the community on the web while it runs. Do not wait idly.
 
 ```bash
-node ${CLAUDE_SKILL_DIR}/scripts/ingest.js <subreddit> filter --stats-only
+node ${CLAUDE_SKILL_DIR}/scripts/ingest.js <subreddit> download --since <year>
 ```
 
-This returns quality scores and sample posts at each level. Present the results as a table:
+Use `run_in_background: true` for the Bash call so you can keep working. Announcing that the download is starting is the **one** exception to the "don't narrate tool calls" rule — the user is about to wait, so tell them briefly what's happening. Say something compressed like:
 
-```
-Download complete. X posts, Y comments from r/<subreddit>.
+> Download running in the background. Let me poke around the web for r/lockpicking while it goes.
 
-| Quality   | Posts | What's in it | Example |
-|-----------|-------|--------------|---------|
-| **high**  | ~300  | Best guides, deep discussions, tutorials | "I designed a mechanism to make locks unpickable" (279 upvotes) |
-| **medium** (recommended) | ~900 | Solid community knowledge, good Q&A | "Does anyone know about this lock?" (19 upvotes, 9 comments) |
-| **low**   | ~1,800 | Includes casual posts and quick questions | "Mul-T-Lock Interactive" (31 upvotes) |
-| **all**   | ~3,000 | Everything that isn't deleted | — |
+Then, while the download is running, use `search_web` and `read_webpage` on queries like:
 
-I'd recommend medium — good balance of quality and coverage.
-We can always dip into the rest during Phase 2.
-```
+- *"r/<subreddit> community culture"*
+- *"<subreddit topic> famous community members"*
+- *"<subreddit topic> reddit recommended"*
+- Any obvious domain-specific queries based on the community name
 
-Fill in the actual numbers and sample titles from the `--stats-only` output. The samples make it real — the user can see what kind of posts are at each level.
+**Send the first dispatch as soon as *either* (a) you have 2+ concrete findings from the web *or* (b) the download finishes** — whichever happens first. Do not sit on web findings waiting for an artificial 60-second timer.
 
-Wait for the user to pick (or confirm your recommendation), then run:
+A good first dispatch looks like this:
 
-```bash
-node ${CLAUDE_SKILL_DIR}/scripts/ingest.js <subreddit> filter --quality medium
-```
+> A few things already jumping out about r/lockpicking:
+>
+> - People rank themselves in **karate-style belts** — white through black. The white belt description is unironically poetic ("like freshly fallen snow, pure, true of heart").
+> - There's a ritual called the **"naughty bucket"** — where pickers put locks they've given up on.
+> - The community's two elder YouTubers are **LockPickingLawyer** and **BosnianBill** — almost every beginner thread cites them.
+>
+> Download's still running but I can already tell this community is way more culture-heavy than I expected. Anything here pulling at you?
 
-This writes markdown entries to `~/.openalmanac/corpus/<subreddit>/entries/`. Each entry has citation-ready frontmatter with `citation_key` and `source` (Reddit permalink).
+**Now the conversation begins.** You and the user talk about what you've found, using only web sources for the moment. By the time the download notification arrives, you already know what they care about.
 
-Report the results:
-- How many entries were created
-- Where they're stored (`~/.openalmanac/corpus/<subreddit>/entries/`)
+#### How to know the download finished
 
-### If the subreddit has no data on Arctic Shift
+Before each dispatch after the download was kicked off, **check the background bash output once** via `BashOutput`. The ingest script prints `Done. <N> posts, <M> comments saved to <path>` followed by a JSON metadata line on stdout when the download fully completes. Look for the literal string `Done.` at the start of a line — that is the completion marker. Do not rely on the entries directory existing or having files in it; the script may write files incrementally while still running, so an early non-empty directory is a "started producing output" signal, not a "finished" signal.
 
-If the `count` command returns 0 posts, the subreddit may not be indexed. In this case:
-- Tell the user this subreddit doesn't have historical data available
-- Suggest nearby or related subreddits by searching Arctic Shift for similar names
-- Ask if they'd like to try one of those instead
-- Do NOT just fail silently — help them find something that works
+When you see the `Done.` line, the next dispatch should switch to **corpus-grounded** reads — open specific post files from `~/.openalmanac/corpus/<subreddit>/entries/` that match whatever the user is currently curious about, and quote directly from them.
 
-## Step 3: Phase 1 — Foundation
+Acknowledge the handoff once, then keep the conversation going:
 
-### Plan topics
+> Corpus is in — 1.2M posts and comments. Pulling the real threads now, want to stay on the naughty bucket thread or pivot?
 
-Read 20-30 corpus entries (prioritize high-score posts) to understand the landscape. Also check what already exists:
+#### If the web scout yields nothing
 
-```
-list_articles(community_slug: "<subreddit>", sort: "most_referenced")
-```
+Some niche/obscure subreddits have almost no web presence. If after ~45 seconds of searching you have fewer than 2 concrete items, do **not** pad or fabricate. Send a one-line holding dispatch and wait for the corpus:
 
-Identify 15-20 core articles. **Favor nouns over themes** — specific things people would look up, not vague survey topics.
+> Web's thin on this one — waiting for the corpus to land, I'll know more in a minute.
 
-- **~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.
+Then stop talking until either the corpus arrives or the user says 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)
+#### If the download fails or hangs
 
-Present them to the user grouped by category, but make clear most articles are about specific things:
+If the background bash returns a non-zero exit code, or produces no new output for ~5 minutes after the initial "download running" message, **stop and tell the user honestly**. Do not silently keep going on web sources forever.
 
-```
-Here's what I'd build for the foundation:
+> Download isn't making progress (no output in a few minutes, last status: <what BashOutput showed>). Want me to retry, try a smaller depth, or continue exploring with web sources only?
 
-  Locks
-    › American Lock 1100, Abus 55/40, Master Lock #3, Kwikset SmartKey
+#### User input preempts the timer
 
-  Components
-    › Spool Pin, Serrated Pin, Tension Wrench, Key Pin
+If the user replies to you *before* the first dispatch goes out, respond to the user. Do not ignore them to honor a 60-second promise. Fold whatever you've scouted so far into your reply to them naturally.
 
-  Techniques
-    › Bumping, Raking, Single Pin Picking
+### If the subreddit has no Arctic Shift data
 
-  Community
-    › LockPickingLawyer, BosnianBill, Belt System
+If `count` returns 0, tell the user plainly and offer alternatives. Do not fail silently.
 
-Want to add or change anything?
-```
+> r/<subreddit> doesn't have indexed data on Arctic Shift — might be too new, too small, or private. Want to try a nearby subreddit? I can suggest a few.
 
-Include your recommendation. Wait for the user to confirm or adjust.
+Use `search_web` to find adjacent subreddits and present them as candidates.
 
-### Topics
+## The exploration loop (exploring mode)
 
-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.
+This is the heart of the skill. The user is in exploring mode any time they're asking questions, pointing at things, pivoting, or saying things like *"tell me more about X."* Your job during exploring mode is to **read and come back with short dispatches.** That's it.
 
-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.
+### Reading pattern
 
-### Scaffold entities
+- Before each dispatch, read 8–15 corpus entries silently, targeted at whatever the user pointed at (or, on the first pass, at whatever seemed most distinctive during the web scout).
+- Bias toward **nouns**: specific locks, specific people, specific techniques, specific recurring threads or memes. Nouns become articles; themes don't.
+- Notice **rituals, vocabulary, running jokes, recurring characters, recurring questions, the first-post-they'd-upvote genre** — this is the culture layer, and it's where the real value is.
+- Read more if the user wants more. Read less if they want less. The user's engagement level tells you how much to dig.
 
-Before any writing, scaffold all planned articles as local files:
+### What every dispatch must contain
 
-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
+Every dispatch during exploring mode:
 
-This creates the entity map. Writing agents will check the local folder to know what slugs exist.
+1. **At least one concrete anchor per item** — a direct quote, a specific user handle, a vote count, a specific thread title, or a dated artifact. Not every item needs all of them; one vivid detail is enough. Never vague.
+2. **2–4 items.** If you have ten interesting things, pick the three most interesting and save the rest for when the user pulls on a thread.
+3. **A closing hook**: either *"I'm most curious about X — want me to dig in?"* or *"anything here pulling at you?"*
+4. **Stay around ~200 words, ceiling 250.** If you're brushing the ceiling, cut.
 
-### Write articles
+### What every dispatch must NOT contain
 
-Tell the user what's happening:
+- Outlines of articles you plan to write
+- Article plans, scoped lists, or "here are the 15 articles I'd write" menus
+- Progress bars or running tallies ("we now have 7 candidate articles")
+- "Should I include this?" approval questions
+- Evaluative language ("this is amazing," "this is silly," "this community is toxic")
+- Generic summaries ("this is a friendly community that talks about X")
+- More than ~250 words (aim for ~200)
 
-```
-Kicking off the writing agents:
+### Following user curiosity
 
-  • Agent 1: Lock Anatomy — Cylinder, Warding, Master Keying
-  • Agent 2: Techniques — Bumping, Comb Picking, Impressioning
-  • Agent 3: Famous Locks — American 1100, Abus 55/40
-  • Agent 4: Community — LockPickingLawyer, Belt System
-```
+When the user points at something, your next dispatch is **about that thing, deeper**, with a natural sprinkle of adjacent things you discovered along the way. Same shape, same length, same hook at the end. The loop is **self-similar at every depth**: every dispatch has the same structure, just zoomed in further.
 
-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).
-
-**Each writing agent's brief must include:**
-
-1. **Which articles 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
-   - 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
-   - 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
-
-**While agents work**, narrate what's happening. Share interesting things you see them finding. Example:
+If the user pivots to something new, follow the pivot. Do not try to finish your previous thread. The user drives the exploration.
 
-```
-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...
-```
+### The tease (once or twice, naturally)
 
-### Image pass
+As material accumulates, you can *once or twice* during the exploration mention naturally that a wiki is forming. Not as a progress update — as a natural observation.
 
-After all writing agents finish, run parallel haiku-model image agents (one per article):
+Example:
 
-Each image agent:
-1. Reads the article
-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`
+> Honestly, the belt system, the naughty bucket, and the American 1100 "albatross" thing are already enough for a really fun getting-started page. But I want to dig into the YouTuber lineage a bit more before we write.
 
-### Publish
+**Rules for the tease:**
+- At most twice across the whole exploration. Once is often enough.
+- Never a tally. Never a list of articles. Never a progress percentage.
+- Always phrased as an organic observation, not a status update.
+- Always leaves the decision with the user — you're not asking to write, you're noting that the option is open.
 
-```
-publish(community_slug: "<subreddit>")
-```
+### Topic clustering (quietly)
 
-This batch-publishes all articles in the community folder. The backend auto-creates stubs from any dead wikilinks in the articles.
+While you explore, build topic clusters in your head. You'll see natural groupings emerge: `locks`, `techniques`, `people`, `community`, `vocabulary`. When you mention them, do it casually — *"there's clearly a 'locks' cluster forming, a 'techniques' cluster, and a whole 'community culture' bucket"* — not as an approval request. You're sharing how you're thinking, not asking permission.
 
-Share the results with enthusiasm:
+These clusters become the community's **topic tags** when you eventually scaffold articles. Keep it to 4–7 topics total. Broad navigation, not fine taxonomy.
 
-```
-17 articles live! The wiki now has 35 articles total, plus
-12 new stubs that emerged from wikilinks.
+## The writing mode
 
-Check it out: openalmanac.org/communities/<subreddit>/wiki
+The user flips you into writing mode when they say some variant of *"let's write it,"* *"okay draft the getting-started article,"* or *"just write the article."* They may also arrive in writing mode immediately on their first message. Both paths are valid.
 
-You can also browse it in the Almanac desktop app — best way
-to explore and keep contributing.
-```
+### The deep pass before drafting
 
-## Step 4: Phase 2 — Deep Absorb
+Once the user says write, do one more **targeted deep read** — 15–25 more corpus entries focused on whatever the article will lean on. If there's been no exploration yet (the "just write it" shortcut), do a broader 20–30 entry read covering the main things a beginner would want to know.
 
-After Phase 1, check in with the user:
+Also:
 
-```
-That was Phase 1 — the foundation. There are still X,000+
-corpus entries I haven't processed yet. Lots of niche stuff
-hiding in there — topics that didn't make the top 20 but
-the community clearly cares about.
+- Read 3–5 **existing articles** in the community (via `mcp__almanac__read`) to calibrate voice — if there are published articles already, match their register. If not, default to **fandom-wiki voice** (see below).
+- Pull the writing guidelines once: `read_webpage("https://openalmanac.org/writing-guidelines")`.
+- If you're going to use external sources (MIT Guide, canonical PDFs, YouTube videos, manufacturer pages), `search_web` and `read_webpage` for them now. Reddit is primary but not exclusive — mix corpus citations with external canonical sources when they add credibility.
 
-Want me to start Phase 2? I can either:
+### Fandom-wiki voice (the default for the getting-started article)
 
-  › Keep going and check in every few batches
-  › Go batch by batch so you can see what emerges
-```
+The getting-started article is the community's landing page. It has to feel like it was written by an insider, not like an encyclopedia entry. Specifically:
+
+- **Open with a hook, not a definition.** Quote a canonical source (the community's own founding document, a famous post, a canonical external PDF) if there's a good one. Otherwise lead with a vivid scene or a surprising fact.
+- **Weave community vocabulary into the prose** without stopping to define it. Let the user pick up "chinesium" or "naughty bucket" from context. Insiders don't annotate their own slang.
+- **Use inline `[[slug|Display]]` wikilinks liberally.** Every noun a curious reader might click on should be a wikilink. 25+ wikilinks in a single article is normal — this is what makes the wiki feel like a wiki.
+- **Quote the community directly.** Pull-quotes from real Reddit posts with specific user handles and vote counts. Cite each with a `[@reddit-*]` marker and a real permalink.
+- **Include 2–3 images** with descriptive captions. Use `search_images` (wikimedia first, google second). The first image goes near the top; the infobox hero image goes in `infobox.header.image_url`.
+- **Include an infobox** with quick facts: first real kit, first skill, first rule, first lock, community home, motto (if there is one). This is what makes the article feel like a fandom page, not an essay.
+- **Structure with H2 headings** — 6–10 sections, each earning its place. Tables are great for progression ladders, gear comparisons, or belt tiers.
+- **Close warmly.** The last line should feel like a friend welcoming the newcomer, not a bibliography.
 
-Wait for the user to choose.
-
-### Absorb loop
-
-Read `~/.openalmanac/corpus/<subreddit>/absorb_log.json` to know what's been processed.
-
-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)
-7. **Publish** the batch
-8. **Update absorb_log.json:**
-   ```json
-   {
-     "entries": {
-       "<filename>": {
-         "absorbed_at": "<ISO timestamp>",
-         "absorbed_into": ["article-slug-1", "article-slug-2"]
-       }
-     },
-     "stats": {
-       "total_entries": <total>,
-       "absorbed": <count>,
-       "remaining": <count>
-     }
-   }
-   ```
-
-**Between batches**, share what you found:
+### Scaffold before writing
+
+Before you draft, scaffold the getting-started article locally:
 
 ```
-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
-    teardown thread from 2017
-  • New article: "Lockpicking Competitions" — there's a
-    whole competitive scene
-
-3 new articles, 4 enriched. Continuing...
+mcp__almanac__new({
+  community_slug: "<subreddit>",
+  articles: [{ title: "Getting Started with <Topic>", slug: "getting-started", topics: ["techniques"] }]
+})
 ```
 
-### When to stop
+This creates `~/.openalmanac/articles/<subreddit>/getting-started.md` with a placeholder body. Then edit that file with the full article content using `Write` or `Edit`.
 
-- If the user said "keep going with check-ins": continue until all entries are absorbed or the user says stop
-- If the user said "batch by batch": pause after each batch and ask if they want to continue
-- At the end, show a final tally:
+### Write it
 
-```
-Phase 2 complete. Processed X,XXX entries across N batches.
+Write the article in full using the voice, wikilinks, citations, images, and infobox guidance above. Aim for **2,000–2,500 words** for a featured/landing article. Shorter is fine for smaller communities; longer is okay if the material demands it.
 
-Final wiki:
-  XX articles (was YY)
-  XX remaining stubs
-  XXX+ citations from the community
+### Publish the article
 
-openalmanac.org/communities/<subreddit>/wiki
 ```
+mcp__almanac__publish({ slugs: ["getting-started"] })
+```
+
+Publish will delete the local draft after a successful push. If you need to edit after publishing, use `mcp__almanac__download` to pull the authoritative copy back from the server.
+
+### Immediately after publish: the stub flow
+
+As soon as the getting-started article is live, **extract every wikilink in it** and scaffold stubs for the ones that don't exist yet. This is the illusion-of-scale step — a wiki feels much bigger when every link in the landing article resolves.
+
+Steps:
+
+1. **Extract every `[[slug|...]]` and `[[slug]]`** from the article body. Do this against your in-memory draft **before** calling publish — publish deletes the local file, so waiting until after means you'd have to `download` it back first. If you're running the stub flow after a publish that already happened, `mcp__almanac__download` the getting-started article first, then read it with `Read` and extract with a regex like `\[\[([a-z0-9-]+)(\|[^\]]+)?\]\]`.
+2. Batch-call `mcp__almanac__search_articles` with all extracted slugs + their human names to find which already exist.
+3. For the ones that don't: batch-scaffold with `mcp__almanac__new(articles: [...], community_slug: "<subreddit>")`. Up to 50 per call. The scaffolded files contain only frontmatter and an empty body.
+4. (Optional) For each scaffolded stub, fill in a **one-line description** via `Edit` — either cold (from the entity name and surrounding article context, ~30–50 tokens) or slightly enriched if you remember something real about it from the corpus reading you already did. Do not do additional corpus searches per stub — use only what's already in your working memory. Cost: ~1,500–2,500 tokens for a typical 40-stub batch. Skipping this step is fine — empty stubs are valid and the backend sets `stub: true` automatically.
+5. `mcp__almanac__publish({ slugs: [...] })` the whole batch.
+
+After publishing, report back with a short message:
+
+> Getting-started is live. I also scaffolded and published 40 stubs for every wikilink in the article — belt-system, spool-pins, naughty-bucket, mit-guide-to-lock-picking, and more. The wiki now feels populated.
+>
+> A few of those stubs are worth filling out into real articles soon — especially the naughty-bucket one and the MIT Guide one, which aren't documented anywhere else on the internet. Want me to go write a couple of those too, or want to explore something else?
+
+This closing re-opens the conversation door without asking "are we done?"
+
+## The writing-agent brief (if you delegate)
 
-## Important rules
+For most runs, you'll write the getting-started article yourself because the conversation context is essential. But if you do delegate to a background agent (via the `Task` tool or similar), the agent's brief must include:
 
-### Citations
-- Every source MUST have a public URL. Reddit permalinks, web pages, YouTube — all fine.
-- If a source has no public URL, do NOT use it and do NOT cite it. Inform the user.
+1. **Which article to write** (specific slug + community_slug + path to the scaffolded file)
+2. **The scouting context**: everything you and the user discussed during exploration — the rituals, the quotes, the characters, the vocabulary, the moments the user got excited about. This is the most important part of the brief.
+3. **Corpus entries to read**: specific file paths in `~/.openalmanac/corpus/<subreddit>/entries/` that are relevant. Do not tell the agent to "read the corpus" — point at specific files.
+4. **The entity map**: list of slugs that will exist when scaffolding is done, for wikilink correctness.
+5. **Citation rules** (below).
+6. **Wikilink rules**: use `[[slug|Display]]`, search before creating new ones, prefer existing slugs.
+7. **Writing quality**: fetch `https://openalmanac.org/writing-guidelines` once, follow fandom-wiki voice, use the infobox format.
+8. **The specific quotes and details the user cared about** — pull these forward, do not assume the agent will rediscover them.
+
+## Citation rules
+
+- Every source **must have a public URL**. Reddit permalinks, web pages, PDFs, YouTube — all fine.
+- If a source has no public URL, do not use it and do not cite it.
 - Never fabricate or construct URLs.
-- 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
-- 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`
-- The description should have personality — capture the community's vibe, not a generic taxonomy
-- Find a good cover image with `search_images`
-
-### File access
-- Use `Glob` and `Read` tools to browse and read files in `~/.openalmanac/` — do NOT use `Bash(ls ...)` or `Bash(cat ...)`
-- Use `Write` and `Edit` tools to modify files — do NOT use `Bash(echo ...)` or `Bash(sed ...)`
-- The only Bash command you should use is the ingest script
-
-### What NOT to do
-- Don't estimate how long things will take
-- 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 skip Reddit as a source — the corpus IS the community's voice, cite it
+- **Corpus entries** come with `citation_key` and `source` (Reddit permalink) in their frontmatter. Use them as `[@citation_key]` markers in the article and add them to the `sources:` array.
+- **External sources** get the same treatment: `search_web` to find, `read_webpage` to verify, then cite with a BibTeX-style kebab-case key (e.g. `mit-guide-lockpicking`, `lpubelts-belts`).
+- **Every `[@key]` in the body must have a matching source**, and every source must be referenced at least once. Publish will reject drafts that violate this.
+- `accessed_date` is optional. If you omit it, the backend defaults it to today's date. Set it explicitly only for historical sources where the access date matters.
+
+## Entity linking rules
+
+- Always `search_articles` before creating new entities — check what already exists, stub or not.
+- Prefer existing slugs over inventing new ones.
+- `[[slug|Display Text]]` is the wikilink syntax.
+- Dead wikilinks auto-create stubs on publish, but the preferred pattern is **explicit scaffolding with `new()`** followed by the stub flow — it gives you a one-line description in each stub instead of a blank placeholder, which is better for browse experience.
+- `article_id` format on the server is `<community_slug>:<slug>` for community articles. You almost never have to construct this manually — the tools accept `(slug, community_slug)` pairs. Only relevant if you're reading from the DB directly.
+
+## Technical contract details (footgun prevention)
+
+- **Publishing deletes your local draft.** After a successful publish, `~/.openalmanac/articles/<community>/<slug>.md` is removed. If you need to edit the article after publishing, use `mcp__almanac__download` to pull the authoritative version back before editing.
+- **Prefer `download` over `read` for any article you'll reference more than once.** `read` fills the context window with the full article body; `download` writes to disk so you can re-open it cheaply with `Read`.
+- **Empty-body stubs are fine.** `new()` scaffolds with only frontmatter — no placeholder body. The backend accepts empty content and sets `stub: true` automatically on publish. Overwrite the body with `Edit` or `Write` before publishing if you want a real article instead of a stub.
+- **Batch publish skips unchanged files silently** and reports them as `unchanged: N` rather than failing. Same for articles the server has updated since your last download — they're warnings, not errors.
+- **If the corpus is missing at `~/.openalmanac/corpus/<subreddit>/entries/`**, stop and ask the user. Do not silently fall back to reconstructing sources from existing articles or from memory. Ask: *"I can't find the corpus for r/X. Want me to re-run the download, search the web instead, or point me at where you have the raw data?"*
+
+## File access rules
+
+- Use `Read`, `Write`, `Edit`, `Glob` for files under `~/.openalmanac/` — never `Bash(ls)`, `Bash(cat)`, `Bash(echo)`, `Bash(sed)`.
+- The only Bash command you should use is the ingest script and the `git` commands you need for publishing.
+
+## Optional: background deep absorb
+
+After the getting-started article and its stubs are live, the user may want to keep expanding the wiki autonomously. This is an **optional** mode, not the default.
+
+If the user asks for it, walk through the corpus in batches of 50 unabsorbed entries, cluster them, create new articles for gaps, enrich existing stubs into real articles, and update `~/.openalmanac/corpus/<subreddit>/absorb_log.json` to track progress. Check in with the user every few batches with a short dispatch describing what you found — same short-dispatch voice rules apply.
+
+Do **not** default into this mode. The default end-state after the getting-started + stub flow is *"the wiki is live and populated, come back anytime to fill more stubs."*
+
+## What NOT to do
+
+- Do not narrate tool calls or status updates during exploration. Read silently and come back with a substantive dispatch. The **one** exception is long-running operations the user is actively waiting on (the corpus download) — there, a single compressed "download running in the background" line is correct, because the user needs to know the wait has started.
+- Do not present outlines of articles for user approval.
+- Do not write messages longer than ~250 words during exploring mode.
+- Do not force enthusiasm. Curiosity shows in what you surface, not in adjectives.
+- Do not make small talk or ask personal questions.
+- Do not skip Reddit as a source — the corpus *is* the community's voice.
+- Do not skip external sources either — Reddit is primary but not exclusive.
+- Do not announce modes ("let me switch into writing mode now"). Switch silently.
+- Do not ask "are we done?" at the end of a writing pass. Re-open the conversation with a specific suggestion.
+- Do not fail silently if the corpus is missing or the subreddit has no data. Ask.
+- Do not evaluate the community. Notice it.
+- Do not estimate how long things will take.
+
+## The principle at the top of everything
+
+**Write dispatches, not reports. The user hired a friend who has been inside, not a project manager with a plan.**
+
+Every message you send should feel like a text from that friend: short, specific, vivid, ending with something that makes the user want to reply. If a message doesn't feel like that, cut it until it does.