@phuetz/code-buddy 0.3.0 → 1.0.0-rc.8

package/dist/skills/hub.js

@@ -1,20 +1,24 @@
 /**
  * Skills Hub
  *
- * OpenClaw ClawHub-inspired Skills Hub for searching, installing,
+ * Native Engine ClawHub-inspired Skills Hub for searching, installing,
  * publishing, and syncing skills from a remote registry.
  *
  * Provides lockfile-based integrity management, SHA-256 checksums,
  * semver version comparison, and event-driven lifecycle hooks.
  */
 import { EventEmitter } from 'events';
-import { createHash } from 'crypto';
+import { createHash, randomUUID } from 'crypto';
 import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
 import * as yaml from 'yaml';
 import { logger } from '../utils/logger.js';
+import { generateDiff } from '../utils/diff-generator.js';
 import { parseSkillFile, validateSkill } from './parser.js';
+import { generateSkillSigningKeyPair, signSkillContent, resolveSignatureVerification, validateEd25519PublicKey, meetsTrust, isSkillKeyTrust, } from './hub-signing.js';
+// Re-export the signing surface so consumers can import everything from the hub.
+export { generateSkillSigningKeyPair, signSkillContent, resolveSignatureVerification, verifySkillSignatureMath, computeKeyId, meetsTrust, } from './hub-signing.js';
 // ============================================================================
 // Constants
 // ============================================================================
@@ -23,10 +27,25 @@ const DEFAULT_HUB_CONFIG = {
     cacheDir: path.join(os.homedir(), '.codebuddy', 'hub', 'cache'),
     skillsDir: path.join(os.homedir(), '.codebuddy', 'skills', 'managed'),
     lockfilePath: path.join(os.homedir(), '.codebuddy', 'hub', 'lock.json'),
+    tapsPath: path.join(os.homedir(), '.codebuddy', 'hub', 'taps.json'),
+    trustedKeysPath: path.join(os.homedir(), '.codebuddy', 'hub', 'trusted-keys.json'),
+    requireSignedInstalls: false,
+    githubApiBaseUrl: 'https://api.github.com',
+    githubRawBaseUrl: 'https://raw.githubusercontent.com',
     autoUpdate: false,
     checkIntervalMs: 24 * 60 * 60 * 1000, // 24 hours
 };
 const LOCKFILE_VERSION = 1;
+const TAPS_FILE_VERSION = 1;
+const TRUSTED_KEYS_FILE_VERSION = 1;
+const SUPPORTING_FILE_DIRS = new Set(['references', 'templates', 'scripts', 'assets']);
+const MAX_SUPPORTING_FILE_BYTES = 1_048_576;
+const DEFAULT_TAP_PATH = 'skills/';
+const TRUSTED_TAP_REPOS = new Set([
+    'anthropics/skills',
+    'huggingface/skills',
+    'openai/skills',
+]);
 // ============================================================================
 // Utility Functions
 // ============================================================================
