@kernel.chat/kbot 3.98.0 → 3.99.0

package/dist/agent.js

@@ -875,7 +875,7 @@ export async function runAgent(message, options = {}) {
     // Step 2: Build context (cached — only rebuilt when inputs change)
     const matrixPrompt = options.agent ? getMatrixSystemPrompt(options.agent) : null;
     const contextSnippet = options.context ? formatContextForPrompt(options.context) : '';
-    const skillsSnippet = loadSkills(process.cwd());
+    const skillsSnippet = loadSkills(process.cwd(), message);
     const memorySnippet = getMemoryPrompt();
     const learningContext = buildFullLearningContext(message, process.cwd());
     const synthesisSnippet = getSynthesisContext(8); // Three-tier memory: reflection layer insights

package/dist/cli.js

@@ -835,6 +835,50 @@ async function main() {
             ignorePatterns,
         });
     });
+    const skillsCmd = program.command('skills').description('Manage agent skills (agentskills.io format — compatible with Claude Skills, Hermes, Copilot)');
+    skillsCmd
+        .command('list')
+        .description('List all discovered skills')
+        .action(async () => {
+        const { discoverSkillFiles } = await import('./skills-loader.js');
+        const skills = discoverSkillFiles(process.cwd());
+        if (skills.length === 0) {
+            printInfo('No skills found. Run `kbot skills import --from hermes` to import 76 Hermes skills.');
+            return;
+        }
+        printInfo(`Found ${skills.length} skill${skills.length === 1 ? '' : 's'}:\n`);
+        for (const s of skills) {
+            const desc = s.description ? ` — ${s.description.slice(0, 70)}` : '';
+            printInfo(`  ${s.name}${desc}`);
+        }
+    });
+    skillsCmd
+        .command('import')
+        .description('Import skills from an external agent (Hermes, Claude, or a custom directory)')
+        .option('--from <source>', 'Source: hermes, claude, or an absolute path', 'hermes')
+        .action(async (opts) => {
+        const { importExternalSkills } = await import('./skills-loader.js');
+        const { homedir } = await import('node:os');
+        const { join } = await import('node:path');
+        const { existsSync } = await import('node:fs');
+        const sources = {
+            hermes: join(homedir(), '.hermes', 'skills'),
+            claude: join(homedir(), '.claude', 'skills'),
+        };
+        const from = opts.from || 'hermes';
+        const src = sources[from] || from;
+        if (!existsSync(src)) {
+            printError(`Source not found: ${src}`);
+            if (from === 'hermes')
+                printInfo('Install Hermes: `ollama launch hermes --yes --model hermes3:8b`');
+            return;
+        }
+        const result = await importExternalSkills(src);
+        printSuccess(`Imported ${result.imported} skill${result.imported === 1 ? '' : 's'} from ${src}`);
+        if (result.skipped > 0)
+            printInfo(`  ${result.skipped} skipped (existing user-authored files preserved)`);
+        printInfo(`  → ${result.destination}`);
+    });
     program
         .command('doctor')
         .description('Diagnose your kbot setup — check everything is working')

package/dist/skills-loader.d.ts

@@ -2,16 +2,48 @@ export interface SkillFile {
     name: string;
     path: string;
     content: string;
+    description: string;
+    tags: string[];
     tokens: number;
+    /** Skill only activates when these toolsets are available (Hermes: requires_toolsets) */
+    requiresToolsets: string[];
+    /** Skill only activates when these toolsets are UNAVAILABLE (fallback path) */
+    fallbackForToolsets: string[];
+    /** OS platforms this skill supports; empty = all */
+    platforms: string[];
+    /** Related skill names */
+    relatedSkills: string[];
+    /** True for skills that ship with kbot or declare `metadata.kbot.*` — boosted in ranking */
+    native: boolean;
+}
+export interface SkillLoadContext {
+    /** Toolsets currently available — skills can require/fall-back based on these */
+    availableToolsets?: string[];
+    /** Current OS platform, e.g. 'darwin' | 'linux' | 'win32' */
+    platform?: string;
 }
 /**
- * Discover and load skill files from project and global directories.
- * Returns formatted string ready to inject into system prompt.
+ * Discover and load skill files. Returns a prompt-ready string.
+ * When `message` is provided, skills are scored for relevance and only the
+ * most relevant are included (keeps token budget tight with a large library).
  */
