hive-intelligence 1.1.2 → 1.1.3

package/agent-skills/packs/hive-mcp/references/client-install-matrix.md

@@ -0,0 +1,83 @@
+# Hive MCP Client Install Matrix
+
+Hive's default product path is the hosted remote MCP endpoint:
+
+```text
+https://mcp.hiveintelligence.xyz/mcp
+```
+
+Use local `stdio` when the user is developing Hive itself, self-hosting, testing
+provider keys, or using a desktop client that only supports local commands.
+
+## Package boundaries
+
+| Package | Role | Who installs it |
+| --- | --- | --- |
+| `hive-intelligence` | MCP server, CLI, local stdio runtime, bundled skills installer. Exposes `hive`, `hive-intelligence`, and `hive-mcp` binaries. | End users, self-hosters, desktop clients |
+| `@hiveintelligence/mcp-client` | Typed adapter for apps and agent frameworks | Developers integrating Hive into code |
+| `@hiveintelligence/agent-skills` | Skills-only corpus for agents and skill registries | Agents, skill package managers, docs mirrors |
+| `hive-intel` | Packaged user-facing CLI/docs surface retained for compatibility | Existing CLI/docs consumers |
+
+## Recommended setup flow
+
+1. Install hosted MCP first unless the user explicitly needs local `stdio`.
+2. Add the API key as `Authorization: Bearer <HIVE_API_KEY>`.
+3. Install or copy skills so the agent knows the workflow layer.
+4. Verify by asking a live query and checking that the agent calls Hive instead
+   of answering from memory.
+
+## Hosted remote MCP
+
+Use for most agents:
+
+```json
+{
+  "mcpServers": {
+    "hive": {
+      "url": "https://mcp.hiveintelligence.xyz/mcp",
+      "headers": {
+        "Authorization": "Bearer YOUR_HIVE_API_KEY"
+      }
+    }
+  }
+}
+```
+
+## Local stdio MCP
+
+Use when a client requires a command-based server:
+
+```json
+{
+  "mcpServers": {
+    "hive": {
+      "command": "npx",
+      "args": ["-y", "-p", "hive-intelligence@latest", "hive"],
+      "env": {
+        "HIVE_API_KEY": "YOUR_HIVE_API_KEY"
+      }
+    }
+  }
+}
+```
+
+## Skills install
+
+Use the Hive CLI for detected local clients:
+
+```bash
+npx -y -p hive-intelligence@latest hive init --all --browser
+```
+
+Use the public skills CLI only after the dedicated GitHub skills mirror is
+published and verified in CI. Before that, validate the local repo package:
+
+```bash
+npx skills add ./agent-skills --list
+```
+
+Check the npm package contents before publishing:
+
+```bash
+npm --workspace @hiveintelligence/agent-skills run pack:check
+```

package/agent-skills/packs/hive-network-infrastructure/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: hive-network-infrastructure
+description: Use this skill for chain infrastructure and RPC questions covering gas, blocks, receipts, logs, transaction status, supported networks, fee data, and diagnostics. Use it when the user needs current chain state or transaction evidence.
+license: MIT
+metadata:
+  package: "@hiveintelligence/agent-skills"
+  category: "network"
+  requires_network: "true"
+version: 1.0.0
+---
+
+# hive-network-infrastructure — Network Infrastructure
+
+Use this skill for block, gas, transaction receipt, logs, supported network, or
+RPC diagnostic questions.
+
+## Task toolset
+
+Use `network_infrastructure`.
+
+Required identifiers: chain. Optional identifiers include block number,
+transaction hash, contract address, or log filter.
+
+## Procedure
+
+Read `references/workflow.md` when the request needs transaction diagnostics,
+RPC/provider comparison, gas/fee context, or a structured network report.
+
+1. Confirm the chain/network id.
+2. Use block/gas/chain-id tools for current state.
+3. Use transaction, receipt, or logs tools only when the user provides exact
+   identifiers.
+4. Report the block/slot/fetched time so the answer is auditable.
+
+## Example
+
+If the user asks whether a transaction succeeded, ask for chain and transaction
+hash before selecting a receipt or transaction lookup tool.
+
+## Runtime status handling
+
+Use `ok`, `missing_key`, `plan_required`, `rate_limited`, `degraded`, and
+`failing`. For transient RPC failures, retry once or fall back to another
+network read and state the limitation.

