@cleocode/caamp 2026.5.83 → 2026.5.86

package/dist/index.d.ts

@@ -1,7 +1,538 @@
+import { Command } from 'commander';
 import { WorktreeHandle } from '@cleocode/cant';
 import { PlatformPaths, SystemInfo } from '@cleocode/paths';
 export { PlatformPaths, SystemInfo } from '@cleocode/paths';
 
+/**
+ * `skills doctor adopt-orphans` — interactive orphan audit + adoption.
+ *
+ * @remarks
+ * An "orphan" is a skill directory that exists under any tracked path
+ * (`~/.cleo/skills/`, legacy `~/.local/share/agents/skills/`,
+ * `~/.agents/skills/` as a real dir) but has NO row in the per-user
+ * `skills.db` registry described in
+ * `docs/architecture/SG-CLEO-SKILLS-architecture-v3.md` §4.
+ *
+ * The handler offers four per-orphan dispositions:
+ *
+ *   - **canonical-adopt** — REFUSED on a user machine. Canonical writes
+ *     must flow via PR to `packages/skills/skills/` (architecture-v3 §6
+ *     invariant). The handler emits a refusal explaining the PR flow.
+ *   - **user-adopt** — inserts a row into `skills.db` with
+ *     `source_type='user'`, `lifecycle_state='active'`, `installedAt=now`.
+ *   - **delete** — archives the directory to
+ *     `~/.cleo/skills/.archive/<name>-<ts>/` before unlinking from the
+ *     original location.
+ *   - **skip** — no action; the orphan is logged but otherwise ignored.
+ *
+ * All decisions are recorded to a structured JSON audit log at
+ * `~/.cleo/skills/.audit-log/adopt-<ISO-ts>.json` regardless of mode.
+ *
+ * ## Chokepoint compliance (ADR-068)
+ *
+ * This module emits PURE DATA. The skills.db reads and writes are deferred
+ * to caller-supplied callbacks (`loadRegisteredNames`, `recordRow`). The
+ * `cleo` dispatch layer in `packages/cleo/src/cli/commands/skills.ts` plugs
+ * the canonical `openCleoDb('skills')`/`upsertSkillRow` helpers from
+ * `@cleocode/core/store/skills-db`. caamp cannot depend on `@cleocode/core`
+ * directly (would invert the dep direction: core dynamically imports caamp).
+ *
+ * Three execution modes:
+ *
+ *   - default (TTY) — interactive prompt per orphan.
+ *   - `--non-interactive` — list orphans and exit without action
+ *     (read-only audit).
+ *   - `--auto-user-adopt` — bulk user-adopt all orphans without prompting
+ *     (safe default for `cleo-init`-style scripts).
+ *
+ * @task T9657
+ * @epic T9571
+ * @saga T9560
+ * @architecture docs/architecture/SG-CLEO-SKILLS-architecture-v3.md §1, §6
+ */
+
+/**
+ * One orphan disposition decision.
+ *
+ * @public
+ */
+type OrphanDecision = 'canonical-adopt' | 'user-adopt' | 'delete' | 'skip';
+/**
+ * Reason an action was refused (canonical-adopt on user machine, etc.).
+ *
+ * @public
+ */
+interface OrphanRefusal {
+    /** Stable code for programmatic handling. */
+    code: 'E_CANONICAL_ADOPT_REFUSED';
+    /** Human-readable explanation. */
+    message: string;
+    /** Suggested next step (e.g. PR flow). */
+    remediation: string;
+}
+/**
+ * A single orphan skill directory discovered on disk.
+ *
+ * @public
+ */
+interface OrphanRecord {
+    /** Skill name (basename of the orphan directory). */
+    name: string;
+    /** Absolute path to the orphan directory on disk. */
+    path: string;
+    /** Which tracked root this orphan was discovered under. */
+    discoveredVia: 'cleo' | 'legacy-agents' | 'home-agents';
+    /** Whether a `SKILL.md` sentinel exists at the root. */
+    hasSkillMd: boolean;
+    /** Size of the directory in bytes (best-effort; 0 on stat failure). */
+    sizeBytes: number;
+}
+/**
+ * Outcome of acting on a single orphan.
+ *
+ * @public
+ */
+interface OrphanActionResult {
+    /** The orphan that was acted upon. */
+    orphan: OrphanRecord;
+    /** Decision the user (or flag) made. */
+    decision: OrphanDecision;
+    /** Whether the action completed successfully. */
+    applied: boolean;
+    /** Refusal payload when `applied=false` due to a policy block. */
+    refusal: OrphanRefusal | null;
+    /** Where the directory was archived to (delete only). */
+    archivedTo: string | null;
+    /** ISO-8601 timestamp when the action was taken. */
+    decidedAt: string;
+}
+/**
+ * Top-level result returned in the LAFS envelope.
+ *
+ * @public
+ */
+interface DoctorAdoptResult {
+    /** Total orphans discovered. */
+    totalOrphans: number;
+    /** Per-orphan action results. */
+    results: OrphanActionResult[];
+    /** Audit log file path (always written). */
+    auditLogPath: string;
+    /** Execution mode used. */
+    mode: 'interactive' | 'non-interactive' | 'auto-user-adopt';
+}
+/**
+ * Pure-data payload emitted when a `user-adopt` decision is applied.
+ *
+ * @remarks
+ * The dispatch layer translates this into an `upsertSkillRow` call via the
+ * `openCleoDb('skills')` chokepoint. Keeping it as pure data means caamp
+ * never has to touch sqlite directly.
+ *
+ * @public
+ */
+interface AdoptedSkillRowData {
+    /** Skill name (PK in skills.db). */
+    name: string;
+    /** Absolute install path on disk. */
+    installPath: string;
+    /** Wall-clock timestamp the adoption occurred. */
+    installedAt: string;
+    /** Always `'user'` for the adopt-orphans flow (canonical is refused). */
+    sourceType: 'user';
+    /** Always `'active'` post-adoption. */
+    lifecycleState: 'active';
+}
+/**
+ * Discover orphan skills across all tracked roots.
+ *
+ * @remarks
+ * Visits the three tracked roots in priority order and de-duplicates by
+ * basename — the first occurrence of `<name>` wins (so a `~/.cleo/skills/`
+ * entry shadows the same-named legacy entry). Symlinks under
+ * `~/.agents/skills/` that resolve back into `~/.cleo/skills/` are dropped
+ * because those are the bridge symlinks, not real orphans.
+ *
+ * Read-side IO (the set of names already known to `skills.db`) is supplied
+ * via the `registeredNames` callback so this module never opens sqlite
+ * directly — see ADR-068 chokepoint compliance in the file header.
+ *
+ * @param registeredNames - Pre-computed set of skill names known to the
+ *   registry. Callers in production wire this through `openCleoDb('skills')`;
+ *   tests wire it through a sandboxed `DatabaseSync` open.
+ * @returns Sorted-by-name list of `OrphanRecord`s.
+ *
+ * @public
+ */
+declare function discoverOrphans(registeredNames: ReadonlySet<string>): OrphanRecord[];
+/**
+ * Callback signature for persisting a `user-adopt` decision.
+ *
+ * @remarks
+ * Production wiring lives in `packages/cleo/src/cli/commands/skills.ts` and
+ * funnels into `upsertSkillRow` from `@cleocode/core/store/skills-db`,
+ * which routes through the canonical `openCleoDb('skills')` chokepoint.
+ * Test code passes a sandboxed sqlite write. May be synchronous or async.
+ *
+ * @public
+ */
+type RecordRowFn = (data: AdoptedSkillRowData) => void | Promise<void>;
+/**
+ * Apply a single decision to an orphan, returning a structured outcome.
+ *
+ * @remarks
+ * This is the policy chokepoint — `canonical-adopt` is unconditionally
+ * refused, `user-adopt` invokes `recordRow` with the canonical
+ * {@link AdoptedSkillRowData} payload, `delete` archives-then-rms, and
+ * `skip` records the intent without side effects. Errors during
+ * `user-adopt` or `delete` produce an `applied=false` result with a
+ * synthesised refusal payload rather than throwing, so the bulk loop can
+ * proceed across all orphans.
+ *
+ * @param orphan - Orphan to act on.
+ * @param decision - Decision to apply.
+ * @param now - ISO-8601 timestamp to record on the result.
+ * @param recordRow - Callback invoked to persist a successful `user-adopt`.
+ *   Tests pass a sandbox write; production passes the cleo-dispatch wrapper.
+ * @returns A populated `OrphanActionResult`.
+ *
+ * @public
+ */
+declare function applyDecision(orphan: OrphanRecord, decision: OrphanDecision, now: string, recordRow: RecordRowFn): Promise<OrphanActionResult>;
+/**
+ * Write the audit log to `~/.cleo/skills/.audit-log/adopt-<ts>.json`.
+ *
+ * @remarks
+ * The log is written atomically (tmp-then-rename) so a SIGINT mid-write
+ * cannot leave a half-written file. The payload is a structured object
+ * containing the run timestamp, mode, full per-orphan results, and a
+ * stable `runId` UUID for cross-referencing in other CLEO audit streams
+ * (e.g. release-ship logs).
+ *
+ * @param result - The doctor-adopt result to persist.
+ * @returns Absolute path the audit log was written to.
+ *
+ * @public
+ */
+declare function writeAuditLog(result: DoctorAdoptResult): string;
+/**
+ * Options controlling a `runDoctorAdopt` invocation.
+ *
+ * @public
+ */
+interface DoctorAdoptOptions {
+    /** Skip prompting and write nothing — list-only audit mode. */
+    nonInteractive?: boolean;
+    /** Skip prompting and bulk-adopt every orphan as `source_type='user'`. */
+    autoUserAdopt?: boolean;
+    /**
+     * Loads the set of skill names already known to the registry.
+     *
+     * Production wiring opens `skills.db` via `openCleoDb('skills')`; tests
+     * inject a sandbox-scoped reader.
+     */
+    loadRegisteredNames: () => ReadonlySet<string> | Promise<ReadonlySet<string>>;
+    /**
+     * Persists a single `user-adopt` decision to `skills.db`.
+     *
+     * Production wiring calls `upsertSkillRow` from `@cleocode/core/store`;
+     * tests inject a sandbox writer.
+     */
+    recordRow: RecordRowFn;
+    /** Test-only injection of a readline-compatible prompt. */
+    prompt?: (orphan: OrphanRecord) => Promise<OrphanDecision>;
+    /** Test-only opt-out of writing the audit log to disk. */
+    skipAuditLog?: boolean;
+    /** Test-only override for the discovery step. */
+    discoverFn?: (registeredNames: ReadonlySet<string>) => OrphanRecord[];
+}
+/**
+ * Execute the doctor-adopt workflow and return a structured result.
+ *
+ * @remarks
+ * Designed for both CLI invocation (from {@link registerSkillsDoctorAdopt})
+ * and direct testing — every side effect is overridable via
+ * {@link DoctorAdoptOptions}. The function never throws on per-orphan
+ * failures; instead each failure produces an `applied=false` entry with a
+ * refusal payload, so the caller gets a complete report even on partial
+ * failure.
+ *
+ * @param options - Mode flags + dependency-injected callbacks. The
+ *   `loadRegisteredNames` and `recordRow` callbacks are MANDATORY so the
+ *   caller (cleo dispatch or test harness) owns the sqlite open via the
+ *   chokepoint.
+ * @returns The populated `DoctorAdoptResult`.
+ *
+ * @public
+ */
+declare function runDoctorAdopt(options: DoctorAdoptOptions): Promise<DoctorAdoptResult>;
+/**
+ * Default skill-name loader bound at CLI dispatch time.
+ *
+ * @remarks
+ * Re-exported so the cleo dispatch layer can construct it once and inject
+ * the same instance into {@link runDoctorAdopt}.
+ *
+ * @public
+ */
+type RegisteredNamesLoader = () => ReadonlySet<string> | Promise<ReadonlySet<string>>;
+/**
+ * Adapter callbacks the CLI registrar needs to satisfy
+ * {@link DoctorAdoptOptions}'s mandatory deps.
+ *
+ * @remarks
+ * The caamp CLI (`caamp skills doctor adopt-orphans`) supplies a no-op pair
+ * — caamp is the registry-author-tool and never touches a live skills.db.
+ * The cleo CLI overrides both with chokepoint-routed implementations.
+ *
+ * @public
+ */
+interface DoctorAdoptCliAdapters {
+    loadRegisteredNames: RegisteredNamesLoader;
+    recordRow: RecordRowFn;
+}
+/**
+ * Standalone-`caamp` defaults — no DB access, every directory is an orphan.
+ *
+ * @remarks
+ * In the standalone caamp CLI, there's no skills.db (caamp is the
+ * registry-author tool, not the user-runtime). We treat every directory as
+ * an orphan and refuse all user-adopt writes by surfacing an explanatory
+ * error through `recordRow`. The cleo CLI overrides this with the real
+ * chokepoint-routed adapters.
+ *
+ * @public
+ */
+declare const caampStandaloneAdapters: DoctorAdoptCliAdapters;
+/**
+ * Register the `skills doctor adopt-orphans` subcommand on the parent
+ * `skills` Commander group.
+ *
+ * @remarks
+ * The handler creates the `doctor` subgroup if it doesn't already exist on
+ * the parent, so registration order is tolerant of co-registration with
+ * `registerSkillsDoctor` (T9655 bridge). Adapters default to
+ * {@link caampStandaloneAdapters} which surface a clear error — pass the
+ * cleo-chokepoint adapters when wiring under `packages/cleo/`.
+ *
+ * Default output is LAFS JSON. Pass `--human` for the colorised summary.
+ *
+ * @param parent - The parent `skills` Command from
+ *   {@link registerSkillsCommands}.
+ * @param adapters - DB read/write hooks. Defaults to
+ *   {@link caampStandaloneAdapters} so the standalone caamp CLI surfaces a
+ *   helpful error rather than silently no-op'ing.
+ *
+ * @example
+ * ```bash
+ * cleo skills doctor adopt-orphans                 # interactive
+ * cleo skills doctor adopt-orphans --non-interactive
+ * cleo skills doctor adopt-orphans --auto-user-adopt --json
+ * ```
+ *
+ * @public
+ */
+declare function registerSkillsDoctorAdopt(parent: Command, adapters?: DoctorAdoptCliAdapters): void;
+
+/**
+ * `cleo skills doctor bridge` — single bridge symlink + per-skill symlink removal.
+ *
+ * @remarks
+ * Implements the canonical discovery topology described in
+ * `docs/architecture/SG-CLEO-SKILLS-architecture-v3.md` §1:
+ *
+ * - `~/.cleo/skills/<name>/` is the per-user install root (Sphere A + B).
+ * - `~/.claude/skills/agents-shared/<name>` is a symlink INTO `~/.cleo/skills/`
+ *   for each installed skill — Claude Code's hardcoded discovery mount.
+ * - `~/.agents/skills` is the SINGLE bridge symlink → `~/.claude/skills/agents-shared`
+ *   used by every non-Claude harness (Cursor, Aider, Codeium, etc.).
+ *
+ * The bridge command takes a host machine from any pre-v3 state and:
+ *
+ * 1. Ensures `~/.claude/skills/agents-shared/` exists (mkdir -p).
+ * 2. Creates a symlink under `agents-shared/` for every skill currently in
+ *    `~/.cleo/skills/` whose target is missing or wrong.
+ * 3. Atomically replaces `~/.agents/skills` with a symlink to
+ *    `~/.claude/skills/agents-shared`. If the existing `~/.agents/skills` is a
+ *    REAL directory with contents, the command refuses without `--force` and
+ *    backs up to `~/.cleo/backups/agents-skills-pre-bridge-YYYYMMDD-HHmmss/`
+ *    when `--force` is supplied.
+ * 4. Rips per-skill symlinks under `~/.claude/skills/*` that point OUTSIDE
+ *    `agents-shared/` (orphans from the old per-skill fan-out model).
+ *
+ * The handler is pure-functional with a dependency-injected `homeDir` so it
+ * can be exercised against tmpfs fixtures in unit tests without touching the
+ * real user environment.
+ *
+ * @see {@link docs/architecture/SG-CLEO-SKILLS-architecture-v3.md} §1
+ * @task T9655
+ * @epic T9571
+ * @public
+ */
+
+/**
+ * One symlink that was created (or would be created in `--dry-run`).
+ *
+ * @public
+ */
+interface BridgeSymlinkRecord {
+    /** Skill basename, e.g. `ct-orchestrator`. */
+    name: string;
+    /** Absolute path of the symlink under `~/.claude/skills/agents-shared/`. */
+    linkPath: string;
+    /** Absolute path of the symlink target inside `~/.cleo/skills/`. */
+    target: string;
+}
+/**
+ * One per-skill symlink that was removed (or would be removed in `--dry-run`).
+ *
+ * @public
+ */
+interface PerSkillSymlinkRemoval {
+    /** Absolute path of the symlink that was removed. */
+    linkPath: string;
+    /** Resolved target the symlink pointed at, or `null` when unreadable. */
+    previousTarget: string | null;
+}
+/**
+ * LAFS-shaped result payload emitted by {@link runDoctorBridge}.
+ *
+ * @public
+ */
+interface DoctorBridgeResult {
+    /** Whether this run materially changed disk state. `false` on idempotent re-runs. */
+    bridgeCreated: boolean;
+    /**
+     * Whether `~/.agents/skills` is now a symlink to `~/.claude/skills/agents-shared`.
+     *
+     * @remarks
+     * Always `true` after a successful run. `false` only when `--dry-run` was
+     * requested and the bridge had to be created.
+     */
+    bridgeSymlinkActive: boolean;
+    /** Symlinks created under `~/.claude/skills/agents-shared/` (or planned in dry-run). */
+    perSkillSymlinksCreated: BridgeSymlinkRecord[];
+    /** Per-skill symlinks under `~/.claude/skills/*` that were removed (or planned). */
+    perSkillSymlinksRemoved: PerSkillSymlinkRemoval[];
+    /**
+     * Absolute backup path when the existing `~/.agents/skills` real dir was
+     * relocated to make room for the bridge symlink. `null` when no backup was
+     * needed.
+     */
+    backupPath: string | null;
+    /** `true` when `--dry-run` was passed and no disk state was mutated. */
+    dryRun: boolean;
+    /** Resolved skills root, e.g. `~/.cleo/skills`. */
+    skillsRoot: string;
+    /** Resolved bridge target, e.g. `~/.claude/skills/agents-shared`. */
+    bridgeTarget: string;
+    /** Resolved bridge symlink path, e.g. `~/.agents/skills`. */
+    bridgePath: string;
+}
+/**
+ * Dependency-injected options accepted by {@link runDoctorBridge}.
+ *
+ * @public
+ */
+interface DoctorBridgeOptions {
+    /**
+     * Override the home directory. Defaults to {@link homedir}.
+     *
+     * @remarks
+     * Tests pass a tmpfs root so the bridge logic can be exercised end-to-end
+     * without touching the real user environment.
+     */
+    homeDir?: string;
+    /**
+     * Allow the command to clobber an existing real `~/.agents/skills` directory.
+     *
+     * @remarks
+     * When `false` (the default) and `~/.agents/skills` is a non-empty real
+     * directory, the command refuses with `E_AGENTS_SKILLS_REAL_DIR` to preserve
+     * user data. When `true`, the directory is moved to
+     * `~/.cleo/backups/agents-skills-pre-bridge-<ts>/` before the bridge symlink
+     * is created.
+     *
+     * @defaultValue `false`
+     */
+    force?: boolean;
+    /**
+     * Plan-only mode. When `true`, no disk state is mutated; the result still
+     * lists what WOULD happen.
+     *
+     * @defaultValue `false`
+     */
+    dryRun?: boolean;
+}
+/**
+ * Error thrown when {@link runDoctorBridge} refuses to clobber a real
+ * `~/.agents/skills` directory and `--force` was not passed.
+ *
+ * @public
+ */
+declare class AgentsSkillsRealDirError extends Error {
+    /** LAFS error code surfaced by the CLI. */
+    readonly code: "E_AGENTS_SKILLS_REAL_DIR";
+    /** Resolved path of the offending real directory. */
+    readonly agentsSkillsPath: string;
+    /** Number of immediate entries in the offending directory. */
+    readonly entryCount: number;
+    /**
+     * Construct an `AgentsSkillsRealDirError`.
+     *
+     * @param agentsSkillsPath - Path to the real `~/.agents/skills` directory.
+     * @param entryCount - Number of entries inside the directory.
+     */
+    constructor(agentsSkillsPath: string, entryCount: number);
+}
+/**
+ * Generate a deterministic backup-suffix timestamp `YYYYMMDD-HHmmss` (UTC).
+ *
+ * @remarks
+ * Pulled out as a helper so callers (and tests) can deterministically compute
+ * the expected backup path without re-implementing the format. The string is
+ * UTC so backups taken on different machines round-trip identically.
+ *
+ * @returns Timestamp suffix string for backup directory naming.
+ */
+declare function buildBackupTimestamp(): string;
+/**
+ * Execute the bridge flow described in the module docblock.
+ *
+ * @remarks
+ * Order of operations:
+ *
+ * 1. Ensure `~/.claude/skills/agents-shared/` exists.
+ * 2. For each skill in `~/.cleo/skills/`, ensure
+ *    `~/.claude/skills/agents-shared/<name>` → `~/.cleo/skills/<name>` exists.
+ * 3. Rip every per-skill entry under `~/.claude/skills/` that is a symlink
+ *    pointing OUTSIDE `agents-shared/` — those are orphans from the old
+ *    per-skill fan-out model and must be deleted.
+ * 4. Replace `~/.agents/skills` with a symlink to `~/.claude/skills/agents-shared`.
+ *    If it is currently a real directory, refuse unless `options.force` is
+ *    `true`, in which case back up to
+ *    `~/.cleo/backups/agents-skills-pre-bridge-<ts>/` first.
+ *
+ * Idempotency invariant: re-running on a fully-bridged tree returns
+ * `{ bridgeCreated: false, bridgeSymlinkActive: true, perSkillSymlinksCreated: [], perSkillSymlinksRemoved: [], backupPath: null }`.
+ *
+ * @param options - Dependency-injected options (homeDir / force / dry-run).
+ * @returns Materialized {@link DoctorBridgeResult} reflecting the run.
+ * @throws AgentsSkillsRealDirError when `~/.agents/skills` is a non-empty real
+ *   directory and `options.force` is not set.
+ *
+ * @example
+ * ```typescript
+ * import { runDoctorBridge } from '@cleocode/caamp';
+ *
+ * const result = await runDoctorBridge({ homeDir: '/tmp/test-home' });
+ * console.log(result.perSkillSymlinksCreated.length); // # of new bridge symlinks
+ * ```
+ *
+ * @public
+ */
+declare function runDoctorBridge(options?: DoctorBridgeOptions): Promise<DoctorBridgeResult>;
+
 /**
  * Priority tier identifier stored in registry.json.
  *
@@ -3002,10 +3533,103 @@ declare function removeConfig(filePath: string, format: ConfigFormat, key: strin
 /**
  * Skill installer - canonical + symlink model
  *
- * Skills are stored once in a canonical location (.agents/skills/<name>/)
- * and symlinked to each target agent's skills directory.
+ * Skills are stored once in a canonical location (`~/.cleo/skills/<name>/`
+ * per architecture-v3 §1, with legacy `~/.local/share/agents/skills/` as a
+ * read-only fallback for one release cycle) and symlinked to each target
+ * agent's skills directory.
+ *
+ * @task T9659
+ * @epic T9571
+ * @saga T9560
  */
 
