@withandeo/cli 0.19.10 → 0.19.12

package/dist/flagship-runtime.d.ts

@@ -0,0 +1,57 @@
+import { type FlagContext, type FlagValue, type FlagValueType } from "./flagship-contract.js";
+export interface NativeFlagDetails<T = FlagValue> {
+    flagKey: string;
+    value: T;
+    variant?: string;
+    reason?: string;
+    errorCode?: string;
+}
+/** Structural native binding contract; no rules, hashes or provider credentials. */
+export interface NativeFlags {
+    getBooleanDetails(key: string, fallback: boolean, context?: FlagContext): Promise<NativeFlagDetails<boolean>>;
+    getStringDetails(key: string, fallback: string, context?: FlagContext): Promise<NativeFlagDetails<string>>;
+    getNumberDetails(key: string, fallback: number, context?: FlagContext): Promise<NativeFlagDetails<number>>;
+    getObjectDetails<T>(key: string, fallback: T, context?: FlagContext): Promise<NativeFlagDetails<T>>;
+}
+export interface ClientVisibleFlag {
+    key: string;
+    type: FlagValueType;
+    fallback: FlagValue;
+}
+export interface FlagBootstrap {
+    schema: "andeo.flag-bootstrap/v1";
+    environment: string;
+    refreshAfterMs: number;
+    values: Record<string, NativeFlagDetails>;
+}
+export declare function nativeFlagDetails(binding: NativeFlags, flag: ClientVisibleFlag, context: FlagContext): Promise<NativeFlagDetails>;
+/** Application-owned GET endpoint/SSR bootstrap. The server chooses scope and keys;
+ * resolveContext must authenticate/enrich trusted properties and select only
+ * designated presentation attributes. No management credential or private rules.
+ */
+export declare function createFlagGateway(input: {
+    binding: NativeFlags;
+    environment: string;
+    flags: readonly ClientVisibleFlag[];
+    resolveContext: (request: Request) => FlagContext | Promise<FlagContext>;
+    refreshAfterMs?: number;
+}): (request: Request) => Promise<Response>;
+export interface FlagExposure {
+    flagKey: string;
+    variant: string;
+    reason?: string;
+    environment: string;
+    experimentVersion: string;
+}
+/** Call only when the application actually shows an experience. Caller chooses
+ * deduplication lifetime and measurement destination; no raw context is emitted.
+ */
+export declare function flagExposure(details: NativeFlagDetails, environment: string, experimentVersion: string): FlagExposure | null;
+/** Optional server-owned one-year anonymous cookie. Reuse on browser and server
+ * actions; login does not change it. Explicit reset returns a new identity.
+ */
+export declare function flagVisitorIdentity(request: Request, reset?: boolean): {
+    targetingKey: string;
+    setCookie?: string;
+};
+//# sourceMappingURL=flagship-runtime.d.ts.map

package/dist/flagship-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flagship-runtime.d.ts","sourceRoot":"","sources":["../src/flagship-runtime.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqD,KAAK,WAAW,EAAE,KAAK,SAAS,EAAE,KAAK,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAEjJ,MAAM,WAAW,iBAAiB,CAAC,CAAC,GAAG,SAAS;IAAI,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,CAAC,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE;AACtI,oFAAoF;AACpF,MAAM,WAAW,WAAW;IAC1B,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,iBAAiB,CAAC,OAAO,CAAC,CAAC,CAAC;IAC9G,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,iBAAiB,CAAC,MAAM,CAAC,CAAC,CAAC;IAC3G,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,iBAAiB,CAAC,MAAM,CAAC,CAAC,CAAC;IAC3G,gBAAgB,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,CAAC;CACrG;AACD,MAAM,WAAW,iBAAiB;IAAG,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,aAAa,CAAC;IAAC,QAAQ,EAAE,SAAS,CAAA;CAAE;AAC5F,MAAM,WAAW,aAAa;IAAG,MAAM,EAAE,yBAAyB,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAA;CAAE;AAC5J,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,iBAAiB,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,iBAAiB,CAAC,CASvI;AACD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE;IAAE,OAAO,EAAE,WAAW,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,SAAS,iBAAiB,EAAE,CAAC;IACxH,cAAc,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAAC,cAAc,CAAC,EAAE,MAAM,CAAA;CAAE,aAO5E,OAAO,KAAG,OAAO,CAAC,QAAQ,CAAC,CAmBnD;AACD,MAAM,WAAW,YAAY;IAAG,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,iBAAiB,EAAE,MAAM,CAAA;CAAE;AACnI;;GAEG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,EAAE,iBAAiB,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CAG5H;AACD;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,UAAQ,GAAG;IAAE,YAAY,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,CAOjH"}

package/dist/flagship-runtime.js

