@skrr-ai/cli 0.1.93 → 0.1.95

package/dist/commands/daemon/install.js

@@ -84,6 +84,10 @@ class DaemonInstall extends core_1.Command {
             // is how a CLI and its daemon end up on different deployments
             // (OSK-279) without anyone doing anything wrong.
             const code = await (0, exec_runtime_binary_1.execRuntimeBinary)(['install', ...(0, daemon_binding_1.bindToCliSession)(argv)]);
+            if (code === 0 &&
+                !argv.some((arg) => ['--json', '--help', '-h'].includes(arg))) {
+                this.log('Coding-agent instructions: sign in with `skrr login`, or review installation choices with `skrr instructions setup`.');
+            }
             this.exit(code);
         }
         catch (err) {

package/dist/commands/generate-recovery-code.d.ts

@@ -6,7 +6,9 @@ import { BaseCommand } from '../base-command';
  * POST /api/auth/recovery/generate. The formatted code is printed
  * exactly once to STDOUT; a warning goes to STDERR.
  *
- * Requires an interactive user session (NOT a CI token).
+ * Requires a user sign-in session (NOT a CI token or PAT). When the server
+ * requests a fresh proof, this command verifies it for recovery_code_generate
+ * on the same session before retrying the generation exactly once.
  * On success: any previously-active recovery code is revoked server-side
  * and the new one is returned.
  *
@@ -19,6 +21,16 @@ export default class GenerateRecoveryCode extends BaseCommand {
     static examples: string[];
     static flags: {
         json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        otp: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'backup-code': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'email-code': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
     };
     run(): Promise<void>;
+    private generate;
+    private proofFor;
+    private nonemptyCode;
+    private refuseUnavailableMethod;
+    private refusePasskeyOnly;
+    private refuseStepUp;
+    private handleGenerationError;
 }

package/dist/commands/generate-recovery-code.js

@@ -1,8 +1,16 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 const core_1 = require("@oclif/core");
+const data_provider_1 = require("@skrr-ai/data-provider");
 const base_command_1 = require("../base-command");
 const api_fetch_1 = require("../lib/api-fetch");
+const prompt_1 = require("../lib/prompt");
+// Include passkey even though this terminal cannot run a WebAuthn ceremony.
+// The server uses this header when choosing the account's strongest proof:
+// omitting passkey would make a passkey-only account fall back to email.
+// A passkey-only challenge is refused below with a first-party web handoff.
+const STEP_UP_HEADERS = { 'X-Step-Up-Methods': 'passkey,totp,backup_code,email_code' };
+const PURPOSE = data_provider_1.RECOVERY_CODE_GENERATE_STEP_UP_PURPOSE;
 /**
  * `skrr generate-recovery-code`
  *
@@ -10,7 +18,9 @@ const api_fetch_1 = require("../lib/api-fetch");
  * POST /api/auth/recovery/generate. The formatted code is printed
  * exactly once to STDOUT; a warning goes to STDERR.
  *
- * Requires an interactive user session (NOT a CI token).
+ * Requires a user sign-in session (NOT a CI token or PAT). When the server
+ * requests a fresh proof, this command verifies it for recovery_code_generate
+ * on the same session before retrying the generation exactly once.
  * On success: any previously-active recovery code is revoked server-side
  * and the new one is returned.
  *
@@ -22,6 +32,8 @@ class GenerateRecoveryCode extends base_command_1.BaseCommand {
     static description = 'Generate a printable account-recovery code. Shown once — store it safely. Recovery codes use letters A-Z and digits 2-7.';
     static examples = [
         '<%= config.bin %> generate-recovery-code',
+        '<%= config.bin %> generate-recovery-code --otp 123456',
+        '<%= config.bin %> generate-recovery-code --backup-code <unused-code>',
         '<%= config.bin %> generate-recovery-code --json',
     ];
     static flags = {
@@ -29,28 +41,60 @@ class GenerateRecoveryCode extends base_command_1.BaseCommand {
             description: 'Output as JSON (for scripting). Code still printed only once.',
             default: false,
         }),
+        otp: core_1.Flags.string({
+            description: 'Current code from your authenticator app when a fresh proof is required',
+            exclusive: ['backup-code', 'email-code'],
+        }),
+        'backup-code': core_1.Flags.string({
+            description: 'Unused two-factor backup code when a fresh proof is required (it is spent)',
+            exclusive: ['otp', 'email-code'],
+        }),
+        'email-code': core_1.Flags.string({
+            description: 'Previously requested one-time email code when a fresh proof is required',
+            exclusive: ['otp', 'backup-code'],
+        }),
     };
     async run() {
         this.requireAuth();
         const { flags } = await this.parse(GenerateRecoveryCode);
-        // Guard: CI tokens cannot generate recovery codes (server also enforces this).
-        if (this.resolvedCredential.kind === 'ci') {
-            this.error('CI tokens cannot generate recovery codes. Run this command from an interactive session (`skrr login`).', { exit: 2 });
+        // Static credentials cannot mint account recovery credentials.
+        if (this.resolvedCredential.kind === 'ci' || this.resolvedCredential.kind === 'pat') {
+            this.error('CI and personal access tokens cannot generate recovery codes. Sign in with `skrr login` first.', { exit: 2 });
         }
         let result;
         try {
-            result = await (0, api_fetch_1.apiFetch)('/api/auth/recovery/generate', {
-                method: 'POST',
-                credential: this.resolvedCredential,
-            });
+            result = await this.generate();
         }
         catch (err) {
-            if (err instanceof api_fetch_1.ApiFetchError) {
-                if (err.status === 401 || err.status === 403) {
-                    this.error('Not authorized to generate a recovery code. Ensure you are signed in with a user-scope session.', { exit: 1 });
-                }
+            const challenge = err instanceof api_fetch_1.ApiFetchError && err.status === 403 ? (0, data_provider_1.stepUpChallengeFromError)(err) : null;
+            if (!challenge)
+                this.handleGenerationError(err);
+            if (challenge.purpose !== PURPOSE) {
+                this.error('The server asked for verification of a different action. Nothing changed.', {
+                    code: 'STEP_UP_PURPOSE_MISMATCH',
+                    exit: 2,
+                });
+            }
+            if (challenge.reason !== 'no_recent_step_up')
+                this.refuseStepUp(challenge);
+            const proof = await this.proofFor(challenge, flags);
+            try {
+                await (0, api_fetch_1.apiFetch)('/api/auth/step-up', {
+                    method: 'POST',
+                    credential: this.resolvedCredential,
+                    headers: STEP_UP_HEADERS,
+                    body: { purpose: PURPOSE, ...proof },
+                });
+            }
+            catch (verifyError) {
+                this.handleApiError(verifyError);
+            }
+            try {
+                result = await this.generate();
+            }
+            catch (retryError) {
+                this.handleGenerationError(retryError);
             }
-            this.handleApiError(err);
         }
         if (flags.json) {
             // JSON mode: print structured output to stdout for scripting.
@@ -75,5 +119,94 @@ class GenerateRecoveryCode extends base_command_1.BaseCommand {
         process.stderr.write(`  Generated at: ${new Date(result.createdAt).toISOString()}\n`);
         process.stderr.write('\n');
     }
+    generate() {
+        return (0, api_fetch_1.apiFetch)('/api/auth/recovery/generate', {
+            method: 'POST',
+            credential: this.resolvedCredential,
+            headers: STEP_UP_HEADERS,
+        });
+    }
+    async proofFor(challenge, flags) {
+        if (challenge.methods.includes('passkey') &&
+            !challenge.methods.includes('totp') &&
+            !challenge.methods.includes('backup_code')) {
+            this.refusePasskeyOnly();
+        }
+        if (flags.otp !== undefined) {
+            if (!challenge.methods.includes('totp'))
+                this.refuseUnavailableMethod();
+            return { token: this.nonemptyCode(flags.otp) };
+        }
+        if (flags['backup-code'] !== undefined) {
+            if (!challenge.methods.includes('backup_code'))
+                this.refuseUnavailableMethod();
+            return { backupCode: this.nonemptyCode(flags['backup-code']) };
+        }
+        if (flags['email-code'] !== undefined) {
+            if (!challenge.methods.includes('email_code'))
+                this.refuseUnavailableMethod();
+            return { emailCode: this.nonemptyCode(flags['email-code']) };
+        }
+        if (!process.stdin.isTTY) {
+            this.error('A fresh identity check is required. Run this command at a terminal, or pass --otp, --backup-code, or a previously requested --email-code. Nothing changed.', { code: 'STEP_UP_PROOF_REQUIRED', exit: 2 });
+        }
+        if (challenge.methods.includes('totp')) {
+            const entered = await (0, prompt_1.prompt)('Authenticator code: ', {
+                hidden: true,
+                output: process.stderr,
+            });
+            return { token: this.nonemptyCode(entered) };
+        }
+        if (challenge.methods.includes('backup_code')) {
+            const entered = await (0, prompt_1.prompt)('Unused two-factor backup code: ', {
+                hidden: true,
+                output: process.stderr,
+            });
+            return { backupCode: this.nonemptyCode(entered) };
+        }
+        if (challenge.methods.includes('email_code')) {
+            try {
+                await (0, api_fetch_1.apiFetch)('/api/auth/step-up/email-code', {
+                    method: 'POST',
+                    credential: this.resolvedCredential,
+                    headers: STEP_UP_HEADERS,
+                    body: { purpose: PURPOSE },
+                });
+            }
+            catch (requestError) {
+                this.handleApiError(requestError);
+            }
+            process.stderr.write('A one-time code was sent to your account email.\n');
+            const entered = await (0, prompt_1.prompt)('Email code: ', { hidden: true, output: process.stderr });
+            return { emailCode: this.nonemptyCode(entered) };
+        }
+        this.refuseUnavailableMethod();
+    }
+    nonemptyCode(value) {
+        const code = value.trim();
+        if (!code)
+            this.error('A verification code cannot be empty. Nothing changed.', { exit: 2 });
+        return code;
+    }
+    refuseUnavailableMethod() {
+        this.error('This login has no identity-check method the CLI can complete. Use Settings → Account in the web app, or enroll an authenticator and try again. Nothing changed.', { code: 'STEP_UP_METHOD_UNAVAILABLE', exit: 2 });
+    }
+    refusePasskeyOnly() {
+        this.error('This account requires a passkey for this identity check. Open Settings → Account in the web app to generate a recovery code. Nothing changed.', { code: 'STEP_UP_PASSKEY_REQUIRED', exit: 2 });
+    }
+    refuseStepUp(challenge) {
+        if (challenge.reason === 'credential_not_session_bound') {
+            this.error('This credential has no sign-in session for an identity check. Run `skrr login` and try again. Nothing changed.', { code: 'STEP_UP_SESSION_UNBOUND', exit: 2 });
+        }
+        this.refuseUnavailableMethod();
+    }
+    handleGenerationError(err) {
+        if (err instanceof api_fetch_1.ApiFetchError && (err.status === 401 || err.status === 403)) {
+            this.error('Not authorized to generate a recovery code. Sign in with a user-scope session.', {
+                exit: 1,
+            });
+        }
+        this.handleApiError(err);
+    }
 }
 exports.default = GenerateRecoveryCode;

package/dist/commands/instructions/guide.d.ts

@@ -0,0 +1,20 @@
+import { Command } from '@oclif/core';
+export default class InstructionsGuide extends Command {
+    static baseFlags: {
+        bare: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        token: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        workspace: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        profile: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        raw: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    };
+    static description: string;
+    static args: {
+        name: import("@oclif/core/lib/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        offline: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    };
+    static examples: string[];
+    run(): Promise<void>;
+}

package/dist/commands/instructions/guide.js

@@ -0,0 +1,84 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const node_crypto_1 = require("node:crypto");
+const base_command_1 = require("../../base-command");
+const managed_instruction_guides_json_1 = __importDefault(require("../../generated/managed-instruction-guides.json"));
+const api_fetch_1 = require("../../lib/api-fetch");
+const auth_core_init_1 = require("../../lib/auth-core-init");
+const credential_resolver_1 = require("../../lib/credential-resolver");
+const harness_context_1 = require("../../lib/harness-context");
+const keychain_1 = require("../../lib/keychain");
+// Documentation stays available when a daemon-issued Agent credential is
+// unavailable. Do not run BaseCommand's mandatory credential initialization.
+class InstructionsGuide extends core_1.Command {
+    static baseFlags = base_command_1.BaseCommand.baseFlags;
+    static description = 'Read the detailed task-management guide on demand';
+    static args = {
+        name: core_1.Args.string({
+            description: 'Guide to read',
+            options: ['task-management'],
+            default: 'task-management',
+            ignoreStdin: true,
+        }),
+    };
+    static flags = {
+        json: core_1.Flags.boolean({ description: 'Output the guide and source provenance as JSON' }),
+        offline: core_1.Flags.boolean({
+            description: 'Read the bundled release guide without checking credentials or the server',
+        }),
+    };
+    static examples = [
+        '<%= config.bin %> instructions guide task-management',
+        '<%= config.bin %> instructions guide --json',
+    ];
+    async run() {
+        const { flags } = await this.parse(InstructionsGuide);
+        let guide = managed_instruction_guides_json_1.default['oversky-task-management'];
+        let source = 'bundled';
+        let reason = flags.offline ? 'offline-requested' : 'no-session';
+        if (!flags.offline) {
+            try {
+                (0, keychain_1.setActiveProfile)(flags.profile ?? process.env.OVERSKY_PROFILE ?? '');
+                const autonomous = (0, credential_resolver_1.resolveTrustedAutonomousCredential)();
+                if (!autonomous && !flags.bare && !(0, harness_context_1.isHarnessCliContext)())
+                    await (0, auth_core_init_1.prefetchCliAuth)();
+                const credential = autonomous ??
+                    (await (0, credential_resolver_1.resolveCredential)({
+                        flagToken: flags.token,
+                        bareMode: flags.bare,
+                        allowUnreadableStoredCredential: true,
+                    }));
+                if (credential.token) {
+                    reason = 'server-unavailable';
+                    const response = await (0, api_fetch_1.apiFetch)('/api/instructions/presets/oversky-task-management/guide', { credential, signal: AbortSignal.timeout(3_000) });
+                    if ((0, node_crypto_1.createHash)('sha256').update(response.body).digest('hex') !== response.hash) {
+                        throw new Error('The server guide hash does not match its body.');
+                    }
+                    guide = response;
+                    source = 'server';
+                    reason = undefined;
+                }
+            }
+            catch {
+                // A missing/unreadable auth envelope or delegated daemon cannot make
+                // a read-only local guide unavailable, and must never emit auth JSON.
+                reason ??= 'server-unavailable';
+            }
+        }
+        if (flags.json)
+            this.log(JSON.stringify({
+                ...guide,
+                provenance: { source, fallback: source === 'bundled', ...(reason ? { reason } : {}) },
+            }, null, 2));
+        else {
+            if (source === 'bundled')
+                this.logToStderr(`Using the CLI’s bundled task-management guide (template v${guide.templateVersion}).`);
+            this.log(guide.body);
+        }
+    }
+}
+exports.default = InstructionsGuide;

package/dist/commands/instructions/install.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.conflictingTargetOf = conflictingTargetOf;
 exports.describeTargetConflict = describeTargetConflict;
 const core_1 = require("@oclif/core");
+const node_crypto_1 = require("node:crypto");
 const auth_core_1 = require("@skrr-ai/auth-core");
 const data_provider_1 = require("@skrr-ai/data-provider");
 const base_command_1 = require("../../base-command");
@@ -107,41 +108,67 @@ class InstructionsInstall extends base_command_1.BaseCommand {
                 exit: 2,
             });
         }
-        let previewBody;
+        const daemonId = await this.resolveDaemon(flags.daemon);
+        const inputs = providers.map((provider) => ({
+            daemonId,
+            bundleId: flags.bundle,
+            provider,
+            scope,
+            mode: flags.mode,
+            projectPath: flags.project,
+            trackingMode: flags.pin ? 'pinned' : 'latest',
+            pinnedVersionId: flags.pin,
+            label: flags.label,
+        }));
+        // Inspect the selected machine before any consent or target write. This is
+        // also required for --yes: unattended consent does not waive readability.
+        let preparedTargets;
         try {
-            const bundle = (await data_provider_1.dataService.getManagedInstructionBundle(flags.bundle)).bundle;
-            if (flags.pin) {
-                const versions = await data_provider_1.dataService.listManagedInstructionVersions(flags.bundle, true);
-                const pinned = versions.versions.find((version) => version.id === flags.pin);
-                if (!pinned || pinned.archivedAt) {
-                    this.error('The requested pinned version is missing or archived', { exit: 2 });
-                }
-                previewBody = pinned.body;
-            }
-            else {
-                if (!bundle.currentVersion)
-                    this.error('The prompt has no current version', { exit: 2 });
-                previewBody = bundle.currentVersion.body;
-            }
+            preparedTargets = await Promise.all(inputs.map((input) => data_provider_1.dataService.prepareManagedInstructionTarget(input)));
         }
         catch (error) {
             this.handleApiError(error);
         }
-        if (providers.includes('codex') && Buffer.byteLength(previewBody, 'utf8') > 30 * 1024) {
-            this.error('Codex managed instruction bodies are limited to 30 KiB; no targets were created', { exit: 2 });
+        for (let index = 0; index < preparedTargets.length; index += 1) {
+            const entry = preparedTargets[index];
+            const provider = providers[index];
+            const placement = entry.providers.find((candidate) => candidate.provider === provider);
+            const preview = entry.previews.find((candidate) => candidate.provider === provider);
+            if (entry.daemonId !== daemonId || entry.readiness !== 'ready') {
+                this.error(entry.message ||
+                    'The selected daemon cannot inspect its instruction files. Update or reconnect it and retry; no targets were created.', { exit: 1 });
+            }
+            if (!placement?.canInstall ||
+                !placement.instructionPath ||
+                placement.loadingStatus === 'shadowed') {
+                this.error(`${(0, harness_provider_input_1.canonicalHarnessInput)(provider)} cannot use this placement: ${placement?.issues.map((issue) => issue.message).join(' ') || placement?.loadingStatus || 'preflight unavailable'}. No targets were created.`, { exit: 1 });
+            }
+            if (!preview || (0, node_crypto_1.createHash)('sha256').update(preview.body).digest('hex') !== preview.hash) {
+                this.error('The instruction preview could not be verified; no targets were created.', {
+                    exit: 1,
+                });
+            }
+            if (!flags.json) {
+                this.log(`${(0, harness_provider_input_1.canonicalHarnessInput)(provider)} on ${daemonId}: ${placement.instructionPath} (${placement.loadingStatus})`);
+                for (const issue of placement.issues)
+                    this.log(`  ${issue.severity}: ${issue.message}`);
+            }
         }
         // The body is shown so the confirmation below is informed. With `--yes`
         // there is no confirmation to inform, and printing a ~9 KB body anyway put
         // the command's actual outcome — often a refusal — a screen of scrollback
         // away (OSK-4631). Say what was authorized, and where to read it.
         if (!flags.json && !flags.yes) {
-            this.log('Exact managed instruction body:');
-            this.log('---');
-            this.log(previewBody);
-            this.log('---');
+            for (let index = 0; index < providers.length; index += 1) {
+                const preview = preparedTargets[index].previews.find((entry) => entry.provider === providers[index]);
+                this.log(`Exact ${(0, harness_provider_input_1.canonicalHarnessInput)(providers[index])} managed instruction body (SHA-256 ${preview.hash}):`);
+                this.log('---');
+                this.log(preview.body);
+                this.log('---');
+            }
         }
         else if (!flags.json) {
-            this.log(`Authorizing ${Buffer.byteLength(previewBody, 'utf8').toLocaleString()} bytes of instruction ` +
+            this.log(`Authorizing ${Buffer.byteLength(preparedTargets[0].version.body, 'utf8').toLocaleString()} bytes of instruction ` +
                 `${flags.bundle}; \`${this.config.bin} instructions show ${flags.bundle}\` prints them.`);
         }
         const teamWarning = scope === 'project' && flags.mode === 'team'
@@ -150,20 +177,17 @@ class InstructionsInstall extends base_command_1.BaseCommand {
         const confirmed = await (0, prompt_1.confirmDestructive)(`Authorize continuous ${providers.join(', ')} reconciliation on this target?${teamWarning}`, flags.yes);
         if (!confirmed)
             return this.log('Aborted.');
-        const daemonId = await this.resolveDaemon(flags.daemon);
         const results = [];
-        for (const provider of providers) {
+        for (let index = 0; index < providers.length; index += 1) {
+            const provider = providers[index];
+            const entry = preparedTargets[index];
             try {
                 results.push(await data_provider_1.dataService.createManagedInstructionTarget({
-                    daemonId,
-                    bundleId: flags.bundle,
-                    provider,
-                    scope,
-                    mode: flags.mode,
-                    projectPath: flags.project,
-                    trackingMode: flags.pin ? 'pinned' : 'latest',
-                    pinnedVersionId: flags.pin,
-                    label: flags.label,
+                    ...inputs[index],
+                    expectedHash: entry.version.hash,
+                    expectedVersionId: entry.version.id,
+                    expectedRenderedHash: entry.previews.find((preview) => preview.provider === provider)
+                        .hash,
                 }));
             }
             catch (error) {

package/dist/commands/instructions/setup.d.ts

@@ -0,0 +1,14 @@
+import { BaseCommand } from '../../base-command';
+export default class InstructionsSetup extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        daemon: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        provider: import("@oclif/core/lib/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        'update-policy': import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
+        yes: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        review: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        json: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/instructions/setup.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@oclif/core");
+const auth_core_1 = require("@skrr-ai/auth-core");
+const base_command_1 = require("../../base-command");
+const harness_provider_input_1 = require("../../lib/harness-provider-input");
+const managed_instruction_setup_1 = require("../../lib/managed-instruction-setup");
+class InstructionsSetup extends base_command_1.BaseCommand {
+    static description = 'Review and install removable global instructions for coding agents on this machine.\n\n' +
+        'Verifies the local daemon’s account, server and profile, then asks that daemon to check ' +
+        'its real instruction files. Choose providers separately and choose automatic updates or ' +
+        'a fixed current version. Existing installation decisions are preserved. Pass --daemon ' +
+        'to explicitly choose another connected machine. No files are written by the CLI.';
+    static examples = [
+        '<%= config.bin %> instructions setup',
+        '<%= config.bin %> instructions setup --provider codex --review',
+        '<%= config.bin %> instructions setup --provider claude --update-policy pinned --yes --json',
+        '<%= config.bin %> instructions setup --daemon <id> --provider codex --update-policy latest --yes',
+    ];
+    static flags = {
+        daemon: core_1.Flags.string({
+            description: 'Explicit connected daemon ID; defaults only to a verified daemon on this computer',
+        }),
+        provider: core_1.Flags.string({
+            description: 'Provider to set up or revisit (repeatable); otherwise offers newly detected providers',
+            options: (0, harness_provider_input_1.harnessFlagOptions)(['claude', 'codex', auth_core_1.FIRST_PARTY_HARNESS.provider]),
+            multiple: true,
+        }),
+        'update-policy': core_1.Flags.string({
+            description: 'Track automatic updates, or pin today’s reviewed version',
+            options: ['latest', 'pinned'],
+        }),
+        yes: core_1.Flags.boolean({
+            char: 'y',
+            description: 'Authorize selected providers and update policy without prompting; requires --provider and --update-policy',
+        }),
+        review: core_1.Flags.boolean({
+            description: 'Show exact previews and daemon preflight without installing or changing decisions',
+        }),
+        json: core_1.Flags.boolean({ description: 'Output one JSON result; requires --review or --yes' }),
+    };
+    async run() {
+        this.requireAuth();
+        const { flags } = await this.parse(InstructionsSetup);
+        if (flags.json && !flags.review && !flags.yes)
+            this.error('--json requires --review or --yes', { exit: 2 });
+        if (flags.review && flags.yes)
+            this.error('--review cannot be combined with --yes', { exit: 2 });
+        try {
+            const result = await (0, managed_instruction_setup_1.runManagedInstructionSetup)({
+                trigger: 'manual',
+                log: flags.json ? () => { } : (message) => this.log(message),
+                daemonId: flags.daemon,
+                providers: flags.provider
+                    ? (0, harness_provider_input_1.canonicalHarnessInputs)(flags.provider)
+                    : undefined,
+                trackingMode: flags['update-policy'],
+                yes: flags.yes,
+                review: flags.review,
+                json: flags.json,
+            });
+            if (flags.json)
+                this.log(JSON.stringify(result, null, 2));
+            if (result.status === 'unavailable')
+                this.exit(1);
+        }
+        catch (error) {
+            this.handleApiError(error);
+        }
+    }
+}
+exports.default = InstructionsSetup;

package/dist/commands/integrations/execute.js

@@ -33,7 +33,7 @@ class IntegrationsExecute extends base_command_1.BaseCommand {
             description: 'Agent ID (falls back to OVERSKY_AGENT_ID, then primary agent)',
         }),
         'request-id': core_1.Flags.string({
-            description: 'Idempotency key — reuse to safely retry side-effecting tools (auto-generated if omitted)',
+            description: 'Reuse only for the same tool, arguments and connection. A pending or unknown outcome requires reconciliation before another write (auto-generated if omitted)',
         }),
         json: core_1.Flags.boolean({
             description: 'Output full response as JSON (recommended for daemon use)',

package/dist/commands/login.d.ts

@@ -12,14 +12,13 @@ import { BaseCommand } from '../base-command';
  * Refresh, rotation, family revoke, and the cross-process auth.lock are
  * all the same substrate the daemon uses (@skrr-ai/auth-core).
  *
- * CI. There is no long-lived token that `skrr` commands accept yet (OSK-13208).
- * `skrr create-token` mints an `osk_ci_*` token, and that token only
- * bootstraps a DAEMON (`OVERSKY_TOKEN=osk_ci_... skrrd start`): every `skrr`
- * command rejects it with 401 (see create-token.ts and base-command.ts). What
- * works today is a session minted for the machine with
+ * CI. `skrr tokens create` mints an expiring, revocable personal access token
+ * (`osk_pat_*`) for SKRR_TOKEN. It does not rotate and is distinct from a
+ * per-machine SESSION minted with
  * `skrr token mint --for <id>`, restored by the `OVERSKY_REFRESH_TOKEN` path
  * below — whose refresh token rotates on use — or `OVERSKY_AUTH_HELPER`.
- * docs/cli/SKRR_AUTH.md ("CI today") states the caveats.
+ * docs/cli/SKRR_AUTH.md states credential precedence and revocation scopes.
+ * Legacy `skrr create-token` credentials only bootstrap a daemon.
  *
  * L13 — non-interactive restore from a refresh token. When
  * `OVERSKY_REFRESH_TOKEN` is set in the environment, the browser /