+/**
+ * Source-type discriminator emitted with {@link SkillRowData}.
+ *
+ * @remarks
+ * Mirrors the `source_type` column on the `skills` table defined in
+ * architecture-v3 §4. Kept as a local string-literal union (NOT a
+ * `@cleocode/core` import) so caamp stays free of a circular dep on core —
+ * the dispatch layer in `packages/cleo/` is responsible for plugging the
+ * `upsertSkillRow` callback that consumes this shape.
+ *
+ * @public
+ */
+type SkillRowSourceType = 'canonical' | 'user' | 'community' | 'agent-created';
+/**
+ * Provenance payload emitted by {@link installSkill} after a successful copy.
+ *
+ * @remarks
+ * The CAAMP installer ONLY emits this shape — it never writes to
+ * `skills.db` directly. The dispatch layer in `packages/cleo/` (where it's
+ * legal to import from `@cleocode/core`) plugs an `upsertSkillRow` callback
+ * via {@link InstallSkillOptions.recordRow}. This keeps caamp free of a
+ * `@cleocode/core` dependency (mirrors the migration callback pattern
+ * established by T9653 — see `migration.ts`).
+ *
+ * @public
+ */
+interface SkillRowData {
+    /** Skill folder basename (matches `skills.name` column). */
+    name: string;
+    /** Resolved canonical install path under `~/.cleo/skills/<name>/`. */
+    installPath: string;
+    /** Source URL or identifier (matches `skills.source_url`). */
+    sourceUrl: string | null;
+    /**
+     * Source provenance discriminator (matches `skills.source_type`).
+     *
+     * @remarks
+     * Set to `'canonical'` for skills whose name appears in the bundled
+     * Sphere A manifest; `'community'` for marketplace / GitHub-clone installs;
+     * `'user'` for everything else (local-path installs, library installs).
+     * Architecture-v3 §4 enumerates the full set.
+     */
+    sourceType: SkillRowSourceType;
+}
+/**
+ * Optional knobs accepted by {@link installSkill}.
+ *
+ * @remarks
+ * Encoded as an interface so future T-STORE follow-ups (e.g. `pinned`,
+ * `version`) can be added without churning the call sites.
+ *
+ * @public
+ */
+interface InstallSkillOptions {
+    /**
+     * Per-install sink invoked after a successful canonical copy.
+     *
+     * @remarks
+     * Caamp NEVER imports `@cleocode/core` directly — the dispatch layer in
+     * `packages/cleo/` plugs `upsertSkillRow` here so installs are recorded
+     * to `~/.cleo/skills.db`. Defaults to a no-op when omitted. May be sync
+     * or async; thrown errors propagate to the caller.
+     */
+    recordRow?: (row: SkillRowData) => Promise<void> | void;
+    /**
+     * Explicit `sourceUrl` to record on the row.
+     *
+     * @remarks
+     * When omitted, falls back to the `sourcePath` argument. Callers that
+     * resolve a library or marketplace identifier (e.g. `library:ct-foo` or
+     * `https://github.com/owner/repo`) BEFORE copying to a tmpdir should set
+     * this so the row preserves the original provenance string instead of
+     * the disposable filesystem path.
+     */
+    sourceUrl?: string | null;
+    /**
+     * Explicit `sourceType` to record on the row.
+     *
+     * @remarks
+     * When omitted, the type is heuristically inferred from
+     * {@link InstallSkillOptions.sourceUrl} (or `sourcePath` as a fallback)
+     * via {@link inferSkillSourceType}. Dispatch-layer callers that know the
+     * authoritative provenance (e.g. catalog → `'canonical'`, GitHub URL →
+     * `'community'`) SHOULD set this explicitly to bypass the heuristic.
+     */
+    sourceType?: SkillRowSourceType;
+}
 /**
  * Result of installing a skill to the canonical location and linking to agents.
  *
@@ -3032,6 +3656,29 @@ interface SkillInstallResult {
     /** Whether at least one agent was successfully linked. */
     success: boolean;
 }