package/agent-skills/packs/hive-network-infrastructure/evals/evals.json

@@ -0,0 +1,27 @@
+{
+  "skill_name": "hive-network-infrastructure",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Check whether this Ethereum transaction succeeded and summarize the receipt evidence.",
+      "expected_output": "Uses network_infrastructure, asks for chain/tx hash if missing, inspects receipt schema, and reports block/freshness/runtime status.",
+      "files": [],
+      "assertions": [
+        "Chooses network_infrastructure.",
+        "Requires chain and transaction hash.",
+        "Reports receipt/block evidence."
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "What's current gas on Base and are RPC reads healthy?",
+      "expected_output": "Uses current chain/gas/RPC diagnostics, labels provider/source, and avoids broad health claims without diagnostics.",
+      "files": [],
+      "assertions": [
+        "Uses gas or network state workflow.",
+        "Reports provider/source.",
+        "Caveats health based on available diagnostics."
+      ]
+    }
+  ]
+}

package/agent-skills/packs/hive-network-infrastructure/references/workflow.md

@@ -0,0 +1,41 @@
+# Network Infrastructure Workflow
+
+Use this reference for gas, blocks, receipts, logs, transaction status,
+supported networks, fee data, and RPC diagnostics.
+
+## Required identifiers
+
+- Chain/network.
+- Optional: transaction hash, block number/hash, contract address, log topic,
+  account address, or time window.
+
+Ask for exact chain and transaction/block identifiers before status checks.
+
+## Tool selection order
+
+1. Resolve chain/network id.
+2. Use `search_tools` for gas, block, transaction, receipt, log, supported
+   network, or RPC diagnostic tools.
+3. Inspect schemas before invocation.
+4. Use current-state tools for gas and block questions.
+5. Use transaction/receipt/log tools only with exact identifiers.
+
+## Bounded calls
+
+- Bound log queries by block range and topics.
+- Do not run broad chain scans for a single transaction question.
+- Retry transient RPC failures once when appropriate.
+
+## Report template
+
+- Summary: network or transaction state.
+- Calls made: endpoints, chain, identifiers, filters.
+- Evidence: block/slot, gas/fee, receipt/log/status, freshness/runtime status.
+- Caveats: provider mismatch, stale block, rate limit, incomplete logs.
+- Next action: narrower log filter, alternate provider, or retry.
+
+## Gotchas
+
+- A transaction hash is not globally unique without chain context.
+- Logs require bounded block ranges.
+- HTTP health does not prove provider data freshness.

package/agent-skills/packs/hive-nft-research/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: hive-nft-research
+description: Use this skill for NFT collection, ownership, metadata, floor, sale, rarity, spam, or Solana asset research. Use it whenever the user needs current NFT evidence rather than a general explanation of NFTs.
+license: MIT
+metadata:
+  package: "@hiveintelligence/agent-skills"
+  category: "nft"
+  requires_network: "true"
+version: 1.0.0
+---
+
+# hive-nft-research — NFT Research
+
+Use this skill for NFT ownership, metadata, collection, floor, sale, rarity, or
+spam/authenticity questions.
+
+## Task toolset
+
+Use `nft_research`.
+
+Required identifiers: chain and collection contract or asset id.
+
+## Procedure
+
+Read `references/workflow.md` when the request needs collection resolution,
+ownership/floor/sale context, spam caveats, or a structured NFT report.
+
+1. Resolve collection contract, token id, wallet, or asset id.
+2. Pull metadata, owners, floors, sales, rarity, or spam checks as requested.
+3. Separate collection-level and token-level facts.
+4. Preserve raw metadata when the user asks about traits or provenance.
+
+## Example
+
+For a collection-level question, ask for the chain and contract if the user only
+gave a collection name.
+
+## Runtime status handling
+
+If market data is `degraded`, still return metadata/ownership that succeeded
+and label floor or sales metrics as unavailable.

package/agent-skills/packs/hive-nft-research/evals/evals.json

