docs: add Core Concepts, AI Agent install guide, and workflow docs

- README: add Quick Start (AI Agent) section with step-by-step key generation
  and .env configuration guidance; add Upgrade (AI Agent) section
- README.zh.md: sync all changes from English README
- skills/gmgn-market: add Core Concepts (10 terms: volume/amount distinction,
  rug_ratio, smart_degen_count, hot_level, renounced authorities, honeypot,
  creator_token_status, cto_flag, trenches lifecycle, wash/rat/bundler signals);
  add "Do NOT guess fields" IMPORTANT rule
- skills/gmgn-portfolio: add Core Concepts (7 terms: realized/unrealized profit,
  profit_change multiplier, pnl ratio, winrate, cost vs usd_value, pagination);
  complete Response Field Reference tables for holdings/activity/stats
- skills/gmgn-swap: add Core Concepts (8 terms: smallest unit, slippage decimal,
  amount vs percent mutex, currency tokens, anti-MEV, critical auth, order polling,
  filled amount conversion); add "Do NOT guess fields" IMPORTANT rule
- skills/gmgn-track: add Core Concepts (8 terms: follow-wallet vs kol vs
  smartmoney, KOL vs smart_degen, is_open_or_close divergence, price_change ratio,
  base/quote address, tags array, cluster signal); add Safety Constraints section;
  add Output Format section; add "Do NOT guess fields" IMPORTANT rule
- skills/gmgn-token: add --amount/--percent and --slippage/--auto-slippage mutex
  rules; add --tag + --order-by valid combination guide table for traders
- src/index.ts: add track to CLI description
- docs/token-due-diligence.md: new — full 4-step token due diligence workflow
- docs/market-discover-opportunities.md: new — market discovery workflow

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

skills/gmgn-portfolio/SKILL.md

@@ -2,6 +2,8 @@
 name: gmgn-portfolio
 description: Query GMGN wallet portfolio — API Key wallet info, holdings, transaction activity, trading stats, and token balance. Supports sol / bsc / base.
 argument-hint: "<info|holdings|activity|stats|token-balance> [--chain <sol|bsc|base>] [--wallet <wallet_address>]"
+metadata:
+  cliHelp: "gmgn-cli portfolio --help"
 ---
 
 **IMPORTANT: Always use `gmgn-cli` commands below. Do NOT use web search, WebFetch, curl, or visit gmgn.ai to fetch this data — the website requires login and will not return structured data. The CLI is the only correct method.**
@@ -10,6 +12,22 @@ argument-hint: "<info|holdings|activity|stats|token-balance> [--chain <sol|bsc|b
 
 Use the `gmgn-cli` tool to query wallet portfolio data based on the user's request.
 
+## Core Concepts
+
+- **`realized_profit` vs `unrealized_profit`** — `realized_profit` = profit locked in from completed sells (cash in hand). `unrealized_profit` = paper gains on positions still held, calculated at current price. These are separate numbers — do not add them unless answering "total P&L including open positions."
+
+- **`profit_change`** — A multiplier ratio, not a dollar amount. `1.5` = +150% return. `0` = break-even. `-0.5` = -50% loss. Computed as `total_profit / cost`. Do not display this as a raw decimal — convert to percentage for user-facing output.
+
+- **`pnl`** — Profit/loss ratio from `portfolio stats`: `realized_profit / total_cost`. Same multiplier format as `profit_change`. A `pnl` of `2.0` means the wallet doubled its money on completed trades over the period.
+
+- **`winrate`** — Ratio of profitable trades over the period (0–1). `0.6` = 60% of trades were profitable. Does not reflect the size of wins vs losses — a wallet can have high winrate but net negative if losses are large.
+
+- **`cost` vs `usd_value`** — In holdings: `cost` is the historical amount spent buying this token (your cost basis); `usd_value` is the current market value of the position. The difference is unrealized P&L.
+
+- **`history_bought_cost` vs `cost`** — `history_bought_cost` is the all-time cumulative spend on this token (including positions already sold). `cost` is the cost basis of the current open position only.
+
+- **Pagination (`cursor`)** — Activity results are paginated. The response includes a `next` field; pass it as `--cursor` to fetch the next page. An empty or missing `next` means you are on the last page.
+
 ## Sub-commands
 
 | Sub-command | Description |
