@withandeo/cli 0.19.8 → 0.19.10

package/dist/main.js

@@ -20,6 +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";
 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.");
@@ -101,6 +102,8 @@ async function execute(topic, options, cwd, runtime) {
         return { value: await workflowCommand(topic.slice(10), cwd, options, runtime) };
     if (topic.startsWith("email "))
         return { value: await emailCommand(topic.slice(6), cwd, options, runtime) };
+    if (topic.startsWith("flagship "))
+        return { value: await flagshipCommand(topic.slice(9), cwd, options, runtime) };
     switch (topic) {
         case "docs": {
             const name = options.positionals[0];
@@ -225,7 +228,27 @@ async function execute(topic, options, cwd, runtime) {
             return { value: await sourceChangeCreate(cwd, options, runtime) };
         case "source merge": {
             const value = await sourceMerge(cwd, options, runtime);
-            return { value, exitCode: value.status === "timeout" ? 3 : value.merge && ["awaiting_approval", "needs_attention", "superseded", "authorization_required", "cancelled"].includes(value.merge.stage) ? 2 : 0 };
+            return { value, exitCode: value.status === "timeout" ? 3 : value.merge && ["awaiting_approval", "needs_attention", "superseded", "authorization_required", "reconciliation_required", "cancelled"].includes(value.merge.stage) ? 2 : 0 };
+        }
+        case "source merge status":
+        case "source merge resume":
+        case "source merge cancel":
+        case "source merge take-over": {
+            const mergeId = requiredFlag(options, "merge");
+            if (!/^smi_[A-Za-z0-9_-]+$/.test(mergeId))
+                throw new CliError("argument_invalid", "--merge must be a merge intent ID (smi_...).");
+            const key = topic === "source merge take-over" ? requiredFlag(options, "idempotency-key") : undefined;
+            if (key && !/^[A-Za-z0-9:_-]{8,128}$/.test(key))
+                throw new CliError("argument_invalid", "--idempotency-key must contain 8–128 letters, numbers, colons, underscores or hyphens.");
+            const access = await sourceReadAccess(cwd, options, runtime);
+            const current = await access.client.sourceMergeStatus(mergeId);
+            requireLinkedSourceChange(access.projectId, current.merge.projectId);
+            if (current.merge.id !== mergeId || current.merge.repositoryId !== access.repository.id)
+                throw new CliError("source_merge_changed", "The returned merge does not match this repository and intent.");
+            if (topic === "source merge status")
+                return { value: current };
+            return { value: topic === "source merge resume" ? await access.client.resumeSourceMergeById(mergeId)
+                    : key ? await access.client.takeOverSourceMergeById(mergeId, key) : await access.client.cancelSourceMergeById(mergeId) };
         }
         case "source change resume": {
             const access = await sourceReadAccess(cwd, options, runtime);
@@ -249,13 +272,17 @@ async function execute(topic, options, cwd, runtime) {
             if (topic === "source merge-policy show")
                 return { value: await access.client.sourceMergePolicy(access.repository.id) };
             const mode = requiredFlag(options, "mode");
-            if (!["human-review", "agent"].includes(mode))
-                throw new CliError("source_merge_policy_invalid", "--mode must be human-review or agent.");
+            if (!["human-review", "agent", "administrator-authorized"].includes(mode))
+                throw new CliError("source_merge_policy_invalid", "--mode must be human-review, agent or administrator-authorized.");
+            const principalIds = (options.flags.get("principals") ?? "").split(",").filter(Boolean);
+            if (mode === "administrator-authorized" && principalIds.length)
+                throw new CliError("source_merge_policy_invalid", "Administrator-authorized mode requires exact per-operation approval; omit --principals.");
             const executionSeconds = options.flags.has("execution-seconds") ? Number(options.flags.get("execution-seconds")) : undefined;
             if (executionSeconds !== undefined && (!Number.isSafeInteger(executionSeconds) || executionSeconds < 300 || executionSeconds > 86400))
                 throw new CliError("argument_invalid", "--execution-seconds must be between 300 and 86400.");
             return { value: await access.client.sourceMergePolicy(access.repository.id, { enabled: mode === "agent",
-                    principalIds: (options.flags.get("principals") ?? "").split(",").filter(Boolean),
+                    principalIds, validationMode: mode === "administrator-authorized" ? "administrator_authorized" : "native_preview",
+                    buildAdmission: mode === "administrator-authorized" ? "source_only" : "native",
                     expectedRevision: Number(requiredFlag(options, "expected-revision")), idempotencyKey: requiredFlag(options, "idempotency-key"), executionSeconds }) };
         }
         case "source change list":
@@ -1329,9 +1356,34 @@ async function sourceMerge(cwd, options, runtime) {
         throw new CliError("argument_invalid", "--expected-head must be a commit SHA.");
     if (expectedSnapshot && (!changeId || !Number.isSafeInteger(Number(expectedSnapshot)) || Number(expectedSnapshot) < 1))
         throw new CliError("argument_invalid", "--expected-snapshot requires --change and a positive integer.");
+    const expectedBase = options.flags.get("expected-base"), policyRevision = options.flags.get("expected-policy-revision");
+    const validationMode = options.flags.get("validation-mode"), continuation = options.flags.get("continuation");
+    const authorize = options.booleans.has("authorize"), dryRun = options.booleans.has("dry-run"), note = options.flags.get("note");
+    if (expectedBase && !/^[a-f0-9]{40}$/.test(expectedBase))
+        throw new CliError("argument_invalid", "--expected-base must be a commit SHA.");
+    if (policyRevision !== undefined && (!/^\d+$/.test(policyRevision) || !Number.isSafeInteger(Number(policyRevision))))
+        throw new CliError("argument_invalid", "--expected-policy-revision must be a nonnegative integer.");
+    if (validationMode !== undefined && validationMode !== "native_preview" && validationMode !== "administrator_authorized")
+        throw new CliError("argument_invalid", "--validation-mode must be native_preview or administrator_authorized.");
+    if (continuation !== undefined && continuation !== "source_only")
+        throw new CliError("argument_invalid", "--continuation must be source_only.");
+    if (note !== undefined && (note.length < 1 || note.length > 1000))
+        throw new CliError("argument_invalid", "--note must contain 1–1000 characters.");
+    if (validationMode === "administrator_authorized") {
+        if (changeId || expectedSnapshot)
+            throw new CliError("argument_invalid", "Administrator-authorized merges use --head and --title without a native change request.");
+        if (!dryRun && (!authorize || !expectedBase || !expectedHead || policyRevision === undefined))
+            throw new CliError("argument_invalid", "Administrator-authorized merges require --authorize, --expected-base, --expected-head and --expected-policy-revision. Use --dry-run to inspect the exact snapshot first.");
+    }
+    else if (authorize || expectedBase !== undefined || policyRevision !== undefined || continuation !== undefined || note !== undefined) {
+        throw new CliError("argument_invalid", "Administrator authorization flags require --validation-mode administrator_authorized.");
+    }
     const access = await sourceReadAccess(cwd, options, runtime);
     const result = await access.client.sourceMerge(access.repository.id, { headBranch, title, changeId, idempotencyKey,
-        expectedHead, expectedSnapshot: expectedSnapshot ? Number(expectedSnapshot) : undefined, dryRun: options.booleans.has("dry-run") });
+        expectedHead, expectedSnapshot: expectedSnapshot ? Number(expectedSnapshot) : undefined, dryRun,
+        expectedBase, expectedPolicyRevision: policyRevision === undefined ? undefined : Number(policyRevision),
+        validationMode, authorize: validationMode === "administrator_authorized" ? authorize : undefined,
+        continuation: validationMode === "administrator_authorized" ? "source_only" : undefined, note });
     if (result.merge) {
         requireLinkedSourceChange(access.projectId, result.merge.projectId);
         if (result.merge.repositoryId !== access.repository.id)
@@ -1341,13 +1393,14 @@ async function sourceMerge(cwd, options, runtime) {
         return result;
     let merge = result.merge;
     for (let poll = 0; poll < Math.ceil(timeout / 5); poll++) {
-        if (["deployed", "needs_attention", "publication_not_enabled", "superseded", "authorization_required", "cancelled"].includes(merge.stage))
+        if (merge.terminal || ["merged", "deployed", "needs_attention", "publication_not_enabled", "superseded", "authorization_required", "reconciliation_required", "cancelled"].includes(merge.stage))
             return { ...result, merge };
         if (merge.stage === "awaiting_approval")
             return { ...result, merge };
         await runtime.sleep(Math.min(5000, timeout * 1000 - poll * 5000));
-        const current = await access.client.sourceChangeRequest(merge.changeId);
-        requireLinkedSourceChange(access.projectId, current.changeRequest.projectId);
+        const current = merge.changeId ? await access.client.sourceChangeRequest(merge.changeId) : await access.client.sourceMergeStatus(merge.id);
+        if ("changeRequest" in current)
+            requireLinkedSourceChange(access.projectId, current.changeRequest.projectId);
         if (!current.merge || current.merge.id !== merge.id)
             throw new CliError("source_merge_changed", "The merge intent changed. Inspect this exact change before continuing.");
         requireLinkedSourceChange(access.projectId, current.merge.projectId);
@@ -1355,7 +1408,10 @@ async function sourceMerge(cwd, options, runtime) {
             throw new CliError("source_merge_changed", "The returned merge belongs to another repository.");
         merge = current.merge;
     }
-    return { ...result, status: "timeout", merge: { ...merge, waitTimedOut: true }, next: `andeo source change show --change ${merge.changeId} --json` };
+    if (merge.terminal || ["merged", "deployed", "awaiting_approval", "needs_attention", "publication_not_enabled", "superseded", "authorization_required", "reconciliation_required", "cancelled"].includes(merge.stage))
+        return { ...result, merge };
+    return { ...result, status: "timeout", merge: { ...merge, waitTimedOut: true }, next: merge.changeId
+            ? `andeo source change show --change ${merge.changeId} --json` : `andeo source merge status --merge ${merge.id} --json` };
 }
 async function sourceChangeCreate(cwd, options, runtime) {
     const access = await sourceReadAccess(cwd, options, runtime);
@@ -1834,7 +1890,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",
@@ -2380,7 +2436,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");
@@ -2410,7 +2466,82 @@ function exampleConfig() {
         returnPath: "/account",
     };
 }
+async function flagshipCommand(command, cwd, options, runtime) {
+    let environment;
+    try {
+        environment = flagEnvironment(requiredFlag(options, "env"));
+    }
+    catch {
+        throw new CliError("flagship_environment_invalid", "Use --env development, preview, or production explicitly.");
+    }
+    const context = await optionalContext(cwd);
+    const projectId = options.flags.get("project") ?? context?.link?.projectId;
+    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: {} } : {});
+    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")
+        return client.flagship(projectId, segments, environment);
+    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 revision = options.flags.get("expected-revision");
+    // Read before mutation by default. Server rechecks this revision inside serialization.
+    let expectedRevision;
+    if (revision !== undefined) {
+        expectedRevision = Number(revision);
+        if (!/^\d+$/.test(revision) || !Number.isSafeInteger(expectedRevision))
+            throw new CliError("flagship_revision_invalid", "Expected revision must be a nonnegative integer.");
+    }
+    else if (action === "create")
+        expectedRevision = 0;
+    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 === "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));
+    }
+    return client.flagship(projectId, segments, environment, { body });
+}
 function commandTopic(argv) {
+    if (argv[0] === "flagship") {
+        const topic = argv.slice(0, 3).join(" ");
+        if (argv.length < 3 || argv.includes("--help") || argv.includes("-h"))
+            return { topic: "help", values: ["flagship"] };
+        return { topic, values: argv.slice(3) };
+    }
     if (argv.length === 0 || argv[0] === "help" || argv[0] === "--help" || argv[0] === "-h") {
         return { topic: "help", values: argv.slice(1) };
     }
@@ -2425,6 +2556,10 @@ function commandTopic(argv) {
         const child = argv[1];
         if (!child || child.startsWith("--"))
             return { topic: "help", values: [parent] };
+        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) };
+        }
         if (parent === "source" && (child === "default" || child === "history" || child === "operation" || child === "change" || child === "policy" || child === "merge-policy" || child === "reconnect" || child === "branch")) {
             const grandchild = argv[2];
             if (!grandchild || grandchild.startsWith("--"))
@@ -2460,7 +2595,7 @@ function parseOptions(values) {
     const booleans = new Set();
     const positionals = [];
     const booleanNames = new Set([
-        "json", "token-stdin", "dry-run", "no-wait", "force", "reauthorize",
+        "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) {
@@ -2490,6 +2625,20 @@ function parseOptions(values) {
     return { flags, booleans, positionals, json: booleans.has("json") };
 }
 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 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))
+            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;
+        if (options.positionals.length !== length)
+            throw new CliError("argument_required", `Expected ${length} positional arguments for ${topic}.`);
+        return;
+    }
     const common = ["cwd", "json"];
     const authentication = ["api-url", "token-stdin", "profile"];
     const allowed = {
@@ -2521,7 +2670,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"],
@@ -2588,7 +2737,12 @@ function assertAllowedOptions(topic, options) {
         "source operation status": [...common, ...authentication, "operation"],
         "source operation retry": [...common, ...authentication, "operation", "no-wait", "timeout-seconds"],
         "source change create": [...common, ...authentication, "project", "title", "description", "base", "head"],
-        "source merge": [...common, ...authentication, "project", "head", "title", "change", "expected-head", "expected-snapshot", "idempotency-key", "dry-run", "wait", "no-wait", "timeout-seconds"],
+        "source merge": [...common, ...authentication, "project", "head", "title", "change", "expected-head", "expected-snapshot", "idempotency-key", "dry-run", "wait", "no-wait", "timeout-seconds",
+            "expected-base", "expected-policy-revision", "validation-mode", "authorize", "continuation", "note"],
+        "source merge status": [...common, ...authentication, "project", "merge"],
+        "source merge resume": [...common, ...authentication, "project", "merge"],
+        "source merge cancel": [...common, ...authentication, "project", "merge"],
+        "source merge take-over": [...common, ...authentication, "project", "merge", "idempotency-key"],
         "source change resume": [...common, ...authentication, "project", "change"],
         "source change cancel": [...common, ...authentication, "project", "change"],
         "source change take-over": [...common, ...authentication, "project", "change", "idempotency-key"],
@@ -2726,6 +2880,8 @@ function writeOutput(value, options, runtime) {
     runtime.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
 }
 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.";
     if (topic === "email" || topic?.startsWith("email "))
         return `Usage: andeo email <capabilities|create|list|cursor|wait|read|messages|retire> [options]
 
@@ -2805,11 +2961,15 @@ Account workflow entitlement is required for new starts. Run status is authorita
         "source change": "Usage: andeo source change <create|list|show|close|resume|cancel|take-over> [options]\n\nCreate and inspect exact preview-backed changes, or recover an accepted merge intent.",
         "source change cancel": "Usage: andeo source change cancel --change scr_... [--json]\n\nWithdraw new work for an accepted intent. Already-issued effects require readback; source may already be merged.",
         "source change take-over": "Usage: andeo source change take-over --change scr_... --idempotency-key KEY [--json]\n\nAdministrator only. Records a new bounded authorization for the same exact inputs; then use source change resume.",
-        "source merge": "Usage: andeo source merge --head BRANCH --title TITLE --idempotency-key KEY [--dry-run] [--wait] [--timeout-seconds N] [--json]\n       andeo source merge --change scr_... --idempotency-key KEY [--wait] [--json]\n\nRequest exact fast-forward landing and follow the saved publication policy. Human review remains the default; agent merging requires an administrator policy and principal grant. Waiting is bounded and never cancels hosted work.\n\nExamples:\n  andeo source merge --head feature/copy --title \"Update copy\" --idempotency-key account-copy-v1 --dry-run --json\n  andeo source merge --head feature/copy --title \"Update copy\" --idempotency-key account-copy-v1 --wait --json",
+        "source merge": "Usage: andeo source merge --head BRANCH --title TITLE --idempotency-key KEY [--dry-run] [--wait] [--timeout-seconds N] [--json]\n       andeo source merge --change scr_... --idempotency-key KEY [--wait] [--json]\n       andeo source merge --head BRANCH --title TITLE --validation-mode administrator_authorized --expected-base SHA --expected-head SHA --expected-policy-revision N --authorize --idempotency-key KEY [--continuation source_only] [--note TEXT] [--wait] [--json]\n       andeo source merge <status|resume|cancel|take-over> --merge smi_... [options]\n\nRequest exact fast-forward landing. Native review remains the default. Administrator-authorized source-only mode requires saved policy and a current administrator; Andeo does not independently verify checks. Inspect refs and blockers with --dry-run before authorizing. Waiting is bounded and never cancels hosted work.\n\nExamples:\n  andeo source merge --head feature/copy --title \"Update copy\" --idempotency-key account-copy-v1 --dry-run --json\n  andeo source merge --head feature/copy --title \"Update copy\" --idempotency-key account-copy-v1 --wait --json",
+        "source merge status": "Usage: andeo source merge status --merge smi_... [--json]\n\nRead the retained source, validation, authorization, continuation and cleanup outcomes. Source-only merged is successful completion.",
+        "source merge resume": "Usage: andeo source merge resume --merge smi_... [--json]\n\nResume the same exact eligible intent after revalidating authority. Never substitutes a new source snapshot.",
+        "source merge cancel": "Usage: andeo source merge cancel --merge smi_... [--json]\n\nWithdraw new work. Already-issued effects require readback; cancellation cannot undo a merge.",
+        "source merge take-over": "Usage: andeo source merge take-over --merge smi_... --idempotency-key KEY [--json]\n\nAdministrator only. Take ownership of the retained exact source snapshot before resuming.",
         "source merge-policy": "Usage: andeo source merge-policy <show|set> [options]",
         "source change resume": "Usage: andeo source change resume --change scr_... [--json]\n\nResume the same eligible merge intent or exact failed publication. Revalidates authority and retained lineage; never creates a replacement build.\n\nExample:\n  andeo source change resume --change scr_... --json",
         "source merge-policy show": "Usage: andeo source merge-policy show [--json]\n\nRead the saved merge policy and explicit principal grants.",
-        "source merge-policy set": "Usage: andeo source merge-policy set --mode human-review|agent --principals PRINCIPAL_IDS --expected-revision N --idempotency-key KEY [--json]\n\nAdministrator only. Grants are comma-separated stable principal IDs. This never changes publication policy.\n\nExample:\n  andeo source merge-policy set --mode agent --principals principal_example --expected-revision 0 --idempotency-key merge-policy-v1 --json",
+        "source merge-policy set": "Usage: andeo source merge-policy set --mode human-review|agent|administrator-authorized [--principals PRINCIPAL_IDS] --expected-revision N --idempotency-key KEY [--json]\n\nAdministrator only. Agent grants are comma-separated stable principal IDs. Administrator-authorized mode requires controlled transport, source-only continuation and exact per-operation approval; omit --principals. This never changes publication policy.\n\nExample:\n  andeo source merge-policy set --mode agent --principals principal_example --expected-revision 0 --idempotency-key merge-policy-v1 --json",
         "source change create": "Usage: andeo source change create --head BRANCH --title TITLE [--description TEXT] [--base BRANCH] [--json]\n\nOpen a review for the exact protected-base and feature-branch SHAs. Andeo binds checks and approval to this immutable snapshot.",
         "source change list": "Usage: andeo source change list [--state open|closed|all] [--json]\n\nList reviewed source changes for this exact linked project.",
         "source change show": "Usage: andeo source change show --change scr_... [--json]\n\nRead exact snapshot, preview, decision, and landing state.",
@@ -2831,7 +2991,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",