pandora-cli-skills 1.1.59 → 1.1.62

package/README.md

@@ -46,6 +46,11 @@ pandora --output json trade --dry-run \
   --market-address 0x... --side yes --amount-usdc 10 \
   --fork --fork-rpc-url http://127.0.0.1:8545
 
+# Dry-run a sell quote / exit path
+pandora --output json sell --dry-run \
+  --market-address 0x... --side no --shares 25 \
+  --fork --fork-rpc-url http://127.0.0.1:8545
+
 # NDJSON stream
 pandora stream prices --indexer-url https://pandoraindexer.up.railway.app/ --interval-ms 1000
 ```
@@ -73,16 +78,6 @@ pandora --output json lifecycle status --id <lifecycle-id>
 pandora --output json lifecycle resolve --id <lifecycle-id> --confirm
 ```
 
-### Mega Analytics Page (Dune Panels)
-
-```bash
-# starts local page at http://127.0.0.1:8787
-npm run analytics:mega
-```
-
-- Panel registry source: `analytics/dune/panel_registry.json`
-- Dashboard creation script reuses this registry: `scripts/create_pandora_dashboard.js`
-
 ## Risk Controls
 
 - Inspect/engage panic lock:
@@ -115,6 +110,9 @@ npm run analytics:mega
 ## Command Surface
 
 - `pandora markets list|get`
+- `pandora scan`
+  - `scan` is the canonical enriched discovery workflow.
+  - `markets scan` remains a backward-compatible alias.
 - `pandora sports books list`
 - `pandora sports events list|live`
 - `pandora sports odds snapshot|bulk`
@@ -125,11 +123,14 @@ npm run analytics:mega
 - `pandora lifecycle start|status|resolve`
 - `pandora quote`
 - `pandora trade`
+- `pandora sell`
 - `pandora claim --market-address <address>|--all --dry-run|--execute`
 - `pandora history`
 - `pandora export`
+- `pandora arb scan --output ndjson|json`
 - `pandora arbitrage`
-- `pandora arb scan --output ndjson`
+  - `arb scan` is the canonical arbitrage workflow.
+  - `arbitrage` remains a bounded one-shot compatibility wrapper.
 - `pandora odds record|history`
 - `pandora autopilot run|once`
 - `pandora mirror browse|plan|deploy|verify|lp-explain|hedge-calc|simulate|go|sync|status|close`

package/README_FOR_SHARING.md

@@ -101,6 +101,7 @@ Prerequisite: Node.js `>=18`.
 - Read-only indexer commands (GraphQL-backed):
   - `pandora markets list|get`
   - `pandora scan`
+    - `scan` is the canonical enriched discovery flow; `markets scan` remains an alias.
   - `pandora quote`
   - `pandora portfolio`
   - `pandora watch`
@@ -117,8 +118,10 @@ Prerequisite: Node.js `>=18`.
 - `pandora stream events` (reactive event feed in NDJSON)
 - Phase 2 trading helpers:
   - `pandora quote --market-address <0x...> --side yes|no --amount-usdc <amount>`
+  - `pandora quote --market-address <0x...> --side yes|no --mode sell --shares <amount>`
   - `pandora trade --dry-run --market-address <0x...> --side yes|no --amount-usdc <amount> [--max-amount-usdc <amount>] [--min-probability-pct <0-100>] [--max-probability-pct <0-100>]`
   - `pandora trade --execute ...` performs allowance check, conditional USDC approve, then `buy`.
+  - `pandora sell --dry-run|--execute --market-address <0x...> --side yes|no --shares <amount> [--min-amount-out-raw <uint>]`
 - Phase 3 wallet analytics:
   - `pandora portfolio --wallet <0x...> [--chain-id <id>] [--limit <n>] [--include-events|--no-events]`
   - `pandora watch --wallet <0x...> --iterations 10 --interval-ms 5000`
@@ -126,6 +129,7 @@ Prerequisite: Node.js `>=18`.
 - Phase 4 intelligence and automation:
   - `pandora history --wallet <0x...> --limit 50`
   - `pandora export --wallet <0x...> --format csv --year 2026 --out ./trades-2026.csv`
+  - `pandora arb scan --source polymarket --output json --iterations 1 --min-spread-pct 3`
   - `pandora arbitrage --venues pandora,polymarket --min-spread-pct 3`
   - `pandora autopilot run|once ...`
   - `pandora mirror browse|plan|deploy|verify|lp-explain|hedge-calc|simulate|go|sync|status|close ...`
@@ -179,6 +183,7 @@ Prerequisite: Node.js `>=18`.
 ### Fork runtime support
 - Supported families:
   - `trade`