@@ -0,0 +1,27 @@
+{
+  "skill_name": "hive-nft-research",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Research this NFT collection's floor, recent sales, owners, and metadata freshness.",
+      "expected_output": "Uses nft_research, asks for or resolves chain/collection contract, fetches bounded floor/sales/owner/metadata data, and reports marketplace/provider caveats.",
+      "files": [],
+      "assertions": [
+        "Chooses nft_research.",
+        "Requires chain and collection/asset identifier.",
+        "Reports floor/sales metadata caveats."
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "Is this NFT in my wallet spam or a legitimate asset?",
+      "expected_output": "Routes to NFT ownership/metadata/spam checks, preserves wallet and asset identifiers, and avoids unsupported authenticity claims.",
+      "files": [],
+      "assertions": [
+        "Includes spam/authenticity workflow.",
+        "Uses wallet and asset identifiers.",
+        "Avoids absolute legitimacy claims without evidence."
+      ]
+    }
+  ]
+}

package/agent-skills/packs/hive-nft-research/references/workflow.md

@@ -0,0 +1,42 @@
+# NFT Research Workflow
+
+Use this reference for NFT collections, ownership, metadata, floors, sales,
+rarity, spam checks, and Solana assets.
+
+## Required identifiers
+
+- Chain/network.
+- Collection contract, token id, asset id, wallet address, or mint.
+- Optional: marketplace, time window, trait filter, or owner.
+
+Ask for chain and contract/asset identifiers when the user gives only a
+collection name.
+
+## Tool selection order
+
+1. Resolve collection, token, wallet, or asset id.
+2. Use `search_tools` for metadata, owners, floor, sales, rarity, spam, and
+   Solana DAS asset tools.
+3. Inspect schemas before invocation.
+4. Start with metadata/identity.
+5. Add floor/sales or owner/rarity only when relevant.
+
+## Bounded calls
+
+- Limit owner and sales lists.
+- Keep collection-level and token-level evidence separate.
+- Do not treat one marketplace floor as the entire market without caveat.
+
+## Report template
+
+- Summary: collection/token ownership or market read.
+- Calls made: endpoints, chain, contract/asset/token identifiers.
+- Evidence: metadata, owner/floor/sales/rarity/spam, freshness/runtime status.
+- Caveats: marketplace coverage, stale floor, missing metadata, degraded data.
+- Next action: trait drilldown, ownership verification, or market comparison.
+
+## Gotchas
+
+- NFT metadata can be mutable or stale.
+- Spam checks can lag new collections.
+- Solana assets often require Solana-native DAS identifiers.

package/agent-skills/packs/hive-prediction-markets/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: hive-prediction-markets
+description: Use this skill for prediction market research covering Polymarket, Kalshi, events, markets, outcomes, odds, prices, liquidity, stats, traders, holders, and trades. Never present market probability as ground truth.
+license: MIT
+metadata:
+  package: "@hiveintelligence/agent-skills"
+  category: "prediction-markets"
+  requires_network: "true"
+version: 1.0.0
+---
+
+# hive-prediction-markets — Prediction Markets
+
+Use this skill for prediction market discovery, including Polymarket, Kalshi,
+odds, pricing, event stats, traders, holders, trades, or outcome questions.
+
+## Task toolset
+
+Use `prediction_markets`.
+
+Required identifiers: market id, event id, token id, trader address, or search
+query depending on the request.
+
+## Procedure
+
+Read `references/workflow.md` when the request needs market/event discovery,
+liquidity/probability caveats, trader context, or a structured prediction
+market report.
+
+1. Search/filter markets or events when the user starts with a topic.
+2. Resolve exact market/event/token ids before stats, holders, or trades.
+3. Report market price, volume/liquidity, outcomes, and freshness.
+4. Do not present market probability as ground truth.
+
+## Example
+
+For "Bitcoin election prediction markets" or "Polymarket vs Kalshi odds",
+search markets/events first, then ask which specific market to inspect if
+multiple candidates match.
+
+## Runtime status handling
+
+If a market search succeeds but stats are `degraded`, return the candidates and
+label the missing market details clearly.

package/agent-skills/packs/hive-prediction-markets/evals/evals.json

