@cleocode/caamp 0.1.0 → 0.3.0

package/dist/index.d.ts

@@ -2,157 +2,584 @@
  * CAAMP - Central AI Agent Managed Packages
  * Core type definitions
  */
+/**
+ * Supported configuration file formats.
+ *
+ * - `"json"` - Standard JSON
+ * - `"jsonc"` - JSON with comments (comment-preserving via jsonc-parser)
+ * - `"yaml"` - YAML (via js-yaml)
+ * - `"toml"` - TOML (via @iarna/toml)
+ *
+ * @example
+ * ```typescript
+ * const format: ConfigFormat = "jsonc";
+ * ```
+ */
 type ConfigFormat = "json" | "jsonc" | "yaml" | "toml";
+/**
+ * MCP server transport protocol type.
+ *
+ * - `"stdio"` - Standard input/output (local process)
+ * - `"sse"` - Server-Sent Events (remote)
+ * - `"http"` - HTTP/Streamable HTTP (remote)
+ *
+ * @example
+ * ```typescript
+ * const transport: TransportType = "stdio";
+ * ```
+ */
 type TransportType = "stdio" | "sse" | "http";
+/**
+ * Method used to detect whether an AI agent is installed on the system.
+ *
+ * - `"binary"` - Check if a CLI binary exists on PATH
+ * - `"directory"` - Check if known config/data directories exist
+ * - `"appBundle"` - Check for macOS .app bundle in /Applications
+ * - `"flatpak"` - Check for Flatpak installation on Linux
+ */
 type DetectionMethod = "binary" | "directory" | "appBundle" | "flatpak";
+/**
+ * Configuration for detecting whether a provider is installed.
+ *
+ * @example
+ * ```typescript
+ * const config: DetectionConfig = {
+ *   methods: ["binary", "directory"],
+ *   binary: "claude",
+ *   directories: ["~/.config/claude"],
+ * };
+ * ```
+ */
 interface DetectionConfig {
+    /** Detection methods to try, in order. */
     methods: DetectionMethod[];
+    /** Binary name to look up on PATH (for `"binary"` method). */
     binary?: string;
+    /** Directories to check for existence (for `"directory"` method). */
     directories?: string[];
+    /** macOS .app bundle name (for `"appBundle"` method). */
     appBundle?: string;
+    /** Flatpak application ID (for `"flatpak"` method). */
     flatpakId?: string;
 }
+/**
+ * Priority tier for a provider, used for sorting and default selection.
+ *
+ * - `"high"` - Major, widely-used agents
+ * - `"medium"` - Established but less common agents
+ * - `"low"` - Niche or experimental agents
+ */
 type ProviderPriority = "high" | "medium" | "low";
+/**
+ * Lifecycle status of a provider in the registry.
+ *
+ * - `"active"` - Fully supported
+ * - `"beta"` - Supported but may have rough edges
+ * - `"deprecated"` - Still present but no longer recommended
+ * - `"planned"` - Not yet implemented
+ */
 type ProviderStatus = "active" | "beta" | "deprecated" | "planned";
+/**
+ * A resolved AI agent provider definition with platform-specific paths.
+ *
+ * Providers are loaded from `providers/registry.json` and resolved at runtime
+ * to expand platform-specific path variables (`$HOME`, `$CONFIG`, etc.).
+ *
+ * @example
+ * ```typescript
+ * const provider = getProvider("claude-code");
+ * if (provider) {
+ *   console.log(provider.configPathGlobal);
+ * }
+ * ```
+ */
 interface Provider {
+    /** Unique provider identifier (e.g. `"claude-code"`). */
     id: string;
+    /** Human-readable tool name (e.g. `"Claude Code"`). */
     toolName: string;
+    /** Vendor/company name (e.g. `"Anthropic"`). */
     vendor: string;
+    /** CLI flag name for `--agent` selection. */
     agentFlag: string;
+    /** Alternative names that resolve to this provider. */
     aliases: string[];
+    /** Resolved global instruction file directory path. */
     pathGlobal: string;
+    /** Project-relative instruction file directory path. */
     pathProject: string;
+    /** Instruction file name (e.g. `"CLAUDE.md"`, `"AGENTS.md"`). */
     instructFile: string;
+    /** Dot-notation key path for MCP server config (e.g. `"mcpServers"`). */
     configKey: string;
+    /** Config file format used by this provider. */
     configFormat: ConfigFormat;
+    /** Resolved global config file path. */
     configPathGlobal: string;
+    /** Project-relative config file path, or `null` if unsupported. */
     configPathProject: string | null;
+    /** Resolved global skills directory path. */
     pathSkills: string;
+    /** Project-relative skills directory path. */
     pathProjectSkills: string;
+    /** Detection configuration for auto-discovering this provider. */
     detection: DetectionConfig;
+    /** MCP transport protocols this provider supports. */
     supportedTransports: TransportType[];
+    /** Whether the provider supports custom HTTP headers for remote MCP servers. */
     supportsHeaders: boolean;
+    /** Priority tier for sorting and default selection. */
     priority: ProviderPriority;
+    /** Lifecycle status in the registry. */
     status: ProviderStatus;
+    /** Whether the provider is compatible with the Agent Skills standard. */
     agentSkillsCompatible: boolean;
 }
+/**
+ * Canonical MCP server configuration.
+ *
+ * Represents either a remote server (via `url`) or a local stdio process
+ * (via `command` + `args`). This canonical format is transformed to
+ * provider-specific shapes before writing to config files.
+ *
+ * @example
+ * ```typescript
+ * // Remote server
+ * const remote: McpServerConfig = {
+ *   type: "http",
+ *   url: "https://mcp.example.com/sse",
+ * };
+ *
+ * // Local stdio server
+ * const local: McpServerConfig = {
+ *   command: "npx",
+ *   args: ["-y", "@modelcontextprotocol/server-filesystem"],
+ * };
+ * ```
+ */
 interface McpServerConfig {
+    /** Transport type (`"stdio"`, `"sse"`, or `"http"`). */
     type?: TransportType;
+    /** URL for remote MCP servers. */
     url?: string;
+    /** HTTP headers for remote MCP servers. */
     headers?: Record<string, string>;
+    /** Command to run for stdio MCP servers. */
     command?: string;
+    /** Arguments for the stdio command. */
     args?: string[];
+    /** Environment variables for the stdio process. */
     env?: Record<string, string>;
 }
+/**
+ * Classified type of an MCP server or skill source.
+ *
+ * - `"remote"` - HTTP/HTTPS URL to a remote MCP server
+ * - `"package"` - npm package name
+ * - `"command"` - Shell command string
+ * - `"github"` - GitHub repository (URL or shorthand)
+ * - `"gitlab"` - GitLab repository URL
+ * - `"local"` - Local filesystem path
+ */
 type SourceType = "remote" | "package" | "command" | "github" | "gitlab" | "local";
+/**
+ * Result of parsing a source string into its typed components.
+ *
+ * @example
+ * ```typescript
+ * const parsed: ParsedSource = {
+ *   type: "github",
+ *   value: "https://github.com/owner/repo",
+ *   inferredName: "repo",
+ *   owner: "owner",
+ *   repo: "repo",
+ * };
+ * ```
+ */
 interface ParsedSource {
+    /** Classified source type. */
     type: SourceType;
+    /** Original or normalized source value. */
     value: string;
+    /** Display name inferred from the source. */
     inferredName: string;
+    /** Repository owner (for GitHub/GitLab sources). */
     owner?: string;
+    /** Repository name (for GitHub/GitLab sources). */
     repo?: string;
+    /** Path within the repository (for GitHub/GitLab sources). */
     path?: string;
+    /** Git ref / branch / tag (for GitHub/GitLab sources). */
     ref?: string;
 }
+/**
+ * Metadata extracted from a SKILL.md frontmatter.
+ *
+ * @example
+ * ```typescript
+ * const meta: SkillMetadata = {
+ *   name: "my-skill",
+ *   description: "A useful skill for code generation",
+ *   version: "1.0.0",
+ * };
+ * ```
+ */
 interface SkillMetadata {
+    /** Skill name (lowercase, hyphens only). */
     name: string;
+    /** Human-readable description. */
     description: string;
+    /** SPDX license identifier. */
     license?: string;
+    /** Compatibility notes (e.g. agent versions). */
     compatibility?: string;
+    /** Arbitrary key-value metadata. */
     metadata?: Record<string, string>;
+    /** List of tools the skill is allowed to use. */
     allowedTools?: string[];
+    /** Semantic version string. */
     version?: string;
 }
