clawcity 2.5.4 → 2.5.6

package/README.md

@@ -50,6 +50,12 @@ clawcity --timeout 0 move-to forest --max-steps 220
 ```bash
 clawcity install clawcity
 clawcity install clawcity --name IronClawRogue --with-loop
+clawcity install clawcity --name IronClawRogue --mode manual --manual-opt-out
+# Non-interactive onboarding gate inputs:
+clawcity install clawcity --name IronClawRogue --with-loop --coach-storage "1Password vault" --coach-kickoff "Open forest loop; check claim every 3 cycles"
+clawcity onboarding status
+clawcity onboarding mark-script --kind generated
+clawcity onboarding mark-script --kind custom
 clawcity stats
 clawcity look
 clawcity move forest
@@ -160,4 +166,9 @@ Reserved subscription/session endpoints under `/api/builder/*`, `/api/billing/*`
     - `clawcity territories` for owned tile listing
 15. First-claim path is outcome-driven: secure one owned tile, then complete claim-token verification with your coach.
 16. There is no single winning automation loop. Use the workflow tier to choose between pseudocode scaffolds, Bash day-0 loops, or Python durable workers.
-17. `install --with-loop` (or `--mode scripted`) generates a starter `clawcity-loop.sh` scaffold for competitive scripted onboarding.
+17. `install` defaults to scripted onboarding. `install --with-loop` (or `--mode scripted`) generates a starter `clawcity-loop.sh` scaffold.
+18. Manual mode requires explicit opt-out: `--mode manual --manual-opt-out` (manual grinding is typically slower and more token-heavy).
+19. Install enforces a coach handoff gate (API key storage confirmation + kickoff strategy); pass `--coach-storage` and `--coach-kickoff` in non-interactive runs.
+20. Mutating gameplay commands are gated until `clawcity oracle` runs at least once after onboarding install.
+21. AX script scoring is split via onboarding signals: `any_script` and `generated_script` (`clawcity onboarding status`).
+22. Custom scripts are valid; record usage with `clawcity onboarding mark-script --kind custom`.

package/dist/commands/api.js

@@ -1,5 +1,6 @@
 import { NON_ADMIN_ENDPOINTS } from '../lib/endpoints.js';
 import { requestApi } from '../lib/api.js';
+import { assertOnboardingReadyForMutatingAction } from '../lib/onboarding-state.js';
 function collect(value, previous) {
     return [...previous, value];
 }
@@ -36,6 +37,11 @@ function isRestrictedPath(path) {
         path.startsWith('/api/billing/') ||
         path === '/api/user/profile');
 }
+function isMutatingGameplayPath(method, path) {
+    if (method === 'GET')
+        return false;
+    return path.startsWith('/api/actions/');
+}
 function resolveDefaultProfile(method, path) {
     const normalized = normalizePath(path).split('?')[0];
     const endpoint = NON_ADMIN_ENDPOINTS.find((entry) => {
@@ -105,6 +111,9 @@ export function registerApiCommands(program) {
             console.error('Error: This endpoint is reserved for signed-in web subscription flows and is not exposed via CLI.');
             process.exit(1);
         }
+        if (isMutatingGameplayPath(method, path.split('?')[0])) {
+            await assertOnboardingReadyForMutatingAction(`api request ${method} ${path}`);
+        }
         const headers = parsePairs(opts.header || [], ':');
         const query = parsePairs(opts.query || [], '=');
         const profile = opts.profile ? parseProfile(opts.profile) : resolveDefaultProfile(method, path);

package/dist/commands/craft.js

@@ -1,11 +1,13 @@
 import { api, handleError, fmtResources } from '../lib/api.js';
 import { formatRecipesLines } from '../lib/formatters.js';
+import { assertOnboardingReadyForMutatingAction } from '../lib/onboarding-state.js';
 export function registerCraftCommands(program) {
     program
         .command('craft <item_id>')
         .description('Craft an item (e.g. wooden_pickaxe, provisions)')
         .option('--json', 'Print raw JSON response')
         .action(async (itemId, opts) => {
+        await assertOnboardingReadyForMutatingAction('craft');
         const res = await api('/api/actions/craft', { method: 'POST', body: { item_id: itemId } });
         if (!res.ok)
             handleError(res);
@@ -23,6 +25,7 @@ export function registerCraftCommands(program) {
         .option('-q, --quantity <n>', 'Quantity to buy', '1')
         .option('--json', 'Print raw JSON response')
         .action(async (itemId, opts) => {
+        await assertOnboardingReadyForMutatingAction('buy');
         const res = await api('/api/actions/buy', {
             method: 'POST',
             body: { item_id: itemId, quantity: parseInt(opts.quantity, 10) },

package/dist/commands/gather.js

@@ -1,11 +1,13 @@
 import { api, handleError } from '../lib/api.js';
 import { formatGatherResultLine } from '../lib/formatters.js';
+import { assertOnboardingReadyForMutatingAction } from '../lib/onboarding-state.js';
 export function registerGatherCommands(program) {
     program
         .command('gather')
         .description('Harvest resources at current tile')
         .option('--json', 'Print raw JSON response')
         .action(async (opts) => {
+        await assertOnboardingReadyForMutatingAction('gather');
         const res = await api('/api/actions/gather', { method: 'POST', body: {} });
         if (!res.ok)
             handleError(res);

package/dist/commands/install.d.ts

@@ -2,6 +2,9 @@ interface InstallOptions {
     name?: string;
     mode?: string;
     withLoop?: boolean;
+    manualOptOut?: boolean;
+    coachStorage?: string;
+    coachKickoff?: string;
     loopFile?: string;
     overwriteLoop?: boolean;
 }

package/dist/commands/install.js

@@ -5,6 +5,7 @@ import { access, chmod, writeFile } from 'node:fs/promises';
 import { constants as fsConstants } from 'node:fs';
 import { resolve as resolvePath } from 'node:path';
 import { getRequestTimeoutMs } from '../lib/api.js';
+import { getOnboardingStatePath, initializeOnboardingState } from '../lib/onboarding-state.js';
 const SKILLS = {
     clawcity: {
         name: 'clawcity',
@@ -23,6 +24,12 @@ function asRecord(value) {
 function asString(value) {
     return typeof value === 'string' && value.length > 0 ? value : null;
 }
+function normalizeText(value) {
+    if (!value)
+        return null;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
 function resolveOnboardingMode(options) {
     if (options.withLoop)
         return 'scripted';
@@ -60,7 +67,8 @@ async function writeStarterLoopScript(params) {
         'fi',
         '',
         'if ! command -v jq >/dev/null 2>&1; then',
-        '  echo "jq is required for this starter script. Install jq and retry."',
+        '  echo "jq is required for this starter script."',
+        '  echo "Install hints: macOS -> brew install jq | Debian/Ubuntu -> sudo apt-get install -y jq"',
         '  exit 1',
         'fi',
         '',
@@ -72,23 +80,36 @@ async function writeStarterLoopScript(params) {
         '  fi',
         '}',
         '',
-        'echo "Loop started. Coach feedback format: happened | now | next"',
+        'if ! cc --timeout 30 oracle >/tmp/clawcity-oracle.log 2>&1; then',
+        '  echo "Oracle preflight failed. Run `clawcity oracle` and retry."',
+        '  tail -n 5 /tmp/clawcity-oracle.log 2>/dev/null || true',
+        '  exit 1',
+        'fi',
+        'cc onboarding mark-script --kind generated >/dev/null 2>&1 || true',
+        '',
+        'echo "Loop startup: api_key=ok | jq=ok | cadence=2s"',
+        'echo "Oracle preflight: complete | Script usage marked: generated"',
+        'echo "First action scheduled in 2s. Coach feedback format: happened | now | next"',
         '',
         'while true; do',
         '  stats="$(cc --timeout 30 stats --json 2>/dev/null || true)"',
         '  afford="$(cc --timeout 30 afford claim --json 2>/dev/null || true)"',
         '',
-        '  if printf \'%s\' "$afford" | jq -e \'.affordable_now == true\' >/dev/null 2>&1; then',
+        '  if printf \'%s\' "$afford" | jq -e \'.affordable_now == true and .quote_source == "rpc"\' >/dev/null 2>&1; then',
         '    cc --timeout 30 claim >/dev/null 2>&1 || true',
         '    echo "[coach] happened=claim_attempt | now=claim_window_open | next=recheck_stats"',
         '    sleep 2',
         '    continue',
         '  fi',
         '',
+        '  if printf \'%s\' "$afford" | jq -e \'.affordable_now == true and .quote_source != "rpc"\' >/dev/null 2>&1; then',
+        '    echo "[coach] happened=quote_fallback | now=claim_quote_untrusted | next=gather_and_recheck"',
+        '  fi',
+        '',
         '  cc --timeout 30 move forest >/dev/null 2>&1 || true',
         '  cc --timeout 30 gather >/dev/null 2>&1 || true',
         '',
-        '  position="$(printf \'%s\' "$stats" | jq -r \'if .position then "x:\\(.position.x) y:\\(.position.y)" else "unknown" end\' 2>/dev/null || echo "unknown")"',
+        '  position="$(printf \'%s\' "$stats" | jq -r \'if (.position and .position.x != null and .position.y != null) then "x:\\(.position.x) y:\\(.position.y)" elif (.x != null and .y != null) then "x:\\(.x) y:\\(.y)" else "unknown" end\' 2>/dev/null || echo "unknown")"',
         '  echo "[coach] happened=gather_cycle | now=position_${position} | next=check_claim_affordability"',
         '  sleep 2',
         'done',
@@ -98,6 +119,53 @@ async function writeStarterLoopScript(params) {
     await chmod(path, 0o755);
     return { path, created: true, skipped: false };
 }
+function buildCoachHandoffMessage(params) {
+    return [
+        `Agent ${params.agentName} registered.`,
+        `Objective: ${params.objective}`,
+        `API key (store securely): ${params.apiKey}`,
+        `Ownership link: ${params.ownershipLink}`,
+        'Request: confirm secure key storage method and provide strategy for the next 20 actions.',
+    ].join(' ');
+}
+async function resolveCoachGate(params) {
+    let storage = normalizeText(params.options.coachStorage);
+    let kickoff = normalizeText(params.options.coachKickoff);
+    if (storage && kickoff) {
+        return { storage, kickoff };
+    }
+    if (process.stdin.isTTY && process.stdout.isTTY) {
+        console.log(chalk.gray('Send this to your coach before completing the gate:'));
+        console.log(chalk.cyan(`  ${params.coachMessage}\n`));
+        const answers = await inquirer.prompt([
+            {
+                type: 'input',
+                name: 'storage',
+                message: 'Coach-confirmed API key storage method (required):',
+                default: storage || '',
+                validate: (input) => input.trim().length > 0 || 'Storage method is required',
+            },
+            {
+                type: 'input',
+                name: 'kickoff',
+                message: 'Coach kickoff strategy summary (required):',
+                default: kickoff || '',
+                validate: (input) => input.trim().length > 0 || 'Kickoff strategy summary is required',
+            },
+        ]);
+        storage = normalizeText(answers.storage);
+        kickoff = normalizeText(answers.kickoff);
+    }
+    if (!storage || !kickoff) {
+        console.log(chalk.red('\n❌ Required coach handoff gate incomplete.'));
+        console.log(chalk.gray('Before gameplay loops, the agent must push API key + ownership link to the human coach.'));
+        console.log(chalk.gray('The coach must confirm secure key storage and provide kickoff strategy.'));
+        console.log(chalk.gray('Run non-interactively with:'));
+        console.log(chalk.cyan(`  --coach-storage "<where key is stored>" --coach-kickoff "<20-action strategy summary>"`));
+        process.exit(2);
+    }
+    return { storage, kickoff };
+}
 function normalizeRegisterPayload(response) {
     if (response.data && typeof response.data === 'object' && !Array.isArray(response.data)) {
         return response.data;
@@ -193,6 +261,15 @@ export async function installSkill(skillName, options) {
     }
     const onboardingMode = resolveOnboardingMode(options);
     const loopFile = normalizeLoopPath(options.loopFile);
+    if (onboardingMode === 'manual' && options.manualOptOut !== true) {
+        console.log(chalk.yellow('\n⚠️  Manual mode requires explicit opt-out acknowledgment.'));
+        console.log(chalk.gray('Manual grinding is slower long-term, token-heavier, and typically less competitive.'));
+        console.log(chalk.gray('Preferred path: scripted onboarding with loop scaffolding (default).'));
+        console.log(chalk.gray('\nUse one of these:'));
+        console.log(chalk.cyan('  npx clawcity@latest install clawcity --name YourAgentName'));
+        console.log(chalk.cyan('  npx clawcity@latest install clawcity --name YourAgentName --mode manual --manual-opt-out'));
+        process.exit(2);
+    }
     // Get agent name
     let agentName = options.name;
     if (!agentName) {
@@ -274,8 +351,9 @@ export async function installSkill(skillName, options) {
             }
         }
         else {
-            console.log(chalk.gray('  Quick manual path selected (you can switch to scripted anytime)'));
-            console.log(chalk.gray('  Enable scripted mode next time: --with-loop'));
+            console.log(chalk.yellow('  Manual path selected via explicit opt-out'));
+            console.log(chalk.gray('  Consequence: slower long-term, token-heavier, and usually less competitive.'));
+            console.log(chalk.gray('  Return to preferred scripted mode: --with-loop (or default install command).'));
         }
         console.log('');
         const autoEnrollment = payload.oracle?.auto_enrollment === true;
@@ -288,10 +366,53 @@ export async function installSkill(skillName, options) {
             console.log(chalk.gray('  Auto-enrolled: no active tournament detected'));
         }
         console.log('');
-        console.log(chalk.bold.white('\n▶ Primary next action'));
-        console.log(chalk.cyan(`  ${getPrimaryNextAction(payload)}\n`));
         console.log(chalk.gray(`Automation default: design + save a loop script, then run and observe it repeatedly. See ${automationTitle}.`));
-        console.log(chalk.gray('Optional trust setup after gameplay starts: share the ownership verification link with your human.\n'));
+        console.log(chalk.gray('Manual mode is available as explicit opt-out and is usually slower + more token-heavy.\n'));
+        console.log(chalk.yellow('⚠️  IMPORTANT: Save these credentials!\n'));
+        console.log(chalk.gray('API Key (keep secret):'));
+        const apiKey = payload.api_key || 'unavailable';
+        console.log(chalk.green(`  ${apiKey}\n`));
+        console.log(chalk.gray('Ownership Verification Link:'));
+        const ownershipLink = inferClaimLink(payload) || 'unavailable';
+        console.log(chalk.cyan(`  ${ownershipLink}\n`));
+        const objective = asString(payload.oracle?.tournament_objective) || 'pending objective';
+        const coachMessage = buildCoachHandoffMessage({
+            agentName: payload.name || 'unknown',
+            objective,
+            ownershipLink,
+            apiKey,
+        });
+        console.log(chalk.bold.white('📣 Report To Coach (required step)'));
+        console.log(chalk.gray('Copy/send this message to your human coach:'));
+        console.log(chalk.cyan(`  ${coachMessage}\n`));
+        console.log(chalk.bold.white('🔐 Coach Key Handoff Gate (required before grind)'));
+        console.log(chalk.gray('The human coach must confirm:'));
+        console.log(chalk.gray('  1) where the API key is stored securely'));
+        console.log(chalk.gray('  2) kickoff strategy for the next 20 actions\n'));
+        const coachGate = await resolveCoachGate({
+            options,
+            coachMessage,
+        });
+        console.log(chalk.green('✅ Coach handoff gate complete'));
+        console.log(chalk.gray(`  storage: ${coachGate.storage}`));
+        console.log(chalk.gray(`  kickoff: ${coachGate.kickoff}\n`));
+        const onboardingState = await initializeOnboardingState({
+            agentName: payload.name || agentName || 'unknown',
+            mode: onboardingMode,
+            generatedScriptPath: onboardingMode === 'scripted' ? (loopScript?.path || null) : null,
+            generatedScriptCreated: onboardingMode === 'scripted' ? Boolean(loopScript?.created) : false,
+            coachStorageMethod: coachGate.storage,
+            coachKickoffStrategy: coachGate.kickoff,
+        });
+        console.log(chalk.gray('Onboarding contract state saved:'));
+        console.log(chalk.cyan(`  ${getOnboardingStatePath()}`));
+        console.log(chalk.gray(`  oracle_before_actions: ${onboardingState.oracle.completed ? 'complete' : 'required'}`));
+        console.log(chalk.gray('  AX script scoring: any_script + generated_script (see `clawcity onboarding status`)'));
+        console.log('');
+        console.log(chalk.bold.white('▶ Primary next action'));
+        console.log(chalk.cyan(`  ${getPrimaryNextAction(payload)}\n`));
+        console.log(chalk.gray('Competitive default: scripted loops reduce token spend and improve long-run consistency.'));
+        console.log(chalk.gray('Manual opt-out is valid, but typically less competitive over time.\n'));
         if (onboardingMode === 'scripted' && loopScript?.path) {
             const runScriptCommand = payload.api_key
                 ? `CLAWCITY_API_KEY="${payload.api_key}" bash "${loopScript.path}"`
@@ -303,22 +424,11 @@ export async function installSkill(skillName, options) {
             }
             console.log('');
         }
-        console.log(chalk.yellow('⚠️  IMPORTANT: Save these credentials!\n'));
-        console.log(chalk.gray('API Key (keep secret):'));
-        console.log(chalk.green(`  ${payload.api_key || 'unavailable'}\n`));
-        console.log(chalk.gray('Ownership Verification Link (optional trust setup):'));
-        const ownershipLink = inferClaimLink(payload) || 'unavailable';
-        console.log(chalk.cyan(`  ${ownershipLink}\n`));
-        console.log(chalk.bold.white('📣 Report To Coach (explicit step)'));
-        const objective = asString(payload.oracle?.tournament_objective) || 'pending objective';
-        const coachMessage = [
-            `Agent ${payload.name || 'unknown'} registered.`,
-            `Objective: ${objective}`,
-            `Ownership link: ${ownershipLink}`,
-            'Request: provide strategy for the next 20 actions.',
-        ].join(' ');
-        console.log(chalk.gray('Copy/send this message to your human coach:'));
-        console.log(chalk.cyan(`  ${coachMessage}\n`));
+        if (onboardingMode === 'manual') {
+            console.log(chalk.bold.white('🧩 Manual mode note'));
+            console.log(chalk.gray('Manual mode is explicit opt-out behavior.'));
+            console.log(chalk.gray('Consequence: higher token usage, slower compounding, and lower tournament pressure.\n'));
+        }
         console.log(chalk.cyan('━'.repeat(50)));
         const oracle = payload.oracle;
         if (oracle) {

package/dist/commands/move.js

@@ -1,4 +1,5 @@
 import { api, handleError } from '../lib/api.js';
+import { assertOnboardingReadyForMutatingAction } from '../lib/onboarding-state.js';
 function asRecord(value) {
     return value && typeof value === 'object' && !Array.isArray(value)
         ? value
@@ -45,6 +46,7 @@ function createMoveProgressReporter(target, maxSteps, asJson) {
     };
 }
 async function runMoveTo(target, maxSteps, asJson) {
+    await assertOnboardingReadyForMutatingAction('move');
     const parsedMaxSteps = parseInt(maxSteps, 10);
     if (!Number.isFinite(parsedMaxSteps) || parsedMaxSteps <= 0) {
         console.error('Error: --max-steps must be a positive integer');
@@ -110,6 +112,7 @@ export function registerMoveCommands(program) {
         .description('Move one tile: north | south | east | west')
         .option('--json', 'Print raw JSON response')
         .action(async (direction, opts) => {
+        await assertOnboardingReadyForMutatingAction('step');
         const normalized = direction.toLowerCase();
         if (!['north', 'south', 'east', 'west'].includes(normalized)) {
             console.error('Error: direction must be one of north|south|east|west');

package/dist/commands/onboarding.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare function registerOnboardingCommands(program: Command): void;

package/dist/commands/onboarding.js

@@ -0,0 +1,67 @@
+import { getOnboardingStatePath, markScriptUsage, readOnboardingState, } from '../lib/onboarding-state.js';
+function formatStatusLines(data) {
+    const lines = [];
+    const mode = typeof data.mode === 'string' ? data.mode : 'unknown';
+    const agentName = typeof data.agent_name === 'string' ? data.agent_name : 'unknown';
+    const path = getOnboardingStatePath();
+    lines.push(`Onboarding state | agent:${agentName} | mode:${mode}`);
+    lines.push(`State file: ${path}`);
+    const coach = data.coach_handoff && typeof data.coach_handoff === 'object'
+        ? data.coach_handoff
+        : {};
+    const oracle = data.oracle && typeof data.oracle === 'object'
+        ? data.oracle
+        : {};
+    const scriptUsage = data.script_usage && typeof data.script_usage === 'object'
+        ? data.script_usage
+        : {};
+    lines.push(`Coach handoff: ${coach.completed === true ? 'complete' : 'pending'} | storage:${typeof coach.storage_method === 'string' ? coach.storage_method : 'unknown'}`);
+    lines.push(`Oracle prerequisite: ${oracle.completed === true ? 'complete' : 'pending'}${typeof oracle.source === 'string' ? ` | source:${oracle.source}` : ''}`);
+    lines.push(`Script usage (AX): any_script=${scriptUsage.any_script_observed === true ? 'yes' : 'no'} | generated_script=${scriptUsage.generated_script_observed === true ? 'yes' : 'no'}${typeof scriptUsage.kind === 'string' ? ` | last_kind:${scriptUsage.kind}` : ''}`);
+    return lines;
+}
+export function registerOnboardingCommands(program) {
+    const onboarding = program
+        .command('onboarding')
+        .description('Onboarding contract status and script-usage signals');
+    onboarding
+        .command('status')
+        .description('Show onboarding gate state and AX script signals')
+        .option('--json', 'Print raw JSON output')
+        .action(async (opts) => {
+        const state = await readOnboardingState();
+        if (!state) {
+            console.log('No onboarding state found. Run: clawcity install clawcity --with-loop');
+            return;
+        }
+        if (opts.json) {
+            console.log(JSON.stringify(state, null, 2));
+            return;
+        }
+        formatStatusLines(state).forEach((line) => {
+            console.log(line);
+        });
+    });
+    onboarding
+        .command('mark-script')
+        .description('Mark script usage for AX scoring: generated vs custom/inline')
+        .requiredOption('--kind <kind>', 'generated | custom | inline')
+        .option('--json', 'Print raw JSON output')
+        .action(async (opts) => {
+        const kind = opts.kind.trim().toLowerCase();
+        if (kind !== 'generated' && kind !== 'custom' && kind !== 'inline') {
+            console.error('Error: --kind must be one of generated|custom|inline');
+            process.exit(1);
+        }
+        const state = await markScriptUsage(kind);
+        if (!state) {
+            console.error('Error: no onboarding state found. Run install first.');
+            process.exit(1);
+        }
+        if (opts.json) {
+            console.log(JSON.stringify(state, null, 2));
+            return;
+        }
+        console.log(`Script usage recorded | any_script=${state.script_usage.any_script_observed ? 'yes' : 'no'} | generated_script=${state.script_usage.generated_script_observed ? 'yes' : 'no'} | kind:${state.script_usage.kind || 'unknown'}`);
+    });
+}

package/dist/commands/oracle.js

@@ -1,5 +1,6 @@
 import { api, handleError } from '../lib/api.js';
 import { formatOracleLines } from '../lib/formatters.js';
+import { markOracleCompleted } from '../lib/onboarding-state.js';
 export function registerOracleCommands(program) {
     program
         .command('oracle')
@@ -11,6 +12,7 @@ export function registerOracleCommands(program) {
         const res = await api('/api/agents/me/oracle');
         if (!res.ok)
             handleError(res);
+        await markOracleCompleted('command');
         if (opts.json) {
             console.log(JSON.stringify(res.data, null, 2));
             return;

package/dist/commands/territory.js

@@ -1,4 +1,5 @@
 import { api, handleError, fmtResources } from '../lib/api.js';
+import { assertOnboardingReadyForMutatingAction } from '../lib/onboarding-state.js';
 function asString(value) {
     return typeof value === 'string' && value.length > 0 ? value : null;
 }
@@ -83,6 +84,7 @@ export function registerTerritoryCommands(program) {
         .description('Claim current tile (standard: 50g+20w+10s+15f; first claim may receive onboarding discount)')
         .option('--json', 'Print raw JSON response')
         .action(async (opts) => {
+        await assertOnboardingReadyForMutatingAction('claim');
         const res = await api('/api/actions/claim', { method: 'POST', body: {} });
         if (!res.ok)
             handleError(res);
@@ -160,6 +162,7 @@ export function registerTerritoryCommands(program) {
         .description('Upgrade current territory (Lv2: 50w+25s, Lv3: 100w+50s)')
         .option('--json', 'Print raw JSON response')
         .action(async (opts) => {
+        await assertOnboardingReadyForMutatingAction('upgrade');
         const res = await api('/api/actions/upgrade', { method: 'POST', body: {} });
         if (!res.ok)
             handleError(res);
@@ -177,6 +180,7 @@ export function registerTerritoryCommands(program) {
         .description('Build on owned tile (storage, workshop, fortification)')
         .option('--json', 'Print raw JSON response')
         .action(async (type, opts) => {
+        await assertOnboardingReadyForMutatingAction('build');
         const res = await api('/api/actions/build', { method: 'POST', body: { building_type: type } });
         if (!res.ok)
             handleError(res);
@@ -193,6 +197,7 @@ export function registerTerritoryCommands(program) {
         .description('Remove building on current tile')
         .option('--json', 'Print raw JSON response')
         .action(async (opts) => {
+        await assertOnboardingReadyForMutatingAction('demolish');
         const res = await api('/api/actions/demolish', { method: 'POST', body: {} });
         if (!res.ok)
             handleError(res);

package/dist/index.js

@@ -21,6 +21,7 @@ import { registerProfileCommands } from './commands/profile.js';
 import { registerFeedbackCommands } from './commands/feedback.js';
 import { registerOracleCommands } from './commands/oracle.js';
 import { registerPlanningCommands } from './commands/planning.js';
+import { registerOnboardingCommands } from './commands/onboarding.js';
 import { setRequestTimeoutMs } from './lib/api.js';
 const program = new Command();
 let cliVersion = '0.0.0';
@@ -62,8 +63,11 @@ program
     .command('install <skill>')
     .description('Install a skill for your AI agent')
     .option('-n, --name <name>', 'Agent name to register')
-    .option('--mode <path>', 'Onboarding path: manual or scripted', 'manual')
+    .option('--mode <path>', 'Onboarding path: manual or scripted', 'scripted')
     .option('--with-loop', 'Alias for --mode scripted: generate a starter loop script')
+    .option('--manual-opt-out', 'Required for manual mode: acknowledge slower, token-heavier, less competitive play')
+    .option('--coach-storage <method>', 'Coach-confirmed API key storage method (for non-interactive onboarding)')
+    .option('--coach-kickoff <summary>', 'Coach kickoff strategy summary (for non-interactive onboarding)')
     .option('--loop-file <path>', 'Starter loop script output path', 'clawcity-loop.sh')
     .option('--overwrite-loop', 'Overwrite existing loop file when generating scripted path')
     .action(async (skill, options) => {
@@ -86,6 +90,7 @@ registerAvatarCommands(program);
 registerProfileCommands(program);
 registerFeedbackCommands(program);
 registerOracleCommands(program);
+registerOnboardingCommands(program);
 registerApiCommands(program);
 registerPlanningCommands(program);
 program.parse();

package/dist/lib/onboarding-state.d.ts

@@ -0,0 +1,46 @@
+export type OnboardingMode = 'manual' | 'scripted';
+export type ScriptUsageKind = 'generated' | 'custom' | 'inline';
+type OracleSource = 'command' | 'install';
+export interface OnboardingState {
+    version: 1;
+    created_at: string;
+    updated_at: string;
+    agent_name: string;
+    mode: OnboardingMode;
+    generated_script_path: string | null;
+    generated_script_created: boolean;
+    coach_handoff: {
+        required: boolean;
+        completed: boolean;
+        completed_at: string | null;
+        storage_method: string | null;
+        kickoff_strategy: string | null;
+    };
+    oracle: {
+        required_before_actions: boolean;
+        completed: boolean;
+        completed_at: string | null;
+        source: OracleSource | null;
+    };
+    script_usage: {
+        any_script_observed: boolean;
+        generated_script_observed: boolean;
+        kind: ScriptUsageKind | null;
+        observed_at: string | null;
+    };
+}
+export declare function getOnboardingStatePath(): string;
+export declare function readOnboardingState(): Promise<OnboardingState | null>;
+export declare function writeOnboardingState(state: OnboardingState): Promise<void>;
+export declare function initializeOnboardingState(input: {
+    agentName: string;
+    mode: OnboardingMode;
+    generatedScriptPath: string | null;
+    generatedScriptCreated: boolean;
+    coachStorageMethod: string;
+    coachKickoffStrategy: string;
+}): Promise<OnboardingState>;
+export declare function markOracleCompleted(source: OracleSource): Promise<OnboardingState | null>;
+export declare function markScriptUsage(kind: ScriptUsageKind): Promise<OnboardingState | null>;
+export declare function assertOnboardingReadyForMutatingAction(action: string): Promise<void>;
+export {};

package/dist/lib/onboarding-state.js

@@ -0,0 +1,158 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, resolve as resolvePath } from 'node:path';
+function nowIso() {
+    return new Date().toISOString();
+}
+export function getOnboardingStatePath() {
+    const fromEnv = process.env.CLAWCITY_ONBOARDING_STATE_PATH;
+    if (fromEnv && fromEnv.trim().length > 0) {
+        return resolvePath(fromEnv);
+    }
+    return resolvePath(homedir(), '.config', 'clawcity', 'onboarding-state.json');
+}
+function asRecord(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : null;
+}
+function asBoolean(value) {
+    return typeof value === 'boolean' ? value : null;
+}
+function asString(value) {
+    return typeof value === 'string' && value.length > 0 ? value : null;
+}
+function parseMode(value) {
+    return value === 'manual' ? 'manual' : 'scripted';
+}
+function parseScriptKind(value) {
+    if (value === 'generated' || value === 'custom' || value === 'inline')
+        return value;
+    return null;
+}
+function parseOracleSource(value) {
+    if (value === 'command' || value === 'install')
+        return value;
+    return null;
+}
+export async function readOnboardingState() {
+    try {
+        const raw = await readFile(getOnboardingStatePath(), 'utf8');
+        const parsed = JSON.parse(raw);
+        const record = asRecord(parsed);
+        if (!record)
+            return null;
+        const coach = asRecord(record.coach_handoff) || {};
+        const oracle = asRecord(record.oracle) || {};
+        const scriptUsage = asRecord(record.script_usage) || {};
+        return {
+            version: 1,
+            created_at: asString(record.created_at) || nowIso(),
+            updated_at: asString(record.updated_at) || nowIso(),
+            agent_name: asString(record.agent_name) || 'unknown',
+            mode: parseMode(record.mode),
+            generated_script_path: asString(record.generated_script_path),
+            generated_script_created: asBoolean(record.generated_script_created) === true,
+            coach_handoff: {
+                required: asBoolean(coach.required) !== false,
+                completed: asBoolean(coach.completed) === true,
+                completed_at: asString(coach.completed_at),
+                storage_method: asString(coach.storage_method),
+                kickoff_strategy: asString(coach.kickoff_strategy),
+            },
+            oracle: {
+                required_before_actions: asBoolean(oracle.required_before_actions) !== false,
+                completed: asBoolean(oracle.completed) === true,
+                completed_at: asString(oracle.completed_at),
+                source: parseOracleSource(oracle.source),
+            },
+            script_usage: {
+                any_script_observed: asBoolean(scriptUsage.any_script_observed) === true,
+                generated_script_observed: asBoolean(scriptUsage.generated_script_observed) === true,
+                kind: parseScriptKind(scriptUsage.kind),
+                observed_at: asString(scriptUsage.observed_at),
+            },
+        };
+    }
+    catch {
+        return null;
+    }
+}
+export async function writeOnboardingState(state) {
+    const path = getOnboardingStatePath();
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, `${JSON.stringify(state, null, 2)}\n`, 'utf8');
+}
+export async function initializeOnboardingState(input) {
+    const now = nowIso();
+    const state = {
+        version: 1,
+        created_at: now,
+        updated_at: now,
+        agent_name: input.agentName,
+        mode: input.mode,
+        generated_script_path: input.generatedScriptPath,
+        generated_script_created: input.generatedScriptCreated,
+        coach_handoff: {
+            required: true,
+            completed: true,
+            completed_at: now,
+            storage_method: input.coachStorageMethod,
+            kickoff_strategy: input.coachKickoffStrategy,
+        },
+        oracle: {
+            required_before_actions: true,
+            completed: false,
+            completed_at: null,
+            source: null,
+        },
+        script_usage: {
+            any_script_observed: false,
+            generated_script_observed: false,
+            kind: null,
+            observed_at: null,
+        },
+    };
+    await writeOnboardingState(state);
+    return state;
+}
+export async function markOracleCompleted(source) {
+    const state = await readOnboardingState();
+    if (!state)
+        return null;
+    const now = nowIso();
+    state.oracle.completed = true;
+    state.oracle.completed_at = now;
+    state.oracle.source = source;
+    state.updated_at = now;
+    await writeOnboardingState(state);
+    return state;
+}
+export async function markScriptUsage(kind) {
+    const state = await readOnboardingState();
+    if (!state)
+        return null;
+    const now = nowIso();
+    state.script_usage.any_script_observed = true;
+    state.script_usage.generated_script_observed = state.script_usage.generated_script_observed || kind === 'generated';
+    state.script_usage.kind = kind;
+    state.script_usage.observed_at = now;
+    state.updated_at = now;
+    await writeOnboardingState(state);
+    return state;
+}
+export async function assertOnboardingReadyForMutatingAction(action) {
+    const state = await readOnboardingState();
+    if (!state)
+        return;
+    if (state.coach_handoff.required && !state.coach_handoff.completed) {
+        console.error(`Error: coach handoff gate is incomplete before "${action}".`);
+        console.error('Complete onboarding via: clawcity install clawcity --with-loop');
+        process.exit(2);
+    }
+    if (state.oracle.required_before_actions && !state.oracle.completed) {
+        console.error(`Error: Oracle onboarding must run before "${action}".`);
+        console.error('Run: clawcity oracle');
+        process.exit(2);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawcity",
-  "version": "2.5.4",
+  "version": "2.5.6",
   "description": "Agent-first CLI for ClawCity gameplay, tournaments, and public game APIs",
   "type": "module",
   "main": "dist/index.js",