fix(contract-dd): resolve the sub-command contradiction and make coverage auditable

Third review pass, over the sections the first two did not grill: Step 2, Step 8,
Notes, and the two files outside the skill.

**A contradiction introduced by the previous commit.** Step 0 gained a
`portfolio stats` probe to tell a wallet apart from an address GMGN has no record
of, while Sub-commands still read "runs exactly these three ... Nothing else" and
Notes still said "three GET endpoints". The probe is now documented where it
belongs: a conditional fourth call that runs only when `info.symbol` is empty,
feeds no threshold, and sits on the CLI's API-key-only auth path — verified
against `src/client/OpenApiClient.ts`, where `getWalletStats` uses
`authExistRequest`, so the "never needs GMGN_PRIVATE_KEY" prerequisite still
holds. The `--raw` envelope note now covers all four shapes.

**Coverage was stated in a form that cannot be checked.** Step 8 asked for
`executed N / skipped M` against an inventory total, but never for the held-out
count — so `N + M + K = T`, the identity the fixed inventory exists to make
verifiable, was unprintable. The report line is now
`executed N / skipped M / held-out K of T` with all four numbers mandatory.

**The disclosure line named the wrong set.** "chain-analysis metrics (9 checks)"
covered eight holder metrics plus `creator_created_count`, which is a contract
check. It now says so explicitly in both Step 4 and Step 8.

**CLAUDE.md was left self-contradictory by the previous commit**, which routed a
bare wallet address to `gmgn-wallet-analysis` — a skill CLAUDE.md names nowhere
and has no table row for, while a separate row sent "wallet address provided" to
`gmgn-portfolio`. Added the missing row and split that route the same way the
token route was split: dossier verdict to `gmgn-wallet-analysis`, raw holdings
and P&L to `gmgn-portfolio`.

**The DD workflow doc read a struct-default zero as a pass.** Its thresholds
call `top_10_holder_rate < 0.20` safe, but the field arrives as the string `"0"`
on Solana and on some EVM tokens — 0% top-ten concentration does not exist. Noted
the `stat` fallback, and the `"0"` versus `""` distinction for the taxes.

No scoring rule changed in this commit, so no composite or coverage figure moves.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

CLAUDE.md

@@ -29,6 +29,7 @@ This is a **Claude Code plugin** — a collection of GMGN OpenAPI skills for on-
 | `gmgn-token` | Token info, security, pool, holders, traders | User asks about a token's price, market cap, security risk, liquidity pool, top holders, or top traders; user wants to research a token before buying; user asks "is this token safe", "who holds this token", "what's the liquidity" |
 | `gmgn-contract-dd` | One 0-100 due-diligence composite for a token address — contract safety 0.45 + holder structure 0.35 + price action 0.20, every deduction naming the field it read, with a reported coverage that bounds the claim | User wants **one verdict number** rather than fields: 尽调, CA 尽调, 给这个币打个分, 这个币安全吗, 有没有貔貅, 能不能买, rug check, honeypot check, score this contract, due diligence. Refuses to score an address GMGN has no record of, and hands a bare wallet address to `gmgn-wallet-analysis` |
 | `gmgn-market` | K-line / candlestick market data + trending tokens + newly launched launchpad tokens | User asks for price history, chart data, OHLCV candles, trading volume over time; user wants to analyze price trends; user asks "show me the 1h chart", "what was the price last week", "give me kline data for this token"; user wants to discover hot or trending tokens; user asks "what tokens are trending", "show me top tokens by volume", "find hot tokens on SOL"; **user asks about newly launched tokens, fresh tokens, latest tokens on launchpads** — e.g. "show me new tokens on pump.fun", "what tokens just launched on SOL", "find newly created tokens", "latest tokens on letsbonk" → use `market trenches --type new_creation` |
+| `gmgn-wallet-analysis` | The copy-trade dossier on one wallet — four pass/fail gates, what it holds and buys now, entry market-cap band, copy window, size cap | User pastes a **bare wallet address**, or asks 「这个钱包能跟吗」, 「帮我分析一下这个钱包」, 「它现在在买什么」, "can I copy this wallet", "analyze this wallet". This is the default for a bare wallet address; `gmgn-portfolio` is for the raw holdings / P&L / activity behind it |
 | `gmgn-portfolio` | Wallet holdings, activity, trading stats, token balance | User asks about a wallet's holdings, P&L, transaction history, trading statistics, or token balance; user wants to analyze a wallet; user asks "what tokens does this wallet hold", "show me recent trades", "what's the win rate of this wallet" |
 | `gmgn-wallet-score` | Wallet scoring across three angles — profitability (track-record score), copy-tradeability (score + latency/slippage/gas backtest), and Dev reputation for token-creator wallets — plus trading-style tags | User asks about a wallet's profitability ("钱包盈利能力怎么样", "is this wallet profitable"), copy-trade worthiness ("is this wallet worth copying", "跟单评分", "钱包评分", "值不值得跟单", "if I copy this wallet what's my real return"), or launch/Dev reputation ("钱包发盘情况怎么样", "是不是发币方钱包", "dev 信誉怎么样"); user gives a wallet address and wants any of these judgments |
 | `gmgn-track` | Track trade activity of wallets I follow, KOL trades, Smart Money trades across chains | User asks about trades from wallets they follow; user wants to see what KOLs or Smart Money are buying/selling; user asks "show me what wallets I follow have traded recently", "what are KOLs buying", "show me smart money moves on BSC" |