+/**
+ * A discovered skill entry with its location and metadata.
+ *
+ * @example
+ * ```typescript
+ * const entry: SkillEntry = {
+ *   name: "my-skill",
+ *   scopedName: "my-skill",
+ *   path: "/home/user/.agents/skills/my-skill",
+ *   metadata: { name: "my-skill", description: "A skill" },
+ * };
+ * ```
+ */
 interface SkillEntry {
+    /** Skill name. */
     name: string;
+    /** Scoped name (may include marketplace scope). */
     scopedName: string;
+    /** Absolute path to the skill directory. */
     path: string;
+    /** Parsed SKILL.md frontmatter metadata. */
     metadata: SkillMetadata;
+    /** Original source from which the skill was installed. */
     source?: string;
 }
+/**
+ * A single entry in the CAAMP lock file tracking an installed skill or MCP server.
+ *
+ * @example
+ * ```typescript
+ * const entry: LockEntry = {
+ *   name: "my-skill",
+ *   scopedName: "my-skill",
+ *   source: "https://github.com/owner/repo",
+ *   sourceType: "github",
+ *   installedAt: "2025-01-15T10:30:00.000Z",
+ *   agents: ["claude-code", "cursor"],
+ *   canonicalPath: "/home/user/.agents/skills/my-skill",
+ *   isGlobal: true,
+ * };
+ * ```
+ */
 interface LockEntry {
+    /** Skill or server name. */
     name: string;
+    /** Scoped name (may include marketplace scope). */
     scopedName: string;
+    /** Original source string. */
     source: string;
+    /** Classified source type. */
     sourceType: SourceType;
+    /** Version string or commit SHA. */
     version?: string;
+    /** ISO 8601 timestamp of first installation. */
     installedAt: string;
+    /** ISO 8601 timestamp of last update. */
     updatedAt?: string;
+    /** Provider IDs this entry is linked to. */
     agents: string[];
+    /** Absolute path to canonical installation. */
     canonicalPath: string;
+    /** Whether this was installed globally. */
     isGlobal: boolean;
+    /** Project directory (for project-scoped installs). */
     projectDir?: string;
 }
+/**
+ * The CAAMP lock file structure, stored at `~/.agents/.caamp-lock.json`.
+ *
+ * Tracks all installed skills and MCP servers along with their sources,
+ * versions, and linked agents.
+ *
+ * @example
+ * ```typescript
+ * const lock: CaampLockFile = {
+ *   version: 1,
+ *   skills: {},
+ *   mcpServers: {},
+ *   lastSelectedAgents: ["claude-code"],
+ * };
+ * ```
+ */
 interface CaampLockFile {
+    /** Lock file schema version. */
     version: 1;
+    /** Installed skills keyed by name. */
     skills: Record<string, LockEntry>;
+    /** Installed MCP servers keyed by name. */
     mcpServers: Record<string, LockEntry>;
+    /** Last selected agent IDs for UX persistence. */
     lastSelectedAgents?: string[];
 }
+/**
+ * A skill listing from a marketplace search result.
+ *
+ * @example
+ * ```typescript
+ * const skill: MarketplaceSkill = {
+ *   id: "abc123",
+ *   name: "my-skill",
+ *   scopedName: "@author/my-skill",
+ *   description: "A useful skill",
+ *   author: "author",
+ *   stars: 42,
+ *   forks: 5,
+ *   githubUrl: "https://github.com/author/my-skill",
+ *   repoFullName: "author/my-skill",
+ *   path: "/",
+ *   hasContent: true,
+ * };
+ * ```
+ */
 interface MarketplaceSkill {
+    /** Unique marketplace identifier. */
     id: string;
+    /** Skill name. */
     name: string;
+    /** Scoped name (e.g. `"@author/my-skill"`). */
     scopedName: string;
+    /** Short description. */
     description: string;
+    /** Author / publisher name. */
     author: string;
+    /** GitHub star count. */
     stars: number;
+    /** GitHub fork count. */
     forks: number;
+    /** GitHub repository URL. */
     githubUrl: string;
+    /** Full `owner/repo` name. */
     repoFullName: string;
+    /** Path within the repository. */
     path: string;
+    /** Optional category tag. */
     category?: string;
+    /** Whether SKILL.md content was fetched. */
     hasContent: boolean;
 }
+/**
+ * Paginated search results from a marketplace API.
+ *
+ * @example
+ * ```typescript
+ * const result: MarketplaceSearchResult = {
+ *   skills: [],
+ *   total: 0,
+ *   limit: 20,
+ *   offset: 0,
+ * };
+ * ```
+ */
 interface MarketplaceSearchResult {
+    /** Array of matching skills. */
     skills: MarketplaceSkill[];
+    /** Total number of matching results. */
     total: number;
+    /** Maximum results per page. */
     limit: number;
+    /** Offset into the result set. */
     offset: number;
 }
+/**
+ * Severity level for a security audit finding.
+ *
+ * Ordered from most to least severe: `"critical"` > `"high"` > `"medium"` > `"low"` > `"info"`.
+ */
 type AuditSeverity = "critical" | "high" | "medium" | "low" | "info";
+/**
+ * A security audit rule definition with a regex pattern to match against skill content.
+ *
+ * @example
+ * ```typescript
+ * const rule: AuditRule = {
+ *   id: "SEC001",
+ *   name: "shell-injection",
+ *   description: "Potential shell injection vector",
+ *   severity: "critical",
+ *   category: "injection",
+ *   pattern: /rm\s+-rf\s+\//,
+ * };
+ * ```
+ */
 interface AuditRule {
+    /** Unique rule identifier (e.g. `"SEC001"`). */
     id: string;
+    /** Rule name. */
     name: string;
+    /** Human-readable description of what the rule detects. */
     description: string;
+    /** Severity level of findings from this rule. */
     severity: AuditSeverity;
+    /** Category grouping (e.g. `"injection"`, `"exfiltration"`). */
     category: string;
+    /** Regex pattern to match against each line of content. */
     pattern: RegExp;
 }
+/**
+ * A single finding from a security audit scan, with line-level location.
+ *
+ * @example
+ * ```typescript
+ * const finding: AuditFinding = {
+ *   rule: myRule,
+ *   line: 42,
+ *   column: 10,
+ *   match: "rm -rf /",
+ *   context: "Execute: rm -rf / to clean up",
+ * };
+ * ```
+ */
 interface AuditFinding {
+    /** The rule that triggered this finding. */
     rule: AuditRule;
+    /** Line number (1-based). */
     line: number;
+    /** Column number (1-based). */
     column: number;
+    /** The matched text. */
     match: string;
+    /** The full line of text for context. */
     context: string;
 }
+/**
+ * Aggregate audit result for a single file.
+ *
+ * Includes a security score (100 = clean, 0 = very dangerous) and a pass/fail
+ * status based on the presence of critical or high severity findings.
+ *
+ * @example
+ * ```typescript
+ * const result: AuditResult = {
+ *   file: "/path/to/SKILL.md",
+ *   findings: [],
+ *   score: 100,
+ *   passed: true,
+ * };
+ * ```
+ */
 interface AuditResult {
+    /** Path to the scanned file. */
     file: string;
+    /** All findings for this file. */
     findings: AuditFinding[];
+    /** Security score from 0 (dangerous) to 100 (clean). */
     score: number;
+    /** Whether the file passed the audit (no critical/high findings). */
     passed: boolean;
 }
+/**
+ * Status of a CAAMP injection block in an instruction file.
+ *
+ * - `"current"` - Injection block exists and matches expected content
+ * - `"outdated"` - Injection block exists but content differs
+ * - `"missing"` - Instruction file does not exist
+ * - `"none"` - File exists but has no CAAMP injection block
+ */
 type InjectionStatus = "current" | "outdated" | "missing" | "none";
+/**
+ * Result of checking a single instruction file for CAAMP injection status.
+ *
+ * @example
+ * ```typescript
+ * const check: InjectionCheckResult = {
+ *   file: "/project/CLAUDE.md",
+ *   provider: "claude-code",
+ *   status: "current",
+ *   fileExists: true,
+ * };
+ * ```
+ */
 interface InjectionCheckResult {
+    /** Absolute path to the instruction file. */
     file: string;
+    /** Provider ID that owns this instruction file. */
     provider: string;
+    /** Current injection status. */
     status: InjectionStatus;
+    /** Whether the instruction file exists on disk. */
     fileExists: boolean;
 }
+/**
+ * An MCP server entry read from a provider's config file.
+ *
+ * Returned by {@link listMcpServers} and {@link listAllMcpServers}.
+ *
+ * @example
+ * ```typescript
+ * const entry: McpServerEntry = {
+ *   name: "filesystem",
+ *   providerId: "claude-code",
+ *   providerName: "Claude Code",
+ *   scope: "project",
+ *   configPath: "/project/.claude/settings.json",
+ *   config: { command: "npx", args: ["-y", "@mcp/server-filesystem"] },
+ * };
+ * ```
+ */
 interface McpServerEntry {
+    /** Server name (the key in the config file). */
     name: string;
+    /** Provider ID that owns this config file. */
     providerId: string;
+    /** Human-readable provider name. */
     providerName: string;
+    /** Whether from project or global config. */
     scope: "project" | "global";
+    /** Absolute path to the config file. */
     configPath: string;
+    /** Raw server configuration object. */
     config: Record<string, unknown>;
 }