+  - `sell`
   - `resolve`
   - `claim`
   - `lp`
@@ -201,6 +206,9 @@ Prerequisite: Node.js `>=18`.
 Mirror advanced flags (for operator tuning):
 - `--sync-interval-ms <ms>` on `mirror go` to control auto-sync tick cadence.
 - `--oracle <address>` / `--factory <address>` on `mirror deploy` and `mirror go` for explicit contract overrides.
+- `--rules "<text>"` on `mirror deploy` for direct rules override without a plan file.
+- `--distribution-yes-pct <0-100>` / `--distribution-no-pct <0-100>` on `mirror deploy|go` as percentage alternatives to raw 1e9 part hints.
+- `--max-imbalance <n>` now accepts the full uint24 range, including `0` for "no guard".
 - `--polymarket-gamma-mock-url <url>` on `mirror browse|plan|verify|go|sync|status` for deterministic mock-source testing.
 - `--polymarket-tag-id <id>` / `--polymarket-tag-ids <csv>` on `mirror browse` (aliases: `--sport-tag-id`, `--sport-tag-ids`) to query sports-tagged Gamma events.
 - `--no-stream` on `mirror sync` to disable per-tick stdout line streaming in run mode.
@@ -220,6 +228,7 @@ Mirror advanced flags (for operator tuning):
 - `pandora watch --wallet <0x...> --iterations 3 --interval-ms 1000 --alert-net-liquidity-below -100`
 - `pandora history --wallet <0x...> --limit 50`
 - `pandora export --wallet <0x...> --format csv --out ./trades.csv`
+- `pandora arb scan --source polymarket --output json --iterations 1 --min-spread-pct 2 --min-tvl 50`
 - `pandora arbitrage --venues pandora,polymarket --min-spread-pct 2 --cross-venue-only --with-rules --include-similarity`
 - `pandora autopilot once --market-address <0x...> --side no --amount-usdc 10 --trigger-yes-below 15 --paper`
 - `pandora mirror browse --polymarket-tag-id 82 --min-yes-pct 20 --max-yes-pct 80 --min-volume-24h 100000 --limit 10`
@@ -258,19 +267,23 @@ Mirror advanced flags (for operator tuning):
 
 ## Phase 2 JSON contracts
 - `quote`:
-  - envelope is `ok=true`, `command="quote"`, with `data.marketAddress`, `data.side`, `data.amountUsdc`, `data.odds`, `data.quoteAvailable`, and `data.estimate` (or `null` when unavailable).
+  - envelope is `ok=true`, `command="quote"`, with `data.marketAddress`, `data.side`, `data.mode`, either `data.amountUsdc` (buy) or `data.amount` (sell), plus `data.odds`, `data.quoteAvailable`, and `data.estimate` (or `null` when unavailable).
 - `trade --dry-run`:
   - envelope is `ok=true`, `command="trade"`, with `data.mode="dry-run"`, `data.quote`, `data.selectedProbabilityPct`, `data.riskGuards`, and `data.executionPlan.steps`.
 - `trade --execute`:
   - envelope is `ok=true`, `command="trade"`, with tx metadata (`approveTxHash` optional, `buyTxHash` required on success) plus `selectedProbabilityPct` and `riskGuards`.
+- `sell --dry-run|--execute`:
+  - envelope is `ok=true`, `command="sell"`, with `data.action="sell"`, sell-aware quote/tx metadata, and `minAmountOutRaw` instead of buy-side minimum-share semantics.
 
 ## Phase 2 limitations
 - `trade` auto-detects market type and uses the correct buy signature:
   - PariMutuel: `buy(bool,uint256,uint256)`
   - AMM: `buy(bool,uint256,uint256,uint256)` (deadline-aware)
+- `sell` is AMM-only and uses `sell(bool,uint112,uint256,uint256)`.
 - `minSharesOut` protection defaults to raw `0` unless explicitly set with `--min-shares-out-raw`.
 - If indexer odds are unavailable, `quote` still returns a structured payload with `quoteAvailable=false`.
 - `trade --execute` blocks unquoted execution by default unless `--min-shares-out-raw` or `--allow-unquoted-execute` is provided.
+- `sell --execute` blocks unquoted execution by default unless `--min-amount-out-raw` or `--allow-unquoted-execute` is provided.
 
 ## Phase 3 JSON contracts
 - `portfolio`:
@@ -295,6 +308,7 @@ Mirror advanced flags (for operator tuning):
   - envelope is `ok=true`, `command="export"`, with `data.format`, `data.columns`, `data.count`, optional `data.outPath`, and materialized `data.content`.
 - `arbitrage`:
   - envelope is `ok=true`, `command="arbitrage"`, with `data.parameters`, `data.sources`, and `data.opportunities[]`.
