@nexstone/rift-cli 0.1.1

package/dist/commands/more.js

@@ -0,0 +1,227 @@
+import { Args } from '@oclif/core';
+import { GatedCommand } from '../lib/base-command.js';
+import { runEngine } from '../lib/python-bridge.js';
+const bold = (s) => `\x1b[1m${s}\x1b[0m`;
+const cyan = (s) => `\x1b[36m${s}\x1b[0m`;
+const green = (s) => `\x1b[32m${s}\x1b[0m`;
+const dim = (s) => `\x1b[2m${s}\x1b[0m`;
+const red = (s) => `\x1b[31m${s}\x1b[0m`;
+const CATALOG = {
+    'Research & backtesting': [
+        { name: 'backtest', desc: 'Run a backtest on cached candle data', promoted: true },
+        { name: 'compare', desc: 'Compare multiple strategies head-to-head', promoted: true },
+        { name: 'sweep', desc: 'Run a parameter sweep', promoted: true },
+        { name: 'smart-sweep', desc: 'Bayesian-optimized parameter sweep', promoted: false },
+        { name: 'montecarlo', desc: 'Monte Carlo simulation', promoted: true },
+        { name: 'walk-forward', desc: 'Walk-forward validation', promoted: true },
+        { name: 'research', desc: 'Full research pipeline (backtest + WF + MC + gates)', promoted: true },
+        { name: 'quick-test', desc: 'Quick sanity backtest', promoted: true },
+        { name: 'portfolio-backtest', desc: 'Multi-strategy portfolio backtest', promoted: true },
+        { name: 'portfolio-matrix', desc: 'Strategy-pair correlation matrix', promoted: true },
+        { name: 'cross-asset', desc: 'Cross-pair / cross-asset correlation research', promoted: true },
+        { name: 'feature-importance', desc: 'Permutation feature importance for a strategy', promoted: false },
+        { name: 'indicator-stats', desc: 'Indicator IC / decay statistics', promoted: false },
+        { name: 'signal-stats', desc: 'Signal hit rate, IC, decay', promoted: false },
+        { name: 'signal-decay', desc: 'Alpha-decay curve for a signal', promoted: false },
+        { name: 'signal-backfill', desc: 'Backfill signal scores over history', promoted: false },
+        { name: 'history', desc: 'Show backtest history', promoted: false },
+    ],
+    'Validation & promotion': [
+        { name: 'validate-strategy', desc: 'Lint a strategy file (SDK validator)', promoted: false },
+        { name: 'verify', desc: 'Verify strategy vs buy-and-hold over a date range', promoted: true },
+        { name: 'tearsheet', desc: 'Generate a strategy tearsheet (md)', promoted: false },
+        { name: 'audit', desc: 'Export compliance-grade audit trail (csv/json)', promoted: true },
+        { name: 'experiments', desc: 'List recent experiment runs', promoted: false },
+        { name: 'experiment-revert', desc: 'Revert a strategy to an earlier experiment snapshot', promoted: false },
+        { name: 'save-optimized', desc: 'Save a parameter-optimized strategy config', promoted: false },
+        { name: 'versions', desc: 'List strategy version history', promoted: false },
+    ],
+    'Workbench (strategy authoring)': [
+        { name: 'workbench-create', desc: 'Create a new workbench strategy', promoted: true },
+        { name: 'workbench-list', desc: 'List workbench strategies', promoted: false },
+        { name: 'workbench-show', desc: 'Show a workbench strategy', promoted: false },
+        { name: 'workbench-update', desc: 'Update workbench config', promoted: false },
+        { name: 'workbench-delete', desc: 'Delete a workbench strategy', promoted: false },
+        { name: 'workbench-generate', desc: 'Generate a strategy from a workbench config', promoted: false },
+        { name: 'workbench-templates', desc: 'List workbench templates', promoted: false },
+        { name: 'workbench-components', desc: 'List workbench signal components', promoted: false },
+    ],
+    'Data & discovery': [
+        { name: 'sync', desc: 'Sync HL S3 archive into local cache', promoted: true },
+        { name: 'fetch', desc: 'Fetch candles from HL REST API', promoted: false },
+        { name: 'fetch-multi', desc: 'Fetch multiple pairs', promoted: false },
+        { name: 'list-pairs', desc: 'List all HL trading pairs', promoted: false },
+        { name: 'list-data', desc: 'Inventory of cached data', promoted: false },
+        { name: 'data-inventory', desc: 'Detailed cache inventory + freshness', promoted: true },
+        { name: 'diff', desc: 'Diff two backtest runs', promoted: false },
+        { name: 'collect', desc: 'Start persistent data collector daemon', promoted: false },
+        { name: 'collect-status', desc: 'Collector daemon status', promoted: false },
+        { name: 'indicators', desc: 'Compute an indicator on cached data', promoted: false },
+        { name: 'funding-browser', desc: 'Browse funding-rate history across pairs', promoted: true },
+        { name: 'order-flow', desc: 'Inspect order-flow microstructure', promoted: false },
+        { name: 'regime', desc: 'Detect market regime (HMM / changepoints)', promoted: false },
+    ],
+    'Trading & execution': [
+        { name: 'algo', desc: 'Run an automated strategy', promoted: true },
+        { name: 'algo-status', desc: 'Algo session status', promoted: false },
+        { name: 'algo-stop', desc: 'Stop a running algo', promoted: false },
+        { name: 'recon', desc: 'Reconnaissance / dry-run trading', promoted: false },
+        { name: 'manual-trade', desc: 'Place a manual trade (engine-side)', promoted: false },
+        { name: 'test-trade', desc: 'Minimum-size test trade for connectivity', promoted: true },
+        { name: 'buy', desc: 'Direct buy order', promoted: false },
+        { name: 'sell', desc: 'Direct sell order', promoted: false },
+        { name: 'scan', desc: 'Scan multiple pairs for entry signals', promoted: false },
+        { name: 'scout', desc: 'Confluence-ranked opportunity scout', promoted: true },
+        { name: 'close-position', desc: 'Close a single position', promoted: false },
+        { name: 'close-all', desc: 'Close every open position', promoted: false },
+        { name: 'tighten-stop', desc: 'Move a stop loss closer to price', promoted: false },
+        { name: 'reduce-position', desc: 'Reduce position size', promoted: false },
+    ],
+    'Portfolio': [
+        { name: 'portfolio-start', desc: 'Launch portfolio supervisor + strategies', promoted: false },
+        { name: 'portfolio-status', desc: 'Portfolio runtime status', promoted: false },
+        { name: 'portfolio-stop', desc: 'Stop portfolio + all strategies', promoted: false },
+        { name: 'tca', desc: 'Transaction cost analysis on session log', promoted: false },
+        { name: 'attribution', desc: 'PnL attribution (alpha vs costs vs funding)', promoted: false },
+        { name: 'report', desc: 'Generate portfolio performance report', promoted: false },
+        { name: 'var', desc: 'Portfolio Value-at-Risk', promoted: false },
+        { name: 'pairs-backtest', desc: 'Pairs-trading portfolio backtest', promoted: true },
+    ],
+    'Account & wallet': [
+        { name: 'balance', desc: 'Show HL account balance', promoted: false },
+        { name: 'holdings', desc: 'Show open positions', promoted: false },
+        { name: 'state', desc: 'Full account state snapshot', promoted: false },
+        { name: 'transfer', desc: 'Transfer USDC between HL spot and perp', promoted: true },
+        { name: 'agent-pair', desc: 'Pair an API wallet to your main wallet', promoted: false },
+        { name: 'agent-rotate', desc: 'Rotate the API wallet', promoted: false },
+        { name: 'agent-status', desc: 'Show paired API wallet status', promoted: false },
+        { name: 'account-mode-status', desc: 'Show HL account mode (isolated/cross/etc.)', promoted: false },
+        { name: 'account-mode-set', desc: 'Set HL account mode', promoted: false },
+        { name: 'token-issue', desc: 'Issue an authorization token', promoted: false },
+        { name: 'token-list', desc: 'List authorization tokens', promoted: false },
+        { name: 'token-revoke', desc: 'Revoke an authorization token', promoted: false },
+        { name: 'token-show', desc: 'Show a specific token', promoted: false },
+    ],
+    'Learning & lessons': [
+        { name: 'lessons', desc: 'Show captured trading lessons', promoted: true },
+        { name: 'add-lesson', desc: 'Add a manual lesson entry', promoted: false },
+        { name: 'guide', desc: 'Interactive learning guide', promoted: true },
+    ],
+    'System & admin': [
+        { name: 'doctor', desc: 'System health check', promoted: true },
+        { name: 'health', desc: 'Lightweight health snapshot', promoted: false },
+        { name: 'version', desc: 'Show RIFT version', promoted: false },
+        { name: 'strategies', desc: 'List registered strategies', promoted: false },
+        { name: 'check-api', desc: 'Verify HL API reachability', promoted: false },
+        { name: 'set-proxy', desc: 'Configure HTTP proxy', promoted: false },
+        { name: 'clear-proxy', desc: 'Clear HTTP proxy setting', promoted: false },
+        { name: 'auth', desc: 'Wallet auth setup', promoted: true },
+        { name: 'approve-builder-fee', desc: 'On-chain builder-fee approval', promoted: false },
+        { name: 'check-builder-fee', desc: 'Verify builder-fee approval state', promoted: false },
+        { name: 'api-start', desc: 'Start the HTTP API server', promoted: false },
+        { name: 'api-stop', desc: 'Stop the HTTP API server', promoted: false },
+        { name: 'watchdog', desc: 'Start the kill-switch watchdog', promoted: false },
+        { name: 'watchdog-stop', desc: 'Stop the watchdog', promoted: false },
+        { name: 'watchdog-events', desc: 'Show recent watchdog events', promoted: false },
+        { name: 'cost', desc: 'Pre-trade cost estimate', promoted: true },
+    ],
+};
+export default class More extends GatedCommand {
+    static description = 'Discover and run every engine command — including those without a top-level `rift <cmd>` wrapper';
+    static examples = [
+        '$ rift more                          # list all engine commands by category',
+        '$ rift more funding-browser BTC      # run the funding-browser command',
+        '$ rift more verify <bundle-id>       # verify a sealed bundle',
+    ];
+    // Pure passthrough — `rift more` reads raw argv directly so unknown flags
+    // intended for the engine command (e.g. `--local-main-key`) aren't
+    // intercepted by oclif's flag parser. The first arg after `more` is the
+    // engine command name; everything else is forwarded verbatim.
+    static args = {
+        command: Args.string({ description: 'Engine command name (omit to list)' }),
+    };
+    static strict = false;
+    async run() {
+        // Bypass oclif's flag parser. process.argv is:
+        //   [node, run.js, "more", <engineCmd>, <...passthroughArgs>]
+        const rawArgs = process.argv.slice(3);
+        // No command → render the catalog.
+        if (rawArgs.length === 0) {
+            this.renderCatalog();
+            return;
+        }
+        const [command, ...passthrough] = rawArgs;
+        // Track whether the engine surfaced its own error message. If it did,
+        // we suppress the generic "Engine exited with code N" footer on
+        // non-zero exit — the user already saw the helpful message.
+        let surfacedError = false;
+        try {
+            await runEngine(command, passthrough, (msg) => {
+                // Mirror the engine's NDJSON to the user. For programmatic use,
+                // they can pipe `rift more <cmd> --json …`; here we just surface
+                // what the engine emits in human-readable form.
+                const type = msg.type;
+                if (type === 'progress' && msg.msg) {
+                    this.log(dim(`  ${msg.msg}`));
+                }
+                else if (type === 'status' && msg.msg) {
+                    this.log(`  ${msg.msg}`);
+                }
+                else if (type === 'error' && msg.msg) {
+                    // Log + flag, but do NOT call this.error() here — it throws
+                    // a CLIError synchronously inside an async readline callback,
+                    // which oclif's lifecycle does not catch reliably. We let the
+                    // engine's non-zero exit propagate via runEngine's rejection
+                    // path, and exit(1) silently from the catch below.
+                    this.log(`  ${red('Error:')} ${msg.msg}`);
+                    surfacedError = true;
+                }
+                else if (type === 'result') {
+                    // The engine emits a structured result — print as pretty JSON
+                    // so the user can pipe it or read it.
+                    const { type: _t, ...rest } = msg;
+                    this.log(JSON.stringify(rest, null, 2));
+                }
+                else if (msg.msg) {
+                    this.log(`  ${msg.msg}`);
+                }
+            });
+        }
+        catch (err) {
+            if (surfacedError) {
+                // The engine already printed a human-readable error above.
+                // Exit non-zero silently — no second confusing footer.
+                this.exit(1);
+            }
+            // Genuine engine crash with no structured error — re-raise via
+            // this.error so the user sees the stderr-extracted message.
+            throw err;
+        }
+    }
+    renderCatalog() {
+        this.log('');
+        this.log(`  ${bold('RIFT — Full engine command catalog')}`);
+        this.log(`  ${dim('─'.repeat(64))}`);
+        this.log('');
+        this.log(`  Commands marked ${green('●')} have a first-class ${cyan('rift <name>')} wrapper.`);
+        this.log(`  All others are runnable via ${cyan('rift more <name> [args...]')}.`);
+        this.log('');
+        let total = 0;
+        let promoted = 0;
+        for (const [section, entries] of Object.entries(CATALOG)) {
+            this.log(`  ${bold(section)}`);
+            const maxName = Math.max(...entries.map(e => e.name.length));
+            for (const e of entries) {
+                total++;
+                if (e.promoted)
+                    promoted++;
+                const marker = e.promoted ? green('●') : ' ';
+                const name = e.name.padEnd(maxName + 2);
+                this.log(`    ${marker} ${cyan(name)} ${dim(e.desc)}`);
+            }
+            this.log('');
+        }
+        this.log(`  ${dim(`${total} engine commands · ${promoted} promoted as rift <cmd>`)}`);
+        this.log('');
+    }
+}

