@withandeo/cli 0.19.9 → 0.19.11

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":"AAAA,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,YAAY,EAAwD,MAAM,wBAAwB,CAAC;AAYjJ,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,OAAoB,EAAE,IAAuB,EAAE,OAAoB;IACzG,YAAY,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC5B,IAAI,aAAa,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,IAAI,CAAC,IAAI;QAAE,MAAM,IAAI,KAAK,CAAC,gCAAgC,CAAC,CAAC;IAClG,QAAQ,IAAI,CAAC,IAAI,EAAE,CAAC;QAClB,KAAK,SAAS,EAAE,OAAO,OAAO,CAAC,iBAAiB,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,QAAmB,EAAE,OAAO,CAAC,CAAC;QAC9F,KAAK,QAAQ,EAAE,OAAO,OAAO,CAAC,gBAAgB,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,QAAkB,EAAE,OAAO,CAAC,CAAC;QAC3F,KAAK,QAAQ,EAAE,OAAO,OAAO,CAAC,gBAAgB,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,QAAkB,EAAE,OAAO,CAAC,CAAC;QAC3F,KAAK,MAAM,EAAE,OAAO,OAAO,CAAC,gBAAgB,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IACjF,CAAC;AACH,CAAC;AACD;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,KACmE;IACnG,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,EAAE,IAAI,IAAI,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,KAAK,KAAK,CAAC,KAAK,CAAC,MAAM;QAAE,MAAM,IAAI,KAAK,CAAC,oCAAoC,CAAC,CAAC;IACvJ,YAAY,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAC1B,KAAI,MAAM,IAAI,IAAI,KAAK,CAAC,KAAK,EAAC,CAAC;QAAA,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAAA,IAAG,aAAa,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAG,IAAI,CAAC,IAAI;YAAC,MAAM,IAAI,KAAK,CAAC,oCAAoC,CAAC,CAAC;IAAA,CAAC;IACpJ,MAAM,KAAK,GAAC,eAAe,CAAC,KAAK,CAAC,KAAK,CAAC,EAAC,EAAC,OAAO,EAAC,WAAW,EAAC,cAAc,EAAC,GAAC,KAAK,CAAC;IACpF,MAAM,cAAc,GAAG,KAAK,CAAC,cAAc,IAAI,KAAK,CAAC;IACrD,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,cAAc,CAAC,IAAI,cAAc,GAAG,CAAC,IAAI,cAAc,GAAG,KAAK;QAAE,MAAM,IAAI,KAAK,CAAC,0BAA0B,CAAC,CAAC;IACvI,OAAO,KAAK,EAAE,OAAgB,EAAqB,EAAE;QACnD,IAAI,OAAO,CAAC,MAAM,KAAK,KAAK;YAAE,OAAO,IAAI,QAAQ,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC;QACpG,kFAAkF;QAClF,IAAI,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM;YAAE,OAAO,IAAI,QAAQ,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC;QAC5E,MAAM,OAAO,GAAG,WAAW,CAAC,MAAM,cAAc,CAAC,OAAO,CAAC,CAAC,CAAC;QAC3D,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,EAAC,IAAI,EAAC,EAAE;YACvD,IAAI,OAA0B,CAAC;YAC/B,IAAI,CAAC;gBAAC,OAAO,GAAG,MAAM,iBAAiB,CAAC,OAAO,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;YAAC,CAAC;YAClE,MAAM,CAAC;gBAAC,OAAO,GAAG,EAAE,OAAO,EAAE,IAAI,CAAC,GAAG,EAAE,KAAK,EAAE,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,CAAC;YAAC,CAAC;YACvG,wEAAwE;YACxE,MAAM,aAAa,GAAG,EAAE,OAAO,EAAE,IAAI,CAAC,GAAG,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBACvH,GAAG,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;YAC1H,YAAY,CAAC,aAAa,CAAC,CAAC;YAAC,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,aAAa,CAAU,CAAC;QACzE,CAAC,CAAC,CAAC,CAAC;QACJ,MAAM,SAAS,GAAkB,EAAE,MAAM,EAAE,yBAAyB,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC,EAAE,CAAC;QACzI,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;QACvC,IAAI,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,GAAG,EAAE,GAAG,IAAI;YAAE,MAAM,IAAI,KAAK,CAAC,kCAAkC,CAAC,CAAC;QAC3G,OAAO,IAAI,QAAQ,CAAC,IAAI,EAAE,EAAE,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE,eAAe,EAAE,mBAAmB,EAAE,IAAI,EAAE,uBAAuB,EAAE,EAAE,CAAC,CAAC;IACtJ,CAAC,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,YAAY,CAAC,OAA0B,EAAE,WAAmB,EAAE,iBAAyB;IACrG,IAAI,OAAO,CAAC,SAAS,IAAI,OAAO,CAAC,MAAM,KAAK,OAAO,IAAI,OAAO,CAAC,MAAM,KAAK,UAAU,IAAI,OAAO,CAAC,MAAM,KAAK,SAAS,IAAI,CAAC,OAAO,CAAC,OAAO,IAAI,CAAC,iBAAiB;QAAE,OAAO,IAAI,CAAC;IAC5K,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,WAAW,EAAE,iBAAiB,EAAE,CAAC;AACxH,CAAC;AACD;;GAEG;AACH,MAAM,UAAU,mBAAmB,CAAC,OAAgB,EAAE,KAAK,GAAG,KAAK;IACjE,MAAM,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,qBAAqB,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,CAAC,CAAC;IACxI,IAAI,CAAC,KAAK,IAAI,QAAQ,IAAI,iBAAiB,CAAC,IAAI,CAAC,QAAQ,CAAC;QAAE,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,CAAC;IAC9F,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,QAAQ,GAAG,CAAC,WAAW,EAAE,WAAW,EAAE,OAAO,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACxG,IAAI,GAAG,CAAC,QAAQ,KAAK,QAAQ,IAAI,CAAC,QAAQ;QAAE,MAAM,IAAI,KAAK,CAAC,kCAAkC,CAAC,CAAC;IAChG,MAAM,YAAY,GAAG,MAAM,CAAC,UAAU,EAAE,CAAC;IACzC,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,sBAAsB,YAAY,qDAAqD,GAAG,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC;AAC3K,CAAC"}

