pandora-cli-skills 1.1.59 → 1.1.61

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.61
 ---
 
 # Pandora CLI & Skills
@@ -43,7 +43,7 @@ npm link
 - 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 +52,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`
@@ -83,6 +84,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 +142,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 +175,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 +367,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 +484,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 +492,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