@@ -0,0 +1,27 @@
+{
+  "skill_name": "hive-prediction-markets",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Find active prediction markets about the next Fed decision and show the top outcomes with liquidity caveats.",
+      "expected_output": "Uses prediction_markets, searches markets/events first, resolves candidate ids, bounds results, and reports price/liquidity/freshness caveats.",
+      "files": [],
+      "assertions": [
+        "Chooses prediction_markets.",
+        "Searches markets/events before stats.",
+        "States market price is not ground truth."
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "For this Polymarket market id, summarize traders, holders, and recent trades.",
+      "expected_output": "Uses exact market/token identifiers, fetches bounded traders/holders/trades, and reports provider/runtime status.",
+      "files": [],
+      "assertions": [
+        "Uses exact market or token id.",
+        "Bounds traders/holders/trades.",
+        "Reports provider and runtime status."
+      ]
+    }
+  ]
+}

package/agent-skills/packs/hive-prediction-markets/references/workflow.md

@@ -0,0 +1,42 @@
+# Prediction Markets Workflow
+
+Use this reference for prediction market discovery, events, outcomes, prices,
+liquidity, stats, traders, holders, and trades.
+
+## Required identifiers
+
+- Topic/search query, event id, market id, token id, or trader address.
+- Optional: status filter, limit, date range, outcome, or liquidity threshold.
+
+If the user starts with a topic, search candidates first and ask for selection
+when multiple markets match.
+
+## Tool selection order
+
+1. Use `search_tools` for prediction market search, event, market, stats,
+   holders, traders, or trade tools.
+2. Inspect schemas before invocation.
+3. Search events/markets for topic prompts.
+4. Resolve exact market/event/token ids before stats, holders, or trades.
+5. Add liquidity/volume and freshness context before interpreting prices.
+
+## Bounded calls
+
+- Use small search limits and page through only when needed.
+- Do not fetch all trades or holders unless the user asks for a deep dive.
+- Keep outcome token prices separate from event-level interpretation.
+
+## Report template
+
+- Summary: market/event read and top outcomes.
+- Calls made: endpoints, market/event/token/trader identifiers.
+- Evidence: price, liquidity, volume, outcomes, holders/traders, freshness.
+- Caveats: market probability is not truth, thin liquidity, stale/incomplete
+  stats, candidate ambiguity.
+- Next action: inspect selected market, holders, trades, or related events.
+
+## Gotchas
+
+- Market prices reflect trading/liquidity, not verified probability.
+- Similar markets can have different resolution criteria.
+- Event-level and outcome-token-level data are not interchangeable.