-export declare function loadSkills(projectRoot: string): string;
+export declare function loadSkills(projectRoot: string, message?: string, ctx?: SkillLoadContext): string;
 /**
- * Discover .md files from both project-local and global skill directories.
- * Project skills take precedence (loaded first, consume token budget first).
+ * Walk both skill roots and return every skill document found.
+ * Handles flat files (name.md) AND subdirectory layouts (cat/name/SKILL.md).
+ * Project skills take precedence over global skills with the same name.
  */
 export declare function discoverSkillFiles(projectRoot: string): SkillFile[];
+export interface ImportResult {
+    imported: number;
+    skipped: number;
+    source: string;
+    destination: string;
+}
+/**
+ * Copy (as symlinks) every SKILL.md under a foreign skills directory
+ * into ~/.kbot/skills/imported/<category>/<name>/SKILL.md.
+ * Non-destructive: existing symlinks are replaced, real files are skipped.
+ */
+export declare function importExternalSkills(sourceRoot: string): Promise<ImportResult>;
 //# sourceMappingURL=skills-loader.d.ts.map

package/dist/skills-loader.js

@@ -1,92 +1,384 @@
-// Skills Loader — Auto-discover and load .md skill files
+// Skills Loader — Auto-discover and load skill documents
 //
-// Skill files are Markdown documents that inject domain knowledge, tool combinations,
-// and project-specific patterns into the agent's context. They're the kbot equivalent
-// of Copilot's "Agent Skills" or Cursor's "Rules for AI."
+// Supports two formats:
+//   1. kbot native:       ~/.kbot/skills/<name>.md                (flat)
+//   2. agentskills.io:    ~/.kbot/skills/<category>/<name>/SKILL.md (Claude/Hermes/Copilot standard)
+//
+// Frontmatter fields recognized (either format):
+//   name | title         — skill identifier
+//   description          — 1-line "when to use this"
+//   keywords | tags      — list for relevance matching
+//   metadata.hermes.tags — agentskills.io tag list (Hermes/Claude)
+//   domain               — kbot category
 //
 // Discovery locations (in priority order):
-//   1. ./.kbot/skills/*.md  — project-specific skills
-//   2. ~/.kbot/skills/*.md  — user global skills
+//   1. ./.kbot/skills/   — project-specific
+//   2. ~/.kbot/skills/   — user global (includes imported Hermes/Claude skills)
 //