+/**
+ * Heuristic source-type classifier for installs that don't carry an explicit
+ * `source_type`.
+ *
+ * @remarks
+ * Pure string inspection — keeps the installer free of network calls and
+ * filesystem reads. The dispatch layer can ALWAYS override the result by
+ * passing an explicit row through {@link InstallSkillOptions.recordRow}.
+ *
+ * Classification rules:
+ *
+ * 1. `library:<name>` → `'canonical'` (installed from the bundled Sphere A
+ *    skill library — `packages/skills/skills/`).
+ * 2. `github.com` / `gitlab.com` / scoped `@author/name` → `'community'`.
+ * 3. Anything else (local paths, opaque values) → `'user'`.
+ *
+ * @param sourceUrl - The source identifier passed to {@link installSkill}.
+ *   `null` is treated as `'user'`.
+ * @returns The inferred source-type discriminator.
+ *
+ * @public
+ */
+declare function inferSkillSourceType(sourceUrl: string | null | undefined): SkillRowSourceType;
 /**
  * Install a skill from a local path to the canonical location and link to agents.
  *
@@ -3039,24 +3686,45 @@ interface SkillInstallResult {
  * Copies the skill directory to the canonical skills directory and creates symlinks
  * (or copies on Windows) from each provider's skills directory to the canonical path.
  *
+ * **T9659** — when `options.recordRow` is supplied, the callback is invoked
+ * with a {@link SkillRowData} payload after the canonical copy lands and
+ * BEFORE provider linking. This is the integration seam that the cleo
+ * dispatch layer uses to plug `upsertSkillRow` from
+ * `@cleocode/core/store/skills-db` into `~/.cleo/skills.db`. The row is
+ * recorded regardless of whether subsequent provider linking succeeds — the
+ * canonical install is itself the durable artefact.
+ *
  * @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()`)
+ * @param options - Optional callbacks (incl. `recordRow` for `skills.db`)
  * @returns Install result with linked agents and any errors
  *
  * @example
  * ```typescript
- * const result = await installSkill("/tmp/my-skill", "my-skill", providers, true, "/my/project");
- * if (result.success) {
- *   console.log(`Linked to: ${result.linkedAgents.join(", ")}`);
- * }
+ * const result = await installSkill(
+ *   "/tmp/my-skill",
+ *   "my-skill",
+ *   providers,
+ *   true,
+ *   "/my/project",
+ *   {
+ *     recordRow: async (row) => upsertSkillRow({
+ *       name: row.name,
+ *       installPath: row.installPath,
+ *       sourceType: row.sourceType,
+ *       sourceUrl: row.sourceUrl,
+ *       installedAt: new Date().toISOString(),
+ *     }),
+ *   },
+ * );
  * ```
  *
  * @public
  */
