@phuetz/code-buddy 1.2.0 → 1.3.1

package/dist/server/index.js

@@ -844,6 +844,10 @@ function createApp(config) {
     app.use(errorHandler);
     return app;
 }
+/** Guards the sensory layer against double-wiring on a second in-process start. */
+let sensoryWired = false;
+/** Teardown fns for the sensory layer (bridge close, listener unsubscribes, scheduler stop). */
+let sensoryTeardown = [];
 /**
  * Start the server
  */
@@ -1018,6 +1022,80 @@ export async function startServer(userConfig = {}) {
             logger.info(`Metrics Dashboard: ${baseUrl}/api/metrics/dashboard`);
             logger.info(`Docs: ${baseUrl}/api/docs`);
             logger.info(`WebSocket: ${config.websocketEnabled ? 'Enabled (/ws)' : 'Disabled'}`);
+            // Sensory nervous-system bridge (opt-in): ingress for the Rust buddy-sense
+            // daemon → internal event bus → reactions. Loopback-only.
+            if (process.env.CODEBUDDY_SENSORY === 'true' && !sensoryWired) {
+                sensoryWired = true; // wire once per process (a 2nd start would double listeners + re-bind the port)
+                try {
+                    const { startSensoryBridge } = await import('../sensory/sensory-bridge.js');
+                    const { wireSensoryReactions } = await import('../sensory/reactions.js');
+                    const { getHeartbeatScheduler } = await import('../sensory/heartbeat-scheduler.js');
+                    const sensoryBridgeHandle = startSensoryBridge();
+                    const unwireReactions = wireSensoryReactions();
+                    sensoryTeardown.push(() => sensoryBridgeHandle.close(), unwireReactions);
+                    // Vision reaction (opt-in) — vision/motion → camera_analyze (local gemma).
+                    // Requires a shared token: a frame can trigger the webcam, so refuse to
+                    // wire it on an unauthenticated bridge.
+                    const sensoryToken = process.env.CODEBUDDY_SENSORY_TOKEN;
+                    {
+                        const { shouldWireVisionReaction, wireVisionReaction } = await import('../sensory/vision-reaction.js');
+                        if (shouldWireVisionReaction({ camera: process.env.CODEBUDDY_SENSORY_CAMERA, token: sensoryToken })) {
+                            sensoryTeardown.push(wireVisionReaction());
+                            logger.info('Sensory vision reaction: Enabled (vision/motion → camera_analyze)');
+                        }
+                        else if (process.env.CODEBUDDY_SENSORY_CAMERA === 'true') {
+                            logger.warn('Sensory vision reaction NOT enabled: set CODEBUDDY_SENSORY_TOKEN to allow camera triggering.');
+                        }
+                    }
+                    // Screen reaction (opt-in) — also token-gated (an injected analyzer could capture the desktop).
+                    if (process.env.CODEBUDDY_SENSORY_SCREEN === 'true') {
+                        if (sensoryToken) {
+                            const { wireScreenReaction } = await import('../sensory/screen-reaction.js');
+                            sensoryTeardown.push(wireScreenReaction());
+                            logger.info('Sensory screen reaction: Enabled (screen/change → percept)');
+                        }
+                        else {
+                            logger.warn('Sensory screen reaction NOT enabled: set CODEBUDDY_SENSORY_TOKEN.');
+                        }
+                    }
+                    // Speech reaction (opt-in) — speech_end → STT → 'hearing' percept (+ onHeard hook).
+                    if (process.env.CODEBUDDY_SENSORY_SPEECH === 'true') {
+                        const { wireSpeechReaction } = await import('../sensory/speech-reaction.js');
+                        sensoryTeardown.push(wireSpeechReaction());
+                        logger.info('Sensory speech reaction: Enabled (speech_end → STT → percept)');
+                    }
+                    // Privacy: camera/screen descriptions land in percepts.jsonl — warn if not encrypted at rest.
+                    if ((process.env.CODEBUDDY_SENSORY_CAMERA === 'true' || process.env.CODEBUDDY_SENSORY_SCREEN === 'true') &&
+                        !process.env.CODEBUDDY_COMPANION_ENCRYPTION_KEY &&
+                        !process.env.CODEBUDDY_MEMORY_KEY) {
+                        logger.warn('Sensory camera/screen percepts are written UNENCRYPTED — set CODEBUDDY_COMPANION_ENCRYPTION_KEY to encrypt scene/screen descriptions at rest.');
+                    }
+                    // Heartbeat pacemaker — heartbeats trigger periodic processing (every N beats).
+                    const heart = getHeartbeatScheduler();
+                    const everyBeats = Math.max(1, Number(process.env.CODEBUDDY_HEARTBEAT_EVERY ?? 10));
+                    heart.register({
+                        name: 'pacemaker-tick',
+                        everyBeats,
+                        handler: (ctx) => logger.info(`[heartbeat] pacemaker tick — beat ${ctx.beat} (load ${ctx.load1 ?? '?'})`),
+                    });
+                    // Dreaming — consolidate short-term sensory memory every N beats.
+                    const dreamEvery = Math.max(1, Number(process.env.CODEBUDDY_DREAM_EVERY ?? 30));
+                    heart.register({
+                        name: 'dreaming',
+                        everyBeats: dreamEvery,
+                        handler: async () => {
+                            const { runDreamingPass } = await import('../sensory/dreaming.js');
+                            await runDreamingPass();
+                        },
+                    });
+                    heart.start();
+                    sensoryTeardown.push(() => heart.stop());
+                    logger.info(`Sensory bridge: Enabled (buddy-sense → event bus; heartbeat treatments every ${everyBeats} beats)`);
+                }
+                catch (err) {
+                    logger.warn(`Sensory bridge failed to start: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
             logger.info(`Auth: ${config.authEnabled ? 'Enabled' : 'Disabled'}`);
             if (!isLoopbackHost(config.host)) {
                 logger.warn(`Server is bound to ${config.host} (non-loopback) and is reachable from the network. ` +
@@ -1072,6 +1150,17 @@ export async function startServer(userConfig = {}) {
  * Stop the server gracefully
  */
 export async function stopServer(server) {
+    // Tear down the sensory layer (WS bridge, bus listeners, heartbeat scheduler) so
+    // an in-process restart doesn't leak listeners or EADDRINUSE the bridge port.
+    for (const teardown of sensoryTeardown.splice(0)) {
+        try {
+            await teardown();
+        }
+        catch {
+            /* never throw on shutdown */
+        }
+    }
+    sensoryWired = false;
     return new Promise((resolve, reject) => {
         // Phase (d).9 — cancel the heartbeat timer so it doesn't keep
         // emitting against a half-shut server. Idempotent.

package/dist/services/prompt-builder.d.ts

@@ -12,6 +12,7 @@
 import { EnhancedMemory, PersistentMemoryManager } from "../memory/index.js";
 import { PromptCacheManager } from "../optimization/prompt-cache.js";
 import { MoltbotHooksManager } from "../hooks/moltbot-hooks.js";
+import { type ContextRegistry } from "../context/project-context.js";
 import { type QueryComplexity } from "../agent/execution/query-classifier.js";
 export interface PromptBuilderConfig {
     yoloMode: boolean;
@@ -48,7 +49,16 @@ export declare class PromptBuilder {
     private memory?;
     private moltbotHooksManager?;
     private persistentMemory?;
+    /**
+     * Dedup registry for project-instruction files, recreated fresh at the start
+     * of each system-prompt build. The JIT context pass reads it (via
+     * `getContextRegistry()`) so files already injected at startup are not
+     * re-injected when a tool later touches a file in the same tree.
+     */
+    private contextRegistry;
     constructor(config: PromptBuilderConfig, promptCacheManager: PromptCacheManager, memory?: EnhancedMemory | undefined, moltbotHooksManager?: MoltbotHooksManager | undefined, persistentMemory?: PersistentMemoryManager | undefined);
+    /** The registry from the most recent system-prompt build (for the JIT pass). */
+    getContextRegistry(): ContextRegistry | null;
     /**
      * Build the system prompt for the agent. The optional `options`
      * parameter gates per-block injection. All gates default to `true`

package/dist/services/prompt-builder.js

@@ -13,6 +13,7 @@ import { logger } from "../utils/logger.js";
 import { getErrorMessage } from "../errors/index.js";
 import { getSystemPromptForMode, getPromptManager, autoSelectPromptId, getChatOnlySystemPrompt, } from "../prompts/index.js";
 import { getModelToolConfig } from "../config/model-tools.js";
+import { resolveProjectContext, createContextRegistry, setActiveContextRegistry } from "../context/project-context.js";
 import { classifyQuery } from "../agent/execution/query-classifier.js";
 import { filterToolNames, getToolFilter, isToolNameAllowed, } from "../utils/tool-filter.js";
 const ALL_BLOCKS = {
@@ -65,6 +66,13 @@ export class PromptBuilder {
     memory;
     moltbotHooksManager;
     persistentMemory;
+    /**
+     * Dedup registry for project-instruction files, recreated fresh at the start
+     * of each system-prompt build. The JIT context pass reads it (via
+     * `getContextRegistry()`) so files already injected at startup are not
+     * re-injected when a tool later touches a file in the same tree.
+     */
+    contextRegistry = null;
     constructor(config, promptCacheManager, memory, moltbotHooksManager, persistentMemory) {
         this.config = config;
         this.promptCacheManager = promptCacheManager;
@@ -72,6 +80,10 @@ export class PromptBuilder {
         this.moltbotHooksManager = moltbotHooksManager;
         this.persistentMemory = persistentMemory;
     }
+    /** The registry from the most recent system-prompt build (for the JIT pass). */
+    getContextRegistry() {
+        return this.contextRegistry;
+    }
     /**
      * Build the system prompt for the agent. The optional `options`
      * parameter gates per-block injection. All gates default to `true`
@@ -248,18 +260,36 @@ export class PromptBuilder {
                     logger.warn('Failed to inject execution-discipline block', { error: getErrorMessage(err) });
                 }
             }
-            // Inject bootstrap context files (BOOTSTRAP.md, AGENTS.md, SOUL.md, etc.)
+            // Inject project-instruction context (AGENTS.md / CODEBUDDY.md / CLAUDE.md
+            // / GEMINI.md / CONTEXT.md / INSTRUCTIONS.md) via the unified hierarchical
+            // loader, then soul/bootstrap files. A fresh dedup registry is created per
+            // build and reused by the JIT pass (`getContextRegistry`).
             if (gates.includeBootstrap) {
+                this.contextRegistry = createContextRegistry();
+                // Publish for the JIT pass so it skips files injected here at startup.
+                setActiveContextRegistry(this.contextRegistry);
+                try {
+                    const ctx = resolveProjectContext({ cwd: this.config.cwd, registry: this.contextRegistry });
+                    if (ctx.text) {
+                        systemPrompt += '\n\n# Workspace Context\n\n' + ctx.text;
+                        logger.debug(`Loaded project context from ${ctx.sources.length} file(s)`, {
+                            sources: ctx.sources.map((s) => s.relPath),
+                            chars: ctx.bytes,
+                            truncated: ctx.truncated,
+                        });
+                    }
+                }
+                catch (err) {
+                    logger.warn("Failed to load project context", { error: getErrorMessage(err) });
+                }
+                // Soul/identity bootstrap files (SOUL.md, USER.md, …) + PROJECT_KNOWLEDGE.md.
+                // Instruction files are handled above by the unified loader, not here.
                 try {
                     const { BootstrapLoader } = await import('../context/bootstrap-loader.js');
                     const bootstrap = await new BootstrapLoader().load(this.config.cwd);
                     if (bootstrap.content) {
-                        systemPrompt += '\n\n# Workspace Context\n\n' + bootstrap.content;
-                        logger.debug(`Loaded bootstrap context from ${bootstrap.sources.length} file(s)`, {
-                            sources: bootstrap.sources,
-                            chars: bootstrap.tokenCount,
-                            truncated: bootstrap.truncated,
-                        });
+                        systemPrompt += '\n\n' + bootstrap.content;
+                        logger.debug(`Loaded bootstrap/soul context from ${bootstrap.sources.length} file(s)`);
                     }
                 }
                 catch (err) {
@@ -325,6 +355,31 @@ export class PromptBuilder {
                 }
                 catch { /* rules module optional */ }
             }
+            // Steer toward Code Explorer (gitnexus) when it is connected. Conditional:
+            // when Code Explorer is absent this injects nothing, so the built-in
+            // code_graph/codebase_map behaviour is unchanged. Presence is session-
+            // stable, so this stays in the cache-stable prefix.
+            try {
+                const { isCodeExplorerAvailable } = await import('../codebuddy/tools.js');
+                if (isCodeExplorerAvailable()) {
+                    systemPrompt +=
+                        `\n\n<code_explorer_priority>\n` +
+                            `Code Explorer (gitnexus) is connected. For ANY question about code relationships — ` +
+                            `callers/callees, blast radius / impact ("what breaks if I change X"), dead code, cycles, ` +
+                            `coupling, complexity — PREFER its MCP tools (\`mcp__gitnexus__impact\`, ` +
+                            `\`mcp__gitnexus__context\`, \`mcp__gitnexus__query\`, \`mcp__gitnexus__find_cycles\`, …) ` +
+                            `over the built-in \`code_graph\` / \`codebase_map\`: the gitnexus graph is broader and more ` +
+                            `complete (whole-repo, 14 languages).\n` +
+                            `Usage: first call \`mcp__gitnexus__list_repos\` once to get the repo \`path\`/\`id\`, then call ` +
+                            `\`mcp__gitnexus__impact\` with the REQUIRED \`target\` = the symbol name (e.g. \`target: "executePlan"\`, ` +
+                            `optionally \`direction: "both"\`) and \`repo\` = that path; or \`mcp__gitnexus__context\` with \`name\` = ` +
+                            `the symbol. Always include \`target\`/\`name\` — never call these tools with empty arguments. ` +
+                            `Use the built-in \`code_graph\`/\`codebase_map\` only as a fallback if a gitnexus tool errors.\n` +
+                            `</code_explorer_priority>`;
+                    logger.debug('Injected Code Explorer priority directive');
+                }
+            }
+            catch { /* tools module optional */ }
             // Inject active skill prompt enhancement
             if (gates.includeSkills) {
                 try {
@@ -338,10 +393,11 @@ export class PromptBuilder {
                 }
                 catch { /* skills module optional */ }
             }
-            // Inject identity (SOUL.md, USER.md, AGENTS.md) — skip if already present to avoid duplication
+            // Inject identity (SOUL.md, USER.md, …) — skip if already present to avoid duplication.
+            // AGENTS.md/INSTRUCTIONS.md are owned by the unified loader, not identity.
             if (gates.includeIdentity) {
                 try {
-                    if (!systemPrompt.includes('## SOUL.md') && !systemPrompt.includes('## AGENTS.md')) {
+                    if (!systemPrompt.includes('## SOUL.md')) {
                         const { getIdentityManager } = await import('../identity/identity-manager.js');
                         const identityMgr = getIdentityManager();
                         await identityMgr.load(this.config.cwd);
@@ -475,6 +531,16 @@ Lessons complement \`remember\`: \`remember\` stores facts (preferences, decisio
 </lessons_directive>`;
                 logger.debug('Injected lessons directive into system prompt');
             }
+            // Self-knowledge — only when self-improvement is explicitly opted in. Makes
+            // the agent aware it can author its own tools/skills (and the hard `src/` limit).
+            if (process.env.CODEBUDDY_SELF_IMPROVE === 'true') {
+                try {
+                    const { buildSelfKnowledgeBlock } = await import('../agent/self-improvement/self-knowledge.js');
+                    systemPrompt += `\n\n<self_knowledge>\n${buildSelfKnowledgeBlock()}\n</self_knowledge>`;
+                    logger.debug('Injected self-knowledge block into system prompt');
+                }
+                catch { /* self-improvement module optional */ }
+            }
             if (this.config.memoryEnabled && gates.includeUserModelDirective) {
                 systemPrompt += `\n\n<user_model_directive>
 You have a persistent user model that builds a deepening profile of who you are, your traits, preferences, expertise, and working style.

package/dist/skills/parser.js

@@ -92,6 +92,9 @@ function parseMetadata(yamlContent, sourcePath) {
             // CC11: context fork and disable-model-invocation
             contextFork: parsed.context === 'fork' || parsed.contextFork === true,
             disableModelInvocation: parsed['disable-model-invocation'] === true || parsed.disableModelInvocation === true,
+            pinned: parsed.pinned === true,
+            imported: parsed.imported === true,
+            source: parsed.source,
         };
     }
     catch (error) {

package/dist/skills/skill-importer.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Skill importer — bring EXTERNAL skills (a Hermes repo, any skills directory)
+ * into Code Buddy, safely. External skills are untrusted and get injected into the
+ * agent's context, so the firewall gates every one (SKILL.md + its scripts) before
+ * install. Hermes nests 1–3 levels but our registry walks 1 level → flatten; Hermes
+ * tags live under `metadata.hermes.tags` but our discovery scores top-level `tags` +
+ * `nativeEngine.triggers` → remap, else an imported skill is invisible to matching.
+ *
+ * Imported skills are namespaced `imported-*` (distinct provenance; never touched by
+ * the self-improvement engine) and installed flat (1 level) under a tier root.
+ *
+ * @module skills/skill-importer
+ */
+export declare const IMPORTED_PREFIX = "imported-";
+export interface ImportOptions {
+    /** Tier dir to install under. Default ~/.codebuddy/skills/managed. */
+    destRoot?: string;
+    /** Provenance label written to frontmatter (e.g. "hermes"). */
+    source?: string;
+    /** When true, scan + report but write nothing. */
+    dryRun?: boolean;
+    /** Import skills the firewall flags as 'review' (default: skip them). */
+    includeReview?: boolean;
+    /** Overwrite an existing imported-<name> (default: skip). */
+    overwrite?: boolean;
+    /** Only import skills whose source path contains this substring. */
+    category?: string;
+    /** Pin imported skills so curation leaves them alone (default true). */
+    pinByDefault?: boolean;
+}
+export interface ImportedSkill {
+    name: string;
+    sourcePath: string;
+    verdict: string;
+}
+export interface SkippedSkill {
+    sourcePath: string;
+    reason: string;
+    verdict?: string;
+}
+export interface ImportReport {
+    imported: ImportedSkill[];
+    quarantined: SkippedSkill[];
+    review: SkippedSkill[];
+    skipped: SkippedSkill[];
+    total: number;
+    dryRun: boolean;
+}
+/** Recursively find skill directories (those containing a SKILL.md). Skips operational dirs. */
+export declare function findSkillDirs(root: string): string[];
+/** Build a Code-Buddy-shaped SKILL.md from a raw (e.g. Hermes) frontmatter object + body. */
+export declare function remapSkill(rawFm: Record<string, unknown>, body: string, opts: {
+    slug: string;
+    source: string;
+    pinned: boolean;
+}): string;
+/** Import skills from a directory. Pure-ish: writes nothing when dryRun. */
+export declare function importSkills(sourceDir: string, options?: ImportOptions): ImportReport;

package/dist/skills/skill-importer.js

@@ -0,0 +1,261 @@
+/**
+ * Skill importer — bring EXTERNAL skills (a Hermes repo, any skills directory)
+ * into Code Buddy, safely. External skills are untrusted and get injected into the
+ * agent's context, so the firewall gates every one (SKILL.md + its scripts) before
+ * install. Hermes nests 1–3 levels but our registry walks 1 level → flatten; Hermes
+ * tags live under `metadata.hermes.tags` but our discovery scores top-level `tags` +
+ * `nativeEngine.triggers` → remap, else an imported skill is invisible to matching.
+ *
+ * Imported skills are namespaced `imported-*` (distinct provenance; never touched by
+ * the self-improvement engine) and installed flat (1 level) under a tier root.
+ *
+ * @module skills/skill-importer
+ */
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import * as yaml from 'yaml';
+import { scanSkillFirewall } from '../security/skill-scanner.js';
+import { parseSkillFile, validateSkill } from './parser.js';
+import { logger } from '../utils/logger.js';
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/;
+const SUPPORT_DIRS = ['references', 'templates', 'scripts', 'assets', 'workflows', 'tests'];
+const SKIP_DIRS = new Set(['.git', 'index-cache', '.archive', 'node_modules', '.sources-cache']);
+export const IMPORTED_PREFIX = 'imported-';
+function defaultDestRoot() {
+    return path.join(os.homedir(), '.codebuddy', 'skills', 'managed');
+}
+/** Recursively find skill directories (those containing a SKILL.md). Skips operational dirs. */
+export function findSkillDirs(root) {
+    const out = [];
+    const walk = (dir) => {
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        if (entries.some((e) => e.isFile() && e.name.toLowerCase() === 'skill.md')) {
+            out.push(dir);
+            // don't descend into a skill's own support dirs
+            return;
+        }
+        for (const e of entries) {
+            if (!e.isDirectory() || e.name.startsWith('.') || SKIP_DIRS.has(e.name))
+                continue;
+            walk(path.join(dir, e.name));
+        }
+    };
+    walk(root);
+    return out;
+}
+function slugify(raw) {
+    const base = String(raw).trim().toLowerCase().replace(/[^a-z0-9-]+/g, '-').replace(/^-+|-+$/g, '');
+    return base.startsWith(IMPORTED_PREFIX) ? base : `${IMPORTED_PREFIX}${base || 'skill'}`;
+}
+function normalizeTags(raw) {
+    const list = Array.isArray(raw) ? raw : [];
+    const seen = new Set();
+    const out = [];
+    for (const t of list) {
+        const s = String(t).trim().toLowerCase();
+        if (s && !seen.has(s)) {
+            seen.add(s);
+            out.push(s);
+        }
+    }
+    return out;
+}
+const STOPWORDS = new Set([
+    'the', 'and', 'for', 'with', 'your', 'via', 'into', 'from', 'that', 'this', 'use', 'using', 'create',
+    'creates', 'creating', 'a', 'an', 'or', 'to', 'of', 'in', 'on', 'as', 'by', 'it', 'is', 'are', 'add',
+    'list', 'get', 'set', 'run', 'when', 'how', 'you', 'can', 'will', 'their', 'them', 'they', 'about',
+]);
+/** Derive discovery triggers (the primary matcher) from the name + tags + description keywords. */
+function deriveTriggers(rawName, tags, description = '') {
+    const nameWords = String(rawName).toLowerCase().split(/[^a-z0-9]+/).filter((w) => w.length >= 3);
+    const descWords = String(description)
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter((w) => w.length >= 4 && !STOPWORDS.has(w));
+    const seen = new Set();
+    const out = [];
+    for (const t of [String(rawName).toLowerCase(), ...tags, ...nameWords, ...descWords]) {
+        if (t && !seen.has(t)) {
+            seen.add(t);
+            out.push(t);
+        }
+        if (out.length >= 12)
+            break;
+    }
+    return out;
+}
+/** Extract discovery tags from any source layout: top-level `tags`, or `metadata.<source>.tags`. */
+function extractTags(rawFm) {
+    if (Array.isArray(rawFm.tags))
+        return rawFm.tags;
+    const meta = rawFm.metadata;
+    if (meta && typeof meta === 'object') {
+        for (const v of Object.values(meta)) {
+            if (v && typeof v === 'object' && Array.isArray(v.tags)) {
+                return v.tags;
+            }
+        }
+    }
+    return [];
+}
+/** Map prerequisites/requires from any source → our SkillRequirements.tools. */
+function extractRequiresTools(rawFm) {
+    const out = new Set();
+    const add = (v) => {
+        if (Array.isArray(v))
+            for (const x of v)
+                if (typeof x === 'string')
+                    out.add(x);
+    };
+    // Hermes: prerequisites.commands
+    const prereq = rawFm.prerequisites;
+    if (prereq)
+        add(prereq.commands);
+    // OpenClaw (and others): metadata.<source>.requires.bins
+    const meta = rawFm.metadata;
+    if (meta && typeof meta === 'object') {
+        for (const v of Object.values(meta)) {
+            const req = v?.requires;
+            if (req)
+                add(req.bins);
+        }
+    }
+    return [...out];
+}
+/** Build a Code-Buddy-shaped SKILL.md from a raw (e.g. Hermes) frontmatter object + body. */
+export function remapSkill(rawFm, body, opts) {
+    const description = String(rawFm.description ?? '').trim() || `Imported skill ${opts.slug}`;
+    const tags = normalizeTags(extractTags(rawFm));
+    const requiresTools = extractRequiresTools(rawFm);
+    const author = Array.isArray(rawFm.author) ? rawFm.author.join(', ') : rawFm.author;
+    const meta = {
+        name: opts.slug,
+        description,
+        ...(rawFm.version ? { version: rawFm.version } : {}),
+        ...(author ? { author } : {}),
+        ...(rawFm.license ? { license: rawFm.license } : {}),
+        ...(rawFm.platforms ? { platforms: rawFm.platforms } : {}),
+        tags,
+        nativeEngine: { triggers: deriveTriggers(String(rawFm.name ?? opts.slug), tags, description) },
+        ...(requiresTools.length ? { requires: { tools: requiresTools } } : {}),
+        imported: true,
+        source: opts.source,
+        ...(opts.pinned ? { pinned: true } : {}),
+    };
+    return `---\n${yaml.stringify(meta)}---\n\n${body.trim()}\n`;
+}
+function copySupportDirs(srcDir, destDir) {
+    for (const sub of SUPPORT_DIRS) {
+        const from = path.join(srcDir, sub);
+        if (fs.existsSync(from) && fs.statSync(from).isDirectory()) {
+            fs.cpSync(from, path.join(destDir, sub), {
+                recursive: true,
+                // never follow symlinks out of the source tree
+                filter: (s) => {
+                    try {
+                        return !fs.lstatSync(s).isSymbolicLink();
+                    }
+                    catch {
+                        return false;
+                    }
+                },
+            });
+        }
+    }
+}
+/** Import skills from a directory. Pure-ish: writes nothing when dryRun. */
+export function importSkills(sourceDir, options = {}) {
+    const destRoot = options.destRoot ?? defaultDestRoot();
+    const source = options.source ?? 'import';
+    const dryRun = options.dryRun ?? false;
+    const pinByDefault = options.pinByDefault ?? true;
+    const report = { imported: [], quarantined: [], review: [], skipped: [], total: 0, dryRun };
+    const skillDirs = findSkillDirs(sourceDir);
+    report.total = skillDirs.length;
+    for (const skillDir of skillDirs) {
+        const rel = path.relative(sourceDir, skillDir);
+        if (options.category && !rel.includes(options.category)) {
+            report.skipped.push({ sourcePath: rel, reason: 'filtered by --category' });
+            continue;
+        }
+        const skillMd = fs.existsSync(path.join(skillDir, 'SKILL.md'))
+            ? path.join(skillDir, 'SKILL.md')
+            : path.join(skillDir, 'skill.md');
+        const content = fs.readFileSync(skillMd, 'utf-8');
+        // Compatibility check.
+        try {
+            const skill = parseSkillFile(content, skillMd, 'managed');
+            const v = validateSkill(skill);
+            if (!v.valid) {
+                report.skipped.push({ sourcePath: rel, reason: `invalid: ${v.errors.join('; ')}` });
+                continue;
+            }
+        }
+        catch (err) {
+            report.skipped.push({ sourcePath: rel, reason: `parse error: ${err instanceof Error ? err.message : String(err)}` });
+            continue;
+        }
+        // Firewall gate (scans SKILL.md + scripts/support files recursively).
+        const fw = scanSkillFirewall(skillDir);
+        if (fw.quarantineRequired) {
+            report.quarantined.push({ sourcePath: rel, reason: fw.summary, verdict: String(fw.verdict) });
+            continue;
+        }
+        if (String(fw.verdict) === 'review' && !options.includeReview) {
+            report.review.push({ sourcePath: rel, reason: fw.summary, verdict: 'review' });
+            continue;
+        }
+        // Remap + flatten + install.
+        const m = content.match(FRONTMATTER_RE);
+        if (!m) {
+            report.skipped.push({ sourcePath: rel, reason: 'missing frontmatter' });
+            continue;
+        }
+        let rawFm;
+        try {
+            rawFm = (yaml.parse(m[1]) ?? {});
+        }
+        catch {
+            report.skipped.push({ sourcePath: rel, reason: 'unparseable frontmatter' });
+            continue;
+        }
+        const slug = slugify(String(rawFm.name ?? path.basename(skillDir)));
+        const destDir = path.join(destRoot, slug);
+        if (fs.existsSync(destDir) && !options.overwrite) {
+            report.skipped.push({ sourcePath: rel, reason: `conflict: ${slug} already imported` });
+            continue;
+        }
+        if (!dryRun) {
+            try {
+                fs.mkdirSync(destDir, { recursive: true });
+                fs.writeFileSync(path.join(destDir, 'SKILL.md'), remapSkill(rawFm, m[2], { slug, source, pinned: pinByDefault }), 'utf-8');
+                copySupportDirs(skillDir, destDir);
+            }
+            catch (err) {
+                report.skipped.push({ sourcePath: rel, reason: `write error: ${err instanceof Error ? err.message : String(err)}` });
+                continue;
+            }
+        }
+        report.imported.push({ name: slug, sourcePath: rel, verdict: String(fw.verdict) });
+    }
+    if (!dryRun && report.imported.length > 0) {
+        void (async () => {
+            try {
+                const { getSkillRegistry } = await import('./registry.js');
+                await getSkillRegistry().reloadAll();
+            }
+            catch (err) {
+                logger.debug(`skill reload after import failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        })();
+    }
+    return report;
+}
+//# sourceMappingURL=skill-importer.js.map

package/dist/skills/skill-sources.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Skill sources — a small "referential" of named places skills can be imported
+ * from. A source is a local directory or a git repo. Persisted to
+ * `~/.codebuddy/skill-sources.json`. The importer resolves a source to a local
+ * directory (cloning/pulling a git source into a cache) and then runs the same
+ * firewall-gated import path.
+ *
+ * @module skills/skill-sources
+ */
+export interface SkillSource {
+    name: string;
+    type: 'dir' | 'git';
+    location: string;
+}
+export declare function listSources(): SkillSource[];
+export declare function getSource(name: string): SkillSource | undefined;
+export declare function addSource(name: string, location: string, type?: 'dir' | 'git'): SkillSource;
+export declare function removeSource(name: string): boolean;
+/** Resolve a source to a local directory (clone/pull a git source into the cache). */
+export declare function resolveSourceDir(source: SkillSource): string;