+  - use `arb scan` as the canonical arbitrage interface; `arbitrage` is the compatibility one-shot wrapper.
   - agent-focused flags:
     - `--cross-venue-only` (default) prevents same-venue duplicate-market noise.
     - `--allow-same-venue` re-enables same-venue matching.

package/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: pandora-cli-skills
 summary: Canonical skill and operator guide for Pandora CLI including mirror, polymarket, resolve, and LP flows.
-version: 1.1.59
+version: 1.1.62
 ---
 
 # Pandora CLI & Skills
@@ -40,10 +40,13 @@ npm link
 - `--output json` is supported for all commands except `launch`/`clone-bet`; those stream script output directly.
 - Agent schema command: `pandora --output json schema`
 - MCP server mode: `pandora mcp`
+- Agent market prompt tools:
+  - `pandora --output json agent market autocomplete --question "<text>" [--market-type amm|parimutuel]`
+  - `pandora --output json agent market validate --question "<text>" --rules "<text>" --target-timestamp <unix-seconds> [--sources <url...>]`
 - Guided setup command: `pandora setup`
 - Phase 1 discovery command: `pandora scan`
 - Phase 1 lifecycle filters: `pandora markets list --active|--resolved|--expiring-soon`
-- Phase 2 trading commands: `pandora quote`, `pandora trade`
+- Phase 2 trading commands: `pandora quote`, `pandora trade`, `pandora sell`
 - Phase 2 risk guardrails: `--max-amount-usdc`, `--min-probability-pct`, `--max-probability-pct`
 - Phase 3 analytics command: `pandora portfolio`
 - Phase 3 monitoring command: `pandora watch`
@@ -52,6 +55,7 @@ npm link
 - Phase 4 commands:
   - `pandora history`
   - `pandora export`
+  - `pandora arb scan`
   - `pandora arbitrage`
   - `pandora autopilot run|once`
   - `pandora mirror browse|plan|deploy|verify|lp-explain|hedge-calc|simulate|go|sync|status|close`
@@ -72,6 +76,10 @@ npm link
   - `--fork-chain-id <id>`
 - JSON errors can include additive recovery hints:
   - `error.recovery = { action, command, retryable }`
+- Agent/MCP market creation policy:
+  - Agent-drafted manual markets should start with `agent market autocomplete` when rules, sources, or timing still need to be generated/refined.
+  - Execute/live MCP calls for `sports create run`, `mirror deploy`, and `mirror go` require a PASS attestation from `agent market validate`.
+  - Dry-run outputs for those flows include the exact validation ticket that must be echoed back via `agentPreflight` on the execute call.
 - Doctor checks:
   - env presence + format validation
   - RPC reachability and chain id match
@@ -83,6 +91,15 @@ npm link
 - Current risk-counter semantics:
   - `max_position_usd` guards per-operation notional.
   - `max_daily_loss_usd` is enforced as daily live notional (`counters.liveNotionalUsdc`).
+
+## Canonical command paths
+- Market discovery:
+  - `pandora scan` is the canonical enriched discovery flow.
+  - `pandora markets scan` remains a backward-compatible alias.
+  - `pandora markets list` is the raw indexer browse surface.
+- Arbitrage:
+  - `pandora arb scan` is the canonical arbitrage flow for bounded JSON or streaming NDJSON scans.
+  - `pandora arbitrage` remains a backward-compatible one-shot wrapper over the same cross-venue engine.
   - `max_open_markets` is enforced as daily live operation count (`counters.liveOps`).
 
 ## Quant ABM baseline (module contract)
