@teamix-evo/registry 0.6.0 → 0.8.0

package/dist/index.d.ts

@@ -942,6 +942,38 @@ declare const TokensPackLinkedSchema: z.ZodObject<{
     templates?: string | undefined;
     'biz-ui'?: string | undefined;
 }>;
+/**
+ * One entry in a variant's `renames` log — declares that a token was
+ * renamed at the given upstream variant version. Consumed by
+ * `teamix-evo update` (writes `.teamix-evo/.upgrade-hints/tokens-<ts>.json`)
+ * and the future `teamix-evo-upgrade` skill (suggests codemods, never
+ * auto-rewrites — frozen boundary, [ADR 0019](../../../../docs/adr/0019-project-upgrade-flow.md) §D4).
+ *
+ * Semantics: as of `sinceVersion`, every CSS custom property reference of
+ * `from` should be migrated to `to`. Older snapshots may still mention
+ * `from` legitimately.
+ */
+declare const TokenRenameEntrySchema: z.ZodObject<{
+    /** Variant version at which the rename took effect (semver). */
+    sinceVersion: z.ZodString;
+    /** Old token name (with or without leading `--`; both forms accepted). */
+    from: z.ZodString;
+    /** New token name. */
+    to: z.ZodString;
+    /** Optional one-liner rationale surfaced in the upgrade-hints file. */
+    description: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    sinceVersion: string;
+    from: string;
+    to: string;
+    description?: string | undefined;
+}, {
+    sinceVersion: string;
+    from: string;
+    to: string;
+    description?: string | undefined;
+}>;
+type TokenRenameEntry = z.infer<typeof TokenRenameEntrySchema>;
 /**
  * One variant entry in the top-level catalog.
  */
@@ -971,6 +1003,30 @@ declare const TokensVariantEntrySchema: z.ZodObject<{
         templates?: string | undefined;
         'biz-ui'?: string | undefined;
     }>>;
+    /**
+     * Token rename log accumulated across this variant's version history.
+     * Empty / absent when the variant has never renamed a token.
+     */
+    renames: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        /** Variant version at which the rename took effect (semver). */
+        sinceVersion: z.ZodString;
+        /** Old token name (with or without leading `--`; both forms accepted). */
+        from: z.ZodString;
+        /** New token name. */
+        to: z.ZodString;
+        /** Optional one-liner rationale surfaced in the upgrade-hints file. */
+        description: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        sinceVersion: string;
+        from: string;
+        to: string;
+        description?: string | undefined;
+    }, {
+        sinceVersion: string;
+        from: string;
+        to: string;
+        description?: string | undefined;
+    }>, "many">>;
 }, "strip", z.ZodTypeAny, {
     displayName: string;
     version: string;
@@ -981,6 +1037,12 @@ declare const TokensVariantEntrySchema: z.ZodObject<{
         templates?: string | undefined;
         'biz-ui'?: string | undefined;
     } | undefined;
+    renames?: {
+        sinceVersion: string;
+        from: string;
+        to: string;
+        description?: string | undefined;
+    }[] | undefined;
 }, {
     displayName: string;
     version: string;
@@ -991,6 +1053,12 @@ declare const TokensVariantEntrySchema: z.ZodObject<{
         templates?: string | undefined;
         'biz-ui'?: string | undefined;
     } | undefined;
+    renames?: {
+        sinceVersion: string;
+        from: string;
+        to: string;
+        description?: string | undefined;
+    }[] | undefined;
 }>;
 type TokensVariantEntry = z.infer<typeof TokensVariantEntrySchema>;
 type TokensPackLinked = z.infer<typeof TokensPackLinkedSchema>;
@@ -1046,6 +1114,30 @@ declare const TokensPackageManifestSchema: z.ZodObject<{
             templates?: string | undefined;
             'biz-ui'?: string | undefined;
         }>>;
+        /**
+         * Token rename log accumulated across this variant's version history.
+         * Empty / absent when the variant has never renamed a token.
+         */
+        renames: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            /** Variant version at which the rename took effect (semver). */
+            sinceVersion: z.ZodString;
+            /** Old token name (with or without leading `--`; both forms accepted). */
+            from: z.ZodString;
+            /** New token name. */
+            to: z.ZodString;
+            /** Optional one-liner rationale surfaced in the upgrade-hints file. */
+            description: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            sinceVersion: string;
+            from: string;
+            to: string;
+            description?: string | undefined;
+        }, {
+            sinceVersion: string;
+            from: string;
+            to: string;
+            description?: string | undefined;
+        }>, "many">>;
     }, "strip", z.ZodTypeAny, {
         displayName: string;
         version: string;
@@ -1056,6 +1148,12 @@ declare const TokensPackageManifestSchema: z.ZodObject<{
             templates?: string | undefined;
             'biz-ui'?: string | undefined;
         } | undefined;
+        renames?: {
+            sinceVersion: string;
+            from: string;
+            to: string;
+            description?: string | undefined;
+        }[] | undefined;
     }, {
         displayName: string;
         version: string;
@@ -1066,6 +1164,12 @@ declare const TokensPackageManifestSchema: z.ZodObject<{
             templates?: string | undefined;
             'biz-ui'?: string | undefined;
         } | undefined;
+        renames?: {
+            sinceVersion: string;
+            from: string;
+            to: string;
+            description?: string | undefined;
+        }[] | undefined;
     }>, "many">;
     /**
      * Reserved for future shared assets that span variants (e.g. browser
@@ -1089,6 +1193,12 @@ declare const TokensPackageManifestSchema: z.ZodObject<{
             templates?: string | undefined;
             'biz-ui'?: string | undefined;
         } | undefined;
+        renames?: {
+            sinceVersion: string;
+            from: string;
+            to: string;
+            description?: string | undefined;
+        }[] | undefined;
     }[];
     $schema?: string | undefined;
     description?: string | undefined;
@@ -1110,6 +1220,12 @@ declare const TokensPackageManifestSchema: z.ZodObject<{
             templates?: string | undefined;
             'biz-ui'?: string | undefined;
         } | undefined;
+        renames?: {
+            sinceVersion: string;
+            from: string;
+            to: string;
+            description?: string | undefined;
+        }[] | undefined;
     }[];
     $schema?: string | undefined;
     description?: string | undefined;
@@ -1622,9 +1738,59 @@ declare const PackageEntrySchema: z.ZodObject<{
     rsc?: boolean | undefined;
 }>;
 /**
- * Project configuration schema — teamix-evo config.json at project root.
+ * Token rename record — captures a single variant-switch's token mapping so
+ * downstream codemod skills can rewrite consumer code (ADR 0019 §recovery).
+ */
+declare const TokenRenameRecordSchema: z.ZodObject<{
+    /** ISO-8601 UTC timestamp at which the variant switch was performed. */
+    ts: z.ZodString;
+    /** Variant the project was on before the switch. */
+    fromVariant: z.ZodString;
+    /** Variant the project switched to. */
+    toVariant: z.ZodString;
+    /**
+     * Token rename mapping — old token name → new token name.
+     * Empty object is legal (e.g. switch with zero rename).
+     */
+    renames: z.ZodRecord<z.ZodString, z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    renames: Record<string, string>;
+    ts: string;
+    fromVariant: string;
+    toVariant: string;
+}, {
+    renames: Record<string, string>;
+    ts: string;
+    fromVariant: string;
+    toVariant: string;
+}>;
+/**
+ * Last successful update record per package — set by `teamix-evo update`
+ * after a non-critical / critical step succeeds. Used by `restore` to point
+ * users at the right snapshot, and by `doctor` to flag staleness.
+ */
+declare const LastUpdateRecordSchema: z.ZodObject<{
+    /** ISO-8601 UTC timestamp of the last successful update. */
+    ts: z.ZodString;
+    /** Version the package was on before this update. */
+    fromVersion: z.ZodString;
+    /** Version the package was on after this update. */
+    toVersion: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    ts: string;
+    fromVersion: string;
+    toVersion: string;
+}, {
+    ts: string;
+    fromVersion: string;
+    toVersion: string;
+}>;
+/**
+ * Project configuration schema v1 — the original shape shipped through v0.x.
+ * Retained so existing `config.json` files keep validating; the top-level
+ * `ProjectConfigSchema` transforms v1 into v2 transparently for callers.
  */