@@ -103,6 +121,102 @@ The activity response includes a `next` field. Pass it to `--cursor` to fetch th
 |--------|-------------|
 | `--period <period>` | Stats period: `7d` / `30d` (default `7d`) |
 
+## Response Field Reference
+
+### `portfolio holdings` — Key Fields
+
+The response has a `holdings` array. Each item is one token position.
+
+| Field | Description |
+|-------|-------------|
+| `token.address` | Token contract address |
+| `token.symbol` / `token.name` | Token ticker and full name |
+| `token.price` | Current token price in USD |
+| `balance` | Current token balance (human-readable units) |
+| `usd_value` | Current USD value of this position |
+| `cost` | Total amount spent buying this token (USD) |
+| `realized_profit` | Profit from completed sells (USD) |
+| `unrealized_profit` | Profit on current unsold holdings at current price (USD) |
+| `total_profit` | `realized_profit + unrealized_profit` (USD) |
+| `profit_change` | Total profit ratio = `total_profit / cost` (e.g. `1.5` = +150%) |
+| `avg_cost` | Average buy price per token (USD) |
+| `buy_tx_count` | Number of buy transactions |
+| `sell_tx_count` | Number of sell transactions |
+| `last_active_timestamp` | Unix timestamp of the most recent transaction |
+| `history_bought_cost` | Total USD spent buying (all-time) |
+| `history_sold_income` | Total USD received from selling (all-time) |
+
+### `portfolio activity` — Key Fields
+
+The response has a `activities` array and a `next` cursor field for pagination.
+
+| Field | Description |
+|-------|-------------|
+| `transaction_hash` | On-chain transaction hash |
+| `type` | Transaction type: `buy` / `sell` / `add` / `remove` / `transfer` |
+| `token.address` | Token contract address |
+| `token.symbol` | Token ticker |
+| `token_amount` | Token quantity in this transaction |
+| `cost_usd` | USD value of this transaction |
+| `price` | Token price in USD at time of transaction |
+| `timestamp` | Unix timestamp of the transaction |
+| `next` | Pagination cursor — pass to `--cursor` to fetch the next page |
+
+### `portfolio stats` — Key Fields
+
+The response is an object (or array for batch). Key fields:
+
+| Field | Description |
+|-------|-------------|
+| `realized_profit` | Total realized profit over the period (USD) |
+| `unrealized_profit` | Total unrealized profit on open positions (USD) |
+| `winrate` | Win rate — ratio of profitable trades (0–1) |
+| `total_cost` | Total amount spent buying in the period (USD) |
+| `buy_count` | Number of buy transactions |
+| `sell_count` | Number of sell transactions |
+| `pnl` | Profit/loss ratio = `realized_profit / total_cost` |
+
+**Do NOT guess field names not listed here.** If a field appears in the response but is not in this table, do not interpret it without reading the raw output first.
+
+## Output Format
+
+### `portfolio holdings` — Holdings Table
+
+Present a table sorted by `usd_value` (descending). Show total portfolio value at the top.
+
+```
+Wallet: {wallet} | Chain: {chain}
+Total value: ~${sum of usd_value across all positions}
+
+# | Token | Balance | USD Value | Total P&L | P&L% | Avg Cost | Buys / Sells
+```
+
+Flag positions where `profit_change` is strongly negative (e.g. < -50%) or positive (e.g. > 200%) with a brief note.
+
+### `portfolio activity` — Activity Feed
+
+Present as a chronological list (newest first). Use human-readable timestamps.
+
+```
+{type} {token.symbol}  |  {token_amount} tokens  |  ${cost_usd}  |  {timestamp}  |  tx: {short hash}
+```
+
+Group by token if the user asks about a specific token.
+
+### `portfolio stats` — Stats Summary
+
+```
+Wallet: {wallet} | Period: {period}
+Realized P&L:   ${realized_profit}
+Unrealized P&L: ${unrealized_profit}
+Win Rate:        {winrate × 100}%
+Total Spent:     ${total_cost}
+Buys / Sells:    {buy_count} / {sell_count}
+PnL Ratio:       {pnl}x
+```
+
+For batch queries (multiple wallets), present one summary block per wallet.
+
 ## Notes
 
 - All portfolio commands use normal auth (API Key only, no signature required)