package/agent-skills/packs/hive-query/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: hive-query
+description: Use this skill for any live crypto intelligence question before answering from memory. Route wallet, token, DeFi, NFT, Solana, security, market, DEX, network, or prediction-market requests through Hive task toolsets, schema lookup, and bounded endpoint invocation.
+license: MIT
+metadata:
+  package: "@hiveintelligence/agent-skills"
+  category: "discovery"
+  requires_network: "true"
+version: 2.0.0
+---
+
+# hive-query — Route Crypto Questions Through Hive
+
+Use this skill when Hive MCP is connected and the user asks a crypto question.
+Do not answer from model memory when the answer depends on live data.
+
+## Routing rule
+
+Read `references/root-mcp-workflow.md` when the user asks how Hive MCP is
+organized, what tools are available, or how an agent should navigate the root
+endpoint without loading the full provider catalog into context.
+
+1. Read `hive://toolsets` or call `search_tools` with the user's intent.
+2. Select one canonical task toolset.
+3. Ask for missing identifiers before execution if the toolset requires them.
+4. Call `get_api_endpoint_schema` for the exact tool you plan to call.
+5. Call the exact endpoint through `invoke_api_endpoint`.
+6. Report freshness, provider/runtime status, and any missing-data caveats.
+
+## Canonical task toolsets
+
+| Intent | Toolset id |
+| --- | --- |
+| Price, exchange, OHLC, liquidity, derivatives | `market_research` |
+| Token metadata, holders, liquidity, enrichment, risk | `token_diligence` |
+| Wallet balances, transfers, PnL, NFTs, DeFi positions | `wallet_investigation` |
+| Token, approval, phishing, address, simulation risk | `security_risk` |
+| Pools, pairs, trades, OHLCV, DEX flow | `onchain_dex_pool_analysis` |
+| TVL, fees, yields, stablecoins, bridges | `defi_protocol_analysis` |
+| NFT ownership, metadata, floors, sales, rarity | `nft_research` |
+| Blocks, gas, logs, receipts, RPC diagnostics | `network_infrastructure` |
+| Solana wallets, SPL accounts, DAS assets, priority fees | `solana_analysis` |
+| Events, markets, outcomes, traders, holders | `prediction_markets` |
+| Ambiguous request or schema lookup | `search_discovery` |
+
+## Example
+
+User: "Investigate this wallet on Ethereum."
+
+Use `wallet_investigation`. Required identifiers are wallet address and chain.
+Then search for the current wallet-balance endpoint, inspect its schema, and
+only then invoke it. Do not hardcode stale endpoint names in the skill. Use this
+sequence: `search_tools` for `wallet investigation ethereum balances`,
+`get_api_endpoint_schema` for the selected endpoint, then `invoke_api_endpoint`
+with schema-valid `address` and `network` or chain arguments.
+
+Then use schema lookup and add transfer, NFT, or DeFi-position tools only when
+the user's question needs that detail.
+
+## Report template
+
+Use this structure for Hive-backed answers:
+
+```markdown
+## Summary
+[One or two sentences answering the user.]
+
+## Calls made
+- Toolset: [task toolset]
+- Endpoint(s): [exact endpoint names]
+- Identifiers: [chain, wallet, contract, market, protocol, etc.]
+
+## Evidence
+- Provider/source: [provider names]
+- Freshness: [timestamp, block/slot, or fetched_at when available]
+- Runtime status: [ok/missing_key/plan_required/rate_limited/degraded/failing]
+
+## Caveats
+[Fallbacks, stale data, unavailable providers, missing identifiers, limits.]
+
+## Next action
+[Only include if a retry, deeper check, or user choice is needed.]
+```
+
+## Runtime status handling
+
+Hive uses `ok`, `missing_key`, `plan_required`, `rate_limited`, `degraded`, and
+`failing`. Do not treat a non-`ok` provider state as a missing tool. Tell the
+user which task/tool failed, why, and what can be retried or upgraded.
+
+## Guardrails
+
+- Never invent token, wallet, market, or event identifiers.
+- Prefer exact contract addresses, wallet addresses, pair addresses, market ids,
+  or exchange ids over fuzzy names.
+- Keep raw provider endpoints callable; task toolsets are only the selection
+  layer.
+- If a tool is absent from the skill, use `search_tools` instead of guessing.

package/agent-skills/packs/hive-query/evals/evals.json

@@ -0,0 +1,38 @@
+{
+  "skill_name": "hive-query",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Use Hive MCP to investigate whether wallet 0x0000000000000000000000000000000000000000 has meaningful Ethereum token activity. Show the tools you would call and the caveats.",
+      "expected_output": "Routes through wallet_investigation, requests or infers eth-mainnet, looks up schemas before exact endpoint calls, avoids inventing activity, and reports provider/runtime/freshness caveats.",
+      "files": [],
+      "assertions": [
+        "Mentions wallet_investigation or the wallet task toolset.",
+        "Uses get_api_endpoint_schema before invoke_api_endpoint.",
+        "Reports provider/runtime status and does not answer from memory."
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "A user pasted an Ethereum token contract and asks if it is safe and liquid enough to trade. What Hive workflow should the agent use?",
+      "expected_output": "Combines token_diligence and security_risk only as needed, asks for or preserves the exact contract address and chain, inspects schemas, and plans bounded calls.",
+      "files": [],
+      "assertions": [
+        "Chooses token_diligence and/or security_risk.",
+        "Requires exact contract address and chain.",
+        "Includes provenance, liquidity, and risk reporting expectations."
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "Find active prediction markets about the next US Fed decision and summarize the top outcomes with source caveats.",
+      "expected_output": "Routes to prediction_markets, searches for market/event tools, inspects schemas, bounds result limits, and cites source, freshness, and missing data caveats.",
+      "files": [],
+      "assertions": [
+        "Chooses prediction_markets.",
+        "Uses search_tools or hive://toolsets before endpoint selection.",
+        "Reports freshness and source caveats."
+      ]
+    }
+  ]
+}

