@axm.sh/cli 0.0.1

package/dist/src/extensions/skills/state/types.d.ts

@@ -0,0 +1,2022 @@
+/**
+ * State types for skills management - actual, locked, ideal, diff/plan.
+ *
+ * This module implements an Arborist-style state model where:
+ * - **Actual** state is what exists on disk
+ * - **Locked** state is what the lockfile says should exist
+ * - **Ideal** state is the desired state after an operation
+ * - **Diff/Plan** is the set of changes to transform actual to ideal
+ *
+ * See openspec/specs/plan-confirm-apply/spec.md for the reconciliation pattern.
+ *
+ * @experimental This API is unstable and may change without notice.
+ * @packageDocumentation
+ */
+import * as Option from "effect/Option";
+import * as Record from "effect/Record";
+import * as Schema from "effect/Schema";
+import type { SourceInput } from "../../../sources/types.js";
+/**
+ * Skill frontmatter parsed from SKILL.md.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export interface SkillFrontmatter {
+    readonly name: Option.Option<string>;
+    readonly description: Option.Option<string>;
+    readonly version: Option.Option<string>;
+    readonly triggers: Option.Option<readonly string[]>;
+}
+/**
+ * Schema for JSON serialization of SkillFrontmatter.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const SkillFrontmatterSchema: Schema.Struct<{
+    name: Schema.OptionFromNullOr<typeof Schema.String>;
+    description: Schema.OptionFromNullOr<typeof Schema.String>;
+    version: Schema.OptionFromNullOr<typeof Schema.String>;
+    triggers: Schema.OptionFromNullOr<Schema.Array$<typeof Schema.String>>;
+}>;
+/**
+ * Skill as it exists on disk at canonical location (.axm/skills/<name>/).
+ *
+ * The gitTreeFolderHash is the git tree hash of the skill folder, computed using
+ * git's tree object algorithm for deterministic, cross-platform hashing.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export interface ActualSkill {
+    readonly name: string;
+    readonly path: string;
+    readonly frontmatter: Option.Option<SkillFrontmatter>;
+    readonly content: string;
+    readonly gitTreeFolderHash: string;
+    readonly files: readonly string[];
+    readonly lastModified: Date;
+}
+/**
+ * Schema for JSON serialization of ActualSkill.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const ActualSkillSchema: Schema.Struct<{
+    name: typeof Schema.String;
+    path: typeof Schema.String;
+    frontmatter: Schema.OptionFromNullOr<Schema.Struct<{
+        name: Schema.OptionFromNullOr<typeof Schema.String>;
+        description: Schema.OptionFromNullOr<typeof Schema.String>;
+        version: Schema.OptionFromNullOr<typeof Schema.String>;
+        triggers: Schema.OptionFromNullOr<Schema.Array$<typeof Schema.String>>;
+    }>>;
+    content: typeof Schema.String;
+    gitTreeFolderHash: typeof Schema.String;
+    files: Schema.Array$<typeof Schema.String>;
+    lastModified: typeof Schema.Date;
+}>;
+/**
+ * Skill entry from axm-lock.yaml.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export interface LockedSkill {
+    readonly source: string;
+    readonly origin: string;
+    readonly path: Option.Option<string>;
+    readonly ref: Option.Option<string>;
+    readonly version: Option.Option<string>;
+    readonly gitTreeFolderHash: string;
+    readonly agents: readonly string[];
+    readonly installedAt: Date;
+    readonly updatedAt: Date;
+}
+/**
+ * Schema for JSON serialization of LockedSkill.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const LockedSkillSchema: Schema.Struct<{
+    source: typeof Schema.String;
+    origin: typeof Schema.String;
+    path: Schema.OptionFromNullOr<typeof Schema.String>;
+    ref: Schema.OptionFromNullOr<typeof Schema.String>;
+    version: Schema.OptionFromNullOr<typeof Schema.String>;
+    gitTreeFolderHash: typeof Schema.String;
+    agents: Schema.Array$<typeof Schema.String>;
+    installedAt: typeof Schema.Date;
+    updatedAt: typeof Schema.Date;
+}>;
+/**
+ * Validity codes for stable identification in docs, automation, and suppression.
+ * Prefix determines severity: E = error, W = warning.
+ *
+ * Skills:
+ *   E001: MissingSkillMd - SKILL.md file not found
+ *   E002: InvalidFrontmatter - Frontmatter failed to parse
+ *   E003: NameMismatch - Frontmatter name differs from directory name
+ *   E004: Missing - In lockfile but not on disk
+ *   E005: HashMismatch - Disk contents differ from lockfile hash
+ *   E006: Incomplete - Partially installed (missing files)
+ *   W001: MissingDescription - No description in frontmatter
+ *   W002: Orphaned - On disk but not in lockfile
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export type SkillValidityCode = "E001" | "E002" | "E003" | "E004" | "E005" | "E006" | "W001" | "W002";
+/**
+ * Skill validity states as discriminated union.
+ * Each variant has a static code for identification.
+ * Severity derived from code prefix: E = error, W = warning.
+ *
+ * Use exhaustive switch statements for pattern matching:
+ * - TypeScript catches missing cases at compile time
+ * - No runtime overhead from tagged enum machinery
+ * - Simple inline checks: validity._tag === "Valid"
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export type SkillValidity = {
+    readonly _tag: "Valid";
+} | {
+    readonly _tag: "MissingSkillMd";
+    readonly code: "E001";
+    readonly path: string;
+} | {
+    readonly _tag: "InvalidFrontmatter";
+    readonly code: "E002";
+    readonly errors: readonly string[];
+} | {
+    readonly _tag: "NameMismatch";
+    readonly code: "E003";
+    readonly frontmatterName: string;
+    readonly directoryName: string;
+} | {
+    readonly _tag: "MissingDescription";
+    readonly code: "W001";
+} | {
+    readonly _tag: "Orphaned";
+    readonly code: "W002";
+} | {
+    readonly _tag: "Missing";
+    readonly code: "E004";
+    readonly expected: LockedSkill;
+} | {
+    readonly _tag: "HashMismatch";
+    readonly code: "E005";
+    readonly expected: string;
+    readonly actual: string;
+} | {
+    readonly _tag: "Incomplete";
+    readonly code: "E006";
+    readonly reason: string;
+} | {
+    readonly _tag: "Multiple";
+    readonly issues: readonly SkillValidity[];
+};
+/**
+ * Constructors for SkillValidity variants.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const SkillValidity: {
+    readonly Valid: () => SkillValidity;
+    readonly MissingSkillMd: (args: {
+        path: string;
+    }) => SkillValidity;
+    readonly InvalidFrontmatter: (args: {
+        errors: readonly string[];
+    }) => SkillValidity;
+    readonly NameMismatch: (args: {
+        frontmatterName: string;
+        directoryName: string;
+    }) => SkillValidity;
+    readonly MissingDescription: () => SkillValidity;
+    readonly Orphaned: () => SkillValidity;
+    readonly Missing: (args: {
+        expected: LockedSkill;
+    }) => SkillValidity;
+    readonly HashMismatch: (args: {
+        expected: string;
+        actual: string;
+    }) => SkillValidity;
+    readonly Incomplete: (args: {
+        reason: string;
+    }) => SkillValidity;
+    readonly Multiple: (args: {
+        issues: readonly SkillValidity[];
+    }) => SkillValidity;
+};
+/**
+ * Schema for JSON serialization of SkillValidity (excluding Missing to avoid recursive Option issue).
+ * Uses Union of TaggedStructs for cleaner syntax.
+ *
+ * Note: The Missing variant uses LockedSkillSchema which involves Option transformations,
+ * making the Encoded type different from the Type. We use separate encode/decode for JSON.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const SkillValiditySchema: Schema.Union<[Schema.TaggedStruct<"Valid", {}>, Schema.TaggedStruct<"MissingSkillMd", {
+    code: Schema.Literal<["E001"]>;
+    path: typeof Schema.String;
+}>, Schema.TaggedStruct<"InvalidFrontmatter", {
+    code: Schema.Literal<["E002"]>;
+    errors: Schema.Array$<typeof Schema.String>;
+}>, Schema.TaggedStruct<"NameMismatch", {
+    code: Schema.Literal<["E003"]>;
+    frontmatterName: typeof Schema.String;
+    directoryName: typeof Schema.String;
+}>, Schema.TaggedStruct<"MissingDescription", {
+    code: Schema.Literal<["W001"]>;
+}>, Schema.TaggedStruct<"Orphaned", {
+    code: Schema.Literal<["W002"]>;
+}>, Schema.TaggedStruct<"Missing", {
+    code: Schema.Literal<["E004"]>;
+    expected: Schema.Struct<{
+        source: typeof Schema.String;
+        origin: typeof Schema.String;
+        path: Schema.OptionFromNullOr<typeof Schema.String>;
+        ref: Schema.OptionFromNullOr<typeof Schema.String>;
+        version: Schema.OptionFromNullOr<typeof Schema.String>;
+        gitTreeFolderHash: typeof Schema.String;
+        agents: Schema.Array$<typeof Schema.String>;
+        installedAt: typeof Schema.Date;
+        updatedAt: typeof Schema.Date;
+    }>;
+}>, Schema.TaggedStruct<"HashMismatch", {
+    code: Schema.Literal<["E005"]>;
+    expected: typeof Schema.String;
+    actual: typeof Schema.String;
+}>, Schema.TaggedStruct<"Incomplete", {
+    code: Schema.Literal<["E006"]>;
+    reason: typeof Schema.String;
+}>, Schema.TaggedStruct<"Multiple", {
+    issues: Schema.Array$<Schema.suspend<SkillValidity, SkillValidity, never>>;
+}>]>;
+/**
+ * Validity severity levels.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export type ValiditySeverity = "error" | "warning" | "info";
+/**
+ * Derive severity from validity code prefix.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const severityFromCode: (code: SkillValidityCode) => ValiditySeverity;
+/**
+ * Extract code from validity (Valid has no code). Uses exhaustive switch.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const getValidityCode: (v: SkillValidity) => SkillValidityCode | null;
+/**
+ * Issue severity levels.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export type Severity = "error" | "warning";
+/**
+ * Schema for issue severity.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const SeveritySchema: Schema.Literal<["error", "warning"]>;
+/**
+ * Issues specific to a skill on disk.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export type ActualSkillIssue = {
+    readonly _tag: "MissingSkillMd";
+    readonly path: string;
+    readonly severity: "error";
+} | {
+    readonly _tag: "InvalidFrontmatter";
+    readonly errors: ReadonlyArray<string>;
+    readonly severity: "error";
+} | {
+    readonly _tag: "MissingDescription";
+    readonly severity: "warning";
+};
+/**
+ * Constructors for ActualSkillIssue variants.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const ActualSkillIssue: {
+    readonly MissingSkillMd: (args: {
+        path: string;
+    }) => ActualSkillIssue;
+    readonly InvalidFrontmatter: (args: {
+        errors: ReadonlyArray<string>;
+    }) => ActualSkillIssue;
+    readonly MissingDescription: () => ActualSkillIssue;
+};
+/**
+ * Schema for ActualSkillIssue.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const ActualSkillIssueSchema: Schema.Union<[Schema.TaggedStruct<"MissingSkillMd", {
+    path: typeof Schema.String;
+    severity: Schema.Literal<["error"]>;
+}>, Schema.TaggedStruct<"InvalidFrontmatter", {
+    errors: Schema.Array$<typeof Schema.String>;
+    severity: Schema.Literal<["error"]>;
+}>, Schema.TaggedStruct<"MissingDescription", {
+    severity: Schema.Literal<["warning"]>;
+}>]>;
+/**
+ * Issues from comparing actual vs locked state.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export type SkillStateIssue = {
+    readonly _tag: "MissingFromDisk";
+    readonly name: string;
+    readonly severity: "error";
+} | {
+    readonly _tag: "NotInLockfile";
+    readonly name: string;
+    readonly severity: "warning";
+};
+/**
+ * Constructors for SkillStateIssue variants.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const SkillStateIssue: {
+    readonly MissingFromDisk: (args: {
+        name: string;
+    }) => SkillStateIssue;
+    readonly NotInLockfile: (args: {
+        name: string;
+    }) => SkillStateIssue;
+};
+/**
+ * Schema for SkillStateIssue.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const SkillStateIssueSchema: Schema.Union<[Schema.TaggedStruct<"MissingFromDisk", {
+    name: typeof Schema.String;
+    severity: Schema.Literal<["error"]>;
+}>, Schema.TaggedStruct<"NotInLockfile", {
+    name: typeof Schema.String;
+    severity: Schema.Literal<["warning"]>;
+}>]>;
+/**
+ * Workspace-level issues spanning multiple skills.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export type WorkspaceIssue = {
+    readonly _tag: "DuplicateName";
+    readonly name: string;
+    readonly paths: ReadonlyArray<string>;
+    readonly severity: "error";
+} | {
+    readonly _tag: "OrphanedSettingsRef";
+    readonly agent: string;
+    readonly skill: string;
+    readonly severity: "warning";
+};
+/**
+ * Constructors for WorkspaceIssue variants.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const WorkspaceIssue: {
+    readonly DuplicateName: (args: {
+        name: string;
+        paths: ReadonlyArray<string>;
+    }) => WorkspaceIssue;
+    readonly OrphanedSettingsRef: (args: {
+        agent: string;
+        skill: string;
+    }) => WorkspaceIssue;
+};
+/**
+ * Schema for WorkspaceIssue.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const WorkspaceIssueSchema: Schema.Union<[Schema.TaggedStruct<"DuplicateName", {
+    name: typeof Schema.String;
+    paths: Schema.Array$<typeof Schema.String>;
+    severity: Schema.Literal<["error"]>;
+}>, Schema.TaggedStruct<"OrphanedSettingsRef", {
+    agent: typeof Schema.String;
+    skill: typeof Schema.String;
+    severity: Schema.Literal<["warning"]>;
+}>]>;
+/**
+ * Union of all issue types.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export type AnyIssue = ActualSkillIssue | SkillStateIssue | WorkspaceIssue;
+/**
+ * Schema for AnyIssue union.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const AnyIssueSchema: Schema.Union<[Schema.Union<[Schema.TaggedStruct<"MissingSkillMd", {
+    path: typeof Schema.String;
+    severity: Schema.Literal<["error"]>;
+}>, Schema.TaggedStruct<"InvalidFrontmatter", {
+    errors: Schema.Array$<typeof Schema.String>;
+    severity: Schema.Literal<["error"]>;
+}>, Schema.TaggedStruct<"MissingDescription", {
+    severity: Schema.Literal<["warning"]>;
+}>]>, Schema.Union<[Schema.TaggedStruct<"MissingFromDisk", {
+    name: typeof Schema.String;
+    severity: Schema.Literal<["error"]>;
+}>, Schema.TaggedStruct<"NotInLockfile", {
+    name: typeof Schema.String;
+    severity: Schema.Literal<["warning"]>;
+}>]>, Schema.Union<[Schema.TaggedStruct<"DuplicateName", {
+    name: typeof Schema.String;
+    paths: Schema.Array$<typeof Schema.String>;
+    severity: Schema.Literal<["error"]>;
+}>, Schema.TaggedStruct<"OrphanedSettingsRef", {
+    agent: typeof Schema.String;
+    skill: typeof Schema.String;
+    severity: Schema.Literal<["warning"]>;
+}>]>]>;
+export type { SourceInput } from "../../../sources/types.js";
+/**
+ * Skill as it exists on disk (V2 - with issues array).
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export interface ActualSkillV2 {
+    readonly name: string;
+    readonly path: string;
+    readonly files: ReadonlyArray<string>;
+    readonly frontmatter: Option.Option<SkillFrontmatter>;
+    readonly issues: ReadonlyArray<ActualSkillIssue>;
+}
+/**
+ * Schema for ActualSkillV2.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const ActualSkillV2Schema: Schema.Struct<{
+    name: typeof Schema.String;
+    path: typeof Schema.String;
+    files: Schema.Array$<typeof Schema.String>;
+    frontmatter: Schema.OptionFromNullOr<Schema.Struct<{
+        name: Schema.OptionFromNullOr<typeof Schema.String>;
+        description: Schema.OptionFromNullOr<typeof Schema.String>;
+        version: Schema.OptionFromNullOr<typeof Schema.String>;
+        triggers: Schema.OptionFromNullOr<Schema.Array$<typeof Schema.String>>;
+    }>>;
+    issues: Schema.Array$<Schema.Union<[Schema.TaggedStruct<"MissingSkillMd", {
+        path: typeof Schema.String;
+        severity: Schema.Literal<["error"]>;
+    }>, Schema.TaggedStruct<"InvalidFrontmatter", {
+        errors: Schema.Array$<typeof Schema.String>;
+        severity: Schema.Literal<["error"]>;
+    }>, Schema.TaggedStruct<"MissingDescription", {
+        severity: Schema.Literal<["warning"]>;
+    }>]>>;
+}>;
+/**
+ * Skill entry from lockfile (V2 - with Source and agents).
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export interface LockedSkillV2 {
+    readonly name: string;
+    readonly source: SourceInput;
+    readonly version: Option.Option<string>;
+    readonly gitTreeHash: Option.Option<string>;
+    readonly agents: ReadonlyArray<string>;
+    readonly installedAt: Date;
+    readonly updatedAt: Date;
+}
+/**
+ * Schema for LockedSkillV2.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const LockedSkillV2Schema: Schema.Struct<{
+    name: typeof Schema.String;
+    source: typeof Schema.Unknown;
+    version: Schema.OptionFromNullOr<typeof Schema.String>;
+    gitTreeHash: Schema.OptionFromNullOr<typeof Schema.String>;
+    agents: Schema.Array$<typeof Schema.String>;
+    installedAt: typeof Schema.Date;
+    updatedAt: typeof Schema.Date;
+}>;
+/**
+ * Combined state for a skill - actual + locked merged (V2 - with issues array).
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export interface SkillStateV2 {
+    readonly name: string;
+    readonly actual: Option.Option<ActualSkillV2>;
+    readonly locked: Option.Option<LockedSkillV2>;
+    readonly issues: ReadonlyArray<SkillStateIssue>;
+}
+/**
+ * Schema for SkillStateV2.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const SkillStateV2Schema: Schema.Struct<{
+    name: typeof Schema.String;
+    actual: Schema.OptionFromNullOr<Schema.Struct<{
+        name: typeof Schema.String;
+        path: typeof Schema.String;
+        files: Schema.Array$<typeof Schema.String>;
+        frontmatter: Schema.OptionFromNullOr<Schema.Struct<{
+            name: Schema.OptionFromNullOr<typeof Schema.String>;
+            description: Schema.OptionFromNullOr<typeof Schema.String>;
+            version: Schema.OptionFromNullOr<typeof Schema.String>;
+            triggers: Schema.OptionFromNullOr<Schema.Array$<typeof Schema.String>>;
+        }>>;
+        issues: Schema.Array$<Schema.Union<[Schema.TaggedStruct<"MissingSkillMd", {
+            path: typeof Schema.String;
+            severity: Schema.Literal<["error"]>;
+        }>, Schema.TaggedStruct<"InvalidFrontmatter", {
+            errors: Schema.Array$<typeof Schema.String>;
+            severity: Schema.Literal<["error"]>;
+        }>, Schema.TaggedStruct<"MissingDescription", {
+            severity: Schema.Literal<["warning"]>;
+        }>]>>;
+    }>>;
+    locked: Schema.OptionFromNullOr<Schema.Struct<{
+        name: typeof Schema.String;
+        source: typeof Schema.Unknown;
+        version: Schema.OptionFromNullOr<typeof Schema.String>;
+        gitTreeHash: Schema.OptionFromNullOr<typeof Schema.String>;
+        agents: Schema.Array$<typeof Schema.String>;
+        installedAt: typeof Schema.Date;
+        updatedAt: typeof Schema.Date;
+    }>>;
+    issues: Schema.Array$<Schema.Union<[Schema.TaggedStruct<"MissingFromDisk", {
+        name: typeof Schema.String;
+        severity: Schema.Literal<["error"]>;
+    }>, Schema.TaggedStruct<"NotInLockfile", {
+        name: typeof Schema.String;
+        severity: Schema.Literal<["warning"]>;
+    }>]>>;
+}>;
+/**
+ * Current workspace state - all skills with their actual/locked status (V2).
+ * Uses Array (not Record) to detect and report duplicate skill names on disk.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export interface CurrentState {
+    readonly skills: ReadonlyArray<SkillStateV2>;
+    readonly issues: ReadonlyArray<WorkspaceIssue>;
+}
+/**
+ * Schema for CurrentState.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const CurrentStateSchema: Schema.Struct<{
+    skills: Schema.Array$<Schema.Struct<{
+        name: typeof Schema.String;
+        actual: Schema.OptionFromNullOr<Schema.Struct<{
+            name: typeof Schema.String;
+            path: typeof Schema.String;
+            files: Schema.Array$<typeof Schema.String>;
+            frontmatter: Schema.OptionFromNullOr<Schema.Struct<{
+                name: Schema.OptionFromNullOr<typeof Schema.String>;
+                description: Schema.OptionFromNullOr<typeof Schema.String>;
+                version: Schema.OptionFromNullOr<typeof Schema.String>;
+                triggers: Schema.OptionFromNullOr<Schema.Array$<typeof Schema.String>>;
+            }>>;
+            issues: Schema.Array$<Schema.Union<[Schema.TaggedStruct<"MissingSkillMd", {
+                path: typeof Schema.String;
+                severity: Schema.Literal<["error"]>;
+            }>, Schema.TaggedStruct<"InvalidFrontmatter", {
+                errors: Schema.Array$<typeof Schema.String>;
+                severity: Schema.Literal<["error"]>;
+            }>, Schema.TaggedStruct<"MissingDescription", {
+                severity: Schema.Literal<["warning"]>;
+            }>]>>;
+        }>>;
+        locked: Schema.OptionFromNullOr<Schema.Struct<{
+            name: typeof Schema.String;
+            source: typeof Schema.Unknown;
+            version: Schema.OptionFromNullOr<typeof Schema.String>;
+            gitTreeHash: Schema.OptionFromNullOr<typeof Schema.String>;
+            agents: Schema.Array$<typeof Schema.String>;
+            installedAt: typeof Schema.Date;
+            updatedAt: typeof Schema.Date;
+        }>>;
+        issues: Schema.Array$<Schema.Union<[Schema.TaggedStruct<"MissingFromDisk", {
+            name: typeof Schema.String;
+            severity: Schema.Literal<["error"]>;
+        }>, Schema.TaggedStruct<"NotInLockfile", {
+            name: typeof Schema.String;
+            severity: Schema.Literal<["warning"]>;
+        }>]>>;
+    }>>;
+    issues: Schema.Array$<Schema.Union<[Schema.TaggedStruct<"DuplicateName", {
+        name: typeof Schema.String;
+        paths: Schema.Array$<typeof Schema.String>;
+        severity: Schema.Literal<["error"]>;
+    }>, Schema.TaggedStruct<"OrphanedSettingsRef", {
+        agent: typeof Schema.String;
+        skill: typeof Schema.String;
+        severity: Schema.Literal<["warning"]>;
+    }>]>>;
+}>;
+/**
+ * Desired skill after a command (V2 - with Source).
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export interface IdealSkillV2 {
+    readonly name: string;
+    readonly source: SourceInput;
+    readonly version: Option.Option<string>;
+    readonly gitTreeHash: Option.Option<string>;
+    readonly agents: ReadonlyArray<string>;
+}
+/**
+ * Constructor for IdealSkillV2.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const IdealSkillV2: {
+    readonly make: (args: {
+        name: string;
+        source: SourceInput;
+        version: Option.Option<string>;
+        gitTreeHash: Option.Option<string>;
+        agents: ReadonlyArray<string>;
+    }) => IdealSkillV2;
+};
+/**
+ * Alias for IdealSkillV2 constructor. Use IdealSkill.make() to create new IdealSkillV2 instances.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const IdealSkill: {
+    readonly make: (args: {
+        name: string;
+        source: SourceInput;
+        version: Option.Option<string>;
+        gitTreeHash: Option.Option<string>;
+        agents: ReadonlyArray<string>;
+    }) => IdealSkillV2;
+};
+/**
+ * Schema for IdealSkillV2.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const IdealSkillV2Schema: Schema.Struct<{
+    name: typeof Schema.String;
+    source: typeof Schema.Unknown;
+    version: Schema.OptionFromNullOr<typeof Schema.String>;
+    gitTreeHash: Schema.OptionFromNullOr<typeof Schema.String>;
+    agents: Schema.Array$<typeof Schema.String>;
+}>;
+/**
+ * Desired outcome - what we want after a command (V2).
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export interface IdealState {
+    readonly skills: ReadonlyArray<IdealSkillV2>;
+}
+/**
+ * Schema for IdealState (V2).
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const IdealStateV2Schema: Schema.Struct<{
+    skills: Schema.Array$<Schema.Struct<{
+        name: typeof Schema.String;
+        source: typeof Schema.Unknown;
+        version: Schema.OptionFromNullOr<typeof Schema.String>;
+        gitTreeHash: Schema.OptionFromNullOr<typeof Schema.String>;
+        agents: Schema.Array$<typeof Schema.String>;
+    }>>;
+}>;
+/**
+ * Complete state of a skill: actual + locked + computed validity.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export interface SkillState {
+    readonly name: string;
+    readonly actual: Option.Option<ActualSkill>;
+    readonly locked: Option.Option<LockedSkill>;
+    readonly validity: SkillValidity;
+}
+/**
+ * Schema for JSON serialization of SkillState.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const SkillStateSchema: Schema.Struct<{
+    name: typeof Schema.String;
+    actual: Schema.OptionFromNullOr<Schema.Struct<{
+        name: typeof Schema.String;
+        path: typeof Schema.String;
+        frontmatter: Schema.OptionFromNullOr<Schema.Struct<{
+            name: Schema.OptionFromNullOr<typeof Schema.String>;
+            description: Schema.OptionFromNullOr<typeof Schema.String>;
+            version: Schema.OptionFromNullOr<typeof Schema.String>;
+            triggers: Schema.OptionFromNullOr<Schema.Array$<typeof Schema.String>>;
+        }>>;
+        content: typeof Schema.String;
+        gitTreeFolderHash: typeof Schema.String;
+        files: Schema.Array$<typeof Schema.String>;
+        lastModified: typeof Schema.Date;
+    }>>;
+    locked: Schema.OptionFromNullOr<Schema.Struct<{
+        source: typeof Schema.String;
+        origin: typeof Schema.String;
+        path: Schema.OptionFromNullOr<typeof Schema.String>;
+        ref: Schema.OptionFromNullOr<typeof Schema.String>;
+        version: Schema.OptionFromNullOr<typeof Schema.String>;
+        gitTreeFolderHash: typeof Schema.String;
+        agents: Schema.Array$<typeof Schema.String>;
+        installedAt: typeof Schema.Date;
+        updatedAt: typeof Schema.Date;
+    }>>;
+    validity: Schema.Union<[Schema.TaggedStruct<"Valid", {}>, Schema.TaggedStruct<"MissingSkillMd", {
+        code: Schema.Literal<["E001"]>;
+        path: typeof Schema.String;
+    }>, Schema.TaggedStruct<"InvalidFrontmatter", {
+        code: Schema.Literal<["E002"]>;
+        errors: Schema.Array$<typeof Schema.String>;
+    }>, Schema.TaggedStruct<"NameMismatch", {
+        code: Schema.Literal<["E003"]>;
+        frontmatterName: typeof Schema.String;
+        directoryName: typeof Schema.String;
+    }>, Schema.TaggedStruct<"MissingDescription", {
+        code: Schema.Literal<["W001"]>;
+    }>, Schema.TaggedStruct<"Orphaned", {
+        code: Schema.Literal<["W002"]>;
+    }>, Schema.TaggedStruct<"Missing", {
+        code: Schema.Literal<["E004"]>;
+        expected: Schema.Struct<{
+            source: typeof Schema.String;
+            origin: typeof Schema.String;
+            path: Schema.OptionFromNullOr<typeof Schema.String>;
+            ref: Schema.OptionFromNullOr<typeof Schema.String>;
+            version: Schema.OptionFromNullOr<typeof Schema.String>;
+            gitTreeFolderHash: typeof Schema.String;
+            agents: Schema.Array$<typeof Schema.String>;
+            installedAt: typeof Schema.Date;
+            updatedAt: typeof Schema.Date;
+        }>;
+    }>, Schema.TaggedStruct<"HashMismatch", {
+        code: Schema.Literal<["E005"]>;
+        expected: typeof Schema.String;
+        actual: typeof Schema.String;
+    }>, Schema.TaggedStruct<"Incomplete", {
+        code: Schema.Literal<["E006"]>;
+        reason: typeof Schema.String;
+    }>, Schema.TaggedStruct<"Multiple", {
+        issues: Schema.Array$<Schema.suspend<SkillValidity, SkillValidity, never>>;
+    }>]>;
+}>;
+/**
+ * Skills stored as Record for O(1) lookups and immutable updates.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export interface SkillsState {
+    readonly skills: Readonly<Record.ReadonlyRecord<string, SkillState>>;
+}
+/**
+ * Schema for JSON serialization of SkillsState.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const SkillsStateSchema: Schema.Struct<{
+    skills: Schema.Record$<typeof Schema.String, Schema.Struct<{
+        name: typeof Schema.String;
+        actual: Schema.OptionFromNullOr<Schema.Struct<{
+            name: typeof Schema.String;
+            path: typeof Schema.String;
+            frontmatter: Schema.OptionFromNullOr<Schema.Struct<{
+                name: Schema.OptionFromNullOr<typeof Schema.String>;
+                description: Schema.OptionFromNullOr<typeof Schema.String>;
+                version: Schema.OptionFromNullOr<typeof Schema.String>;
+                triggers: Schema.OptionFromNullOr<Schema.Array$<typeof Schema.String>>;
+            }>>;
+            content: typeof Schema.String;
+            gitTreeFolderHash: typeof Schema.String;
+            files: Schema.Array$<typeof Schema.String>;
+            lastModified: typeof Schema.Date;
+        }>>;
+        locked: Schema.OptionFromNullOr<Schema.Struct<{
+            source: typeof Schema.String;
+            origin: typeof Schema.String;
+            path: Schema.OptionFromNullOr<typeof Schema.String>;
+            ref: Schema.OptionFromNullOr<typeof Schema.String>;
+            version: Schema.OptionFromNullOr<typeof Schema.String>;
+            gitTreeFolderHash: typeof Schema.String;
+            agents: Schema.Array$<typeof Schema.String>;
+            installedAt: typeof Schema.Date;
+            updatedAt: typeof Schema.Date;
+        }>>;
+        validity: Schema.Union<[Schema.TaggedStruct<"Valid", {}>, Schema.TaggedStruct<"MissingSkillMd", {
+            code: Schema.Literal<["E001"]>;
+            path: typeof Schema.String;
+        }>, Schema.TaggedStruct<"InvalidFrontmatter", {
+            code: Schema.Literal<["E002"]>;
+            errors: Schema.Array$<typeof Schema.String>;
+        }>, Schema.TaggedStruct<"NameMismatch", {
+            code: Schema.Literal<["E003"]>;
+            frontmatterName: typeof Schema.String;
+            directoryName: typeof Schema.String;
+        }>, Schema.TaggedStruct<"MissingDescription", {
+            code: Schema.Literal<["W001"]>;
+        }>, Schema.TaggedStruct<"Orphaned", {
+            code: Schema.Literal<["W002"]>;
+        }>, Schema.TaggedStruct<"Missing", {
+            code: Schema.Literal<["E004"]>;
+            expected: Schema.Struct<{
+                source: typeof Schema.String;
+                origin: typeof Schema.String;
+                path: Schema.OptionFromNullOr<typeof Schema.String>;
+                ref: Schema.OptionFromNullOr<typeof Schema.String>;
+                version: Schema.OptionFromNullOr<typeof Schema.String>;
+                gitTreeFolderHash: typeof Schema.String;
+                agents: Schema.Array$<typeof Schema.String>;
+                installedAt: typeof Schema.Date;
+                updatedAt: typeof Schema.Date;
+            }>;
+        }>, Schema.TaggedStruct<"HashMismatch", {
+            code: Schema.Literal<["E005"]>;
+            expected: typeof Schema.String;
+            actual: typeof Schema.String;
+        }>, Schema.TaggedStruct<"Incomplete", {
+            code: Schema.Literal<["E006"]>;
+            reason: typeof Schema.String;
+        }>, Schema.TaggedStruct<"Multiple", {
+            issues: Schema.Array$<Schema.suspend<SkillValidity, SkillValidity, never>>;
+        }>]>;
+    }>>;
+}>;
+/**
+ * Skill source types as discriminated union.
+ * Use exhaustive switch for pattern matching.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export type SkillSource = {
+    readonly _tag: "Local";
+    readonly path: string;
+} | {
+    readonly _tag: "Git";
+    readonly url: string;
+    readonly ref: Option.Option<string>;
+    readonly subpath: Option.Option<string>;
+} | {
+    readonly _tag: "Registry";
+    readonly name: string;
+    readonly version: string;
+};
+/**
+ * Constructors for SkillSource variants.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const SkillSource: {
+    readonly Local: (args: {
+        path: string;
+    }) => SkillSource;
+    readonly Git: (args: {
+        url: string;
+        ref: Option.Option<string>;
+        subpath: Option.Option<string>;
+    }) => SkillSource;
+    readonly Registry: (args: {
+        name: string;
+        version: string;
+    }) => SkillSource;
+};
+/**
+ * Schema for JSON serialization of SkillSource.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const SkillSourceSchema: Schema.Union<[Schema.TaggedStruct<"Local", {
+    path: typeof Schema.String;
+}>, Schema.TaggedStruct<"Git", {
+    url: typeof Schema.String;
+    ref: Schema.OptionFromNullOr<typeof Schema.String>;
+    subpath: Schema.OptionFromNullOr<typeof Schema.String>;
+}>, Schema.TaggedStruct<"Registry", {
+    name: typeof Schema.String;
+    version: typeof Schema.String;
+}>]>;
+/**
+ * Desired state for a skill after an operation (legacy interface).
+ *
+ * The source field serves dual purpose:
+ * 1. Where to fetch the skill from (for install/update)
+ * 2. What to write to settings.json (the settings entry value)
+ *
+ * @deprecated Use IdealSkillV2 for the new reconciliation design.
+ * @experimental This API is unstable and may change without notice.
+ */
+export interface IdealSkillLegacy {
+    readonly name: string;
+    readonly source: SkillSource;
+    readonly gitTreeFolderHash: string;
+    readonly description: Option.Option<string>;
+    readonly agents: readonly string[];
+}
+/**
+ * Type alias for legacy code that uses IdealSkill as a type.
+ * Also provides IdealSkill.make() for creating V2 instances.
+ *
+ * @deprecated Use IdealSkillV2 for the new reconciliation design.
+ * @experimental This API is unstable and may change without notice.
+ */
+export type IdealSkillType = IdealSkillLegacy;
+/**
+ * Schema for JSON serialization of IdealSkillLegacy.
+ *
+ * @deprecated Use IdealSkillSchema for the new reconciliation design.
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const IdealSkillLegacySchema: Schema.Struct<{
+    name: typeof Schema.String;
+    source: Schema.Union<[Schema.TaggedStruct<"Local", {
+        path: typeof Schema.String;
+    }>, Schema.TaggedStruct<"Git", {
+        url: typeof Schema.String;
+        ref: Schema.OptionFromNullOr<typeof Schema.String>;
+        subpath: Schema.OptionFromNullOr<typeof Schema.String>;
+    }>, Schema.TaggedStruct<"Registry", {
+        name: typeof Schema.String;
+        version: typeof Schema.String;
+    }>]>;
+    gitTreeFolderHash: typeof Schema.String;
+    description: Schema.OptionFromNullOr<typeof Schema.String>;
+    agents: Schema.Array$<typeof Schema.String>;
+}>;
+/**
+ * Ideal skills state with skills to add/update and removals list (legacy).
+ *
+ * @deprecated Use IdealState for the new reconciliation design.
+ * @experimental This API is unstable and may change without notice.
+ */
+export interface IdealSkillsState {
+    readonly skills: Readonly<Record.ReadonlyRecord<string, IdealSkillLegacy>>;
+    readonly removals: readonly string[];
+}
+/**
+ * Schema for JSON serialization of IdealSkillsState (legacy).
+ *
+ * @deprecated Use IdealStateSchema for the new reconciliation design.
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const IdealSkillsStateSchema: Schema.Struct<{
+    skills: Schema.Record$<typeof Schema.String, Schema.Struct<{
+        name: typeof Schema.String;
+        source: Schema.Union<[Schema.TaggedStruct<"Local", {
+            path: typeof Schema.String;
+        }>, Schema.TaggedStruct<"Git", {
+            url: typeof Schema.String;
+            ref: Schema.OptionFromNullOr<typeof Schema.String>;
+            subpath: Schema.OptionFromNullOr<typeof Schema.String>;
+        }>, Schema.TaggedStruct<"Registry", {
+            name: typeof Schema.String;
+            version: typeof Schema.String;
+        }>]>;
+        gitTreeFolderHash: typeof Schema.String;
+        description: Schema.OptionFromNullOr<typeof Schema.String>;
+        agents: Schema.Array$<typeof Schema.String>;
+    }>>;
+    removals: Schema.Array$<typeof Schema.String>;
+}>;
+/**
+ * Skill change types as discriminated union (legacy).
+ * Use exhaustive switch for pattern matching.
+ *
+ * @deprecated Use PlanStep for the new reconciliation design.
+ * @experimental This API is unstable and may change without notice.
+ */
+export type SkillChange = {
+    readonly _tag: "Add";
+    readonly skill: IdealSkillLegacy;
+} | {
+    readonly _tag: "Update";
+    readonly from: SkillState;
+    readonly to: IdealSkillLegacy;
+} | {
+    readonly _tag: "Remove";
+    readonly skill: SkillState;
+} | {
+    readonly _tag: "Unchanged";
+    readonly skill: SkillState;
+} | {
+    readonly _tag: "Repair";
+    readonly skill: SkillState;
+    readonly target: IdealSkillLegacy;
+};
+/**
+ * Constructors for SkillChange variants (legacy).
+ *
+ * @deprecated Use PlanStep for the new reconciliation design.
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const SkillChange: {
+    readonly Add: (args: {
+        skill: IdealSkillLegacy;
+    }) => SkillChange;
+    readonly Update: (args: {
+        from: SkillState;
+        to: IdealSkillLegacy;
+    }) => SkillChange;
+    readonly Remove: (args: {
+        skill: SkillState;
+    }) => SkillChange;
+    readonly Unchanged: (args: {
+        skill: SkillState;
+    }) => SkillChange;
+    readonly Repair: (args: {
+        skill: SkillState;
+        target: IdealSkillLegacy;
+    }) => SkillChange;
+};
+/**
+ * Schema for JSON serialization of SkillChange (legacy).
+ *
+ * @deprecated Use PlanStepSchema for the new reconciliation design.
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const SkillChangeSchema: Schema.Union<[Schema.TaggedStruct<"Add", {
+    skill: Schema.Struct<{
+        name: typeof Schema.String;
+        source: Schema.Union<[Schema.TaggedStruct<"Local", {
+            path: typeof Schema.String;
+        }>, Schema.TaggedStruct<"Git", {
+            url: typeof Schema.String;
+            ref: Schema.OptionFromNullOr<typeof Schema.String>;
+            subpath: Schema.OptionFromNullOr<typeof Schema.String>;
+        }>, Schema.TaggedStruct<"Registry", {
+            name: typeof Schema.String;
+            version: typeof Schema.String;
+        }>]>;
+        gitTreeFolderHash: typeof Schema.String;
+        description: Schema.OptionFromNullOr<typeof Schema.String>;
+        agents: Schema.Array$<typeof Schema.String>;
+    }>;
+}>, Schema.TaggedStruct<"Update", {
+    from: Schema.Struct<{
+        name: typeof Schema.String;
+        actual: Schema.OptionFromNullOr<Schema.Struct<{
+            name: typeof Schema.String;
+            path: typeof Schema.String;
+            frontmatter: Schema.OptionFromNullOr<Schema.Struct<{
+                name: Schema.OptionFromNullOr<typeof Schema.String>;
+                description: Schema.OptionFromNullOr<typeof Schema.String>;
+                version: Schema.OptionFromNullOr<typeof Schema.String>;
+                triggers: Schema.OptionFromNullOr<Schema.Array$<typeof Schema.String>>;
+            }>>;
+            content: typeof Schema.String;
+            gitTreeFolderHash: typeof Schema.String;
+            files: Schema.Array$<typeof Schema.String>;
+            lastModified: typeof Schema.Date;
+        }>>;
+        locked: Schema.OptionFromNullOr<Schema.Struct<{
+            source: typeof Schema.String;
+            origin: typeof Schema.String;
+            path: Schema.OptionFromNullOr<typeof Schema.String>;
+            ref: Schema.OptionFromNullOr<typeof Schema.String>;
+            version: Schema.OptionFromNullOr<typeof Schema.String>;
+            gitTreeFolderHash: typeof Schema.String;
+            agents: Schema.Array$<typeof Schema.String>;
+            installedAt: typeof Schema.Date;
+            updatedAt: typeof Schema.Date;
+        }>>;
+        validity: Schema.Union<[Schema.TaggedStruct<"Valid", {}>, Schema.TaggedStruct<"MissingSkillMd", {
+            code: Schema.Literal<["E001"]>;
+            path: typeof Schema.String;
+        }>, Schema.TaggedStruct<"InvalidFrontmatter", {
+            code: Schema.Literal<["E002"]>;
+            errors: Schema.Array$<typeof Schema.String>;
+        }>, Schema.TaggedStruct<"NameMismatch", {
+            code: Schema.Literal<["E003"]>;
+            frontmatterName: typeof Schema.String;
+            directoryName: typeof Schema.String;
+        }>, Schema.TaggedStruct<"MissingDescription", {
+            code: Schema.Literal<["W001"]>;
+        }>, Schema.TaggedStruct<"Orphaned", {
+            code: Schema.Literal<["W002"]>;
+        }>, Schema.TaggedStruct<"Missing", {
+            code: Schema.Literal<["E004"]>;
+            expected: Schema.Struct<{
+                source: typeof Schema.String;
+                origin: typeof Schema.String;
+                path: Schema.OptionFromNullOr<typeof Schema.String>;
+                ref: Schema.OptionFromNullOr<typeof Schema.String>;
+                version: Schema.OptionFromNullOr<typeof Schema.String>;
+                gitTreeFolderHash: typeof Schema.String;
+                agents: Schema.Array$<typeof Schema.String>;
+                installedAt: typeof Schema.Date;
+                updatedAt: typeof Schema.Date;
+            }>;
+        }>, Schema.TaggedStruct<"HashMismatch", {
+            code: Schema.Literal<["E005"]>;
+            expected: typeof Schema.String;
+            actual: typeof Schema.String;
+        }>, Schema.TaggedStruct<"Incomplete", {
+            code: Schema.Literal<["E006"]>;
+            reason: typeof Schema.String;
+        }>, Schema.TaggedStruct<"Multiple", {
+            issues: Schema.Array$<Schema.suspend<SkillValidity, SkillValidity, never>>;
+        }>]>;
+    }>;
+    to: Schema.Struct<{
+        name: typeof Schema.String;
+        source: Schema.Union<[Schema.TaggedStruct<"Local", {
+            path: typeof Schema.String;
+        }>, Schema.TaggedStruct<"Git", {
+            url: typeof Schema.String;
+            ref: Schema.OptionFromNullOr<typeof Schema.String>;
+            subpath: Schema.OptionFromNullOr<typeof Schema.String>;
+        }>, Schema.TaggedStruct<"Registry", {
+            name: typeof Schema.String;
+            version: typeof Schema.String;
+        }>]>;
+        gitTreeFolderHash: typeof Schema.String;
+        description: Schema.OptionFromNullOr<typeof Schema.String>;
+        agents: Schema.Array$<typeof Schema.String>;
+    }>;
+}>, Schema.TaggedStruct<"Remove", {
+    skill: Schema.Struct<{
+        name: typeof Schema.String;
+        actual: Schema.OptionFromNullOr<Schema.Struct<{
+            name: typeof Schema.String;
+            path: typeof Schema.String;
+            frontmatter: Schema.OptionFromNullOr<Schema.Struct<{
+                name: Schema.OptionFromNullOr<typeof Schema.String>;
+                description: Schema.OptionFromNullOr<typeof Schema.String>;
+                version: Schema.OptionFromNullOr<typeof Schema.String>;
+                triggers: Schema.OptionFromNullOr<Schema.Array$<typeof Schema.String>>;
+            }>>;
+            content: typeof Schema.String;
+            gitTreeFolderHash: typeof Schema.String;
+            files: Schema.Array$<typeof Schema.String>;
+            lastModified: typeof Schema.Date;
+        }>>;
+        locked: Schema.OptionFromNullOr<Schema.Struct<{
+            source: typeof Schema.String;
+            origin: typeof Schema.String;
+            path: Schema.OptionFromNullOr<typeof Schema.String>;
+            ref: Schema.OptionFromNullOr<typeof Schema.String>;
+            version: Schema.OptionFromNullOr<typeof Schema.String>;
+            gitTreeFolderHash: typeof Schema.String;
+            agents: Schema.Array$<typeof Schema.String>;
+            installedAt: typeof Schema.Date;
+            updatedAt: typeof Schema.Date;
+        }>>;
+        validity: Schema.Union<[Schema.TaggedStruct<"Valid", {}>, Schema.TaggedStruct<"MissingSkillMd", {
+            code: Schema.Literal<["E001"]>;
+            path: typeof Schema.String;
+        }>, Schema.TaggedStruct<"InvalidFrontmatter", {
+            code: Schema.Literal<["E002"]>;
+            errors: Schema.Array$<typeof Schema.String>;
+        }>, Schema.TaggedStruct<"NameMismatch", {
+            code: Schema.Literal<["E003"]>;
+            frontmatterName: typeof Schema.String;
+            directoryName: typeof Schema.String;
+        }>, Schema.TaggedStruct<"MissingDescription", {
+            code: Schema.Literal<["W001"]>;
+        }>, Schema.TaggedStruct<"Orphaned", {
+            code: Schema.Literal<["W002"]>;
+        }>, Schema.TaggedStruct<"Missing", {
+            code: Schema.Literal<["E004"]>;
+            expected: Schema.Struct<{
+                source: typeof Schema.String;
+                origin: typeof Schema.String;
+                path: Schema.OptionFromNullOr<typeof Schema.String>;
+                ref: Schema.OptionFromNullOr<typeof Schema.String>;
+                version: Schema.OptionFromNullOr<typeof Schema.String>;
+                gitTreeFolderHash: typeof Schema.String;
+                agents: Schema.Array$<typeof Schema.String>;
+                installedAt: typeof Schema.Date;
+                updatedAt: typeof Schema.Date;
+            }>;
+        }>, Schema.TaggedStruct<"HashMismatch", {
+            code: Schema.Literal<["E005"]>;
+            expected: typeof Schema.String;
+            actual: typeof Schema.String;
+        }>, Schema.TaggedStruct<"Incomplete", {
+            code: Schema.Literal<["E006"]>;
+            reason: typeof Schema.String;
+        }>, Schema.TaggedStruct<"Multiple", {
+            issues: Schema.Array$<Schema.suspend<SkillValidity, SkillValidity, never>>;
+        }>]>;
+    }>;
+}>, Schema.TaggedStruct<"Unchanged", {
+    skill: Schema.Struct<{
+        name: typeof Schema.String;
+        actual: Schema.OptionFromNullOr<Schema.Struct<{
+            name: typeof Schema.String;
+            path: typeof Schema.String;
+            frontmatter: Schema.OptionFromNullOr<Schema.Struct<{
+                name: Schema.OptionFromNullOr<typeof Schema.String>;
+                description: Schema.OptionFromNullOr<typeof Schema.String>;
+                version: Schema.OptionFromNullOr<typeof Schema.String>;
+                triggers: Schema.OptionFromNullOr<Schema.Array$<typeof Schema.String>>;
+            }>>;
+            content: typeof Schema.String;
+            gitTreeFolderHash: typeof Schema.String;
+            files: Schema.Array$<typeof Schema.String>;
+            lastModified: typeof Schema.Date;
+        }>>;
+        locked: Schema.OptionFromNullOr<Schema.Struct<{
+            source: typeof Schema.String;
+            origin: typeof Schema.String;
+            path: Schema.OptionFromNullOr<typeof Schema.String>;
+            ref: Schema.OptionFromNullOr<typeof Schema.String>;
+            version: Schema.OptionFromNullOr<typeof Schema.String>;
+            gitTreeFolderHash: typeof Schema.String;
+            agents: Schema.Array$<typeof Schema.String>;
+            installedAt: typeof Schema.Date;
+            updatedAt: typeof Schema.Date;
+        }>>;
+        validity: Schema.Union<[Schema.TaggedStruct<"Valid", {}>, Schema.TaggedStruct<"MissingSkillMd", {
+            code: Schema.Literal<["E001"]>;
+            path: typeof Schema.String;
+        }>, Schema.TaggedStruct<"InvalidFrontmatter", {
+            code: Schema.Literal<["E002"]>;
+            errors: Schema.Array$<typeof Schema.String>;
+        }>, Schema.TaggedStruct<"NameMismatch", {
+            code: Schema.Literal<["E003"]>;
+            frontmatterName: typeof Schema.String;
+            directoryName: typeof Schema.String;
+        }>, Schema.TaggedStruct<"MissingDescription", {
+            code: Schema.Literal<["W001"]>;
+        }>, Schema.TaggedStruct<"Orphaned", {
+            code: Schema.Literal<["W002"]>;
+        }>, Schema.TaggedStruct<"Missing", {
+            code: Schema.Literal<["E004"]>;
+            expected: Schema.Struct<{
+                source: typeof Schema.String;
+                origin: typeof Schema.String;
+                path: Schema.OptionFromNullOr<typeof Schema.String>;
+                ref: Schema.OptionFromNullOr<typeof Schema.String>;
+                version: Schema.OptionFromNullOr<typeof Schema.String>;
+                gitTreeFolderHash: typeof Schema.String;
+                agents: Schema.Array$<typeof Schema.String>;
+                installedAt: typeof Schema.Date;
+                updatedAt: typeof Schema.Date;
+            }>;
+        }>, Schema.TaggedStruct<"HashMismatch", {
+            code: Schema.Literal<["E005"]>;
+            expected: typeof Schema.String;
+            actual: typeof Schema.String;
+        }>, Schema.TaggedStruct<"Incomplete", {
+            code: Schema.Literal<["E006"]>;
+            reason: typeof Schema.String;
+        }>, Schema.TaggedStruct<"Multiple", {
+            issues: Schema.Array$<Schema.suspend<SkillValidity, SkillValidity, never>>;
+        }>]>;
+    }>;
+}>, Schema.TaggedStruct<"Repair", {
+    skill: Schema.Struct<{
+        name: typeof Schema.String;
+        actual: Schema.OptionFromNullOr<Schema.Struct<{
+            name: typeof Schema.String;
+            path: typeof Schema.String;
+            frontmatter: Schema.OptionFromNullOr<Schema.Struct<{
+                name: Schema.OptionFromNullOr<typeof Schema.String>;
+                description: Schema.OptionFromNullOr<typeof Schema.String>;
+                version: Schema.OptionFromNullOr<typeof Schema.String>;
+                triggers: Schema.OptionFromNullOr<Schema.Array$<typeof Schema.String>>;
+            }>>;
+            content: typeof Schema.String;
+            gitTreeFolderHash: typeof Schema.String;
+            files: Schema.Array$<typeof Schema.String>;
+            lastModified: typeof Schema.Date;
+        }>>;
+        locked: Schema.OptionFromNullOr<Schema.Struct<{
+            source: typeof Schema.String;
+            origin: typeof Schema.String;
+            path: Schema.OptionFromNullOr<typeof Schema.String>;
+            ref: Schema.OptionFromNullOr<typeof Schema.String>;
+            version: Schema.OptionFromNullOr<typeof Schema.String>;
+            gitTreeFolderHash: typeof Schema.String;
+            agents: Schema.Array$<typeof Schema.String>;
+            installedAt: typeof Schema.Date;
+            updatedAt: typeof Schema.Date;
+        }>>;
+        validity: Schema.Union<[Schema.TaggedStruct<"Valid", {}>, Schema.TaggedStruct<"MissingSkillMd", {
+            code: Schema.Literal<["E001"]>;
+            path: typeof Schema.String;
+        }>, Schema.TaggedStruct<"InvalidFrontmatter", {
+            code: Schema.Literal<["E002"]>;
+            errors: Schema.Array$<typeof Schema.String>;
+        }>, Schema.TaggedStruct<"NameMismatch", {
+            code: Schema.Literal<["E003"]>;
+            frontmatterName: typeof Schema.String;
+            directoryName: typeof Schema.String;
+        }>, Schema.TaggedStruct<"MissingDescription", {
+            code: Schema.Literal<["W001"]>;
+        }>, Schema.TaggedStruct<"Orphaned", {
+            code: Schema.Literal<["W002"]>;
+        }>, Schema.TaggedStruct<"Missing", {
+            code: Schema.Literal<["E004"]>;
+            expected: Schema.Struct<{
+                source: typeof Schema.String;
+                origin: typeof Schema.String;
+                path: Schema.OptionFromNullOr<typeof Schema.String>;
+                ref: Schema.OptionFromNullOr<typeof Schema.String>;
+                version: Schema.OptionFromNullOr<typeof Schema.String>;
+                gitTreeFolderHash: typeof Schema.String;
+                agents: Schema.Array$<typeof Schema.String>;
+                installedAt: typeof Schema.Date;
+                updatedAt: typeof Schema.Date;
+            }>;
+        }>, Schema.TaggedStruct<"HashMismatch", {
+            code: Schema.Literal<["E005"]>;
+            expected: typeof Schema.String;
+            actual: typeof Schema.String;
+        }>, Schema.TaggedStruct<"Incomplete", {
+            code: Schema.Literal<["E006"]>;
+            reason: typeof Schema.String;
+        }>, Schema.TaggedStruct<"Multiple", {
+            issues: Schema.Array$<Schema.suspend<SkillValidity, SkillValidity, never>>;
+        }>]>;
+    }>;
+    target: Schema.Struct<{
+        name: typeof Schema.String;
+        source: Schema.Union<[Schema.TaggedStruct<"Local", {
+            path: typeof Schema.String;
+        }>, Schema.TaggedStruct<"Git", {
+            url: typeof Schema.String;
+            ref: Schema.OptionFromNullOr<typeof Schema.String>;
+            subpath: Schema.OptionFromNullOr<typeof Schema.String>;
+        }>, Schema.TaggedStruct<"Registry", {
+            name: typeof Schema.String;
+            version: typeof Schema.String;
+        }>]>;
+        gitTreeFolderHash: typeof Schema.String;
+        description: Schema.OptionFromNullOr<typeof Schema.String>;
+        agents: Schema.Array$<typeof Schema.String>;
+    }>;
+}>]>;
+/**
+ * Summary of diff counts by change type.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export interface DiffSummary {
+    readonly add: number;
+    readonly update: number;
+    readonly remove: number;
+    readonly unchanged: number;
+    readonly repair: number;
+}
+/**
+ * Schema for JSON serialization of DiffSummary.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const DiffSummarySchema: Schema.Struct<{
+    add: typeof Schema.Number;
+    update: typeof Schema.Number;
+    remove: typeof Schema.Number;
+    unchanged: typeof Schema.Number;
+    repair: typeof Schema.Number;
+}>;
+/**
+ * Diff/Plan for skills: changes and summary.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export interface SkillsDiff {
+    readonly changes: Readonly<Record.ReadonlyRecord<string, SkillChange>>;
+    readonly summary: DiffSummary;
+}
+/**
+ * Schema for JSON serialization of SkillsDiff.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const SkillsDiffSchema: Schema.Struct<{
+    changes: Schema.Record$<typeof Schema.String, Schema.Union<[Schema.TaggedStruct<"Add", {
+        skill: Schema.Struct<{
+            name: typeof Schema.String;
+            source: Schema.Union<[Schema.TaggedStruct<"Local", {
+                path: typeof Schema.String;
+            }>, Schema.TaggedStruct<"Git", {
+                url: typeof Schema.String;
+                ref: Schema.OptionFromNullOr<typeof Schema.String>;
+                subpath: Schema.OptionFromNullOr<typeof Schema.String>;
+            }>, Schema.TaggedStruct<"Registry", {
+                name: typeof Schema.String;
+                version: typeof Schema.String;
+            }>]>;
+            gitTreeFolderHash: typeof Schema.String;
+            description: Schema.OptionFromNullOr<typeof Schema.String>;
+            agents: Schema.Array$<typeof Schema.String>;
+        }>;
+    }>, Schema.TaggedStruct<"Update", {
+        from: Schema.Struct<{
+            name: typeof Schema.String;
+            actual: Schema.OptionFromNullOr<Schema.Struct<{
+                name: typeof Schema.String;
+                path: typeof Schema.String;
+                frontmatter: Schema.OptionFromNullOr<Schema.Struct<{
+                    name: Schema.OptionFromNullOr<typeof Schema.String>;
+                    description: Schema.OptionFromNullOr<typeof Schema.String>;
+                    version: Schema.OptionFromNullOr<typeof Schema.String>;
+                    triggers: Schema.OptionFromNullOr<Schema.Array$<typeof Schema.String>>;
+                }>>;
+                content: typeof Schema.String;
+                gitTreeFolderHash: typeof Schema.String;
+                files: Schema.Array$<typeof Schema.String>;
+                lastModified: typeof Schema.Date;
+            }>>;
+            locked: Schema.OptionFromNullOr<Schema.Struct<{
+                source: typeof Schema.String;
+                origin: typeof Schema.String;
+                path: Schema.OptionFromNullOr<typeof Schema.String>;
+                ref: Schema.OptionFromNullOr<typeof Schema.String>;
+                version: Schema.OptionFromNullOr<typeof Schema.String>;
+                gitTreeFolderHash: typeof Schema.String;
+                agents: Schema.Array$<typeof Schema.String>;
+                installedAt: typeof Schema.Date;
+                updatedAt: typeof Schema.Date;
+            }>>;
+            validity: Schema.Union<[Schema.TaggedStruct<"Valid", {}>, Schema.TaggedStruct<"MissingSkillMd", {
+                code: Schema.Literal<["E001"]>;
+                path: typeof Schema.String;
+            }>, Schema.TaggedStruct<"InvalidFrontmatter", {
+                code: Schema.Literal<["E002"]>;
+                errors: Schema.Array$<typeof Schema.String>;
+            }>, Schema.TaggedStruct<"NameMismatch", {
+                code: Schema.Literal<["E003"]>;
+                frontmatterName: typeof Schema.String;
+                directoryName: typeof Schema.String;
+            }>, Schema.TaggedStruct<"MissingDescription", {
+                code: Schema.Literal<["W001"]>;
+            }>, Schema.TaggedStruct<"Orphaned", {
+                code: Schema.Literal<["W002"]>;
+            }>, Schema.TaggedStruct<"Missing", {
+                code: Schema.Literal<["E004"]>;
+                expected: Schema.Struct<{
+                    source: typeof Schema.String;
+                    origin: typeof Schema.String;
+                    path: Schema.OptionFromNullOr<typeof Schema.String>;
+                    ref: Schema.OptionFromNullOr<typeof Schema.String>;
+                    version: Schema.OptionFromNullOr<typeof Schema.String>;
+                    gitTreeFolderHash: typeof Schema.String;
+                    agents: Schema.Array$<typeof Schema.String>;
+                    installedAt: typeof Schema.Date;
+                    updatedAt: typeof Schema.Date;
+                }>;
+            }>, Schema.TaggedStruct<"HashMismatch", {
+                code: Schema.Literal<["E005"]>;
+                expected: typeof Schema.String;
+                actual: typeof Schema.String;
+            }>, Schema.TaggedStruct<"Incomplete", {
+                code: Schema.Literal<["E006"]>;
+                reason: typeof Schema.String;
+            }>, Schema.TaggedStruct<"Multiple", {
+                issues: Schema.Array$<Schema.suspend<SkillValidity, SkillValidity, never>>;
+            }>]>;
+        }>;
+        to: Schema.Struct<{
+            name: typeof Schema.String;
+            source: Schema.Union<[Schema.TaggedStruct<"Local", {
+                path: typeof Schema.String;
+            }>, Schema.TaggedStruct<"Git", {
+                url: typeof Schema.String;
+                ref: Schema.OptionFromNullOr<typeof Schema.String>;
+                subpath: Schema.OptionFromNullOr<typeof Schema.String>;
+            }>, Schema.TaggedStruct<"Registry", {
+                name: typeof Schema.String;
+                version: typeof Schema.String;
+            }>]>;
+            gitTreeFolderHash: typeof Schema.String;
+            description: Schema.OptionFromNullOr<typeof Schema.String>;
+            agents: Schema.Array$<typeof Schema.String>;
+        }>;
+    }>, Schema.TaggedStruct<"Remove", {
+        skill: Schema.Struct<{
+            name: typeof Schema.String;
+            actual: Schema.OptionFromNullOr<Schema.Struct<{
+                name: typeof Schema.String;
+                path: typeof Schema.String;
+                frontmatter: Schema.OptionFromNullOr<Schema.Struct<{
+                    name: Schema.OptionFromNullOr<typeof Schema.String>;
+                    description: Schema.OptionFromNullOr<typeof Schema.String>;
+                    version: Schema.OptionFromNullOr<typeof Schema.String>;
+                    triggers: Schema.OptionFromNullOr<Schema.Array$<typeof Schema.String>>;
+                }>>;
+                content: typeof Schema.String;
+                gitTreeFolderHash: typeof Schema.String;
+                files: Schema.Array$<typeof Schema.String>;
+                lastModified: typeof Schema.Date;
+            }>>;
+            locked: Schema.OptionFromNullOr<Schema.Struct<{
+                source: typeof Schema.String;
+                origin: typeof Schema.String;
+                path: Schema.OptionFromNullOr<typeof Schema.String>;
+                ref: Schema.OptionFromNullOr<typeof Schema.String>;
+                version: Schema.OptionFromNullOr<typeof Schema.String>;
+                gitTreeFolderHash: typeof Schema.String;
+                agents: Schema.Array$<typeof Schema.String>;
+                installedAt: typeof Schema.Date;
+                updatedAt: typeof Schema.Date;
+            }>>;
+            validity: Schema.Union<[Schema.TaggedStruct<"Valid", {}>, Schema.TaggedStruct<"MissingSkillMd", {
+                code: Schema.Literal<["E001"]>;
+                path: typeof Schema.String;
+            }>, Schema.TaggedStruct<"InvalidFrontmatter", {
+                code: Schema.Literal<["E002"]>;
+                errors: Schema.Array$<typeof Schema.String>;
+            }>, Schema.TaggedStruct<"NameMismatch", {
+                code: Schema.Literal<["E003"]>;
+                frontmatterName: typeof Schema.String;
+                directoryName: typeof Schema.String;
+            }>, Schema.TaggedStruct<"MissingDescription", {
+                code: Schema.Literal<["W001"]>;
+            }>, Schema.TaggedStruct<"Orphaned", {
+                code: Schema.Literal<["W002"]>;
+            }>, Schema.TaggedStruct<"Missing", {
+                code: Schema.Literal<["E004"]>;
+                expected: Schema.Struct<{
+                    source: typeof Schema.String;
+                    origin: typeof Schema.String;
+                    path: Schema.OptionFromNullOr<typeof Schema.String>;
+                    ref: Schema.OptionFromNullOr<typeof Schema.String>;
+                    version: Schema.OptionFromNullOr<typeof Schema.String>;
+                    gitTreeFolderHash: typeof Schema.String;
+                    agents: Schema.Array$<typeof Schema.String>;
+                    installedAt: typeof Schema.Date;
+                    updatedAt: typeof Schema.Date;
+                }>;
+            }>, Schema.TaggedStruct<"HashMismatch", {
+                code: Schema.Literal<["E005"]>;
+                expected: typeof Schema.String;
+                actual: typeof Schema.String;
+            }>, Schema.TaggedStruct<"Incomplete", {
+                code: Schema.Literal<["E006"]>;
+                reason: typeof Schema.String;
+            }>, Schema.TaggedStruct<"Multiple", {
+                issues: Schema.Array$<Schema.suspend<SkillValidity, SkillValidity, never>>;
+            }>]>;
+        }>;
+    }>, Schema.TaggedStruct<"Unchanged", {
+        skill: Schema.Struct<{
+            name: typeof Schema.String;
+            actual: Schema.OptionFromNullOr<Schema.Struct<{
+                name: typeof Schema.String;
+                path: typeof Schema.String;
+                frontmatter: Schema.OptionFromNullOr<Schema.Struct<{
+                    name: Schema.OptionFromNullOr<typeof Schema.String>;
+                    description: Schema.OptionFromNullOr<typeof Schema.String>;
+                    version: Schema.OptionFromNullOr<typeof Schema.String>;
+                    triggers: Schema.OptionFromNullOr<Schema.Array$<typeof Schema.String>>;
+                }>>;
+                content: typeof Schema.String;
+                gitTreeFolderHash: typeof Schema.String;
+                files: Schema.Array$<typeof Schema.String>;
+                lastModified: typeof Schema.Date;
+            }>>;
+            locked: Schema.OptionFromNullOr<Schema.Struct<{
+                source: typeof Schema.String;
+                origin: typeof Schema.String;
+                path: Schema.OptionFromNullOr<typeof Schema.String>;
+                ref: Schema.OptionFromNullOr<typeof Schema.String>;
+                version: Schema.OptionFromNullOr<typeof Schema.String>;
+                gitTreeFolderHash: typeof Schema.String;
+                agents: Schema.Array$<typeof Schema.String>;
+                installedAt: typeof Schema.Date;
+                updatedAt: typeof Schema.Date;
+            }>>;
+            validity: Schema.Union<[Schema.TaggedStruct<"Valid", {}>, Schema.TaggedStruct<"MissingSkillMd", {
+                code: Schema.Literal<["E001"]>;
+                path: typeof Schema.String;
+            }>, Schema.TaggedStruct<"InvalidFrontmatter", {
+                code: Schema.Literal<["E002"]>;
+                errors: Schema.Array$<typeof Schema.String>;
+            }>, Schema.TaggedStruct<"NameMismatch", {
+                code: Schema.Literal<["E003"]>;
+                frontmatterName: typeof Schema.String;
+                directoryName: typeof Schema.String;
+            }>, Schema.TaggedStruct<"MissingDescription", {
+                code: Schema.Literal<["W001"]>;
+            }>, Schema.TaggedStruct<"Orphaned", {
+                code: Schema.Literal<["W002"]>;
+            }>, Schema.TaggedStruct<"Missing", {
+                code: Schema.Literal<["E004"]>;
+                expected: Schema.Struct<{
+                    source: typeof Schema.String;
+                    origin: typeof Schema.String;
+                    path: Schema.OptionFromNullOr<typeof Schema.String>;
+                    ref: Schema.OptionFromNullOr<typeof Schema.String>;
+                    version: Schema.OptionFromNullOr<typeof Schema.String>;
+                    gitTreeFolderHash: typeof Schema.String;
+                    agents: Schema.Array$<typeof Schema.String>;
+                    installedAt: typeof Schema.Date;
+                    updatedAt: typeof Schema.Date;
+                }>;
+            }>, Schema.TaggedStruct<"HashMismatch", {
+                code: Schema.Literal<["E005"]>;
+                expected: typeof Schema.String;
+                actual: typeof Schema.String;
+            }>, Schema.TaggedStruct<"Incomplete", {
+                code: Schema.Literal<["E006"]>;
+                reason: typeof Schema.String;
+            }>, Schema.TaggedStruct<"Multiple", {
+                issues: Schema.Array$<Schema.suspend<SkillValidity, SkillValidity, never>>;
+            }>]>;
+        }>;
+    }>, Schema.TaggedStruct<"Repair", {
+        skill: Schema.Struct<{
+            name: typeof Schema.String;
+            actual: Schema.OptionFromNullOr<Schema.Struct<{
+                name: typeof Schema.String;
+                path: typeof Schema.String;
+                frontmatter: Schema.OptionFromNullOr<Schema.Struct<{
+                    name: Schema.OptionFromNullOr<typeof Schema.String>;
+                    description: Schema.OptionFromNullOr<typeof Schema.String>;
+                    version: Schema.OptionFromNullOr<typeof Schema.String>;
+                    triggers: Schema.OptionFromNullOr<Schema.Array$<typeof Schema.String>>;
+                }>>;
+                content: typeof Schema.String;
+                gitTreeFolderHash: typeof Schema.String;
+                files: Schema.Array$<typeof Schema.String>;
+                lastModified: typeof Schema.Date;
+            }>>;
+            locked: Schema.OptionFromNullOr<Schema.Struct<{
+                source: typeof Schema.String;
+                origin: typeof Schema.String;
+                path: Schema.OptionFromNullOr<typeof Schema.String>;
+                ref: Schema.OptionFromNullOr<typeof Schema.String>;
+                version: Schema.OptionFromNullOr<typeof Schema.String>;
+                gitTreeFolderHash: typeof Schema.String;
+                agents: Schema.Array$<typeof Schema.String>;
+                installedAt: typeof Schema.Date;
+                updatedAt: typeof Schema.Date;
+            }>>;
+            validity: Schema.Union<[Schema.TaggedStruct<"Valid", {}>, Schema.TaggedStruct<"MissingSkillMd", {
+                code: Schema.Literal<["E001"]>;
+                path: typeof Schema.String;
+            }>, Schema.TaggedStruct<"InvalidFrontmatter", {
+                code: Schema.Literal<["E002"]>;
+                errors: Schema.Array$<typeof Schema.String>;
+            }>, Schema.TaggedStruct<"NameMismatch", {
+                code: Schema.Literal<["E003"]>;
+                frontmatterName: typeof Schema.String;
+                directoryName: typeof Schema.String;
+            }>, Schema.TaggedStruct<"MissingDescription", {
+                code: Schema.Literal<["W001"]>;
+            }>, Schema.TaggedStruct<"Orphaned", {
+                code: Schema.Literal<["W002"]>;
+            }>, Schema.TaggedStruct<"Missing", {
+                code: Schema.Literal<["E004"]>;
+                expected: Schema.Struct<{
+                    source: typeof Schema.String;
+                    origin: typeof Schema.String;
+                    path: Schema.OptionFromNullOr<typeof Schema.String>;
+                    ref: Schema.OptionFromNullOr<typeof Schema.String>;
+                    version: Schema.OptionFromNullOr<typeof Schema.String>;
+                    gitTreeFolderHash: typeof Schema.String;
+                    agents: Schema.Array$<typeof Schema.String>;
+                    installedAt: typeof Schema.Date;
+                    updatedAt: typeof Schema.Date;
+                }>;
+            }>, Schema.TaggedStruct<"HashMismatch", {
+                code: Schema.Literal<["E005"]>;
+                expected: typeof Schema.String;
+                actual: typeof Schema.String;
+            }>, Schema.TaggedStruct<"Incomplete", {
+                code: Schema.Literal<["E006"]>;
+                reason: typeof Schema.String;
+            }>, Schema.TaggedStruct<"Multiple", {
+                issues: Schema.Array$<Schema.suspend<SkillValidity, SkillValidity, never>>;
+            }>]>;
+        }>;
+        target: Schema.Struct<{
+            name: typeof Schema.String;
+            source: Schema.Union<[Schema.TaggedStruct<"Local", {
+                path: typeof Schema.String;
+            }>, Schema.TaggedStruct<"Git", {
+                url: typeof Schema.String;
+                ref: Schema.OptionFromNullOr<typeof Schema.String>;
+                subpath: Schema.OptionFromNullOr<typeof Schema.String>;
+            }>, Schema.TaggedStruct<"Registry", {
+                name: typeof Schema.String;
+                version: typeof Schema.String;
+            }>]>;
+            gitTreeFolderHash: typeof Schema.String;
+            description: Schema.OptionFromNullOr<typeof Schema.String>;
+            agents: Schema.Array$<typeof Schema.String>;
+        }>;
+    }>]>>;
+    summary: Schema.Struct<{
+        add: typeof Schema.Number;
+        update: typeof Schema.Number;
+        remove: typeof Schema.Number;
+        unchanged: typeof Schema.Number;
+        repair: typeof Schema.Number;
+    }>;
+}>;
+/**
+ * Skill change with name field for array representation in JSON output.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export interface SkillChangeWithName {
+    readonly name: string;
+    readonly _tag: SkillChange["_tag"];
+    readonly skill: Option.Option<IdealSkillLegacy | SkillState>;
+    readonly from: Option.Option<SkillState>;
+    readonly to: Option.Option<IdealSkillLegacy>;
+    readonly target: Option.Option<IdealSkillLegacy>;
+}
+/**
+ * JSON output format for skills diff (array-based for CLI consumers).
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export interface SkillsDiffJson {
+    readonly changes: readonly SkillChangeWithName[];
+    readonly summary: DiffSummary;
+}
+/**
+ * Convert internal SkillsDiff to JSON output format.
+ * Transforms Record to array with name field for easier CLI consumption.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const skillsDiffToJson: (diff: SkillsDiff) => SkillsDiffJson;
+/**
+ * Plan step types as discriminated union.
+ * Simplified from SkillChange: InstallSkill/UpdateSkill/UninstallSkill only.
+ * Use exhaustive switch for pattern matching.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export type PlanStep = {
+    readonly _tag: "InstallSkill";
+    readonly skill: string;
+    readonly source: SourceInput;
+    readonly version: Option.Option<string>;
+    readonly gitTreeHash: Option.Option<string>;
+    readonly agents: ReadonlyArray<string>;
+} | {
+    readonly _tag: "UpdateSkill";
+    readonly skill: string;
+    readonly source: SourceInput;
+    readonly fromVersion: Option.Option<string>;
+    readonly toVersion: Option.Option<string>;
+    readonly fromHash: Option.Option<string>;
+    readonly toHash: Option.Option<string>;
+    readonly agents: ReadonlyArray<string>;
+} | {
+    readonly _tag: "UninstallSkill";
+    readonly skill: string;
+    readonly agents: ReadonlyArray<string>;
+};
+/**
+ * Constructors for PlanStep variants.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const PlanStep: {
+    readonly InstallSkill: (args: {
+        skill: string;
+        source: SourceInput;
+        version: Option.Option<string>;
+        gitTreeHash: Option.Option<string>;
+        agents: ReadonlyArray<string>;
+    }) => PlanStep;
+    readonly UpdateSkill: (args: {
+        skill: string;
+        source: SourceInput;
+        fromVersion: Option.Option<string>;
+        toVersion: Option.Option<string>;
+        fromHash: Option.Option<string>;
+        toHash: Option.Option<string>;
+        agents: ReadonlyArray<string>;
+    }) => PlanStep;
+    readonly UninstallSkill: (args: {
+        skill: string;
+        agents: ReadonlyArray<string>;
+    }) => PlanStep;
+};
+/**
+ * Schema for JSON serialization of PlanStep.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const PlanStepSchema: Schema.Union<[Schema.TaggedStruct<"InstallSkill", {
+    skill: typeof Schema.String;
+    source: typeof Schema.Unknown;
+    version: Schema.OptionFromNullOr<typeof Schema.String>;
+    gitTreeHash: Schema.OptionFromNullOr<typeof Schema.String>;
+    agents: Schema.Array$<typeof Schema.String>;
+}>, Schema.TaggedStruct<"UpdateSkill", {
+    skill: typeof Schema.String;
+    source: typeof Schema.Unknown;
+    fromVersion: Schema.OptionFromNullOr<typeof Schema.String>;
+    toVersion: Schema.OptionFromNullOr<typeof Schema.String>;
+    fromHash: Schema.OptionFromNullOr<typeof Schema.String>;
+    toHash: Schema.OptionFromNullOr<typeof Schema.String>;
+    agents: Schema.Array$<typeof Schema.String>;
+}>, Schema.TaggedStruct<"UninstallSkill", {
+    skill: typeof Schema.String;
+    agents: Schema.Array$<typeof Schema.String>;
+}>]>;
+/**
+ * Plan is pure data - no behavior.
+ * Contains steps reflecting user intent for skill operations.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export interface Plan {
+    readonly steps: ReadonlyArray<PlanStep>;
+}
+/**
+ * Schema for JSON serialization of Plan.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const PlanSchema: Schema.Struct<{
+    steps: Schema.Array$<Schema.Union<[Schema.TaggedStruct<"InstallSkill", {
+        skill: typeof Schema.String;
+        source: typeof Schema.Unknown;
+        version: Schema.OptionFromNullOr<typeof Schema.String>;
+        gitTreeHash: Schema.OptionFromNullOr<typeof Schema.String>;
+        agents: Schema.Array$<typeof Schema.String>;
+    }>, Schema.TaggedStruct<"UpdateSkill", {
+        skill: typeof Schema.String;
+        source: typeof Schema.Unknown;
+        fromVersion: Schema.OptionFromNullOr<typeof Schema.String>;
+        toVersion: Schema.OptionFromNullOr<typeof Schema.String>;
+        fromHash: Schema.OptionFromNullOr<typeof Schema.String>;
+        toHash: Schema.OptionFromNullOr<typeof Schema.String>;
+        agents: Schema.Array$<typeof Schema.String>;
+    }>, Schema.TaggedStruct<"UninstallSkill", {
+        skill: typeof Schema.String;
+        agents: Schema.Array$<typeof Schema.String>;
+    }>]>>;
+}>;
+/**
+ * Error type for apply operations.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export interface ApplyError {
+    readonly _tag: "ApplyError";
+    readonly message: string;
+    readonly step: Option.Option<PlanStep>;
+    readonly cause: Option.Option<unknown>;
+}
+/**
+ * Schema for JSON serialization of ApplyError.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const ApplyErrorSchema: Schema.TaggedStruct<"ApplyError", {
+    message: typeof Schema.String;
+    step: Schema.OptionFromNullOr<Schema.Union<[Schema.TaggedStruct<"InstallSkill", {
+        skill: typeof Schema.String;
+        source: typeof Schema.Unknown;
+        version: Schema.OptionFromNullOr<typeof Schema.String>;
+        gitTreeHash: Schema.OptionFromNullOr<typeof Schema.String>;
+        agents: Schema.Array$<typeof Schema.String>;
+    }>, Schema.TaggedStruct<"UpdateSkill", {
+        skill: typeof Schema.String;
+        source: typeof Schema.Unknown;
+        fromVersion: Schema.OptionFromNullOr<typeof Schema.String>;
+        toVersion: Schema.OptionFromNullOr<typeof Schema.String>;
+        fromHash: Schema.OptionFromNullOr<typeof Schema.String>;
+        toHash: Schema.OptionFromNullOr<typeof Schema.String>;
+        agents: Schema.Array$<typeof Schema.String>;
+    }>, Schema.TaggedStruct<"UninstallSkill", {
+        skill: typeof Schema.String;
+        agents: Schema.Array$<typeof Schema.String>;
+    }>]>>;
+    cause: Schema.OptionFromNullOr<typeof Schema.Unknown>;
+}>;
+/**
+ * Summary of apply operation counts.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export interface ApplySummary {
+    readonly installed: number;
+    readonly updated: number;
+    readonly uninstalled: number;
+    readonly failed: number;
+}
+/**
+ * Schema for JSON serialization of ApplySummary.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const ApplySummarySchema: Schema.Struct<{
+    installed: typeof Schema.Number;
+    updated: typeof Schema.Number;
+    uninstalled: typeof Schema.Number;
+    failed: typeof Schema.Number;
+}>;
+/**
+ * Result of applying a plan.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export interface ApplyResult {
+    readonly applied: ReadonlyArray<PlanStep>;
+    readonly failed: ReadonlyArray<{
+        step: PlanStep;
+        error: ApplyError;
+    }>;
+    readonly summary: ApplySummary;
+}
+/**
+ * Schema for JSON serialization of ApplyResult.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const ApplyResultSchema: Schema.Struct<{
+    applied: Schema.Array$<Schema.Union<[Schema.TaggedStruct<"InstallSkill", {
+        skill: typeof Schema.String;
+        source: typeof Schema.Unknown;
+        version: Schema.OptionFromNullOr<typeof Schema.String>;
+        gitTreeHash: Schema.OptionFromNullOr<typeof Schema.String>;
+        agents: Schema.Array$<typeof Schema.String>;
+    }>, Schema.TaggedStruct<"UpdateSkill", {
+        skill: typeof Schema.String;
+        source: typeof Schema.Unknown;
+        fromVersion: Schema.OptionFromNullOr<typeof Schema.String>;
+        toVersion: Schema.OptionFromNullOr<typeof Schema.String>;
+        fromHash: Schema.OptionFromNullOr<typeof Schema.String>;
+        toHash: Schema.OptionFromNullOr<typeof Schema.String>;
+        agents: Schema.Array$<typeof Schema.String>;
+    }>, Schema.TaggedStruct<"UninstallSkill", {
+        skill: typeof Schema.String;
+        agents: Schema.Array$<typeof Schema.String>;
+    }>]>>;
+    failed: Schema.Array$<Schema.Struct<{
+        step: Schema.Union<[Schema.TaggedStruct<"InstallSkill", {
+            skill: typeof Schema.String;
+            source: typeof Schema.Unknown;
+            version: Schema.OptionFromNullOr<typeof Schema.String>;
+            gitTreeHash: Schema.OptionFromNullOr<typeof Schema.String>;
+            agents: Schema.Array$<typeof Schema.String>;
+        }>, Schema.TaggedStruct<"UpdateSkill", {
+            skill: typeof Schema.String;
+            source: typeof Schema.Unknown;
+            fromVersion: Schema.OptionFromNullOr<typeof Schema.String>;
+            toVersion: Schema.OptionFromNullOr<typeof Schema.String>;
+            fromHash: Schema.OptionFromNullOr<typeof Schema.String>;
+            toHash: Schema.OptionFromNullOr<typeof Schema.String>;
+            agents: Schema.Array$<typeof Schema.String>;
+        }>, Schema.TaggedStruct<"UninstallSkill", {
+            skill: typeof Schema.String;
+            agents: Schema.Array$<typeof Schema.String>;
+        }>]>;
+        error: Schema.TaggedStruct<"ApplyError", {
+            message: typeof Schema.String;
+            step: Schema.OptionFromNullOr<Schema.Union<[Schema.TaggedStruct<"InstallSkill", {
+                skill: typeof Schema.String;
+                source: typeof Schema.Unknown;
+                version: Schema.OptionFromNullOr<typeof Schema.String>;
+                gitTreeHash: Schema.OptionFromNullOr<typeof Schema.String>;
+                agents: Schema.Array$<typeof Schema.String>;
+            }>, Schema.TaggedStruct<"UpdateSkill", {
+                skill: typeof Schema.String;
+                source: typeof Schema.Unknown;
+                fromVersion: Schema.OptionFromNullOr<typeof Schema.String>;
+                toVersion: Schema.OptionFromNullOr<typeof Schema.String>;
+                fromHash: Schema.OptionFromNullOr<typeof Schema.String>;
+                toHash: Schema.OptionFromNullOr<typeof Schema.String>;
+                agents: Schema.Array$<typeof Schema.String>;
+            }>, Schema.TaggedStruct<"UninstallSkill", {
+                skill: typeof Schema.String;
+                agents: Schema.Array$<typeof Schema.String>;
+            }>]>>;
+            cause: Schema.OptionFromNullOr<typeof Schema.Unknown>;
+        }>;
+    }>>;
+    summary: Schema.Struct<{
+        installed: typeof Schema.Number;
+        updated: typeof Schema.Number;
+        uninstalled: typeof Schema.Number;
+        failed: typeof Schema.Number;
+    }>;
+}>;
+//# sourceMappingURL=types.d.ts.map