package/dist/main.js

@@ -20,7 +20,7 @@ import { initializeStarter } from "./starter.js";
 import { normalizeAndeoEnvironment } from "./andeo-environment.js";
 import { DOC_TOPICS, readDocumentation, installDocumentation, installedSkillCheck } from "./documentation.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.");
@@ -98,6 +98,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 "))
@@ -1890,7 +1900,7 @@ async function linkProject(cwd, options, runtime) {
 }
 async function doctor(cwd, options, runtime) {
     const checks = [];
-    checks.push(await installedSkillCheck(runtime.homeDirectory));
+    checks.push(await installedSkillCheck(runtime.homeDirectory, { fetcher: runtime.fetcher, cliVersion: CLI_VERSION }));
     const nodeMajor = Number(process.versions.node.split(".")[0]);
     checks.push({
         name: "node",
@@ -2436,7 +2446,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) };
+    return { status: "installed", agent, ...await installDocumentation(base, options.booleans.has("force"), CLI_VERSION, { fetcher: runtime.fetcher, bundled: options.booleans.has("bundled") }) };
 }
 async function readSkill() {
     return await readFile(skillPath(), "utf8");
@@ -2467,6 +2477,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 +2493,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 +2534,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,7 +2570,7 @@ 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] };
@@ -2595,7 +2613,7 @@ function parseOptions(values) {
     const booleans = new Set();
     const positionals = [];
     const booleanNames = new Set([
-        "json", "token-stdin", "dry-run", "no-wait", "force", "reauthorize", "authorize",
+        "json", "token-stdin", "dry-run", "no-wait", "force", "reauthorize", "authorize", "bundled",
         "device", "wait", "no-open", "local", "all", "production",
     ]);
     for (let index = 0; index < values.length; index += 1) {
@@ -2627,14 +2645,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 +2660,7 @@ function assertAllowedOptions(topic, options) {
     const common = ["cwd", "json"];
     const authentication = ["api-url", "token-stdin", "profile"];
     const allowed = {
+        "artifact finalize": [...common, "artifact-directory"],
         docs: common,
         capabilities: [...common, ...authentication, "project"],
         "email capabilities": [...common, ...authentication, "tenant", "project"],
@@ -2670,7 +2689,7 @@ function assertAllowedOptions(topic, options) {
         init: [...common, "name", "slug", "directory", "template", "dry-run"],
         "config example": common,
         "skill print": common,
-        "skill install": [...common, "agent", "directory", "force"],
+        "skill install": [...common, "agent", "directory", "force", "bundled"],
         "skills list": [...common, ...authentication],
         "skills get": [...common, ...authentication],
         "skills file": [...common, ...authentication, "path"],
@@ -2881,7 +2900,22 @@ function writeOutput(value, options, runtime) {
 }
 function helpText(topic) {
     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]
 
@@ -2991,7 +3025,7 @@ Account workflow entitlement is required for new starts. Run status is authorita
         "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 print": "Usage: andeo skill print [--json]",
-        "skill install": "Usage: andeo skill install [--agent codex|claude] [--directory PATH] [--force] [--json]\n\nInstall globally for the current user by default: ~/.agents/skills for Codex or ~/.claude/skills for Claude. --directory is an explicit custom or repository-local override.",
+        "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",
@@ -3004,6 +3038,8 @@ Account workflow entitlement is required for new starts. Run status is authorita
     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.`;
 }
 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 } : {}) };
     }