package/agent-skills/packs/hive-query/references/root-mcp-workflow.md

@@ -0,0 +1,54 @@
+# Hive Root MCP Workflow
+
+Hive is an agent-facing crypto intelligence product, not a flat endpoint
+catalog. The root MCP endpoint stays compact so agents can decide quickly and
+only pull deeper schemas when needed.
+
+## Architecture
+
+```mermaid
+flowchart LR
+  User["User crypto question"] --> Agent["Agent with Hive skill"]
+  Agent --> Root["Root MCP /mcp"]
+  Root --> Resources["Resources: hive://toolsets, hive://tools, hive://providers, hive://status"]
+  Root --> MetaTools["Meta tools: search_tools, get_api_endpoint_schema, invoke_api_endpoint"]
+  Root --> Toolsets["Task toolsets"]
+  MetaTools --> Registry["Provider endpoint registry"]
+  Registry --> Providers["CoinGecko, DeFiLlama, GoPlus, Codex, CCXT, Tenderly, Moralis, Helius, Alchemy, Polymarket"]
+  Agent --> Answer["Answer with provenance, freshness, runtime status"]
+```
+
+## Default agent loop
+
+1. Start from user intent, not provider names.
+2. Read `hive://toolsets` or call `search_tools`.
+3. Select the closest task toolset.
+4. Ask for required identifiers that are missing: chain, wallet, contract,
+   token id, pair id, protocol slug, market id, or time window.
+5. Call `get_api_endpoint_schema` for each exact endpoint before execution.
+6. Call `invoke_api_endpoint` with bounded arguments. Respect `limit`,
+   `page`, `per_page`, `offset`, time windows, and response-size safeguards.
+7. Report provider, freshness, fallback/degraded state, missing keys, rate
+   limits, and caveats.
+
+## Root versus category endpoints
+
+- Root `/mcp` should expose a small meta-tool surface. It is optimized for
+  agents that need routing, schema lookup, and bounded invocation.
+- Category endpoints expose direct scoped tools for clients that explicitly
+  need broad `tools/list` results.
+- Do not treat root `tools/list` as the full product. Full provider coverage is
+  discoverable through resources, category listing tools, schema lookup, and
+  `invoke_api_endpoint`.
+
+## Reporting standard
+
+Every answer that used Hive should include enough context to debug the result:
+
+- Toolset or endpoint used.
+- Provider or data source.
+- Chain/network and identifiers.
+- Freshness or timestamp if available.
+- Runtime state: `ok`, `missing_key`, `plan_required`, `rate_limited`,
+  `degraded`, or `failing`.
+- Any fallback, cache use, unavailable provider, or omitted data.

package/agent-skills/packs/hive-security-risk/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: hive-security-risk
+description: Use this skill before advising on swaps, approvals, signatures, dApps, contracts, URLs, or transaction payloads where token, address, approval, phishing, or simulation risk matters. Report severity, evidence, and remediation instead of guessing.
+license: MIT
+metadata:
+  package: "@hiveintelligence/agent-skills"
+  category: "security"
+  requires_network: "true"
+version: 1.0.0
+---
+
+# hive-security-risk — Security Risk
+
+Use this skill before explaining swaps, approvals, signatures, dApps, or
+unknown contracts.
+
+## Task toolset
+
+Use `security_risk`.
+
+Required identifiers: chain and token contract, wallet address, spender,
+dApp URL, or transaction payload depending on the request.
+
+## Procedure
+
+Read `references/workflow.md` when the request involves signing, approvals,
+dApps, simulations, or any risk report that needs severity and remediation.
+
+1. Identify the asset, address, approval, dApp, or transaction payload.
+2. Run token/address/approval/phishing/simulation checks as appropriate.
+3. Report severity, evidence, and remediation steps.
+4. Do not provide signing guidance when critical risk is unresolved.
+
+## Example
+
+For an ERC-20 approval concern, collect chain, token contract, owner wallet, and
+spender before selecting the approval or allowance tool.
+
+## Runtime status handling
+
+`rate_limited` and `degraded` can be retried with backoff. `plan_required` means
+the tool exists but the upstream account cannot execute it right now.