package/dist/commands/new.d.ts

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

package/dist/commands/new.js

@@ -0,0 +1,306 @@
+import { Args, Flags } from '@oclif/core';
+import { GatedCommand } from '../lib/base-command.js';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { runEngine } from '../lib/python-bridge.js';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const bold = (s) => `\x1b[1m${s}\x1b[0m`;
+const green = (s) => `\x1b[32m${s}\x1b[0m`;
+const dim = (s) => `\x1b[2m${s}\x1b[0m`;
+/**
+ * Walk up from `start` to find the repo root. We identify the root by the
+ * presence of `pnpm-workspace.yaml` — this file only exists at the top of
+ * the monorepo. Walking up looking for `engine/pyproject.toml` (the prior
+ * heuristic) was buggy because `packages/engine/pyproject.toml` also exists
+ * and would match first, dropping scaffolded files into the wrong dir.
+ */
+function findRepoRoot(start) {
+    let dir = path.resolve(start);
+    for (let i = 0; i < 12; i++) {
+        if (fs.existsSync(path.join(dir, 'pnpm-workspace.yaml')))
+            return dir;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    // Fallback: cwd. Better than landing in the wrong subdirectory silently.
+    return path.resolve('.');
+}
+export default class New extends GatedCommand {
+    static description = 'Scaffold a new trading strategy or scout signal';
+    static examples = [
+        '$ rift new my-strategy',
+        '$ rift new bollinger-breakout',
+        '$ rift new my-momentum-signal --type signal',
+    ];
+    static args = {
+        name: Args.string({ description: 'Name (lowercase, hyphens ok)', required: true }),
+    };
+    static flags = {
+        type: Flags.string({
+            description: 'What to scaffold: "strategy" (default) or "signal"',
+            options: ['strategy', 'signal'],
+            default: 'strategy',
+        }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(New);
+        if (flags.type === 'signal') {
+            return this.scaffoldSignal(args.name);
+        }
+        return this.scaffoldStrategy(args.name);
+    }
+    // ── Strategy scaffold (existing behavior) ──────────────────────
+    async scaffoldStrategy(rawName) {
+        const name = rawName.toLowerCase().replace(/[^a-z0-9_-]/g, '_');
+        const className = name.split(/[-_]/).map(w => w.charAt(0).toUpperCase() + w.slice(1)).join('');
+        const configName = `${className}Config`;
+        // Find repo root via `pnpm-workspace.yaml` (only present at the root —
+        // walking up from packages/cli/dist/commands looking for engine/pyproject.toml
+        // would otherwise match packages/engine/pyproject.toml first).
+        const strategiesDir = path.join(findRepoRoot(__dirname), 'strategies');
+        fs.mkdirSync(strategiesDir, { recursive: true });
+        const stratDir = path.join(strategiesDir, name);
+        if (fs.existsSync(stratDir)) {
+            this.error(`Strategy "${name}" already exists at ${stratDir}`);
+        }
+        fs.mkdirSync(stratDir, { recursive: true });
+        // strategy.py
+        const strategyPy = `"""${className} strategy."""
+
+from dataclasses import dataclass
+
+from rift.strategy import EMA, RSI, Candle, Indicator, Signal, Strategy, StrategyState, register
+
+
+@dataclass(frozen=True)
+class ${configName}:
+    ema_period: int = 20
+    rsi_period: int = 14
+    entry_threshold: float = 30.0
+    exit_threshold: float = 70.0
+    leverage: float = 1.0
+    stop_loss_pct: float = 0.02
+
+
+@register("${name}")
+class ${className}(Strategy):
+    """${className} — describe your strategy here."""
+
+    config_class = ${configName}
+
+    def on_candle(self, candle: Candle, state: StrategyState) -> Signal | None:
+        ema = state.ema
+        rsi = state.rsi
+
+        if ema == 0 or rsi == 0:
+            return None
+
+        # Entry logic — customize this
+        if state.position == 0 and rsi < self.config.entry_threshold and candle.close > ema:
+            return Signal.long(size=self.position_size(), sl=self.config.stop_loss_pct)
+
+        # Exit logic — customize this
+        if state.position > 0 and rsi > self.config.exit_threshold:
+            return Signal.close()
+
+        return None
+
+    def indicators(self) -> dict[str, Indicator]:
+        return {
+            "ema": EMA(self.config.ema_period),
+            "rsi": RSI(self.config.rsi_period),
+        }
+`;
+        // config.yaml
+        const configYaml = `# ${className} default configuration
+strategy: ${name}
+
+params:
+  ema_period: 20
+  rsi_period: 14
+  entry_threshold: 30.0
+  exit_threshold: 70.0
+  leverage: 1.0
+  stop_loss_pct: 0.02
+`;
+        // sweep.yaml
+        const sweepYaml = `# Parameter sweep configuration for ${className}
+strategy: ${name}
+
+sweep:
+  ema_period: [10, 15, 20, 30, 50]
+  rsi_period: [7, 14, 21]
+  entry_threshold: [20.0, 25.0, 30.0, 35.0]
+  exit_threshold: [60.0, 65.0, 70.0, 75.0]
+  stop_loss_pct: [0.01, 0.02, 0.03]
+`;
+        // README.md
+        const readme = `# ${className}
+
+## Description
+Describe your strategy logic here.
+
+## Parameters
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| ema_period | 20 | EMA lookback period |
+| rsi_period | 14 | RSI lookback period |
+| entry_threshold | 30.0 | RSI level to enter |
+| exit_threshold | 70.0 | RSI level to exit |
+| leverage | 1.0 | Position leverage |
+| stop_loss_pct | 0.02 | Stop loss percentage |
+
+## Usage
+\`\`\`bash
+rift backtest ${name} --pair BTC --tf 1h
+rift compare ${name},trend_follow --pair BTC --tf 4h
+\`\`\`
+`;
+        fs.writeFileSync(path.join(stratDir, 'strategy.py'), strategyPy);
+        fs.writeFileSync(path.join(stratDir, 'config.yaml'), configYaml);
+        fs.writeFileSync(path.join(stratDir, 'sweep.yaml'), sweepYaml);
+        fs.writeFileSync(path.join(stratDir, 'README.md'), readme);
+        this.log('');
+        this.log(`  ${green('✔')} Strategy ${bold(name)} created at:`);
+        this.log('');
+        this.log(`    ${stratDir}/`);
+        this.log(`    ├── strategy.py     ${dim('— your strategy code')}`);
+        this.log(`    ├── config.yaml     ${dim('— default parameters')}`);
+        this.log(`    ├── sweep.yaml      ${dim('— parameter ranges for optimization')}`);
+        this.log(`    └── README.md       ${dim('— documentation')}`);
+        this.log('');
+        // Validate the scaffolded strategy
+        const strategyFile = path.join(stratDir, 'strategy.py');
+        this.log(`  ${dim('Validating...')}`);
+        try {
+            await runEngine('validate-strategy', [strategyFile], (msg) => {
+                if (msg.type === 'result') {
+                    if (msg.status === 'ok') {
+                        this.log(`  ${green('✔')} Strategy ${bold(String(msg.name))} registered with indicators: ${dim(String(msg.indicators.join(', ')))}`);
+                    }
+                    else if (msg.status === 'warn') {
+                        this.log(`  ${yellow('!')} Warning: ${msg.error || msg.errors.join(', ')}`);
+                    }
+                    else {
+                        this.log(`  ${red('✘')} ${msg.error}`);
+                    }
+                }
+            });
+        }
+        catch {
+            this.log(`  ${yellow('!')} Could not validate (Python engine issue). Strategy files are created.`);
+        }
+        this.log('');
+        this.log(`  ${dim('Next steps:')}`);
+        this.log(`    1. Edit ${bold('strategy.py')} with your trading logic`);
+        this.log(`    2. Run: ${cyan('rift backtest ' + name + ' --pair BTC --tf 1h')}`);
+        this.log(`    3. Optimize: ${cyan('rift sweep ' + name + ' --config sweep.yaml')}`);
+        this.log('');
+        function cyan(s) { return `\x1b[36m${s}\x1b[0m`; }
+        function yellow(s) { return `\x1b[33m${s}\x1b[0m`; }
+        function red(s) { return `\x1b[31m${s}\x1b[0m`; }
+    }
+    // ── Signal scaffold (Custom-signal SDK) ───────────────────────
+    async scaffoldSignal(rawName) {
+        const name = rawName.toLowerCase().replace(/[^a-z0-9_]/g, '_');
+        const signalsDir = path.join(findRepoRoot(__dirname), 'strategies', 'signals');
+        fs.mkdirSync(signalsDir, { recursive: true });
+        const signalFile = path.join(signalsDir, `${name}.py`);
+        if (fs.existsSync(signalFile)) {
+            this.error(`Signal "${name}" already exists at ${signalFile}`);
+        }
+        const cyan = (s) => `\x1b[36m${s}\x1b[0m`;
+        // Signal scaffolds are intentionally single-file (no config.yaml, no
+        // sweep.yaml). The signal IS the unit; users register one per file
+        // and the file's @signal(...) decorator is the entire surface.
+        const signalPy = `"""${name} — custom scout signal.
+
+Register with @signal(...). \`rift scout\` discovers this file automatically
+from strategies/signals/ (and ~/.rift/signals/) at scan time.
+
+See docs/signals/AUTHORING.md for the full guide.
+"""
+
+from __future__ import annotations
+
+from rift_strategies_sdk import signal, SignalResult
+
+
+@signal(
+    name="${name}",
+    category="momentum",  # one of: funding, momentum, microstructure,
+                          # volatility, cross_pair, seasonality
+    description="${name} — describe what this signal detects",
+    weight=1.0,           # higher = more influence in aggregation
+)
+def ${name}(coin: str, state: dict) -> SignalResult:
+    """Return a SignalResult with score in [-1, +1].
+
+    Args:
+        coin: ticker symbol, e.g. "BTC"
+        state: dict of available market state. Common keys:
+          - mid_price, funding_rate, predicted_funding, open_interest
+          - oracle_price, premium, atr_pct, day_volume
+          - cvd, volume_delta, relative_volume
+          - candles_1h, candles_5m (lists of {o,h,l,c,v,t})
+          - indicators (dict of pre-computed indicator values)
+
+    Returns:
+        SignalResult with score=+1 (strong long), 0 (no opinion),
+        or -1 (strong short). Score=0 is silently dropped by the
+        aggregator, so always return a meaningful score when fired.
+    """
+    # ──────────────────────────────────────────────────────────────
+    # Replace this with your detection logic.
+    #
+    # Example: extreme funding rate as a contrarian signal.
+    # ──────────────────────────────────────────────────────────────
+    funding = float(state.get("funding_rate") or 0.0)
+
+    # Extreme positive funding → over-leveraged longs → fade
+    if funding > 0.0005:
+        return SignalResult(
+            name="${name}",
+            score=-0.5,
+            reason=f"Extreme positive funding {funding * 100:.3f}% — fade longs",
+            category="momentum",
+            confidence=0.6,
+        )
+
+    # Extreme negative funding → over-leveraged shorts → fade
+    if funding < -0.0005:
+        return SignalResult(
+            name="${name}",
+            score=+0.5,
+            reason=f"Extreme negative funding {funding * 100:.3f}% — fade shorts",
+            category="momentum",
+            confidence=0.6,
+        )
+
+    return SignalResult(
+        name="${name}",
+        score=0.0,
+        reason="Funding within normal range",
+        category="momentum",
+        confidence=0.0,
+    )
+`;
+        fs.writeFileSync(signalFile, signalPy);
+        this.log('');
+        this.log(`  \x1b[32m✔\x1b[0m Signal ${bold(name)} created at:`);
+        this.log('');
+        this.log(`    ${signalFile}`);
+        this.log('');
+        this.log(`  ${dim('Next steps:')}`);
+        this.log(`    1. Edit ${bold(name + '.py')} with your detection logic`);
+        this.log(`    2. Run: ${cyan('rift scout --top 5 --min 1 --no-soak')} (your signal fires alongside the 9 built-ins)`);
+        this.log(`    3. Use ${cyan('rift signal-stats')} to see how often it fires`);
+        this.log('');
+        this.log(`  ${dim('Place user-only signals at ~/.rift/signals/<name>.py (not committed to the repo).')}`);
+        this.log('');
+    }
+}

package/dist/commands/pairs.d.ts

@@ -0,0 +1,22 @@
+import { GatedCommand } from '../lib/base-command.js';
+export default class Pairs extends GatedCommand {
+    static description: string;
+    static aliases: string[];
+    static examples: string[];
+    static flags: {
+        a: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        b: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        tf: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        equity: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+        lookback: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+        'entry-z': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        'exit-z': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        'stop-z': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        'max-hold': import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+        json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+    private renderResult;
+    private row;
+    private rowColored;
+}