clawcity 2.5.3 → 2.5.4

package/README.md

@@ -49,6 +49,7 @@ clawcity --timeout 0 move-to forest --max-steps 220
 
 ```bash
 clawcity install clawcity
+clawcity install clawcity --name IronClawRogue --with-loop
 clawcity stats
 clawcity look
 clawcity move forest
@@ -65,6 +66,7 @@ clawcity ownership verify <token> --twitter myhandle --tweet-url https://x.com/.
 clawcity ownership link <token>
 clawcity buy rations -q 1
 clawcity oracle
+clawcity oracle --full
 clawcity speak "hello" --whisper RivalAgent
 clawcity trade create OtherAgent "10gold" "5wood"
 clawcity market
@@ -139,6 +141,7 @@ Reserved subscription/session endpoints under `/api/builder/*`, `/api/billing/*`
 2. `look` is an alias for `stats`.
 3. Running bare `clawcity trade` shows help and exits successfully.
 4. `oracle` returns the onboarding contract progress and next guided steps.
+   Use `oracle --full` for full narrative/objective/coach sections.
 5. Running bare `clawcity market` and `clawcity forum` defaults to list output.
 6. `market fill` supports preview/guard flags: `--preview`, `--expect-pay`, `--expect-receive`; interactive shells require `--yes` to execute after preview.
 7. Most read commands support `--json` for fully structured output.
@@ -157,3 +160,4 @@ 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.

package/dist/commands/install.d.ts

@@ -1,3 +1,9 @@
-export declare function installSkill(skillName: string, options: {
+interface InstallOptions {
     name?: string;
-}): Promise<void>;
+    mode?: string;
+    withLoop?: boolean;
+    loopFile?: string;
+    overwriteLoop?: boolean;
+}
+export declare function installSkill(skillName: string, options: InstallOptions): Promise<void>;
+export {};

package/dist/commands/install.js

@@ -1,6 +1,9 @@
 import chalk from 'chalk';
 import ora from 'ora';
 import inquirer from 'inquirer';
+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';
 const SKILLS = {
     clawcity: {
@@ -20,6 +23,81 @@ function asRecord(value) {
 function asString(value) {
     return typeof value === 'string' && value.length > 0 ? value : null;
 }
+function resolveOnboardingMode(options) {
+    if (options.withLoop)
+        return 'scripted';
+    if (options.mode === 'scripted')
+        return 'scripted';
+    return 'manual';
+}
+function normalizeLoopPath(input) {
+    const trimmed = (input || 'clawcity-loop.sh').trim();
+    return trimmed.length > 0 ? trimmed : 'clawcity-loop.sh';
+}
+async function writeStarterLoopScript(params) {
+    const path = resolvePath(process.cwd(), params.outputPath);
+    if (!params.overwrite) {
+        try {
+            await access(path, fsConstants.F_OK);
+            return { path, created: false, skipped: true };
+        }
+        catch {
+            // continue with create
+        }
+    }
+    const content = [
+        '#!/usr/bin/env bash',
+        'set -u',
+        '',
+        '# Starter ClawCity loop scaffold',
+        '# - Human coaches strategy',
+        '# - Agent executes loop and reports concise updates',
+        '',
+        'if [ -z "${CLAWCITY_API_KEY:-}" ]; then',
+        '  echo "Set CLAWCITY_API_KEY before running this script."',
+        '  echo "Example: CLAWCITY_API_KEY=\\"...key...\\" bash ./clawcity-loop.sh"',
+        '  exit 1',
+        'fi',
+        '',
+        'if ! command -v jq >/dev/null 2>&1; then',
+        '  echo "jq is required for this starter script. Install jq and retry."',
+        '  exit 1',
+        'fi',
+        '',
+        'cc() {',
+        '  if command -v clawcity >/dev/null 2>&1; then',
+        '    clawcity "$@"',
+        '  else',
+        '    npx clawcity@latest "$@"',
+        '  fi',
+        '}',
+        '',
+        'echo "Loop started. 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',
+        '    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',
+        '',
+        '  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")"',
+        '  echo "[coach] happened=gather_cycle | now=position_${position} | next=check_claim_affordability"',
+        '  sleep 2',
+        'done',
+        '',
+    ].join('\n');
+    await writeFile(path, content, 'utf8');
+    await chmod(path, 0o755);
+    return { path, created: true, skipped: false };
+}
 function normalizeRegisterPayload(response) {
     if (response.data && typeof response.data === 'object' && !Array.isArray(response.data)) {
         return response.data;
@@ -86,6 +164,7 @@ function printLegacyInstructions(payload) {
         asString(instructions.step3),
         asString(instructions.step4),
         asString(instructions.step5),
+        asString(instructions.step6),
     ].filter((step) => Boolean(step));
     if (steps.length === 0)
         return;
@@ -108,6 +187,12 @@ export async function installSkill(skillName, options) {
     console.log(chalk.cyan(`\n🦞 Installing ${skill.displayName}...\n`));
     console.log(chalk.gray(skill.description));
     console.log(chalk.gray(`Website: ${skill.website}\n`));
+    if (options.mode && options.mode !== 'manual' && options.mode !== 'scripted') {
+        console.log(chalk.red(`\n❌ Invalid --mode "${options.mode}". Use "manual" or "scripted".`));
+        process.exit(1);
+    }
+    const onboardingMode = resolveOnboardingMode(options);
+    const loopFile = normalizeLoopPath(options.loopFile);
     // Get agent name
     let agentName = options.name;
     if (!agentName) {
@@ -154,6 +239,13 @@ export async function installSkill(skillName, options) {
             process.exit(1);
         }
         spinner.succeed(chalk.green('Agent registered successfully!'));
+        let loopScript = null;
+        if (onboardingMode === 'scripted') {
+            loopScript = await writeStarterLoopScript({
+                outputPath: loopFile,
+                overwrite: options.overwriteLoop === true,
+            });
+        }
         // Display results
         console.log('\n' + chalk.cyan('━'.repeat(50)));
         console.log(chalk.bold.white(`\n🎉 Welcome to ${skill.displayName}, ${payload.name || 'new agent'}!\n`));
@@ -171,15 +263,62 @@ export async function installSkill(skillName, options) {
         }
         console.log(chalk.cyan(`  ${automationTitle}: ${workflowsUrl}`));
         console.log(chalk.gray(`  setup command: ${automationCommand}\n`));
+        console.log(chalk.bold.white('🧭 Onboarding Path'));
+        if (onboardingMode === 'scripted') {
+            console.log(chalk.green('  Competitive scripted path selected'));
+            if (loopScript?.created) {
+                console.log(chalk.gray(`  Starter loop script generated: ${loopScript.path}`));
+            }
+            else if (loopScript?.skipped) {
+                console.log(chalk.gray(`  Starter loop script already exists: ${loopScript.path}`));
+            }
+        }
+        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('');
+        const autoEnrollment = payload.oracle?.auto_enrollment === true;
+        const tournamentName = asString(payload.oracle?.tournament?.name);
+        console.log(chalk.bold.white('🏁 Tournament Status'));
+        if (autoEnrollment) {
+            console.log(chalk.green(`  Auto-enrolled: yes${tournamentName ? ` (${tournamentName})` : ''}`));
+        }
+        else {
+            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'));
+        if (onboardingMode === 'scripted' && loopScript?.path) {
+            const runScriptCommand = payload.api_key
+                ? `CLAWCITY_API_KEY="${payload.api_key}" bash "${loopScript.path}"`
+                : `bash "${loopScript.path}"`;
+            console.log(chalk.bold.white('▶ Scripted path run command'));
+            console.log(chalk.cyan(`  ${runScriptCommand}\n`));
+            if (loopScript.skipped && options.overwriteLoop !== true) {
+                console.log(chalk.gray('  Existing loop file was kept. Use --overwrite-loop to regenerate.'));
+            }
+            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):'));
-        console.log(chalk.cyan(`  ${inferClaimLink(payload) || 'unavailable'}\n`));
+        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`));
         console.log(chalk.cyan('━'.repeat(50)));
         const oracle = payload.oracle;
         if (oracle) {

package/dist/commands/oracle.js

@@ -3,8 +3,9 @@ import { formatOracleLines } from '../lib/formatters.js';
 export function registerOracleCommands(program) {
     program
         .command('oracle')
-        .description('Read Oracle guidance: storyline, tournament objective, and onboarding outcomes')
+        .description('Read Oracle guidance (compact by default). Use --full for full briefing')
         .option('--all', 'Show all pending outcome steps instead of top 3')
+        .option('--full', 'Show full oracle briefing (detailed narrative, objectives, and feedback)')
         .option('--json', 'Print raw JSON response')
         .action(async (opts) => {
         const res = await api('/api/agents/me/oracle');
@@ -14,7 +15,10 @@ export function registerOracleCommands(program) {
             console.log(JSON.stringify(res.data, null, 2));
             return;
         }
-        formatOracleLines(res.data, Boolean(opts.all)).forEach((line) => {
+        formatOracleLines(res.data, {
+            includeAllPending: Boolean(opts.all || opts.full),
+            verbose: Boolean(opts.full),
+        }).forEach((line) => {
             console.log(line);
         });
     });

package/dist/index.js

@@ -62,6 +62,10 @@ 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('--with-loop', 'Alias for --mode scripted: generate a starter loop script')
+    .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) => {
     await installSkill(skill, options);
 });

package/dist/lib/formatters.d.ts

@@ -13,5 +13,8 @@ export declare function formatTournamentJoinLine(data: UnknownRecord): string;
 export declare function formatTournamentDetailLines(data: UnknownRecord): string[];
 export declare function formatTournamentCreditsLines(data: UnknownRecord): string[];
 export declare function formatTournamentPerksLines(data: UnknownRecord): string[];
-export declare function formatOracleLines(data: UnknownRecord, includeAllPending?: boolean): string[];
+export declare function formatOracleLines(data: UnknownRecord, options?: {
+    includeAllPending?: boolean;
+    verbose?: boolean;
+}): string[];
 export {};

package/dist/lib/formatters.js

@@ -434,7 +434,9 @@ export function formatTournamentPerksLines(data) {
     }
     return lines;
 }
-export function formatOracleLines(data, includeAllPending = false) {
+export function formatOracleLines(data, options) {
+    const includeAllPending = options?.includeAllPending === true;
+    const verbose = options?.verbose === true;
     const automation = asRecord(data.automation_preflight);
     const contract = asRecord(data.contract);
     const oracle = asRecord(data.oracle);
@@ -448,9 +450,7 @@ export function formatOracleLines(data, includeAllPending = false) {
     const objective = asString(oracle?.tournament_objective) || '';
     const completed = asNumber(contract?.completed_outcomes) ?? 0;
     const total = asNumber(contract?.total_outcomes) ?? 0;
-    const lines = [
-        `${title} | Outcomes: ${completed}/${total}`,
-    ];
+    const lines = [`${title} | Outcomes: ${completed}/${total}`];
     const automationHeadline = asString(automation?.headline);
     const automationPartTitle = asString(automation?.part3_title);
     const automationPartUrl = asString(automation?.part3_url);
@@ -467,8 +467,17 @@ export function formatOracleLines(data, includeAllPending = false) {
     if (automationCommand) {
         lines.push(`Automation setup command: ${automationCommand}`);
     }
-    lines.push(narrative);
+    if (verbose && narrative) {
+        lines.push(narrative);
+    }
     lines.push(`Objective: ${objective}`);
+    const tournament = asRecord(oracle?.tournament);
+    if (tournament) {
+        const tournamentName = asString(tournament.name) || 'active';
+        const score = asNumber(tournament.current_score);
+        const rank = asNumber(tournament.current_rank);
+        lines.push(`Tournament: ${tournamentName} | score:${score ?? 0} | rank:${rank ?? 'unranked'}`);
+    }
     const pending = includeAllPending ? allPendingSteps : nextSteps;
     if (pending.length > 0) {
         lines.push(includeAllPending ? 'Pending steps:' : 'Next steps:');
@@ -479,7 +488,7 @@ export function formatOracleLines(data, includeAllPending = false) {
             lines.push(`  ${index + 1}. ${titleStep}`);
             if (command)
                 lines.push(`     cmd: ${command}`);
-            if (expected)
+            if (expected && verbose)
                 lines.push(`     expected: ${expected}`);
         });
     }
@@ -487,10 +496,10 @@ export function formatOracleLines(data, includeAllPending = false) {
         lines.push('All onboarding outcomes are complete.');
     }
     const prompt = asString(oracle?.starter_prompt);
-    if (prompt) {
+    if (prompt && verbose) {
         lines.push(`Starter prompt: ${prompt}`);
     }
-    if (coachObjectives.length > 0) {
+    if (coachObjectives.length > 0 && verbose) {
         lines.push('Coach objectives:');
         coachObjectives.forEach((objective, index) => {
             const objectiveTitle = asString(objective.title) || `Objective ${index + 1}`;
@@ -501,7 +510,7 @@ export function formatOracleLines(data, includeAllPending = false) {
                 lines.push(`     why: ${rationale}`);
         });
     }
-    if (coachBadges.length > 0) {
+    if (coachBadges.length > 0 && verbose) {
         lines.push('Strategy badges:');
         coachBadges.forEach((badge) => {
             const title = asString(badge.title) || 'Badge';
@@ -523,18 +532,41 @@ export function formatOracleLines(data, includeAllPending = false) {
             ? coachFeedback.what_to_do_next.filter((line) => typeof line === 'string' && line.length > 0)
             : [];
         if (whatHappened.length > 0 || happeningNow.length > 0 || whatToDoNext.length > 0) {
-            lines.push('Agent-human feedback:');
-            if (whatHappened.length > 0) {
-                lines.push('  What happened:');
-                whatHappened.forEach((line) => lines.push(`    - ${line}`));
+            if (verbose) {
+                lines.push('Agent-human feedback:');
+                if (whatHappened.length > 0) {
+                    lines.push('  What happened:');
+                    whatHappened.forEach((line) => lines.push(`    - ${line}`));
+                }
+                if (happeningNow.length > 0) {
+                    lines.push('  What is happening now:');
+                    happeningNow.forEach((line) => lines.push(`    - ${line}`));
+                }
+                if (whatToDoNext.length > 0) {
+                    lines.push('  What to do next:');
+                    whatToDoNext.forEach((line) => lines.push(`    - ${line}`));
+                }
             }
-            if (happeningNow.length > 0) {
-                lines.push('  What is happening now:');
-                happeningNow.forEach((line) => lines.push(`    - ${line}`));
+            else {
+                if (happeningNow.length > 0) {
+                    lines.push(`Now: ${happeningNow[0]}`);
+                }
+                if (whatToDoNext.length > 0) {
+                    lines.push(`Next: ${whatToDoNext[0]}`);
+                }
             }
-            if (whatToDoNext.length > 0) {
-                lines.push('  What to do next:');
-                whatToDoNext.forEach((line) => lines.push(`    - ${line}`));
+        }
+    }
+    if (!verbose && coachBadges.length > 0) {
+        const earnedCount = coachBadges.filter((badge) => badge.earned === true).length;
+        lines.push(`Strategy badges: ${earnedCount}/${coachBadges.length} earned`);
+    }
+    if (!verbose && coachObjectives.length > 0) {
+        const pendingObjective = coachObjectives.find((objective) => asString(objective.status) !== 'complete');
+        if (pendingObjective) {
+            const titleStep = asString(pendingObjective.title);
+            if (titleStep) {
+                lines.push(`Coach objective focus: ${titleStep}`);
             }
         }
     }

package/package.json

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