@@ -0,0 +1,79 @@
+import { flagKey, flagContext, flagValueType, safeFlagJson } from "./flagship-contract.js";
+export async function nativeFlagDetails(binding, flag, context) {
+    safeFlagJson(flag.fallback);
+    if (flagValueType(flag.fallback) !== flag.type)
+        throw new Error("flagship_fallback_type_invalid");
+    switch (flag.type) {
+        case "boolean": return binding.getBooleanDetails(flag.key, flag.fallback, context);
+        case "string": return binding.getStringDetails(flag.key, flag.fallback, context);
+        case "number": return binding.getNumberDetails(flag.key, flag.fallback, context);
+        case "json": return binding.getObjectDetails(flag.key, flag.fallback, context);
+    }
+}
+/** Application-owned GET endpoint/SSR bootstrap. The server chooses scope and keys;
+ * resolveContext must authenticate/enrich trusted properties and select only
+ * designated presentation attributes. No management credential or private rules.
+ */
+export function createFlagGateway(input) {
+    if (input.flags.length > 64 || new Set(input.flags.map(f => f.key)).size !== input.flags.length)
+        throw new Error("flagship_browser_allowlist_invalid");
+    safeFlagJson(input.flags);
+    for (const flag of input.flags) {
+        flagKey(flag.key);
+        if (flagValueType(flag.fallback) !== flag.type)
+            throw new Error("flagship_browser_allowlist_invalid");
+    }
+    const flags = structuredClone(input.flags), { binding, environment, resolveContext } = input;
+    const refreshAfterMs = input.refreshAfterMs ?? 30000;
+    if (!Number.isSafeInteger(refreshAfterMs) || refreshAfterMs < 0 || refreshAfterMs > 60000)
+        throw new Error("flagship_refresh_invalid");
+    return async (request) => {
+        if (request.method !== "GET")
+            return new Response(null, { status: 405, headers: { allow: "GET" } });
+        // Queries never select flags, apps, environments or trusted targeting properties.
+        if (new URL(request.url).search)
+            return new Response(null, { status: 400 });
+        const context = flagContext(await resolveContext(request));
+        const entries = await Promise.all(flags.map(async (flag) => {
+            let details;
+            try {
+                details = await nativeFlagDetails(binding, flag, context);
+            }
+            catch {
+                details = { flagKey: flag.key, value: flag.fallback, reason: "ERROR", errorCode: "GENERAL" };
+            }
+            // Explicitly select the public details; never spread provider metadata.
+            const publicDetails = { flagKey: flag.key, value: details.value, ...(details.variant ? { variant: details.variant } : {}),
+                ...(details.reason ? { reason: details.reason } : {}), ...(details.errorCode ? { errorCode: details.errorCode } : {}) };
+            safeFlagJson(publicDetails);
+            return [flag.key, publicDetails];
+        }));
+        const bootstrap = { schema: "andeo.flag-bootstrap/v1", environment, refreshAfterMs, values: Object.fromEntries(entries) };
+        const body = JSON.stringify(bootstrap);
+        if (new TextEncoder().encode(body).length > 64 * 1024)
+            throw new Error("flagship_bootstrap_size_exceeded");
+        return new Response(body, { headers: { "content-type": "application/json", "cache-control": "private, no-store", vary: "Cookie, Authorization" } });
+    };
+}
+/** Call only when the application actually shows an experience. Caller chooses
+ * deduplication lifetime and measurement destination; no raw context is emitted.
+ */
+export function flagExposure(details, environment, experimentVersion) {
+    if (details.errorCode || details.reason === "ERROR" || details.reason === "DISABLED" || details.reason === "DEFAULT" || !details.variant || !experimentVersion)
+        return null;
+    return { flagKey: details.flagKey, variant: details.variant, reason: details.reason, environment, experimentVersion };
+}
+/** Optional server-owned one-year anonymous cookie. Reuse on browser and server
+ * actions; login does not change it. Explicit reset returns a new identity.
+ */
+export function flagVisitorIdentity(request, reset = false) {
+    const existing = request.headers.get("cookie")?.split(";").map(s => s.trim()).find(s => s.startsWith("andeo_flag_visitor="))?.slice(19);
+    if (!reset && existing && /^[a-f0-9-]{36}$/.test(existing))
+        return { targetingKey: existing };
+    const url = new URL(request.url), loopback = ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname);
+    if (url.protocol !== "https:" && !loopback)
+        throw new Error("flagship_identity_https_required");
+    const targetingKey = crypto.randomUUID();
+    return { targetingKey, setCookie: `andeo_flag_visitor=${targetingKey}; Path=/; Max-Age=31536000; HttpOnly; SameSite=Lax${url.protocol === "https:" ? "; Secure" : ""}` };
+}
+//# sourceMappingURL=flagship-runtime.js.map

package/dist/flagship-runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flagship-runtime.js","sourceRoot":"","sources":["../src/flagship-runtime.ts"],"names":[],"mappings":"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"}

package/dist/main.d.ts

@@ -2,6 +2,7 @@ import { type CliAuthStore } from "./auth-store.js";
 import { waitForLoopbackAuthorization } from "./oauth.js";
 import { captureCommand, runProjectCommand } from "./processes.js";
 import { type CliProfileBindings } from "./profile-bindings.js";