-declare const ProjectConfigSchema: z.ZodObject<{
+declare const ProjectConfigV1Schema: z.ZodObject<{
     $schema: z.ZodOptional<z.ZodString>;
     schemaVersion: z.ZodLiteral<1>;
     /** IDE identifier */
@@ -1755,116 +1921,751 @@ declare const ProjectConfigSchema: z.ZodObject<{
     }>;
     $schema?: string | undefined;
 }>;
-
 /**
- * An installed resource entry — tracks individual resource installation state.
+ * Project configuration schema v2 — adds failure-recovery / variant-switch
+ * tracking fields per [ADR 0019](../../../../docs/adr/0019-project-upgrade-flow.md):
  *
- * For type="skill" resources, the same logical skill may produce multiple installed
- * entries (one per ide × scope combination); the optional `ide`/`scope` fields
- * disambiguate them.
- */
-declare const InstalledResourceSchema: z.ZodObject<{
-    /** Resource identifier matching the variant manifest */
-    id: z.ZodString;
-    /** Target path where the resource was installed (absolute or project-relative) */
-    target: z.ZodString;
-    /** Content hash for change detection (e.g. "sha256:...") */
-    hash: z.ZodString;
-    /** Update strategy that was applied */
-    strategy: z.ZodEnum<["frozen", "regenerable", "managed"]>;
-    /** IDE this resource was installed for (skill resources only) */
-    ide: z.ZodOptional<z.ZodEnum<["qoder", "claude"]>>;
-    /** Install scope (skill resources only) */
-    scope: z.ZodOptional<z.ZodEnum<["project", "global"]>>;
-}, "strip", z.ZodTypeAny, {
-    id: string;
-    target: string;
-    hash: string;
-    strategy: "frozen" | "regenerable" | "managed";
-    scope?: "project" | "global" | undefined;
-    ide?: "qoder" | "claude" | undefined;
-}, {
-    id: string;
-    target: string;
-    hash: string;
-    strategy: "frozen" | "regenerable" | "managed";
-    scope?: "project" | "global" | undefined;
-    ide?: "qoder" | "claude" | undefined;
-}>;
-/**
- * An installed package entry — tracks a single package installation.
+ * - `priorVariant`        — variant in effect before the most recent switch.
+ * - `lastUpdate`          — per-package successful update record.
+ * - `tokenRenameHistory`  — accumulated rename log across switches.
+ *
+ * All new fields are optional so a freshly-migrated v1 config (no recovery
+ * history yet) is a legal v2 document.
  */
-declare const InstalledPackageSchema: z.ZodObject<{
-    /** Full package name (e.g. "@teamix-evo/tokens") */
-    package: z.ZodString;
-    /** Variant identifier (use "_flat" for non-variant packages such as skills) */
-    variant: z.ZodString;
-    /** Installed version */
-    version: z.ZodString;
-    /** ISO 8601 timestamp of installation */
-    installedAt: z.ZodString;
-    /** List of installed resources */
-    resources: z.ZodArray<z.ZodObject<{
-        /** Resource identifier matching the variant manifest */
-        id: z.ZodString;
-        /** Target path where the resource was installed (absolute or project-relative) */
-        target: z.ZodString;
-        /** Content hash for change detection (e.g. "sha256:...") */
-        hash: z.ZodString;
-        /** Update strategy that was applied */
-        strategy: z.ZodEnum<["frozen", "regenerable", "managed"]>;
-        /** IDE this resource was installed for (skill resources only) */
-        ide: z.ZodOptional<z.ZodEnum<["qoder", "claude"]>>;
-        /** Install scope (skill resources only) */
+declare const ProjectConfigV2Schema: z.ZodObject<{
+    $schema: z.ZodOptional<z.ZodString>;
+    schemaVersion: z.ZodLiteral<2>;
+    /** IDE identifier */
+    ide: z.ZodString;
+    /** Installed packages keyed by package name */
+    packages: z.ZodRecord<z.ZodString, z.ZodObject<{
+        /** Variant identifier (e.g. "opentrek"; use "_flat" for skills/ui) */
+        variant: z.ZodString;
+        /** Semver version string */
+        version: z.ZodString;
+        /** Tailwind CSS version this project uses (only meaningful for design package). */
+        tailwind: z.ZodOptional<z.ZodLiteral<"v4">>;
+        /** IDEs this package was installed for (only meaningful for skills package). */
+        ides: z.ZodOptional<z.ZodArray<z.ZodEnum<["qoder", "claude"]>, "many">>;
+        /** Install scope (only meaningful for skills package). */
         scope: z.ZodOptional<z.ZodEnum<["project", "global"]>>;
+        /** Path aliases for ui entry installation (only meaningful for ui package). */
+        aliases: z.ZodOptional<z.ZodObject<{
+            components: z.ZodString;
+            hooks: z.ZodString;
+            utils: z.ZodString;
+            lib: z.ZodString;
+            /** Biz-ui components (variant-bound). Defaults to `src/components/business/`. */
+            business: z.ZodDefault<z.ZodString>;
+            /** Page templates (variant-bound). Defaults to `src/templates/`. */
+            templates: z.ZodDefault<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            components: string;
+            hooks: string;
+            utils: string;
+            lib: string;
+            business: string;
+            templates: string;
+        }, {
+            components: string;
+            hooks: string;
+            utils: string;
+            lib: string;
+            business?: string | undefined;
+            templates?: string | undefined;
+        }>>;
+        /**
+         * Default icon library declared by the project (only meaningful for ui).
+         * Declarative only — does NOT trigger code rewrites; ui entries hardcode imports.
+         */
+        iconLibrary: z.ZodOptional<z.ZodString>;
+        /** Whether the project uses TSX (true) or JSX (false). ui-specific. */
+        tsx: z.ZodOptional<z.ZodBoolean>;
+        /** Whether to emit React Server Components markers (`"use client"`). ui-specific. */
+        rsc: z.ZodOptional<z.ZodBoolean>;
     }, "strip", z.ZodTypeAny, {
-        id: string;
-        target: string;
-        hash: string;
-        strategy: "frozen" | "regenerable" | "managed";
+        variant: string;
+        version: string;
+        ides?: ("qoder" | "claude")[] | undefined;
         scope?: "project" | "global" | undefined;
-        ide?: "qoder" | "claude" | undefined;
+        tailwind?: "v4" | undefined;
+        aliases?: {
+            components: string;
+            hooks: string;
+            utils: string;
+            lib: string;
+            business: string;
+            templates: string;
+        } | undefined;
+        iconLibrary?: string | undefined;
+        tsx?: boolean | undefined;
+        rsc?: boolean | undefined;
     }, {
-        id: string;
-        target: string;
-        hash: string;
-        strategy: "frozen" | "regenerable" | "managed";
+        variant: string;
+        version: string;
+        ides?: ("qoder" | "claude")[] | undefined;
         scope?: "project" | "global" | undefined;
-        ide?: "qoder" | "claude" | undefined;
-    }>, "many">;
+        tailwind?: "v4" | undefined;
+        aliases?: {
+            components: string;
+            hooks: string;
+            utils: string;
+            lib: string;
+            business?: string | undefined;
+            templates?: string | undefined;
+        } | undefined;
+        iconLibrary?: string | undefined;
+        tsx?: boolean | undefined;
+        rsc?: boolean | undefined;
+    }>>;
+    /** Variant in effect before the most recent `variant switch`, if any. */
+    priorVariant: z.ZodOptional<z.ZodString>;
+    /** Last successful update record keyed by package name. */
+    lastUpdate: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        /** ISO-8601 UTC timestamp of the last successful update. */
+        ts: z.ZodString;
+        /** Version the package was on before this update. */
+        fromVersion: z.ZodString;
+        /** Version the package was on after this update. */
+        toVersion: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        ts: string;
+        fromVersion: string;
+        toVersion: string;
+    }, {
+        ts: string;
+        fromVersion: string;
+        toVersion: string;
+    }>>>;
+    /** Token rename log accumulated across variant switches (oldest → newest). */
+    tokenRenameHistory: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        /** ISO-8601 UTC timestamp at which the variant switch was performed. */
+        ts: z.ZodString;
+        /** Variant the project was on before the switch. */
+        fromVariant: z.ZodString;
+        /** Variant the project switched to. */
+        toVariant: z.ZodString;
+        /**
+         * Token rename mapping — old token name → new token name.
+         * Empty object is legal (e.g. switch with zero rename).
+         */
+        renames: z.ZodRecord<z.ZodString, z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        renames: Record<string, string>;
+        ts: string;
+        fromVariant: string;
+        toVariant: string;
+    }, {
+        renames: Record<string, string>;
+        ts: string;
+        fromVariant: string;
+        toVariant: string;
+    }>, "many">>;
 }, "strip", z.ZodTypeAny, {
-    package: string;
-    variant: string;
-    version: string;
-    resources: {
-        id: string;
-        target: string;
-        hash: string;
-        strategy: "frozen" | "regenerable" | "managed";
+    schemaVersion: 2;
+    ide: string;
+    packages: Record<string, {
+        variant: string;
+        version: string;
+        ides?: ("qoder" | "claude")[] | undefined;
         scope?: "project" | "global" | undefined;
-        ide?: "qoder" | "claude" | undefined;
-    }[];
-    installedAt: string;
+        tailwind?: "v4" | undefined;
+        aliases?: {
+            components: string;
+            hooks: string;
+            utils: string;
+            lib: string;
+            business: string;
+            templates: string;
+        } | undefined;
+        iconLibrary?: string | undefined;
+        tsx?: boolean | undefined;
+        rsc?: boolean | undefined;
+    }>;
+    $schema?: string | undefined;
+    priorVariant?: string | undefined;
+    lastUpdate?: Record<string, {
+        ts: string;
+        fromVersion: string;
+        toVersion: string;
+    }> | undefined;
+    tokenRenameHistory?: {
+        renames: Record<string, string>;
+        ts: string;
+        fromVariant: string;
+        toVariant: string;
+    }[] | undefined;
 }, {
-    package: string;
-    variant: string;
-    version: string;
-    resources: {
-        id: string;
-        target: string;
-        hash: string;
-        strategy: "frozen" | "regenerable" | "managed";
+    schemaVersion: 2;
+    ide: string;
+    packages: Record<string, {
+        variant: string;
+        version: string;
+        ides?: ("qoder" | "claude")[] | undefined;
         scope?: "project" | "global" | undefined;
-        ide?: "qoder" | "claude" | undefined;
-    }[];
-    installedAt: string;
-}>;
-/**
- * Installed manifest schema — tracks all installed packages in a project.
- * Stored at `.teamix-evo/manifest.json`.
- */
-declare const InstalledManifestSchema: z.ZodObject<{
-    schemaVersion: z.ZodLiteral<1>;
+        tailwind?: "v4" | undefined;
+        aliases?: {
+            components: string;
+            hooks: string;
+            utils: string;
+            lib: string;
+            business?: string | undefined;
+            templates?: string | undefined;
+        } | undefined;
+        iconLibrary?: string | undefined;
+        tsx?: boolean | undefined;
+        rsc?: boolean | undefined;
+    }>;
+    $schema?: string | undefined;
+    priorVariant?: string | undefined;
+    lastUpdate?: Record<string, {
+        ts: string;
+        fromVersion: string;
+        toVersion: string;
+    }> | undefined;
+    tokenRenameHistory?: {
+        renames: Record<string, string>;
+        ts: string;
+        fromVariant: string;
+        toVariant: string;
+    }[] | undefined;
+}>;
+/**
+ * Project configuration schema — teamix-evo config.json at project root.
+ *
+ * Accepts both v1 and v2 input documents and transforms v1 → v2 transparently,
+ * so consumers always observe a v2-shaped object. Writers (`writeProjectConfig`)
+ * therefore always emit `schemaVersion: 2`; legacy v1 files on disk are
+ * silently upgraded the next time they're read and re-written.
+ */
+declare const ProjectConfigSchema: z.ZodEffects<z.ZodDiscriminatedUnion<"schemaVersion", [z.ZodObject<{
+    $schema: z.ZodOptional<z.ZodString>;
+    schemaVersion: z.ZodLiteral<1>;
+    /** IDE identifier */
+    ide: z.ZodString;
+    /** Installed packages keyed by package name */
+    packages: z.ZodRecord<z.ZodString, z.ZodObject<{
+        /** Variant identifier (e.g. "opentrek"; use "_flat" for skills/ui) */
+        variant: z.ZodString;
+        /** Semver version string */
+        version: z.ZodString;
+        /** Tailwind CSS version this project uses (only meaningful for design package). */
+        tailwind: z.ZodOptional<z.ZodLiteral<"v4">>;
+        /** IDEs this package was installed for (only meaningful for skills package). */
+        ides: z.ZodOptional<z.ZodArray<z.ZodEnum<["qoder", "claude"]>, "many">>;
+        /** Install scope (only meaningful for skills package). */
+        scope: z.ZodOptional<z.ZodEnum<["project", "global"]>>;
+        /** Path aliases for ui entry installation (only meaningful for ui package). */
+        aliases: z.ZodOptional<z.ZodObject<{
+            components: z.ZodString;
+            hooks: z.ZodString;
+            utils: z.ZodString;
+            lib: z.ZodString;
+            /** Biz-ui components (variant-bound). Defaults to `src/components/business/`. */
+            business: z.ZodDefault<z.ZodString>;
+            /** Page templates (variant-bound). Defaults to `src/templates/`. */
+            templates: z.ZodDefault<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            components: string;
+            hooks: string;
+            utils: string;
+            lib: string;
+            business: string;
+            templates: string;
+        }, {
+            components: string;
+            hooks: string;
+            utils: string;
+            lib: string;
+            business?: string | undefined;
+            templates?: string | undefined;
+        }>>;
+        /**
+         * Default icon library declared by the project (only meaningful for ui).
+         * Declarative only — does NOT trigger code rewrites; ui entries hardcode imports.
+         */
+        iconLibrary: z.ZodOptional<z.ZodString>;
+        /** Whether the project uses TSX (true) or JSX (false). ui-specific. */
+        tsx: z.ZodOptional<z.ZodBoolean>;
+        /** Whether to emit React Server Components markers (`"use client"`). ui-specific. */
+        rsc: z.ZodOptional<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        variant: string;
+        version: string;
+        ides?: ("qoder" | "claude")[] | undefined;
+        scope?: "project" | "global" | undefined;
+        tailwind?: "v4" | undefined;
+        aliases?: {
+            components: string;
+            hooks: string;
+            utils: string;
+            lib: string;
+            business: string;
+            templates: string;
+        } | undefined;
+        iconLibrary?: string | undefined;
+        tsx?: boolean | undefined;
+        rsc?: boolean | undefined;
+    }, {
+        variant: string;
+        version: string;
+        ides?: ("qoder" | "claude")[] | undefined;
+        scope?: "project" | "global" | undefined;
+        tailwind?: "v4" | undefined;
+        aliases?: {
+            components: string;
+            hooks: string;
+            utils: string;
+            lib: string;
+            business?: string | undefined;
+            templates?: string | undefined;
+        } | undefined;
+        iconLibrary?: string | undefined;
+        tsx?: boolean | undefined;
+        rsc?: boolean | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    schemaVersion: 1;
+    ide: string;
+    packages: Record<string, {
+        variant: string;
+        version: string;
+        ides?: ("qoder" | "claude")[] | undefined;
+        scope?: "project" | "global" | undefined;
+        tailwind?: "v4" | undefined;
+        aliases?: {
+            components: string;
+            hooks: string;
+            utils: string;
+            lib: string;
+            business: string;
+            templates: string;
+        } | undefined;
+        iconLibrary?: string | undefined;
+        tsx?: boolean | undefined;
+        rsc?: boolean | undefined;
+    }>;
+    $schema?: string | undefined;
+}, {
+    schemaVersion: 1;
+    ide: string;
+    packages: Record<string, {
+        variant: string;
+        version: string;
+        ides?: ("qoder" | "claude")[] | undefined;
+        scope?: "project" | "global" | undefined;
+        tailwind?: "v4" | undefined;
+        aliases?: {
+            components: string;
+            hooks: string;
+            utils: string;
+            lib: string;
+            business?: string | undefined;
+            templates?: string | undefined;
+        } | undefined;
+        iconLibrary?: string | undefined;
+        tsx?: boolean | undefined;
+        rsc?: boolean | undefined;
+    }>;
+    $schema?: string | undefined;
+}>, z.ZodObject<{
+    $schema: z.ZodOptional<z.ZodString>;
+    schemaVersion: z.ZodLiteral<2>;
+    /** IDE identifier */
+    ide: z.ZodString;
+    /** Installed packages keyed by package name */
+    packages: z.ZodRecord<z.ZodString, z.ZodObject<{
+        /** Variant identifier (e.g. "opentrek"; use "_flat" for skills/ui) */
+        variant: z.ZodString;
+        /** Semver version string */
+        version: z.ZodString;
+        /** Tailwind CSS version this project uses (only meaningful for design package). */
+        tailwind: z.ZodOptional<z.ZodLiteral<"v4">>;
+        /** IDEs this package was installed for (only meaningful for skills package). */
+        ides: z.ZodOptional<z.ZodArray<z.ZodEnum<["qoder", "claude"]>, "many">>;
+        /** Install scope (only meaningful for skills package). */
+        scope: z.ZodOptional<z.ZodEnum<["project", "global"]>>;
+        /** Path aliases for ui entry installation (only meaningful for ui package). */
+        aliases: z.ZodOptional<z.ZodObject<{
+            components: z.ZodString;
+            hooks: z.ZodString;
+            utils: z.ZodString;
+            lib: z.ZodString;
+            /** Biz-ui components (variant-bound). Defaults to `src/components/business/`. */
+            business: z.ZodDefault<z.ZodString>;
+            /** Page templates (variant-bound). Defaults to `src/templates/`. */
+            templates: z.ZodDefault<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            components: string;
+            hooks: string;
+            utils: string;
+            lib: string;
+            business: string;
+            templates: string;
+        }, {
+            components: string;
+            hooks: string;
+            utils: string;
+            lib: string;
+            business?: string | undefined;
+            templates?: string | undefined;
+        }>>;
+        /**
+         * Default icon library declared by the project (only meaningful for ui).
+         * Declarative only — does NOT trigger code rewrites; ui entries hardcode imports.
+         */
+        iconLibrary: z.ZodOptional<z.ZodString>;
+        /** Whether the project uses TSX (true) or JSX (false). ui-specific. */
+        tsx: z.ZodOptional<z.ZodBoolean>;
+        /** Whether to emit React Server Components markers (`"use client"`). ui-specific. */
+        rsc: z.ZodOptional<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        variant: string;
+        version: string;
+        ides?: ("qoder" | "claude")[] | undefined;
+        scope?: "project" | "global" | undefined;
+        tailwind?: "v4" | undefined;
+        aliases?: {
+            components: string;
+            hooks: string;
+            utils: string;
+            lib: string;
+            business: string;
+            templates: string;
+        } | undefined;
+        iconLibrary?: string | undefined;
+        tsx?: boolean | undefined;
+        rsc?: boolean | undefined;
+    }, {
+        variant: string;
+        version: string;
+        ides?: ("qoder" | "claude")[] | undefined;
+        scope?: "project" | "global" | undefined;
+        tailwind?: "v4" | undefined;
+        aliases?: {
+            components: string;
+            hooks: string;
+            utils: string;
+            lib: string;
+            business?: string | undefined;
+            templates?: string | undefined;
+        } | undefined;
+        iconLibrary?: string | undefined;
+        tsx?: boolean | undefined;
+        rsc?: boolean | undefined;
+    }>>;
+    /** Variant in effect before the most recent `variant switch`, if any. */
+    priorVariant: z.ZodOptional<z.ZodString>;
+    /** Last successful update record keyed by package name. */
+    lastUpdate: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        /** ISO-8601 UTC timestamp of the last successful update. */
+        ts: z.ZodString;
+        /** Version the package was on before this update. */
+        fromVersion: z.ZodString;
+        /** Version the package was on after this update. */
+        toVersion: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        ts: string;
+        fromVersion: string;
+        toVersion: string;
+    }, {
+        ts: string;
+        fromVersion: string;
+        toVersion: string;
+    }>>>;
+    /** Token rename log accumulated across variant switches (oldest → newest). */
+    tokenRenameHistory: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        /** ISO-8601 UTC timestamp at which the variant switch was performed. */
+        ts: z.ZodString;
+        /** Variant the project was on before the switch. */
+        fromVariant: z.ZodString;
+        /** Variant the project switched to. */
+        toVariant: z.ZodString;
+        /**
+         * Token rename mapping — old token name → new token name.
+         * Empty object is legal (e.g. switch with zero rename).
+         */
+        renames: z.ZodRecord<z.ZodString, z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        renames: Record<string, string>;
+        ts: string;
+        fromVariant: string;
+        toVariant: string;
+    }, {
+        renames: Record<string, string>;
+        ts: string;
+        fromVariant: string;
+        toVariant: string;
+    }>, "many">>;
+}, "strip", z.ZodTypeAny, {
+    schemaVersion: 2;
+    ide: string;
+    packages: Record<string, {
+        variant: string;
+        version: string;
+        ides?: ("qoder" | "claude")[] | undefined;
+        scope?: "project" | "global" | undefined;
+        tailwind?: "v4" | undefined;
+        aliases?: {
+            components: string;
+            hooks: string;
+            utils: string;
+            lib: string;
+            business: string;
+            templates: string;
+        } | undefined;
+        iconLibrary?: string | undefined;
+        tsx?: boolean | undefined;
+        rsc?: boolean | undefined;
+    }>;
+    $schema?: string | undefined;
+    priorVariant?: string | undefined;
+    lastUpdate?: Record<string, {
+        ts: string;
+        fromVersion: string;
+        toVersion: string;
+    }> | undefined;
+    tokenRenameHistory?: {
+        renames: Record<string, string>;
+        ts: string;
+        fromVariant: string;
+        toVariant: string;
+    }[] | undefined;
+}, {
+    schemaVersion: 2;
+    ide: string;
+    packages: Record<string, {
+        variant: string;
+        version: string;
+        ides?: ("qoder" | "claude")[] | undefined;
+        scope?: "project" | "global" | undefined;
+        tailwind?: "v4" | undefined;
+        aliases?: {
+            components: string;
+            hooks: string;
+            utils: string;
+            lib: string;
+            business?: string | undefined;
+            templates?: string | undefined;
+        } | undefined;
+        iconLibrary?: string | undefined;
+        tsx?: boolean | undefined;
+        rsc?: boolean | undefined;
+    }>;
+    $schema?: string | undefined;
+    priorVariant?: string | undefined;
+    lastUpdate?: Record<string, {
+        ts: string;
+        fromVersion: string;
+        toVersion: string;
+    }> | undefined;
+    tokenRenameHistory?: {
+        renames: Record<string, string>;
+        ts: string;
+        fromVariant: string;
+        toVariant: string;
+    }[] | undefined;
+}>]>, {
+    schemaVersion: 2;
+    ide: string;
+    packages: Record<string, {
+        variant: string;
+        version: string;
+        ides?: ("qoder" | "claude")[] | undefined;
+        scope?: "project" | "global" | undefined;
+        tailwind?: "v4" | undefined;
+        aliases?: {
+            components: string;
+            hooks: string;
+            utils: string;
+            lib: string;
+            business: string;
+            templates: string;
+        } | undefined;
+        iconLibrary?: string | undefined;
+        tsx?: boolean | undefined;
+        rsc?: boolean | undefined;
+    }>;
+    $schema?: string | undefined;
+    priorVariant?: string | undefined;
+    lastUpdate?: Record<string, {
+        ts: string;
+        fromVersion: string;
+        toVersion: string;
+    }> | undefined;
+    tokenRenameHistory?: {
+        renames: Record<string, string>;
+        ts: string;
+        fromVariant: string;
+        toVariant: string;
+    }[] | undefined;
+}, {
+    schemaVersion: 1;
+    ide: string;
+    packages: Record<string, {
+        variant: string;
+        version: string;
+        ides?: ("qoder" | "claude")[] | undefined;
+        scope?: "project" | "global" | undefined;
+        tailwind?: "v4" | undefined;
+        aliases?: {
+            components: string;
+            hooks: string;
+            utils: string;
+            lib: string;
+            business?: string | undefined;
+            templates?: string | undefined;
+        } | undefined;
+        iconLibrary?: string | undefined;
+        tsx?: boolean | undefined;
+        rsc?: boolean | undefined;
+    }>;
+    $schema?: string | undefined;
+} | {
+    schemaVersion: 2;
+    ide: string;
+    packages: Record<string, {
+        variant: string;
+        version: string;
+        ides?: ("qoder" | "claude")[] | undefined;
+        scope?: "project" | "global" | undefined;
+        tailwind?: "v4" | undefined;
+        aliases?: {
+            components: string;
+            hooks: string;
+            utils: string;
+            lib: string;
+            business?: string | undefined;
+            templates?: string | undefined;
+        } | undefined;
+        iconLibrary?: string | undefined;
+        tsx?: boolean | undefined;
+        rsc?: boolean | undefined;
+    }>;
+    $schema?: string | undefined;
+    priorVariant?: string | undefined;
+    lastUpdate?: Record<string, {
+        ts: string;
+        fromVersion: string;
+        toVersion: string;
+    }> | undefined;
+    tokenRenameHistory?: {
+        renames: Record<string, string>;
+        ts: string;
+        fromVariant: string;
+        toVariant: string;
+    }[] | undefined;
+}>;
+
+/**
+ * An installed resource entry — tracks individual resource installation state.
+ *
+ * For type="skill" resources, the same logical skill may produce multiple installed
+ * entries (one per ide × scope combination); the optional `ide`/`scope` fields
+ * disambiguate them.
+ */
+declare const InstalledResourceSchema: z.ZodObject<{
+    /** Resource identifier matching the variant manifest */
+    id: z.ZodString;
+    /** Target path where the resource was installed (absolute or project-relative) */
+    target: z.ZodString;
+    /** Content hash for change detection (e.g. "sha256:...") */
+    hash: z.ZodString;
+    /** Update strategy that was applied */
+    strategy: z.ZodEnum<["frozen", "regenerable", "managed"]>;
+    /** IDE this resource was installed for (skill resources only) */
+    ide: z.ZodOptional<z.ZodEnum<["qoder", "claude"]>>;
+    /** Install scope (skill resources only) */
+    scope: z.ZodOptional<z.ZodEnum<["project", "global"]>>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    target: string;
+    hash: string;
+    strategy: "frozen" | "regenerable" | "managed";
+    scope?: "project" | "global" | undefined;
+    ide?: "qoder" | "claude" | undefined;
+}, {
+    id: string;
+    target: string;
+    hash: string;
+    strategy: "frozen" | "regenerable" | "managed";
+    scope?: "project" | "global" | undefined;
+    ide?: "qoder" | "claude" | undefined;
+}>;
+/**
+ * An installed package entry — tracks a single package installation.
+ */
+declare const InstalledPackageSchema: z.ZodObject<{
+    /** Full package name (e.g. "@teamix-evo/tokens") */
+    package: z.ZodString;
+    /** Variant identifier (use "_flat" for non-variant packages such as skills) */
+    variant: z.ZodString;
+    /** Installed version */
+    version: z.ZodString;
+    /** ISO 8601 timestamp of installation */
+    installedAt: z.ZodString;
+    /** List of installed resources */
+    resources: z.ZodArray<z.ZodObject<{
+        /** Resource identifier matching the variant manifest */
+        id: z.ZodString;
+        /** Target path where the resource was installed (absolute or project-relative) */
+        target: z.ZodString;
+        /** Content hash for change detection (e.g. "sha256:...") */
+        hash: z.ZodString;
+        /** Update strategy that was applied */
+        strategy: z.ZodEnum<["frozen", "regenerable", "managed"]>;
+        /** IDE this resource was installed for (skill resources only) */
+        ide: z.ZodOptional<z.ZodEnum<["qoder", "claude"]>>;
+        /** Install scope (skill resources only) */
+        scope: z.ZodOptional<z.ZodEnum<["project", "global"]>>;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        target: string;
+        hash: string;
+        strategy: "frozen" | "regenerable" | "managed";
+        scope?: "project" | "global" | undefined;
+        ide?: "qoder" | "claude" | undefined;
+    }, {
+        id: string;
+        target: string;
+        hash: string;
+        strategy: "frozen" | "regenerable" | "managed";
+        scope?: "project" | "global" | undefined;
+        ide?: "qoder" | "claude" | undefined;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    package: string;
+    variant: string;
+    version: string;
+    resources: {
+        id: string;
+        target: string;
+        hash: string;
+        strategy: "frozen" | "regenerable" | "managed";
+        scope?: "project" | "global" | undefined;
+        ide?: "qoder" | "claude" | undefined;
+    }[];
+    installedAt: string;
+}, {
+    package: string;
+    variant: string;
+    version: string;
+    resources: {
+        id: string;
+        target: string;
+        hash: string;
+        strategy: "frozen" | "regenerable" | "managed";
+        scope?: "project" | "global" | undefined;
+        ide?: "qoder" | "claude" | undefined;
+    }[];
+    installedAt: string;
+}>;
+/**
+ * Installed manifest schema — tracks all installed packages in a project.
+ * Stored at `.teamix-evo/manifest.json`.
+ */
+declare const InstalledManifestSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
     /** List of installed packages */
     installed: z.ZodArray<z.ZodObject<{
         /** Full package name (e.g. "@teamix-evo/tokens") */
@@ -2066,6 +2867,392 @@ declare const SkillsLockSchema: z.ZodObject<{
 type SkillsLockEntry = z.infer<typeof SkillsLockEntrySchema>;
 type SkillsLock = z.infer<typeof SkillsLockSchema>;
 
+/**
+ * Component-source upgrade staging manifest — emitted by CLI as the input for
+ * the `teamix-evo-upgrade` skill (component source section). Persisted at
+ * `.teamix-evo/.upgrade-staging/<category>-<fs-iso-ts>/meta.json`.
+ *
+ * See [ADR 0040](../../../../docs/adr/0040-component-source-layer-upgrade-flow.md).
+ */
+/** Risk classification CLI assigns per component (AI may downgrade after review). */
+declare const UpgradeRiskLevelSchema: z.ZodEnum<["unchanged", "upgradable-low", "upgradable-medium", "risky", "breaking", "foreign"]>;
+/** Lineage classification of the consumer project's component layer. */
+declare const ComponentLineageSchema: z.ZodEnum<["teamix-evo", "shadcn-native", "mixed", "custom-only"]>;
+/** Discriminator for which package category a staging manifest covers. */
+declare const UpgradeStagingCategorySchema: z.ZodEnum<["ui", "biz-ui"]>;
+/** What command produced the staging dir. */
+declare const UpgradeStagingTriggerSchema: z.ZodEnum<["update", "ui-upgrade", "biz-ui-upgrade"]>;
+/** Per-component "current state on disk" portion of a staging entry. */
+declare const UpgradeStagingCurrentSchema: z.ZodObject<{
+    /** Project-relative path of the component file (e.g. `src/components/ui/button.tsx`). */
+    target: z.ZodString;
+    /** Hash recorded in `.teamix-evo/manifest.json` at install time, or null when foreign. */
+    hash: z.ZodNullable<z.ZodString>;
+    /** Lineage of *this specific component* (independent of project-wide lineage). */
+    sourceLineage: z.ZodEnum<["teamix-evo", "shadcn-native", "custom", "absent"]>;
+}, "strip", z.ZodTypeAny, {
+    target: string;
+    hash: string | null;
+    sourceLineage: "custom" | "teamix-evo" | "shadcn-native" | "absent";
+}, {
+    target: string;
+    hash: string | null;
+    sourceLineage: "custom" | "teamix-evo" | "shadcn-native" | "absent";
+}>;
+/** Per-component "incoming source from registry" portion of a staging entry. */
+declare const UpgradeStagingIncomingSchema: z.ZodObject<{
+    /** Package-level version the incoming source comes from. */
+    sourceVersion: z.ZodString;
+    /** Hash of incoming source after applying the consumer's import-rewrite aliases. */
+    hash: z.ZodString;
+    /** Path of the incoming source file relative to the staging dir (e.g. `button/incoming.tsx`). */
+    relPath: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    hash: string;
+    sourceVersion: string;
+    relPath: string;
+}, {
+    hash: string;
+    sourceVersion: string;
+    relPath: string;
+}>;
+/** Risk + diff metadata produced by CLI heuristics. */
+declare const UpgradeStagingDiffSchema: z.ZodObject<{
+    riskLevel: z.ZodEnum<["unchanged", "upgradable-low", "upgradable-medium", "risky", "breaking", "foreign"]>;
+    /** Human-readable, machine-parsable hints (e.g. `"new prop: loading"`, `"removed cva variant: ghost"`). */
+    hints: z.ZodArray<z.ZodString, "many">;
+    /** Number of files that differ for this entry (almost always 1 today; reserved for multi-file entries). */
+    filesChangedCount: z.ZodNumber;
+    /**
+     * Path of the unified diff relative to the staging dir, when CLI emitted one.
+     * Reserved for a future emitter — in schema v1 the CLI does **not** pre-render
+     * `diff.unified.patch`; the consumer of the staging (the `teamix-evo-upgrade`
+     * skill) computes the diff on the fly from `current.tsx` vs `incoming.tsx`.
+     */
+    diffRelPath: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    riskLevel: "unchanged" | "upgradable-low" | "upgradable-medium" | "risky" | "breaking" | "foreign";
+    hints: string[];
+    filesChangedCount: number;
+    diffRelPath?: string | undefined;
+}, {
+    riskLevel: "unchanged" | "upgradable-low" | "upgradable-medium" | "risky" | "breaking" | "foreign";
+    hints: string[];
+    filesChangedCount: number;
+    diffRelPath?: string | undefined;
+}>;
+/** A single component-level entry inside the staging manifest. */
+declare const UpgradeStagingEntrySchema: z.ZodObject<{
+    /** Component identifier matching the upstream registry (e.g. `"button"`). */
+    id: z.ZodString;
+    /** Which package category this entry belongs to. */
+    category: z.ZodEnum<["ui", "biz-ui"]>;
+    current: z.ZodObject<{
+        /** Project-relative path of the component file (e.g. `src/components/ui/button.tsx`). */
+        target: z.ZodString;
+        /** Hash recorded in `.teamix-evo/manifest.json` at install time, or null when foreign. */
+        hash: z.ZodNullable<z.ZodString>;
+        /** Lineage of *this specific component* (independent of project-wide lineage). */
+        sourceLineage: z.ZodEnum<["teamix-evo", "shadcn-native", "custom", "absent"]>;
+    }, "strip", z.ZodTypeAny, {
+        target: string;
+        hash: string | null;
+        sourceLineage: "custom" | "teamix-evo" | "shadcn-native" | "absent";
+    }, {
+        target: string;
+        hash: string | null;
+        sourceLineage: "custom" | "teamix-evo" | "shadcn-native" | "absent";
+    }>;
+    /** Absent when the entry is `breaking` (no incoming) or `foreign` (no upstream). */
+    incoming: z.ZodOptional<z.ZodObject<{
+        /** Package-level version the incoming source comes from. */
+        sourceVersion: z.ZodString;
+        /** Hash of incoming source after applying the consumer's import-rewrite aliases. */
+        hash: z.ZodString;
+        /** Path of the incoming source file relative to the staging dir (e.g. `button/incoming.tsx`). */
+        relPath: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        hash: string;
+        sourceVersion: string;
+        relPath: string;
+    }, {
+        hash: string;
+        sourceVersion: string;
+        relPath: string;
+    }>>;
+    diff: z.ZodObject<{
+        riskLevel: z.ZodEnum<["unchanged", "upgradable-low", "upgradable-medium", "risky", "breaking", "foreign"]>;
+        /** Human-readable, machine-parsable hints (e.g. `"new prop: loading"`, `"removed cva variant: ghost"`). */
+        hints: z.ZodArray<z.ZodString, "many">;
+        /** Number of files that differ for this entry (almost always 1 today; reserved for multi-file entries). */
+        filesChangedCount: z.ZodNumber;
+        /**
+         * Path of the unified diff relative to the staging dir, when CLI emitted one.
+         * Reserved for a future emitter — in schema v1 the CLI does **not** pre-render
+         * `diff.unified.patch`; the consumer of the staging (the `teamix-evo-upgrade`
+         * skill) computes the diff on the fly from `current.tsx` vs `incoming.tsx`.
+         */
+        diffRelPath: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        riskLevel: "unchanged" | "upgradable-low" | "upgradable-medium" | "risky" | "breaking" | "foreign";
+        hints: string[];
+        filesChangedCount: number;
+        diffRelPath?: string | undefined;
+    }, {
+        riskLevel: "unchanged" | "upgradable-low" | "upgradable-medium" | "risky" | "breaking" | "foreign";
+        hints: string[];
+        filesChangedCount: number;
+        diffRelPath?: string | undefined;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    category: "ui" | "biz-ui";
+    current: {
+        target: string;
+        hash: string | null;
+        sourceLineage: "custom" | "teamix-evo" | "shadcn-native" | "absent";
+    };
+    diff: {
+        riskLevel: "unchanged" | "upgradable-low" | "upgradable-medium" | "risky" | "breaking" | "foreign";
+        hints: string[];
+        filesChangedCount: number;
+        diffRelPath?: string | undefined;
+    };
+    incoming?: {
+        hash: string;
+        sourceVersion: string;
+        relPath: string;
+    } | undefined;
+}, {
+    id: string;
+    category: "ui" | "biz-ui";
+    current: {
+        target: string;
+        hash: string | null;
+        sourceLineage: "custom" | "teamix-evo" | "shadcn-native" | "absent";
+    };
+    diff: {
+        riskLevel: "unchanged" | "upgradable-low" | "upgradable-medium" | "risky" | "breaking" | "foreign";
+        hints: string[];
+        filesChangedCount: number;
+        diffRelPath?: string | undefined;
+    };
+    incoming?: {
+        hash: string;
+        sourceVersion: string;
+        relPath: string;
+    } | undefined;
+}>;
+/**
+ * Top-level staging manifest, written as `meta.json` in the staging dir.
+ * Versioned independently from the project config (`schemaVersion: 1` here is
+ * scoped to this manifest only).
+ */
+declare const UpgradeStagingManifestSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    /** ISO-8601 timestamp the staging dir was created (matches dir suffix). */
+    ts: z.ZodString;
+    /** Which package category this staging covers. */
+    package: z.ZodEnum<["ui", "biz-ui"]>;
+    /** Which command produced this staging. */
+    trigger: z.ZodEnum<["update", "ui-upgrade", "biz-ui-upgrade"]>;
+    /** Variant applicable to the staging (always `_flat` for ui; concrete variant for biz-ui). */
+    variant: z.ZodString;
+    /** Installed package version (from `.teamix-evo/manifest.json`); empty string when foreign-only. */
+    fromVersion: z.ZodString;
+    /** Upstream package version. */
+    toVersion: z.ZodString;
+    /** Project-wide lineage classification. */
+    lineage: z.ZodEnum<["teamix-evo", "shadcn-native", "mixed", "custom-only"]>;
+    /** Aggregate counts grouped by riskLevel for quick AI summarization. */
+    summary: z.ZodObject<{
+        total: z.ZodNumber;
+        byRisk: z.ZodRecord<z.ZodEnum<["unchanged", "upgradable-low", "upgradable-medium", "risky", "breaking", "foreign"]>, z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        total: number;
+        byRisk: Partial<Record<"unchanged" | "upgradable-low" | "upgradable-medium" | "risky" | "breaking" | "foreign", number>>;
+    }, {
+        total: number;
+        byRisk: Partial<Record<"unchanged" | "upgradable-low" | "upgradable-medium" | "risky" | "breaking" | "foreign", number>>;
+    }>;
+    entries: z.ZodArray<z.ZodObject<{
+        /** Component identifier matching the upstream registry (e.g. `"button"`). */
+        id: z.ZodString;
+        /** Which package category this entry belongs to. */
+        category: z.ZodEnum<["ui", "biz-ui"]>;
+        current: z.ZodObject<{
+            /** Project-relative path of the component file (e.g. `src/components/ui/button.tsx`). */
+            target: z.ZodString;
+            /** Hash recorded in `.teamix-evo/manifest.json` at install time, or null when foreign. */
+            hash: z.ZodNullable<z.ZodString>;
+            /** Lineage of *this specific component* (independent of project-wide lineage). */
+            sourceLineage: z.ZodEnum<["teamix-evo", "shadcn-native", "custom", "absent"]>;
+        }, "strip", z.ZodTypeAny, {
+            target: string;
+            hash: string | null;
+            sourceLineage: "custom" | "teamix-evo" | "shadcn-native" | "absent";
+        }, {
+            target: string;
+            hash: string | null;
+            sourceLineage: "custom" | "teamix-evo" | "shadcn-native" | "absent";
+        }>;
+        /** Absent when the entry is `breaking` (no incoming) or `foreign` (no upstream). */
+        incoming: z.ZodOptional<z.ZodObject<{
+            /** Package-level version the incoming source comes from. */
+            sourceVersion: z.ZodString;
+            /** Hash of incoming source after applying the consumer's import-rewrite aliases. */
+            hash: z.ZodString;
+            /** Path of the incoming source file relative to the staging dir (e.g. `button/incoming.tsx`). */
+            relPath: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            hash: string;
+            sourceVersion: string;
+            relPath: string;
+        }, {
+            hash: string;
+            sourceVersion: string;
+            relPath: string;
+        }>>;
+        diff: z.ZodObject<{
+            riskLevel: z.ZodEnum<["unchanged", "upgradable-low", "upgradable-medium", "risky", "breaking", "foreign"]>;
+            /** Human-readable, machine-parsable hints (e.g. `"new prop: loading"`, `"removed cva variant: ghost"`). */
+            hints: z.ZodArray<z.ZodString, "many">;
+            /** Number of files that differ for this entry (almost always 1 today; reserved for multi-file entries). */
+            filesChangedCount: z.ZodNumber;
+            /**
+             * Path of the unified diff relative to the staging dir, when CLI emitted one.
+             * Reserved for a future emitter — in schema v1 the CLI does **not** pre-render
+             * `diff.unified.patch`; the consumer of the staging (the `teamix-evo-upgrade`
+             * skill) computes the diff on the fly from `current.tsx` vs `incoming.tsx`.
+             */
+            diffRelPath: z.ZodOptional<z.ZodString>;
+        }, "strip", z.ZodTypeAny, {
+            riskLevel: "unchanged" | "upgradable-low" | "upgradable-medium" | "risky" | "breaking" | "foreign";
+            hints: string[];
+            filesChangedCount: number;
+            diffRelPath?: string | undefined;
+        }, {
+            riskLevel: "unchanged" | "upgradable-low" | "upgradable-medium" | "risky" | "breaking" | "foreign";
+            hints: string[];
+            filesChangedCount: number;
+            diffRelPath?: string | undefined;
+        }>;
+    }, "strip", z.ZodTypeAny, {
+        id: string;
+        category: "ui" | "biz-ui";
+        current: {
+            target: string;
+            hash: string | null;
+            sourceLineage: "custom" | "teamix-evo" | "shadcn-native" | "absent";
+        };
+        diff: {
+            riskLevel: "unchanged" | "upgradable-low" | "upgradable-medium" | "risky" | "breaking" | "foreign";
+            hints: string[];
+            filesChangedCount: number;
+            diffRelPath?: string | undefined;
+        };
+        incoming?: {
+            hash: string;
+            sourceVersion: string;
+            relPath: string;
+        } | undefined;
+    }, {
+        id: string;
+        category: "ui" | "biz-ui";
+        current: {
+            target: string;
+            hash: string | null;
+            sourceLineage: "custom" | "teamix-evo" | "shadcn-native" | "absent";
+        };
+        diff: {
+            riskLevel: "unchanged" | "upgradable-low" | "upgradable-medium" | "risky" | "breaking" | "foreign";
+            hints: string[];
+            filesChangedCount: number;
+            diffRelPath?: string | undefined;
+        };
+        incoming?: {
+            hash: string;
+            sourceVersion: string;
+            relPath: string;
+        } | undefined;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    entries: {
+        id: string;
+        category: "ui" | "biz-ui";
+        current: {
+            target: string;
+            hash: string | null;
+            sourceLineage: "custom" | "teamix-evo" | "shadcn-native" | "absent";
+        };
+        diff: {
+            riskLevel: "unchanged" | "upgradable-low" | "upgradable-medium" | "risky" | "breaking" | "foreign";
+            hints: string[];
+            filesChangedCount: number;
+            diffRelPath?: string | undefined;
+        };
+        incoming?: {
+            hash: string;
+            sourceVersion: string;
+            relPath: string;
+        } | undefined;
+    }[];
+    schemaVersion: 1;
+    package: "ui" | "biz-ui";
+    variant: string;
+    ts: string;
+    fromVersion: string;
+    toVersion: string;
+    trigger: "update" | "ui-upgrade" | "biz-ui-upgrade";
+    lineage: "teamix-evo" | "shadcn-native" | "mixed" | "custom-only";
+    summary: {
+        total: number;
+        byRisk: Partial<Record<"unchanged" | "upgradable-low" | "upgradable-medium" | "risky" | "breaking" | "foreign", number>>;
+    };
+}, {
+    entries: {
+        id: string;
+        category: "ui" | "biz-ui";
+        current: {
+            target: string;
+            hash: string | null;
+            sourceLineage: "custom" | "teamix-evo" | "shadcn-native" | "absent";
+        };
+        diff: {
+            riskLevel: "unchanged" | "upgradable-low" | "upgradable-medium" | "risky" | "breaking" | "foreign";
+            hints: string[];
+            filesChangedCount: number;
+            diffRelPath?: string | undefined;
+        };
+        incoming?: {
+            hash: string;
+            sourceVersion: string;
+            relPath: string;
+        } | undefined;
+    }[];
+    schemaVersion: 1;
+    package: "ui" | "biz-ui";
+    variant: string;
+    ts: string;
+    fromVersion: string;
+    toVersion: string;
+    trigger: "update" | "ui-upgrade" | "biz-ui-upgrade";
+    lineage: "teamix-evo" | "shadcn-native" | "mixed" | "custom-only";
+    summary: {
+        total: number;
+        byRisk: Partial<Record<"unchanged" | "upgradable-low" | "upgradable-medium" | "risky" | "breaking" | "foreign", number>>;
+    };
+}>;
+type UpgradeRiskLevel = z.infer<typeof UpgradeRiskLevelSchema>;
+type ComponentLineage = z.infer<typeof ComponentLineageSchema>;
+type UpgradeStagingCategory = z.infer<typeof UpgradeStagingCategorySchema>;
+type UpgradeStagingTrigger = z.infer<typeof UpgradeStagingTriggerSchema>;
+type UpgradeStagingCurrent = z.infer<typeof UpgradeStagingCurrentSchema>;
+type UpgradeStagingIncoming = z.infer<typeof UpgradeStagingIncomingSchema>;
+type UpgradeStagingDiff = z.infer<typeof UpgradeStagingDiffSchema>;
+type UpgradeStagingEntry = z.infer<typeof UpgradeStagingEntrySchema>;
+type UpgradeStagingManifest = z.infer<typeof UpgradeStagingManifestSchema>;
+
 /** Resource update strategy */
 type UpdateStrategy = z.infer<typeof UpdateStrategySchema>;
 /** Resource type discriminator */
@@ -2098,8 +3285,26 @@ type UiAliases = z.infer<typeof UiAliasesSchema>;
 type PackageEntry = z.infer<typeof PackageEntrySchema>;
 /** Tailwind CSS major version (always `"v4"` since v0.7). */
 type TailwindVersion = z.infer<typeof TailwindVersionSchema>;
-/** Project configuration (config.json) */
+/**
+ * Project configuration v1 — legacy shape kept for migration only. New code
+ * should use `ProjectConfig` (≡ v2) which `validateConfig` always returns.
+ */
+type ProjectConfigV1 = z.infer<typeof ProjectConfigV1Schema>;
+/**
+ * Project configuration v2 — current shape with failure-recovery fields
+ * (`priorVariant` / `lastUpdate` / `tokenRenameHistory`). Equivalent to
+ * `ProjectConfig`.
+ */
+type ProjectConfigV2 = z.infer<typeof ProjectConfigV2Schema>;
+/**
+ * Project configuration (config.json) — always v2 after parsing; legacy v1
+ * documents are auto-migrated by `ProjectConfigSchema.transform`.
+ */
 type ProjectConfig = z.infer<typeof ProjectConfigSchema>;
+/** Token rename record stored in `tokenRenameHistory`. */
+type TokenRenameRecord = z.infer<typeof TokenRenameRecordSchema>;
+/** Last successful update record stored in `lastUpdate[pkgName]`. */
+type LastUpdateRecord = z.infer<typeof LastUpdateRecordSchema>;
 /** An installed resource tracking entry */
 type InstalledResource = z.infer<typeof InstalledResourceSchema>;
 /** An installed package tracking entry */
@@ -2117,6 +3322,24 @@ interface ManagedRegion {
     /** Content between start and end markers */
     content: string;
 }
+/**
+ * Ordered slice of a document, classifying each chunk as either user-owned
+ * (`unmanaged`) or framework-owned (`managed`). Used by the update pipeline
+ * (ADR 0019 §2) to apply tri-state semantics — `regenerable` rewrites the
+ * whole file, `managed` rewrites only `managed` segments and preserves
+ * `unmanaged` ones verbatim, `frozen` skips entirely.
+ *
+ * Concatenating every segment's textual form (start marker + content + end
+ * marker for managed; content for unmanaged) reconstructs the original
+ * document byte-for-byte.
+ */
+type DocumentSegment = {
+    kind: 'unmanaged';
+    content: string;
+} | {
+    kind: 'managed';
+    region: ManagedRegion;
+};
 /** Generic result type for validation operations */
 type Result<T> = {
     success: true;
@@ -2250,6 +3473,58 @@ declare function replaceManagedRegion(content: string, id: string, newContent: s
  * @returns true if the region exists
  */
 declare function hasManagedRegion(content: string, id: string): boolean;
+/**
+ * Split a document into an ordered sequence of {@link DocumentSegment}s,
+ * classifying each chunk as either `unmanaged` (user-owned) or `managed`
+ * (framework-owned, identified by `<!-- teamix-evo:managed:start id="..." -->`
+ * markers).
+ *
+ * The output preserves the document byte-for-byte: concatenating each
+ * segment's serialized form—marker + content + marker for `managed`,
+ * `content` for `unmanaged`—reconstructs the original input exactly.
+ *
+ * `unmanaged` segments may be empty strings when two managed regions touch
+ * each other or sit at the document edges — callers SHOULD preserve them so
+ * a later round-trip (split → mutate managed only → join) does not silently
+ * drop boundary structure.
+ *
+ * Marker integrity is enforced via {@link parseManagedRegions} — unmatched
+ * or duplicate markers throw. The update pipeline (ADR 0019 §2) relies on
+ * this contract so a corrupted file fails fast rather than producing
+ * unexpected merges.
+ *
+ * @example
+ *   const segs = splitManagedRegions(
+ *     `prelude\n<!-- teamix-evo:managed:start id="core" -->\nA\n<!-- teamix-evo:managed:end id="core" -->\ntail`,
+ *   );
+ *   // [
+ *   //   { kind: 'unmanaged', content: 'prelude\n' },
+ *   //   { kind: 'managed', region: { id: 'core', …, content: '\nA\n' } },
+ *   //   { kind: 'unmanaged', content: '\ntail' },
+ *   // ]
+ *
+ * @param content - The full document content.
+ * @returns Ordered segments covering the entire input.
+ * @throws Error when start/end markers are unmatched or a start id appears more than once.
+ */
+declare function splitManagedRegions(content: string): DocumentSegment[];
+/**
+ * Extract the leading YAML frontmatter block (including the surrounding
+ * `---` fences and the trailing newline, if any) from a document.
+ *
+ * Returns `null` when the document does not start with a frontmatter block.
+ */
+declare function extractFrontmatter(content: string): string | null;
+/**
+ * Replace the leading YAML frontmatter block of `content` with
+ * `newFrontmatter`. If `content` has no frontmatter, `newFrontmatter` is
+ * prepended (separated by a single newline if it does not already end
+ * with one).
+ *
+ * `newFrontmatter` must include the surrounding `---` fences — pass the
+ * value returned by {@link extractFrontmatter}.
+ */
+declare function replaceFrontmatter(content: string, newFrontmatter: string): string;
 
 /**
  * Determine whether a resource should be updated based on its strategy
@@ -2279,4 +3554,4 @@ interface UpdateActionOptions {
  */
 declare function getUpdateAction(strategy: UpdateStrategy, options: UpdateActionOptions): UpdateAction;
 
-export { type InstalledManifest, InstalledManifestSchema, type InstalledPackage, InstalledPackageSchema, type InstalledResource, InstalledResourceSchema, type ManagedRegion, type PackageEntry, PackageEntrySchema, type ProjectConfig, ProjectConfigSchema, type Resource, ResourceSchema, type ResourceType, ResourceTypeSchema, type Result, type SkillEntry, SkillEntrySchema, type SkillIde, SkillIdeSchema, type SkillScope, SkillScopeSchema, type SkillsLock, type SkillsLockEntry, SkillsLockEntrySchema, SkillsLockSchema, type SkillsPackageManifest, SkillsPackageManifestSchema, type TailwindVersion, TailwindVersionSchema, type TokensPackLinked, TokensPackLinkedSchema, type TokensPackLock, TokensPackLockSchema, type TokensPackageManifest, TokensPackageManifestSchema, type TokensVariantEntry, TokensVariantEntrySchema, type UiAlias, UiAliasSchema, type UiAliases, UiAliasesSchema, type UiEntry, type UiEntryFile, UiEntryFileSchema, UiEntrySchema, type UiEntryType, UiEntryTypeSchema, type UiPackageManifest, UiPackageManifestSchema, type UpdateAction, type UpdateActionOptions, type UpdateStrategy, UpdateStrategySchema, type VariantManifest, VariantManifestSchema, type VariantUiPackageCatalog, VariantUiPackageCatalogSchema, type VariantUiPackageManifest, VariantUiPackageManifestSchema, type VariantUiPackageName, VariantUiPackageNameSchema, getUpdateAction, getVariantEntry, hasManagedRegion, loadSkillsPackageManifest, loadTokensPackageManifest, loadUiPackageManifest, loadVariantManifest, loadVariantUiPackageCatalog, loadVariantUiPackageManifest, parseManagedRegions, replaceManagedRegion, resolveUiEntryOrder, shouldUpdate, validateConfig, validateInstalled, validateManifest, validateSkillsLock, validateSkillsPackage, validateUiDependencyGraph, validateUiPackage };
+export { type ComponentLineage, ComponentLineageSchema, type DocumentSegment, type InstalledManifest, InstalledManifestSchema, type InstalledPackage, InstalledPackageSchema, type InstalledResource, InstalledResourceSchema, type LastUpdateRecord, LastUpdateRecordSchema, type ManagedRegion, type PackageEntry, PackageEntrySchema, type ProjectConfig, ProjectConfigSchema, type ProjectConfigV1, ProjectConfigV1Schema, type ProjectConfigV2, ProjectConfigV2Schema, type Resource, ResourceSchema, type ResourceType, ResourceTypeSchema, type Result, type SkillEntry, SkillEntrySchema, type SkillIde, SkillIdeSchema, type SkillScope, SkillScopeSchema, type SkillsLock, type SkillsLockEntry, SkillsLockEntrySchema, SkillsLockSchema, type SkillsPackageManifest, SkillsPackageManifestSchema, type TailwindVersion, TailwindVersionSchema, type TokenRenameEntry, TokenRenameEntrySchema, type TokenRenameRecord, TokenRenameRecordSchema, type TokensPackLinked, TokensPackLinkedSchema, type TokensPackLock, TokensPackLockSchema, type TokensPackageManifest, TokensPackageManifestSchema, type TokensVariantEntry, TokensVariantEntrySchema, type UiAlias, UiAliasSchema, type UiAliases, UiAliasesSchema, type UiEntry, type UiEntryFile, UiEntryFileSchema, UiEntrySchema, type UiEntryType, UiEntryTypeSchema, type UiPackageManifest, UiPackageManifestSchema, type UpdateAction, type UpdateActionOptions, type UpdateStrategy, UpdateStrategySchema, type UpgradeRiskLevel, UpgradeRiskLevelSchema, type UpgradeStagingCategory, UpgradeStagingCategorySchema, type UpgradeStagingCurrent, UpgradeStagingCurrentSchema, type UpgradeStagingDiff, UpgradeStagingDiffSchema, type UpgradeStagingEntry, UpgradeStagingEntrySchema, type UpgradeStagingIncoming, UpgradeStagingIncomingSchema, type UpgradeStagingManifest, UpgradeStagingManifestSchema, type UpgradeStagingTrigger, UpgradeStagingTriggerSchema, type VariantManifest, VariantManifestSchema, type VariantUiPackageCatalog, VariantUiPackageCatalogSchema, type VariantUiPackageManifest, VariantUiPackageManifestSchema, type VariantUiPackageName, VariantUiPackageNameSchema, extractFrontmatter, getUpdateAction, getVariantEntry, hasManagedRegion, loadSkillsPackageManifest, loadTokensPackageManifest, loadUiPackageManifest, loadVariantManifest, loadVariantUiPackageCatalog, loadVariantUiPackageManifest, parseManagedRegions, replaceFrontmatter, replaceManagedRegion, resolveUiEntryOrder, shouldUpdate, splitManagedRegions, validateConfig, validateInstalled, validateManifest, validateSkillsLock, validateSkillsPackage, validateUiDependencyGraph, validateUiPackage };