-// Token budget: 2000 tokens max (~8000 characters) to leave room for
-// repo map, learning context, and memory.
-import { existsSync, readdirSync, readFileSync } from 'node:fs';
-import { join, basename } from 'node:path';
+// Token budget: 2000 tokens max. When a message is provided, skills are
+// scored for relevance and only the top matches are injected — so a user
+// with 200 imported skills doesn't blow the budget on irrelevant docs.
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, basename, dirname } from 'node:path';
 import { homedir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+/** Package-bundled skills directory — ships with the npm tarball. */
+function getBundledSkillsDir() {
+    // dist/skills-loader.js → ../skills  (package root)
+    const here = dirname(fileURLToPath(import.meta.url));
+    return join(here, '..', 'skills');
+}
 const MAX_SKILL_TOKENS = 2000;
+const MAX_SKILLS_WITHOUT_MESSAGE = 6; // unfiltered cap
+const MAX_SKILLS_WITH_MESSAGE = 4; // relevance-filtered cap
 const estimateTokens = (text) => Math.ceil(text.length / 4);
 /**
- * Discover and load skill files from project and global directories.
- * Returns formatted string ready to inject into system prompt.
+ * Discover and load skill files. Returns a prompt-ready string.
+ * When `message` is provided, skills are scored for relevance and only the
+ * most relevant are included (keeps token budget tight with a large library).
  */
-export function loadSkills(projectRoot) {
-    const skills = discoverSkillFiles(projectRoot);
-    if (skills.length === 0)
+export function loadSkills(projectRoot, message, ctx) {
+    const all = discoverSkillFiles(projectRoot);
+    if (all.length === 0)
         return '';
-    return formatSkillsForPrompt(skills);
+    const filtered = applyConditionalActivation(all, ctx);
+    if (filtered.length === 0)
+        return '';
+    const selected = message ? rankByRelevance(filtered, message) : filtered;
+    return formatSkillsForPrompt(selected, message ? MAX_SKILLS_WITH_MESSAGE : MAX_SKILLS_WITHOUT_MESSAGE);
 }
 /**
- * Discover .md files from both project-local and global skill directories.
- * Project skills take precedence (loaded first, consume token budget first).
+ * Filter skills by platform and toolset conditions.
+ * Matches Hermes's activation semantics:
+ *   - `platforms: [darwin]` — only loads on macOS
+ *   - `requires_toolsets: [browser]` — only loads when browser tools are available
+ *   - `fallback_for_toolsets: [browser]` — only loads when browser tools are NOT available
+ */
+function applyConditionalActivation(skills, ctx) {
+    const platform = ctx?.platform ?? process.platform;
+    const toolsets = new Set((ctx?.availableToolsets ?? []).map(t => t.toLowerCase()));
+    return skills.filter(s => {
+        if (s.platforms.length > 0 && !s.platforms.some(p => platform.startsWith(p)))
+            return false;
+        if (s.requiresToolsets.length > 0 && !s.requiresToolsets.every(t => toolsets.has(t.toLowerCase())))
+            return false;
+        if (s.fallbackForToolsets.length > 0 && s.fallbackForToolsets.some(t => toolsets.has(t.toLowerCase())))
+            return false;
+        return true;
+    });
+}
+/**
+ * Walk both skill roots and return every skill document found.
+ * Handles flat files (name.md) AND subdirectory layouts (cat/name/SKILL.md).
+ * Project skills take precedence over global skills with the same name.
  */
 export function discoverSkillFiles(projectRoot) {
+    // Precedence (first wins on name collision):
+    //   1. project-local — most specific, author's own
+    //   2. bundled       — kbot-curated skills shipping with the package
+    //   3. user-global   — includes imported third-party skills (symlinks)
     const locations = [
-        join(projectRoot, '.kbot', 'skills'), // Project-specific
-        join(homedir(), '.kbot', 'skills'), // User global
+        join(projectRoot, '.kbot', 'skills'),
+        getBundledSkillsDir(),
+        join(homedir(), '.kbot', 'skills'),
     ];
     const skills = [];
-    const seen = new Set(); // Deduplicate by filename
-    for (const dir of locations) {
-        if (!existsSync(dir))
+    const seen = new Set();
+    for (const root of locations) {
+        if (!existsSync(root))
+            continue;
+        walkSkillRoot(root, skills, seen);
+    }
+    return skills;
+}
+function walkSkillRoot(root, out, seen, depth = 0) {
+    if (depth > 3)
+        return; // guard against deep nesting
+    let entries;
+    try {
+        entries = readdirSync(root);
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        if (entry.startsWith('.') || entry === 'node_modules')
             continue;
+        const full = join(root, entry);
+        let stat;
         try {
-            const files = readdirSync(dir)
-                .filter(f => f.endsWith('.md'))
-                .sort(); // Alphabetical for deterministic ordering
-            for (const file of files) {
-                if (seen.has(file))
-                    continue; // Project overrides global
-                seen.add(file);
-                try {
-                    const path = join(dir, file);
-                    const content = readFileSync(path, 'utf-8').trim();
-                    if (content.length === 0)
-                        continue;
-                    skills.push({
-                        name: basename(file, '.md'),
-                        path,
-                        content,
-                        tokens: estimateTokens(content),
-                    });
-                }
-                catch { /* permission denied, etc. */ }
+            stat = statSync(full);
+        }
+        catch {
+            continue;
+        }
+        if (stat.isDirectory()) {
+            // Subdirectory layout: look for SKILL.md first (agentskills.io standard)
+            const skillMd = join(full, 'SKILL.md');
+            if (existsSync(skillMd)) {
+                tryAddSkill(skillMd, entry, out, seen);
             }
+            else {
+                // Category directory — recurse
+                walkSkillRoot(full, out, seen, depth + 1);
+            }
+        }
+        else if (entry.endsWith('.md') && entry !== 'README.md') {
+            const name = basename(entry, '.md');
+            tryAddSkill(full, name, out, seen);
         }
-        catch { /* directory read error */ }
     }
-    return skills;
+}
+function tryAddSkill(path, fallbackName, out, seen) {
+    let content;
+    try {
+        content = readFileSync(path, 'utf-8').trim();
+    }
+    catch {
+        return;
+    }
+    if (!content)
+        return;
+    const parsed = parseFrontmatter(content);
+    const name = String(parsed.fm.name ?? parsed.fm.title ?? fallbackName).trim() || fallbackName;
+    if (seen.has(name))
+        return;
+    seen.add(name);
+    const description = String(parsed.fm.description ?? '').trim();
+    const tags = extractTags(parsed.fm);
+    const hermesMeta = parsed.fm.metadata?.hermes ?? {};
+    const kbotMeta = parsed.fm.metadata?.kbot ?? {};
+    const asList = (v) => {
+        if (Array.isArray(v))
+            return v.map(String).map(s => s.trim()).filter(Boolean);
+        if (typeof v === 'string')
+            return v.split(',').map(s => s.trim()).filter(Boolean);
+        return [];
+    };
+    const bundledDir = getBundledSkillsDir();
+    const native = path.startsWith(bundledDir) || Object.keys(kbotMeta).length > 0;
+    out.push({
+        name,
+        path,
+        content,
+        description,
+        tags,
+        tokens: estimateTokens(content),
+        requiresToolsets: [...asList(kbotMeta.requires_toolsets), ...asList(hermesMeta.requires_toolsets)],
+        fallbackForToolsets: [...asList(kbotMeta.fallback_for_toolsets), ...asList(hermesMeta.fallback_for_toolsets)],
+        platforms: asList(parsed.fm.platforms),
+        relatedSkills: [...asList(kbotMeta.related_skills), ...asList(hermesMeta.related_skills)],
+        native,
+    });
 }
 /**
- * Format skill files for prompt injection, respecting token budget.
+ * Lightweight YAML-frontmatter parser. Handles the subset skills use:
+ *   key: value
+ *   key: [a, b, c]
+ *   metadata:
+ *     hermes:
+ *       tags: [x, y]
+ * Avoids pulling in a full YAML dep. Good enough for flat skill metadata.
  */
-function formatSkillsForPrompt(skills, maxTokens = MAX_SKILL_TOKENS) {
+function parseFrontmatter(content) {
+    if (!content.startsWith('---'))
+        return { fm: {}, body: content };
+    const end = content.indexOf('\n---', 3);
+    if (end < 0)
+        return { fm: {}, body: content };
+    const yaml = content.slice(3, end).trim();
+    const body = content.slice(end + 4).trim();
+    const fm = {};
+    const stack = [{ indent: -1, obj: fm }];
+    for (const rawLine of yaml.split('\n')) {
+        const line = rawLine.replace(/\s+$/, '');
+        if (!line.trim() || line.trim().startsWith('#'))
+            continue;
+        const indent = line.match(/^ */)[0].length;
+        while (stack.length > 1 && indent <= stack[stack.length - 1].indent)
+            stack.pop();
+        const parent = stack[stack.length - 1].obj;
+        const m = line.trim().match(/^([A-Za-z0-9_\-]+)\s*:\s*(.*)$/);
+        if (!m)
+            continue;
+        const [, key, valueRaw] = m;
+        const value = valueRaw.trim();
+        if (!value) {
+            // Nested object
+            const child = {};
+            parent[key] = child;
+            stack.push({ indent, obj: child });
+            continue;
+        }
+        parent[key] = parseScalar(value);
+    }
+    return { fm, body };
+}
+function parseScalar(value) {
+    // Inline list: [a, b, "c"]
+    if (value.startsWith('[') && value.endsWith(']')) {
+        return value.slice(1, -1)
+            .split(',')
+            .map(s => s.trim().replace(/^["']|["']$/g, ''))
+            .filter(Boolean);
+    }
+    // Quoted string
+    if ((value.startsWith('"') && value.endsWith('"')) ||
+        (value.startsWith("'") && value.endsWith("'"))) {
+        return value.slice(1, -1);
+    }
+    return value;
+}
+function extractTags(fm) {
+    const tags = [];
+    const push = (v) => {
+        if (Array.isArray(v))
+            tags.push(...v.map(String));
+        else if (typeof v === 'string')
+            tags.push(...v.split(',').map(s => s.trim()).filter(Boolean));
+    };
+    push(fm.keywords);
+    push(fm.tags);
+    const meta = fm.metadata;
+    if (meta && typeof meta === 'object') {
+        push(meta.hermes?.tags);
+        push(meta.claude?.tags);
+    }
+    return [...new Set(tags.map(t => t.toLowerCase()))];
+}
+// ── Relevance scoring ────────────────────────────────────────────────
+function rankByRelevance(skills, message) {
+    const terms = tokenize(message);
+    if (terms.size === 0)
+        return skills;
+    const scored = skills.map(s => ({ skill: s, score: scoreSkill(s, terms) }));
+    scored.sort((a, b) => b.score - a.score);
+    // Keep skills with at least one hit; fall back to top-N if nothing matches
+    const hits = scored.filter(x => x.score > 0);
+    return (hits.length > 0 ? hits : scored).map(x => x.skill);
+}
+function scoreSkill(skill, terms) {
+    let score = 0;
+    const nameTokens = tokenize(skill.name);
+    const descTokens = tokenize(skill.description);
+    for (const t of terms) {
+        if (nameTokens.has(t))
+            score += 3;
+        if (skill.tags.some(tag => tag === t || tag.includes(t)))
+            score += 2;
+        if (descTokens.has(t))
+            score += 1;
+    }
+    // Bundled kbot-native skills get a curated-content boost over imported third-party skills.
+    // Only applied when the skill already matched on something (score > 0) — we don't surface
+    // unrelated native skills over perfectly-matched imported ones.
+    if (score > 0 && skill.native)
+        score += 2;
+    return score;
+}
+const STOPWORDS = new Set([
+    'the', 'a', 'an', 'and', 'or', 'but', 'if', 'then', 'of', 'to', 'for', 'in', 'on', 'at',
+    'with', 'by', 'is', 'are', 'was', 'were', 'be', 'been', 'this', 'that', 'it', 'i', 'you',
+    'we', 'they', 'how', 'what', 'when', 'why', 'can', 'do', 'does', 'please',
+]);
+function tokenize(text) {
+    const out = new Set();
+    // Split on non-alphanumeric AND on kebab/snake separators so "daemon-deployment"
+    // and "skill_self_authorship" both yield useful word tokens.
+    for (const raw of text.toLowerCase().split(/[^a-z0-9]+/)) {
+        if (raw.length < 3)
+            continue;
+        if (STOPWORDS.has(raw))
+            continue;
+        out.add(raw);
+    }
+    return out;
+}
+// ── Prompt formatting ────────────────────────────────────────────────
+function formatSkillsForPrompt(skills, maxSkills) {
     const parts = [];
     let currentTokens = 0;
+    let included = 0;
     for (const skill of skills) {
-        if (currentTokens + skill.tokens > maxTokens) {
-            // Try to fit a truncated version
-            const remaining = maxTokens - currentTokens;
+        if (included >= maxSkills)
+            break;
+        if (currentTokens + skill.tokens > MAX_SKILL_TOKENS) {
+            const remaining = MAX_SKILL_TOKENS - currentTokens;
             if (remaining > 100) {
                 const truncated = skill.content.slice(0, remaining * 4) + '\n...(truncated)';
                 parts.push(`## Skill: ${skill.name}\n${truncated}`);
+                included++;
             }
             break;
         }
         parts.push(`## Skill: ${skill.name}\n${skill.content}`);
         currentTokens += skill.tokens;
+        included++;
     }
     if (parts.length === 0)
         return '';
     return `\n\n[Custom Skills]\n${parts.join('\n---\n')}`;
 }
+/**
+ * Copy (as symlinks) every SKILL.md under a foreign skills directory
+ * into ~/.kbot/skills/imported/<category>/<name>/SKILL.md.
+ * Non-destructive: existing symlinks are replaced, real files are skipped.
+ */
+export async function importExternalSkills(sourceRoot) {
+    const { mkdirSync, symlinkSync, unlinkSync, lstatSync } = await import('node:fs');
+    const destRoot = join(homedir(), '.kbot', 'skills', 'imported');
+    mkdirSync(destRoot, { recursive: true });
+    let imported = 0;
+    let skipped = 0;
+    const walk = (dir, rel) => {
+        let entries;
+        try {
+            entries = readdirSync(dir);
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            if (e.startsWith('.'))
+                continue;
+            const full = join(dir, e);
+            let st;
+            try {
+                st = statSync(full);
+            }
+            catch {
+                continue;
+            }
+            if (st.isDirectory()) {
+                const skillMd = join(full, 'SKILL.md');
+                if (existsSync(skillMd)) {
+                    const destDir = join(destRoot, rel, e);
+                    mkdirSync(destDir, { recursive: true });
+                    const destFile = join(destDir, 'SKILL.md');
+                    try {
+                        if (existsSync(destFile)) {
+                            const ls = lstatSync(destFile);
+                            if (ls.isSymbolicLink())
+                                unlinkSync(destFile);
+                            else {
+                                skipped++;
+                                continue;
+                            } // don't clobber user-authored file
+                        }
+                        symlinkSync(skillMd, destFile);
+                        imported++;
+                    }
+                    catch {
+                        skipped++;
+                    }
+                }
+                else {
+                    walk(full, join(rel, e));
+                }
+            }
+        }
+    };
+    walk(sourceRoot, '');
+    return { imported, skipped, source: sourceRoot, destination: destRoot };
+}
 //# sourceMappingURL=skills-loader.js.map

package/dist/train-self.js

@@ -193,7 +193,7 @@ export async function trainSelf(opts = {}) {
             `SYSTEM "You are kbot's self-trained assistant (${mode} mode). You were fine-tuned on the operator's own agent sessions."`,
         ].join('\n');
         try {
-            require('node:fs').writeFileSync(modelfilePath, modelfile);
+            writeFileSync(modelfilePath, modelfile);
             const cmd = `ollama create ${outputName} -f ${modelfilePath}`;
             const r = shell(cmd);
             log('deploy', r.ok, Date.now() - t0, r.output.split('\n').slice(-8).join('\n'));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kernel.chat/kbot",
-  "version": "3.98.0",
+  "version": "3.99.0",
   "description": "Open-source terminal AI agent. 787+ tools, 35 agents, 20 providers. Dreams, learns, watches your system. Controls your phone. Fully local, fully sovereign. MIT.",
   "type": "module",
   "repository": {
@@ -103,6 +103,7 @@
     "!dist/**/*.test.d.ts",
     "!dist/**/*.js.map",
     "!dist/**/*.d.ts.map",
+    "skills/**/*.md",
     "README.md",
     "install.sh",
     "ollama-manifest.json"

package/skills/deployment/daemon-deployment/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: daemon-deployment
+description: Use when setting up 24/7 background workers. kbot's compound improvement depends on daemons running even when nobody is looking.
+version: 1.0.0
+author: kbot
+license: MIT
+platforms: [darwin, linux]
+metadata:
+  kbot:
+    tags: [daemon, launchd, background, 24-7, compound]
+    related_skills: [autopoiesis-loop, teacher-trace-curation]
+---
+
+# Daemon Deployment
+
+kbot's intelligence doesn't sleep. Three daemons run continuously:
+- `kbot-daemon` — code quality, i18n sync, embeddings, docs gaps (every 15 min)
+- `kbot-discovery-daemon` — self-advocacy, field intelligence (every 15 min → 24 hr cycles)
+- `kbot-social-daemon` — autonomous posting to X/Bluesky/Mastodon/LinkedIn (daily)
+
+Plus a weekly `train-self` that fine-tunes the local model on curated traces.
+
+## Iron Law
+
+```
+VERIFY THE DAEMON IS ACTUALLY RUNNING AFTER INSTALL.
+```
+
+launchd plists that fail silently are the single most common cause of "kbot feels stale" — the daemon was never loaded, so no compound improvement happened.
+
+## Install Sequence (macOS)
+
+1. `npm run daemon` — run once manually to confirm it works at all.
+2. `npm run daemon:start` — loads the launchd plist.
+3. **Verify**: `launchctl list | grep kernel.kbot` — should show a running entry with PID.
+4. **Confirm output**: `tail -f tools/daemon-reports/daemon.log` — should show activity within 15 min.
+5. **Check state**: `npm run daemon:stats` — shows task timestamps, token usage, cost savings.
+
+If any of steps 3–5 fail, the daemon is not actually running. Debug before moving on.
+
+## Per-Daemon Triggers
+
+- `com.kernel.kbot-daemon.plist` → every 15 min
+- `com.kernel.kbot-discovery.plist` → every 15 min (internal sub-cycles stagger)
+- `com.kernel.kbot-social.plist` → daily at 9am
+- `com.kernel.kbot-train-self.plist` → Sundays 3am
+
+## What You Gain
+
+- Daily digest of codebase activity (without asking).
+- i18n stays in sync across 24 languages automatically.
+- Embedding index for semantic search rebuilds overnight.
+- Social presence grows without manual posting.
+- Local fine-tune stays current with your actual work.
+
+Cost: zero. All daemon work routes through local Ollama models.
+
+## Failure Modes
+
+- **Mac sleep blocks launchd** — use `caffeinate` or enable "wake for network access" in Energy Saver if you need guaranteed intervals.
+- **Ollama not running** — daemons depend on `localhost:11434`. Either start Ollama at login OR the daemon silently no-ops. Add Ollama to Login Items.
+- **Filesystem permission errors** — daemon's user context may differ from your shell. Absolute paths in plist, check `~/.kbot/` is writable by the daemon user.
+
+## Rollback
+
+`npm run daemon:stop` unloads the plist. Work resumes manually. No state is lost — `tools/daemon-reports/state.json` persists until the daemon re-enables.
+
+## What Emerges
+
+After two weeks of active daemons, the user finds: i18n is always current, the daily digest email is actually read, social posts have engagement, the local model passes a basic task without Claude. The compound output is larger than any single feature could produce.