+import { type UpdateRunner } from "./updates.js";
 export declare const CLI_VERSION: string;
 export interface CliRuntime {
     defaultApiUrl: string;
@@ -15,6 +16,8 @@ export interface CliRuntime {
     sleep(milliseconds: number): Promise<void>;
     runProjectCommand: typeof runProjectCommand;
     captureCommand: typeof captureCommand;
+    updateCommand: UpdateRunner;
+    packageDirectory: string;
     authStore: CliAuthStore;
     profileBindings: CliProfileBindings;
     openBrowser(url: string): Promise<boolean>;

package/dist/main.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":"AASA,OAAO,EAIL,KAAK,YAAY,EAIlB,MAAM,iBAAiB,CAAC;AA2BzB,OAAO,EAIL,4BAA4B,EAE7B,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACnE,OAAO,EAEL,KAAK,kBAAkB,EACxB,MAAM,uBAAuB,CAAC;AAW/B,eAAO,MAAM,WAAW,QAA0B,CAAC;AAenD,MAAM,WAAW,UAAU;IACzB,aAAa,EAAE,MAAM,CAAC;IACtB,GAAG,EAAE,MAAM,CAAC;IACZ,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC,UAAU,CAAC;IAC/B,KAAK,EAAE,MAAM,CAAC,cAAc,CAAC;IAC7B,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;IAC1C,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;IAC1C,OAAO,EAAE,OAAO,KAAK,CAAC;IACtB,KAAK,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3C,iBAAiB,EAAE,OAAO,iBAAiB,CAAC;IAC5C,cAAc,EAAE,OAAO,cAAc,CAAC;IACtC,SAAS,EAAE,YAAY,CAAC;IACxB,eAAe,EAAE,kBAAkB,CAAC;IACpC,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC3C,4BAA4B,EAAE,OAAO,4BAA4B,CAAC;IAClE,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,gBAAgB,CAAC;IAClE,WAAW,CAAC,OAAO,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC;CAC9C;AAED,MAAM,WAAW,gBAAgB;IAC/B,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;IAC3D,gBAAgB,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE;QAAE,IAAI,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,GAAG,IAAI,CAAC;IACtF,gBAAgB,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,GAAG,IAAI,CAAC;IACnG,gBAAgB,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;IAC5D,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7C;AA6BD,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,SAAS,GAAE,OAAO,CAAC,UAAU,CAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAmCjG"}
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":"AASA,OAAO,EAIL,KAAK,YAAY,EAIlB,MAAM,iBAAiB,CAAC;AA2BzB,OAAO,EAIL,4BAA4B,EAE7B,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACnE,OAAO,EAEL,KAAK,kBAAkB,EACxB,MAAM,uBAAuB,CAAC;AAI/B,OAAO,EAA6E,KAAK,YAAY,EAAsB,MAAM,cAAc,CAAC;AAQhJ,eAAO,MAAM,WAAW,QAA0B,CAAC;AAenD,MAAM,WAAW,UAAU;IACzB,aAAa,EAAE,MAAM,CAAC;IACtB,GAAG,EAAE,MAAM,CAAC;IACZ,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC,UAAU,CAAC;IAC/B,KAAK,EAAE,MAAM,CAAC,cAAc,CAAC;IAC7B,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;IAC1C,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;IAC1C,OAAO,EAAE,OAAO,KAAK,CAAC;IACtB,KAAK,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3C,iBAAiB,EAAE,OAAO,iBAAiB,CAAC;IAC5C,cAAc,EAAE,OAAO,cAAc,CAAC;IACtC,aAAa,EAAE,YAAY,CAAC;IAC5B,gBAAgB,EAAE,MAAM,CAAC;IACzB,SAAS,EAAE,YAAY,CAAC;IACxB,eAAe,EAAE,kBAAkB,CAAC;IACpC,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC3C,4BAA4B,EAAE,OAAO,4BAA4B,CAAC;IAClE,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,gBAAgB,CAAC;IAClE,WAAW,CAAC,OAAO,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC;CAC9C;AAED,MAAM,WAAW,gBAAgB;IAC/B,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;IAC3D,gBAAgB,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE;QAAE,IAAI,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,GAAG,IAAI,CAAC;IACtF,gBAAgB,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,GAAG,IAAI,CAAC;IACnG,gBAAgB,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;IAC5D,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7C;AA+BD,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,SAAS,GAAE,OAAO,CAAC,UAAU,CAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAmCjG"}

package/dist/main.js

@@ -18,9 +18,10 @@ import { captureCommand, runProjectCommand } from "./processes.js";
 import { createDefaultProfileBindings, } from "./profile-bindings.js";
 import { initializeStarter } from "./starter.js";
 import { normalizeAndeoEnvironment } from "./andeo-environment.js";
-import { DOC_TOPICS, readDocumentation, installDocumentation, installedSkillCheck } from "./documentation.js";
+import { DOC_TOPICS, readDocumentation, installDocumentation, installedSkillCheck, skillDocumentationStatus, syncDocumentation } from "./documentation.js";
+import { CLI_PACKAGE_DIRECTORY, configureAutoUpgrade, runUpdateCommand, upgradeCli } from "./updates.js";
 import { capabilityPreflight } from "./capability-preflight.js";
-import { flagEnvironment, flagKey, rolloutPercentage, customerIds } from "./flagship-contract.js";
+import { flagEnvironment, flagKey, validateFlagDefinition, flagContext, FLAGSHIP_SCHEMA, FLAG_DELETION_GUIDANCE, FlagCompatibilityError } from "./flagship-contract.js";
 const packageMetadata = createRequire(import.meta.url)("../package.json");
 if (typeof packageMetadata.version !== "string" || packageMetadata.version.length === 0) {
     throw new Error("Andeo CLI package version is missing.");
@@ -38,6 +39,8 @@ const DEFAULT_RUNTIME = {
     sleep: async (milliseconds) => await new Promise((resolvePromise) => setTimeout(resolvePromise, milliseconds)),
     runProjectCommand,
     captureCommand,
+    updateCommand: runUpdateCommand,
+    packageDirectory: CLI_PACKAGE_DIRECTORY,
     authStore: createDefaultAuthStore(process.env),
     profileBindings: createDefaultProfileBindings(process.env),
     openBrowser: openSystemBrowser,
@@ -98,6 +101,16 @@ export async function runCli(argv, overrides = {}) {
     }
 }
 async function execute(topic, options, cwd, runtime) {
+    if (topic === "artifact finalize") {
+        const directory = resolve(cwd, requiredFlag(options, "artifact-directory"));
+        const before = await verifyArtifact(directory);
+        await packageAppWorkflows(cwd, before.directory, runtime.environment.WRANGLER_ENV);
+        const after = await verifyArtifact(directory);
+        if (before.envelope.sourceRevision !== after.envelope.sourceRevision)
+            throw new CliError("artifact_source_changed", "Packaging changed the attested source revision.");
+        return { value: { status: "verified", sourceRevision: after.envelope.sourceRevision, bundleDigest: after.envelope.bundleDigest,
+                artifactDirectory: after.directory, workflowCount: after.envelope.manifest.workflows?.declarations.length ?? 0, flags: after.envelope.manifest.flags ?? null } };
+    }
     if (topic.startsWith("workflows "))
         return { value: await workflowCommand(topic.slice(10), cwd, options, runtime) };
     if (topic.startsWith("email "))
@@ -105,6 +118,16 @@ async function execute(topic, options, cwd, runtime) {
     if (topic.startsWith("flagship "))
         return { value: await flagshipCommand(topic.slice(9), cwd, options, runtime) };
     switch (topic) {
+        case "upgrade":
+            if (options.positionals.length)
+                throw new CliError("argument_invalid", "upgrade does not accept positional arguments.");
+            return { value: await upgradeCli(updateRuntime(runtime)) };
+        case "config autoupgrade on":
+        case "config autoupgrade off":
+        case "config autoupgrade status":
+            if (options.positionals.length)
+                throw new CliError("argument_invalid", "autoupgrade does not accept positional arguments.");
+            return { value: await configureAutoUpgrade(topic.split(" ")[2], updateRuntime(runtime)) };
         case "docs": {
             const name = options.positionals[0];
             if (!name)
@@ -134,6 +157,14 @@ async function execute(topic, options, cwd, runtime) {
                 : { raw: await readSkill() };
         case "skill install":
             return { value: await installSkill(cwd, options, runtime) };
+        case "skill status":
+        case "skill sync": {
+            if (options.positionals.length)
+                throw new CliError("argument_invalid", "skill status/sync do not accept positional arguments.");
+            const { agent, base } = skillDestination(cwd, options, runtime);
+            const action = topic === "skill sync" ? syncDocumentation : skillDocumentationStatus;
+            return { value: { agent, ...await action(base, CLI_VERSION, { fetcher: runtime.fetcher }) } };
+        }
         case "skills list": {
             if (options.positionals.length)
                 throw new CliError("skills_arguments_invalid", "skills list does not accept positional arguments.");
@@ -2424,6 +2455,14 @@ async function optionalContext(cwd) {
     }
 }
 async function installSkill(cwd, options, runtime) {
+    const { agent, base } = skillDestination(cwd, options, runtime);
+    return { status: "installed", agent, ...await installDocumentation(base, options.booleans.has("force"), CLI_VERSION, { fetcher: runtime.fetcher, bundled: options.booleans.has("bundled") }) };
+}
+function updateRuntime(runtime) {
+    return { ...runtime, version: CLI_VERSION, runner: runtime.updateCommand, now: Date.now,
+        notify: message => { runtime.stderr.write(`${message}\n`); } };
+}
+function skillDestination(cwd, options, runtime) {
     const agent = options.flags.get("agent") ?? "codex";
     const requestedDirectory = options.flags.get("directory");
     const base = requestedDirectory
@@ -2436,7 +2475,7 @@ async function installSkill(cwd, options, runtime) {
     if (!base) {
         throw new CliError("skill_target_invalid", "--agent must be codex or claude unless --directory is provided.");
     }
-    return { status: "installed", agent, ...await installDocumentation(base, options.booleans.has("force"), CLI_VERSION, { fetcher: runtime.fetcher, bundled: options.booleans.has("bundled") }) };
+    return { agent, base };
 }
 async function readSkill() {
     return await readFile(skillPath(), "utf8");
@@ -2467,6 +2506,10 @@ function exampleConfig() {
     };
 }
 async function flagshipCommand(command, cwd, options, runtime) {
+    const definitionFile = async () => validateFlagDefinition(JSON.parse(new TextDecoder().decode(await readBoundedFile(resolve(cwd, requiredFlag(options, "file")), 192 * 1024))));
+    if (command === "flags validate")
+        return { schema: FLAGSHIP_SCHEMA, definition: await definitionFile() };
+    const createDefinition = command === "flags create" ? await definitionFile() : undefined;
     let environment;
     try {
         environment = flagEnvironment(requiredFlag(options, "env"));
@@ -2479,21 +2522,33 @@ async function flagshipCommand(command, cwd, options, runtime) {
     if (!projectId)
         throw new CliError("project_required", "Link a project or pass --project.");
     const { client } = await authenticatedClient(cwd, context?.link ?? null, options, runtime);
-    if (command.startsWith("apps "))
-        return client.flagship(projectId, ["apps", ...(command === "apps ensure" ? ["ensure"] : [])], environment, command === "apps ensure" ? { body: {} } : {});
+    if (command === "apps ensure" || command === "apps list")
+        return client.flagship(projectId, ["apps", ...(command === "apps ensure" ? ["ensure"] : [])], environment, command === "apps ensure" ? { body: { ...(options.flags.has("collection") ? { collection: options.flags.get("collection") } : {}) } } : {});
+    if (command.startsWith("apps ")) {
+        const action = command.slice(5), segments = ["apps", options.positionals[0], action];
+        if (action === "get")
+            return client.flagship(projectId, segments, environment);
+        const revision = requiredFlag(options, "expected-revision");
+        if (!/^\d+$/.test(revision) || !Number.isSafeInteger(Number(revision)))
+            throw new CliError("flagship_revision_invalid", "Use an observed collection revision.");
+        return client.flagship(projectId, segments, environment, { body: { expectedRevision: Number(revision), ...(action === "rename" ? { name: requiredFlag(options, "name") } : {}), ...(action === "delete" || action === "disconnect" ? { confirm: requiredFlag(options, "confirm") } : {}) } });
+    }
     const action = command.slice(6), app = options.positionals[0], key = options.positionals[1];
     const segments = ["flags", app, ...(key ? [flagKey(key)] : [])];
     if (action === "list" || action === "get")
         return client.flagship(projectId, segments, environment);
     segments.push(action);
-    if (action === "changelog")
+    if (action === "changelog" || action === "export")
         return client.flagship(projectId, segments, environment);
+    if (action === "diff")
+        return client.flagship(projectId, segments, environment, { body: { definition: await definitionFile() } });
     if (action === "evaluate") {
-        const context = requiredFlag(options, "context");
-        if (!context.startsWith("customerId="))
-            throw new CliError("flagship_context_invalid", "Use --context customerId=IDENTIFIER.");
-        const [customerId] = customerIds([context.slice(11)]);
-        return client.flagship(projectId, segments, environment, { customerId });
+        const file = options.flags.get("context-file");
+        const context = file ? flagContext(JSON.parse(new TextDecoder().decode(await readBoundedFile(resolve(cwd, file), 16 * 1024)))) : {};
+        const type = options.flags.get("type"), fallbackFile = options.flags.get("fallback-file");
+        if (!!type !== !!fallbackFile)
+            throw new CliError("flagship_fallback_type_invalid", "Choose both --type and --fallback-file.");
+        return client.flagship(projectId, segments, environment, { body: { context, ...(type ? { type, fallback: JSON.parse(new TextDecoder().decode(await readBoundedFile(resolve(cwd, fallbackFile), 10000))) } : {}) } });
     }
     const revision = options.flags.get("expected-revision");
     // Read before mutation by default. Server rechecks this revision inside serialization.
@@ -2508,31 +2563,23 @@ async function flagshipCommand(command, cwd, options, runtime) {
     else
         expectedRevision = (await client.flagship(projectId, segments.slice(0, -1), environment)).revision;
     const body = { expectedRevision };
-    if (action === "audience") {
-        const all = options.booleans.has("all"), file = options.flags.get("customer-ids-file");
-        if (all === !!file)
-            throw new CliError("flagship_audience_invalid", "Choose --all or --customer-ids-file.");
-        if (all)
-            body.all = true;
-        else {
-            let value;
-            try {
-                value = JSON.parse(new TextDecoder().decode(await readBoundedFile(resolve(cwd, file), 192 * 1024)));
-            }
-            catch {
-                throw new CliError("flagship_audience_invalid", "The customer ID file must contain a bounded JSON array.");
-            }
-            body.customerIds = customerIds(value);
+    if (action === "apply" || action === "delete") {
+        // General editing requires a reviewed revision and digest, rather than auto-adopting a new baseline.
+        if (revision === undefined)
+            throw new CliError("flagship_revision_required", "Review flags diff, then supply --expected-revision and --expected-digest.");
+        if (action === "apply")
+            body.definition = await definitionFile();
+        body.expectedDigest = requiredFlag(options, "expected-digest");
+        if (action === "delete") {
+            if (options.flags.get("confirm") !== key)
+                throw new CliError("flagship_delete_confirmation_required", `Use --confirm ${key} after cleanup. ${FLAG_DELETION_GUIDANCE}`);
+            body.confirm = key;
+            if (!options.booleans.has("json"))
+                runtime.stderr.write(`${FLAG_DELETION_GUIDANCE}\n`);
         }
     }
-    if (action === "rollout") {
-        if (requiredFlag(options, "to") !== "on" || requiredFlag(options, "by") !== "customerId")
-            throw new CliError("flagship_rollout_invalid", "V1 supports --to on --by customerId.");
-        const percentage = requiredFlag(options, "percentage");
-        if (!/^(?:\d+)(?:\.\d{1,2})?$/.test(percentage))
-            throw new CliError("flagship_percentage_invalid", "Use a percentage from 0 to 100 with at most two decimals.");
-        body.percentage = rolloutPercentage(Number(percentage));
-    }
+    if (action === "create")
+        body.definition = createDefinition;
     return client.flagship(projectId, segments, environment, { body });
 }
 function commandTopic(argv) {
@@ -2552,10 +2599,16 @@ function commandTopic(argv) {
         const topic = `preview ${argv[1]}`;
         return argv.includes("--help") || argv.includes("-h") ? { topic: "help", values: [topic] } : { topic, values: argv.slice(2) };
     }
-    if (parent === "email" || parent === "auth" || parent === "delivery" || parent === "source" || parent === "vars" || parent === "skill" || parent === "skills" || parent === "config" || parent === "production" || parent === "workflows") {
+    if (parent === "artifact" || parent === "email" || parent === "auth" || parent === "delivery" || parent === "source" || parent === "vars" || parent === "skill" || parent === "skills" || parent === "config" || parent === "production" || parent === "workflows") {
         const child = argv[1];
         if (!child || child.startsWith("--"))
             return { topic: "help", values: [parent] };
+        if (parent === "config" && child === "autoupgrade") {
+            const action = argv[2];
+            if (!action || action.startsWith("-") || argv.includes("--help") || argv.includes("-h"))
+                return { topic: "help", values: ["config autoupgrade"] };
+            return { topic: `config autoupgrade ${action}`, values: argv.slice(3) };
+        }
         if (parent === "source" && child === "merge" && argv[2] && !argv[2].startsWith("-")) {
             const topic = `source merge ${argv[2]}`;
             return argv.includes("--help") || argv.includes("-h") ? { topic: "help", values: [topic] } : { topic, values: argv.slice(3) };
@@ -2627,14 +2680,14 @@ function parseOptions(values) {
 function assertAllowedOptions(topic, options) {
     if (topic.startsWith("flagship ")) {
         const common = ["cwd", "json", "api-url", "token-stdin", "profile", "project", "env"];
-        const extras = { "flags create": ["expected-revision"], "flags enable": ["expected-revision"], "flags disable": ["expected-revision"],
-            "flags audience": ["expected-revision", "customer-ids-file", "all"], "flags rollout": ["expected-revision", "to", "percentage", "by"], "flags evaluate": ["context"], "flags reconcile": ["expected-revision"] };
+        const extras = { "apps ensure": ["collection"], "apps rename": ["expected-revision", "name"], "apps delete": ["expected-revision", "confirm"], "apps disconnect": ["expected-revision", "confirm"], "apps reconcile": ["expected-revision"], "flags delete": ["expected-revision", "expected-digest", "confirm"], "flags validate": ["file"], "flags diff": ["file"], "flags apply": ["file", "expected-revision", "expected-digest"], "flags create": ["expected-revision", "file"], "flags enable": ["expected-revision"], "flags disable": ["expected-revision"],
+            "flags evaluate": ["context-file", "type", "fallback-file"], "flags reconcile": ["expected-revision"] };
         const sub = topic.slice(9);
-        if (!["apps ensure", "apps list", "flags list", "flags get", "flags create", "flags enable", "flags disable", "flags audience", "flags rollout", "flags evaluate", "flags changelog", "flags reconcile"].includes(sub))
+        if (!["apps ensure", "apps list", "apps get", "apps rename", "apps delete", "apps disconnect", "apps reconcile", "flags list", "flags get", "flags export", "flags delete", "flags validate", "flags diff", "flags apply", "flags create", "flags enable", "flags disable", "flags evaluate", "flags changelog", "flags reconcile"].includes(sub))
             throw new CliError("argument_unknown", "Unknown flagship command.");
         if ([...options.flags.keys(), ...options.booleans].some(k => ![...common, ...(extras[sub] ?? [])].includes(k)))
             throw new CliError("argument_unknown", "Unsupported flagship option.");
-        const length = sub.startsWith("apps") ? 0 : sub === "flags list" ? 1 : 2;
+        const length = sub === "apps ensure" || sub === "apps list" || sub === "flags validate" ? 0 : sub.startsWith("apps") || sub === "flags list" ? 1 : 2;
         if (options.positionals.length !== length)
             throw new CliError("argument_required", `Expected ${length} positional arguments for ${topic}.`);
         return;
@@ -2642,6 +2695,11 @@ function assertAllowedOptions(topic, options) {
     const common = ["cwd", "json"];
     const authentication = ["api-url", "token-stdin", "profile"];
     const allowed = {
+        "artifact finalize": [...common, "artifact-directory"],
+        upgrade: common,
+        "config autoupgrade on": common,
+        "config autoupgrade off": common,
+        "config autoupgrade status": common,
         docs: common,
         capabilities: [...common, ...authentication, "project"],
         "email capabilities": [...common, ...authentication, "tenant", "project"],
@@ -2671,6 +2729,8 @@ function assertAllowedOptions(topic, options) {
         "config example": common,
         "skill print": common,
         "skill install": [...common, "agent", "directory", "force", "bundled"],
+        "skill status": [...common, "agent", "directory"],
+        "skill sync": [...common, "agent", "directory"],
         "skills list": [...common, ...authentication],
         "skills get": [...common, ...authentication],
         "skills file": [...common, ...authentication, "path"],
@@ -2880,8 +2940,25 @@ function writeOutput(value, options, runtime) {
     runtime.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
 }
 function helpText(topic) {
+    if (topic?.startsWith("config autoupgrade "))
+        topic = "config autoupgrade";
     if (topic === "flagship")
-        return "Usage: andeo flagship apps ensure|list --env development|preview|production [--project ID] [--json]\n       andeo flagship flags list APP_ID --env ENV\n       andeo flagship flags create|get|enable|disable|changelog|reconcile APP_ID KEY --env ENV [--expected-revision N]\n       andeo flagship flags audience APP_ID KEY --env ENV --customer-ids-file FILE|--all\n       andeo flagship flags rollout APP_ID KEY --env ENV --to on --percentage 5 --by customerId\n       andeo flagship flags evaluate APP_ID KEY --env ENV --context customerId=synthetic-customer-a\n\nDefaults off. Audience and percentage edits preserve each other and do not enable a disabled flag. Changes propagate; pending writes must be reconciled.";
+        return `Usage: andeo flagship apps ensure|list --env ENV [--collection NAME] [--project ID] [--json]
+       andeo flagship apps get|rename|disconnect|delete|reconcile APP_ID --env ENV [--expected-revision N] [--name NAME] [--confirm EXACT_ID]
+       andeo flagship flags validate --file flag.json --json
+       andeo flagship flags list APP_ID --env ENV
+       andeo flagship flags create APP_ID KEY --env ENV --file flag.json [--expected-revision N]
+       andeo flagship flags get|export|enable|disable|changelog|reconcile APP_ID KEY --env ENV [--expected-revision N]
+       andeo flagship flags diff APP_ID KEY --env ENV --file flag.json --json
+       andeo flagship flags apply APP_ID KEY --env ENV --file flag.json --expected-revision N --expected-digest SHA256 --json
+       andeo flagship flags delete APP_ID KEY --env ENV --expected-revision N --expected-digest SHA256 --confirm KEY
+       andeo flagship flags evaluate APP_ID KEY --env ENV [--context-file context.json] [--type boolean|string|number|json --fallback-file fallback.json]
+
+All definitions use one pinned native Flagship schema. Create requires a complete disabled definition; apply preserves enabled state. Disable returns the configured default, which may differ from the caller fallback. Targeting and rollouts are edited through full definitions; evaluation context uses --context-file. Management numeric/boolean context transport is unverified and fails explicitly; use native evaluation. Pending operations require reconciliation. No conversion analytics or significance calculation is connected.
+
+Flag deletion requires a disabled saved flag and exact --confirm KEY after cleanup. ${FLAG_DELETION_GUIDANCE} Andeo does not detect remaining evaluations automatically.`;
+    if (topic === "artifact" || topic === "artifact finalize")
+        return "Usage: andeo artifact finalize --artifact-directory DIR [--json]\n\nFinalize workflow coordinators and native Flagship declarations after producer packaging, retaining the attested source revision. Runs offline in the build checkout.";
     if (topic === "email" || topic?.startsWith("email "))
         return `Usage: andeo email <capabilities|create|list|cursor|wait|read|messages|retire> [options]
 
@@ -2911,6 +2988,8 @@ Choose background preview routing with preview-service-set --target-project PROJ
 Only non-secret JSON belongs in workflow params/events. Keep credentials in the connected service's native secrets.
 Account workflow entitlement is required for new starts. Run status is authoritative; list results are a timestamped projection.`;
     const topics = {
+        upgrade: "Usage: andeo upgrade [--json]\n\nUpgrade a verified global npm, pnpm or Yarn 1 installation to the latest stable CLI. Explicit upgrades can cross compatibility boundaries. CI, temporary npx and project-local installs must use their package manager. The next invocation uses the new CLI.",
+        "config autoupgrade": "Usage: andeo config autoupgrade <on|off|status> [--json]\n\nGlobal CLI upgrades default on and run after successful commands at most once daily. Before 1.0, only patches within the current minor are automatic; afterward, updates stay in the current major. Off retains daily reminders and independent global skill refresh. Help, version, CI and explicit maintenance commands skip automatic maintenance.",
         vars: "Usage: andeo vars <list|set|unset> --environment preview|production [options]\n\nManage saved non-secret runtime variables. Changes apply on the next delivery.",
         "source reconnect": "Usage: andeo source reconnect <prepare|status|complete|cancel> [options]\n\nMove a legacy managed repository to its tenant namespace by preparing, pushing, and completing.",
         "source reconnect prepare": "Usage: andeo source reconnect prepare --repository SRC_ID --idempotency-key KEY [--project PROJECT_ID] [--json]\n\nPause the old source and prepare its tenant destination. Merchant administrator required.",
@@ -2989,21 +3068,25 @@ Account workflow entitlement is required for new starts. Run status is authorita
         "preview entries": "Usage: andeo preview entries [--json]\n\nList eligible published entry apps and the selected default for this linked app.",
         "preview open": "Usage: andeo preview open --from dly_...|sbl_... [--through PROJECT_ID] [--return-path /account] [--json]\n\nOpen the exact deployed preview without rebuilding or uploading. Private apps open through their published connections. Opening again renews access.",
         "delivery retry": "Usage: andeo delivery retry --delivery dly_... [--reauthorize] [--json]\n\nRetry one requested or failed developer preview idempotently. --reauthorize explicitly authorizes a legacy preview for the same owner and linked project using the current CLI login; it cannot replace another login's recorded grant or publish production. Normal credential refresh needs no flag. A dwf_ production workflow is resumed by a merchant administrator from Activity.",
-        skill: "Usage: andeo skill <print|install> [options]",
+        skill: "Usage: andeo skill <print|install|status|sync> [options]",
+        "skill status": "Usage: andeo skill status [--agent codex|claude] [--directory PATH] [--json]\n\nCheck the installed guide against the compatible public revision. Reports local_changes, unmanaged or not_installed without overwriting files. Offline and incompatible checks fail explicitly.",
+        "skill sync": "Usage: andeo skill sync [--agent codex|claude] [--directory PATH] [--json]\n\nRefresh an existing, unchanged Andeo-managed guide. Preserve local edits and unrelated files. Outages and incompatible bundles retain installed guidance. After status=updated, reread SKILL.md and relevant references in active chats. Use skill install for a missing guide.",
         "skill print": "Usage: andeo skill print [--json]",
         "skill install": "Usage: andeo skill install [--agent codex|claude] [--directory PATH] [--force] [--bundled] [--json]\n\nFetch the latest compatible public Andeo guide without login. A fresh install falls back to the bundled guide during an outage; existing installations are preserved. --bundled explicitly selects this CLI's offline guide. --force replaces owned files, preserving unrelated files. Installs globally: ~/.agents/skills for Codex or ~/.claude/skills for Claude. --directory overrides the location.\n\nExamples:\n  andeo skill install --agent codex --json\n  andeo skill install --agent codex --force --json\n  andeo skill install --bundled --directory ./skills --json",
         skills: "Usage: andeo skills <list|get|file> [options]\n\nAuthenticated, session-only access to Andeo practice skills. Content is not installed into the repository.\n\nExamples:\n  andeo skills list --json\n  andeo skills get recharge-client\n  andeo skills file recharge-customer-operations --path references/subscriptions.md",
         "skills list": "Usage: andeo skills list [--profile NAME] [--api-url URL] [--json]\n\nList the practice skills available to the authenticated Andeo user.",
         "skills get": "Usage: andeo skills get SKILL_ID [--profile NAME] [--api-url URL] [--json]\n\nRead one skill entrypoint for the current invocation.\n\nExample:\n  andeo skills get guardrailed-design-system",
         "skills file": "Usage: andeo skills file SKILL_ID --path PATH [--profile NAME] [--api-url URL] [--json]\n\nRead one catalog-listed supporting file for the current invocation.\n\nExample:\n  andeo skills file recharge-customer-operations --path references/subscriptions.md",
-        config: "Usage: andeo config example [--json]",
+        config: "Usage: andeo config example [--json]\n       andeo config autoupgrade <on|off|status> [--json]",
         "config example": "Usage: andeo config example [--json]\n\nPrint the committed tender-accounts.json contract.",
     };
     if (topic && topics[topic])
         return topics[topic];
-    return `Andeo merchant developer CLI ${CLI_VERSION}\n\nCommands:\n  docs              Read version-matched offline guides\n  capabilities      Inspect scoped support, enablement and permissions\n  init              Create a new Shopify account starter\n  auth login        Create or refresh the default login\n  auth create       Create or re-authorize a named login\n  auth activate     Bind a named login to a directory tree\n  auth deactivate   Remove an exact directory binding\n  auth status       Validate one login or scoped credential\n  auth list         List local login profiles and bindings\n  auth delete       Revoke one named login\n  auth logout       Revoke the default or every login\n  link              Link this checkout to one permitted project\n  doctor            Check developer readiness\n  dev               Run the project-owned local dev command\n  check             Run project validation\n  build             Package and verify a portable artifact\n  upload            Retain a build for administrator publication\n  preview           Build and deploy an exact preview\n  preview entries   List eligible connected entry apps\n  preview open      Reopen an exact deployed preview\n  source status     Inspect Andeo-managed Git and recent builds\n  source branches   List exact managed branches and default policy\n  source compare    Compare two managed branches\n  source connect    Connect this linked project to managed Git\n  source reconnect  Prepare, inspect, complete or cancel a tenant namespace cutover\n  source pull       Clone or fast-forward the exact connected repository\n  source token      Issue a short-lived repository credential\n  source push       Push the exact commit without persisting a token\n  source promote    Fast-forward the default after successful preview checks\n  source history    Run guarded, archived source-history migration\n  email             Create and reuse merchant email identities\n  workflows         Inspect and control app-defined background runs\n  vars              Manage saved per-environment runtime variables\n  source policy     Inspect or change automatic publication\n  tail              Stream logs for one exact linked project\n  delivery status   Read preview workflow state\n  delivery retry    Retry a failed preview workflow\n  skill install     Install the Andeo agent skill\n  skills list       Discover authenticated practice skills\n  skills get        Read an authenticated practice skill\n  skills file       Read one authenticated skill resource\n  config example    Print the project configuration contract\n\nThere is intentionally no production publish command.\nRun andeo <command> --help for examples.`;
+    return `Andeo merchant developer CLI ${CLI_VERSION}\n\nCommands:\n  docs              Read version-matched offline guides\n  capabilities      Inspect scoped support, enablement and permissions\n  init              Create a new Shopify account starter\n  auth login        Create or refresh the default login\n  auth create       Create or re-authorize a named login\n  auth activate     Bind a named login to a directory tree\n  auth deactivate   Remove an exact directory binding\n  auth status       Validate one login or scoped credential\n  auth list         List local login profiles and bindings\n  auth delete       Revoke one named login\n  auth logout       Revoke the default or every login\n  link              Link this checkout to one permitted project\n  doctor            Check developer readiness\n  dev               Run the project-owned local dev command\n  check             Run project validation\n  build             Package and verify a portable artifact\n  upload            Retain a build for administrator publication\n  preview           Build and deploy an exact preview\n  preview entries   List eligible connected entry apps\n  preview open      Reopen an exact deployed preview\n  source status     Inspect Andeo-managed Git and recent builds\n  source branches   List exact managed branches and default policy\n  source compare    Compare two managed branches\n  source connect    Connect this linked project to managed Git\n  source reconnect  Prepare, inspect, complete or cancel a tenant namespace cutover\n  source pull       Clone or fast-forward the exact connected repository\n  source token      Issue a short-lived repository credential\n  source push       Push the exact commit without persisting a token\n  source promote    Fast-forward the default after successful preview checks\n  source history    Run guarded, archived source-history migration\n  email             Create and reuse merchant email identities\n  workflows         Inspect and control app-defined background runs\n  vars              Manage saved per-environment runtime variables\n  source policy     Inspect or change automatic publication\n  tail              Stream logs for one exact linked project\n  delivery status   Read preview workflow state\n  delivery retry    Retry a failed preview workflow\n  upgrade           Upgrade a verified global CLI installation\n  config autoupgrade Configure automatic CLI upgrades\n  skill install     Install the Andeo agent skill\n  skill status      Inspect installed guidance freshness\n  skill sync        Refresh unchanged managed guidance\n  skills list       Discover authenticated practice skills\n  skills get        Read an authenticated practice skill\n  skills file       Read one authenticated skill resource\n  config example    Print the project configuration contract\n\nThere is intentionally no production publish command.\nRun andeo <command> --help for examples.`;
 }
 function normalizeError(error) {
+    if (error instanceof FlagCompatibilityError)
+        return { code: error.code, message: error.message, details: { field: error.field, schema: FLAGSHIP_SCHEMA } };
     if (error instanceof CliApiError) {
         return { code: error.code, message: error.message, ...(error.hint ? { hint: error.hint } : {}), ...(error.requestId ? { requestId: error.requestId } : {}), ...(error.details ? { details: error.details } : {}) };
     }