@@ -52,7 +53,7 @@ Match the user's request to the right skill and workflow:
 | "daily brief", "today's market", "每日简报", "今天市场怎么样", "聪明钱今天买了什么" | `gmgn-market` + `gmgn-track` → `docs/workflow-daily-brief.md` |
 | "what is smart money buying", "what are KOLs trading" | `gmgn-track smartmoney` / `gmgn-track kol` |
 | "wallets I follow", "my followed wallets traded" | `gmgn-track follow-wallet` |
-| "analyze this wallet", "is this wallet worth following", wallet address provided | `gmgn-portfolio` → full workflow: `docs/workflow-wallet-analysis.md` |
+| "analyze this wallet", "is this wallet worth following", bare wallet address provided | `gmgn-wallet-analysis` for the verdict dossier; `gmgn-portfolio` → `docs/workflow-wallet-analysis.md` when the raw holdings / P&L / activity are what is wanted |
 | "wallet style", "smart money profile", "聪明钱画像", "这个钱包是长线还是短线", "跟着他买收益如何", "聪明钱排行榜" | `gmgn-portfolio` + `gmgn-track` → `docs/workflow-smart-money-profile.md` |
 | "钱包盈利能力怎么样", "钱包战绩怎么样", "is this wallet profitable" | `gmgn-wallet-score` (profitability angle — track-record score) |
 | "跟单评分", "钱包评分", "值不值得跟单", "is this wallet worth copying", "copy trade score", wallet address provided + copy-trade decision | `gmgn-wallet-score` (copy-tradeability angle — score + backtest) |

docs/workflow-token-due-diligence.md

@@ -36,6 +36,8 @@ gmgn-cli token security --chain sol --address <token_address> --raw
 
 **Every rate and tax field is a decimal fraction**: `top_10_holder_rate: "0.1783"` is 17.83%, `buy_tax: "0.01"` is a 1% tax.
 
+**A `0` in these fields is not automatically a pass.** `top_10_holder_rate` comes back as the string `"0"` on Solana and on some EVM tokens — 0% top-ten concentration does not exist, so read that as *not reported* and fall back to `token info` → `stat.top_10_holder_rate`. For the taxes the two spellings differ: `"0"` on a populated block is a genuine 0% tax, while `""` means the block was never populated and the tax is unknown. Reading either blank as a safe zero is how a token with no security record reads as clean.
+
 **Three fields this table used to list are not returned by `token security` at all** — verified absent from every live response:
 
 - `rug_ratio` — it is a `market trending` / `market trenches` row field, not a security field. Read it there.

skills/gmgn-contract-dd/SKILL.md

@@ -20,11 +20,11 @@ metadata:
 
 **⚠️ IPv6 NOT SUPPORTED: on a `401` / `403` with correct credentials, run `ifconfig | grep inet6` (macOS) or `ip addr show | grep inet6`. If that lists a global IPv6 address, tell the user to disable IPv6 — gmgn-cli only works over IPv4. Do not call any third-party IP-echo service to check this: the local interface listing already answers it, and this skill contacts GMGN and nothing else.**
 
-This skill turns three read-only CLI calls into one auditable score. It does not trade, does not need a private key, and reads nothing on the local machine other than the API key that `gmgn-cli config` already manages.
+This skill turns three read-only CLI calls — plus one conditional fourth, only to tell a wallet from an unknown address — into one auditable score. It does not trade, does not need a private key, and reads nothing on the local machine other than the API key that `gmgn-cli config` already manages.
 
 ## Sub-commands
 
-This skill runs exactly these three, all read-only:
+Every score comes from these three, all read-only:
 
 ```
 gmgn-cli token info     --chain <chain> --address <token_address> --raw
@@ -32,6 +32,14 @@ gmgn-cli token security --chain <chain> --address <token_address> --raw
 gmgn-cli market kline   --chain <chain> --address <token_address> --resolution 15m --raw
 ```
 
+Plus one **conditional** call, made only when Step 0 finds `info.symbol` empty and has to tell a wallet apart from an address GMGN holds no record of:
+
+```
+gmgn-cli portfolio stats --chain <chain> --wallet <address> --period 30d --raw
+```
+
+It never runs on a token that resolved, it feeds no threshold, and it is read-only on the same API-key-only auth as the other three — `portfolio stats` is not in the CLI's signed-request set, so no private key is involved.
+
 Nothing else. Do not call swap, order, or cooking commands from this skill.
 
 ## Supported Chains
