@phnx-labs/agents-cli 1.12.0 → 1.14.2

package/dist/lib/skills.d.ts

@@ -1,4 +1,13 @@
+/**
+ * Skill management -- discovery, installation, and syncing of SKILL.md bundles.
+ *
+ * Skills are knowledge packs stored in ~/.agents/skills/. Each skill directory
+ * contains a SKILL.md (with frontmatter metadata) and optional supporting files
+ * (rules/, examples/, etc.). This module handles parsing skill metadata,
+ * installing skills into agent version homes, and tracking installation state.
+ */
 import type { AgentId, SkillMetadata, InstalledSkill } from './types.js';
+/** User-scoped skills dir (~/.agents/skills/). Used for installs. */
 export declare function getSkillsDir(): string;
 export declare function ensureCentralSkillsDir(): void;
 export declare function getAgentSkillsDir(agentId: AgentId): string;
@@ -41,6 +50,12 @@ export interface DiscoveredSkill {
     ruleCount: number;
     validation: ValidationResult;
     parseError?: string;
+    /**
+     * Which repo the skill was discovered in. `undefined` means the primary
+     * ~/.agents/ repo; otherwise the alias of an extra repo registered via
+     * `agents repo add`. Primary wins on name collisions.
+     */
+    source?: string;
 }
 export declare function discoverSkillsFromRepo(repoPath: string): DiscoveredSkill[];
 export declare function installSkill(sourcePath: string, skillName: string, agents: AgentId[], method?: 'symlink' | 'copy'): {
@@ -58,9 +73,20 @@ export declare function skillExists(agentId: AgentId, skillName: string): boolea
  */
 export declare function skillContentMatches(agentId: AgentId, skillName: string, sourcePath: string): boolean;
 /**
- * List skill names in the central ~/.agents/skills/ directory.
+ * List skill names from user (~/.agents/skills/) and system (~/.agents-system/skills/) dirs.
+ * User dir takes priority; deduplication preserves first occurrence.
  */
 export declare function listCentralSkills(): string[];
+/**
+ * Resolve a skill name to its source directory. Searches user dir first,
+ * then system dir, then extra repos. Returns null if no source has a SKILL.md.
+ */
+export declare function resolveSkillSourcePath(skillName: string): string | null;
+/**
+ * Union of skill names available across the primary and all enabled extras.
+ * Primary wins on name collision.
+ */
+export declare function listAllSkills(): string[];
 /**
  * Path to the skills dir of a specific version home (not the active one).
  */
@@ -131,4 +157,3 @@ export declare function installSkillCentrally(sourcePath: string, skillName: str
     error?: string;
     warnings?: string[];
 };
-//# sourceMappingURL=skills.d.ts.map

package/dist/lib/skills.js

@@ -1,16 +1,25 @@
+/**
+ * Skill management -- discovery, installation, and syncing of SKILL.md bundles.
+ *
+ * Skills are knowledge packs stored in ~/.agents/skills/. Each skill directory
+ * contains a SKILL.md (with frontmatter metadata) and optional supporting files
+ * (rules/, examples/, etc.). This module handles parsing skill metadata,
+ * installing skills into agent version homes, and tracking installation state.
+ */
 import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
 import * as yaml from 'yaml';
 import { SKILLS_CAPABLE_AGENTS, ensureSkillsDir } from './agents.js';
-import { getAgentsDir, getProjectAgentsDir } from './state.js';
+import { getUserSkillsDir, getSkillsDir as getSystemSkillsDir, getProjectAgentsDir, getEnabledExtraRepos } from './state.js';
 import { getEffectiveHome, getVersionHomePath, listInstalledVersions } from './versions.js';
 const HOME = os.homedir();
+/** User-scoped skills dir (~/.agents/skills/). Used for installs. */
 export function getSkillsDir() {
-    return path.join(getAgentsDir(), 'skills');
+    return getUserSkillsDir();
 }
 export function ensureCentralSkillsDir() {
-    const dir = getSkillsDir();
+    const dir = getUserSkillsDir();
     if (!fs.existsSync(dir)) {
         fs.mkdirSync(dir, { recursive: true });
     }
@@ -317,17 +326,60 @@ export function skillContentMatches(agentId, skillName, sourcePath) {
     }
 }
 /**
- * List skill names in the central ~/.agents/skills/ directory.
+ * List skill names from user (~/.agents/skills/) and system (~/.agents-system/skills/) dirs.
+ * User dir takes priority; deduplication preserves first occurrence.
  */
 export function listCentralSkills() {
-    const dir = getSkillsDir();
-    if (!fs.existsSync(dir))
-        return [];
-    return fs.readdirSync(dir, { withFileTypes: true })
-        .filter((e) => e.isDirectory() && !e.name.startsWith('.'))
-        .filter((e) => fs.existsSync(path.join(dir, e.name, 'SKILL.md')))
-        .map((e) => e.name)
-        .sort();
+    const seen = new Set();
+    for (const dir of [getUserSkillsDir(), getSystemSkillsDir()]) {
+        if (!fs.existsSync(dir))
+            continue;
+        for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+            if (!e.isDirectory() || e.name.startsWith('.'))
+                continue;
+            if (!fs.existsSync(path.join(dir, e.name, 'SKILL.md')))
+                continue;
+            seen.add(e.name);
+        }
+    }
+    return Array.from(seen).sort();
+}
+/**
+ * Resolve a skill name to its source directory. Searches user dir first,
+ * then system dir, then extra repos. Returns null if no source has a SKILL.md.
+ */
+export function resolveSkillSourcePath(skillName) {
+    for (const dir of [getUserSkillsDir(), getSystemSkillsDir()]) {
+        const candidate = path.join(dir, skillName);
+        if (fs.existsSync(path.join(candidate, 'SKILL.md')))
+            return candidate;
+    }
+    for (const extra of getEnabledExtraRepos()) {
+        const candidate = path.join(extra.dir, 'skills', skillName);
+        if (fs.existsSync(path.join(candidate, 'SKILL.md')))
+            return candidate;
+    }
+    return null;
+}
+/**
+ * Union of skill names available across the primary and all enabled extras.
+ * Primary wins on name collision.
+ */
+export function listAllSkills() {
+    const seen = new Set(listCentralSkills());
+    for (const extra of getEnabledExtraRepos()) {
+        const dir = path.join(extra.dir, 'skills');
+        if (!fs.existsSync(dir))
+            continue;
+        for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+            if (!e.isDirectory() || e.name.startsWith('.'))
+                continue;
+            if (!fs.existsSync(path.join(dir, e.name, 'SKILL.md')))
+                continue;
+            seen.add(e.name);
+        }
+    }
+    return Array.from(seen).sort();
 }
 /**
  * Path to the skills dir of a specific version home (not the active one).
@@ -354,35 +406,35 @@ export function listSkillsInVersionHome(agent, version) {
  */
 function versionSkillMatches(agent, version, skillName) {
     const installedPath = path.join(getVersionSkillsDir(agent, version), skillName);
-    const centralPath = path.join(getSkillsDir(), skillName);
-    if (!fs.existsSync(installedPath) || !fs.existsSync(centralPath))
+    const sourcePath = resolveSkillSourcePath(skillName);
+    if (!fs.existsSync(installedPath) || !sourcePath)
         return false;
     const installedSkillMd = path.join(installedPath, 'SKILL.md');
-    const centralSkillMd = path.join(centralPath, 'SKILL.md');
-    if (!fs.existsSync(installedSkillMd) || !fs.existsSync(centralSkillMd))
+    const sourceSkillMd = path.join(sourcePath, 'SKILL.md');
+    if (!fs.existsSync(installedSkillMd) || !fs.existsSync(sourceSkillMd))
         return false;
     try {
         if (normalizeContent(fs.readFileSync(installedSkillMd, 'utf-8')) !==
-            normalizeContent(fs.readFileSync(centralSkillMd, 'utf-8'))) {
+            normalizeContent(fs.readFileSync(sourceSkillMd, 'utf-8'))) {
             return false;
         }
     }
     catch {
         return false;
     }
-    return directoriesMatch(path.join(installedPath, 'rules'), path.join(centralPath, 'rules'));
+    return directoriesMatch(path.join(installedPath, 'rules'), path.join(sourcePath, 'rules'));
 }
 /**
  * Compare a version home's skills against central. Returns the reconciliation diff.
  */
 export function diffVersionSkills(agent, version) {
-    const central = new Set(listCentralSkills());
+    const available = new Set(listAllSkills());
     const installed = new Set(listSkillsInVersionHome(agent, version));
     const toAdd = [];
     const toUpdate = [];
     const matched = [];
     const orphans = [];
-    for (const name of central) {
+    for (const name of available) {
         if (!installed.has(name)) {
             toAdd.push(name);
         }
@@ -394,7 +446,7 @@ export function diffVersionSkills(agent, version) {
         }
     }
     for (const name of installed) {
-        if (!central.has(name))
+        if (!available.has(name))
             orphans.push(name);
     }
     return { agent, version, toAdd: toAdd.sort(), toUpdate: toUpdate.sort(), matched, orphans: orphans.sort() };
@@ -439,9 +491,9 @@ function walkRelativeFiles(base) {
  * local secrets.
  */
 export function installSkillToVersion(agent, version, skillName, method = 'copy') {
-    const centralPath = path.join(getSkillsDir(), skillName);
-    if (!fs.existsSync(centralPath)) {
-        return { success: false, error: `Skill '${skillName}' not found in central` };
+    const sourcePath = resolveSkillSourcePath(skillName);
+    if (!sourcePath) {
+        return { success: false, error: `Skill '${skillName}' not found in central or any extra repo` };
     }
     const skillsDir = getVersionSkillsDir(agent, version);
     if (!fs.existsSync(skillsDir)) {
@@ -449,15 +501,15 @@ export function installSkillToVersion(agent, version, skillName, method = 'copy'
     }
     const target = path.join(skillsDir, skillName);
     // Snapshot files unique to the version home so we can restore them after
-    // the fresh copy (copy mode only; symlink shares central so there's nothing
-    // local to preserve — and writing a .env into a symlinked skill would
-    // pollute the git-tracked central dir anyway).
+    // the fresh copy (copy mode only; symlink shares the source so there's
+    // nothing local to preserve — and writing a .env into a symlinked skill
+    // would pollute the git-tracked source dir anyway).
     const preserved = [];
     if (method === 'copy' && fs.existsSync(target) && !fs.lstatSync(target).isSymbolicLink()) {
-        const centralFiles = walkRelativeFiles(centralPath);
+        const sourceFiles = walkRelativeFiles(sourcePath);
         const installedFiles = walkRelativeFiles(target);
         for (const rel of installedFiles) {
-            if (centralFiles.has(rel))
+            if (sourceFiles.has(rel))
                 continue;
             try {
                 const abs = path.join(target, rel);
@@ -482,10 +534,10 @@ export function installSkillToVersion(agent, version, skillName, method = 'copy'
     }
     try {
         if (method === 'symlink') {
-            fs.symlinkSync(centralPath, target, 'dir');
+            fs.symlinkSync(sourcePath, target, 'dir');
         }
         else {
-            fs.cpSync(centralPath, target, { recursive: true });
+            fs.cpSync(sourcePath, target, { recursive: true });
         }
     }
     catch (err) {
@@ -568,34 +620,42 @@ export function uninstallSkill(skillName) {
 }
 export function listInstalledSkills() {
     const skills = new Map();
-    const centralDir = getSkillsDir();
-    if (!fs.existsSync(centralDir)) {
-        return skills;
-    }
-    try {
-        const entries = fs.readdirSync(centralDir, { withFileTypes: true });
-        for (const entry of entries) {
-            if (!entry.isDirectory())
-                continue;
-            // Skip hidden directories (e.g., .system)
-            if (entry.name.startsWith('.'))
-                continue;
-            const skillDir = path.join(centralDir, entry.name);
-            const metadata = parseSkillMetadata(skillDir);
-            const validation = validateSkillMetadata(metadata, entry.name);
-            if (metadata) {
-                skills.set(entry.name, {
-                    name: entry.name,
-                    path: skillDir,
-                    metadata,
-                    ruleCount: countSkillRules(skillDir),
-                    validation,
-                });
+    const scan = (dir, source) => {
+        if (!fs.existsSync(dir))
+            return;
+        try {
+            const entries = fs.readdirSync(dir, { withFileTypes: true });
+            for (const entry of entries) {
+                if (!entry.isDirectory())
+                    continue;
+                // Skip hidden directories (e.g., .system)
+                if (entry.name.startsWith('.'))
+                    continue;
+                // Primary wins on name collisions.
+                if (skills.has(entry.name))
+                    continue;
+                const skillDir = path.join(dir, entry.name);
+                const metadata = parseSkillMetadata(skillDir);
+                const validation = validateSkillMetadata(metadata, entry.name);
+                if (metadata) {
+                    skills.set(entry.name, {
+                        name: entry.name,
+                        path: skillDir,
+                        metadata,
+                        ruleCount: countSkillRules(skillDir),
+                        validation,
+                        source,
+                    });
+                }
             }
         }
-    }
-    catch {
-        // Ignore errors
+        catch {
+            // Ignore errors
+        }
+    };
+    scan(getSkillsDir());
+    for (const extra of getEnabledExtraRepos()) {
+        scan(path.join(extra.dir, 'skills'), extra.alias);
     }
     return skills;
 }
@@ -710,26 +770,29 @@ export function listInstalledSkillsWithScope(agentId, cwd = process.cwd(), optio
     return results;
 }
 export function getSkillInfo(skillName) {
-    const centralPath = path.join(getSkillsDir(), skillName);
-    if (!fs.existsSync(centralPath)) {
+    const sourcePath = resolveSkillSourcePath(skillName);
+    if (!sourcePath) {
         return null;
     }
-    const metadata = parseSkillMetadata(centralPath);
+    const metadata = parseSkillMetadata(sourcePath);
     const validation = validateSkillMetadata(metadata, skillName);
     if (!metadata) {
         return null;
     }
     return {
         name: skillName,
-        path: centralPath,
+        path: sourcePath,
         metadata,
-        ruleCount: countSkillRules(centralPath),
+        ruleCount: countSkillRules(sourcePath),
         validation,
     };
 }
 export function getSkillRules(skillName) {
-    const centralPath = path.join(getSkillsDir(), skillName);
-    const rulesDir = path.join(centralPath, 'rules');
+    const sourcePath = resolveSkillSourcePath(skillName);
+    if (!sourcePath) {
+        return [];
+    }
+    const rulesDir = path.join(sourcePath, 'rules');
     if (!fs.existsSync(rulesDir)) {
         return [];
     }
@@ -780,4 +843,3 @@ export function installSkillCentrally(sourcePath, skillName) {
         return { success: false, error: `Failed to copy skill: ${err.message}` };
     }
 }
-//# sourceMappingURL=skills.js.map

package/dist/lib/sqlite.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Runtime-aware compatibility shim for SQLite.
+ *
+ * Picks `bun:sqlite` under Bun and `node:sqlite` under Node (>=22.5). Avoids
+ * the native `better-sqlite3` addon entirely so there is no prebuild compile
+ * and no Node/Bun ABI mismatch when the same source runs in tests (Bun) and
+ * production (Node).
+ *
+ * Exposes the small better-sqlite3-shaped surface area the rest of the
+ * codebase already uses: `prepare/exec/pragma/transaction/close` on the DB,
+ * `run/get/all` on statements.
+ */
+interface NativeStmt {
+    run(...args: unknown[]): RunResult;
+    get(...args: unknown[]): unknown;
+    all(...args: unknown[]): unknown[];
+}
+export interface RunResult {
+    changes: number | bigint;
+    lastInsertRowid: number | bigint;
+}
+declare class StatementImpl<_T = unknown> {
+    private readonly inner;
+    constructor(inner: NativeStmt);
+    run(...params: unknown[]): RunResult;
+    get(...params: unknown[]): unknown;
+    all(...params: unknown[]): unknown[];
+}
+declare class Database {
+    private readonly inner;
+    constructor(filename: string);
+    prepare<T = unknown>(sql: string): StatementImpl<T>;
+    exec(sql: string): void;
+    pragma(stmt: string): void;
+    transaction<Args extends unknown[], R>(fn: (...args: Args) => R): (...args: Args) => R;
+    close(): void;
+}
+declare namespace Database {
+    type Database = InstanceType<typeof DatabaseConstructor>;
+    type Statement<T = unknown> = StatementImpl<T>;
+}
+declare const DatabaseConstructor: typeof Database;
+export default Database;

package/dist/lib/sqlite.js

@@ -0,0 +1,94 @@
+/**
+ * Runtime-aware compatibility shim for SQLite.
+ *
+ * Picks `bun:sqlite` under Bun and `node:sqlite` under Node (>=22.5). Avoids
+ * the native `better-sqlite3` addon entirely so there is no prebuild compile
+ * and no Node/Bun ABI mismatch when the same source runs in tests (Bun) and
+ * production (Node).
+ *
+ * Exposes the small better-sqlite3-shaped surface area the rest of the
+ * codebase already uses: `prepare/exec/pragma/transaction/close` on the DB,
+ * `run/get/all` on statements.
+ */
+import { createRequire } from 'module';
+const isBun = typeof globalThis.Bun !== 'undefined';
+const require = createRequire(import.meta.url);
+// Keep Node on createRequire() so Vitest doesn't try to prebundle the built-in
+// sqlite module as a userland package during test collection.
+const sqliteMod = isBun
+    ? await import('bun:sqlite')
+    : require('node:sqlite');
+// bun:sqlite exports `Database`; node:sqlite exports `DatabaseSync`.
+const NativeDatabase = sqliteMod.Database
+    ?? sqliteMod.DatabaseSync;
+function bindArgs(params) {
+    // Both bindings accept positional `(a, b, c)` and named `({ a, b, c })`
+    // forms. Pass an object through unchanged so callers using named binds work.
+    if (params.length === 1 &&
+        params[0] !== null &&
+        typeof params[0] === 'object' &&
+        !Array.isArray(params[0])) {
+        return [params[0]];
+    }
+    return params;
+}
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+class StatementImpl {
+    inner;
+    constructor(inner) {
+        this.inner = inner;
+    }
+    run(...params) {
+        return this.inner.run(...bindArgs(params));
+    }
+    get(...params) {
+        return this.inner.get(...bindArgs(params));
+    }
+    all(...params) {
+        return this.inner.all(...bindArgs(params));
+    }
+}
+class Database {
+    inner;
+    constructor(filename) {
+        this.inner = new NativeDatabase(filename);
+    }
+    prepare(sql) {
+        return new StatementImpl(this.inner.prepare(sql));
+    }
+    exec(sql) {
+        this.inner.exec(sql);
+    }
+    // node:sqlite has no dedicated `pragma()` and bun:sqlite's signature differs
+    // slightly from better-sqlite3. `exec('PRAGMA ...')` works on both and is
+    // sufficient for the setter pragmas (`journal_mode = WAL`) used here.
+    // Reader pragmas in this codebase use `db.prepare(...).all()`.
+    pragma(stmt) {
+        this.inner.exec(`PRAGMA ${stmt}`);
+    }
+    // Wrap fn in BEGIN/COMMIT, ROLLBACK on throw. Manual on both runtimes
+    // because node:sqlite has no `db.transaction(fn)` and the manual form is
+    // identical in shape to what better-sqlite3 / bun:sqlite produce.
+    transaction(fn) {
+        return (...args) => {
+            this.inner.exec('BEGIN');
+            try {
+                const result = fn(...args);
+                this.inner.exec('COMMIT');
+                return result;
+            }
+            catch (err) {
+                try {
+                    this.inner.exec('ROLLBACK');
+                }
+                catch { /* original error wins */ }
+                throw err;
+            }
+        };
+    }
+    close() {
+        this.inner.close();
+    }
+}
+const DatabaseConstructor = Database;
+export default Database;

package/dist/lib/state.d.ts

@@ -1,46 +1,138 @@
+/**
+ * Filesystem layout and persistent state for agents-cli.
+ *
+ * Two roots:
+ *  - ~/.agents-system/ — system repo (npm-shipped resources, versions, shims, backups, runs)
+ *  - ~/.agents/        — user repo  (user-authored commands, skills, hooks, rules, mcp,
+ *                                    permissions, subagents, profiles, secrets, agents.yaml)
+ *
+ * Resolution precedence for resources: project > user > system.
+ * Every module that needs a path or reads/writes agents.yaml goes through here.
+ */
 import type { Meta } from './types.js';
+/** Root of the system data directory (~/.agents-system/). Legacy alias — prefer getSystemAgentsDir(). */
 export declare function getAgentsDir(): string;
+/** Root of the system data directory (~/.agents-system/). */
+export declare function getSystemAgentsDir(): string;
+/** Root of the user repo (~/.agents/). Always present after ensureAgentsDir(). */
+export declare function getUserAgentsDir(): string;
+/**
+ * Backward-compat shim. Returns null when ~/.agents/ is a symlink to the
+ * system dir; otherwise returns USER_AGENTS_DIR.
+ *
+ * @deprecated Use getUserAgentsDir() directly.
+ */
+export declare function getOptionalUserAgentsDir(): string | null;
+/** Walk up from startPath to find a project-scoped .agents/ directory (skipping both roots). */
 export declare function getProjectAgentsDir(startPath?: string): string | null;
+/** Return all .agents/ directories in scope: project, user, then system. */
 export declare function getScopedAgentsDirs(startPath?: string): Array<{
-    scope: 'project' | 'user';
+    scope: 'project' | 'user' | 'system';
     path: string;
 }>;
+/** Path to slash command markdown files — system repo. */
+export declare function getCommandsDir(): string;
+/** Path to hook script directories — system repo. */
+export declare function getHooksDir(): string;
+/** Path to skill bundles — system repo. */
+export declare function getSkillsDir(): string;
+/** Path to the canonical rules directory — system repo. */
+export declare function getRulesDir(): string;
+/** Back-compat export; resolves to system rules dir. */
+export declare function getMemoryDir(): string;
+/**
+ * Read-side resolution for the canonical rules dir.
+ *
+ * Returns SYSTEM_RULES_DIR normally. Falls back to the legacy
+ * SYSTEM_LEGACY_MEMORY_DIR (~/.agents-system/memory/) only when the upstream
+ * still uses the old layout and the user hasn't pulled the rename yet —
+ * detected by absence of rules/AGENTS.md and presence of memory/AGENTS.md.
+ *
+ * Prints a single warning per process the first time the fallback fires.
+ * Per the read-only system-repo invariant, this never moves files; the rename
+ * is applied when the user pulls upstream.
+ */
+export declare function getResolvedRulesDir(): string;
+/** Path to MCP server YAML configs — system repo. */
+export declare function getMcpDir(): string;
+/** Path to permission group YAML files — system repo. */
+export declare function getPermissionsDir(): string;
+/** Path to subagent definition directories — system repo. */
+export declare function getSubagentsDir(): string;
+/** Path to encrypted secret bundles — system repo. */
+export declare function getSecretsDir(): string;
+/** Path to ~/.agents-system/promptcuts.yaml. */
+export declare function getPromptcutsPath(): string;
+/** Path to the legacy MCP config JSON. */
+export declare function getMcpConfigPath(): string;
+/** Path to the global instructions file. */
+export declare function getInstructionsPath(): string;
+export declare function getSystemCommandsDir(): string;
+export declare function getSystemHooksDir(): string;
+export declare function getSystemSkillsDir(): string;
+export declare function getSystemRulesDir(): string;
+export declare function getSystemMcpDir(): string;
+export declare function getSystemPermissionsDir(): string;
+export declare function getSystemSubagentsDir(): string;
+export declare function getSystemSecretsDir(): string;
+export declare function getSystemPromptcutsPath(): string;
+export declare function getUserCommandsDir(): string;
+export declare function getUserHooksDir(): string;
+export declare function getUserSkillsDir(): string;
+export declare function getUserRulesDir(): string;
+export declare function getUserMcpDir(): string;
+export declare function getUserPermissionsDir(): string;
+export declare function getUserSubagentsDir(): string;
+export declare function getUserSecretsDir(): string;
+export declare function getUserPromptcutsPath(): string;
+/** Path to cloned packages (~/.agents-system/packages/). */
 export declare function getPackagesDir(): string;
+/** Path to routine YAML definitions (~/.agents-system/routines/). */
 export declare function getRoutinesDir(): string;
+/** Path to routine execution logs (~/.agents-system/runs/). */
 export declare function getRunsDir(): string;
+/** Path to installed agent CLI binaries (~/.agents-system/versions/). */
 export declare function getVersionsDir(): string;
+/** Path to version-switching shim scripts (~/.agents-system/shims/). */
 export declare function getShimsDir(): string;
-export declare function getPermissionsDir(): string;
-export declare function getMcpDir(): string;
+/** Path to config backups (~/.agents-system/backups/). */
 export declare function getBackupsDir(): string;
-export declare function getSubagentsDir(): string;
+/** Path to plugin bundles (~/.agents-system/plugins/). */
 export declare function getPluginsDir(): string;
+/** Path to synced remote session data (~/.agents-system/drive/). */
 export declare function getDriveDir(): string;
-export declare function getCommandsDir(): string;
-export declare function getHooksDir(): string;
-export declare function getSkillsDir(): string;
-export declare function getMemoryDir(): string;
-export declare function getInstructionsPath(): string;
-export declare function getMcpConfigPath(): string;
+/**
+ * Path to a single user-level extra DotAgent repo clone (~/.agents-<alias>/).
+ *
+ * Extra repos are user-defined config — they live as peer dirs to ~/.agents/,
+ * not under the system repo. `agents repo add` clones here by default.
+ */
+export declare function getExtraRepoDir(alias: string): string;
+/** Resolve the on-disk path for an extra repo, whether managed or user-owned. */
+export declare function resolveExtraRepoDir(alias: string, config?: {
+    path?: string;
+}): string;
+/**
+ * Return enabled extra repos that exist on disk, in insertion order.
+ */
+export declare function getEnabledExtraRepos(): Array<{
+    alias: string;
+    dir: string;
+    url: string;
+}>;
+/** Create both the system and user directory trees if any subdirectories are missing. */
 export declare function ensureAgentsDir(): void;
+/** Return an empty Meta object used when no agents.yaml exists yet. */
 export declare function createDefaultMeta(): Meta;
+/** Read and cache ~/.agents/agents.yaml, migrating from legacy locations if needed. */
 export declare function readMeta(): Meta;
+/** Serialize and write agents.yaml to the user repo, invalidating the in-memory cache. */
 export declare function writeMeta(meta: Meta): void;
+/** Shallow-merge updates into agents.yaml and return the new state. */
 export declare function updateMeta(updates: Partial<Meta>): Meta;
+/** Derive a filesystem-safe local clone path for a package source URL. */
 export declare function getPackageLocalPath(source: string): string;
 import type { AgentId, ResourceType, VersionResources } from './types.js';
-/**
- * Record that resources were synced to a specific version.
- * Creates nested entries if they don't exist (handles existing installs gracefully).
- * Merges with existing resources (uses Set for deduplication).
- */
 export declare function recordVersionResources(agent: AgentId, version: string, resourceType: ResourceType, resources: string[]): void;
-/**
- * Get tracked resources for a specific version.
- */
 export declare function getVersionResources(agent: AgentId, version: string): VersionResources | null;
-/**
- * Clear resource tracking when a version is removed.
- */
 export declare function clearVersionResources(agent: AgentId, version: string): void;
-//# sourceMappingURL=state.d.ts.map