@@ -45,7 +64,9 @@ export function parseSemver(version) {
     if (!match) {
         return [0, 0, 0];
     }
-    return [parseInt(match[1], 10), parseInt(match[2], 10), parseInt(match[3], 10)];
+    // safe: regex matched with three mandatory `(\d+)` capture groups, so match[1..3] are present
+    const [, major, minor, patch] = match;
+    return [parseInt(major ?? '0', 10), parseInt(minor ?? '0', 10), parseInt(patch ?? '0', 10)];
 }
 /**
  * Compare two semver strings.
@@ -93,6 +114,14 @@ export class SkillsHub extends EventEmitter {
         if (!fs.existsSync(lockDir)) {
             fs.mkdirSync(lockDir, { recursive: true });
         }
+        const tapsDir = path.dirname(this.config.tapsPath);
+        if (!fs.existsSync(tapsDir)) {
+            fs.mkdirSync(tapsDir, { recursive: true });
+        }
+        const trustedKeysDir = path.dirname(this.config.trustedKeysPath);
+        if (!fs.existsSync(trustedKeysDir)) {
+            fs.mkdirSync(trustedKeysDir, { recursive: true });
+        }
     }
     /**
      * Read the lockfile from disk. Returns an empty lockfile if not found.
@@ -132,7 +161,708 @@ export class SkillsHub extends EventEmitter {
      * Get the lockfile contents (for testing / external inspection).
      */
     getLockfile() {
-        return { ...this.lockfile, skills: { ...this.lockfile.skills } };
+        return {
+            ...this.lockfile,
+            skills: Object.fromEntries(Object.entries(this.lockfile.skills).map(([name, skill]) => [
+                name,
+                {
+                    ...skill,
+                    usage: skill.usage ? { ...skill.usage } : undefined,
+                    lifecycle: skill.lifecycle ? { ...skill.lifecycle } : undefined,
+                    history: skill.history?.map((snapshot) => ({ ...snapshot })),
+                },
+            ])),
+        };
+    }
+    // ==========================================================================
+    // Taps & Trust
+    // ==========================================================================
+    /**
+     * List configured skill taps. Taps are repository-backed skill catalogs
+     * compatible with Hermes' owner/repo + path model.
+     */
+    listTaps() {
+        return this.readTapsFile().taps.map((tap) => ({ ...tap }));
+    }
+    addTap(repo, options = {}) {
+        const normalizedRepo = this.normalizeTapRepo(repo);
+        const tapsFile = this.readTapsFile();
+        const existing = tapsFile.taps.find((tap) => tap.repo === normalizedRepo);
+        const now = options.updatedAt ?? Date.now();
+        const trust = options.trust ?? this.defaultTapTrust(normalizedRepo);
+        const tapPath = this.normalizeTapPath(options.path ?? existing?.path ?? DEFAULT_TAP_PATH);
+        if (existing) {
+            existing.path = tapPath;
+            existing.trust = trust;
+            existing.updatedAt = now;
+            if (options.actor)
+                existing.addedBy = options.actor;
+            this.writeTapsFile(tapsFile);
+            this.emit('tap:updated', { ...existing });
+            return { ...existing };
+        }
+        const tap = {
+            repo: normalizedRepo,
+            path: tapPath,
+            trust,
+            addedAt: now,
+            updatedAt: now,
+            ...(options.actor ? { addedBy: options.actor } : {}),
+        };
+        tapsFile.taps.push(tap);
+        tapsFile.taps.sort((left, right) => left.repo.localeCompare(right.repo));
+        this.writeTapsFile(tapsFile);
+        this.emit('tap:added', { ...tap });
+        return { ...tap };
+    }
+    removeTap(repo) {
+        const normalizedRepo = this.normalizeTapRepo(repo);
+        const tapsFile = this.readTapsFile();
+        const next = tapsFile.taps.filter((tap) => tap.repo !== normalizedRepo);
+        if (next.length === tapsFile.taps.length) {
+            return false;
+        }
+        tapsFile.taps = next;
+        this.writeTapsFile(tapsFile);
+        this.emit('tap:removed', normalizedRepo);
+        return true;
+    }
+    setTapTrust(repo, trust, options = {}) {
+        const normalizedRepo = this.normalizeTapRepo(repo);
+        const tapsFile = this.readTapsFile();
+        const tap = tapsFile.taps.find((item) => item.repo === normalizedRepo);
+        if (!tap) {
+            return null;
+        }
+        tap.trust = this.normalizeTapTrust(trust);
+        tap.updatedAt = options.updatedAt ?? Date.now();
+        if (options.actor)
+            tap.addedBy = options.actor;
+        this.writeTapsFile(tapsFile);
+        this.emit('tap:trust_updated', { ...tap });
+        return { ...tap };
+    }
+    getTapTrust(repo) {
+        const normalizedRepo = this.normalizeTapRepo(repo);
+        const tap = this.readTapsFile().taps.find((item) => item.repo === normalizedRepo);
+        return tap?.trust ?? this.defaultTapTrust(normalizedRepo);
+    }
+    /**
+     * Discover SKILL.md packages from configured GitHub taps. This is read-only:
+     * it indexes remote metadata into the local cache but does not install or
+     * trust any skill content automatically.
+     */
+    async refreshTapIndex(repo) {
+        const selectedTaps = repo
+            ? this.listTaps().filter((tap) => tap.repo === this.normalizeTapRepo(repo))
+            : this.listTaps();
+        if (repo && selectedTaps.length === 0) {
+            throw new Error(`Skill tap not found: ${repo}`);
+        }
+        const skills = [];
+        const errors = [];
+        for (const tap of selectedTaps) {
+            try {
+                skills.push(...await this.discoverGitHubTapSkills(tap));
+            }
+            catch (err) {
+                errors.push({
+                    repo: tap.repo,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+        }
+        const refreshedAt = new Date().toISOString();
+        this.replaceTapCacheForTaps(skills, selectedTaps.map((tap) => tap.repo), refreshedAt);
+        return {
+            errors,
+            refreshedAt,
+            skillCount: skills.length,
+            skills,
+            taps: selectedTaps,
+        };
+    }
+    /**
+     * Discover skills from a site exposing `/.well-known/skills/index.json`.
+     * The index parser is intentionally tolerant because the convention is
+     * designed for independent publishers.
+     */
+    async discoverWellKnownSkills(inputUrl) {
+        const indexUrl = this.resolveWellKnownIndexUrl(inputUrl);
+        const response = await fetch(indexUrl, {
+            method: 'GET',
+            headers: {
+                'Accept': 'application/json',
+                'User-Agent': 'codebuddy-hub/1.0',
+            },
+            signal: AbortSignal.timeout(10000),
+        });
+        if (!response.ok) {
+            throw new Error(`Well-known skills index returned ${response.status}: ${response.statusText}`);
+        }
+        const body = await response.json();
+        const entries = this.extractWellKnownEntries(body);
+        const errors = [];
+        const skills = [];
+        for (const entry of entries) {
+            try {
+                const skill = this.discoveredSkillFromWellKnownEntry(entry, indexUrl);
+                if (skill.contentUrl) {
+                    try {
+                        const content = await this.fetchUrlText(skill.contentUrl, 'text/markdown');
+                        this.validateSkillContent(content, skill.name);
+                        skills.push({
+                            ...skill,
+                            checksum: computeChecksum(content),
+                            size: Buffer.byteLength(content, 'utf-8'),
+                        });
+                        this.writeCachedSkillContent(skill.name, skill.version, content);
+                        continue;
+                    }
+                    catch (err) {
+                        errors.push(`${skill.identifier}: ${err instanceof Error ? err.message : String(err)}`);
+                    }
+                }
+                skills.push(skill);
+            }
+            catch (err) {
+                errors.push(err instanceof Error ? err.message : String(err));
+            }
+        }
+        const refreshedAt = new Date().toISOString();
+        this.mergeTapCache(skills, refreshedAt);
+        return {
+            errors,
+            indexUrl,
+            refreshedAt,
+            skillCount: skills.length,
+            skills,
+        };
+    }
+    readTapsFile() {
+        try {
+            if (fs.existsSync(this.config.tapsPath)) {
+                const raw = fs.readFileSync(this.config.tapsPath, 'utf-8');
+                const parsed = JSON.parse(raw);
+                if (parsed.version === TAPS_FILE_VERSION
+                    && Array.isArray(parsed.taps)) {
+                    const taps = parsed.taps
+                        .map((tap) => this.normalizeTapRecord(tap))
+                        .filter((tap) => Boolean(tap));
+                    return {
+                        version: TAPS_FILE_VERSION,
+                        updatedAt: typeof parsed.updatedAt === 'string' ? parsed.updatedAt : new Date().toISOString(),
+                        taps,
+                    };
+                }
+            }
+        }
+        catch (err) {
+            logger.warn('Failed to read hub taps file, starting fresh', {
+                path: this.config.tapsPath,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+        return {
+            version: TAPS_FILE_VERSION,
+            updatedAt: new Date().toISOString(),
+            taps: [],
+        };
+    }
+    writeTapsFile(tapsFile) {
+        tapsFile.updatedAt = new Date().toISOString();
+        tapsFile.taps.sort((left, right) => left.repo.localeCompare(right.repo));
+        fs.writeFileSync(this.config.tapsPath, JSON.stringify(tapsFile, null, 2), 'utf-8');
+        logger.debug('Hub taps file written', { path: this.config.tapsPath });
+    }
+    normalizeTapRecord(tap) {
+        if (!tap || typeof tap !== 'object') {
+            return null;
+        }
+        const candidate = tap;
+        if (typeof candidate.repo !== 'string') {
+            return null;
+        }
+        const addedAt = typeof candidate.addedAt === 'number' ? candidate.addedAt : Date.now();
+        const updatedAt = typeof candidate.updatedAt === 'number' ? candidate.updatedAt : addedAt;
+        return {
+            repo: this.normalizeTapRepo(candidate.repo),
+            path: this.normalizeTapPath(candidate.path ?? DEFAULT_TAP_PATH),
+            trust: this.normalizeTapTrust(candidate.trust ?? this.defaultTapTrust(candidate.repo)),
+            addedAt,
+            updatedAt,
+            ...(typeof candidate.addedBy === 'string' && candidate.addedBy.trim()
+                ? { addedBy: candidate.addedBy.trim() }
+                : {}),
+        };
+    }
+    normalizeTapRepo(repo) {
+        const trimmed = repo.trim().replace(/^https:\/\/github\.com\//i, '').replace(/\.git$/i, '');
+        const normalized = trimmed.replace(/^\/+|\/+$/g, '');
+        if (!/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(normalized)) {
+            throw new Error(`Invalid skill tap repo '${repo}'. Use owner/repo.`);
+        }
+        return normalized;
+    }
+    normalizeTapPath(tapPath) {
+        const normalized = tapPath.trim().replace(/\\/g, '/').replace(/^\/+|\/+$/g, '');
+        if (!normalized
+            || normalized.includes('..')
+            || normalized.split('/').some((part) => part.trim() === '')) {
+            throw new Error(`Invalid skill tap path '${tapPath}'. Use a relative directory such as skills/.`);
+        }
+        return `${normalized}/`;
+    }
+    normalizeTapTrust(trust) {
+        if (['builtin', 'official', 'trusted', 'community'].includes(trust)) {
+            return trust;
+        }
+        throw new Error(`Invalid skill tap trust '${trust}'. Use builtin, official, trusted, or community.`);
+    }
+    defaultTapTrust(repo) {
+        return TRUSTED_TAP_REPOS.has(repo.toLowerCase()) ? 'trusted' : 'community';
+    }
+    async discoverGitHubTapSkills(tap) {
+        const directories = await this.fetchGitHubDirectory(tap.repo, tap.path);
+        const skills = [];
+        for (const entry of directories) {
+            if (entry.type !== 'dir' || entry.name.startsWith('.') || entry.name.startsWith('_')) {
+                continue;
+            }
+            const skillPath = `${tap.path}${entry.name}`;
+            const skillMdPath = `${skillPath}/SKILL.md`;
+            try {
+                const content = await this.fetchGitHubFile(tap.repo, skillMdPath);
+                const skill = parseSkillFile(content, skillMdPath, 'managed');
+                const description = skill.metadata.description || `${skill.metadata.name} from ${tap.repo}`;
+                const version = skill.metadata.version || '0.0.0';
+                const tags = skill.metadata.tags || [];
+                this.writeCachedSkillContent(skill.metadata.name, version, content);
+                skills.push({
+                    name: skill.metadata.name,
+                    version,
+                    description,
+                    author: skill.metadata.author || tap.repo,
+                    tags,
+                    downloads: 0,
+                    stars: 0,
+                    updatedAt: new Date().toISOString(),
+                    checksum: computeChecksum(content),
+                    size: Buffer.byteLength(content, 'utf-8'),
+                    repository: `https://github.com/${tap.repo}`,
+                    source: 'github-tap',
+                    identifier: `${tap.repo}/${entry.name}`,
+                    trust: tap.trust,
+                    contentUrl: this.rawGitHubUrl(tap.repo, skillMdPath),
+                    tapRepo: tap.repo,
+                    skillPath,
+                });
+            }
+            catch (err) {
+                logger.debug('Skipping invalid GitHub tap skill', {
+                    repo: tap.repo,
+                    path: skillMdPath,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+        }
+        return skills;
+    }
+    async fetchGitHubDirectory(repo, tapPath) {
+        const url = `${this.config.githubApiBaseUrl.replace(/\/+$/, '')}/repos/${repo}/contents/${this.encodeGitHubContentPath(tapPath.replace(/\/+$/, ''))}`;
+        const response = await fetch(url, {
+            method: 'GET',
+            headers: this.githubHeaders('application/vnd.github+json'),
+            signal: AbortSignal.timeout(10000),
+        });
+        if (!response.ok) {
+            throw new Error(`GitHub contents returned ${response.status}: ${response.statusText}`);
+        }
+        const json = await response.json();
+        if (!Array.isArray(json)) {
+            throw new Error(`GitHub contents for ${repo}/${tapPath} did not return a directory listing`);
+        }
+        return json.filter((item) => (Boolean(item)
+            && typeof item === 'object'
+            && typeof item.name === 'string'
+            && typeof item.type === 'string'));
+    }
+    async fetchGitHubFile(repo, filePath) {
+        const url = `${this.config.githubApiBaseUrl.replace(/\/+$/, '')}/repos/${repo}/contents/${this.encodeGitHubContentPath(filePath)}`;
+        const response = await fetch(url, {
+            method: 'GET',
+            headers: this.githubHeaders('application/vnd.github.raw'),
+            signal: AbortSignal.timeout(10000),
+        });
+        if (!response.ok) {
+            throw new Error(`GitHub file returned ${response.status}: ${response.statusText}`);
+        }
+        return await response.text();
+    }
+    async fetchUrlText(url, accept) {
+        const response = await fetch(url, {
+            method: 'GET',
+            headers: {
+                'Accept': accept,
+                'User-Agent': 'codebuddy-hub/1.0',
+            },
+            signal: AbortSignal.timeout(10000),
+        });
+        if (!response.ok) {
+            throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+        }
+        return await response.text();
+    }
+    writeCachedSkillContent(skillName, version, content) {
+        if (!/^[a-zA-Z0-9_-]+$/.test(skillName)) {
+            return;
+        }
+        const targets = [
+            path.join(this.config.cacheDir, `${skillName}.skill.md`),
+            version ? path.join(this.config.cacheDir, `${skillName}@${version}.skill.md`) : null,
+        ].filter((target) => Boolean(target));
+        for (const target of targets) {
+            fs.writeFileSync(target, content, 'utf-8');
+        }
+    }
+    encodeGitHubContentPath(filePath) {
+        return filePath.split('/').map((part) => encodeURIComponent(part)).join('/');
+    }
+    githubHeaders(accept) {
+        const headers = {
+            'Accept': accept,
+            'User-Agent': 'codebuddy-hub/1.0',
+        };
+        const token = process.env['GITHUB_TOKEN'];
+        if (token) {
+            headers['Authorization'] = `Bearer ${token}`;
+        }
+        return headers;
+    }
+    rawGitHubUrl(repo, filePath) {
+        return `${this.config.githubRawBaseUrl.replace(/\/+$/, '')}/${repo}/HEAD/${filePath}`;
+    }
+    getTapCacheFile() {
+        return path.join(this.config.cacheDir, 'tap-cache.json');
+    }
+    getTapCacheSkills() {
+        try {
+            const cacheFile = this.getTapCacheFile();
+            if (!fs.existsSync(cacheFile)) {
+                return [];
+            }
+            const raw = fs.readFileSync(cacheFile, 'utf-8');
+            const parsed = JSON.parse(raw);
+            return Array.isArray(parsed.skills) ? parsed.skills : [];
+        }
+        catch {
+            return [];
+        }
+    }
+    writeTapCache(skills, cachedAt) {
+        const cacheFile = this.getTapCacheFile();
+        fs.mkdirSync(path.dirname(cacheFile), { recursive: true });
+        fs.writeFileSync(cacheFile, JSON.stringify({ cachedAt, skills }, null, 2), 'utf-8');
+    }
+    mergeTapCache(skills, cachedAt) {
+        const merged = new Map();
+        for (const skill of this.getTapCacheSkills()) {
+            merged.set(skill.identifier, skill);
+        }
+        for (const skill of skills) {
+            merged.set(skill.identifier, skill);
+        }
+        this.writeTapCache([...merged.values()], cachedAt);
+    }
+    replaceTapCacheForTaps(skills, tapRepos, cachedAt) {
+        const selectedRepos = new Set(tapRepos);
+        const retained = this.getTapCacheSkills().filter((skill) => (skill.source !== 'github-tap'
+            || !skill.tapRepo
+            || !selectedRepos.has(skill.tapRepo)));
+        this.writeTapCache([...retained, ...skills], cachedAt);
+    }
+    resolveWellKnownIndexUrl(inputUrl) {
+        const normalized = inputUrl.trim().replace(/^well-known:/, '');
+        const url = new URL(normalized);
+        if (url.pathname.endsWith('/.well-known/skills/index.json')) {
+            return url.toString();
+        }
+        return new URL('/.well-known/skills/index.json', url.origin).toString();
+    }
+    extractWellKnownEntries(body) {
+        if (Array.isArray(body)) {
+            return body;
+        }
+        if (!body || typeof body !== 'object') {
+            return [];
+        }
+        const record = body;
+        for (const key of ['skills', 'items', 'entries']) {
+            if (Array.isArray(record[key])) {
+                return record[key];
+            }
+        }
+        return [];
+    }
+    discoveredSkillFromWellKnownEntry(entry, indexUrl) {
+        if (!entry || typeof entry !== 'object') {
+            throw new Error('Well-known skill entry must be an object');
+        }
+        const record = entry;
+        const name = this.readStringField(record, ['name', 'id', 'slug']);
+        const description = this.readStringField(record, ['description', 'summary']) || `${name} from well-known index`;
+        const version = this.readStringField(record, ['version']) || '0.0.0';
+        const contentUrl = this.resolveWellKnownSkillUrl(record, indexUrl, name);
+        return {
+            name,
+            version,
+            description,
+            author: this.readStringField(record, ['author', 'publisher']) || new URL(indexUrl).hostname,
+            tags: this.readStringArrayField(record, ['tags', 'keywords']),
+            downloads: 0,
+            stars: 0,
+            updatedAt: this.readStringField(record, ['updatedAt', 'updated_at', 'modified']) || new Date().toISOString(),
+            checksum: this.readStringField(record, ['checksum', 'sha256']) || computeChecksum(`${name}:${version}:${contentUrl}`),
+            size: Number(record['size']) || 0,
+            repository: this.readStringField(record, ['repository', 'repo']),
+            source: 'well-known',
+            identifier: `well-known:${contentUrl.replace(/\/SKILL\.md$/i, '')}`,
+            trust: 'community',
+            contentUrl,
+            indexUrl,
+        };
+    }
+    readStringField(record, keys) {
+        for (const key of keys) {
+            const value = record[key];
+            if (typeof value === 'string' && value.trim()) {
+                return value.trim();
+            }
+        }
+        return '';
+    }
+    readStringArrayField(record, keys) {
+        for (const key of keys) {
+            const value = record[key];
+            if (Array.isArray(value)) {
+                return value.filter((item) => typeof item === 'string' && item.trim().length > 0);
+            }
+            if (typeof value === 'string' && value.trim()) {
+                return value.split(',').map((item) => item.trim()).filter(Boolean);
+            }
+        }
+        return [];
+    }
+    resolveWellKnownSkillUrl(record, indexUrl, name) {
+        const explicit = this.readStringField(record, [
+            'skillMdUrl',
+            'skill_md_url',
+            'skillUrl',
+            'skill_url',
+            'url',
+            'href',
+        ]);
+        if (explicit) {
+            return new URL(explicit, indexUrl).toString();
+        }
+        const base = indexUrl.replace(/\/index\.json(?:[?#].*)?$/, '/');
+        return new URL(`${encodeURIComponent(name)}/SKILL.md`, base).toString();
+    }
+    // ==========================================================================
+    // Signing & Trusted Keys
+    // ==========================================================================
+    /**
+     * List trusted publisher keys. Returns copies so callers cannot mutate the
+     * keyring in place. Public keys are safe to display; no private material is
+     * ever stored here.
+     */
+    listTrustedKeys() {
+        return this.readTrustedKeysFile().keys.map((key) => ({ ...key }));
+    }
+    /**
+     * Look up a single trusted key by id.
+     */
+    getTrustedKey(keyId) {
+        const key = this.readTrustedKeysFile().keys.find((item) => item.keyId === keyId);
+        return key ? { ...key } : null;
+    }
+    /**
+     * Add (or update) a trusted publisher key. The public key must be a base64
+     * SPKI DER Ed25519 key; if no keyId is supplied it is derived from the key
+     * fingerprint so a publisher and consumer agree on the same id.
+     */
+    addTrustedKey(publicKey, options = {}) {
+        const normalizedPublicKey = publicKey.trim();
+        if (!normalizedPublicKey) {
+            throw new Error('A base64 SPKI DER Ed25519 public key is required to trust a publisher.');
+        }
+        // Validate the key parses as an Ed25519 public key before we trust it.
+        const keyId = this.validateTrustedPublicKey(normalizedPublicKey, options.keyId);
+        const trust = options.trust ?? 'community';
+        if (!isSkillKeyTrust(trust)) {
+            throw new Error(`Invalid key trust '${trust}'. Use builtin, official, trusted, or community.`);
+        }
+        const keysFile = this.readTrustedKeysFile();
+        const now = options.updatedAt ?? Date.now();
+        const existing = keysFile.keys.find((item) => item.keyId === keyId);
+        if (existing) {
+            existing.publicKey = normalizedPublicKey;
+            existing.trust = trust;
+            existing.updatedAt = now;
+            if (options.addedBy)
+                existing.addedBy = options.addedBy;
+            if (options.label)
+                existing.label = options.label;
+            this.writeTrustedKeysFile(keysFile);
+            this.emit('key:updated', { ...existing });
+            return { ...existing };
+        }
+        const key = {
+            keyId,
+            publicKey: normalizedPublicKey,
+            algorithm: 'ed25519',
+            trust,
+            addedAt: now,
+            updatedAt: now,
+            ...(options.addedBy ? { addedBy: options.addedBy } : {}),
+            ...(options.label ? { label: options.label } : {}),
+        };
+        keysFile.keys.push(key);
+        keysFile.keys.sort((left, right) => left.keyId.localeCompare(right.keyId));
+        this.writeTrustedKeysFile(keysFile);
+        this.emit('key:added', { ...key });
+        return { ...key };
+    }
+    /**
+     * Remove a trusted publisher key by id. Returns false if it was not present.
+     */
+    removeTrustedKey(keyId) {
+        const keysFile = this.readTrustedKeysFile();
+        const next = keysFile.keys.filter((key) => key.keyId !== keyId);
+        if (next.length === keysFile.keys.length) {
+            return false;
+        }
+        keysFile.keys = next;
+        this.writeTrustedKeysFile(keysFile);
+        this.emit('key:removed', keyId);
+        return true;
+    }
+    /**
+     * Change the trust level of an existing trusted key.
+     */
+    setKeyTrust(keyId, trust, options = {}) {
+        if (!isSkillKeyTrust(trust)) {
+            throw new Error(`Invalid key trust '${trust}'. Use builtin, official, trusted, or community.`);
+        }
+        const keysFile = this.readTrustedKeysFile();
+        const key = keysFile.keys.find((item) => item.keyId === keyId);
+        if (!key) {
+            return null;
+        }
+        key.trust = trust;
+        key.updatedAt = options.updatedAt ?? Date.now();
+        if (options.addedBy)
+            key.addedBy = options.addedBy;
+        this.writeTrustedKeysFile(keysFile);
+        this.emit('key:trust_updated', { ...key });
+        return { ...key };
+    }
+    /**
+     * Generate a fresh Ed25519 publisher keypair. The private key is returned to
+     * the caller and never persisted by the hub; only public keys are trusted.
+     */
+    generateSigningKeyPair(keyId) {
+        return generateSkillSigningKeyPair(keyId);
+    }
+    /**
+     * Verify a detached signature for SKILL.md content against the trusted keyring.
+     * Returns `unsigned` when no signature is supplied.
+     */
+    verifySkillContentSignature(content, signature) {
+        return resolveSignatureVerification(content, signature, this.readTrustedKeysFile().keys);
+    }
+    validateTrustedPublicKey(publicKeyB64, requestedKeyId) {
+        // resolveSignatureVerification matches a signature's keyId against the ring,
+        // so the operator-supplied keyId (if any) wins; otherwise derive it from the
+        // key fingerprint. validateEd25519PublicKey rejects non-Ed25519/malformed keys.
+        const derived = validateEd25519PublicKey(publicKeyB64);
+        const requested = requestedKeyId?.trim();
+        return requested && requested.length > 0 ? requested : derived;
+    }
+    enforceSignaturePolicy(skillName, verification) {
+        if (!this.config.requireSignedInstalls) {
+            return;
+        }
+        if (verification.status !== 'verified') {
+            throw new Error(`Refusing to install '${skillName}': signed installs are required but the signature is '${verification.status}'`
+                + (verification.reason ? ` (${verification.reason})` : ''));
+        }
+        const min = this.config.minSignatureTrust;
+        if (min && (!verification.trust || !meetsTrust(verification.trust, min))) {
+            throw new Error(`Refusing to install '${skillName}': signer trust '${verification.trust ?? 'unknown'}' `
+                + `is below the required minimum '${min}'`);
+        }
+    }
+    readTrustedKeysFile() {
+        try {
+            if (fs.existsSync(this.config.trustedKeysPath)) {
+                const raw = fs.readFileSync(this.config.trustedKeysPath, 'utf-8');
+                const parsed = JSON.parse(raw);
+                if (parsed.version === TRUSTED_KEYS_FILE_VERSION && Array.isArray(parsed.keys)) {
+                    const keys = parsed.keys
+                        .map((key) => this.normalizeTrustedKeyRecord(key))
+                        .filter((key) => Boolean(key));
+                    return {
+                        version: TRUSTED_KEYS_FILE_VERSION,
+                        updatedAt: typeof parsed.updatedAt === 'string' ? parsed.updatedAt : new Date().toISOString(),
+                        keys,
+                    };
+                }
+            }
+        }
+        catch (err) {
+            logger.warn('Failed to read hub trusted keys file, starting fresh', {
+                path: this.config.trustedKeysPath,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+        return {
+            version: TRUSTED_KEYS_FILE_VERSION,
+            updatedAt: new Date().toISOString(),
+            keys: [],
+        };
+    }
+    writeTrustedKeysFile(keysFile) {
+        keysFile.updatedAt = new Date().toISOString();
+        keysFile.keys.sort((left, right) => left.keyId.localeCompare(right.keyId));
+        fs.writeFileSync(this.config.trustedKeysPath, JSON.stringify(keysFile, null, 2), 'utf-8');
+        logger.debug('Hub trusted keys file written', { path: this.config.trustedKeysPath });
+    }
+    normalizeTrustedKeyRecord(key) {
+        if (!key || typeof key !== 'object') {
+            return null;
+        }
+        const candidate = key;
+        if (typeof candidate.keyId !== 'string' || typeof candidate.publicKey !== 'string') {
+            return null;
+        }
+        const addedAt = typeof candidate.addedAt === 'number' ? candidate.addedAt : Date.now();
+        const updatedAt = typeof candidate.updatedAt === 'number' ? candidate.updatedAt : addedAt;
+        const trust = isSkillKeyTrust(candidate.trust) ? candidate.trust : 'community';
+        return {
+            keyId: candidate.keyId,
+            publicKey: candidate.publicKey,
+            algorithm: 'ed25519',
+            trust,
+            addedAt,
+            updatedAt,
+            ...(typeof candidate.addedBy === 'string' && candidate.addedBy.trim()
+                ? { addedBy: candidate.addedBy.trim() }
+                : {}),
+            ...(typeof candidate.label === 'string' && candidate.label.trim()
+                ? { label: candidate.label.trim() }
+                : {}),
+        };
     }
     // ==========================================================================
     // Search
@@ -154,6 +884,7 @@ export class SkillsHub extends EventEmitter {
             logger.debug('Remote fetch failed, using local cache');
             allSkills = this.getLocalCacheSkills();
         }
+        allSkills = this.mergeDiscoveredSkills(allSkills, this.getTapCacheSkills());
         // Filter by query
         const queryLower = query.toLowerCase();
         let filtered = allSkills.filter(skill => {
@@ -186,6 +917,16 @@ export class SkillsHub extends EventEmitter {
         const skills = filtered.slice(start, start + pageSize);
         return { skills, total, page, pageSize };
     }
+    mergeDiscoveredSkills(base, discovered) {
+        const merged = new Map();
+        for (const skill of base) {
+            merged.set(`${skill.name}@${skill.version}:${skill.repository ?? ''}`, skill);
+        }
+        for (const skill of discovered) {
+            merged.set(`${skill.name}@${skill.version}:${skill.repository ?? ''}`, skill);
+        }
+        return [...merged.values()];
+    }
     /**
      * Fetch skills from the remote registry.
      * In a real implementation this would call the API.
@@ -253,6 +994,13 @@ export class SkillsHub extends EventEmitter {
             logger.debug('Failed to write local cache');
         }
     }
+    getCachedSkillContentPath(skillName, version) {
+        const candidates = [
+            version ? path.join(this.config.cacheDir, `${skillName}@${version}.skill.md`) : null,
+            path.join(this.config.cacheDir, `${skillName}.skill.md`),
+        ].filter((candidate) => Boolean(candidate));
+        return candidates.find((candidate) => fs.existsSync(candidate)) ?? null;
+    }
     // ==========================================================================
     // Install
     // ==========================================================================
@@ -278,6 +1026,10 @@ export class SkillsHub extends EventEmitter {
         // Parse and validate the SKILL.md content
         const resolvedVersion = this.extractVersionFromContent(content) || version || '0.0.0';
         this.validateSkillContent(content, skillName);
+        // By-name hub downloads carry no detached signature, so this resolves to
+        // `unsigned`; enforcement is a no-op unless requireSignedInstalls is on.
+        const verification = this.verifySkillContentSignature(content);
+        this.enforceSignaturePolicy(skillName, verification);
         // Write to managed skills directory
         const skillDir = path.join(this.config.skillsDir, skillName);
         if (!fs.existsSync(skillDir)) {
@@ -293,6 +1045,7 @@ export class SkillsHub extends EventEmitter {
             source: 'hub',
             checksum,
             path: skillPath,
+            signatureStatus: verification.status,
         };
         this.lockfile.skills[skillName] = installed;
         this.writeLockfile();
@@ -305,6 +1058,11 @@ export class SkillsHub extends EventEmitter {
      * In a real implementation, this would download from the registry.
      */
     async fetchSkillContent(skillName, version) {
+        const cachedContentPath = this.getCachedSkillContentPath(skillName, version);
+        if (cachedContentPath) {
+            logger.debug('Using cached skill content', { name: skillName, version, path: cachedContentPath });
+            return fs.readFileSync(cachedContentPath, 'utf-8');
+        }
         const versionParam = version ? `&version=${encodeURIComponent(version)}` : '';
         const url = `${this.config.registryUrl}/skills/${encodeURIComponent(skillName)}/download?format=skillmd${versionParam}`;
         try {
@@ -323,24 +1081,23 @@ export class SkillsHub extends EventEmitter {
         }
         catch (err) {
             // Check local cache
-            const cached = path.join(this.config.cacheDir, `${skillName}.skill.md`);
-            if (fs.existsSync(cached)) {
-                logger.debug('Using cached skill content', { name: skillName });
-                return fs.readFileSync(cached, 'utf-8');
-            }
             throw new Error(`Failed to fetch skill '${skillName}': ${err instanceof Error ? err.message : String(err)}`);
         }
     }
     /**
      * Install a skill from local content string (for local/offline installs).
      */
-    async installFromContent(skillName, content, source = 'local') {
+    async installFromContent(skillName, content, source = 'local', options = {}) {
         if (!/^[a-zA-Z0-9_-]+$/.test(skillName)) {
             throw new Error(`Invalid skill name: ${skillName}. Only alphanumeric, dash, and underscore allowed.`);
         }
         const checksum = computeChecksum(content);
         const version = this.extractVersionFromContent(content) || '0.0.0';
         this.validateSkillContent(content, skillName);
+        // Verify the optional detached signature against the trusted keyring and
+        // enforce the signed-install policy before writing anything to disk.
+        const verification = this.verifySkillContentSignature(content, options.signature);
+        this.enforceSignaturePolicy(skillName, verification);
         // Write to managed skills directory
         const skillDir = path.join(this.config.skillsDir, skillName);
         if (!fs.existsSync(skillDir)) {
@@ -355,10 +1112,50 @@ export class SkillsHub extends EventEmitter {
             source,
             checksum,
             path: skillPath,
+            signatureStatus: verification.status,
+            ...(options.signature ? { signature: options.signature } : {}),
+        };
+        this.lockfile.skills[skillName] = installed;
+        this.writeLockfile();
+        logger.info('Skill installed from content', {
+            name: skillName,
+            version,
+            source,
+            signatureStatus: verification.status,
+        });
+        this.emit('skill:installed', installed);
+        return installed;
+    }
+    /**
+     * Track an existing local SKILL.md file in the lockfile without copying it.
+     * This keeps review-gated workspace installs visible to skills_list/skill_view
+     * while preserving the workspace path as the source of truth.
+     */
+    registerLocalSkillFile(skillName, skillPath, source = 'local') {
+        if (!/^[a-zA-Z0-9_-]+$/.test(skillName)) {
+            throw new Error(`Invalid skill name: ${skillName}. Only alphanumeric, dash, and underscore allowed.`);
+        }
+        const resolvedPath = path.resolve(skillPath);
+        if (!fs.existsSync(resolvedPath)) {
+            throw new Error(`Skill file not found: ${resolvedPath}`);
+        }
+        const content = fs.readFileSync(resolvedPath, 'utf-8');
+        this.validateSkillContent(content, skillName);
+        const previous = this.lockfile.skills[skillName];
+        const installed = {
+            name: skillName,
+            version: this.extractVersionFromContent(content) || previous?.version || '0.0.0',
+            installedAt: previous?.installedAt ?? Date.now(),
+            source,
+            checksum: computeChecksum(content),
+            path: resolvedPath,
+            ...(previous?.usage ? { usage: previous.usage } : {}),
+            ...(previous?.enabled === false ? { enabled: false } : {}),
+            ...(previous?.lifecycle ? { lifecycle: previous.lifecycle } : {}),
+            ...(previous?.history ? { history: previous.history } : {}),
         };
         this.lockfile.skills[skillName] = installed;
         this.writeLockfile();
-        logger.info('Skill installed from content', { name: skillName, version, source });
         this.emit('skill:installed', installed);
         return installed;
     }
@@ -387,6 +1184,28 @@ export class SkillsHub extends EventEmitter {
         this.emit('skill:removed', skillName);
         return true;
     }
+    /**
+     * Remove a stale lockfile row only when its recorded SKILL.md is already
+     * missing. Unlike uninstall(), this never deletes files from skillsDir.
+     */
+    removeMissingSkillRecord(skillName) {
+        const installed = this.lockfile.skills[skillName];
+        if (!installed) {
+            logger.warn('Cannot prune missing skill record because it is not in the lockfile', { name: skillName });
+            return false;
+        }
+        if (fs.existsSync(installed.path)) {
+            logger.warn('Refusing to prune skill record because SKILL.md still exists', {
+                name: skillName,
+                path: installed.path,
+            });
+            return false;
+        }
+        delete this.lockfile.skills[skillName];
+        this.writeLockfile();
+        this.emit('skill:removed', skillName);
+        return true;
+    }
     // ==========================================================================
     // Update
     // ==========================================================================
@@ -405,6 +1224,8 @@ export class SkillsHub extends EventEmitter {
             return updated;
         }
         for (const skill of toUpdate) {
+            if (!skill)
+                continue;
             try {
                 // Check for newer version
                 const hubInfo = await this.getHubSkillInfo(skill.name);
@@ -442,6 +1263,10 @@ export class SkillsHub extends EventEmitter {
      * Get skill info from the hub API.
      */
     async getHubSkillInfo(skillName) {
+        const cachedInfo = this.getLocalCacheSkills().find((skill) => skill.name === skillName);
+        if (cachedInfo) {
+            return cachedInfo;
+        }
         const url = `${this.config.registryUrl}/skills/${encodeURIComponent(skillName)}`;
         try {
             const response = await fetch(url, {
@@ -461,6 +1286,153 @@ export class SkillsHub extends EventEmitter {
         }
         return null;
     }
+    async previewInstalledSkillUpdate(skillName, options = {}) {
+        const installed = this.lockfile.skills[skillName];
+        if (!installed) {
+            logger.warn('Cannot preview update for missing skill', { name: skillName });
+            return null;
+        }
+        if (!fs.existsSync(installed.path)) {
+            throw new Error(`Skill file not found: ${installed.path}`);
+        }
+        const hubInfo = await this.getHubSkillInfo(skillName);
+        const targetVersion = options.version || hubInfo?.version;
+        if (!targetVersion) {
+            throw new Error(`No update metadata found for '${skillName}'`);
+        }
+        const currentContent = fs.readFileSync(installed.path, 'utf-8');
+        const remoteContent = await this.fetchSkillContent(skillName, targetVersion);
+        this.validateSkillContent(remoteContent, skillName);
+        const resolvedVersion = this.extractVersionFromContent(remoteContent) || targetVersion;
+        const currentChecksum = computeChecksum(currentContent);
+        const remoteChecksum = computeChecksum(remoteContent);
+        const diff = generateDiff(currentContent.trimEnd().split('\n'), remoteContent.trimEnd().split('\n'), `${skillName}/SKILL.md`, {
+            contextLines: 2,
+            summaryPrefix: 'Skill update',
+        });
+        const maxLines = options.maxDiffLines ?? 120;
+        const maxChars = options.maxDiffChars ?? 12000;
+        const linePreview = diff.diff.split('\n').slice(0, maxLines).join('\n');
+        const preview = linePreview.slice(0, maxChars);
+        return {
+            currentChecksum,
+            diff: {
+                addedLines: diff.addedLines,
+                maxChars,
+                maxLines,
+                preview,
+                removedLines: diff.removedLines,
+                summary: diff.summary,
+                truncated: linePreview.length > preview.length || diff.diff.split('\n').length > maxLines,
+            },
+            fromVersion: installed.version,
+            installCommand: `buddy skills update ${skillName} --approved-by <reviewer>${resolvedVersion ? ` --version ${resolvedVersion}` : ''}`,
+            name: skillName,
+            remoteChecksum,
+            sameContent: currentChecksum === remoteChecksum,
+            toVersion: resolvedVersion,
+            updateAvailable: compareSemver(resolvedVersion, installed.version) > 0,
+        };
+    }
+    async updateInstalledSkill(skillName, options = {}) {
+        const installed = this.lockfile.skills[skillName];
+        if (!installed) {
+            logger.warn('Cannot update missing skill', { name: skillName });
+            return null;
+        }
+        if (!fs.existsSync(installed.path)) {
+            throw new Error(`Skill file not found: ${installed.path}`);
+        }
+        const hubInfo = await this.getHubSkillInfo(skillName);
+        const targetVersion = options.version || hubInfo?.version;
+        if (!targetVersion) {
+            throw new Error(`No update metadata found for '${skillName}'`);
+        }
+        if (!options.force && compareSemver(targetVersion, installed.version) <= 0) {
+            throw new Error(`Skill '${skillName}' is already up to date (${installed.version})`);
+        }
+        const content = await this.fetchSkillContent(skillName, targetVersion);
+        this.validateSkillContent(content, skillName);
+        const resolvedVersion = this.extractVersionFromContent(content) || targetVersion;
+        if (!options.force && compareSemver(resolvedVersion, installed.version) <= 0) {
+            throw new Error(`Skill '${skillName}' update content is not newer (${resolvedVersion} <= ${installed.version})`);
+        }
+        const snapshot = this.snapshotInstalledSkill(installed, {
+            actor: options.actor,
+            reason: options.reason,
+            updatedAt: options.updatedAt,
+        });
+        const fromVersion = installed.version;
+        fs.writeFileSync(installed.path, content, 'utf-8');
+        installed.version = resolvedVersion;
+        installed.checksum = computeChecksum(content);
+        installed.lifecycle = {
+            status: installed.enabled === false ? 'disabled' : 'active',
+            updatedAt: options.updatedAt ?? Date.now(),
+            ...(options.actor ? { updatedBy: options.actor } : {}),
+            ...(options.reason ? { reason: options.reason } : {}),
+        };
+        this.appendSnapshot(installed, snapshot);
+        this.writeLockfile();
+        this.emit('skill:updated', installed);
+        return {
+            installed,
+            fromVersion,
+            toVersion: resolvedVersion,
+            snapshot,
+        };
+    }
+    async resetInstalledSkill(skillName, options = {}) {
+        const installed = this.lockfile.skills[skillName];
+        if (!installed) {
+            logger.warn('Cannot reset missing skill', { name: skillName });
+            return null;
+        }
+        const targetVersion = options.version || installed.version;
+        if (!targetVersion) {
+            throw new Error(`No reset version found for '${skillName}'`);
+        }
+        const content = await this.fetchSkillContent(skillName, targetVersion);
+        this.validateSkillContent(content, skillName);
+        const resolvedVersion = this.extractVersionFromContent(content) || targetVersion;
+        const toChecksum = computeChecksum(content);
+        const existedBeforeReset = fs.existsSync(installed.path);
+        const fromChecksum = existedBeforeReset
+            ? computeChecksum(fs.readFileSync(installed.path, 'utf-8'))
+            : undefined;
+        const snapshot = existedBeforeReset
+            ? this.snapshotInstalledSkill(installed, {
+                actor: options.actor,
+                reason: options.reason || `before reset to ${resolvedVersion}`,
+                updatedAt: options.updatedAt,
+            })
+            : undefined;
+        const fromVersion = installed.version;
+        fs.mkdirSync(path.dirname(installed.path), { recursive: true });
+        fs.writeFileSync(installed.path, content, 'utf-8');
+        installed.version = resolvedVersion;
+        installed.checksum = toChecksum;
+        installed.lifecycle = {
+            status: installed.enabled === false ? 'disabled' : 'active',
+            updatedAt: options.updatedAt ?? Date.now(),
+            ...(options.actor ? { updatedBy: options.actor } : {}),
+            ...(options.reason ? { reason: options.reason } : {}),
+        };
+        if (snapshot) {
+            this.appendSnapshot(installed, snapshot);
+        }
+        this.writeLockfile();
+        this.emit('skill:reset', installed);
+        return {
+            installed,
+            ...(fromChecksum ? { fromChecksum } : {}),
+            fromVersion,
+            recreated: !existedBeforeReset,
+            ...(snapshot ? { snapshot } : {}),
+            toChecksum,
+            toVersion: resolvedVersion,
+        };
+    }
     // ==========================================================================
     // Publish
     // ==========================================================================
@@ -469,7 +1441,7 @@ export class SkillsHub extends EventEmitter {
      * Reads the SKILL.md, validates YAML frontmatter, computes checksum,
      * and returns the prepared HubSkill metadata.
      */
-    async publish(skillPath) {
+    async publish(skillPath, options = {}) {
         const resolvedPath = path.resolve(skillPath);
         if (!fs.existsSync(resolvedPath)) {
             throw new Error(`Skill file not found: ${resolvedPath}`);
@@ -514,11 +1486,20 @@ export class SkillsHub extends EventEmitter {
             checksum,
             size,
         };
+        // Optionally attach a detached Ed25519 signature so consumers can verify
+        // authenticity (not just integrity) before installing.
+        if (options.signingKey) {
+            hubSkill.signature = signSkillContent(content, options.signingKey, {
+                ...(options.keyId ? { keyId: options.keyId } : {}),
+                ...(options.signedAt ? { signedAt: options.signedAt } : {}),
+            });
+        }
         logger.info('Skill prepared for publishing', {
             name: hubSkill.name,
             version: hubSkill.version,
             checksum,
             size,
+            signed: Boolean(hubSkill.signature),
         });
         this.emit('skill:published', hubSkill);
         return hubSkill;
@@ -541,6 +1522,8 @@ export class SkillsHub extends EventEmitter {
         const skillNames = Object.keys(this.lockfile.skills);
         for (const name of skillNames) {
             const entry = this.lockfile.skills[name];
+            if (!entry)
+                continue;
             // Check if skill still exists on disk
             if (!fs.existsSync(entry.path)) {
                 logger.info('Skill file missing, removing from lockfile', { name, path: entry.path });
@@ -590,6 +1573,405 @@ export class SkillsHub extends EventEmitter {
     list() {
         return Object.values(this.lockfile.skills);
     }
+    /**
+     * List installed skills with cheap on-disk health checks so stale lockfile
+     * entries are visible before an agent or operator tries to reuse them.
+     */
+    listWithIntegrity() {
+        return this.list().map((skill) => {
+            const detail = this.info(skill.name);
+            const exists = typeof detail?.content === 'string';
+            return {
+                ...skill,
+                exists,
+                integrityOk: detail?.integrityOk ?? false,
+                ...(exists ? { sizeBytes: Buffer.byteLength(detail.content, 'utf-8') } : {}),
+            };
+        });
+    }
+    /**
+     * List only enabled skills (absent `enabled` flag counts as enabled). This is
+     * the set selection/injection should use so a disabled package stays
+     * installed but inactive.
+     */
+    listEnabled() {
+        return this.list().filter((skill) => skill.enabled !== false);
+    }
+    setEnabled(skillName, enabled, options) {
+        let installed = this.lockfile.skills[skillName];
+        if (!installed) {
+            if (!options?.path) {
+                logger.warn('Cannot toggle missing skill', { name: skillName });
+                return null;
+            }
+            installed = {
+                name: skillName,
+                version: options?.version || '0.0.0',
+                installedAt: Date.now(),
+                source: 'local',
+                checksum: '',
+                path: options.path,
+                enabled: enabled,
+            };
+            this.lockfile.skills[skillName] = installed;
+        }
+        else {
+            installed.enabled = enabled;
+        }
+        installed.lifecycle = {
+            status: enabled ? 'active' : options?.status ?? 'disabled',
+            updatedAt: options?.updatedAt ?? Date.now(),
+            ...(options?.actor ? { updatedBy: options.actor } : {}),
+            ...(options?.reason ? { reason: options.reason } : {}),
+        };
+        this.writeLockfile();
+        this.emit('skill:enabled', { name: skillName, enabled });
+        return installed;
+    }
+    /**
+     * Rewrite an installed SKILL.md. The current file is snapshotted before
+     * writing, so review-gated edits can roll back.
+     */
+    editInstalledSkill(skillName, content, options = {}) {
+        const installed = this.lockfile.skills[skillName];
+        if (!installed) {
+            logger.warn('Cannot edit missing skill', { name: skillName });
+            return null;
+        }
+        if (!fs.existsSync(installed.path)) {
+            throw new Error(`Skill file not found: ${installed.path}`);
+        }
+        this.validateSkillContent(content, skillName);
+        const snapshot = this.snapshotInstalledSkill(installed, {
+            actor: options.actor,
+            reason: options.reason,
+            updatedAt: options.updatedAt,
+        });
+        fs.writeFileSync(installed.path, content, 'utf-8');
+        installed.checksum = computeChecksum(content);
+        installed.version = this.extractVersionFromContent(content) || installed.version;
+        installed.lifecycle = {
+            status: installed.enabled === false ? 'disabled' : 'active',
+            updatedAt: options.updatedAt ?? Date.now(),
+            ...(options.actor ? { updatedBy: options.actor } : {}),
+            ...(options.reason ? { reason: options.reason } : {}),
+        };
+        this.appendSnapshot(installed, snapshot);
+        this.writeLockfile();
+        this.emit('skill:edited', { name: skillName, snapshot });
+        return { installed, snapshot };
+    }
+    /**
+     * Patch an installed SKILL.md or one of its supporting files with a literal
+     * text replacement. The current SKILL.md is snapshotted before writing, so
+     * review-gated guidance edits can roll back.
+     */
+    patchInstalledSkill(skillName, oldText, newText, options = {}) {
+        const installed = this.lockfile.skills[skillName];
+        if (!installed) {
+            logger.warn('Cannot patch missing skill', { name: skillName });
+            return null;
+        }
+        if (!oldText) {
+            throw new Error('Patch oldText must not be empty');
+        }
+        if (!fs.existsSync(installed.path)) {
+            throw new Error(`Skill file not found: ${installed.path}`);
+        }
+        const targetPath = this.resolveSkillMutationPath(installed, options.filePath);
+        if (!fs.existsSync(targetPath)) {
+            throw new Error(`Skill file not found: ${targetPath}`);
+        }
+        const content = fs.readFileSync(targetPath, 'utf-8');
+        const replacements = content.split(oldText).length - 1;
+        if (replacements === 0) {
+            throw new Error(`Patch text not found in skill '${skillName}'`);
+        }
+        const replaceAll = options.replaceAll === true;
+        if (!replaceAll && replacements !== 1) {
+            throw new Error(`Patch text is not unique in '${skillName}' (${replacements} matches). Set replace_all=true to replace all occurrences.`);
+        }
+        if (typeof options.expectedReplacements === 'number'
+            && options.expectedReplacements !== replacements) {
+            throw new Error(`Patch replacement count mismatch for '${skillName}': expected ${options.expectedReplacements}, found ${replacements}`);
+        }
+        const updatedContent = replaceAll
+            ? content.split(oldText).join(newText)
+            : content.replace(oldText, newText);
+        const relativeFilePath = this.relativeSkillMutationPath(installed, targetPath);
+        const targetIsSkillMd = path.resolve(targetPath) === path.resolve(installed.path);
+        if (targetIsSkillMd) {
+            this.validateSkillContent(updatedContent, skillName);
+        }
+        const snapshot = this.snapshotInstalledSkill(installed, {
+            actor: options.actor,
+            reason: options.reason,
+            updatedAt: options.updatedAt,
+        });
+        fs.writeFileSync(targetPath, updatedContent, 'utf-8');
+        if (targetIsSkillMd) {
+            installed.checksum = computeChecksum(updatedContent);
+            installed.version = this.extractVersionFromContent(updatedContent) || installed.version;
+        }
+        installed.lifecycle = {
+            status: installed.enabled === false ? 'disabled' : 'active',
+            updatedAt: options.updatedAt ?? Date.now(),
+            ...(options.actor ? { updatedBy: options.actor } : {}),
+            ...(options.reason ? { reason: options.reason } : {}),
+        };
+        this.appendSnapshot(installed, snapshot);
+        this.writeLockfile();
+        this.emit('skill:patched', { name: skillName, filePath: relativeFilePath, snapshot, replacements });
+        return { installed, filePath: relativeFilePath, replacements, snapshot };
+    }
+    /**
+     * Add or overwrite a supporting file in an installed skill directory.
+     */
+    writeSkillSupportingFile(skillName, filePath, fileContent, options = {}) {
+        const installed = this.lockfile.skills[skillName];
+        if (!installed) {
+            logger.warn('Cannot write file for missing skill', { name: skillName });
+            return null;
+        }
+        if (!fs.existsSync(installed.path)) {
+            throw new Error(`Skill file not found: ${installed.path}`);
+        }
+        const byteLength = Buffer.byteLength(fileContent, 'utf-8');
+        if (byteLength > MAX_SUPPORTING_FILE_BYTES) {
+            throw new Error(`Supporting file exceeds ${MAX_SUPPORTING_FILE_BYTES} bytes`);
+        }
+        const targetPath = this.resolveSkillMutationPath(installed, filePath, { requireSupportingDir: true });
+        const snapshot = this.snapshotInstalledSkill(installed, {
+            actor: options.actor,
+            reason: options.reason,
+            updatedAt: options.updatedAt,
+        });
+        fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+        fs.writeFileSync(targetPath, fileContent, 'utf-8');
+        installed.lifecycle = {
+            status: installed.enabled === false ? 'disabled' : 'active',
+            updatedAt: options.updatedAt ?? Date.now(),
+            ...(options.actor ? { updatedBy: options.actor } : {}),
+            ...(options.reason ? { reason: options.reason } : {}),
+        };
+        this.appendSnapshot(installed, snapshot);
+        this.writeLockfile();
+        const relativeFilePath = this.relativeSkillMutationPath(installed, targetPath);
+        this.emit('skill:file_written', { name: skillName, filePath: relativeFilePath, snapshot });
+        return {
+            absolutePath: targetPath,
+            bytesWritten: byteLength,
+            filePath: relativeFilePath,
+            installed,
+            snapshot,
+        };
+    }
+    /**
+     * Remove a supporting file from an installed skill directory.
+     */
+    removeSkillSupportingFile(skillName, filePath, options = {}) {
+        const installed = this.lockfile.skills[skillName];
+        if (!installed) {
+            logger.warn('Cannot remove file for missing skill', { name: skillName });
+            return null;
+        }
+        if (!fs.existsSync(installed.path)) {
+            throw new Error(`Skill file not found: ${installed.path}`);
+        }
+        const targetPath = this.resolveSkillMutationPath(installed, filePath, { requireSupportingDir: true });
+        if (!fs.existsSync(targetPath)) {
+            throw new Error(`Supporting file not found: ${filePath}`);
+        }
+        const snapshot = this.snapshotInstalledSkill(installed, {
+            actor: options.actor,
+            reason: options.reason,
+            updatedAt: options.updatedAt,
+        });
+        fs.rmSync(targetPath, { force: false });
+        this.removeEmptySupportingParents(installed, path.dirname(targetPath));
+        installed.lifecycle = {
+            status: installed.enabled === false ? 'disabled' : 'active',
+            updatedAt: options.updatedAt ?? Date.now(),
+            ...(options.actor ? { updatedBy: options.actor } : {}),
+            ...(options.reason ? { reason: options.reason } : {}),
+        };
+        this.appendSnapshot(installed, snapshot);
+        this.writeLockfile();
+        const relativeFilePath = this.relativeSkillMutationPath(installed, targetPath);
+        this.emit('skill:file_removed', { name: skillName, filePath: relativeFilePath, snapshot });
+        return {
+            absolutePath: targetPath,
+            filePath: relativeFilePath,
+            installed,
+            removed: true,
+            snapshot,
+        };
+    }
+    /**
+     * Restore a previous SKILL.md snapshot, snapshotting the current file first
+     * so rollback itself remains reversible.
+     */
+    rollbackInstalledSkill(skillName, snapshotId, options = {}) {
+        const installed = this.lockfile.skills[skillName];
+        if (!installed) {
+            logger.warn('Cannot rollback missing skill', { name: skillName });
+            return null;
+        }
+        if (!fs.existsSync(installed.path)) {
+            throw new Error(`Skill file not found: ${installed.path}`);
+        }
+        const history = installed.history ?? [];
+        const restoredSnapshot = snapshotId
+            ? history.find((snapshot) => snapshot.id === snapshotId)
+            : history[history.length - 1];
+        if (!restoredSnapshot) {
+            throw new Error(snapshotId
+                ? `Rollback snapshot not found for '${skillName}': ${snapshotId}`
+                : `No rollback snapshots available for '${skillName}'`);
+        }
+        if (!fs.existsSync(restoredSnapshot.snapshotPath)) {
+            throw new Error(`Rollback snapshot file not found: ${restoredSnapshot.snapshotPath}`);
+        }
+        const restoredContent = fs.readFileSync(restoredSnapshot.snapshotPath, 'utf-8');
+        this.validateSkillContent(restoredContent, skillName);
+        const currentSnapshot = this.snapshotInstalledSkill(installed, {
+            actor: options.actor,
+            reason: options.reason
+                ? `before rollback: ${options.reason}`
+                : `before rollback to ${restoredSnapshot.id}`,
+            updatedAt: options.updatedAt,
+        });
+        fs.writeFileSync(installed.path, restoredContent, 'utf-8');
+        installed.checksum = computeChecksum(restoredContent);
+        installed.version = this.extractVersionFromContent(restoredContent) || restoredSnapshot.version;
+        installed.lifecycle = {
+            status: installed.enabled === false ? 'disabled' : 'active',
+            updatedAt: options.updatedAt ?? Date.now(),
+            ...(options.actor ? { updatedBy: options.actor } : {}),
+            ...(options.reason ? { reason: options.reason } : {}),
+        };
+        this.appendSnapshot(installed, currentSnapshot);
+        this.writeLockfile();
+        this.emit('skill:rolled_back', { name: skillName, restoredSnapshot, currentSnapshot });
+        return { installed, restoredSnapshot, currentSnapshot };
+    }
+    /**
+     * Return current installed skill state plus rollback snapshots with on-disk
+     * integrity checks. This is the read model Cowork/CLI use before offering a
+     * version restore decision to a human reviewer.
+     */
+    getInstalledSkillHistory(skillName) {
+        const detail = this.info(skillName);
+        if (!detail) {
+            return null;
+        }
+        const { installed, content, integrityOk } = detail;
+        const snapshots = [...(installed.history ?? [])]
+            .map((snapshot) => {
+            const snapshotExists = fs.existsSync(snapshot.snapshotPath);
+            let snapshotIntegrityOk = false;
+            let sizeBytes;
+            if (snapshotExists) {
+                const snapshotContent = fs.readFileSync(snapshot.snapshotPath, 'utf-8');
+                snapshotIntegrityOk = computeChecksum(snapshotContent) === snapshot.checksum;
+                sizeBytes = Buffer.byteLength(snapshotContent, 'utf-8');
+            }
+            return {
+                ...snapshot,
+                rollbackable: snapshotExists && snapshotIntegrityOk,
+                snapshotExists,
+                snapshotIntegrityOk,
+                ...(typeof sizeBytes === 'number' ? { sizeBytes } : {}),
+            };
+        })
+            .sort((left, right) => right.createdAt - left.createdAt);
+        return {
+            installed,
+            current: {
+                checksum: installed.checksum,
+                enabled: installed.enabled !== false,
+                exists: typeof content === 'string',
+                installedAt: installed.installedAt,
+                integrityOk,
+                path: installed.path,
+                source: installed.source,
+                version: installed.version,
+                ...(installed.lifecycle ? { lifecycle: installed.lifecycle } : {}),
+                ...(typeof content === 'string' ? { sizeBytes: Buffer.byteLength(content, 'utf-8') } : {}),
+            },
+            snapshots,
+            rollbackableCount: snapshots.filter((snapshot) => snapshot.rollbackable).length,
+            missingSnapshotCount: snapshots.filter((snapshot) => !snapshot.snapshotExists).length,
+        };
+    }
+    /**
+     * Record local skill usage so frequently useful skills can be curated.
+     * Hermes-style learning starts with this small durable signal.
+     */
+    recordUsage(skillName, record) {
+        const installed = this.lockfile.skills[skillName];
+        if (!installed) {
+            logger.warn('Cannot record usage for missing skill', { name: skillName });
+            return null;
+        }
+        const previous = installed.usage;
+        const invocationCount = (previous?.invocationCount ?? 0) + 1;
+        const previousAverage = previous?.averageDurationMs ?? 0;
+        const durationMs = record.durationMs;
+        const averageDurationMs = typeof durationMs === 'number'
+            ? ((previousAverage * (invocationCount - 1)) + durationMs) / invocationCount
+            : previous?.averageDurationMs;
+        installed.usage = {
+            invocationCount,
+            successCount: (previous?.successCount ?? 0) + (record.success ? 1 : 0),
+            failureCount: (previous?.failureCount ?? 0) + (record.success ? 0 : 1),
+            lastUsedAt: record.usedAt ?? Date.now(),
+            lastDurationMs: durationMs,
+            averageDurationMs,
+            lastError: record.success ? undefined : record.error,
+        };
+        this.writeLockfile();
+        this.emit('skill:usage', installed);
+        return installed;
+    }
+    /**
+     * Return installed skills ordered by local usage frequency.
+     */
+    usageSummary() {
+        return this.list()
+            .filter(skill => Boolean(skill.usage))
+            .sort((left, right) => {
+            const countDelta = (right.usage?.invocationCount ?? 0) - (left.usage?.invocationCount ?? 0);
+            if (countDelta !== 0)
+                return countDelta;
+            return (right.usage?.lastUsedAt ?? 0) - (left.usage?.lastUsedAt ?? 0);
+        });
+    }
+    snapshotInstalledSkill(installed, options = {}) {
+        if (!fs.existsSync(installed.path)) {
+            throw new Error(`Skill file not found: ${installed.path}`);
+        }
+        const content = fs.readFileSync(installed.path, 'utf-8');
+        const checksum = computeChecksum(content);
+        const createdAt = options.updatedAt ?? Date.now();
+        const id = `${createdAt.toString(36)}-${randomUUID().slice(0, 8)}-${checksum.slice(0, 12)}`;
+        const snapshotDir = path.join(this.config.cacheDir, 'history', installed.name.replace(/[^a-zA-Z0-9_-]/g, '_'));
+        const snapshotPath = path.join(snapshotDir, `${id}.SKILL.md`);
+        fs.mkdirSync(snapshotDir, { recursive: true });
+        fs.writeFileSync(snapshotPath, content, 'utf-8');
+        return {
+            id,
+            createdAt,
+            checksum,
+            version: this.extractVersionFromContent(content) || installed.version,
+            snapshotPath,
+            ...(options.actor ? { createdBy: options.actor } : {}),
+            ...(options.reason ? { reason: options.reason } : {}),
+        };
+    }
+    appendSnapshot(installed, snapshot) {
+        installed.history = [...(installed.history ?? []), snapshot].slice(-20);
+    }
     /**
      * Get detailed information about an installed skill.
      * Returns the lockfile entry plus the current on-disk content metadata.
@@ -611,6 +1993,70 @@ export class SkillsHub extends EventEmitter {
     // ==========================================================================
     // Helpers
     // ==========================================================================
+    resolveSkillMutationPath(installed, filePath, options = {}) {
+        const skillDir = path.dirname(installed.path);
+        if (!filePath || filePath.trim() === '') {
+            if (options.requireSupportingDir) {
+                throw new Error('file_path is required');
+            }
+            return installed.path;
+        }
+        const normalized = filePath.trim().replace(/\\/g, '/');
+        if (normalized.startsWith('/')
+            || path.isAbsolute(normalized)
+            || /^[A-Za-z]:/.test(normalized)
+            || normalized.split('/').some((part) => part === '..' || part === '')) {
+            throw new Error(`Unsafe skill file path: ${filePath}`);
+        }
+        if (normalized === 'SKILL.md') {
+            if (options.requireSupportingDir) {
+                throw new Error('SKILL.md cannot be used as a supporting file path');
+            }
+            return installed.path;
+        }
+        const parts = normalized.split('/');
+        const [topLevel] = parts;
+        if (!topLevel || !SUPPORTING_FILE_DIRS.has(topLevel)) {
+            throw new Error(`Unsupported skill file path '${filePath}'. Use references/, templates/, scripts/, or assets/.`);
+        }
+        if (parts.length < 2 || !parts[parts.length - 1]) {
+            throw new Error(`Unsupported skill file path '${filePath}'. Use a file under references/, templates/, scripts/, or assets/.`);
+        }
+        const targetPath = path.resolve(skillDir, ...parts);
+        const relative = path.relative(skillDir, targetPath);
+        if (relative.startsWith('..') || path.isAbsolute(relative)) {
+            throw new Error(`Unsafe skill file path: ${filePath}`);
+        }
+        return targetPath;
+    }
+    relativeSkillMutationPath(installed, targetPath) {
+        if (path.resolve(targetPath) === path.resolve(installed.path)) {
+            return 'SKILL.md';
+        }
+        return path.relative(path.dirname(installed.path), targetPath).replace(/\\/g, '/');
+    }
+    removeEmptySupportingParents(installed, startDir) {
+        const skillDir = path.dirname(installed.path);
+        let current = path.resolve(startDir);
+        while (current !== path.resolve(skillDir)) {
+            const relative = path.relative(skillDir, current).replace(/\\/g, '/');
+            const [topLevel] = relative.split('/');
+            if (!topLevel || !SUPPORTING_FILE_DIRS.has(topLevel)) {
+                return;
+            }
+            try {
+                if (fs.existsSync(current) && fs.readdirSync(current).length === 0) {
+                    fs.rmdirSync(current);
+                    current = path.dirname(current);
+                    continue;
+                }
+            }
+            catch {
+                return;
+            }
+            return;
+        }
+    }
     /**
      * Extract the version field from SKILL.md YAML frontmatter.
      */
@@ -618,8 +2064,10 @@ export class SkillsHub extends EventEmitter {
         const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
         if (!match)
             return null;
+        // safe: regex matched with a mandatory capture group, so match[1] is present
+        const frontmatter = match[1] ?? '';
         try {
-            const parsed = yaml.parse(match[1]);
+            const parsed = yaml.parse(frontmatter);
             if (typeof parsed.version === 'string') {
                 return parsed.version;
             }
@@ -638,8 +2086,10 @@ export class SkillsHub extends EventEmitter {
         if (!match) {
             throw new Error(`Invalid SKILL.md format for '${skillName}': missing YAML frontmatter`);
         }
+        // safe: regex matched with a mandatory capture group, so match[1] is present
+        const frontmatter = match[1] ?? '';
         try {
-            const parsed = yaml.parse(match[1]);
+            const parsed = yaml.parse(frontmatter);
             if (!parsed.name || typeof parsed.name !== 'string') {
                 throw new Error(`SKILL.md for '${skillName}' is missing required 'name' field`);
             }