@@ -242,7 +250,7 @@ Only when `info.stat` is populated per Step 1B — test it per token, do not dec
 
 **When the block is unpopulated, all eight are unavailable — never eight passes.** Together with `stat.creator_created_count` from Step 3 that is nine unavailable checks. Do **not** put them in the coverage denominator: hold all nine out of it entirely. Otherwise nine skipped checks bury the coverage number on every token GMGN has no chain-analysis data for, and a token where every applicable check passed reads as poorly evidenced. Measured 2026-08-28: CAKE and eth USDT read 86.7% and 80.0% with the nine held out, and would read 54.2% and 50.0% with them counted as skipped — "coverage low" on two tokens with no failed check between them.
 
-**Holding them out of the denominator is a labelling choice, and it must be disclosed.** `stat` population is per token, not per chain, so an empty block is genuinely missing data for this token rather than a field the chain cannot have. Therefore, whenever the nine are held out, the report **must** carry the line *"chain-analysis metrics (9 checks) unavailable for this token"* next to the confidence label, so the reader can discount the confidence themselves. Confidence without that line is overstated.
+**Holding them out of the denominator is a labelling choice, and it must be disclosed.** `stat` population is per token, not per chain, so an empty block is genuinely missing data for this token rather than a field the chain cannot have. Therefore, whenever the nine are held out, the report **must** carry the line *"`stat` chain-analysis metrics (9 checks: the 8 holder metrics plus `creator_created_count`) unavailable for this token"* next to the confidence label, so the reader can discount the confidence themselves. Confidence without that line is overstated.
 
 ## Step 5 — Price action, from 100
 
@@ -340,7 +348,7 @@ This cap is lower than Step 2's 79 on purpose, and it is not the same situation.
 Report in this order:
 
 1. Composite score, grade, and confidence label side by side. When confidence is "insufficient evidence", say so on the same line as the number.
-2. Coverage as `executed N / skipped M` against the inventory total from Step 6, and the weights actually used. If the nine `stat` checks were held out of the denominator, print *"chain-analysis metrics (9 checks) unavailable for this token"* on this line — it is mandatory, not optional.
+2. Coverage as `executed N / skipped M / held-out K of T`, where `T` is the Step 6 inventory total — 22 on `sol`, 24 on the EVM chains — and the weights actually used. **`N + M + K` must equal `T`; print all four numbers so a reader can check that it does.** A line that omits `K` cannot be verified, which defeats the point of having a fixed inventory. If the nine `stat` checks were held out, also print *"`stat` chain-analysis metrics (9 checks: the 8 holder metrics plus `creator_created_count`) unavailable for this token"* — mandatory, not optional.
 3. Each section's sub-score, then every deduction as: field path → measured value → points → reason.
 4. **The unavailable list, in full, never omitted.** For each entry say why: not applicable on this chain, block unpopulated, or field absent.
 5. **Reported-not-scored findings**, each quoted with its value and labelled as not having moved the score: the two `dev` X fields, labelled as history of the linked X account rather than of this token; `vol_ratio` from Step 5 when it was computable, labelled as unvalidated; and any `[filtered]` string or `neutralized … suspicious metadata` stderr notice from `gmgn-cli`.
@@ -350,9 +358,9 @@ Report in this order:
 ## Notes
 
 - All three commands support `--raw`. Always use it.
-- **With `--raw`, these three commands print the unwrapped payload — there is no `code` field to read.** Measured: `token info` and `token security` return the object itself (`{"address": …, "symbol": …}`) and `market kline` returns `{"list": [...]}`. Do not look for `code`, `data`, or an HTTP status; decide "no record" from `info.symbol` per Step 0. Other `gmgn-cli` commands do keep the `{"code":…,"data":…}` envelope under `--raw`, so do not generalise either shape.
+- **With `--raw`, all four of these commands print the unwrapped payload — there is no `code` field to read.** Measured: `token info` and `token security` return the object itself (`{"address": …, "symbol": …}`), `market kline` returns `{"list": [...]}`, and `portfolio stats` returns `{"wallet_address": …, "buy": …}`. Do not look for `code`, `data`, or an HTTP status; decide "no record" from `info.symbol` per Step 0. Other `gmgn-cli` commands do keep the `{"code":…,"data":…}` envelope under `--raw`, so do not generalise either shape.
 - `gmgn-cli` exits **1** with a printed message on a chain outside the seven and on a malformed address, before any request is sent. It exits **0** for a well-formed address GMGN has no record of — that case is Step 0's job, not the exit code's.
-- This skill is read-only: three GET endpoints, no signing, no private key, no local file access beyond the API key `gmgn-cli config` already manages.
+- This skill is read-only: three GET endpoints for scoring plus Step 0's conditional `portfolio stats` probe, no signing, no private key, no local file access beyond the API key `gmgn-cli config` already manages. All four are on the CLI's API-key-only auth path.
 - Chain support is **per endpoint**, not global. Do not assume that a chain accepted by one GMGN endpoint is accepted by another.
 - For chart-pattern naming rather than a risk score, that is `gmgn-kline-pattern`. For holder chip structure in depth, that is `gmgn-holder-analysis`. For raw fields with no scoring, that is `gmgn-token`. This skill owns the composite risk score and nothing else.