@@ -132,11 +149,14 @@ pandora [--output table|json] positions list [--wallet <address>] [--market-addr
 pandora [--output table|json] portfolio --wallet <address> [--chain-id <id>] [--limit <n>] [--include-events|--no-events] [--with-lp] [--rpc-url <url>]
 pandora [--output table|json] watch [--wallet <address>] [--market-address <address>] [--side yes|no] [--amount-usdc <amount>] [--iterations <n>] [--interval-ms <ms>] [--chain-id <id>] [--include-events|--no-events] [--yes-pct <0-100>] [--alert-yes-below <0-100>] [--alert-yes-above <0-100>] [--alert-net-liquidity-below <amount>] [--alert-net-liquidity-above <amount>] [--fail-on-alert] [--track-brier] [--brier-source <name>] [--brier-file <path>] [--group-by source|market|competition]
 pandora [--output table|json] scan [--limit <n>] [--after <cursor>] [--before <cursor>] [--order-by <field>] [--order-direction asc|desc] [--chain-id <id>] [--creator <address>] [--poll-address <address>] [--market-type <type>] [--where-json <json>] [--active|--resolved|--expiring-soon] [--expiring-hours <n>] [--expand]
-pandora [--output table|json] quote [--indexer-url <url>] [--timeout-ms <ms>] --market-address <address> --side yes|no --amount-usdc <amount> [--yes-pct <0-100>] [--slippage-bps <0-10000>]
+pandora [--output table|json] markets scan [scan flags]  # backward-compatible alias of scan
+pandora [--output table|json] quote [--indexer-url <url>] [--timeout-ms <ms>] --market-address <address> --side yes|no [--mode buy|sell] --amount-usdc <amount>|--shares <amount>|--amounts <csv> [--yes-pct <0-100>] [--slippage-bps <0-10000>]
 pandora [--output table|json] trade [--indexer-url <url>] [--timeout-ms <ms>] [--dotenv-path <path>] [--skip-dotenv] --market-address <address> --side yes|no --amount-usdc <amount> --dry-run|--execute [--yes-pct <0-100>] [--slippage-bps <0-10000>] [--min-shares-out-raw <uint>] [--max-amount-usdc <amount>] [--min-probability-pct <0-100>] [--max-probability-pct <0-100>] [--allow-unquoted-execute] [--fork] [--fork-rpc-url <url>] [--fork-chain-id <id>] [--chain-id <id>] [--rpc-url <url>] [--private-key <hex>] [--usdc <address>]
+pandora [--output table|json] sell [--indexer-url <url>] [--timeout-ms <ms>] [--dotenv-path <path>] [--skip-dotenv] --market-address <address> --side yes|no --shares <amount>|--amount <amount> --dry-run|--execute [--yes-pct <0-100>] [--slippage-bps <0-10000>] [--min-amount-out-raw <uint>] [--allow-unquoted-execute] [--fork] [--fork-rpc-url <url>] [--fork-chain-id <id>] [--chain-id <id>] [--rpc-url <url>] [--private-key <hex>] [--usdc <address>]
 pandora [--output table|json] claim [--dotenv-path <path>] [--skip-dotenv] --market-address <address>|--all [--wallet <address>] --dry-run|--execute [--fork] [--fork-rpc-url <url>] [--fork-chain-id <id>] [--chain-id <id>] [--rpc-url <url>] [--private-key <hex>] [--indexer-url <url>] [--timeout-ms <ms>]
 pandora [--output table|json] history --wallet <address> [--chain-id <id>] [--market-address <address>] [--side yes|no|both] [--status all|open|won|lost|closed] [--limit <n>] [--after <cursor>] [--before <cursor>] [--order-by timestamp|pnl|entry-price|mark-price] [--order-direction asc|desc] [--include-seed]
 pandora [--output table|json] export --wallet <address> --format csv|json [--chain-id <id>] [--year <yyyy>] [--from <unix>] [--to <unix>] [--out <path>]
+pandora arb scan [--source pandora|polymarket] [--markets <csv>] --output ndjson|json [--min-net-spread-pct <n>] [--fee-pct-per-leg <n>] [--slippage-pct-per-leg <n>] [--amount-usdc <n>] [--combinatorial] [--max-bundle-size <n>] [--iterations <n>] [--interval-ms <ms>]
 pandora [--output table|json] arbitrage [--chain-id <id>] [--venues pandora,polymarket] [--limit <n>] [--min-spread-pct <n>] [--min-liquidity-usdc <n>] [--max-close-diff-hours <n>] [--similarity-threshold <0-1>] [--cross-venue-only|--allow-same-venue] [--with-rules] [--include-similarity] [--question-contains <text>] [--polymarket-host <url>] [--polymarket-mock-url <url>]
 pandora [--output table|json] autopilot run|once --market-address <address> --side yes|no --amount-usdc <amount> [--trigger-yes-below <0-100>] [--trigger-yes-above <0-100>] [--paper|--execute-live] [--interval-ms <ms>] [--cooldown-ms <ms>] [--max-amount-usdc <amount>] [--max-open-exposure-usdc <amount>] [--max-trades-per-day <n>] [--state-file <path>] [--kill-switch-file <path>] [--webhook-url <url>] [--telegram-bot-token <token>] [--telegram-chat-id <id>] [--discord-webhook-url <url>]
 pandora [--output table|json] mirror browse|plan|deploy|verify|lp-explain|hedge-calc|simulate|go|sync|status|close ...
@@ -162,12 +182,12 @@ Mirror subcommand detail:
 ```text
 browse --min-yes-pct <n> --max-yes-pct <n> --min-volume-24h <n> [--closes-after <date>] [--closes-before <date>] [--question-contains <text>] [--limit <n>] [--chain-id <id>] [--polymarket-gamma-url <url>] [--polymarket-gamma-mock-url <url>] [--polymarket-mock-url <url>]
 plan   --source polymarket --polymarket-market-id <id>|--polymarket-slug <slug> [--chain-id <id>] [--target-slippage-bps <n>] [--turnover-target <n>] [--depth-slippage-bps <n>] [--safety-multiplier <n>] [--min-liquidity-usdc <n>] [--max-liquidity-usdc <n>] [--with-rules] [--include-similarity] [--polymarket-gamma-url <url>] [--polymarket-gamma-mock-url <url>] [--polymarket-mock-url <url>]
-deploy --plan-file <path>|--polymarket-market-id <id>|--polymarket-slug <slug> --dry-run|--execute [--liquidity-usdc <n>] [--fee-tier <500-50000>] [--max-imbalance <n>] [--arbiter <address>] [--category <n>] [--chain-id <id>] [--rpc-url <url>] [--private-key <hex>] [--oracle <address>] [--factory <address>] [--usdc <address>] [--distribution-yes <parts>] [--distribution-no <parts>] [--sources <url...>] [--min-close-lead-seconds <n>] [--manifest-file <path>] [--polymarket-host <url>] [--polymarket-gamma-url <url>] [--polymarket-gamma-mock-url <url>] [--polymarket-mock-url <url>]
+deploy --plan-file <path>|--polymarket-market-id <id>|--polymarket-slug <slug> --dry-run|--execute [--liquidity-usdc <n>] [--fee-tier <500-50000>] [--max-imbalance <n>] [--arbiter <address>] [--category <n>] [--chain-id <id>] [--rpc-url <url>] [--private-key <hex>] [--oracle <address>] [--factory <address>] [--usdc <address>] [--distribution-yes <parts>] [--distribution-no <parts>] [--distribution-yes-pct <0-100>] [--distribution-no-pct <0-100>] [--rules <text>] [--sources <url...>] [--min-close-lead-seconds <n>] [--manifest-file <path>] [--polymarket-host <url>] [--polymarket-gamma-url <url>] [--polymarket-gamma-mock-url <url>] [--polymarket-mock-url <url>]
 verify --pandora-market-address <address>|--market-address <address> --polymarket-market-id <id>|--polymarket-slug <slug> [--trust-deploy] [--manifest-file <path>] [--include-similarity] [--with-rules] [--allow-rule-mismatch] [--polymarket-host <url>] [--polymarket-gamma-url <url>] [--polymarket-gamma-mock-url <url>] [--polymarket-mock-url <url>]
 lp-explain --liquidity-usdc <n> [--source-yes-pct <0-100>] [--distribution-yes <parts>] [--distribution-no <parts>]
 hedge-calc [--reserve-yes-usdc <n> --reserve-no-usdc <n>] [--excess-yes-usdc <n>] [--excess-no-usdc <n>] [--polymarket-yes-pct <0-100>] [--hedge-ratio <n>] [--hedge-cost-bps <n>] [--volume-scenarios <csv>] [--pandora-market-address <address>|--market-address <address> --polymarket-market-id <id>|--polymarket-slug <slug>] [--trust-deploy] [--manifest-file <path>]
 simulate --liquidity-usdc <n> [--source-yes-pct <0-100>] [--target-yes-pct <0-100>] [--distribution-yes <parts>] [--distribution-no <parts>] [--fee-tier <500-50000>] [--volume-scenarios <csv>] [--hedge-ratio <n>] [--hedge-cost-bps <n>] [--polymarket-yes-pct <0-100>]
-go     --polymarket-market-id <id>|--polymarket-slug <slug> [--liquidity-usdc <n>] [--fee-tier <500-50000>] [--max-imbalance <n>] [--arbiter <address>] [--category <n>] [--paper|--dry-run|--execute-live|--execute] [--auto-sync] [--sync-once] [--sync-interval-ms <ms>] [--hedge-ratio <n>] [--no-hedge] [--max-rebalance-usdc <n>] [--max-hedge-usdc <n>] [--max-open-exposure-usdc <n>] [--max-trades-per-day <n>] [--cooldown-ms <ms>] [--chain-id <id>] [--rpc-url <url>] [--private-key <hex>] [--funder <address>] [--usdc <address>] [--oracle <address>] [--factory <address>] [--sources <url...>] [--manifest-file <path>] [--trust-deploy] [--skip-gate] [--polymarket-host <url>] [--polymarket-gamma-url <url>] [--polymarket-gamma-mock-url <url>] [--polymarket-mock-url <url>] [--with-rules] [--include-similarity] [--min-close-lead-seconds <n>]
+go     --polymarket-market-id <id>|--polymarket-slug <slug> [--liquidity-usdc <n>] [--fee-tier <500-50000>] [--max-imbalance <n>] [--arbiter <address>] [--category <n>] [--paper|--dry-run|--execute-live|--execute] [--auto-sync] [--sync-once] [--sync-interval-ms <ms>] [--hedge-ratio <n>] [--no-hedge] [--max-rebalance-usdc <n>] [--max-hedge-usdc <n>] [--max-open-exposure-usdc <n>] [--max-trades-per-day <n>] [--cooldown-ms <ms>] [--chain-id <id>] [--rpc-url <url>] [--private-key <hex>] [--funder <address>] [--usdc <address>] [--oracle <address>] [--factory <address>] [--distribution-yes-pct <0-100>] [--distribution-no-pct <0-100>] [--sources <url...>] [--manifest-file <path>] [--trust-deploy] [--skip-gate] [--polymarket-host <url>] [--polymarket-gamma-url <url>] [--polymarket-gamma-mock-url <url>] [--polymarket-mock-url <url>] [--with-rules] [--include-similarity] [--min-close-lead-seconds <n>]
 sync run|once|start --pandora-market-address <address>|--market-address <address> --polymarket-market-id <id>|--polymarket-slug <slug> [--paper|--dry-run|--execute-live|--execute] [--private-key <hex>] [--funder <address>] [--usdc <address>] [--trust-deploy] [--manifest-file <path>] [--skip-gate] [--daemon] [--stream|--no-stream] [--interval-ms <ms>] [--drift-trigger-bps <n>] [--hedge-trigger-usdc <n>] [--hedge-ratio <n>] [--no-hedge] [--max-rebalance-usdc <n>] [--max-hedge-usdc <n>] [--max-open-exposure-usdc <n>] [--max-trades-per-day <n>] [--cooldown-ms <ms>] [--depth-slippage-bps <n>] [--min-time-to-close-sec <n>] [--iterations <n>] [--state-file <path>] [--kill-switch-file <path>] [--chain-id <id>] [--rpc-url <url>] [--polymarket-host <url>] [--polymarket-gamma-url <url>] [--polymarket-gamma-mock-url <url>] [--polymarket-mock-url <url>] [--webhook-url <url>] [--telegram-bot-token <token>] [--telegram-chat-id <id>] [--discord-webhook-url <url>]
 status --state-file <path>|--strategy-hash <hash> [--with-live] [--pandora-market-address <address>|--market-address <address>] [--polymarket-market-id <id>|--polymarket-slug <slug>]
 close  --pandora-market-address <address>|--market-address <address> --polymarket-market-id <id>|--polymarket-slug <slug>|--all --dry-run|--execute [--wallet <address>] [--chain-id <id>] [--rpc-url <url>] [--private-key <hex>] [--indexer-url <url>] [--timeout-ms <ms>]
@@ -354,19 +374,23 @@ pandora --output json schema
 
 ## Phase 2 JSON contracts
 - `quote`:
-  - envelope is `ok=true`, `command="quote"`, with `data.marketAddress`, `data.side`, `data.amountUsdc`, `data.odds`, `data.quoteAvailable`, and `data.estimate` (or `null`).
+  - envelope is `ok=true`, `command="quote"`, with `data.marketAddress`, `data.side`, `data.mode`, either `data.amountUsdc` (buy) or `data.amount` (sell), plus `data.odds`, `data.quoteAvailable`, and `data.estimate` (or `null`).
 - `trade --dry-run`:
   - envelope is `ok=true`, `command="trade"`, with `data.mode="dry-run"`, `data.quote`, `data.selectedProbabilityPct`, `data.riskGuards`, and `data.executionPlan.steps`.
 - `trade --execute`:
   - envelope is `ok=true`, `command="trade"`, with tx metadata (`approveTxHash` optional, `buyTxHash` required on success) plus `selectedProbabilityPct` and `riskGuards`.
+- `sell --dry-run|--execute`:
+  - envelope is `ok=true`, `command="sell"`, with `data.action="sell"`, sell-aware quote/tx metadata, and `minAmountOutRaw` instead of buy-side minimum-share semantics.
 
 ## Phase 2 limitations
 - `trade` auto-detects market type and uses the correct buy signature:
   - PariMutuel: `buy(bool,uint256,uint256)`
   - AMM: `buy(bool,uint256,uint256,uint256)` (deadline-aware)
+- `sell` is AMM-only and uses `sell(bool,uint112,uint256,uint256)`.
 - `--min-shares-out-raw` is the explicit slippage guard input for on-chain execution.
 - If indexer odds are unavailable, `quote` still returns structured output with `quoteAvailable=false`.
 - `trade --execute` blocks unquoted execution by default unless `--min-shares-out-raw` or `--allow-unquoted-execute` is provided.
+- `sell --execute` blocks unquoted execution by default unless `--min-amount-out-raw` or `--allow-unquoted-execute` is provided.
 
 ## Phase 3 JSON contracts
 - `portfolio`:
@@ -467,7 +491,7 @@ Mode aliases:
 Common compatibility aliases:
 - `--env-file` = `--dotenv-path`
 - `--no-env-file` = `--skip-dotenv`
-- `--amount` = `--amount-usdc` (trade/watch/autopilot paths)
+- `--amount` = `--amount-usdc` on buy-side trade/watch/autopilot paths, and share input on `sell`.
 - `--market-id` = `--condition-id` (polymarket trade)
 - `--force-gate` = `--skip-gate` (deprecated; use `--skip-gate`)
 
@@ -475,6 +499,7 @@ Common compatibility aliases:
 - Distribution inputs use parts-per-billion (ppb):
   - `--distribution-yes 580000000` means YES seed weight = `58%`.
   - `--distribution-no 420000000` means NO seed weight = `42%`.
+  - `--distribution-yes-pct 58 --distribution-no-pct 42` is the percentage alias form on supported deploy/create paths.
   - Constraint: `distributionYes + distributionNo = 1_000_000_000`.
 
 ## Error code guide

package/cli/lib/agent_command_service.cjs

@@ -0,0 +1,222 @@
+const {
+  buildAgentMarketAutocompletePayload,
+  buildAgentMarketValidationPayload,
+} = require('./agent_market_prompt_service.cjs');
+
+function requireDep(deps, name) {
+  if (!deps || typeof deps[name] !== 'function') {
+    throw new Error(`createRunAgentCommand requires deps.${name}()`);
+  }
+  return deps[name];
+}
+
+function readFlagValue(args, index, flagName) {
+  const value = args[index + 1];
+  if (typeof value !== 'string' || value.startsWith('--')) {
+    const error = new Error(`${flagName} requires a value.`);
+    error.code = 'MISSING_FLAG_VALUE';
+    throw error;
+  }
+  return value;
+}
+
+function parseAgentMarketAutocompleteFlags(args) {
+  const options = {
+    question: '',
+    marketType: 'amm',
+  };
+
+  for (let i = 0; i < args.length; i += 1) {
+    const token = args[i];
+    if (token === '--question') {
+      options.question = readFlagValue(args, i, '--question');
+      i += 1;
+      continue;
+    }
+    if (token === '--market-type') {
+      options.marketType = readFlagValue(args, i, '--market-type');
+      i += 1;
+      continue;
+    }
+    const error = new Error(`Unknown flag for agent market autocomplete: ${token}`);
+    error.code = 'UNKNOWN_FLAG';
+    throw error;
+  }
+
+  if (!String(options.question || '').trim()) {
+    const error = new Error('agent market autocomplete requires --question <text>.');
+    error.code = 'MISSING_REQUIRED_FLAG';
+    throw error;
+  }
+
+  return options;
+}
+
+function parseAgentMarketValidateFlags(args) {
+  const options = {
+    question: '',
+    rules: '',
+    sources: [],
+    targetTimestamp: 0,
+  };
+
+  for (let i = 0; i < args.length; i += 1) {
+    const token = args[i];
+    if (token === '--question') {
+      options.question = readFlagValue(args, i, '--question');
+      i += 1;
+      continue;
+    }
+    if (token === '--rules') {
+      options.rules = readFlagValue(args, i, '--rules');
+      i += 1;
+      continue;
+    }
+    if (token === '--target-timestamp') {
+      const raw = readFlagValue(args, i, '--target-timestamp');
+      const numeric = Number(raw);
+      if (!Number.isFinite(numeric) || numeric <= 0) {
+        const error = new Error('--target-timestamp must be a unix timestamp in seconds.');
+        error.code = 'INVALID_FLAG_VALUE';
+        throw error;
+      }
+      options.targetTimestamp = Math.trunc(numeric);
+      i += 1;
+      continue;
+    }
+    if (token === '--sources') {
+      let consumed = 0;
+      for (let j = i + 1; j < args.length; j += 1) {
+        const value = args[j];
+        if (typeof value !== 'string' || value.startsWith('--')) break;
+        options.sources.push(value);
+        consumed += 1;
+      }
+      if (!consumed) {
+        const error = new Error('--sources requires at least one URL value.');
+        error.code = 'MISSING_FLAG_VALUE';
+        throw error;
+      }
+      i += consumed;
+      continue;
+    }
+    if (token === '--source') {
+      options.sources.push(readFlagValue(args, i, '--source'));
+      i += 1;
+      continue;
+    }
+    const error = new Error(`Unknown flag for agent market validate: ${token}`);
+    error.code = 'UNKNOWN_FLAG';
+    throw error;
+  }
+
+  if (!String(options.question || '').trim()) {
+    const error = new Error('agent market validate requires --question <text>.');
+    error.code = 'MISSING_REQUIRED_FLAG';
+    throw error;
+  }
+  if (!String(options.rules || '').trim()) {
+    const error = new Error('agent market validate requires --rules <text>.');
+    error.code = 'MISSING_REQUIRED_FLAG';
+    throw error;
+  }
+  if (!options.targetTimestamp) {
+    const error = new Error('agent market validate requires --target-timestamp <unix-seconds>.');
+    error.code = 'MISSING_REQUIRED_FLAG';
+    throw error;
+  }
+
+  return options;
+}
+
+function renderAgentPromptTable(payload) {
+  const lines = [
+    `${payload.promptKind} (${payload.promptVersion})`,
+  ];
+  if (payload.ticket) {
+    lines.push(`ticket: ${payload.ticket}`);
+  }
+  lines.push('');
+  lines.push('Prompt:');
+  lines.push(payload.prompt);
+  lines.push('');
+  lines.push('Workflow:');
+  for (const note of payload.workflow && Array.isArray(payload.workflow.notes) ? payload.workflow.notes : []) {
+    lines.push(`- ${note}`);
+  }
+  if (payload.requiredAttestation) {
+    lines.push('');
+    lines.push('Required attestation:');
+    lines.push(JSON.stringify(payload.requiredAttestation, null, 2));
+  }
+  // eslint-disable-next-line no-console
+  console.log(lines.join('\n'));
+}
+
+function createRunAgentCommand(deps) {
+  const CliError = deps.CliError;
+  const includesHelpFlag = requireDep(deps, 'includesHelpFlag');
+  const emitSuccess = requireDep(deps, 'emitSuccess');
+  const commandHelpPayload = requireDep(deps, 'commandHelpPayload');
+
+  if (typeof CliError !== 'function') {
+    throw new Error('createRunAgentCommand requires deps.CliError.');
+  }
+
+  async function runAgentCommand(args, context) {
+    const rest = Array.isArray(args) ? args : [];
+    if (!rest.length || includesHelpFlag(rest)) {
+      const usage = [
+        'pandora [--output table|json] agent market autocomplete --question <text> [--market-type amm|parimutuel]',
+        'pandora [--output table|json] agent market validate --question <text> --rules <text> --target-timestamp <unix-seconds> [--sources <url...>]',
+      ];
+      if (context.outputMode === 'json') {
+        emitSuccess(context.outputMode, 'agent.help', commandHelpPayload(usage));
+      } else {
+        renderAgentPromptTable({
+          promptKind: 'agent.help',
+          promptVersion: 'n/a',
+          ticket: null,
+          prompt: usage.join('\n'),
+          workflow: {
+            notes: [
+              'Use agent market autocomplete when the agent must draft market rules or timing.',
+              'Use agent market validate before any agent-exposed market execute path.',
+            ],
+          },
+        });
+      }
+      return;
+    }
+
+    const namespace = rest[0];
+    const action = rest[1];
+    const actionArgs = rest.slice(2);
+
+    if (namespace !== 'market') {
+      throw new CliError('INVALID_ARGS', 'agent requires subcommand: market autocomplete|validate');
+    }
+
+    if (action === 'autocomplete') {
+      const payload = buildAgentMarketAutocompletePayload(parseAgentMarketAutocompleteFlags(actionArgs));
+      emitSuccess(context.outputMode, 'agent.market.autocomplete', payload, renderAgentPromptTable);
+      return;
+    }
+
+    if (action === 'validate') {
+      const payload = buildAgentMarketValidationPayload(parseAgentMarketValidateFlags(actionArgs));
+      emitSuccess(context.outputMode, 'agent.market.validate', payload, renderAgentPromptTable);
+      return;
+    }
+
+    throw new CliError('INVALID_ARGS', 'agent market requires subcommand: autocomplete|validate');
+  }
+
+  return {
+    runAgentCommand,
+  };
+}
+
+module.exports = {
+  createRunAgentCommand,
+};