-declare function installSkill(sourcePath: string, skillName: string, providers: Provider[], isGlobal: boolean, projectDir?: string): Promise<SkillInstallResult>;
+declare function installSkill(sourcePath: string, skillName: string, providers: Provider[], isGlobal: boolean, projectDir?: string, options?: InstallSkillOptions): Promise<SkillInstallResult>;
 /**
  * Remove a skill from the canonical location and all agent symlinks.
  *
@@ -5630,20 +6298,73 @@ declare function getAgentsHome(): string;
  * @public
  */
 declare function getProjectAgentsDir(projectRoot?: string): string;
+/**
+ * Reset the cached deprecation-warning flag.
+ *
+ * @remarks
+ * Test-only seam. Production code should never call this.
+ *
+ * @internal
+ */
+declare function _resetLegacySkillsWarning(): void;
+/**
+ * Returns the canonical user-machine skills install root.
+ *
+ * @remarks
+ * Per architecture-v3 §1 the new SSoT for ALL installed skills is
+ * `~/.cleo/skills/` (replacing the legacy XDG path
+ * `~/.local/share/agents/skills/`). This resolver implements the migration
+ * contract: it ALWAYS returns the new SSoT when it exists, falls through to
+ * the legacy path as a read-only fallback for one release cycle, and
+ * defaults to the new SSoT on a fresh install so first-write lands in the
+ * correct location.
+ *
+ * Resolution order:
+ *
+ * 1. `~/.cleo/skills/` (new SSoT — preferred). Returned when it exists.
+ * 2. `getAgentsHome()/skills` (legacy XDG via `AGENTS_HOME` /
+ *    `~/.local/share/agents/skills/`). Returned when the new SSoT is missing
+ *    but the legacy directory exists. Emits a one-shot stderr deprecation
+ *    warning so the user is prompted to migrate.
+ * 3. `~/.cleo/skills/` (new SSoT) on a fresh install when neither exists,
+ *    so first-write creates the correct directory.
+ *
+ * **Test override:** when the `AGENTS_HOME` env var is set explicitly (the
+ * primary test seam used by `skills-installer.test.ts`), the resolver SKIPS
+ * step 1 and returns `getAgentsHome()/skills` directly. This preserves the
+ * existing test surface (tmpdirs via `AGENTS_HOME`) while production paths
+ * resolve through the new SSoT chain.
+ *
+ * @returns Absolute path to the resolved canonical skills directory
+ *
+ * @example
+ * ```typescript
+ * const dir = getCanonicalSkillsRoot();
+ * // Fresh install:                  "/home/user/.cleo/skills"
+ * // Legacy install + warning:       "/home/user/.local/share/agents/skills"
+ * // Test (AGENTS_HOME=/tmp/foo):    "/tmp/foo/skills"
+ * ```
+ *
+ * @task T9659
+ * @public
+ */
+declare function getCanonicalSkillsRoot(): string;
 /**
  * Returns the canonical skills storage directory path.
  *
  * @remarks
  * Skills are stored once in this canonical directory and symlinked into
  * provider-specific locations. This is the single source of truth for
- * installed skill files.
+ * installed skill files. **T9659 — this now delegates to
+ * {@link getCanonicalSkillsRoot} so the SSoT is `~/.cleo/skills/` with the
+ * legacy XDG path as a read-only fallback per architecture-v3 §1.**
  *
  * @returns The absolute path to the canonical skills directory
  *
  * @example
  * ```typescript
  * const dir = getCanonicalSkillsDir();
- * // e.g., "/home/user/.local/share/caamp/skills"
+ * // e.g., "/home/user/.cleo/skills" (new SSoT)
  * ```
  *
  * @public
@@ -8331,4 +9052,4 @@ declare function parseSource(input: string): ParsedSource;
  */
 declare function isMarketplaceScoped(input: string): boolean;
 