+/**
+ * Global CLI options shared across all CAAMP commands.
+ *
+ * @example
+ * ```typescript
+ * const opts: GlobalOptions = {
+ *   agent: ["claude-code", "cursor"],
+ *   global: true,
+ *   json: true,
+ * };
+ * ```
+ */
 interface GlobalOptions {
+    /** Target agent IDs (repeatable). */
     agent?: string[];
+    /** Operate on global config instead of project. */
     global?: boolean;
+    /** Skip confirmation prompts. */
     yes?: boolean;
+    /** Target all detected agents. */
     all?: boolean;
+    /** Output as JSON. */
     json?: boolean;
+    /** Preview changes without writing. */
     dryRun?: boolean;
+    /** Enable debug logging. */
+    verbose?: boolean;
+    /** Suppress non-error output. */
+    quiet?: boolean;
 }
 
 /**
@@ -162,19 +589,95 @@ interface GlobalOptions {
  * by checking binaries, directories, app bundles, and flatpak.
  */
 
+/**
+ * Result of detecting whether a provider is installed on the system.
+ *
+ * @example
+ * ```typescript
+ * const result = detectProvider(provider);
+ * if (result.installed) {
+ *   console.log(`Found via: ${result.methods.join(", ")}`);
+ * }
+ * ```
+ */
 interface DetectionResult {
+    /** The provider that was checked. */
     provider: Provider;
+    /** Whether the provider was detected as installed. */
     installed: boolean;
+    /** Detection methods that matched (e.g. `["binary", "directory"]`). */
     methods: string[];
+    /** Whether the provider has project-level config in the current directory. */
     projectDetected: boolean;
 }
-/** Detect if a single provider is installed */
+/**
+ * Detect if a single provider is installed on the system.
+ *
+ * Checks each detection method configured for the provider (binary, directory,
+ * appBundle, flatpak) and returns which methods matched.
+ *
+ * @param provider - The provider to detect
+ * @returns Detection result with installation status and matched methods
+ *
+ * @example
+ * ```typescript
+ * const provider = getProvider("claude-code")!;
+ * const result = detectProvider(provider);
+ * if (result.installed) {
+ *   console.log(`Claude Code found via: ${result.methods.join(", ")}`);
+ * }
+ * ```
+ */
 declare function detectProvider(provider: Provider): DetectionResult;
-/** Detect all installed providers */
+/**
+ * Detect all registered providers and return their installation status.
+ *
+ * Runs detection for every provider in the registry.
+ *
+ * @returns Array of detection results for all providers
+ *
+ * @example
+ * ```typescript
+ * const results = detectAllProviders();
+ * const installed = results.filter(r => r.installed);
+ * console.log(`${installed.length} agents detected`);
+ * ```
+ */
 declare function detectAllProviders(): DetectionResult[];
-/** Get only installed providers */
+/**
+ * Get only providers that are currently installed on the system.
+ *
+ * Convenience wrapper that filters {@link detectAllProviders} results to only
+ * those with `installed === true`.
+ *
+ * @returns Array of installed provider definitions
+ *
+ * @example
+ * ```typescript
+ * const installed = getInstalledProviders();
+ * console.log(installed.map(p => p.toolName).join(", "));
+ * ```
+ */
 declare function getInstalledProviders(): Provider[];
-/** Detect providers with project-level presence */
+/**
+ * Detect all providers and enrich results with project-level presence.
+ *
+ * Extends {@link detectAllProviders} by also checking whether each provider
+ * has a project-level config file in the given directory.
+ *
+ * @param projectDir - Absolute path to the project directory to check
+ * @returns Array of detection results with `projectDetected` populated
+ *
+ * @example
+ * ```typescript
+ * const results = detectProjectProviders("/home/user/my-project");
+ * for (const r of results) {
+ *   if (r.projectDetected) {
+ *     console.log(`${r.provider.toolName} has project config`);
+ *   }
+ * }
+ * ```
+ */
 declare function detectProjectProviders(projectDir: string): DetectionResult[];
 
 /**
@@ -184,18 +687,94 @@ declare function detectProjectProviders(projectDir: string): DetectionResult[];
  * handling per-agent formats, keys, and transformations.
  */
 
+/**
+ * Result of installing an MCP server configuration to a single provider.
+ *
+ * @example
+ * ```typescript
+ * const result = await installMcpServer(provider, "my-server", config);
+ * if (result.success) {
+ *   console.log(`Written to ${result.configPath}`);
+ * }
+ * ```
+ */
 interface InstallResult {
+    /** The provider the config was written to. */
     provider: Provider;
+    /** Whether project or global scope was used. */
     scope: "project" | "global";
+    /** Absolute path to the config file that was written. */
     configPath: string;
+    /** Whether the write succeeded. */
     success: boolean;
+    /** Error message if the write failed. */
     error?: string;
 }
-/** Install an MCP server config for a single provider */
+/**
+ * Install an MCP server configuration for a single provider.
+ *
+ * Applies provider-specific transforms (e.g. Goose, Zed, Codex) and writes
+ * the config to the provider's config file in the specified scope.
+ *
+ * @param provider - Target provider to write config for
+ * @param serverName - Name/key for the MCP server entry
+ * @param config - Canonical MCP server configuration
+ * @param scope - Whether to write to project or global config (default: `"project"`)
+ * @param projectDir - Project directory path (defaults to `process.cwd()`)
+ * @returns Install result with success status and config path
+ *
+ * @example
+ * ```typescript
+ * const provider = getProvider("claude-code")!;
+ * const result = await installMcpServer(provider, "filesystem", {
+ *   command: "npx",
+ *   args: ["-y", "@modelcontextprotocol/server-filesystem"],
+ * });
+ * ```
+ */
 declare function installMcpServer(provider: Provider, serverName: string, config: McpServerConfig, scope?: "project" | "global", projectDir?: string): Promise<InstallResult>;
-/** Install an MCP server config for multiple providers */
+/**
+ * Install an MCP server configuration to multiple providers.
+ *
+ * Calls {@link installMcpServer} for each provider sequentially and collects results.
+ *
+ * @param providers - Array of target providers
+ * @param serverName - Name/key for the MCP server entry
+ * @param config - Canonical MCP server configuration
+ * @param scope - Whether to write to project or global config (default: `"project"`)
+ * @param projectDir - Project directory path (defaults to `process.cwd()`)
+ * @returns Array of install results, one per provider
+ *
+ * @example
+ * ```typescript
+ * const providers = getInstalledProviders();
+ * const results = await installMcpServerToAll(providers, "my-server", config);
+ * const successes = results.filter(r => r.success);
+ * ```
+ */
 declare function installMcpServerToAll(providers: Provider[], serverName: string, config: McpServerConfig, scope?: "project" | "global", projectDir?: string): Promise<InstallResult[]>;
