@nexstone/rift-cli 0.1.1

package/dist/commands/walkforward.js

@@ -0,0 +1,191 @@
+import { Flags, Args } from '@oclif/core';
+import { GatedCommand } from '../lib/base-command.js';
+import { runEngine } from '../lib/python-bridge.js';
+const green = (s) => `\x1b[32m${s}\x1b[0m`;
+const red = (s) => `\x1b[31m${s}\x1b[0m`;
+const yellow = (s) => `\x1b[33m${s}\x1b[0m`;
+const cyan = (s) => `\x1b[36m${s}\x1b[0m`;
+const bold = (s) => `\x1b[1m${s}\x1b[0m`;
+const dim = (s) => `\x1b[2m${s}\x1b[0m`;
+function colorNum(val, suffix = '') {
+    const str = `${val}${suffix}`;
+    if (val > 0)
+        return green(str);
+    if (val < 0)
+        return red(str);
+    return yellow(str);
+}
+function gradeBadge(ratio) {
+    if (ratio >= 0.7)
+        return green(bold('ROBUST'));
+    if (ratio >= 0.4)
+        return yellow(bold('MODERATE'));
+    if (ratio > 0)
+        return red(bold('WEAK'));
+    return red(bold('OVERFIT'));
+}
+export default class WalkForward extends GatedCommand {
+    static description = 'Run walk-forward analysis to test strategy robustness';
+    // Engine command and docs/guide use the hyphenated form. File basename
+    // `walkforward` (one word) stays for backwards compatibility.
+    static aliases = ['walk-forward'];
+    static examples = [
+        '$ rift walk-forward trend_follow --pair BTC --tf 1h --wf 3m/1m',
+        '$ rift walk-forward trend_follow --pair BTC --tf 4h --wf 6m/2m',
+    ];
+    static args = {
+        strategy: Args.string({ description: 'Strategy name', required: true }),
+    };
+    static flags = {
+        pair: Flags.string({ description: 'Trading pair', default: 'BTC-PERP' }),
+        tf: Flags.string({ description: 'Timeframe', default: '1h' }),
+        wf: Flags.string({
+            description: "Walk-forward config: train/test (e.g. 6m/3m). " +
+                "Default uses the strategy's recommended_train_months / " +
+                "recommended_test_months (or 3m/1m if unset).",
+            default: '',
+        }),
+        equity: Flags.integer({ description: 'Starting equity per window', default: 10000 }),
+        leverage: Flags.integer({ description: 'Leverage multiplier', default: 1 }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(WalkForward);
+        this.log('');
+        this.log(`  ${bold('Walk-Forward Analysis')}`);
+        const wfDisplay = flags.wf || "strategy default";
+        this.log(`  ${dim(`${args.strategy} on ${flags.pair} ${flags.tf} — ${wfDisplay} windows`)}`);
+        this.log('');
+        const engineArgs = [
+            args.strategy,
+            '--pair', flags.pair,
+            '--tf', flags.tf,
+            '--equity', String(flags.equity),
+            '--leverage', String(flags.leverage),
+        ];
+        // Only forward --wf when the user actually passed one. Otherwise let
+        // the engine pick the strategy's recommended_train_months / _test_months.
+        if (flags.wf) {
+            engineArgs.push('--wf', flags.wf);
+        }
+        await runEngine('walk-forward', engineArgs, (msg) => {
+            if (msg.type === 'progress' && msg.msg) {
+                process.stdout.write(`\r  ${dim(String(msg.msg))}${''.padEnd(20)}`);
+            }
+            else if (msg.type === 'result') {
+                process.stdout.write('\r' + ' '.repeat(80) + '\r');
+                this.renderResult(msg);
+            }
+            else if (msg.type === 'error') {
+                process.stdout.write('\r' + ' '.repeat(80) + '\r');
+                this.error(msg.msg);
+            }
+        });
+    }
+    renderResult(msg) {
+        const windows = msg.windows;
+        const is = msg.in_sample;
+        const oos = msg.out_of_sample;
+        const degradation = msg.degradation_ratio;
+        const pctProfitable = msg.pct_profitable_windows;
+        const numWindows = msg.num_windows;
+        // Per-window results table
+        this.log(dim('  ── Per-Window Results ──'));
+        this.log('');
+        const hdr = `  ${dim('│')} ${'#'.padEnd(3)} ${'Train Period'.padEnd(24)} ${'Test Period'.padEnd(24)} ${'IS Return'.padEnd(12)} ${'OOS Return'.padEnd(12)} ${'OOS Sharpe'.padEnd(12)} ${dim('│')}`;
+        const hr = `  ${dim('─'.repeat(hdr.replace(/\x1b\[[0-9;]*m/g, '').length - 2))}`;
+        this.log(hr);
+        this.log(hdr);
+        this.log(hr);
+        for (const w of windows) {
+            const isRet = colorNum(w.in_sample.return_pct, '%');
+            const oosRet = colorNum(w.out_of_sample.return_pct, '%');
+            const oosSharpe = colorNum(w.out_of_sample.sharpe);
+            const isRetClean = `${w.in_sample.return_pct}%`;
+            const oosRetClean = `${w.out_of_sample.return_pct}%`;
+            const oosSharpeClean = `${w.out_of_sample.sharpe}`;
+            const trainPeriod = `${w.train_period.start} → ${w.train_period.end}`;
+            const testPeriod = `${w.test_period.start} → ${w.test_period.end}`;
+            this.log(`  ${dim('│')} ${String(w.window).padEnd(3)} ${trainPeriod.padEnd(24)} ${testPeriod.padEnd(24)} ${isRet}${' '.repeat(Math.max(1, 12 - isRetClean.length))} ${oosRet}${' '.repeat(Math.max(1, 12 - oosRetClean.length))} ${oosSharpe}${' '.repeat(Math.max(1, 12 - oosSharpeClean.length))} ${dim('│')}`);
+        }
+        this.log(hr);
+        this.log('');
+        // Summary box
+        const w = 55;
+        const boxHr = '─'.repeat(w - 2);
+        this.log(`  ${dim('┌' + boxHr + '┐')}`);
+        this.log(`  ${dim('│')} ${bold('WALK-FORWARD SUMMARY')}${' '.repeat(w - 23)}${dim('│')}`);
+        this.log(`  ${dim('├' + boxHr + '┤')}`);
+        this.log(this.row('Strategy', String(msg.strategy), w));
+        this.log(this.row('Pair / Interval', `${msg.pair} ${msg.interval}`, w));
+        this.log(this.row('Config', String(msg.config), w));
+        this.log(this.row('Windows', String(numWindows), w));
+        this.log(`  ${dim('├' + boxHr + '┤')}`);
+        this.log(`  ${dim('│')} ${dim('IN-SAMPLE (train periods)')}${' '.repeat(w - 29)}${dim('│')}`);
+        this.log(`  ${dim('├' + boxHr + '┤')}`);
+        this.log(this.rowColored('Avg Return', is.avg_return_pct, '%', w));
+        this.log(this.rowColored('Avg Sharpe', is.avg_sharpe, '', w));
+        this.log(this.row('Avg Win Rate', `${is.avg_win_rate}%`, w));
+        this.log(this.rowColored('Avg Max Drawdown', is.avg_max_drawdown_pct, '%', w));
+        this.log(this.row('Total Trades', String(is.total_trades), w));
+        this.log(`  ${dim('├' + boxHr + '┤')}`);
+        this.log(`  ${dim('│')} ${bold('OUT-OF-SAMPLE (test periods — unseen data)')}${' '.repeat(w - 46)}${dim('│')}`);
+        this.log(`  ${dim('├' + boxHr + '┤')}`);
+        this.log(this.rowColored('Avg Return', oos.avg_return_pct, '%', w));
+        this.log(this.rowColored('Avg Sharpe', oos.avg_sharpe, '', w));
+        this.log(this.row('Avg Win Rate', `${oos.avg_win_rate}%`, w));
+        this.log(this.rowColored('Avg Max Drawdown', oos.avg_max_drawdown_pct, '%', w));
+        this.log(this.row('Total Trades', String(oos.total_trades), w));
+        this.log(this.rowColored('Combined OOS Return', oos.combined_return_pct, '%', w));
+        this.log(`  ${dim('├' + boxHr + '┤')}`);
+        this.log(`  ${dim('│')} ${bold('ROBUSTNESS')}${' '.repeat(w - 14)}${dim('│')}`);
+        this.log(`  ${dim('├' + boxHr + '┤')}`);
+        // Degradation ratio with badge
+        const badge = gradeBadge(degradation);
+        const degStr = `${degradation} — ${badge}`;
+        // Can't easily calc ANSI-free length of badge, so just pad generously
+        this.log(`  ${dim('│')}  Degradation Ratio:  ${degStr}${' '.repeat(Math.max(1, 10))}${dim('│')}`);
+        this.log(this.row('Profitable Windows', `${pctProfitable}%`, w, pctProfitable >= 60 ? 'green' : pctProfitable >= 40 ? 'yellow' : 'red'));
+        this.log(`  ${dim('└' + boxHr + '┘')}`);
+        this.log('');
+        // Interpretation
+        this.log(dim('  ── Interpretation ──'));
+        this.log('');
+        if (degradation >= 0.7) {
+            this.log(`  ${green('Strategy shows strong out-of-sample performance.')}`);
+            this.log(`  ${dim('The strategy maintains most of its edge on unseen data — this is a good sign for live trading.')}`);
+        }
+        else if (degradation >= 0.4) {
+            this.log(`  ${yellow('Strategy shows moderate degradation on unseen data.')}`);
+            this.log(`  ${dim('Some of the backtest performance is likely from curve-fitting. Consider simplifying parameters.')}`);
+        }
+        else if (degradation > 0) {
+            this.log(`  ${red('Strategy shows significant degradation on unseen data.')}`);
+            this.log(`  ${dim('Most of the backtest edge disappears out-of-sample. High risk of failure in live trading.')}`);
+        }
+        else {
+            this.log(`  ${red('Strategy is likely overfit.')}`);
+            this.log(`  ${dim('Out-of-sample performance is negative — the strategy loses money on new data. Do not trade this.')}`);
+        }
+        this.log('');
+    }
+    row(label, value, width, color) {
+        const labelStr = `  ${label}:`;
+        const cleanVal = value.replace(/\x1b\[[0-9;]*m/g, '');
+        const padding = width - labelStr.length - cleanVal.length - 3;
+        let coloredVal = value;
+        if (color === 'green')
+            coloredVal = green(value);
+        else if (color === 'red')
+            coloredVal = red(value);
+        else if (color === 'yellow')
+            coloredVal = yellow(value);
+        return `  ${dim('│')}${labelStr}${' '.repeat(Math.max(1, padding))}${coloredVal} ${dim('│')}`;
+    }
+    rowColored(label, value, suffix, width) {
+        const coloredStr = colorNum(value, suffix);
+        const cleanStr = `${value}${suffix}`;
+        const labelStr = `  ${label}:`;
+        const padding = width - labelStr.length - cleanStr.length - 3;
+        return `  ${dim('│')}${labelStr}${' '.repeat(Math.max(1, padding))}${coloredStr} ${dim('│')}`;
+    }
+}

package/dist/commands/withdraw.d.ts

@@ -0,0 +1,12 @@
+import { GatedCommand } from '../lib/base-command.js';
+export default class Withdraw extends GatedCommand {
+    static description: string;
+    static examples: string[];
+    static args: {
+        amount: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        destination: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/withdraw.js

@@ -0,0 +1,55 @@
+import { Args, Flags } from '@oclif/core';
+import { GatedCommand } from '../lib/base-command.js';
+import { requestWithdrawal, postToHyperliquid, getExistingSession } from '../lib/walletconnect.js';
+import { loadCredentials, getAccountAddress } from '../lib/credentials.js';
+import { green, red, cyan, dim } from '../lib/tui.js';
+export default class Withdraw extends GatedCommand {
+    static description = 'Withdraw USDC from Hyperliquid to Arbitrum';
+    static examples = [
+        '$ rift withdraw 100',
+        '$ rift withdraw 50 --destination 0x1234...',
+    ];
+    static args = {
+        amount: Args.string({ description: 'USDC amount to withdraw', required: true }),
+    };
+    static flags = {
+        destination: Flags.string({ description: 'Arbitrum address to receive USDC (defaults to main wallet)', default: '' }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(Withdraw);
+        const amount = args.amount;
+        const isMainnet = true;
+        const creds = loadCredentials();
+        if (!creds) {
+            this.log(`  ${red('✘')} No wallet configured. Run: ${cyan('rift auth setup')}`);
+            return;
+        }
+        const destination = flags.destination || getAccountAddress(creds);
+        // Check for existing WalletConnect session
+        const session = await getExistingSession();
+        if (!session) {
+            this.log(`  ${red('✘')} No wallet session. Run: ${cyan('rift auth setup')} to reconnect.`);
+            return;
+        }
+        this.log('');
+        this.log(`  Withdrawing $${amount} USDC to Arbitrum...`);
+        this.log(`  ${dim('→ Approve in your wallet (check your phone)')}`);
+        this.log('');
+        const result = await requestWithdrawal(amount, destination, isMainnet);
+        if (!result.success) {
+            this.log(`  ${red('✘')} Withdrawal failed: ${result.error}`);
+            return;
+        }
+        // Post to Hyperliquid
+        try {
+            const response = await postToHyperliquid(result.action, result.signature, result.nonce, isMainnet);
+            this.log(`  ${green('✔')} Withdrawal submitted`);
+            this.log(`  ${dim(`$${amount} USDC will arrive on Arbitrum in ~2 minutes`)}`);
+            this.log(`  ${dim('$1 fee deducted by Hyperliquid')}`);
+            this.log('');
+        }
+        catch (error) {
+            this.log(`  ${red('✘')} Failed to submit withdrawal: ${error.message}`);
+        }
+    }
+}

package/dist/commands/workbench-create.d.ts

@@ -0,0 +1,13 @@
+import { GatedCommand } from '../lib/base-command.js';
+export default class WorkbenchCreate extends GatedCommand {
+    static description: string;
+    static examples: string[];
+    static args: {
+        name: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    static flags: {
+        template: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

package/dist/commands/workbench-create.js

@@ -0,0 +1,39 @@
+import { Args, Flags } from '@oclif/core';
+import { GatedCommand } from '../lib/base-command.js';
+import { passthroughToEngine } from '../lib/engine-passthrough.js';
+export default class WorkbenchCreate extends GatedCommand {
+    static description = 'Create a new custom strategy from a workbench template (config-as-data — no Python required).';
+    static examples = [
+        '$ rift workbench-create my_strategy',
+        '$ rift workbench-create rsi_revert --template single_signal_example',
+    ];
+    static args = {
+        // Engine validator requires letters/numbers/underscores only — reject
+        // hyphens up front so the user sees a clear error from oclif's parser
+        // rather than the engine's "Invalid strategy name" reply.
+        name: Args.string({
+            description: 'Name for the new strategy (letters, numbers, underscores)',
+            required: true,
+        }),
+    };
+    static flags = {
+        template: Flags.string({
+            description: 'Template to seed from',
+            options: ['blank', 'single_signal_example'],
+            default: 'blank',
+        }),
+        json: Flags.boolean({ description: 'Emit raw JSON only', default: false }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(WorkbenchCreate);
+        const engineArgs = [args.name, '--template', flags.template];
+        await passthroughToEngine({
+            command: 'workbench-create',
+            args: engineArgs,
+            log: (m) => this.log(m),
+            error: (m) => this.error(m),
+            exit: (c) => this.exit(c),
+            jsonOnly: flags.json,
+        });
+    }
+}

package/dist/lib/account-mode.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Hyperliquid account abstraction mode detection + collateral reading.
+ *
+ * TS mirror of packages/data/src/rift_data/account_mode.py. The two MUST
+ * agree on what counts as "tradeable collateral" per mode, or Python and
+ * TS surfaces will show different numbers to the same user.
+ *
+ * Modes:
+ *   - 'standard'         Spot and perp are separate. Only perp counts.
+ *   - 'unified'          UI default. Spot USDC IS perp collateral.
+ *   - 'portfolio_margin' Pooled USDC + LTV-weighted assets. Per HL docs,
+ *                        perp dex user state is "not meaningful" here;
+ *                        real collateral lives in spot. v0.1 counts USDC
+ *                        only — non-USDC PM collateral (HYPE/BTC/USDH at
+ *                        oracle*LTV) under-counted; LTV table not exposed
+ *                        via info endpoints.
+ *   - 'unknown'          Future HL mode we don't recognize. Treated as
+ *                        unified (sum) for safety.
+ *
+ * Detection uses HL's /info endpoint with type='userAbstraction'. There's
+ * a confusingly-named 'userDexAbstraction' endpoint — that's a DIFFERENT
+ * mode (DEX Abstraction, being discontinued). Do not confuse.
+ */
+export type AccountMode = 'standard' | 'unified' | 'portfolio_margin' | 'unknown';
+export interface CollateralBreakdown {
+    mode: AccountMode;
+    perpAccountValue: number;
+    perpMarginUsed: number;
+    perpAvailable: number;
+    spotUsdc: number;
+    /** What sizing logic / gates should use. */
+    total: number;
+    /** True if spot USDC is NOT counted (Standard mode). */
+    perpOnly: boolean;
+}
+export declare const hlBaseUrl: (_isMainnet?: boolean) => string;
+export declare function queryAccountMode(baseUrl: string, address: string): Promise<AccountMode>;
+/**
+ * Read the wallet's available collateral, mode-aware. One source of truth
+ * for "how much can this wallet trade with" in TS surfaces.
+ *
+ * Three HL info calls in parallel: perp state, spot state, mode.
+ */
+export declare function readCollateral(baseUrl: string, address: string): Promise<CollateralBreakdown>;

package/dist/lib/account-mode.js

@@ -0,0 +1,96 @@
+/**
+ * Hyperliquid account abstraction mode detection + collateral reading.
+ *
+ * TS mirror of packages/data/src/rift_data/account_mode.py. The two MUST
+ * agree on what counts as "tradeable collateral" per mode, or Python and
+ * TS surfaces will show different numbers to the same user.
+ *
+ * Modes:
+ *   - 'standard'         Spot and perp are separate. Only perp counts.
+ *   - 'unified'          UI default. Spot USDC IS perp collateral.
+ *   - 'portfolio_margin' Pooled USDC + LTV-weighted assets. Per HL docs,
+ *                        perp dex user state is "not meaningful" here;
+ *                        real collateral lives in spot. v0.1 counts USDC
+ *                        only — non-USDC PM collateral (HYPE/BTC/USDH at
+ *                        oracle*LTV) under-counted; LTV table not exposed
+ *                        via info endpoints.
+ *   - 'unknown'          Future HL mode we don't recognize. Treated as
+ *                        unified (sum) for safety.
+ *
+ * Detection uses HL's /info endpoint with type='userAbstraction'. There's
+ * a confusingly-named 'userDexAbstraction' endpoint — that's a DIFFERENT
+ * mode (DEX Abstraction, being discontinued). Do not confuse.
+ */
+const HL_TO_FRIENDLY = {
+    disabled: 'standard',
+    unifiedAccount: 'unified',
+    portfolioMargin: 'portfolio_margin',
+};
+const _hlPost = async (baseUrl, body) => {
+    const resp = await fetch(`${baseUrl}/info`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(body),
+    });
+    if (!resp.ok)
+        throw new Error(`HL info ${resp.status}`);
+    return resp.json();
+};
+export const hlBaseUrl = (_isMainnet = true) => 'https://api.hyperliquid.xyz';
+export async function queryAccountMode(baseUrl, address) {
+    const raw = await _hlPost(baseUrl, { type: 'userAbstraction', user: address.toLowerCase() });
+    if (typeof raw !== 'string')
+        return 'unknown';
+    return HL_TO_FRIENDLY[raw] ?? 'unknown';
+}
+/**
+ * Read the wallet's available collateral, mode-aware. One source of truth
+ * for "how much can this wallet trade with" in TS surfaces.
+ *
+ * Three HL info calls in parallel: perp state, spot state, mode.
+ */
+export async function readCollateral(baseUrl, address) {
+    const addr = address.toLowerCase();
+    const [perp, spot, modeRaw] = await Promise.all([
+        _hlPost(baseUrl, { type: 'clearinghouseState', user: addr }),
+        _hlPost(baseUrl, { type: 'spotClearinghouseState', user: addr }),
+        _hlPost(baseUrl, { type: 'userAbstraction', user: addr }),
+    ]);
+    const mode = typeof modeRaw === 'string' ? (HL_TO_FRIENDLY[modeRaw] ?? 'unknown') : 'unknown';
+    const summary = perp?.marginSummary ?? {};
+    const perpAccountValue = parseFloat(summary.accountValue ?? '0');
+    const perpMarginUsed = parseFloat(summary.totalMarginUsed ?? '0');
+    const perpAvailable = perpAccountValue - perpMarginUsed;
+    let spotUsdc = 0;
+    for (const b of spot?.balances ?? []) {
+        if (b?.coin === 'USDC') {
+            spotUsdc = parseFloat(b.total ?? '0');
+            break;
+        }
+    }
+    let total;
+    switch (mode) {
+        case 'standard':
+            total = perpAvailable;
+            break;
+        case 'unified':
+        case 'portfolio_margin':
+            // HL docs: under both modes, perp state is "not meaningful";
+            // real collateral is in spot. v0.1 counts USDC only — see file
+            // header for the PM non-USDC caveat.
+            total = perpAvailable + spotUsdc;
+            break;
+        default:
+            // unknown: sum, matching Python's safest-default behavior
+            total = perpAvailable + spotUsdc;
+    }
+    return {
+        mode,
+        perpAccountValue,
+        perpMarginUsed,
+        perpAvailable,
+        spotUsdc,
+        total,
+        perpOnly: mode === 'standard',
+    };
+}

package/dist/lib/analyzer.d.ts

@@ -0,0 +1,4 @@
+/**
+ * AI-powered backtest analysis using Claude API.
+ */
+export declare function analyzeBacktest(resultData: Record<string, unknown>): Promise<string>;

package/dist/lib/analyzer.js

@@ -0,0 +1,62 @@
+/**
+ * AI-powered backtest analysis using Claude API.
+ */
+import Anthropic from '@anthropic-ai/sdk';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+const CONFIG_PATH = path.join(process.env.HOME || '~', '.rift', 'config.json');
+function loadAIConfig() {
+    // Check env var first
+    const envKey = process.env.RIFT_AI_API_KEY || process.env.ANTHROPIC_API_KEY;
+    if (envKey) {
+        return { apiKey: envKey, model: 'claude-sonnet-4-20250514' };
+    }
+    // Check config file
+    if (fs.existsSync(CONFIG_PATH)) {
+        try {
+            const config = JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf-8'));
+            const ai = config.ai;
+            if (ai?.api_key) {
+                return { apiKey: ai.api_key, model: ai.model || 'claude-sonnet-4-20250514' };
+            }
+        }
+        catch { }
+    }
+    return null;
+}
+const SYSTEM_PROMPT = `You are a senior quantitative analyst reviewing backtest results for a trading strategy on Hyperliquid perpetual futures. Your job is to give a concise, actionable assessment.
+
+Be direct and specific. No fluff. Focus on:
+1. Is this strategy viable for real trading? Why or why not?
+2. What are the critical risk issues?
+3. What specific parameter changes would improve it?
+4. What's the one thing the trader should fix first?
+
+Keep your response under 200 words. Use plain language. If the strategy would blow up a real account, say so clearly.`;
+export async function analyzeBacktest(resultData) {
+    const config = loadAIConfig();
+    if (!config) {
+        return 'No AI API key configured. Run: rift config set ai.api_key <your-anthropic-key>\nOr set RIFT_AI_API_KEY or ANTHROPIC_API_KEY environment variable.';
+    }
+    const client = new Anthropic({ apiKey: config.apiKey });
+    // Build a clean summary for the LLM
+    const { chart, export: _, type, command, ...metrics } = resultData;
+    const trades = resultData.export?.trades || [];
+    const prompt = `Analyze this backtest result:
+
+${JSON.stringify(metrics, null, 2)}
+
+Number of trades in detail: ${trades.length}
+${trades.length > 0 ? `First trade: ${JSON.stringify(trades[0])}
+Last trade: ${JSON.stringify(trades[trades.length - 1])}` : 'No trades executed.'}
+
+${trades.length === 0 ? 'The strategy made zero trades. This likely means the entry conditions were never met for this pair/timeframe combination.' : ''}`;
+    const response = await client.messages.create({
+        model: config.model,
+        max_tokens: 500,
+        system: SYSTEM_PROMPT,
+        messages: [{ role: 'user', content: prompt }],
+    });
+    const textBlock = response.content.find(b => b.type === 'text');
+    return textBlock ? textBlock.text : 'No analysis returned.';
+}

package/dist/lib/base-command.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Base command for RIFT — every CLI command extends `GatedCommand`.
+ *
+ * The historical name "GatedCommand" is kept to avoid churning 17 import
+ * sites; it doesn't actually gate anything in v0.1. Acts as the central
+ * point for cross-cutting CLI behavior:
+ *
+ *   Persistent status footer (Phase 0 polish item #5)
+ *     - Renders a single-line footer at the end of every command's output
+ *       showing system state (live ready / research-only / kill switch / etc.)
+ *     - TTY-only — suppressed for piped output so `rift list-data | jq`
+ *       still produces clean JSON
+ *     - Opt out per command by setting `static skipFooter = true`
+ *       (e.g., `home` which renders its own bottom-of-screen status)
+ *
+ * Future hook points (Phase 1+):
+ *   - Fee-gating prompts (where the name originally came from)
+ *   - Telemetry emit
+ *   - Auth state checks before live commands
+ */
+import { Command } from '@oclif/core';
+export declare abstract class GatedCommand extends Command {
+    /**
+     * Subclass override: skip the auto-rendered status footer.
+     * For commands that render their own bottom-of-screen status (home)
+     * or emit raw structured data where a trailing footer would be wrong.
+     */
+    static skipFooter: boolean;
+    init(): Promise<void>;
+    /**
+     * oclif lifecycle: called after run() succeeds AND after catch() on error.
+     * Footer renders regardless of outcome — TTY check protects piped output.
+     */
+    protected finally(err: Error | undefined): Promise<unknown>;
+}

package/dist/lib/base-command.js

@@ -0,0 +1,49 @@
+/**
+ * Base command for RIFT — every CLI command extends `GatedCommand`.
+ *
+ * The historical name "GatedCommand" is kept to avoid churning 17 import
+ * sites; it doesn't actually gate anything in v0.1. Acts as the central
+ * point for cross-cutting CLI behavior:
+ *
+ *   Persistent status footer (Phase 0 polish item #5)
+ *     - Renders a single-line footer at the end of every command's output
+ *       showing system state (live ready / research-only / kill switch / etc.)
+ *     - TTY-only — suppressed for piped output so `rift list-data | jq`
+ *       still produces clean JSON
+ *     - Opt out per command by setting `static skipFooter = true`
+ *       (e.g., `home` which renders its own bottom-of-screen status)
+ *
+ * Future hook points (Phase 1+):
+ *   - Fee-gating prompts (where the name originally came from)
+ *   - Telemetry emit
+ *   - Auth state checks before live commands
+ */
+import { Command } from '@oclif/core';
+import { printStatusFooterIfTTYWithSpacing } from './status-footer.js';
+export class GatedCommand extends Command {
+    /**
+     * Subclass override: skip the auto-rendered status footer.
+     * For commands that render their own bottom-of-screen status (home)
+     * or emit raw structured data where a trailing footer would be wrong.
+     */
+    static skipFooter = false;
+    async init() {
+        await super.init();
+    }
+    /**
+     * oclif lifecycle: called after run() succeeds AND after catch() on error.
+     * Footer renders regardless of outcome — TTY check protects piped output.
+     */
+    async finally(err) {
+        const ctor = this.constructor;
+        if (!ctor.skipFooter) {
+            try {
+                printStatusFooterIfTTYWithSpacing();
+            }
+            catch {
+                // Never let footer rendering break command execution
+            }
+        }
+        return super.finally(err);
+    }
+}

package/dist/lib/credentials.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Wallet credential management — canonical snake_case schema, matching
+ * what the Python engine writes via `rift agent-pair` (rift_trade.api_wallet
+ * → rift_core.keys.APIWalletKey, serialized via Pydantic).
+ *
+ * File location: ~/.rift/credentials   (no extension, matches Python)
+ * Format: single-account JSON (snake_case fields).
+ *
+ * The loader is tolerant of two legacy formats:
+ *   (a) ~/.rift/credentials.json with camelCase fields (old TS auth.ts writer)
+ *   (b) Multi-account wrapped: {"default": {…}}
+ * Both are migrated to the canonical form on first read.
+ *
+ * The Python engine is the authoritative writer. The TS `rift auth setup`
+ * flow also writes to the same path + schema.
+ */
+export interface Credentials {
+    address: string;
+    private_key: string;
+    network: 'mainnet';
+    name?: string;
+    registered_at?: string;
+    registered_tx?: string | null;
+    account_address?: string;
+    type?: 'api-wallet' | 'generated' | 'walletconnect';
+    agent_approved?: boolean;
+    builder_fee_approved?: boolean;
+}
+export declare function loadCredentials(): Credentials | null;
+export declare function saveCredentials(creds: Credentials): void;
+export declare function hasCredentials(): boolean;
+/**
+ * Returns true if the wallet is ready for live trading (mainnet-only).
+ *
+ *   - File must exist with `address` + `private_key` (pairing complete).
+ *   - `agent_approved` defaults to true when the file exists — the file is
+ *     only written after a successful approveAgent transaction.
+ *   - `builder_fee_approved` must be explicit `true`. Absent → user is
+ *     prompted to run `rift approve-builder-fee` before their first trade.
+ */
+export declare function hasFullSetup(): boolean;
+/** Main wallet address — falls back to API wallet address when not stored
+ * (older Python-paired wallets don't include account_address). */
+export declare function getAccountAddress(creds: Credentials): string;
+export declare function maskKey(key: string): string;
+export declare function maskAddress(addr: string): string;