-export { type AuditFinding, type AuditResult, type AuditRule, type AuditSeverity, type BatchInstallOptions, type BatchInstallResult, CANONICAL_HOOK_EVENTS, type CaampBlock, type CaampLockFile, type CanonicalEventDefinition, type CanonicalHookEvent, type CantProfileCounts, type CantProfileEntry, type CantValidationDiagnostic, type ConfigFormat, type CrossProviderMatrix, type CtDispatchMatrix, type CtManifest, type CtManifestSkill, type CtProfileDefinition, type CtSkillEntry, type CtValidationIssue, type CtValidationResult, DEFAULT_EXCLUSIVITY_MODE, type DedupeResult, type DetectionCacheOptions, type DetectionResult, EXCLUSIVITY_MODE_ENV_VAR, type EnsureProviderInstructionFileOptions, type EnsureProviderInstructionFileResult, type ExclusivityMode, type GlobalOptions, HOOK_CATEGORIES, type Harness, type HarnessScope, type HookCategory, type HookEvent, type HookHandlerType, type HookMapping, type HookSupportResult, type HookSystemType, type InjectionCheckResult, type InjectionStatus, type InjectionTemplate, type InstallMcpServerOptions, type InstallMcpServerResult, type InstructionUpdateSummary, type KnownProviderAgentFolderId, type LockEntry, MarketplaceClient, type MarketplaceResult, type MarketplaceSearchResult, type MarketplaceSkill, type McpConfigFormat, type McpDetectionEntry, type McpScope, type McpServerConfig, type McpServerEntriesByProvider, type McpServerEntry, type McpTransportType, type NormalizedHookEvent, type NormalizedRecommendationCriteria, type ParsedSource, PiHarness, PiRequiredError, type Provider, type ProviderCapabilities, type ProviderHarnessCapability, type ProviderHookProfile, type ProviderHookSummary, type ProviderHooksCapability, type ProviderMcpCapability, type ProviderPriority, type ProviderSkillsCapability, type ProviderSpawnCapability, type ProviderStatus, RECOMMENDATION_ERROR_CODES, type RankedSkillRecommendation, type RecommendSkillsResult, type RecommendationCriteriaInput, type RecommendationErrorCode, type RecommendationOptions, type RecommendationReason, type RecommendationReasonCode, type RecommendationScoreBreakdown, type RecommendationValidationIssue, type RecommendationValidationResult, type RecommendationWeights, type RegistryHarnessKind, type RegistryHookCatalog, type RegistryHookFormat, type RemoveMcpServerOptions, type RemoveMcpServerResult, type ResolveDefaultTargetProvidersOptions, type SkillBatchOperation, type SkillEntry, type SkillInstallResult, type SkillIntegrityResult, type SkillIntegrityStatus, type SkillLibrary, type SkillLibraryDispatchMatrix, type SkillLibraryEntry, type SkillLibraryManifest, type SkillLibraryManifestSkill, type SkillLibraryProfile, type SkillLibraryValidationIssue, type SkillLibraryValidationResult, type SkillMetadata, type SkillsPrecedence, type SourceType, type SpawnAdapter, type SpawnMechanism, type SpawnOptions, type SpawnResult, type SubagentHandle, type SubagentResult, type SubagentTask, type TransportType, type ValidateCantProfileResult, type ValidationIssue, type ValidationResult, type WriteAgentFileOptions, type WriteAgentFileResult, _resetPlatformPathsCache, buildHookMatrix, buildInjectionContent, buildLibraryFromFiles, buildSkillsMap, catalog, checkAllInjections, checkAllSkillIntegrity, checkAllSkillUpdates, checkInjection, checkSkillIntegrity, checkSkillUpdate, clearRegisteredLibrary, dedupeFile, dedupeFiles, deepMerge, detectAllProviders, detectMcpInstallations, detectProjectProviders, detectProvider, discoverSkill, discoverSkills, ensureAllProviderInstructionFiles, ensureDir, ensureProviderInstructionFile, formatSkillRecommendations, generateInjectionContent, generateSkillsSection, getAgentsConfigPath, getAgentsHome, getAgentsInstructFile, getAgentsLinksDir, getAgentsMcpDir, getAgentsMcpServersPath, getAgentsSpecDir, getAgentsWikiDir, getAllCanonicalEvents, getAllHarnesses, getAllProviders, getCanonicalEvent, getCanonicalEventsByCategory, getCanonicalSkillsDir, getCommonEvents, getCommonHookEvents, getEffectiveSkillsPaths, getExclusivityMode, getHarnessFor, getHookConfigPath, getHookMappingsVersion, getHookSupport, getHookSystemType, getInstalledProviders, getInstructionFiles, getLockFilePath, getMappedProviderIds, getNestedValue, getPlatformLocations, getPlatformPaths, getPrimaryHarness, getPrimaryProvider, getProjectAgentsDir, getProvider, getProviderAgentFolder, getProviderCapabilities, getProviderCount, getProviderHookProfile, getProviderInstructionReferences, getProviderOnlyEvents, getProviderSummary, getProvidersByHookEvent, getProvidersByInstructFile, getProvidersByPriority, getProvidersBySkillsPrecedence, getProvidersBySpawnCapability, getProvidersByStatus, getProvidersForEvent, getRegistryVersion, getSpawnCapableProviders, getSupportedEvents, getSystemInfo, getTrackedSkills, getUnsupportedEvents, groupByInstructFile, inject, injectAll, installBatchWithRollback, installMcpServer, installSkill, isCaampOwnedSkill, isExclusivityMode, isMarketplaceScoped, isQuiet, isVerbose, listAllMcpServers, listCanonicalSkills, listMcpServers, loadLibraryFromModule, normalizeRecommendationCriteria, parseCaampBlocks, parseInjectionContent, parseSkillFile, parseSource, providerSupports, providerSupportsById, rankSkills, readConfig, recommendSkills, recordSkillInstall, registerSkillLibrary, registerSkillLibraryFromPath, removeConfig, removeInjection, removeMcpServer, removeMcpServerFromAll, removeSkill, removeSkillFromLock, resetDetectionCache, resetExclusivityModeOverride, resolveAlias, resolveDefaultTargetProviders, resolveMcpConfigPath, resolveNativeEvent, resolveProviderSkillsDirs, resolveRegistryTemplatePath, scanDirectory, scanFile, scoreSkillRecommendation, searchSkills, selectProvidersByMinimumPriority, setExclusivityMode, setQuiet, setVerbose, shouldOverrideSkill, supportsHook, toCanonical, toNative, toNativeBatch, toSarif, tokenizeCriteriaValue, translateToAll, updateInstructionsSingleOperation, validateInstructionIntegrity, validateRecommendationCriteria, validateSkill, writeAgentFileToAllProviders, writeConfig };
+export { type AdoptedSkillRowData, AgentsSkillsRealDirError, type AuditFinding, type AuditResult, type AuditRule, type AuditSeverity, type BatchInstallOptions, type BatchInstallResult, type BridgeSymlinkRecord, CANONICAL_HOOK_EVENTS, type CaampBlock, type CaampLockFile, type CanonicalEventDefinition, type CanonicalHookEvent, type CantProfileCounts, type CantProfileEntry, type CantValidationDiagnostic, type ConfigFormat, type CrossProviderMatrix, type CtDispatchMatrix, type CtManifest, type CtManifestSkill, type CtProfileDefinition, type CtSkillEntry, type CtValidationIssue, type CtValidationResult, DEFAULT_EXCLUSIVITY_MODE, type DedupeResult, type DetectionCacheOptions, type DetectionResult, type DoctorAdoptCliAdapters, type DoctorAdoptOptions, type DoctorAdoptResult, type DoctorBridgeOptions, type DoctorBridgeResult, EXCLUSIVITY_MODE_ENV_VAR, type EnsureProviderInstructionFileOptions, type EnsureProviderInstructionFileResult, type ExclusivityMode, type GlobalOptions, HOOK_CATEGORIES, type Harness, type HarnessScope, type HookCategory, type HookEvent, type HookHandlerType, type HookMapping, type HookSupportResult, type HookSystemType, type InjectionCheckResult, type InjectionStatus, type InjectionTemplate, type InstallMcpServerOptions, type InstallMcpServerResult, type InstallSkillOptions, type InstructionUpdateSummary, type KnownProviderAgentFolderId, type LockEntry, MarketplaceClient, type MarketplaceResult, type MarketplaceSearchResult, type MarketplaceSkill, type McpConfigFormat, type McpDetectionEntry, type McpScope, type McpServerConfig, type McpServerEntriesByProvider, type McpServerEntry, type McpTransportType, type NormalizedHookEvent, type NormalizedRecommendationCriteria, type OrphanActionResult, type OrphanDecision, type OrphanRecord, type OrphanRefusal, type ParsedSource, type PerSkillSymlinkRemoval, PiHarness, PiRequiredError, type Provider, type ProviderCapabilities, type ProviderHarnessCapability, type ProviderHookProfile, type ProviderHookSummary, type ProviderHooksCapability, type ProviderMcpCapability, type ProviderPriority, type ProviderSkillsCapability, type ProviderSpawnCapability, type ProviderStatus, RECOMMENDATION_ERROR_CODES, type RankedSkillRecommendation, type RecommendSkillsResult, type RecommendationCriteriaInput, type RecommendationErrorCode, type RecommendationOptions, type RecommendationReason, type RecommendationReasonCode, type RecommendationScoreBreakdown, type RecommendationValidationIssue, type RecommendationValidationResult, type RecommendationWeights, type RecordRowFn, type RegisteredNamesLoader, type RegistryHarnessKind, type RegistryHookCatalog, type RegistryHookFormat, type RemoveMcpServerOptions, type RemoveMcpServerResult, type ResolveDefaultTargetProvidersOptions, type SkillBatchOperation, type SkillEntry, type SkillInstallResult, type SkillIntegrityResult, type SkillIntegrityStatus, type SkillLibrary, type SkillLibraryDispatchMatrix, type SkillLibraryEntry, type SkillLibraryManifest, type SkillLibraryManifestSkill, type SkillLibraryProfile, type SkillLibraryValidationIssue, type SkillLibraryValidationResult, type SkillMetadata, type SkillRowData, type SkillRowSourceType, type SkillsPrecedence, type SourceType, type SpawnAdapter, type SpawnMechanism, type SpawnOptions, type SpawnResult, type SubagentHandle, type SubagentResult, type SubagentTask, type TransportType, type ValidateCantProfileResult, type ValidationIssue, type ValidationResult, type WriteAgentFileOptions, type WriteAgentFileResult, _resetLegacySkillsWarning, _resetPlatformPathsCache, applyDecision, buildBackupTimestamp, buildHookMatrix, buildInjectionContent, buildLibraryFromFiles, buildSkillsMap, caampStandaloneAdapters, catalog, checkAllInjections, checkAllSkillIntegrity, checkAllSkillUpdates, checkInjection, checkSkillIntegrity, checkSkillUpdate, clearRegisteredLibrary, dedupeFile, dedupeFiles, deepMerge, detectAllProviders, detectMcpInstallations, detectProjectProviders, detectProvider, discoverOrphans, discoverSkill, discoverSkills, ensureAllProviderInstructionFiles, ensureDir, ensureProviderInstructionFile, formatSkillRecommendations, generateInjectionContent, generateSkillsSection, getAgentsConfigPath, getAgentsHome, getAgentsInstructFile, getAgentsLinksDir, getAgentsMcpDir, getAgentsMcpServersPath, getAgentsSpecDir, getAgentsWikiDir, getAllCanonicalEvents, getAllHarnesses, getAllProviders, getCanonicalEvent, getCanonicalEventsByCategory, getCanonicalSkillsDir, getCanonicalSkillsRoot, getCommonEvents, getCommonHookEvents, getEffectiveSkillsPaths, getExclusivityMode, getHarnessFor, getHookConfigPath, getHookMappingsVersion, getHookSupport, getHookSystemType, getInstalledProviders, getInstructionFiles, getLockFilePath, getMappedProviderIds, getNestedValue, getPlatformLocations, getPlatformPaths, getPrimaryHarness, getPrimaryProvider, getProjectAgentsDir, getProvider, getProviderAgentFolder, getProviderCapabilities, getProviderCount, getProviderHookProfile, getProviderInstructionReferences, getProviderOnlyEvents, getProviderSummary, getProvidersByHookEvent, getProvidersByInstructFile, getProvidersByPriority, getProvidersBySkillsPrecedence, getProvidersBySpawnCapability, getProvidersByStatus, getProvidersForEvent, getRegistryVersion, getSpawnCapableProviders, getSupportedEvents, getSystemInfo, getTrackedSkills, getUnsupportedEvents, groupByInstructFile, inferSkillSourceType, inject, injectAll, installBatchWithRollback, installMcpServer, installSkill, isCaampOwnedSkill, isExclusivityMode, isMarketplaceScoped, isQuiet, isVerbose, listAllMcpServers, listCanonicalSkills, listMcpServers, loadLibraryFromModule, normalizeRecommendationCriteria, parseCaampBlocks, parseInjectionContent, parseSkillFile, parseSource, providerSupports, providerSupportsById, rankSkills, readConfig, recommendSkills, recordSkillInstall, registerSkillLibrary, registerSkillLibraryFromPath, registerSkillsDoctorAdopt, removeConfig, removeInjection, removeMcpServer, removeMcpServerFromAll, removeSkill, removeSkillFromLock, resetDetectionCache, resetExclusivityModeOverride, resolveAlias, resolveDefaultTargetProviders, resolveMcpConfigPath, resolveNativeEvent, resolveProviderSkillsDirs, resolveRegistryTemplatePath, runDoctorAdopt, runDoctorBridge, scanDirectory, scanFile, scoreSkillRecommendation, searchSkills, selectProvidersByMinimumPriority, setExclusivityMode, setQuiet, setVerbose, shouldOverrideSkill, supportsHook, toCanonical, toNative, toNativeBatch, toSarif, tokenizeCriteriaValue, translateToAll, updateInstructionsSingleOperation, validateInstructionIntegrity, validateRecommendationCriteria, validateSkill, writeAgentFileToAllProviders, writeAuditLog, writeConfig };