-/** Build a canonical MCP server config from parsed source */
+/**
+ * Build a canonical {@link McpServerConfig} from a parsed source.
+ *
+ * Maps source types to appropriate transport configurations:
+ * - `"remote"` sources become HTTP/SSE configs with a `url`
+ * - `"package"` sources become `npx -y <package>` stdio configs
+ * - All others are treated as shell commands split into `command` + `args`
+ *
+ * @param source - Parsed source with `type` and `value`
+ * @param transport - Override transport type for remote sources (default: `"http"`)
+ * @param headers - Optional HTTP headers for remote servers
+ * @returns Canonical MCP server configuration
+ *
+ * @example
+ * ```typescript
+ * buildServerConfig({ type: "package", value: "@mcp/server-fs" });
+ * // { command: "npx", args: ["-y", "@mcp/server-fs"] }
+ *
+ * buildServerConfig({ type: "remote", value: "https://mcp.example.com" });
+ * // { type: "http", url: "https://mcp.example.com" }
+ * ```
+ */
 declare function buildServerConfig(source: {
     type: string;
     value: string;
@@ -208,21 +787,83 @@ declare function buildServerConfig(source: {
  * and symlinked to each target agent's skills directory.
  */
 
+/**
+ * Result of installing a skill to the canonical location and linking to agents.
+ *
+ * @example
+ * ```typescript
+ * const result = await installSkill(sourcePath, "my-skill", providers, true);
+ * if (result.success) {
+ *   console.log(`Installed to ${result.canonicalPath}`);
+ *   console.log(`Linked to: ${result.linkedAgents.join(", ")}`);
+ * }
+ * ```
+ */
 interface SkillInstallResult {
+    /** Skill name. */
     name: string;
+    /** Absolute path to the canonical installation directory. */
     canonicalPath: string;
+    /** Provider IDs that were successfully linked. */
     linkedAgents: string[];
+    /** Error messages from failed link operations. */
     errors: string[];
+    /** Whether at least one agent was successfully linked. */
     success: boolean;
 }
-/** Install a skill from a local path to canonical + link to agents */
+/**
+ * Install a skill from a local path to the canonical location and link to agents.
+ *
+ * Copies the skill directory to `~/.agents/skills/<name>/` and creates symlinks
+ * (or copies on Windows) from each provider's skills directory to the canonical path.
+ *
+ * @param sourcePath - Local path to the skill directory to install
+ * @param skillName - Name for the installed skill
+ * @param providers - Target providers to link the skill to
+ * @param isGlobal - Whether to link to global or project skill directories
+ * @param projectDir - Project directory (defaults to `process.cwd()`)
+ * @returns Install result with linked agents and any errors
+ *
+ * @example
+ * ```typescript
+ * const result = await installSkill("/tmp/my-skill", "my-skill", providers, true);
+ * ```
+ */
 declare function installSkill(sourcePath: string, skillName: string, providers: Provider[], isGlobal: boolean, projectDir?: string): Promise<SkillInstallResult>;
-/** Remove a skill from canonical location and all agent symlinks */
+/**
+ * Remove a skill from the canonical location and all agent symlinks.
+ *
+ * Removes symlinks from each provider's skills directory and then removes the
+ * canonical copy from `~/.agents/skills/<name>/`.
+ *
+ * @param skillName - Name of the skill to remove
+ * @param providers - Providers to unlink the skill from
+ * @param isGlobal - Whether to target global or project skill directories
+ * @param projectDir - Project directory (defaults to `process.cwd()`)
+ * @returns Object with arrays of successfully removed provider IDs and error messages
+ *
+ * @example
+ * ```typescript
+ * const { removed, errors } = await removeSkill("my-skill", providers, true);
+ * ```
+ */
 declare function removeSkill(skillName: string, providers: Provider[], isGlobal: boolean, projectDir?: string): Promise<{
     removed: string[];
     errors: string[];
 }>;
-/** List all canonically installed skills */
+/**
+ * List all skills installed in the canonical directory (`~/.agents/skills/`).
+ *
+ * Returns the directory names of all skills, which correspond to skill names.
+ *
+ * @returns Array of skill names
+ *
+ * @example
+ * ```typescript
+ * const skills = await listCanonicalSkills();
+ * // ["my-skill", "another-skill"]
+ * ```
+ */
 declare function listCanonicalSkills(): Promise<string[]>;
 
 /**
@@ -230,17 +871,63 @@ declare function listCanonicalSkills(): Promise<string[]>;
  *
  * Validates skill files against the Agent Skills standard.
  */
+/**
+ * A single validation issue found during SKILL.md validation.
+ *
+ * @example
+ * ```typescript
+ * const issue: ValidationIssue = {
+ *   level: "error",
+ *   field: "name",
+ *   message: "Missing required field: name",
+ * };
+ * ```
+ */
 interface ValidationIssue {
+    /** Severity: `"error"` causes validation failure, `"warning"` does not. */
     level: "error" | "warning";
+    /** The field or section that triggered the issue. */
     field: string;
+    /** Human-readable description of the issue. */
     message: string;
 }
+/**
+ * Result of validating a SKILL.md file against the Agent Skills standard.
+ *
+ * @example
+ * ```typescript
+ * const result = await validateSkill("/path/to/SKILL.md");
+ * if (!result.valid) {
+ *   for (const issue of result.issues) {
+ *     console.log(`[${issue.level}] ${issue.field}: ${issue.message}`);
+ *   }
+ * }
+ * ```
+ */
 interface ValidationResult {
+    /** Whether the skill passed validation (no error-level issues). */
     valid: boolean;
+    /** All issues found during validation. */
     issues: ValidationIssue[];
+    /** Parsed frontmatter metadata, or `null` if parsing failed. */
     metadata: Record<string, unknown> | null;
 }
-/** Validate a SKILL.md file */
+/**
+ * Validate a SKILL.md file against the Agent Skills standard.
+ *
+ * Checks for required frontmatter fields (`name`, `description`), validates
+ * naming conventions, enforces length limits, checks for reserved names,
+ * and warns about long skill bodies.
+ *
+ * @param filePath - Absolute path to the SKILL.md file to validate
+ * @returns Validation result with issues and parsed metadata
+ *
+ * @example
+ * ```typescript
+ * const result = await validateSkill("/path/to/SKILL.md");
+ * console.log(result.valid ? "Valid" : `${result.issues.length} issues found`);
+ * ```
+ */
 declare function validateSkill(filePath: string): Promise<ValidationResult>;
 
 /**
@@ -250,23 +937,121 @@ declare function validateSkill(filePath: string): Promise<ValidationResult>;
  * platform-specific paths at runtime.
  */
 
-/** Get all providers */
+/**
+ * Retrieve all registered providers with resolved platform paths.
+ *
+ * Providers are lazily loaded from `providers/registry.json` on first call
+ * and cached for subsequent calls.
+ *
+ * @returns Array of all provider definitions
+ *
+ * @example
+ * ```typescript
+ * const providers = getAllProviders();
+ * console.log(`${providers.length} providers registered`);
+ * ```
+ */
 declare function getAllProviders(): Provider[];
-/** Get a provider by ID or alias */
+/**
+ * Look up a provider by its ID or any of its aliases.
+ *
+ * @param idOrAlias - Provider ID (e.g. `"claude-code"`) or alias (e.g. `"claude"`)
+ * @returns The matching provider, or `undefined` if not found
+ *
+ * @example
+ * ```typescript
+ * const provider = getProvider("claude");
+ * // Returns the claude-code provider via alias resolution
+ * ```
+ */
 declare function getProvider(idOrAlias: string): Provider | undefined;
-/** Resolve an alias to provider ID */
+/**
+ * Resolve an alias to its canonical provider ID.
+ *
+ * If the input is already a canonical ID (or unrecognized), it is returned as-is.
+ *
+ * @param idOrAlias - Provider ID or alias to resolve
+ * @returns The canonical provider ID
+ *
+ * @example
+ * ```typescript
+ * resolveAlias("claude"); // "claude-code"
+ * resolveAlias("claude-code"); // "claude-code"
+ * resolveAlias("unknown"); // "unknown"
+ * ```
+ */
 declare function resolveAlias(idOrAlias: string): string;
-/** Get providers by priority tier */
+/**
+ * Filter providers by their priority tier.
+ *
+ * @param priority - Priority level to filter by (`"high"`, `"medium"`, or `"low"`)
+ * @returns Array of providers matching the given priority
+ *
+ * @example
+ * ```typescript
+ * const highPriority = getProvidersByPriority("high");
+ * ```
+ */
 declare function getProvidersByPriority(priority: ProviderPriority): Provider[];
-/** Get providers by status */
+/**
+ * Filter providers by their lifecycle status.
+ *
+ * @param status - Status to filter by (`"active"`, `"beta"`, `"deprecated"`, or `"planned"`)
+ * @returns Array of providers matching the given status
+ *
+ * @example
+ * ```typescript
+ * const active = getProvidersByStatus("active");
+ * ```
+ */
 declare function getProvidersByStatus(status: ProviderStatus): Provider[];
-/** Get providers that use a specific instruction file */
+/**
+ * Filter providers that use a specific instruction file.
+ *
+ * Multiple providers often share the same instruction file (e.g. many use `"AGENTS.md"`).
+ *
+ * @param file - Instruction file name (e.g. `"CLAUDE.md"`, `"AGENTS.md"`)
+ * @returns Array of providers that use the given instruction file
+ *
+ * @example
+ * ```typescript
+ * const claudeProviders = getProvidersByInstructFile("CLAUDE.md");
+ * ```
+ */
 declare function getProvidersByInstructFile(file: string): Provider[];
-/** Get all unique instruction files */
+/**
+ * Get the set of all unique instruction file names across all providers.
+ *
+ * @returns Array of unique instruction file names (e.g. `["CLAUDE.md", "AGENTS.md", "GEMINI.md"]`)
+ *
+ * @example
+ * ```typescript
+ * const files = getInstructionFiles();
+ * // ["CLAUDE.md", "AGENTS.md", "GEMINI.md"]
+ * ```
+ */
 declare function getInstructionFiles(): string[];
-/** Get provider count */
+/**
+ * Get the total number of registered providers.
+ *
+ * @returns Count of providers in the registry
+ *
+ * @example
+ * ```typescript
+ * console.log(`Registry has ${getProviderCount()} providers`);
+ * ```
+ */
 declare function getProviderCount(): number;
-/** Get registry version */
+/**
+ * Get the semantic version string of the provider registry.
+ *
+ * @returns Version string from `providers/registry.json` (e.g. `"1.0.0"`)
+ *
+ * @example
+ * ```typescript
+ * console.log(`Registry version: ${getRegistryVersion()}`);
+ * ```
+ */
 declare function getRegistryVersion(): string;
 
 /**
@@ -276,9 +1061,42 @@ declare function getRegistryVersion(): string;
  * GitLab URLs, local paths, or shell commands.
  */
 
-/** Parse a source string into a typed ParsedSource */
+/**
+ * Parse and classify a source string into a typed {@link ParsedSource}.
+ *
+ * Supports GitHub URLs, GitLab URLs, GitHub shorthand (`owner/repo`),
+ * HTTP URLs (remote MCP servers), npm package names, local paths, and
+ * shell commands as a fallback.
+ *
+ * @param input - Raw source string to classify
+ * @returns Parsed source with type, value, and inferred name
+ *
+ * @example
+ * ```typescript
+ * parseSource("owner/repo");
+ * // { type: "github", value: "https://github.com/owner/repo", inferredName: "repo", ... }
+ *
+ * parseSource("https://mcp.example.com/sse");
+ * // { type: "remote", value: "https://mcp.example.com/sse", inferredName: "example" }
+ *
+ * parseSource("@modelcontextprotocol/server-filesystem");
+ * // { type: "package", value: "@modelcontextprotocol/server-filesystem", inferredName: "filesystem" }
+ * ```
+ */
 declare function parseSource(input: string): ParsedSource;
-/** Check if source looks like an MCP marketplace scoped name (@author/name) */
+/**
+ * Check if a source string looks like a marketplace scoped name (`@author/name`).
+ *
+ * @param input - Source string to check
+ * @returns `true` if the input matches the `@scope/name` pattern
+ *
+ * @example
+ * ```typescript
+ * isMarketplaceScoped("@anthropic/my-skill"); // true
+ * isMarketplaceScoped("my-skill");             // false
+ * isMarketplaceScoped("owner/repo");           // false
+ * ```
+ */
 declare function isMarketplaceScoped(input: string): boolean;
 
 /**
@@ -287,11 +1105,57 @@ declare function isMarketplaceScoped(input: string): boolean;
  * Scans directories for SKILL.md files and parses their frontmatter.
  */
 
-/** Parse a SKILL.md file and extract metadata */
+/**
+ * Parse a SKILL.md file and extract its frontmatter metadata.
+ *
+ * Reads the file, parses YAML frontmatter via `gray-matter`, and maps the
+ * fields to a {@link SkillMetadata} object. Returns `null` if the file cannot
+ * be read or lacks required `name` and `description` fields.
+ *
+ * @param filePath - Absolute path to the SKILL.md file
+ * @returns Parsed metadata, or `null` if invalid
+ *
+ * @example
+ * ```typescript
+ * const meta = await parseSkillFile("/path/to/SKILL.md");
+ * if (meta) {
+ *   console.log(`${meta.name}: ${meta.description}`);
+ * }
+ * ```
+ */
 declare function parseSkillFile(filePath: string): Promise<SkillMetadata | null>;
-/** Discover a skill at a given path (directory containing SKILL.md) */
+/**
+ * Discover a single skill at a given directory path.
+ *
+ * Checks for a `SKILL.md` file in the directory and parses its metadata.
+ *
+ * @param skillDir - Absolute path to a skill directory (containing SKILL.md)
+ * @returns Skill entry with metadata, or `null` if no valid SKILL.md exists
+ *
+ * @example
+ * ```typescript
+ * const skill = await discoverSkill("/home/user/.agents/skills/my-skill");
+ * if (skill) {
+ *   console.log(`Found: ${skill.name}`);
+ * }
+ * ```
+ */
 declare function discoverSkill(skillDir: string): Promise<SkillEntry | null>;
-/** Scan a directory for skill directories (each containing SKILL.md) */
+/**
+ * Scan a directory for skill subdirectories, each containing a SKILL.md file.
+ *
+ * Iterates over directories and symlinks in `rootDir` and calls
+ * {@link discoverSkill} on each.
+ *
+ * @param rootDir - Absolute path to a skills root directory to scan
+ * @returns Array of discovered skill entries
+ *
+ * @example
+ * ```typescript
+ * const skills = await discoverSkills("/home/user/.agents/skills");
+ * console.log(`Found ${skills.length} skills`);
+ * ```
+ */
 declare function discoverSkills(rootDir: string): Promise<SkillEntry[]>;
 
 /**
@@ -301,11 +1165,55 @@ declare function discoverSkills(rootDir: string): Promise<SkillEntry[]>;
  * and produces findings with line-level precision.
  */
 
-/** Scan a single file against all rules */
+/**
+ * Scan a single file against security audit rules.
+ *
+ * Checks each line of the file against all active rules and produces findings
+ * with line-level precision. Calculates a security score (100 = clean, 0 = dangerous)
+ * based on severity-weighted penalties.
+ *
+ * @param filePath - Absolute path to the file to scan
+ * @param rules - Custom rules to scan against (defaults to the built-in 46+ rules)
+ * @returns Audit result with findings, score, and pass/fail status
+ *
+ * @example
+ * ```typescript
+ * const result = await scanFile("/path/to/SKILL.md");
+ * console.log(`Score: ${result.score}/100, Passed: ${result.passed}`);
+ * ```
+ */
 declare function scanFile(filePath: string, rules?: AuditRule[]): Promise<AuditResult>;
-/** Scan a directory of skills */
+/**
+ * Scan a directory of skills for security issues.
+ *
+ * Iterates over skill subdirectories and scans each `SKILL.md` file found.
+ *
+ * @param dirPath - Absolute path to the skills directory to scan
+ * @returns Array of audit results, one per scanned SKILL.md
+ *
+ * @example
+ * ```typescript
+ * const results = await scanDirectory("/home/user/.agents/skills");
+ * const failing = results.filter(r => !r.passed);
+ * ```
+ */
 declare function scanDirectory(dirPath: string): Promise<AuditResult[]>;
-/** Format findings as SARIF (Static Analysis Results Interchange Format) */
+/**
+ * Convert audit results to SARIF 2.1.0 format (Static Analysis Results Interchange Format).
+ *
+ * Produces a standards-compliant SARIF document suitable for CI/CD integration
+ * and code scanning tools (e.g. GitHub Code Scanning).
+ *
+ * @param results - Array of audit results to convert
+ * @returns SARIF 2.1.0 JSON object
+ *
+ * @example
+ * ```typescript
+ * const results = await scanDirectory("/path/to/skills");
+ * const sarif = toSarif(results);
+ * writeFileSync("audit.sarif", JSON.stringify(sarif, null, 2));
+ * ```
+ */
 declare function toSarif(results: AuditResult[]): object;
 
 /**
@@ -315,7 +1223,24 @@ declare function toSarif(results: AuditResult[]): object;
  * These transforms handle agents with non-standard schemas.
  */
 
-/** Get the transform function for a provider, or undefined for passthrough */
+/**
+ * Get the config transform function for a provider, or `undefined` for passthrough.
+ *
+ * Providers with non-standard MCP config schemas (Goose, Zed, OpenCode, Codex, Cursor)
+ * require transforms to convert the canonical {@link McpServerConfig} into their
+ * provider-specific format.
+ *
+ * @param providerId - Provider ID to look up (e.g. `"goose"`, `"zed"`)
+ * @returns Transform function, or `undefined` if the provider uses the canonical format
+ *
+ * @example
+ * ```typescript
+ * const transform = getTransform("goose");
+ * if (transform) {
+ *   const gooseConfig = transform("my-server", canonicalConfig);
+ * }
+ * ```
+ */
 declare function getTransform(providerId: string): ((name: string, config: McpServerConfig) => unknown) | undefined;
 
 /**
@@ -325,15 +1250,87 @@ declare function getTransform(providerId: string): ((name: string, config: McpSe
  * Provides the programmatic API that CLI commands delegate to.
  */
 
-/** Resolve the config file path for a provider and scope */
+/**
+ * Resolve the absolute config file path for a provider and scope.
+ *
+ * For project scope, joins the project directory with the provider's relative
+ * config path. For global scope, returns the provider's global config path.
+ *
+ * @param provider - Provider to resolve config path for
+ * @param scope - Whether to resolve project or global config path
+ * @param projectDir - Project directory (defaults to `process.cwd()`)
+ * @returns Absolute config file path, or `null` if the provider does not support the given scope
+ *
+ * @example
+ * ```typescript
+ * const path = resolveConfigPath(provider, "project", "/home/user/my-project");
+ * // "/home/user/my-project/.claude/settings.json"
+ * ```
+ */
 declare function resolveConfigPath(provider: Provider, scope: "project" | "global", projectDir?: string): string | null;
-/** List MCP servers configured for a single provider */
+/**
+ * List MCP servers configured for a single provider.
+ *
+ * Reads the provider's config file, extracts the MCP servers section using the
+ * provider's `configKey`, and returns each server entry with metadata.
+ *
+ * @param provider - Provider whose config file to read
+ * @param scope - Whether to read project or global config
+ * @param projectDir - Project directory (defaults to `process.cwd()`)
+ * @returns Array of MCP server entries found in the config file
+ *
+ * @example
+ * ```typescript
+ * const servers = await listMcpServers(provider, "project");
+ * for (const s of servers) {
+ *   console.log(`${s.name} (${s.scope})`);
+ * }
+ * ```
+ */
 declare function listMcpServers(provider: Provider, scope: "project" | "global", projectDir?: string): Promise<McpServerEntry[]>;
-/** List MCP servers across all given providers, deduplicating by config path */
+/**
+ * List MCP servers across all given providers, deduplicating by config path.
+ *
+ * Multiple providers may share the same config file. This function ensures each
+ * config file is read only once to avoid duplicate entries.
+ *
+ * @param providers - Array of providers to query
+ * @param scope - Whether to read project or global config
+ * @param projectDir - Project directory (defaults to `process.cwd()`)
+ * @returns Combined array of MCP server entries from all providers
+ *
+ * @example
+ * ```typescript
+ * const allServers = await listAllMcpServers(getInstalledProviders(), "global");
+ * ```
+ */
 declare function listAllMcpServers(providers: Provider[], scope: "project" | "global", projectDir?: string): Promise<McpServerEntry[]>;
-/** Remove an MCP server entry from a provider's config file */
+/**
+ * Remove an MCP server entry from a provider's config file.
+ *
+ * @param provider - Provider whose config file to modify
+ * @param serverName - Name/key of the MCP server to remove
+ * @param scope - Whether to modify project or global config
+ * @param projectDir - Project directory (defaults to `process.cwd()`)
+ * @returns `true` if the entry was removed, `false` if no config path exists
+ *
+ * @example
+ * ```typescript
+ * const removed = await removeMcpServer(provider, "my-server", "project");
+ * ```
+ */
 declare function removeMcpServer(provider: Provider, serverName: string, scope: "project" | "global", projectDir?: string): Promise<boolean>;
 
+/**
+ * Shared lock file utilities
+ *
+ * Single source of truth for reading/writing ~/.agents/.caamp-lock.json.
+ * Both MCP and skills lock modules import from here.
+ */
+
+/** Read the lock file */
+declare function readLockFile(): Promise<CaampLockFile>;
+
 /**
  * MCP lock file management
  *
@@ -341,17 +1338,74 @@ declare function removeMcpServer(provider: Provider, serverName: string, scope:
  * Stored at ~/.agents/.caamp-lock.json (shared with skills lock).
  */
 
-/** Read the lock file */
-declare function readLockFile(): Promise<CaampLockFile>;
-/** Record an MCP server installation */
+/**
+ * Record an MCP server installation in the lock file.
+ *
+ * Creates or updates an entry in `lock.mcpServers`. If the server already exists,
+ * the agent list is merged and `updatedAt` is refreshed while `installedAt` is preserved.
+ *
+ * @param serverName - Name/key of the MCP server
+ * @param source - Original source string
+ * @param sourceType - Classified source type
+ * @param agents - Provider IDs the server was installed to
+ * @param isGlobal - Whether this is a global installation
+ *
+ * @example
+ * ```typescript
+ * await recordMcpInstall("filesystem", "@mcp/server-fs", "package", ["claude-code"], true);
+ * ```
+ */
 declare function recordMcpInstall(serverName: string, source: string, sourceType: SourceType, agents: string[], isGlobal: boolean): Promise<void>;
-/** Remove an MCP server from the lock file */
+/**
+ * Remove an MCP server entry from the lock file.
+ *
+ * @param serverName - Name/key of the MCP server to remove
+ * @returns `true` if the entry was found and removed, `false` if not found
+ *
+ * @example
+ * ```typescript
+ * const removed = await removeMcpFromLock("filesystem");
+ * ```
+ */
 declare function removeMcpFromLock(serverName: string): Promise<boolean>;
-/** Get all tracked MCP servers */
+/**
+ * Get all MCP servers tracked in the lock file.
+ *
+ * @returns Record of server name to lock entry
+ *
+ * @example
+ * ```typescript
+ * const servers = await getTrackedMcpServers();
+ * for (const [name, entry] of Object.entries(servers)) {
+ *   console.log(`${name}: installed ${entry.installedAt}`);
+ * }
+ * ```
+ */
 declare function getTrackedMcpServers(): Promise<Record<string, LockEntry>>;
-/** Save last selected agents for UX */
+/**
+ * Save the last selected agent IDs to the lock file for UX persistence.
+ *
+ * Used to remember the user's agent selection between CLI invocations.
+ *
+ * @param agents - Array of provider IDs to remember
+ *
+ * @example
+ * ```typescript
+ * await saveLastSelectedAgents(["claude-code", "cursor"]);
+ * ```
+ */
 declare function saveLastSelectedAgents(agents: string[]): Promise<void>;
-/** Get last selected agents */
+/**
+ * Retrieve the last selected agent IDs from the lock file.
+ *
+ * @returns Array of provider IDs, or `undefined` if none were saved
+ *
+ * @example
+ * ```typescript
+ * const agents = await getLastSelectedAgents();
+ * // ["claude-code", "cursor"] or undefined
+ * ```
+ */
 declare function getLastSelectedAgents(): Promise<string[] | undefined>;
 
 /**
@@ -360,17 +1414,80 @@ declare function getLastSelectedAgents(): Promise<string[] | undefined>;
  * Shares the same lock file as MCP (~/.agents/.caamp-lock.json).
  */
 
-/** Record a skill installation */
+/**
+ * Record a skill installation in the lock file.
+ *
+ * Creates or updates an entry in `lock.skills`. If the skill already exists,
+ * the agent list is merged and `updatedAt` is refreshed while `installedAt` is preserved.
+ *
+ * @param skillName - Skill name
+ * @param scopedName - Scoped name (may include marketplace scope)
+ * @param source - Original source string
+ * @param sourceType - Classified source type
+ * @param agents - Provider IDs the skill was linked to
+ * @param canonicalPath - Absolute path to the canonical installation
+ * @param isGlobal - Whether this is a global installation
+ * @param projectDir - Project directory (for project-scoped installs)
+ * @param version - Version string or commit SHA
+ *
+ * @example
+ * ```typescript
+ * await recordSkillInstall(
+ *   "my-skill", "my-skill", "owner/repo", "github",
+ *   ["claude-code"], "/home/user/.agents/skills/my-skill", true,
+ * );
+ * ```
+ */
 declare function recordSkillInstall(skillName: string, scopedName: string, source: string, sourceType: SourceType, agents: string[], canonicalPath: string, isGlobal: boolean, projectDir?: string, version?: string): Promise<void>;
-/** Remove a skill from the lock file */
+/**
+ * Remove a skill entry from the lock file.
+ *
+ * @param skillName - Name of the skill to remove
+ * @returns `true` if the entry was found and removed, `false` if not found
+ *
+ * @example
+ * ```typescript
+ * const removed = await removeSkillFromLock("my-skill");
+ * ```
+ */
 declare function removeSkillFromLock(skillName: string): Promise<boolean>;
-/** Get all tracked skills */
+/**
+ * Get all skills tracked in the lock file.
+ *
+ * @returns Record of skill name to lock entry
+ *
+ * @example
+ * ```typescript
+ * const skills = await getTrackedSkills();
+ * for (const [name, entry] of Object.entries(skills)) {
+ *   console.log(`${name}: ${entry.source}`);
+ * }
+ * ```
+ */
 declare function getTrackedSkills(): Promise<Record<string, LockEntry>>;
-/** Check if a skill has updates available (comparing version/hash) */
+/**
+ * Check if a skill has updates available by comparing the installed version
+ * against the latest remote commit SHA.
+ *
+ * Only supports GitHub and GitLab sources. Returns `"unknown"` for local,
+ * package, or other source types.
+ *
+ * @param skillName - Name of the installed skill to check
+ * @returns Object with update status, current version, and latest version
+ *
+ * @example
+ * ```typescript
+ * const update = await checkSkillUpdate("my-skill");
+ * if (update.hasUpdate) {
+ *   console.log(`Update available: ${update.currentVersion} -> ${update.latestVersion}`);
+ * }
+ * ```
+ */
 declare function checkSkillUpdate(skillName: string): Promise<{
     hasUpdate: boolean;
     currentVersion?: string;
     latestVersion?: string;
+    status: "up-to-date" | "update-available" | "unknown";
 }>;
 
 /**
@@ -400,12 +1517,68 @@ interface MarketplaceResult {
  * deduplicates, and sorts by relevance.
  */
 
+/**
+ * Unified marketplace client that aggregates results from multiple marketplace adapters.
+ *
+ * Queries all configured marketplaces in parallel, deduplicates results by scoped name,
+ * and sorts by star count.
+ *
+ * @example
+ * ```typescript
+ * const client = new MarketplaceClient();
+ * const results = await client.search("filesystem");
+ * for (const r of results) {
+ *   console.log(`${r.scopedName} (${r.stars} stars)`);
+ * }
+ * ```
+ */
 declare class MarketplaceClient {
     private adapters;
+    /**
+     * Create a new marketplace client.
+     *
+     * @param adapters - Custom marketplace adapters (defaults to agentskills.in and skills.sh)
+     *
+     * @example
+     * ```typescript
+     * // Use default adapters
+     * const client = new MarketplaceClient();
+     *
+     * // Use custom adapters
+     * const client = new MarketplaceClient([myAdapter]);
+     * ```
+     */
     constructor(adapters?: MarketplaceAdapter[]);
-    /** Search all marketplaces and deduplicate results */
+    /**
+     * Search all marketplaces and return deduplicated, sorted results.
+     *
+     * Queries all adapters in parallel and deduplicates by `scopedName`,
+     * keeping the entry with the highest star count. Results are sorted by
+     * stars descending.
+     *
+     * @param query - Search query string
+     * @param limit - Maximum number of results to return (default: 20)
+     * @returns Deduplicated and sorted marketplace results
+     *
+     * @example
+     * ```typescript
+     * const results = await client.search("code review", 10);
+     * ```
+     */
     search(query: string, limit?: number): Promise<MarketplaceResult[]>;
-    /** Get a specific skill by scoped name */
+    /**
+     * Get a specific skill by its scoped name from any marketplace.
+     *
+     * Tries each adapter in order and returns the first match.
+     *
+     * @param scopedName - Scoped skill name (e.g. `"@author/my-skill"`)
+     * @returns The marketplace result, or `null` if not found in any marketplace
+     *
+     * @example
+     * ```typescript
+     * const skill = await client.getSkill("@anthropic/memory");
+     * ```
+     */
     getSkill(scopedName: string): Promise<MarketplaceResult | null>;
 }
 
@@ -416,15 +1589,99 @@ declare class MarketplaceClient {
  * (CLAUDE.md, AGENTS.md, GEMINI.md).
  */
 
-/** Check if a file has a CAAMP injection block */
+/**
+ * Check the status of a CAAMP injection block in an instruction file.
+ *
+ * Returns the injection status:
+ * - `"missing"` - File does not exist
+ * - `"none"` - File exists but has no CAAMP markers
+ * - `"current"` - CAAMP block exists and matches expected content (or no expected content given)
+ * - `"outdated"` - CAAMP block exists but differs from expected content
+ *
+ * @param filePath - Absolute path to the instruction file
+ * @param expectedContent - Optional expected content to compare against
+ * @returns The injection status
+ *
+ * @example
+ * ```typescript
+ * const status = await checkInjection("/project/CLAUDE.md", expectedContent);
+ * if (status === "outdated") {
+ *   console.log("CAAMP injection needs updating");
+ * }
+ * ```
+ */
 declare function checkInjection(filePath: string, expectedContent?: string): Promise<InjectionStatus>;
-/** Inject content into a file */
+/**
+ * Inject content into an instruction file between CAAMP markers.
+ *
+ * Behavior depends on the file state:
+ * - File does not exist: creates the file with the injection block
+ * - File exists without markers: prepends the injection block
+ * - File exists with markers: replaces the existing injection block
+ *
+ * @param filePath - Absolute path to the instruction file
+ * @param content - Content to inject between CAAMP markers
+ * @returns Action taken: `"created"`, `"added"`, or `"updated"`
+ *
+ * @example
+ * ```typescript
+ * const action = await inject("/project/CLAUDE.md", "## My Config\nSome content");
+ * console.log(`File ${action}`);
+ * ```
+ */
 declare function inject(filePath: string, content: string): Promise<"created" | "added" | "updated">;
-/** Remove the CAAMP injection block from a file */
+/**
+ * Remove the CAAMP injection block from an instruction file.
+ *
+ * If removing the block would leave the file empty, the file is deleted entirely.
+ *
+ * @param filePath - Absolute path to the instruction file
+ * @returns `true` if a CAAMP block was found and removed, `false` otherwise
+ *
+ * @example
+ * ```typescript
+ * const removed = await removeInjection("/project/CLAUDE.md");
+ * ```
+ */
 declare function removeInjection(filePath: string): Promise<boolean>;
-/** Check injection status across all providers' instruction files */
+/**
+ * Check injection status across all providers' instruction files.
+ *
+ * Deduplicates by file path since multiple providers may share the same
+ * instruction file (e.g. many providers use `AGENTS.md`).
+ *
+ * @param providers - Array of providers to check
+ * @param projectDir - Absolute path to the project directory
+ * @param scope - Whether to check project or global instruction files
+ * @param expectedContent - Optional expected content to compare against
+ * @returns Array of injection check results, one per unique instruction file
+ *
+ * @example
+ * ```typescript
+ * const results = await checkAllInjections(providers, "/project", "project");
+ * const outdated = results.filter(r => r.status === "outdated");
+ * ```
+ */
 declare function checkAllInjections(providers: Provider[], projectDir: string, scope: "project" | "global", expectedContent?: string): Promise<InjectionCheckResult[]>;
-/** Inject content into all providers' instruction files */
+/**
+ * Inject content into all providers' instruction files.
+ *
+ * Deduplicates by file path to avoid injecting the same file multiple times.
+ *
+ * @param providers - Array of providers to inject into
+ * @param projectDir - Absolute path to the project directory
+ * @param scope - Whether to target project or global instruction files
+ * @param content - Content to inject between CAAMP markers
+ * @returns Map of file path to action taken (`"created"`, `"added"`, or `"updated"`)
+ *
+ * @example
+ * ```typescript
+ * const results = await injectAll(providers, "/project", "project", content);
+ * for (const [file, action] of results) {
+ *   console.log(`${file}: ${action}`);
+ * }
+ * ```
+ */
 declare function injectAll(providers: Provider[], projectDir: string, scope: "project" | "global", content: string): Promise<Map<string, "created" | "added" | "updated">>;
 
 /**
@@ -433,33 +1690,207 @@ declare function injectAll(providers: Provider[], projectDir: string, scope: "pr
  * Generates injection content based on provider capabilities.
  */
 
-/** Generate a standard CAAMP injection block */
+/**
+ * Generate a standard CAAMP injection block for instruction files.
+ *
+ * Produces markdown content suitable for injection between CAAMP markers.
+ * Optionally includes MCP server and custom content sections.
+ *
+ * @param options - Optional configuration for the generated content
+ * @param options.mcpServerName - MCP server name to include a server section
+ * @param options.customContent - Additional custom markdown content to append
+ * @returns Generated markdown string
+ *
+ * @example
+ * ```typescript
+ * const content = generateInjectionContent({ mcpServerName: "filesystem" });
+ * ```
+ */
 declare function generateInjectionContent(options?: {
     mcpServerName?: string;
     customContent?: string;
 }): string;
-/** Group providers by instruction file */
+/**
+ * Group providers by their instruction file name.
+ *
+ * Useful for determining which providers share the same instruction file
+ * (e.g. multiple providers using `AGENTS.md`).
+ *
+ * @param providers - Array of providers to group
+ * @returns Map from instruction file name to array of providers using that file
+ *
+ * @example
+ * ```typescript
+ * const groups = groupByInstructFile(getAllProviders());
+ * for (const [file, providers] of groups) {
+ *   console.log(`${file}: ${providers.map(p => p.id).join(", ")}`);
+ * }
+ * ```
+ */
 declare function groupByInstructFile(providers: Provider[]): Map<string, Provider[]>;
 
 /**
  * Format utility functions
  */
-/** Deep merge two objects, source wins on conflict */
+/**
+ * Deep merge two objects, with `source` values winning on conflict.
+ *
+ * Recursively merges nested plain objects. Arrays and non-object values from
+ * `source` overwrite `target` values.
+ *
+ * @param target - Base object to merge into
+ * @param source - Object with values that take precedence
+ * @returns A new merged object (does not mutate inputs)
+ *
+ * @example
+ * ```typescript
+ * deepMerge({ a: 1, b: { c: 2 } }, { b: { d: 3 } });
+ * // { a: 1, b: { c: 2, d: 3 } }
+ * ```
+ */
 declare function deepMerge(target: Record<string, unknown>, source: Record<string, unknown>): Record<string, unknown>;
-/** Get a nested value using dot-notation key path */
+/**
+ * Get a nested value from an object using a dot-notation key path.
+ *
+ * @param obj - Object to traverse
+ * @param keyPath - Dot-separated key path (e.g. `"mcpServers"` or `"a.b.c"`)
+ * @returns The value at the key path, or `undefined` if not found
+ *
+ * @example
+ * ```typescript
+ * getNestedValue({ a: { b: { c: 42 } } }, "a.b.c"); // 42
+ * getNestedValue({ a: 1 }, "a.b"); // undefined
+ * ```
+ */
 declare function getNestedValue(obj: Record<string, unknown>, keyPath: string): unknown;
-/** Ensure parent directories exist */
+/**
+ * Ensure that the parent directories of a file path exist.
+ *
+ * Creates directories recursively if they do not exist.
+ *
+ * @param filePath - Absolute path to a file (parent directories will be created)
+ *
+ * @example
+ * ```typescript
+ * await ensureDir("/path/to/new/dir/file.json");
+ * // /path/to/new/dir/ now exists
+ * ```
+ */
 declare function ensureDir(filePath: string): Promise<void>;
 
 /**
  * Format router - dispatches config reads/writes to format-specific handlers
  */
 
-/** Read a config file in the specified format */
+/**
+ * Read and parse a config file in the specified format.
+ *
+ * Dispatches to the appropriate format handler (JSON/JSONC, YAML, or TOML).
+ *
+ * @param filePath - Absolute path to the config file
+ * @param format - Config file format
+ * @returns Parsed config object
+ * @throws If the file cannot be read or the format is unsupported
+ *
+ * @example
+ * ```typescript
+ * const config = await readConfig("/path/to/config.json", "jsonc");
+ * ```
+ */
 declare function readConfig(filePath: string, format: ConfigFormat): Promise<Record<string, unknown>>;
-/** Write a config file in the specified format, preserving existing content */
+/**
+ * Write a server entry to a config file, preserving existing content.
+ *
+ * Dispatches to the appropriate format handler. For JSONC files, comments are
+ * preserved using `jsonc-parser`.
+ *
+ * @param filePath - Absolute path to the config file
+ * @param format - Config file format
+ * @param key - Dot-notation key path to the servers section (e.g. `"mcpServers"`)
+ * @param serverName - Name/key for the server entry
+ * @param serverConfig - Server configuration object to write
+ * @throws If the format is unsupported
+ *
+ * @example
+ * ```typescript
+ * await writeConfig("/path/to/config.json", "jsonc", "mcpServers", "my-server", config);
+ * ```
+ */
 declare function writeConfig(filePath: string, format: ConfigFormat, key: string, serverName: string, serverConfig: unknown): Promise<void>;
-/** Remove a server entry from a config file in the specified format */
+/**
+ * Remove a server entry from a config file in the specified format.
+ *
+ * @param filePath - Absolute path to the config file
+ * @param format - Config file format
+ * @param key - Dot-notation key path to the servers section
+ * @param serverName - Name/key of the server entry to remove
+ * @returns `true` if the entry was removed, `false` otherwise
+ * @throws If the format is unsupported
+ *
+ * @example
+ * ```typescript
+ * const removed = await removeConfig("/path/to/config.json", "jsonc", "mcpServers", "my-server");
+ * ```
+ */
 declare function removeConfig(filePath: string, format: ConfigFormat, key: string, serverName: string): Promise<boolean>;
 
-export { type AuditFinding, type AuditResult, type AuditRule, type AuditSeverity, type CaampLockFile, type ConfigFormat, type DetectionResult, type GlobalOptions, type InjectionCheckResult, type InjectionStatus, type InstallResult, type LockEntry, MarketplaceClient, type MarketplaceSearchResult, type MarketplaceSkill, type McpServerConfig, type McpServerEntry, type ParsedSource, type Provider, type SkillEntry, type SkillInstallResult, type SkillMetadata, type SourceType, type TransportType, type ValidationIssue, type ValidationResult, buildServerConfig, checkAllInjections, checkInjection, checkSkillUpdate, deepMerge, detectAllProviders, detectProjectProviders, detectProvider, discoverSkill, discoverSkills, ensureDir, generateInjectionContent, getAllProviders, getInstalledProviders, getInstructionFiles, getLastSelectedAgents, getNestedValue, getProvider, getProviderCount, getProvidersByInstructFile, getProvidersByPriority, getProvidersByStatus, getRegistryVersion, getTrackedMcpServers, getTrackedSkills, getTransform, groupByInstructFile, inject, injectAll, installMcpServer, installMcpServerToAll, installSkill, isMarketplaceScoped, listAllMcpServers, listCanonicalSkills, listMcpServers, parseSkillFile, parseSource, readConfig, readLockFile, recordMcpInstall, recordSkillInstall, removeConfig, removeInjection, removeMcpFromLock, removeMcpServer, removeSkill, removeSkillFromLock, resolveAlias, resolveConfigPath, saveLastSelectedAgents, scanDirectory, scanFile, toSarif, validateSkill, writeConfig };
+/**
+ * Simple logger with verbose/quiet mode support.
+ *
+ * - verbose: enables debug output to stderr
+ * - quiet: suppresses info and warn output (errors always shown)
+ */
+/**
+ * Enable or disable verbose (debug) logging mode.
+ *
+ * When enabled, debug messages are written to stderr.
+ *
+ * @param v - `true` to enable verbose mode, `false` to disable
+ *
+ * @example
+ * ```typescript
+ * setVerbose(true);
+ * ```
+ */
+declare function setVerbose(v: boolean): void;
+/**
+ * Enable or disable quiet mode.
+ *
+ * When enabled, info and warning messages are suppressed. Errors are always shown.
+ *
+ * @param q - `true` to enable quiet mode, `false` to disable
+ *
+ * @example
+ * ```typescript
+ * setQuiet(true);
+ * ```
+ */
+declare function setQuiet(q: boolean): void;
+/**
+ * Check if verbose (debug) logging is currently enabled.
+ *
+ * @returns `true` if verbose mode is active
+ *
+ * @example
+ * ```typescript
+ * if (isVerbose()) {
+ *   console.error("Extra debug info");
+ * }
+ * ```
+ */
+declare function isVerbose(): boolean;
+/**
+ * Check if quiet mode is currently enabled.
+ *
+ * @returns `true` if quiet mode is active
+ *
+ * @example
+ * ```typescript
+ * if (!isQuiet()) {
+ *   console.log("Status message");
+ * }
+ * ```
+ */
+declare function isQuiet(): boolean;
+
+export { type AuditFinding, type AuditResult, type AuditRule, type AuditSeverity, type CaampLockFile, type ConfigFormat, type DetectionResult, type GlobalOptions, type InjectionCheckResult, type InjectionStatus, type InstallResult, type LockEntry, MarketplaceClient, type MarketplaceResult, type MarketplaceSearchResult, type MarketplaceSkill, type McpServerConfig, type McpServerEntry, type ParsedSource, type Provider, type ProviderPriority, type ProviderStatus, type SkillEntry, type SkillInstallResult, type SkillMetadata, type SourceType, type TransportType, type ValidationIssue, type ValidationResult, buildServerConfig, checkAllInjections, checkInjection, checkSkillUpdate, deepMerge, detectAllProviders, detectProjectProviders, detectProvider, discoverSkill, discoverSkills, ensureDir, generateInjectionContent, getAllProviders, getInstalledProviders, getInstructionFiles, getLastSelectedAgents, getNestedValue, getProvider, getProviderCount, getProvidersByInstructFile, getProvidersByPriority, getProvidersByStatus, getRegistryVersion, getTrackedMcpServers, getTrackedSkills, getTransform, groupByInstructFile, inject, injectAll, installMcpServer, installMcpServerToAll, installSkill, isMarketplaceScoped, isQuiet, isVerbose, listAllMcpServers, listCanonicalSkills, listMcpServers, parseSkillFile, parseSource, readConfig, readLockFile, recordMcpInstall, recordSkillInstall, removeConfig, removeInjection, removeMcpFromLock, removeMcpServer, removeSkill, removeSkillFromLock, resolveAlias, resolveConfigPath, saveLastSelectedAgents, scanDirectory, scanFile, setQuiet, setVerbose, toSarif, validateSkill, writeConfig };