echopai 2.6.1 → 2.8.0

package/dist/bin.js

@@ -15,8 +15,8 @@ var OPERATIONS = {
     cliName: "agent session-end",
     method: "POST",
     path: "/v1/agent/session/{id}/end",
-    description: "关闭 `/v1/agent/session/start` 开启的会话，最终用量提交入库。",
-    summary: "End a billable agent session",
+    description: "Closes a session opened by `/v1/agent/session/start` and commits its final usage.",
+    summary: "Close a billable agent session.",
     positional: [
       "id"
     ],
@@ -50,8 +50,8 @@ var OPERATIONS = {
     cliName: "agent session-start",
     method: "POST",
     path: "/v1/agent/session/start",
-    description: "开启 agent kind 凭据的计费会话。返回 session_id，用于将多次调用归并到一次 billable 单位。需要 `Idempotency-Key` 头。",
-    summary: "Start a billable agent session",
+    description: "Opens a billable session for an agent credential and returns a session_id that groups subsequent calls into a single billable unit. Requires an `Idempotency-Key` header.",
+    summary: "Open a billable agent session.",
     positional: [],
     outputDefault: "json",
     pagination: "none",
@@ -115,8 +115,8 @@ var OPERATIONS = {
     cliName: "agent session-usage",
     method: "GET",
     path: "/v1/agent/session/{id}/usage",
-    description: "返回 session 内累计 billable 调用次数、各 scope 配额消耗。",
-    summary: "Get cumulative usage of an agent session",
+    description: "Returns the cumulative billable call count and per-scope quota consumption for the given session.",
+    summary: "Get cumulative usage for an agent session.",
     positional: [
       "id"
     ],
@@ -150,8 +150,8 @@ var OPERATIONS = {
     cliName: "announcements detail",
     method: "GET",
     path: "/v1/announcements/{announcement_id}",
-    description: "返回公告完整内容：content_md、content_text、cninfo 元数据、解析状态。",
-    summary: "Fetch a single announcement by id",
+    description: "Returns the full content of one announcement: body (markdown and plain text), metadata, and parse status.",
+    summary: "Get a single announcement by id.",
     positional: [
       "announcement_id"
     ],
@@ -185,8 +185,8 @@ var OPERATIONS = {
     cliName: "announcements feed",
     method: "GET",
     path: "/v1/announcements/feed",
-    description: "A 股公告 feed，按 published_at 降序、同日按 cninfo source_id 降序。可按 type / since 过滤。需要 `announcements:read` scope。",
-    summary: "List recent A-share announcements",
+    description: "Returns a feed of recent A-share corporate announcements, sorted by publication date descending. Filter by `type` or `since`. Requires the `announcements:read` scope.",
+    summary: "List recent A-share announcements.",
     positional: [],
     outputDefault: "json",
     pagination: "offset",
@@ -233,8 +233,8 @@ var OPERATIONS = {
     cliName: "announcements search",
     method: "GET",
     path: "/v1/announcements/search",
-    description: "公告混合搜索：名称 / 代码做结构化过滤 + 关键词 BM25 全文（ParadeDB jieba，覆盖 title / ai_summary / content_md 前 1500 字）。q 含 6 位代码或内嵌 A 股名 → 按代码精确过滤；残余或纯文本 → BM25 按相关度×时间衰减排序；纯代码/名称则按 published_at 倒序列出。需要 `announcements:read` scope。",
-    summary: "Hybrid search over A-share announcements",
+    description: "Hybrid search over A-share announcements: structured filtering by security name or code, combined with full-text keyword search (over title, AI summary, and the first ~1500 characters of the body). A query containing a 6-digit code or an embedded security name is filtered by that security; remaining free text is ranked by relevance with time decay; a pure code or name lists results by publication date descending. Requires the `announcements:read` scope.",
+    summary: "Search A-share announcements.",
     positional: [],
     outputDefault: "json",
     pagination: "offset",
@@ -293,8 +293,8 @@ var OPERATIONS = {
     cliName: "announcements stock",
     method: "GET",
     path: "/v1/announcements/stock",
-    description: "指定股票代码的公告列表（含历史窗口）。代码接受 6 位纯数字或 SSE:600519 / SZSE:000001 / BSE:430000 形式。需要 `announcements:read` scope。",
-    summary: "List announcements for a specific A-share security",
+    description: "Returns the announcement history for one A-share security over a date window. Accepts a 6-digit code or canonical form (e.g. `SSE:600519`). Requires the `announcements:read` scope.",
+    summary: "List announcements for one security.",
     positional: [],
     outputDefault: "json",
     pagination: "offset",
@@ -352,17 +352,8 @@ var OPERATIONS = {
     cliName: "auth whoami",
     method: "GET",
     path: "/v1/auth/whoami",
-    description: `Returns the calling token's kind, scopes, audience, app metadata,
-rate_limit, allowed_clients, agent_budget (if kind=agent), api_version,
-feature_flags. Any valid JWT can call — no specific scope required.
-
-CLI/MCP call this once at startup, cache 5 minutes in-process, and use
-the response to derive \`verbs.available\` (intersection of curated verb
-scopes with token scopes) and to populate \`echopai doctor\` checks.
-
-See \`docs/PLAN_CLI_V2_AGENT_SURFACE.md\` §5.1.
-`,
-    summary: "Token introspection (CLI/MCP capability discovery)",
+    description: "Returns the calling token's kind, scopes, audience, app metadata, rate limit, allowed clients, agent budget (when kind=agent), API version, and feature flags. Any valid token may call this; no specific scope is required. Clients typically call it once at startup and cache the result briefly to determine which commands are available.",
+    summary: "Introspect the calling token (capability discovery).",
     positional: [],
     outputDefault: "json",
     pagination: "none",
@@ -383,8 +374,8 @@ See \`docs/PLAN_CLI_V2_AGENT_SURFACE.md\` §5.1.
     cliName: "bars daily",
     method: "GET",
     path: "/v1/bars/daily",
-    description: "Daily OHLC bars for one A-share security over a date range. Returns open / high / low / close / volume / turnover per trading day. Requires `bars:30d` (last 30 trading days) or `bars:full` (full history) scope.",
-    summary: "Daily OHLC bars for one A-share security",
+    description: "Returns daily open/high/low/close/volume/turnover for one A-share security over a date range (canonical code, e.g. `SSE:600519`). End-of-day data. Requires the `bars:30d` scope (last 30 trading days) or `bars:full` scope (full history).",
+    summary: "List daily OHLC bars for one A-share security.",
     positional: [],
     outputDefault: "json",
     pagination: "none",
@@ -432,8 +423,8 @@ See \`docs/PLAN_CLI_V2_AGENT_SURFACE.md\` §5.1.
     cliName: "bars daily-batch",
     method: "GET",
     path: "/v1/bars/daily-batch",
-    description: "Batch daily OHLC bars for multiple A-share securities. Up to 100 codes\nper call, up to 1-year date range. Single round-trip; ClickHouse `IN(...)`\nunder the hood.\n\nReturns partial success envelope: codes denied by `allowed_securities`\nappear in `errors[]`, others in `items[]` (with empty `bars[]` if no\ndata found). Order in `items[]` matches input order.\n\nRequires `bars:30d` or `bars:full` scope.\n",
-    summary: "Batch daily OHLC bars for up to 100 A-share securities",
+    description: "Returns daily OHLC bars for multiple A-share securities in one call: up to 100 codes and up to a one-year date range. Responses use a partial-success envelope: codes the token may not access are reported in `errors[]`, the rest in `items[]` (with an empty `bars[]` when no data is found), preserving input order. Requires the `bars:30d` or `bars:full` scope.",
+    summary: "Batch daily OHLC bars for up to 100 securities.",
     positional: [],
     outputDefault: "json",
     pagination: "none",
@@ -489,8 +480,8 @@ See \`docs/PLAN_CLI_V2_AGENT_SURFACE.md\` §5.1.
     cliName: "bars minute",
     method: "GET",
     path: "/v1/bars/minute",
-    description: "Minute-level OHLC bars for one A-share security on a single trade date. Requires `bars:30d` or `bars:full` scope.",
-    summary: "Minute-level OHLC bars for one A-share security",
+    description: "Returns minute-level OHLC bars for one A-share security on a single trade date (canonical code, e.g. `SSE:600519`). Requires the `bars:30d` or `bars:full` scope.",
+    summary: "List minute OHLC bars for one A-share security.",
     positional: [],
     outputDefault: "json",
     pagination: "none",
@@ -531,8 +522,8 @@ See \`docs/PLAN_CLI_V2_AGENT_SURFACE.md\` §5.1.
     cliName: "bars minute-batch",
     method: "GET",
     path: "/v1/bars/minute-batch",
-    description: "Batch minute OHLC bars for multiple A-share securities. Up to 20 codes\nper call, up to 7 calendar days (≈5 trading days) date range. Single\nClickHouse round-trip; app groups rows by canonical_code.\n\nPartial success envelope same as daily-batch: codes denied by\n`allowed_securities` go to `errors[]`; others to `items[]` with flat\n`bars[]` (each bar carries its own `trade_date` for client grouping).\n\nRequires `bars:30d` or `bars:full` scope.\n",
-    summary: "Batch minute OHLC bars for up to 20 A-share securities",
+    description: "Returns minute-level OHLC bars for multiple A-share securities in one call: up to 20 codes and up to a 7 calendar-day (~5 trading-day) range. Responses use a partial-success envelope: codes the token may not access are reported in `errors[]`, the rest in `items[]` with a flat `bars[]` array where each bar carries its own `trade_date` for client-side grouping. Requires the `bars:30d` or `bars:full` scope.",
+    summary: "Batch minute OHLC bars for up to 20 securities.",
     positional: [],
     outputDefault: "json",
     pagination: "none",
@@ -583,17 +574,35 @@ See \`docs/PLAN_CLI_V2_AGENT_SURFACE.md\` §5.1.
       ]
     }
   },
+  "capabilities.show": {
+    cliKey: "capabilities.show",
+    cliName: "capabilities show",
+    method: "GET",
+    path: "/v1/capabilities",
+    description: "Returns the current API spec version plus a machine-readable changelog of capability changes (new endpoints, new fields, behavior fixes), newest first. Check it at session start — or after an unexpected response shape — to discover capabilities added since your integration was written. Free and unauthenticated.",
+    summary: "Capability changelog and API version discovery.",
+    positional: [],
+    outputDefault: "json",
+    pagination: "none",
+    stream: false,
+    billable: false,
+    idempotencyRequired: false,
+    scopesAny: [],
+    sideEffect: "read",
+    dryRunSupported: false,
+    inputSchema: {
+      type: "object",
+      properties: {},
+      additionalProperties: false
+    }
+  },
   "concepts.alerts": {
     cliKey: "concepts.alerts",
     cliName: "concepts alerts",
     method: "GET",
     path: "/v1/concepts/alerts",
-    description: `Returns the live \`concept_alerts:active\` hash. Two rules:
-  - big_move: abs(pct_change) > 3%
-  - limit_up_cluster: limit_up_count >= 3 AND stock_count >= 5
-See PLAN_CONCEPT_INDUSTRY_QUOTE §5.5 "异动检测与推送".
-`,
-    summary: "Currently active concept alerts (big_move / limit_up_cluster)",
+    description: "Returns the live set of concept alerts. Two rules fire: `big_move` when absolute percent change exceeds 3%, and `limit_up_cluster` when a concept has at least 3 limit-up members across at least 5 member stocks.",
+    summary: "List currently active concept alerts.",
     positional: [],
     outputDefault: "json",
     pagination: "none",
@@ -618,8 +627,8 @@ See PLAN_CONCEPT_INDUSTRY_QUOTE §5.5 "异动检测与推送".
     cliName: "concepts alerts-history",
     method: "GET",
     path: "/v1/concepts/alerts/history",
-    description: "Concept异动 historical events (default last 24h). Filter by rule (big_move / limit_up_cluster) and time window. Used by AI agent / admin review.",
-    summary: "Concept alerts history (last 24h)",
+    description: "Returns historical concept alert events (default: last 24 hours). Filter by rule (`big_move` / `limit_up_cluster`) and time window. Useful for reviewing how concept activity evolved over a period.",
+    summary: "List recent concept alert history.",
     positional: [],
     outputDefault: "json",
     pagination: "none",
@@ -668,10 +677,8 @@ See PLAN_CONCEPT_INDUSTRY_QUOTE §5.5 "异动检测与推送".
     cliName: "concepts daily-bars",
     method: "GET",
     path: "/v1/concepts/{concept_id}/daily-bars",
-    description: `Returns daily OHLC (concept index points, not stock prices average),
-breadth fields, and is_backfilled flag. See PLAN §5.4 algorithm.
-`,
-    summary: "Concept index daily bars (chain-linked equal-weight, base 1000)",
+    description: "Returns daily OHLC for a concept index (index points, not an average of member stock prices), along with breadth fields and a backfill flag. The concept index is a chain-linked equal-weight return series with a base of 1000.",
+    summary: "List daily bars for a concept index.",
     positional: [
       "concept_id"
     ],
@@ -716,8 +723,8 @@ breadth fields, and is_backfilled flag. See PLAN §5.4 algorithm.
     cliName: "concepts list",
     method: "GET",
     path: "/v1/concepts",
-    description: "Concept list joining CH `v_concept_meta` with Redis snapshot hashes,\nfollowing the hot/warm two-key pattern (PR #438):\n\nRead order **per concept** (not global):\n  1. `concept_snapshots:latest`     (hot, TTL 5min) — fresh tick\n  2. `concept_snapshots:last_close` (warm, TTL 7d)  — post-close / weekend\n  3. CH `v_concept_daily_bars` argMax                — extreme fallback (~ 7d+)\n\n9:00–9:14 pre-open reset window: hot + warm both suppressed (loading state),\nregardless of TTL; CH fallback is also disabled in this window.\n\nEach item carries `_source` ∈ {`latest`, `last_close`, `ch_daily`, `miss`}\nso the client can render a freshness badge.\n\nLive fields: pct_change / index_value / up/down_count / limit_up_count /\namount / speed_3min / `main_net_in`. `main_net_in` (元) is the concept-level\nsum of member-stocks' fundflow `main_net_in` (collector MGETs\n`stockpulse:fundflow:latest:{code}` each aggregation round). May be negative\n(net outflow); null when collector / Redis snapshot unavailable.\n\nSource / status / index are computed per PLAN_CONCEPT_INDUSTRY_QUOTE\n§5.4 algorithm (chain-linked equal-weight returns, base = 1000).\n",
-    summary: "List concepts with live snapshot (hot/warm fallback)",
+    description: "Lists market concepts (themes/sectors) joined with their latest real-time snapshot, falling back to the last close and then to recent daily data when live ticks are unavailable. Each item carries a `_source` freshness indicator. Live fields include percent change, index value, advancing/declining counts, limit-up count, turnover amount, 3-minute momentum, and `main_net_in` (net main-capital inflow in CNY, which may be negative for net outflow and null when unavailable). The concept index is a chain-linked equal-weight return series with a base of 1000. During the 9:00–9:14 pre-open window, live data is suppressed and a loading state is returned.",
+    summary: "List concepts with their live snapshot.",
     positional: [],
     outputDefault: "json",
     pagination: "none",
@@ -773,8 +780,8 @@ breadth fields, and is_backfilled flag. See PLAN §5.4 algorithm.
     cliName: "concepts minute-bars",
     method: "GET",
     path: "/v1/concepts/{concept_id}/minute-bars",
-    description: "Concept index minute-level OHLC (chain-linked equal-weight, base = 1000), max 7 days per request. See PLAN_CONCEPT_INDUSTRY_QUOTE §5.4.",
-    summary: "Concept index minute bars (max 7 days)",
+    description: "Returns minute-level OHLC for a concept index (chain-linked equal-weight return series, base 1000), up to 7 days per request.",
+    summary: "List minute bars for a concept index.",
     positional: [
       "concept_id"
     ],
@@ -819,10 +826,8 @@ breadth fields, and is_backfilled flag. See PLAN §5.4 algorithm.
     cliName: "concepts news",
     method: "GET",
     path: "/v1/concepts/{concept_id}/news",
-    description: `Short-term implementation: ILIKE on news.title + content with the
-concept name and full_name. Long-term: news AI tagging.
-`,
-    summary: "Related news matching concept name (ILIKE)",
+    description: "Returns recent news whose title or body mentions the concept's name. Use it to see what is currently driving a theme.",
+    summary: "List news related to a concept.",
     positional: [
       "concept_id"
     ],
@@ -869,8 +874,8 @@ concept name and full_name. Long-term: news AI tagging.
     cliName: "concepts show",
     method: "GET",
     path: "/v1/concepts/{concept_id}",
-    description: "Detail view for one concept: meta (full_name / source / status / approved_at / first_listed_at) plus current member securities with their latest snapshots.",
-    summary: "Concept detail (meta + member securities)",
+    description: "Returns detail for one concept: metadata (full name, source, status, approval date, first-listed date) plus its current member securities with their latest snapshots.",
+    summary: "Get concept detail with member securities.",
     positional: [
       "concept_id"
     ],
@@ -905,8 +910,8 @@ concept name and full_name. Long-term: news AI tagging.
     cliName: "concepts snapshot",
     method: "GET",
     path: "/v1/concepts/snapshot",
-    description: "Two contracts depending on `codes` parameter:\n\n- **With `codes=`** (per-key completeness): each requested id is resolved\n  via hot → warm → CH three-tier fallback. Missing ids are populated.\n- **Without `codes`** (best-effort dump): returns the **union** of\n  `concept_snapshots:latest` and `concept_snapshots:last_close` Redis\n  hashes. Concepts absent from both Redis hashes are **not** backfilled\n  from CH. Use GET `/v1/concepts` instead if you need every known concept.\n\n9:00–9:14 pre-open reset window: hot and warm both suppressed, CH fallback\nalso disabled; the endpoint returns an empty list (loading state).\n\nEach item carries `_source` ∈ {`latest`, `last_close`, `ch_daily`}.\n",
-    summary: "Bulk Redis snapshot of concepts (hot/warm union)",
+    description: "Returns real-time snapshots for concepts, with two modes. With `codes=`, each requested concept id is resolved via real-time → last-close → recent-daily fallback so every requested id is populated. Without `codes`, it returns a best-effort dump of all concepts that currently have a real-time or last-close snapshot; concepts absent from both are not backfilled (use `GET /v1/concepts` if you need every known concept). Each item carries a `_source` freshness indicator. During the 9:00–9:14 pre-open window, live data is suppressed and an empty list is returned.",
+    summary: "Bulk real-time snapshot of concepts.",
     positional: [],
     outputDefault: "json",
     pagination: "none",
@@ -936,8 +941,8 @@ concept name and full_name. Long-term: news AI tagging.
     cliName: "concepts views",
     method: "GET",
     path: "/v1/concepts/{concept_id}/views",
-    description: "JOIN concept_views × broker_views (ai_status=done) sorted by published_at desc.",
-    summary: "Broker views associated with this concept",
+    description: "Returns analyst views linked to this concept (with AI processing complete), sorted by publication date descending.",
+    summary: "List analyst views associated with a concept.",
     positional: [
       "concept_id"
     ],
@@ -977,25 +982,8 @@ concept name and full_name. Long-term: news AI tagging.
     cliName: "digest get",
     method: "GET",
     path: "/v1/digest/{code}",
-    description: `Composite endpoint: in one HTTP call returns views (PRIMARY research),
-real-time quote, valuation snapshot (PE/PB/PS/换手率/股息率/量比 等 14 字段),
-market sentiment context, and supplementary news.
-Partial-failure tolerant:
-each bucket is independently fetched and per-bucket failures surface
-in \`meta.partial_failures[]\` rather than poisoning the response. If
-every sub-bucket fails the endpoint returns 502.
-
-Bucket scopes are checked *per bucket* (not at gateway level): a
-token with only \`views:read\` gets the views bucket populated and the
-rest reported as \`scope_insufficient\` partial failures. This mirrors
-the CLI fan-out contract exactly so \`echopai digest\` can either call
-this endpoint (preferred, single round-trip) or fall back to local
-fan-out without behavior drift.
-
-See \`docs/PLAN_CLI_V2_AGENT_SURFACE.md\` §3.3 (digest spec) and §11
-Phase 5.2 (server endpoint).
-`,
-    summary: "One-shot research digest for a single security (composite)",
+    description: "Composite endpoint that, in a single call, returns separated sections for one security: analyst views (the primary research source), a real-time quote, a valuation snapshot (PE/PB/PS, turnover rate, dividend yield, volume ratio, and ~14 fields in total), market sentiment context, and supplementary news. Each section is fetched independently and per-section failures are reported in `meta.partial_failures[]` instead of failing the whole call; the endpoint returns 502 only if every section fails. Scopes are enforced per section, so a token with only `views:read` receives the views section and sees the rest reported as scope-insufficient. Use this when you want a single broad overview of a security (canonical code, e.g. `SSE:600519`).",
+    summary: "Build a one-shot research digest for one security.",
     positional: [
       "code"
     ],
@@ -1049,8 +1037,8 @@ Phase 5.2 (server endpoint).
     cliName: "financials pit",
     method: "GET",
     path: "/v1/financials/pit",
-    description: "基于 TDX 财务数据的 Point-in-time 查询。给定 `code` 和 `date`，返回该\n`trade_date` 当时市场上可见的最新一期财务报告（`announce_date <= date`，\n无公告日时保守延迟 90 天）。专为回测、AI agent、量化策略防未来函数泄漏。\n\n返回字段包括：EPS（基本/扣非/稀释）、BPS、ROE、毛利率、营收/净利润/总资产/\n归母权益等核心 ~25 字段。\n",
-    summary: "Point-in-time financial indicators for one A-share at a given date",
+    description: "Returns the most recent financial report that was publicly available on a given date for one A-share security (canonical code, e.g. `SSE:600519`) — i.e. announcement date on or before `date`, with a conservative 90-day fallback when the announcement date is unknown. Designed to avoid look-ahead bias in backtests and quantitative strategies. Fields include EPS (basic / non-recurring / diluted), BPS, ROE, gross margin, revenue, net profit, total assets, and parent-company equity (~25 core fields).",
+    summary: "Get point-in-time fundamentals for one security at a date.",
     positional: [],
     outputDefault: "json",
     pagination: "none",
@@ -1089,8 +1077,8 @@ Phase 5.2 (server endpoint).
     cliName: "financials quote-snapshot",
     method: "GET",
     path: "/v1/financials/quote-snapshot",
-    description: "一站式估值快照 —— 一次返回 14 个字段，**全部基于 TDX 原始数据 + Sina 实时\n价自算，不依赖 Tushare**：\n\n- 估值: `pe` / `pe_ttm` / `pb` / `ps` / `ps_ttm`\n- 股本（万股）: `total_share` / `float_share` / `free_share`\n- 市值（万元）: `total_mv` / `circ_mv`\n- 流动性: `turnover_rate` / `turnover_rate_f`（%）/ `volume_ratio`（倍）\n- 分红: `dv_ratio` / `dv_ttm`（%）\n\n计算口径：\n- PE-TTM = 当前总市值 / 近 4 季度滚动净利润（PIT 表 `ni_parent_ttm`）\n- PE     = 当前总市值 / 上年报净利润（`ni_parent_last1y`）\n- PB     = 当前总市值 / 归母净资产（`equity_parent`，PIT 防穿越）\n- 换手率 = 当日累计成交量 / 流通股本 × 100\n- 量比   = 当日累计 / 近 5 日同时段累计平均（实时模式）\n          / 近 5 日全日成交量平均（指定历史日期模式）\n- 股息率 = Σ(去年 / 近12月内派息事件 派现/10) / 现价 × 100\n\n默认 `date` 留空 → 实时（Sina 5s 快照价 + 当日累计成交量）；\n给 `date=YYYY-MM-DD` 则按当日 close 取值（用于历史回测 / 校验）。\n\n财报数据走 `security_financial_indicators_pit` PIT 视图：保证 `visible_date`\n≤ trade_date，避免未来函数。\n\n准确性已对照 Tushare `daily_basic` 校验（见 `scripts/validation/validate_quote_snapshot_vs_tushare.py`）。\n",
-    summary: "Real-time valuation / share / turnover snapshot for one A-share",
+    description: "Returns a one-stop valuation snapshot (14 fields) for one A-share security (canonical code, e.g. `SSE:600519`), combining real-time prices with point-in-time fundamentals so figures are free of look-ahead bias. Fields: valuation (`pe`, `pe_ttm`, `pb`, `ps`, `ps_ttm`); share counts in 10k shares (`total_share`, `float_share`, `free_share`); market cap in 10k CNY (`total_mv`, `circ_mv`); liquidity (`turnover_rate`, `turnover_rate_f` in %, `volume_ratio` as a multiple); and dividend yield (`dv_ratio`, `dv_ttm` in %). Leave `date` empty for a real-time snapshot, or pass `date=YYYY-MM-DD` to value as of that day's close (useful for historical checks and backtests).",
+    summary: "Get a real-time valuation snapshot for one security.",
     positional: [],
     outputDefault: "json",
     pagination: "none",
@@ -1130,8 +1118,8 @@ Phase 5.2 (server endpoint).
     cliName: "financials reports",
     method: "GET",
     path: "/v1/financials/reports",
-    description: "返回该股票最近 N 期财务报告的核心指标（EPS/BPS/ROE/毛利率/营收/净利润/总\n资产/归母权益/经营现金流/总股本 等 ~25 字段）。可按 `kind` 过滤季报/半年报/\n年报。每期 `announce_date` 字段告知何时市场可见，建议结合回测时使用。\n\n**`kind` 口径说明**：\n\n- `Q1` / `H1` / `Q3` / `annual` —— 四个标准季度末快照（3-31 / 6-30 /\n  9-30 / 12-31），TDX 财务源数据全部落在这四个 report_date。\n- `preliminary` —— **当前数据源结构上不存在**。业绩预告 / 快报 是 indicators\n  行内的字段（`forecast_ni_lower` / `forecast_ni_upper` /\n  `express_ni_parent` / `express_revenue` 等），通过 `financials.series`\n  metric 参数访问，不是单独的 report_kind 行。`kind=preliminary` 会返\n  空列表 + meta.note。\n",
-    summary: "Recent financial reports for one A-share security",
+    description: "Returns core indicators for the most recent N financial reports of one A-share security (EPS/BPS/ROE, gross margin, revenue, net profit, total assets, parent equity, operating cash flow, total shares, and ~25 fields in total). Filter by `kind` for quarterly / interim / annual reports. Each report's `announce_date` indicates when it became publicly visible, which is useful for point-in-time analysis. Note: `kind=preliminary` does not exist as a separate report row — earnings forecasts and flash reports are exposed as metric fields (e.g. `forecast_ni_lower`, `forecast_ni_upper`, `express_ni_parent`, `express_revenue`) via `financials.series`, so `kind=preliminary` returns an empty list with an explanatory note.",
+    summary: "List recent financial reports for one security.",
     positional: [],
     outputDefault: "json",
     pagination: "none",
@@ -1182,8 +1170,8 @@ Phase 5.2 (server endpoint).
     cliName: "financials series",
     method: "GET",
     path: "/v1/financials/series",
-    description: "返回某只股票某个财务指标的历史时间序列（按报告期排列）。`metric` 是\nindicators 表中的字段名（如 `roe_simple` / `revenue` / `ni_parent` /\n`debt_asset_ratio` / `gross_margin` / `eps_basic` 等共 150 个）。\n\n典型用法：画茅台 10 年 ROE 走势、对比 5 只白酒股 net_margin。\n",
-    summary: "Time series of a single financial metric for one security",
+    description: "Returns the historical time series of a single financial metric for one A-share security, ordered by reporting period. `metric` is an indicator field name (e.g. `roe_simple`, `revenue`, `ni_parent`, `debt_asset_ratio`, `gross_margin`, `eps_basic`; ~150 metrics available). Use it to chart a multi-year trend for one company or to compare the same metric across several securities.",
+    summary: "Get a time series of one financial metric.",
     positional: [],
     outputDefault: "json",
     pagination: "none",
@@ -1241,8 +1229,8 @@ Phase 5.2 (server endpoint).
     cliName: "index daily-bars",
     method: "GET",
     path: "/v1/index/bars/daily",
-    description: "指数日线 OHLC。覆盖 v2 表中的指数（上证综指 `SSE:000001` / 深证成指\n`SZSE:399001` / 沪深300 `SSE:000300` / 北证50 `BSE:899050` / 中证系列 `CSI:000922` 等）。\n与 `/v1/bars/daily` 同语义，但 index 没有 `turnover_rate` / `paused` 等股票特有字段。\n",
-    summary: "Daily OHLC bars for one A-share index",
+    description: "Returns daily OHLC for one A-share index (e.g. 上证综指 `SSE:000001`, 深证成指 `SZSE:399001`, 沪深300 `SSE:000300`, 北证50 `BSE:899050`, CSI series such as `CSI:000922`). Same semantics as `/v1/bars/daily`, but indices have no stock-specific fields such as turnover rate or suspension flag.",
+    summary: "List daily OHLC bars for one A-share index.",
     positional: [],
     outputDefault: "json",
     pagination: "none",
@@ -1290,8 +1278,8 @@ Phase 5.2 (server endpoint).
     cliName: "index minute-bars",
     method: "GET",
     path: "/v1/index/bars/minute",
-    description: "指数 1min OHLC。日期范围 ≤ 7 天（与 `/v1/bars/minute-batch` 对齐）。\n返回 `bar_time` / `trade_date` / OHLC / volume / amount / pct_change。\n",
-    summary: "Minute OHLC bars for one A-share index",
+    description: "Returns 1-minute OHLC for one A-share index over a date range of up to 7 days. Each bar includes bar time, trade date, OHLC, volume, amount, and percent change.",
+    summary: "List minute OHLC bars for one A-share index.",
     positional: [],
     outputDefault: "json",
     pagination: "none",
@@ -1337,8 +1325,8 @@ Phase 5.2 (server endpoint).
     cliName: "index snapshot",
     method: "GET",
     path: "/v1/index/snapshot",
-    description: "Returns the latest real-time snapshot for the 172 indices that Sina\nexposes a quote for (SSE / SZSE / BSE — includes 北证50 `BSE:899050`\nand 专精特新 `899601.BJ`). Source is the Redis hash\n`stockpulse:index_snapshots:latest` which the Rust collector refreshes\nevery ~15 seconds during market hours; outside trading hours the last\nintraday snapshot is returned.\n\nUse `codes` to narrow to a subset (canonical format `SSE:000001` (exchange-prefix; legacy `000001.SH` is also accepted but discouraged)).\nOmit to receive all 172.\n\nNote: CSI-series indices (e.g. `CSI:000922`) are not available here —\nSina has no quote feed for them. Daily/minute history for those still\nlives behind `/api/internal/index/{daily-bars,minute-bars-range}`.\n\nRequires `quote:l1`, `quote:l2`, or `quote:delayed` scope.\n",
-    summary: "Real-time snapshot of all Sina-OK A-share indices (172 indices)",
+    description: "Returns the latest real-time snapshot for the 172 A-share indices that have a live quote feed (SSE / SZSE / BSE, including 北证50 `BSE:899050`). The snapshot refreshes roughly every 15 seconds during market hours; outside trading hours the last intraday snapshot is returned. Use `codes` (canonical format, e.g. `SSE:000001`) to narrow to a subset, or omit it to receive all indices. Note: CSI-series indices (e.g. `CSI:000922`) have no live quote feed and are not returned here. Requires a `quote:l1`, `quote:l2`, or `quote:delayed` scope.",
+    summary: "Snapshot real-time quotes for A-share indices.",
     positional: [],
     outputDefault: "json",
     pagination: "none",
@@ -1364,197 +1352,13 @@ Phase 5.2 (server endpoint).
       additionalProperties: false
     }
   },
-  "industries.alerts": {
-    cliKey: "industries.alerts",
-    cliName: "industries alerts",
-    method: "GET",
-    path: "/v1/industries/alerts",
-    description: "Currently active industry alerts (big_move / limit_up_cluster). Same rule set as concepts.",
-    summary: "Currently active industry alerts",
-    positional: [],
-    outputDefault: "json",
-    pagination: "none",
-    stream: false,
-    billable: false,
-    idempotencyRequired: false,
-    scopesAny: [
-      "quote:l1",
-      "quote:l2",
-      "quote:delayed"
-    ],
-    sideEffect: "read",
-    dryRunSupported: false,
-    inputSchema: {
-      type: "object",
-      properties: {},
-      additionalProperties: false
-    }
-  },
-  "industries.daily-bars": {
-    cliKey: "industries.daily-bars",
-    cliName: "industries daily-bars",
-    method: "GET",
-    path: "/v1/industries/{key}/daily-bars",
-    description: "Industry index daily OHLC (chain-linked equal-weight, base = 1000). Path key format `<sw_industry_code>:<sw_level>` (e.g. `401001:1`).",
-    summary: "Industry index daily bars",
-    positional: [
-      "key"
-    ],
-    outputDefault: "json",
-    pagination: "none",
-    stream: false,
-    billable: true,
-    idempotencyRequired: false,
-    scopesAny: [
-      "bars:read"
-    ],
-    sideEffect: "read",
-    dryRunSupported: false,
-    inputSchema: {
-      type: "object",
-      properties: {
-        key: {
-          type: "string",
-          description: "Industry key in `<sw_industry_code>:<sw_level>` format (e.g. `401001:1`).",
-          example: "401001:1"
-        },
-        from: {
-          type: "string",
-          format: "date",
-          description: "Window start. For daily/minute bars: ISO date `YYYY-MM-DD`. For alerts history: Unix milliseconds (default = now - 24h)."
-        },
-        to: {
-          type: "string",
-          format: "date",
-          description: "Window end. For daily/minute bars: ISO date `YYYY-MM-DD`. For alerts history: Unix milliseconds (default = now)."
-        }
-      },
-      additionalProperties: false,
-      required: [
-        "key",
-        "from",
-        "to"
-      ]
-    }
-  },
-  "industries.list": {
-    cliKey: "industries.list",
-    cliName: "industries list",
-    method: "GET",
-    path: "/v1/industries",
-    description: "Industry index list joining CH `v_industry_meta` with Redis snapshot.\n申万一级 (level=1) ≈ 127 industries, 申万二级 (level=2) ≈ 348.\nChain-linked equal-weight algorithm identical to concepts (PLAN §5.4).\n\nRead order per industry (mirrors `/v1/concepts`, PR #442):\n  1. `industry_snapshots:latest`     (hot, TTL 5min)\n  2. `industry_snapshots:last_close` (warm, TTL 7d)\n  3. CH `v_industry_daily_bars` argMax\n9:00–9:14 reset window suppresses hot+warm (loading state).\nEach item carries `_source` ∈ {`latest`, `last_close`, `ch_daily`, `miss`}.\n",
-    summary: "List industries (申万 L1/L2) with hot/warm fallback",
-    positional: [],
-    outputDefault: "json",
-    pagination: "none",
-    stream: false,
-    billable: true,
-    idempotencyRequired: false,
-    scopesAny: [
-      "quote:l1",
-      "quote:l2",
-      "quote:delayed"
-    ],
-    sideEffect: "read",
-    dryRunSupported: false,
-    inputSchema: {
-      type: "object",
-      properties: {
-        level: {
-          type: "integer",
-          enum: [
-            1,
-            2
-          ],
-          default: 1,
-          description: "申万 industry level (1 or 2)."
-        },
-        limit: {
-          type: "integer",
-          minimum: 1,
-          maximum: 1000,
-          default: 500,
-          description: "Maximum number of items to return."
-        }
-      },
-      additionalProperties: false
-    }
-  },
-  "industries.show": {
-    cliKey: "industries.show",
-    cliName: "industries show",
-    method: "GET",
-    path: "/v1/industries/{key}",
-    description: "Path key format: `<sw_industry_code>:<sw_level>` (e.g. `401001:1`).",
-    summary: "Industry detail (meta + today members)",
-    positional: [
-      "key"
-    ],
-    outputDefault: "json",
-    pagination: "none",
-    stream: false,
-    billable: true,
-    idempotencyRequired: false,
-    scopesAny: [
-      "quote:l1",
-      "quote:l2",
-      "quote:delayed"
-    ],
-    sideEffect: "read",
-    dryRunSupported: false,
-    inputSchema: {
-      type: "object",
-      properties: {
-        key: {
-          type: "string",
-          description: "Industry key in `<sw_industry_code>:<sw_level>` format (e.g. `401001:1`).",
-          example: "401001:1"
-        }
-      },
-      additionalProperties: false,
-      required: [
-        "key"
-      ]
-    }
-  },
-  "industries.snapshot": {
-    cliKey: "industries.snapshot",
-    cliName: "industries snapshot",
-    method: "GET",
-    path: "/v1/industries/snapshot",
-    description: "Mirrors `/v1/concepts/snapshot` contract (PR #442 review 二轮):\n\n- **With `codes=`** (per-key completeness): hot → warm → CH fallback\n  per industry; missing keys populated.\n- **Without `codes`** (best-effort dump): union of\n  `industry_snapshots:latest` and `industry_snapshots:last_close`\n  Redis hashes. Missing industries are **not** backfilled from CH; use\n  GET `/v1/industries` for a fully populated list.\n\n9:00–9:14 reset window suppresses both Redis hashes and CH fallback.\nEach item carries `_source` ∈ {`latest`, `last_close`, `ch_daily`}.\n申万一级 (level=1) ≈ 127 industries, 申万二级 (level=2) ≈ 348.\n",
-    summary: "Bulk Redis snapshot of industries (hot/warm union)",
-    positional: [],
-    outputDefault: "json",
-    pagination: "none",
-    stream: false,
-    billable: true,
-    idempotencyRequired: false,
-    scopesAny: [
-      "quote:l1",
-      "quote:l2",
-      "quote:delayed"
-    ],
-    sideEffect: "read",
-    dryRunSupported: false,
-    inputSchema: {
-      type: "object",
-      properties: {
-        codes: {
-          type: "string",
-          description: "Comma-separated `sw_code:level` (e.g. `401001:1,401002:1`); omit for best-effort Redis union."
-        }
-      },
-      additionalProperties: false
-    }
-  },
   "limit-up.analysis": {
     cliKey: "limit-up.analysis",
     cliName: "limit-up analysis",
     method: "GET",
     path: "/v1/limit-up/analysis",
-    description: '涨停股 LLM 归因：逐股「主导题材 leading_concept + 概念标签 concept_tags +\n涨停理由 reason」。题材由 LLM 依据最新研报 / 机构观点 / 快讯判定，**不依赖概念\n图谱**（可含图谱里还没有的全新题材），每交易日北京 9:45 / 11:00 / 12:30 / 14:00 /\n14:40 / 18:00 共 6 个时段自动刷新（后跑时段在前次基础上 refine）。\n\n与 `limit-up/pool` 互补：pool 给"涨停了哪些票"（行情数据，stockpulse 上游），\n本接口给"为什么涨停 / 属什么题材"（LLM 归因，echopai api 上游）。pool 里的\ngraph-based `leading_concept` 是另一条数据，本接口的 `leading_concept` 才是\nLLM 判定结果。\n\n⚠️ **trade_date 不传 = 库内最新「已归因」交易日**（非自然最新交易日）：归因每个\n时段按当时池快照写库，今日**首个时段（北京约 09:47）落库前**，不传 trade_date\n会返回**上一交易日**的归因（不是今日空结果）——agent 拿当日数据请显式传今日\ntrade_date 并以 `trade_date` / `generated_at` 字段核对时效。显式传某交易日而该日\n尚未归因时，`analyses` 为空。\n\n平面归属：本接口在 **vu 平面**（前端 apiFetch 同源），与 `market/status` 同款\n`x-audience: vu`；行情类 `limit-up/pool|summary|history` 在 sp 平面（前端 spFetch）。\n需要 `market:read` 或任一 `quote:*` scope。\n',
-    summary: "A-share limit-up LLM attribution (per-stock leading theme + reason)",
+    description: "Returns LLM-generated attribution for each limit-up stock: the leading theme (`leading_concept`), concept tags, and a reason explaining why it hit the limit. Themes are inferred by an LLM from the latest research, institutional views, and news, so they may include brand-new themes; results refresh automatically at six points each trading day, with later runs refining earlier ones. This complements the limit-up pool, which tells you which stocks limited up; this endpoint tells you why and under which theme. Note: when `trade_date` is omitted, the latest attributed trading day is returned — before today's first run completes (around 09:47 Beijing time) this may be the previous trading day rather than empty, so pass an explicit `trade_date` for today and verify the `trade_date` / `generated_at` fields. Requires the `market:read` scope or any `quote:*` scope.",
+    summary: "Get LLM attribution for limit-up stocks.",
     positional: [],
     outputDefault: "json",
     pagination: "none",
@@ -1586,8 +1390,8 @@ Phase 5.2 (server endpoint).
     cliName: "limit-up history",
     method: "GET",
     path: "/v1/limit-up/history",
-    description: "近 N 个交易日每日涨停数 + 最高连板 + 炸板数。涨停数 / 最高连板来源\n`market_limit_up_pool` (仅 status=limit_up)；炸板数来源\n`market_breadth_intraday`（all_a_ex_st 当日最新分钟行）。\n\n响应按 trade_date asc 排序（旧日期在前）。需要 `quote:*` scope。\n",
-    summary: "A-share limit-up daily trend (last N days)",
+    description: "Returns the daily limit-up trend over the last N trading days: per-day limit-up count, highest consecutive-board height, and seal-break count. Sorted by trade date ascending (oldest first). Requires a `quote:*` scope.",
+    summary: "Get the A-share limit-up daily trend.",
     positional: [],
     outputDefault: "json",
     pagination: "none",
@@ -1620,8 +1424,8 @@ Phase 5.2 (server endpoint).
     cliName: "limit-up pool",
     method: "GET",
     path: "/v1/limit-up/pool",
-    description: "当日（或指定 `trade_date`）涨停股池逐股明细：首/末次封板时间、最终涨幅、\n封单金额/封单量、炸板次数、连板数、N 日板内统计、一字板标记、当前 status\n(limit_up / broken)、板块分类。\n\n盘前回退规则（与所有行情类页面一致）：\n  - `< 9:00`：返回 max(trade_date) 的最新一日数据（昨日）\n  - `9:00-9:14`：集合竞价前空窗期，items=[] / trade_date=null\n  - `>= 9:15`：collector 已写入今日数据\n\n排序：连板数 desc → 板内板数 desc → 封单金额 desc。需要 `quote:*` scope。\n",
-    summary: "A-share limit-up pool (per-stock detail) for a given trade date",
+    description: "Returns per-stock detail for the limit-up pool on the current (or specified `trade_date`) trading day: first/last seal time, final percent change, seal amount and seal volume, number of times the seal broke, consecutive limit-up days, in-pool statistics over N days, one-line-board flag, current status (limit_up / broken), and sector classification. Sorted by consecutive limit-up days, then in-pool board count, then seal amount (all descending). Before 9:00 the previous trading day's data is returned; during 9:00–9:14 an empty result is returned; from 9:15 today's data is available. Requires a `quote:*` scope.",
+    summary: "List the A-share limit-up pool for a trade date.",
     positional: [],
     outputDefault: "json",
     pagination: "none",
@@ -1655,7 +1459,7 @@ Phase 5.2 (server endpoint).
         include_broken: {
           type: "boolean",
           default: false,
-          description: "true 时连炸板（status=broken）也一起返回；默认只返回当前封板 status=limit_up。"
+          description: "true 时连真炸板（盘中封板后跌出、当前未回封，status=broken）也一起返回；默认只返回当前封板 status=limit_up。"
         }
       },
       additionalProperties: false
@@ -1666,8 +1470,8 @@ Phase 5.2 (server endpoint).
     cliName: "limit-up summary",
     method: "GET",
     path: "/v1/limit-up/summary",
-    description: "涨停股池聚合统计：涨停数、炸板数、跌停数、最高连板高度、连板梯队\n`ladder: [{ height, count }, ...]`。\n\n炸板数 / 跌停数 与情绪页同源（`market_breadth_intraday` 当日最新分钟行）；\n连板梯队仅统计当前封板 status=limit_up 的个股。\n\n盘前回退规则与 `limit-up/pool` 一致。需要 `quote:*` scope。\n",
-    summary: "A-share limit-up summary (counts + height ladder) for a given trade date",
+    description: "Returns aggregate limit-up statistics for the trade date: limit-up count, seal-break count, limit-down count, the highest consecutive-board height, and a height ladder (`ladder: [{ height, count }, ...]`). The height ladder counts only stocks currently sealed at limit-up. Pre-open fallback follows the same rules as the limit-up pool. Requires a `quote:*` scope.",
+    summary: "Summarize A-share limit-up activity for a trade date.",
     positional: [],
     outputDefault: "json",
     pagination: "none",
@@ -1707,8 +1511,8 @@ Phase 5.2 (server endpoint).
     cliName: "market status",
     method: "GET",
     path: "/v1/market/status",
-    description: "Current A-share market session: pre-open / open / lunch / closed; current and next trading day; holiday flag. Requires `market:read` or any `quote:*` scope.",
-    summary: "Current A-share market session state",
+    description: "Returns the current A-share trading session (pre-open / open / lunch / closed), the current and next trading day, and a holiday flag. Requires the `market:read` scope or any `quote:*` scope.",
+    summary: "Get the current A-share market session state.",
     positional: [],
     outputDefault: "json",
     pagination: "none",
@@ -1734,8 +1538,8 @@ Phase 5.2 (server endpoint).
     cliName: "news feed",
     method: "GET",
     path: "/v1/news",
-    description: "与 `/v1/news/list` 行为一致，旧客户端兼容用。",
-    summary: "List recent news (alias of /v1/news/list)",
+    description: "Returns recent news. Equivalent to `/v1/news/list`; retained for backward compatibility. Partner/agent callers receive `fields=compact` by default (id, title, ai_summary, tagged securities, first ~300 chars of content); pass `fields=full` for complete content.",
+    summary: "List recent news.",
     positional: [],
     outputDefault: "json",
     pagination: "offset",
@@ -1747,7 +1551,16 @@ Phase 5.2 (server endpoint).
     dryRunSupported: false,
     inputSchema: {
       type: "object",
-      properties: {},
+      properties: {
+        fields: {
+          type: "string",
+          enum: [
+            "compact",
+            "full"
+          ],
+          description: "Response shape: `compact` (the default for partner/agent callers) returns id, title, ai_summary, tagged securities, and the first ~300 chars of content with a `content_truncated` flag; `full` returns complete content."
+        }
+      },
       additionalProperties: false
     }
   },
@@ -1756,8 +1569,8 @@ Phase 5.2 (server endpoint).
     cliName: "news get",
     method: "GET",
     path: "/v1/news/{news_id}",
-    description: "返回新闻完整内容：title、content snippet、tagged securities。（采集端字段 source / source_id / source_url 对外不暴露，admin 路径 /v1/admin/news/{id} 可见。）",
-    summary: "Fetch a single news item by id",
+    description: "Returns the full content of one news item: title, content snippet, and tagged securities.",
+    summary: "Get a single news item by id.",
     positional: [
       "news_id"
     ],
@@ -1788,8 +1601,8 @@ Phase 5.2 (server endpoint).
     cliName: "news list",
     method: "GET",
     path: "/v1/news/list",
-    description: "List news mentioning a specific A-share security, ordered by published_at desc. Requires `news:read` scope.",
-    summary: "List news mentioning a specific security",
+    description: "Returns news items mentioning a specific A-share security, ordered by publication date descending. Requires the `news:read` scope.",
+    summary: "List news mentioning one security.",
     positional: [],
     outputDefault: "json",
     pagination: "none",
@@ -1839,6 +1652,14 @@ Phase 5.2 (server endpoint).
           minimum: 0,
           default: 0,
           description: "Pagination offset (page through long history ranges)."
+        },
+        fields: {
+          type: "string",
+          enum: [
+            "compact",
+            "full"
+          ],
+          description: "Response shape: `compact` (the default for partner/agent callers) returns id, title/ai_summary, attribution, tagged securities, and the first ~300 chars of content with a `content_truncated` flag; `full` returns complete content. Prefer compact for scanning; fetch full text per item only when needed."
         }
       },
       additionalProperties: false,
@@ -1852,8 +1673,8 @@ Phase 5.2 (server endpoint).
     cliName: "news search",
     method: "GET",
     path: "/v1/news/search",
-    description: "Full-text search recent news / market briefs. Returns title, published_at, snippet, tagged securities. (Internal collector identifiers — `source`/`source_id`/`source_url` — are NOT exposed publicly; admin tools see them via /v1/admin/*.) Requires `news:read` scope. Note: news fields are user-generated; meta.untrusted_text_fields lists fields that need sanitization before passing to an LLM.",
-    summary: "Full-text search recent news",
+    description: "Full-text search over recent news and market briefs. Returns title, publication date, snippet, and tagged securities. Requires the `news:read` scope. Note: news fields are user-generated; `meta.untrusted_text_fields` lists fields that should be sanitized before being passed to an LLM.",
+    summary: "Full-text search recent news.",
     positional: [],
     outputDefault: "json",
     pagination: "none",
@@ -1904,6 +1725,14 @@ Phase 5.2 (server endpoint).
           minimum: 0,
           default: 0,
           description: "Pagination offset (page through long history ranges)."
+        },
+        fields: {
+          type: "string",
+          enum: [
+            "compact",
+            "full"
+          ],
+          description: "Response shape: `compact` (the default for partner/agent callers) returns id, title/ai_summary, attribution, tagged securities, and the first ~300 chars of content with a `content_truncated` flag; `full` returns complete content. Prefer compact for scanning; fetch full text per item only when needed."
         }
       },
       additionalProperties: false,
@@ -1917,10 +1746,8 @@ Phase 5.2 (server endpoint).
     cliName: "ownership lockups",
     method: "GET",
     path: "/v1/ownership-events/lockups",
-    description: `全市场未来 days 天即将解禁扫描，按解禁日升序 + 占比降序。前瞻抛压预警，
-digest 给不了（digest 是单 code 维度）。min_pct 过滤小额解禁，limit 控量。
-`,
-    summary: "Scan upcoming share-lockup expirations across the whole market",
+    description: "Scans the whole market for share lockups expiring within the next `days` days, sorted by unlock date ascending then by unlocking ratio descending — a forward-looking selling-pressure screen across all securities. Use `min_pct` to filter out small unlocks and `limit` to cap the result size. T+1 data.",
+    summary: "Scan upcoming share-lockup expirations market-wide.",
     positional: [],
     outputDefault: "json",
     pagination: "none",
@@ -1965,20 +1792,8 @@ digest 给不了（digest 是单 code 维度）。min_pct 过滤小额解禁，l
     cliName: "ownership show",
     method: "GET",
     path: "/v1/ownership-events",
-    description: `单股股权事件三合一结构化字段，给研究 agent 一眼可读的「近 30 天增减持/回购
-+ 未来 30 天限售解禁」。源 Tushare（T+1），落 PG 专表幂等同步。
-
-- shareholder_transactions：增减持回看 txn_days 天，含净增减股数/比例 +
-  增减笔数 + 明细（方向/股东/均价/区间）。
-- share_repurchases：回购回看 repurchase_days 天，含在进行笔数 + 已执行
-  累计金额/股数（仅计 in_progress/completed）+ 最新进度 + 明细。
-- lockup_expirations：解禁前瞻 lockup_days 天（unlock_date ∈ [today,
-  today+N]），含合计解禁股数/占比 + 最近解禁日 + 明细。前瞻抛压预警。
-
-枚举 slug（direction / holder_category / status / lockup_type）见
-docs/OWNERSHIP_EVENTS.md。
-`,
-    summary: "Ownership events for one A-share (holder trades / repurchases / lockups)",
+    description: "Returns a structured three-in-one view of ownership events for one A-share security (canonical code, e.g. `SSE:600519`): recent shareholder transactions, recent share repurchases, and upcoming lockup expirations. T+1 data. Shareholder transactions look back `txn_days` days and include net change in shares/ratio, transaction count, and per-transaction detail (direction, holder, average price, date range). Repurchases look back `repurchase_days` days and include in-progress count, cumulative executed amount/shares, latest progress, and detail. Lockup expirations look ahead `lockup_days` days and include total unlocking shares/ratio, the nearest unlock date, and detail — useful as a forward-looking selling-pressure warning. Enum values (direction, holder category, status, lockup type) are documented in the response schema.",
+    summary: "Get ownership events for one security.",
     positional: [],
     outputDefault: "json",
     pagination: "none",
@@ -2027,35 +1842,13 @@ docs/OWNERSHIP_EVENTS.md。
       ]
     }
   },
-  "payment.plans": {
-    cliKey: "payment.plans",
-    cliName: "payment plans",
-    method: "GET",
-    path: "/v1/payment/plans",
-    description: "返回订阅计划清单（plan_id + 价格 + 时长 + 描述）。",
-    summary: "List subscription plans",
-    positional: [],
-    outputDefault: "json",
-    pagination: "none",
-    stream: false,
-    billable: false,
-    idempotencyRequired: false,
-    scopesAny: [],
-    sideEffect: "read",
-    dryRunSupported: false,
-    inputSchema: {
-      type: "object",
-      properties: {},
-      additionalProperties: false
-    }
-  },
   quote: {
     cliKey: "quote",
     cliName: "quote",
     method: "GET",
     path: "/v1/quote/realtime",
-    description: "Real-time quote for one or more A-share securities. Returns last price, volume, change %, bid/ask. Up to 200 codes per call. Requires `quote:l1`, `quote:l2`, or `quote:delayed` scope.",
-    summary: "Real-time quote for one or more A-share securities",
+    description: "Returns real-time quotes for one or more A-share securities (canonical codes, e.g. `SSE:600519`): last price, volume, percent change, and bid/ask. Up to 200 codes per call. The response carries a `session` label (`pre_open` / `auction` / `open` / `break` / `closed`) and, outside continuous trading, an explanatory `note`: during 9:00–9:14 pre-open the previous session's snapshot is returned; during the 9:15–9:29 call auction, prices are indicative auction match prices. Rows whose feed has stopped updating (suspension / feed drop) keep their last snapshot and are flagged `stale: true` with `stale_since`. Requires a `quote:l1`, `quote:l2`, or `quote:delayed` scope.",
+    summary: "Get real-time quotes for one or more securities.",
     positional: [],
     outputDefault: "json",
     pagination: "none",
@@ -2105,8 +1898,8 @@ docs/OWNERSHIP_EVENTS.md。
     cliName: "quote scan",
     method: "GET",
     path: "/v1/quote/scan",
-    description: 'Dumps the entire Redis snapshot of A-share real-time quotes in a single\nround-trip. Use for "全市场扫描" / agent universe-of-interest discovery\nwhen you don\'t yet know which codes to query.\n\nFiltering:\n- `exchange=SSE|SZSE|BSE` narrows to one exchange (canonical_code prefix)\n- `app.allowed_securities` is ALWAYS applied; codes outside drop silently\n\nResponse size: ~3 MB unfiltered (~5800 items). CLI users should pair\nwith `--max-bytes` / `--fields` / `--query` from Phase 1.4.\n\n9:00–9:14 集合竞价时段返回空 items + `note` 字段说明。\n\nEach item also includes `main_net_in` (元, may be negative) — current-day\ncumulative main-capital net inflow merged from fundflow snapshot via\nhot/warm two-key pattern (PR #438):\n  - `stockpulse:fundflow:latest:{code}`     (hot, TTL 180s) for fresh\n  - `stockpulse:fundflow:last_close:{code}` (warm, TTL 7d)  for post-close\nCompanion field `main_net_in_stale` (boolean): false = fresh from hot,\ntrue = served from warm (post-close / weekend / collector down).\nTreated as a public field (same tier as `amount`); not scrubbed under\nany scope.\n\nRequires `quote:l1`, `quote:l2`, or `quote:delayed` scope.\n',
-    summary: "Full-market real-time quote scan (~5800 A-share securities)",
+    description: "Returns a real-time quote for every A-share in a single call — use it for full-market scans or to discover a universe of interest when you do not yet know which codes to query. Filter with `exchange=SSE|SZSE|BSE` to narrow to one exchange. The payload is large (~3 MB, ~5,800 instruments), so pair it with `--fields`, `--jq`, or `--max-bytes` to trim it. The response carries a `session` label (`pre_open` / `auction` / `open` / `break` / `closed`) plus an explanatory `note` outside continuous trading: during 9:00–9:14 pre-open the previous session's snapshot is returned; during the 9:15–9:29 call auction, prices are indicative auction match prices. Instruments whose feed has stopped updating (suspension / feed drop) are excluded from the default scan; pass `include=all` to keep them, flagged with `stale: true` and `stale_since`. Each item also includes `main_net_in` (current-day cumulative net main-capital inflow in CNY, which may be negative) and a companion `main_net_in_stale` flag (true when served from the last-close fallback). Requires a `quote:l1`, `quote:l2`, or `quote:delayed` scope.",
+    summary: "Snapshot every A-share real-time quote in one call.",
     positional: [],
     outputDefault: "json",
     pagination: "none",
@@ -2134,6 +1927,15 @@ docs/OWNERSHIP_EVENTS.md。
             "bse"
           ],
           description: "Filter by exchange: SSE / SZSE / BSE (case-insensitive). Omit for all."
+        },
+        include: {
+          type: "string",
+          enum: [
+            "active",
+            "all"
+          ],
+          default: "active",
+          description: "`active` (default) excludes ST, delisted, and stale (feed-dropped / suspended) instruments; `all` returns the full set with stale rows flagged."
         }
       },
       additionalProperties: false
@@ -2144,15 +1946,8 @@ docs/OWNERSHIP_EVENTS.md。
     cliName: "search semantic",
     method: "GET",
     path: "/v1/search",
-    description: `语义 + 模糊泛化搜索。结合 entity 精确匹配（公司代码/分析师）、向量召回（pgvector
-+ DashScope embedding）、trigram 模糊、ILIKE 精确四路召回，RRF 融合后用 reranker
-精排，叠时间衰减 + views 加权（views 主源优先）。
-
-- 搜"锂电池"会带出新能源产业链（正极/负极/碳酸锂/宁德时代…）
-- 搜"芯片"会带出存储芯片/洁净室/晶圆代工…
-- mode=exact 兼容老 ILIKE 行为，仅在精确关键词命中时返回。
-`,
-    summary: "Hybrid semantic search across news + analyst views",
+    description: 'Hybrid semantic search across news and analyst views that generalizes beyond exact keywords. It combines exact entity matching (security codes, analysts), semantic (embedding-based) recall, and fuzzy matching, then fuses and re-ranks results with time decay and a weighting toward analyst views as the primary source. For example, searching "锂电池" surfaces the broader new-energy supply chain (cathode/anode materials, lithium carbonate, leading battery makers). Pass `mode=exact` for legacy exact-keyword behavior.',
+    summary: "Semantic search across news and analyst views.",
     positional: [],
     outputDefault: "json",
     pagination: "none",
@@ -2214,52 +2009,13 @@ docs/OWNERSHIP_EVENTS.md。
       ]
     }
   },
-  "securities.industry": {
-    cliKey: "securities.industry",
-    cliName: "securities industry",
-    method: "GET",
-    path: "/v1/securities/industry",
-    description: `返回该股票的 TDX 自定义行业代码（T1001 食品饮料等）与申万行业三级代码
-L1/L2/L3（X5001 食品饮料 / X500102 白酒 等）。
-
-用法：
-- 股票详情页"申万行业：白酒 / 食品饮料"标签
-- 筛选器交叉过滤：行业 + ROE/营收增长率
-- AI agent \`find_peers(code)\` 用申万二级行业找同业
-`,
-    summary: "TDX + 申万 industry classification for one A-share security",
-    positional: [],
-    outputDefault: "json",
-    pagination: "none",
-    stream: false,
-    billable: false,
-    idempotencyRequired: false,
-    scopesAny: [],
-    sideEffect: "read",
-    dryRunSupported: false,
-    inputSchema: {
-      type: "object",
-      properties: {
-        code: {
-          type: "string",
-          description: "A-share canonical code (SSE/SZSE/BSE only). For quote/chart/bars/financials endpoints.",
-          pattern: "^(SSE|SZSE|BSE|SH|SZ|BJ):[0-9]{6}$",
-          example: "SSE:600519"
-        }
-      },
-      additionalProperties: false,
-      required: [
-        "code"
-      ]
-    }
-  },
   "semantic.find": {
     cliKey: "semantic.find",
     cliName: "semantic find",
     method: "GET",
     path: "/v1/securities/search",
-    description: "Find A-share securities matching a name (Chinese), code (e.g. 600519), or pinyin initials (e.g. gzmt). Use this when an agent has a description and needs canonical codes.",
-    summary: "Find A-share securities by name / code / pinyin",
+    description: "Finds A-share securities matching a Chinese name, a code (e.g. `600519`), or pinyin initials (e.g. `gzmt`). Use it to turn a free-form description into canonical codes (e.g. `SSE:600519`).",
+    summary: "Resolve A-share securities by name, code, or pinyin.",
     positional: [],
     outputDefault: "json",
     pagination: "none",
@@ -2298,8 +2054,8 @@ L1/L2/L3（X5001 食品饮料 / X500102 白酒 等）。
     cliName: "sentiment breadth",
     method: "GET",
     path: "/v1/sentiment/breadth",
-    description: "Intraday breadth time series for one trading day.\n`trade_date` 缺省 → 今日（盘前 9:00 前返回空 items）；显式传 YYYY-MM-DD 可\n拉历史任意交易日（来源 ClickHouse `market_breadth_intraday`，剔除 13:00\n稀疏分钟，单日最多 241 行）。Requires `sentiment:read` scope.\n",
-    summary: "Intraday breadth time series",
+    description: "Returns the intraday market-breadth time series for one trading day. Omit `trade_date` for today (returns empty before 9:00); pass `YYYY-MM-DD` for any historical trading day (sparse minutes around the lunch break are excluded; up to 241 rows per day). Requires the `sentiment:read` scope.",
+    summary: "Get the intraday market-breadth time series.",
     positional: [],
     outputDefault: "json",
     pagination: "none",
@@ -2341,8 +2097,8 @@ L1/L2/L3（X5001 食品饮料 / X500102 白酒 等）。
     cliName: "sentiment overview",
     method: "GET",
     path: "/v1/sentiment/overview",
-    description: "Aggregate sentiment snapshot for one trading day's latest minute:\nlimit-up/down counts, breadth, divergence index, MA / 52w breadth.\n`trade_date` 缺省 → 今日（Redis 实时，盘前 9:00 前返空结构）；显式传\nYYYY-MM-DD 拉历史任意日（最后一分钟聚合行，来源 ClickHouse\n`market_breadth_intraday`）。Requires `sentiment:read` scope.\n",
-    summary: "Aggregate market sentiment indicators",
+    description: "Returns an aggregate sentiment snapshot for the latest minute of one trading day: limit-up/down counts, breadth, divergence index, and moving-average / 52-week breadth. Omit `trade_date` for today's real-time snapshot (returns an empty structure before 9:00); pass `YYYY-MM-DD` for any historical day (the day's final aggregated minute). Requires the `sentiment:read` scope.",
+    summary: "Get aggregate market sentiment indicators.",
     positional: [],
     outputDefault: "json",
     pagination: "none",
@@ -2385,8 +2141,8 @@ L1/L2/L3（X5001 食品饮料 / X500102 白酒 等）。
     cliName: "sentiment pct-distribution",
     method: "GET",
     path: "/v1/sentiment/pct-distribution",
-    description: "返回 A 股全市场涨跌幅分桶（≤-10% / -9% / ... / +10% / 涨停）的家数分布，用于市场宽度可视化。",
-    summary: "Distribution of intraday percent change across the universe",
+    description: "Returns the distribution of intraday percent change across the full A-share universe, bucketed (≤-10% / -9% / ... / +10% / limit-up), for visualizing market breadth.",
+    summary: "Get the intraday percent-change distribution.",
     positional: [],
     outputDefault: "json",
     pagination: "none",
@@ -2409,8 +2165,8 @@ L1/L2/L3（X5001 食品饮料 / X500102 白酒 等）。
     cliName: "sentiment turnover",
     method: "GET",
     path: "/v1/sentiment/turnover",
-    description: "Intraday turnover time series across one or more trading days.\n`trade_date` 缺省 → 今日（盘前 9:00 前返空 items）；显式 YYYY-MM-DD 拉\n历史任意交易日的当日 + 之前 `days-1` 天。Response 含 `current_turnover`\n/ `predicted_total` / `delta_vs_yesterday` headline 字段。Requires\n`sentiment:read` scope.\n",
-    summary: "Intraday turnover time series",
+    description: "Returns the intraday turnover time series across one or more trading days. Omit `trade_date` for today (returns empty before 9:00); pass `YYYY-MM-DD` for that day plus the preceding `days-1` days. The response includes headline fields `current_turnover`, `predicted_total`, and `delta_vs_yesterday`. Requires the `sentiment:read` scope.",
+    summary: "Get the intraday turnover time series.",
     positional: [],
     outputDefault: "json",
     pagination: "none",
@@ -2459,8 +2215,8 @@ L1/L2/L3（X5001 食品饮料 / X500102 白酒 等）。
     cliName: "stocks hot",
     method: "GET",
     path: "/v1/stocks/hot",
-    description: "今日最热股票榜（来源 East-Money），按搜索 / 关注 / 评论综合分排序。",
-    summary: "Today's hot-stock leaderboard",
+    description: "Returns today's most-popular A-share stocks, ranked by a composite score of searches, follows, and comments.",
+    summary: "Get today's hot-stock leaderboard.",
     positional: [],
     outputDefault: "json",
     pagination: "none",
@@ -2481,8 +2237,8 @@ L1/L2/L3（X5001 食品饮料 / X500102 白酒 等）。
     cliName: "stocks social-hot",
     method: "GET",
     path: "/v1/stocks/social-hot",
-    description: "跨平台（微博 / 雪球 / Twitter）社交媒体提及聚合榜，按提及量 / 情感打分。",
-    summary: "Cross-platform social-hot stocks",
+    description: "Returns a leaderboard of A-share stocks aggregated by social-media mentions across multiple platforms, ranked by mention volume and sentiment score.",
+    summary: "Get cross-platform social-hot stocks.",
     positional: [],
     outputDefault: "json",
     pagination: "none",
@@ -2503,8 +2259,8 @@ L1/L2/L3（X5001 食品饮料 / X500102 白酒 等）。
     cliName: "views document",
     method: "GET",
     path: "/v1/views/{view_id}/document",
-    description: "取一条研报 view 背后的全文（mineru 解析的 parsed_md）。仅 `full_text_available=true` 的 view 可用（gdrive 研报）。大文档默认 format=outline 只回标题目录 + total_chars；format=full 按 offset/max_chars 切片正文并给 next_offset 游标翻页。需要 `views:read` scope。CLI 顶层 curated 别名：`report`（`echopai report <view_id>`）。",
-    summary: "Fetch the full research-report text behind a view",
+    description: "Returns the full parsed text of the research report behind one view. Available only for views with `full_text_available=true`. Large documents default to `format=outline`, returning a heading-only table of contents plus total character count; use `format=full` with `offset` / `max_chars` to page through the body via the `next_offset` cursor. Requires the `views:read` scope.",
+    summary: "Get the full research-report text behind a view.",
     positional: [
       "view_id"
     ],
@@ -2559,8 +2315,8 @@ L1/L2/L3（X5001 食品饮料 / X500102 白酒 等）。
     cliName: "views feed",
     method: "GET",
     path: "/v1/views",
-    description: "分析师观点 / 卖方研报 / 长文本观点流。可按机构 / 分析师 / 证券 / hours 过滤。需要 `views:read` scope。",
-    summary: "List analyst views",
+    description: "Returns a stream of analyst views, sell-side research, and long-form opinion. Filter by institution, analyst, security, or recency (`hours`). Partner/agent callers receive `fields=compact` by default (id, ai_summary, attribution, tagged securities, first ~300 chars of content); pass `fields=full` for complete content. Requires the `views:read` scope.",
+    summary: "List analyst views.",
     positional: [],
     outputDefault: "json",
     pagination: "offset",
@@ -2572,7 +2328,16 @@ L1/L2/L3（X5001 食品饮料 / X500102 白酒 等）。
     dryRunSupported: false,
     inputSchema: {
       type: "object",
-      properties: {},
+      properties: {
+        fields: {
+          type: "string",
+          enum: [
+            "compact",
+            "full"
+          ],
+          description: "Response shape: `compact` (the default for partner/agent callers) returns id, ai_summary, attribution, tagged securities, and the first ~300 chars of content with a `content_truncated` flag; `full` returns complete content."
+        }
+      },
       additionalProperties: false
     }
   },
@@ -2581,8 +2346,8 @@ L1/L2/L3（X5001 食品饮料 / X500102 白酒 等）。
     cliName: "views get",
     method: "GET",
     path: "/v1/views/{view_id}",
-    description: "返回单条 view 完整内容、附件图片、tagged securities、AI 摘要。",
-    summary: "Fetch a single analyst view",
+    description: "Returns the full content of one analyst view: body, attached images, tagged securities, and AI summary.",
+    summary: "Get a single analyst view.",
     positional: [
       "view_id"
     ],
@@ -2613,8 +2378,8 @@ L1/L2/L3（X5001 食品饮料 / X500102 白酒 等）。
     cliName: "views recent",
     method: "GET",
     path: "/v1/views/recent",
-    description: "List recent broker / analyst views (research notes, price targets, ratings). Filter by analyst, institution, or a specific security. Requires `views:read` scope.",
-    summary: "Recent broker / analyst views",
+    description: "Returns recent broker / analyst views (research notes, price targets, ratings). Filter by analyst, institution, or a specific security. Requires the `views:read` scope.",
+    summary: "List recent analyst views.",
     positional: [],
     outputDefault: "json",
     pagination: "none",
@@ -2672,6 +2437,14 @@ L1/L2/L3（X5001 食品饮料 / X500102 白酒 等）。
           minimum: 0,
           default: 0,
           description: "Pagination offset (page through long history ranges)."
+        },
+        fields: {
+          type: "string",
+          enum: [
+            "compact",
+            "full"
+          ],
+          description: "Response shape: `compact` (the default for partner/agent callers) returns id, title/ai_summary, attribution, tagged securities, and the first ~300 chars of content with a `content_truncated` flag; `full` returns complete content. Prefer compact for scanning; fetch full text per item only when needed."
         }
       },
       additionalProperties: false
@@ -2728,7 +2501,7 @@ function attachOperation(cmd, op, dispatch) {
 function buildCommandTree(program, dispatch) {
   {
     const noun = program.command("agent");
-    noun.description("agent commands");
+    noun.description("Manage agent billing sessions and identity.");
     {
       const cmd = noun.command("session-end");
       attachOperation(cmd, OPERATIONS["agent.session-end"], dispatch);
@@ -2744,7 +2517,7 @@ function buildCommandTree(program, dispatch) {
   }
   {
     const noun = program.command("announcements");
-    noun.description("announcements commands");
+    noun.description("Listed-company disclosures: feed, per-stock, and full-text search.");
     {
       const cmd = noun.command("detail");
       attachOperation(cmd, OPERATIONS["announcements.detail"], dispatch);
@@ -2764,7 +2537,7 @@ function buildCommandTree(program, dispatch) {
   }
   {
     const noun = program.command("auth");
-    noun.description("auth commands");
+    noun.description("Authentication and caller identity.");
     {
       const cmd = noun.command("whoami");
       attachOperation(cmd, OPERATIONS["auth.whoami"], dispatch);
@@ -2772,7 +2545,7 @@ function buildCommandTree(program, dispatch) {
   }
   {
     const noun = program.command("bars");
-    noun.description("bars commands");
+    noun.description("Historical OHLC price bars — daily and minute, single or batch.");
     {
       const cmd = noun.command("daily");
       attachOperation(cmd, OPERATIONS["bars.daily"], dispatch);
@@ -2790,9 +2563,17 @@ function buildCommandTree(program, dispatch) {
       attachOperation(cmd, OPERATIONS["bars.minute-batch"], dispatch);
     }
   }
+  {
+    const noun = program.command("capabilities");
+    noun.description("capabilities commands");
+    {
+      const cmd = noun.command("show");
+      attachOperation(cmd, OPERATIONS["capabilities.show"], dispatch);
+    }
+  }
   {
     const noun = program.command("concepts");
-    noun.description("concepts commands");
+    noun.description("Thematic concept boards: constituents, quotes, and alerts.");
     {
       const cmd = noun.command("alerts");
       attachOperation(cmd, OPERATIONS["concepts.alerts"], dispatch);
@@ -2840,7 +2621,7 @@ function buildCommandTree(program, dispatch) {
   }
   {
     const noun = program.command("financials");
-    noun.description("financials commands");
+    noun.description("Point-in-time fundamental financials.");
     {
       const cmd = noun.command("pit");
       attachOperation(cmd, OPERATIONS["financials.pit"], dispatch);
@@ -2860,7 +2641,7 @@ function buildCommandTree(program, dispatch) {
   }
   {
     const noun = program.command("index");
-    noun.description("index commands");
+    noun.description("Index quotes and snapshots.");
     {
       const cmd = noun.command("daily-bars");
       attachOperation(cmd, OPERATIONS["index.daily-bars"], dispatch);
@@ -2874,33 +2655,9 @@ function buildCommandTree(program, dispatch) {
       attachOperation(cmd, OPERATIONS["index.snapshot"], dispatch);
     }
   }
-  {
-    const noun = program.command("industries");
-    noun.description("industries commands");
-    {
-      const cmd = noun.command("alerts");
-      attachOperation(cmd, OPERATIONS["industries.alerts"], dispatch);
-    }
-    {
-      const cmd = noun.command("daily-bars");
-      attachOperation(cmd, OPERATIONS["industries.daily-bars"], dispatch);
-    }
-    {
-      const cmd = noun.command("list");
-      attachOperation(cmd, OPERATIONS["industries.list"], dispatch);
-    }
-    {
-      const cmd = noun.command("show");
-      attachOperation(cmd, OPERATIONS["industries.show"], dispatch);
-    }
-    {
-      const cmd = noun.command("snapshot");
-      attachOperation(cmd, OPERATIONS["industries.snapshot"], dispatch);
-    }
-  }
   {
     const noun = program.command("limit-up");
-    noun.description("limit-up commands");
+    noun.description("Daily limit-up pool and attribution analysis.");
     {
       const cmd = noun.command("analysis");
       attachOperation(cmd, OPERATIONS["limit-up.analysis"], dispatch);
@@ -2920,7 +2677,7 @@ function buildCommandTree(program, dispatch) {
   }
   {
     const noun = program.command("market");
-    noun.description("market commands");
+    noun.description("Market-wide trading status and breadth.");
     {
       const cmd = noun.command("status");
       attachOperation(cmd, OPERATIONS["market.status"], dispatch);
@@ -2928,7 +2685,7 @@ function buildCommandTree(program, dispatch) {
   }
   {
     const noun = program.command("news");
-    noun.description("news commands");
+    noun.description("Market news feed and full-text search.");
     {
       const cmd = noun.command("feed");
       attachOperation(cmd, OPERATIONS["news.feed"], dispatch);
@@ -2948,7 +2705,7 @@ function buildCommandTree(program, dispatch) {
   }
   {
     const noun = program.command("ownership");
-    noun.description("ownership commands");
+    noun.description("Insider trades, share buybacks, and lockup expirations.");
     {
       const cmd = noun.command("lockups");
       attachOperation(cmd, OPERATIONS["ownership.lockups"], dispatch);
@@ -2958,14 +2715,6 @@ function buildCommandTree(program, dispatch) {
       attachOperation(cmd, OPERATIONS["ownership.show"], dispatch);
     }
   }
-  {
-    const noun = program.command("payment");
-    noun.description("payment commands");
-    {
-      const cmd = noun.command("plans");
-      attachOperation(cmd, OPERATIONS["payment.plans"], dispatch);
-    }
-  }
   {
     const noun = program.command("quote");
     noun.description("quote commands");
@@ -2980,23 +2729,15 @@ function buildCommandTree(program, dispatch) {
   }
   {
     const noun = program.command("search");
-    noun.description("search commands");
+    noun.description("Search securities and content.");
     {
       const cmd = noun.command("semantic");
       attachOperation(cmd, OPERATIONS["search.semantic"], dispatch);
     }
   }
-  {
-    const noun = program.command("securities");
-    noun.description("securities commands");
-    {
-      const cmd = noun.command("industry");
-      attachOperation(cmd, OPERATIONS["securities.industry"], dispatch);
-    }
-  }
   {
     const noun = program.command("semantic");
-    noun.description("semantic commands");
+    noun.description("Meaning-based (semantic) security and content search.");
     {
       const cmd = noun.command("find");
       attachOperation(cmd, OPERATIONS["semantic.find"], dispatch);
@@ -3004,7 +2745,7 @@ function buildCommandTree(program, dispatch) {
   }
   {
     const noun = program.command("sentiment");
-    noun.description("sentiment commands");
+    noun.description("Market sentiment and breadth indicators.");
     {
       const cmd = noun.command("breadth");
       attachOperation(cmd, OPERATIONS["sentiment.breadth"], dispatch);
@@ -3024,7 +2765,7 @@ function buildCommandTree(program, dispatch) {
   }
   {
     const noun = program.command("stocks");
-    noun.description("stocks commands");
+    noun.description("Per-stock overview, hot lists, and screening.");
     {
       const cmd = noun.command("hot");
       attachOperation(cmd, OPERATIONS["stocks.hot"], dispatch);
@@ -3036,7 +2777,7 @@ function buildCommandTree(program, dispatch) {
   }
   {
     const noun = program.command("views");
-    noun.description("views commands");
+    noun.description("Analyst and broker research views (primary research source).");
     {
       const cmd = noun.command("document");
       attachOperation(cmd, OPERATIONS["views.document"], dispatch);
@@ -3959,7 +3700,7 @@ import os2 from "node:os";
 import path2 from "node:path";
 
 // src/version.ts
-var CLI_VERSION = "2.6.1";
+var CLI_VERSION = "2.8.0";
 
 // src/runtime/update_check.ts
 var UPDATE_CACHE_PATH = path2.join(os2.homedir(), ".config", "echopai", "update_cache.json");
@@ -4092,9 +3833,10 @@ async function invoke(op, args, ctx) {
     }
     throw e;
   }
+  const opOwnedFlags = new Set(Object.keys(op.inputSchema.properties).filter((k) => SYSTEM_FLAGS.has(k)));
   const apiParams = {};
   for (const [k, v] of Object.entries(args)) {
-    if (SYSTEM_FLAGS.has(k))
+    if (SYSTEM_FLAGS.has(k) && !opOwnedFlags.has(k))
       continue;
     if (v === undefined || v === "")
       continue;
@@ -4261,9 +4003,10 @@ async function invoke(op, args, ctx) {
   let envelope = rawEnvelope;
   try {
     const jq = typeof args.jq === "string" ? args.jq : undefined;
+    const fieldsProjection = opOwnedFlags.has("fields") ? undefined : parseFieldsFlag(args.fields);
     envelope = applyFilters(rawEnvelope, {
       ...jq ? { query: jq } : {},
-      ...parseFieldsFlag(args.fields) ? { fields: parseFieldsFlag(args.fields) } : {},
+      ...fieldsProjection ? { fields: fieldsProjection } : {},
       ...parseMaxBytesFlag(args.max_bytes) ? { maxBytes: parseMaxBytesFlag(args.max_bytes) } : {}
     });
   } catch (e) {
@@ -4873,6 +4616,19 @@ function buildBarsBatchCommand() {
   });
   return cmd;
 }
+// src/verbs/capabilities.ts
+var capabilitiesSpec = {
+  name: "capabilities",
+  description: "API capability changelog and spec-version discovery. Returns the current spec version plus a newest-first changelog of capability changes (new endpoints, new fields, behavior fixes). Call once at session start — or when a response shape surprises you — to learn what changed since your integration was written. Free, unauthenticated, non-billable.",
+  inputSchema: {},
+  handler: async (_args, ctx) => {
+    const op = OPERATIONS["capabilities.show"];
+    if (!op)
+      throw new Error("capabilities.show op missing from codegen");
+    return callOp(op, {}, ctx);
+  },
+  backingOps: ["capabilities.show"]
+};
 // src/verbs/chart.ts
 import { Command as Command5, Option as Option4 } from "commander";
 import { z as z3 } from "zod";
@@ -5818,9 +5574,29 @@ function buildHotCommand() {
   });
   return cmd;
 }
+// src/verbs/indices.ts
+import { z as z8 } from "zod";
+var indexSnapshotSpec = {
+  name: "index_snapshot",
+  description: "Real-time snapshot for the 172 A-share indices with a live quote feed (e.g. 上证指数 SSE:000001, 深证成指 SZSE:399001, 创业板指 SZSE:399006, 科创50 SSE:000688, 北证50 BSE:899050): price, pct_change, amount, speed_3min per index, refreshed ~15s during market hours (last intraday snapshot outside trading hours). Pass `codes` to narrow to a subset; omit for all 172. Use this for 'how is the broad market doing right now' — `quote` covers individual stocks only. CSI-series indices (CSI:*) have no live feed and are not returned.",
+  inputSchema: {
+    codes: z8.array(z8.string().regex(/^(SSE|SZSE|BSE):[0-9]{6}$/)).min(1).max(172).optional().describe("Canonical index codes to narrow the snapshot (e.g. ['SSE:000001', 'BSE:899050']); omit for all 172")
+  },
+  handler: async (args, ctx) => {
+    const op = OPERATIONS["index.snapshot"];
+    if (!op)
+      throw new Error("index.snapshot op missing from codegen");
+    const callArgs = {};
+    if (Array.isArray(args.codes) && args.codes.length > 0) {
+      callArgs.codes = args.codes.join(",");
+    }
+    return callOp(op, callArgs, ctx);
+  },
+  backingOps: ["index.snapshot"]
+};
 // src/verbs/limit_up.ts
 import { Command as Command11, Option as Option9 } from "commander";
-import { z as z8 } from "zod";
+import { z as z9 } from "zod";
 var DATE_RE5 = /^\d{4}-\d{2}-\d{2}$/;
 var INCLUDE_VALUES = ["active", "all"];
 function clampInt5(raw, min, max, fallback) {
@@ -5837,9 +5613,9 @@ var limitUpPoolSpec = {
   name: "limit_up_pool",
   description: "A-share limit-up pool for a given trade date — per-stock detail: first/last seal time, final pct, seal amount/volume, broken count, consecutive_days (连板数), board_count_within (N-day 板数), one-word-board flag, current status (limit_up / broken), board classification. Sort: consecutive_days desc → board_count_within desc → seal_amount desc. Pre-open fallback applies. Use when an agent needs the concrete list of '今天涨停了哪些票'.",
   inputSchema: {
-    trade_date: z8.string().regex(DATE_RE5).optional().describe("ISO date YYYY-MM-DD; omit for latest (pre-open fallback)"),
-    include: z8.enum(INCLUDE_VALUES).default("active").describe("active = 排除 ST/退市（默认）; all = 全部"),
-    include_broken: z8.boolean().default(false).describe("true 时连炸板（status=broken）也一起返回；默认只返回当前封板 status=limit_up")
+    trade_date: z9.string().regex(DATE_RE5).optional().describe("ISO date YYYY-MM-DD; omit for latest (pre-open fallback)"),
+    include: z9.enum(INCLUDE_VALUES).default("active").describe("active = 排除 ST/退市（默认）; all = 全部"),
+    include_broken: z9.boolean().default(false).describe("true 时连炸板（status=broken）也一起返回；默认只返回当前封板 status=limit_up")
   },
   handler: async (args, ctx) => {
     const op = OPERATIONS["limit-up.pool"];
@@ -5859,8 +5635,8 @@ var limitUpSummarySpec = {
   name: "limit_up_summary",
   description: "Limit-up summary for a given trade date: 涨停数 (limit_up_count) / 炸板数 (broken_count) / 跌停数 (limit_down_count) / 最高连板 (max_height) / 连板梯队 ladder[{height, count}]. 炸板/跌停 与情绪页同源 (market_breadth_intraday 当日最新分钟行). Pre-open fallback applies.",
   inputSchema: {
-    trade_date: z8.string().regex(DATE_RE5).optional().describe("ISO date YYYY-MM-DD; omit for latest"),
-    include: z8.enum(INCLUDE_VALUES).default("active").describe("active = all_a_ex_st 口径（默认）; all = all_a 口径")
+    trade_date: z9.string().regex(DATE_RE5).optional().describe("ISO date YYYY-MM-DD; omit for latest"),
+    include: z9.enum(INCLUDE_VALUES).default("active").describe("active = all_a_ex_st 口径（默认）; all = all_a 口径")
   },
   handler: async (args, ctx) => {
     const op = OPERATIONS["limit-up.summary"];
@@ -5877,7 +5653,7 @@ var limitUpHistorySpec = {
   name: "limit_up_history",
   description: "Daily limit-up trend over the last N trading days: { trade_date, limit_up_count, broken_count, max_height }. 涨停数/最高连板 from market_limit_up_pool; 炸板数 from market_breadth_intraday (all_a_ex_st). Sorted by trade_date asc (oldest first).",
   inputSchema: {
-    days: z8.number().int().min(1).max(250).default(30).describe("Lookback window in trading days (1-250, default 30)")
+    days: z9.number().int().min(1).max(250).default(30).describe("Lookback window in trading days (1-250, default 30)")
   },
   handler: async (args, ctx) => {
     const op = OPERATIONS["limit-up.history"];
@@ -5891,7 +5667,7 @@ var limitUpAnalysisSpec = {
   name: "limit_up_analysis",
   description: "Per-stock limit-up LLM attribution for a given trade date: leading_concept (主导题材) + concept_tags (相关标签) + reason (涨停理由). Themes are judged by an LLM from the latest research / views / news (NOT from the concept graph, so brand-new themes are covered) and refreshed across 6 Beijing slots daily. Complements limit-up pool (which says '哪些票涨停'); this says '为什么涨停/属什么题材'. STALE-DATA WARNING: omitting trade_date returns the latest *attributed* trading day, NOT necessarily today — before today's first slot lands (~09:47 Beijing) it falls back to the PREVIOUS day's attribution. For today's data pass trade_date explicitly and verify the returned trade_date / generated_at fields. An explicit trade_date with no attribution yet returns an empty analyses list.",
   inputSchema: {
-    trade_date: z8.string().regex(DATE_RE5).optional().describe("ISO date YYYY-MM-DD; omit for the latest *attributed* day (falls back to the previous day until today's first slot lands ~09:47 Beijing — pass today explicitly for today's data)")
+    trade_date: z9.string().regex(DATE_RE5).optional().describe("ISO date YYYY-MM-DD; omit for the latest *attributed* day (falls back to the previous day until today's first slot lands ~09:47 Beijing — pass today explicitly for today's data)")
   },
   handler: async (args, ctx) => {
     const op = OPERATIONS["limit-up.analysis"];
@@ -5957,7 +5733,7 @@ function buildLimitUpCommand() {
 }
 // src/verbs/lookup.ts
 import { Command as Command12, Option as Option10 } from "commander";
-import { z as z9 } from "zod";
+import { z as z10 } from "zod";
 function mapLookupResponse(raw) {
   if (!Array.isArray(raw))
     return [];
@@ -5981,8 +5757,8 @@ var lookupSpec = {
   name: "lookup",
   description: "Resolve a Chinese name / A-share code / pinyin initials to canonical codes (e.g. SSE:600519). Use this first whenever the agent has a description but needs a canonical_code for downstream calls. AH dual-listing: when a company is listed on both A-share and HK (e.g. 工商银行 SSE:601398 / HK:01398), prefer the A-share canonical for all downstream analysis unless the user explicitly asks for the HK side.",
   inputSchema: {
-    text: z9.string().min(1).max(50).describe("Search text: Chinese name (贵州茅台), code (600519), or pinyin (gzmt)"),
-    limit: z9.number().int().min(1).max(30).default(10).describe("Max matches (1-30)")
+    text: z10.string().min(1).max(50).describe("Search text: Chinese name (贵州茅台), code (600519), or pinyin (gzmt)"),
+    limit: z10.number().int().min(1).max(30).default(10).describe("Max matches (1-30)")
   },
   handler: async (args, ctx) => {
     const op = OPERATIONS["semantic.find"];
@@ -6016,7 +5792,7 @@ function buildLookupCommand() {
 }
 // src/verbs/market.ts
 import { Command as Command13, Option as Option11 } from "commander";
-import { z as z10 } from "zod";
+import { z as z11 } from "zod";
 var marketStatusSpec = {
   name: "market_status",
   description: "Current A-share market session: pre-open / open / lunch / closed; current and next trading day; holiday flag. Cheap and non-billable — call it before any quote / bars fetch when the agent needs to decide pre-market fallback vs intraday vs after-close behavior.",
@@ -6069,10 +5845,10 @@ var marketMoversSpec = {
   name: "market_movers",
   description: "A-share market movers — top N from the full real-time snapshot, sorted by chosen field. Sort keys: `pct` (涨幅榜) / `pct_asc` (跌幅榜) / `speed` (3-min 涨速 speed_3min) / `amount` (成交额) / `turnover` (换手率 turnover_rate) / `total_mv` (总市值). Backed by `quote.scan` so 9:00-9:14 集合竞价时段会返空 (with `note`). Defaults: sort=pct, top=20, include=active (排除 ST / 退市). Use this for /market-style 'who's running today' instead of pulling the full 3 MB scan and sorting client-side.",
   inputSchema: {
-    sort: z10.enum(MOVERS_SORT_VALUES).default("pct").describe("Sort field: pct / pct_asc / speed / amount / turnover / total_mv"),
-    top: z10.number().int().min(1).max(500).default(20).describe("Top N items (1-500, default 20)"),
-    exchange: z10.enum(EXCHANGE_VALUES).optional().describe("Narrow to one exchange: SSE / SZSE / BSE"),
-    include: z10.enum(INCLUDE_VALUES2).default("active").describe("active = 排除 ST/退市（默认）; all = 全集（含 ST + 退市 + 未知 status）")
+    sort: z11.enum(MOVERS_SORT_VALUES).default("pct").describe("Sort field: pct / pct_asc / speed / amount / turnover / total_mv"),
+    top: z11.number().int().min(1).max(500).default(20).describe("Top N items (1-500, default 20)"),
+    exchange: z11.enum(EXCHANGE_VALUES).optional().describe("Narrow to one exchange: SSE / SZSE / BSE"),
+    include: z11.enum(INCLUDE_VALUES2).default("active").describe("active = 排除 ST/退市（默认）; all = 全集（含 ST + 退市 + 未知 status）")
   },
   handler: async (args, ctx) => {
     const op = OPERATIONS["quote.scan"];
@@ -6156,18 +5932,19 @@ function buildMarketCommand() {
 }
 // src/verbs/news.ts
 import { Command as Command14, Option as Option12 } from "commander";
-import { z as z11 } from "zod";
+import { z as z12 } from "zod";
 var newsSpec = {
   name: "news",
-  description: "SUPPLEMENTARY news / market briefs (short time-horizon event stream). Use ONLY to fill gaps not covered by `views`; prefer `views` as the primary research source. Three modes: `code` (canonical, works across A-share | HK | US — e.g. SSE:600519, HK:00700 腾讯, US:BABA) → news mentioning that security; `query` (free text) → full-text search; neither → recent time-window feed. AH dual-listing: when filtering by `code` for an A+H listed company, pass the A-share canonical (e.g. SSE:601398) for consolidated coverage; HK side only if the user explicitly asks. Note: `query` is matched against news text, so passing a canonical_code as `query` will not work — use `code` for security filtering.",
+  description: "SUPPLEMENTARY news / market briefs (short time-horizon event stream). Use ONLY to fill gaps not covered by `views`; prefer `views` as the primary research source. Returns `fields=compact` by default (title + ai_summary + first ~300 chars of content, `content_truncated` flag) — typically 20-50x smaller than full; pass fields='full' only when you need complete article text. Three modes: `code` (canonical, works across A-share | HK | US — e.g. SSE:600519, HK:00700 腾讯, US:BABA) → news mentioning that security; `query` (free text) → full-text search; neither → recent time-window feed. AH dual-listing: when filtering by `code` for an A+H listed company, pass the A-share canonical (e.g. SSE:601398) for consolidated coverage; HK side only if the user explicitly asks. Note: `query` is matched against news text, so passing a canonical_code as `query` will not work — use `code` for security filtering.",
   inputSchema: {
-    code: z11.string().regex(/^((SSE|SZSE|BSE):[0-9]{6}|HK:[0-9]{5}|US:[A-Z][A-Z0-9.\-]{0,5})$/).optional().describe("Filter by security canonical_code (e.g. SSE:600519, HK:00700). Takes precedence over `query`."),
-    query: z11.string().optional().describe("Free-text query (Chinese or English) matched against news content; omit for time-window feed. Do NOT pass canonical_code here — use `code` instead."),
-    hours: z11.number().int().min(1).max(168).default(24).describe("Rolling-feed lookback in hours (default 24 — much narrower than views). For longer history use from/to with code or query."),
-    from: z11.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional().describe("History range start (China date YYYY-MM-DD). Range mode: needs code or query; Pro-only up to 365 days back."),
-    to: z11.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional().describe("History range end (inclusive, China date; defaults to today). Use with from."),
-    offset: z11.number().int().min(0).optional().describe("Pagination offset for paging through long history ranges."),
-    limit: z11.number().int().min(1).max(100).default(20).describe("Max items per page")
+    code: z12.string().regex(/^((SSE|SZSE|BSE):[0-9]{6}|HK:[0-9]{5}|US:[A-Z][A-Z0-9.\-]{0,5})$/).optional().describe("Filter by security canonical_code (e.g. SSE:600519, HK:00700). Takes precedence over `query`."),
+    query: z12.string().optional().describe("Free-text query (Chinese or English) matched against news content; omit for time-window feed. Do NOT pass canonical_code here — use `code` instead."),
+    hours: z12.number().int().min(1).max(168).default(24).describe("Rolling-feed lookback in hours (default 24 — much narrower than views). For longer history use from/to with code or query."),
+    from: z12.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional().describe("History range start (China date YYYY-MM-DD). Range mode: needs code or query; Pro-only up to 365 days back."),
+    to: z12.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional().describe("History range end (inclusive, China date; defaults to today). Use with from."),
+    offset: z12.number().int().min(0).optional().describe("Pagination offset for paging through long history ranges."),
+    limit: z12.number().int().min(1).max(100).default(20).describe("Max items per page"),
+    fields: z12.enum(["compact", "full"]).optional().describe("Response shape: compact (default — title + ai_summary + first ~300 chars) or full (complete content)")
   },
   handler: async (args, ctx) => {
     const { opKey, callArgs } = buildNewsCall(args);
@@ -6180,11 +5957,14 @@ var newsSpec = {
 };
 function buildNewsCall(args) {
   const hasRange = typeof args.from === "string" && args.from.length > 0;
+  const fields = args.fields === "compact" || args.fields === "full" ? args.fields : undefined;
   const withWindow = (a) => {
     if (typeof args.limit === "number")
       a.limit = args.limit;
     if (typeof args.offset === "number")
       a.offset = args.offset;
+    if (fields)
+      a.fields = fields;
     if (hasRange) {
       a.from = args.from;
       if (typeof args.to === "string" && args.to.length > 0)
@@ -6201,7 +5981,7 @@ function buildNewsCall(args) {
   if (hasRange) {
     throw new Error("range history (from/to) requires --code or --query; the bare feed has no narrowing filter");
   }
-  return { opKey: "news.feed", callArgs: {} };
+  return { opKey: "news.feed", callArgs: fields ? { fields } : {} };
 }
 function clamp3(raw, min, max, fallback) {
   const n = Math.floor(Number(raw));
@@ -6222,6 +6002,10 @@ function buildNewsCommand() {
   cmd.addOption(new Option12("--to <date>", "History range end YYYY-MM-DD (inclusive; default today)"));
   cmd.addOption(new Option12("--offset <n>", "Pagination offset for long history").default("0"));
   cmd.addOption(new Option12("--limit <n>", "Max items").default("20"));
+  cmd.addOption(new Option12("--fields <mode>", "Response shape: compact (default) or full").choices([
+    "compact",
+    "full"
+  ]));
   cmd.action(async (opts) => {
     const args = {
       hours: clamp3(opts.hours, 1, 168, 24),
@@ -6236,19 +6020,21 @@ function buildNewsCommand() {
       args.from = opts.from;
     if (opts.to)
       args.to = opts.to;
+    if (opts.fields)
+      args.fields = opts.fields;
     await executeVerb(async (ctx) => newsSpec.handler(args, ctx));
   });
   return cmd;
 }
 // src/verbs/quote.ts
 import { Command as Command15, Option as Option13 } from "commander";
-import { z as z12 } from "zod";
+import { z as z13 } from "zod";
 var quoteSpec = {
   name: "quote",
   description: "Real-time quote for 1-200 A-share securities (last price, volume, change %, bid/ask). For >200 codes use `scan` instead. AH dual-listing: HK codes are not supported here; for an A+H listed company use the A-share canonical (e.g. SSE:601398 not HK:01398).",
   inputSchema: {
-    codes: z12.array(z12.string().regex(/^(SSE|SZSE|BSE|SH|SZ|BJ):[0-9]{6}$/)).min(1).max(200).describe("Array of canonical codes (e.g. ['SSE:600519', 'SZSE:000001'])"),
-    include_l2: z12.boolean().optional().describe("Include L2 5-level order book (requires quote:l2 scope)")
+    codes: z13.array(z13.string().regex(/^(SSE|SZSE|BSE|SH|SZ|BJ):[0-9]{6}$/)).min(1).max(200).describe("Array of canonical codes (e.g. ['SSE:600519', 'SZSE:000001'])"),
+    include_l2: z13.boolean().optional().describe("Include L2 5-level order book (requires quote:l2 scope)")
   },
   handler: async (args, ctx) => {
     const op = OPERATIONS["quote"];
@@ -6279,12 +6065,12 @@ function buildQuoteCommand() {
 }
 // src/verbs/scan.ts
 import { Command as Command16, Option as Option14 } from "commander";
-import { z as z13 } from "zod";
+import { z as z14 } from "zod";
 var scanSpec = {
   name: "scan",
   description: "Full-market real-time quote scan (~5800 A-share securities in one round-trip). Use for universe discovery; agents should slim output with field/byte limits in their tool host or post-processing.",
   inputSchema: {
-    exchange: z13.enum(["SSE", "SZSE", "BSE"]).optional().describe("Filter by exchange (omit for all)")
+    exchange: z14.enum(["SSE", "SZSE", "BSE"]).optional().describe("Filter by exchange (omit for all)")
   },
   handler: async (args, ctx) => {
     const op = OPERATIONS["quote.scan"];
@@ -6313,16 +6099,16 @@ function buildScanCommand() {
 }
 // src/verbs/search.ts
 import { Command as Command17, Option as Option15 } from "commander";
-import { z as z14 } from "zod";
+import { z as z15 } from "zod";
 var searchSpec = {
   name: "search",
   description: "Structured-first hybrid search across analyst views + news (views weighted higher per feedback_views_over_news). Three lanes — entity (company codes / names, analyst names), concept-graph hub (theme alias → concept → constituents & research), and ParadeDB BM25 full-text (jieba) — fused with RRF. Deterministic & explainable: no vector kNN, no LLM rerank. Best for theme/concept queries: 'CPO' brings out 光模块/光通信/光芯片; '减肥药' brings out 创新药; '智驾' brings out 智能驾驶. Use `news` or `views` instead if you need strict time-window listing.",
   inputSchema: {
-    q: z14.string().min(1).max(200).describe("Free-text query (Chinese or English)"),
-    type: z14.enum(["news", "views", "all"]).default("all").describe("Search scope (views weighted higher in 'all')"),
-    mode: z14.enum(["hybrid", "exact"]).default("hybrid").describe("hybrid = entity + concept-graph + BM25 fused; exact = BM25 keyword only"),
-    hours: z14.number().int().min(1).max(720).optional().describe("Lookback window in hours; omit for no time limit"),
-    limit: z14.number().int().min(1).max(50).default(20).describe("Max items returned")
+    q: z15.string().min(1).max(200).describe("Free-text query (Chinese or English)"),
+    type: z15.enum(["news", "views", "all"]).default("all").describe("Search scope (views weighted higher in 'all')"),
+    mode: z15.enum(["hybrid", "exact"]).default("hybrid").describe("hybrid = entity + concept-graph + BM25 fused; exact = BM25 keyword only"),
+    hours: z15.number().int().min(1).max(720).optional().describe("Lookback window in hours; omit for no time limit"),
+    limit: z15.number().int().min(1).max(50).default(20).describe("Max items returned")
   },
   handler: async (args, ctx) => {
     const op = OPERATIONS["search.semantic"];
@@ -6375,7 +6161,7 @@ function buildSearchCommand() {
 }
 // src/verbs/sentiment.ts
 import { Command as Command18, Option as Option16 } from "commander";
-import { z as z15 } from "zod";
+import { z as z16 } from "zod";
 var SCOPE_VALUES = [
   "all_a",
   "all_a_ex_st",
@@ -6399,8 +6185,8 @@ var sentimentSpec = {
   name: "sentiment",
   description: "Aggregate market sentiment indicators (limit-up/down counts, breadth, divergence index, top movers). Defaults to all_a_ex_st (all A-shares ex-ST). Pass `at_date` (YYYY-MM-DD) for any historical trading day; omit for today's latest snapshot. Backward-compat alias of `sentiment_overview` — prefer the latter in new agent code.",
   inputSchema: {
-    scope: z15.enum(SCOPE_VALUES).default("all_a_ex_st").describe("Universe filter"),
-    at_date: z15.string().regex(DATE_RE6).optional().describe("Trade date YYYY-MM-DD; omit for today's realtime snapshot")
+    scope: z16.enum(SCOPE_VALUES).default("all_a_ex_st").describe("Universe filter"),
+    at_date: z16.string().regex(DATE_RE6).optional().describe("Trade date YYYY-MM-DD; omit for today's realtime snapshot")
   },
   handler: async (args, ctx) => {
     const op = OPERATIONS["sentiment.overview"];
@@ -6417,8 +6203,8 @@ var sentimentOverviewSpec = {
   name: "sentiment_overview",
   description: "Aggregate sentiment snapshot for one trading day's latest minute: up/down/flat counts, limit-up/down, gt3/lt3 breadth, divergence index + label, MA20/50/200 breadth, 52w new high/low. `at_date` omitted = today realtime (Redis); explicit YYYY-MM-DD = historical from ClickHouse `market_breadth_intraday` last minute.",
   inputSchema: {
-    scope: z15.enum(SCOPE_VALUES).default("all_a_ex_st").describe("Universe filter"),
-    at_date: z15.string().regex(DATE_RE6).optional().describe("Trade date YYYY-MM-DD; omit for today realtime")
+    scope: z16.enum(SCOPE_VALUES).default("all_a_ex_st").describe("Universe filter"),
+    at_date: z16.string().regex(DATE_RE6).optional().describe("Trade date YYYY-MM-DD; omit for today realtime")
   },
   handler: async (args, ctx) => {
     const op = OPERATIONS["sentiment.overview"];
@@ -6435,8 +6221,8 @@ var sentimentBreadthSpec = {
   name: "sentiment_breadth",
   description: "Intraday breadth time series for one trading day (up to 241 minute bars; 13:00 excluded due to sparse Sina ticks). `at_date` omitted = today (pre-open returns empty); explicit YYYY-MM-DD = historical replay. Returns per-minute rows of up/down/flat/limit_up/limit_down/breadth/divergence fields — same shape as `sentiment_overview` per row.",
   inputSchema: {
-    scope: z15.enum(SCOPE_VALUES).default("all_a_ex_st").describe("Universe filter"),
-    at_date: z15.string().regex(DATE_RE6).optional().describe("Trade date YYYY-MM-DD; omit for today")
+    scope: z16.enum(SCOPE_VALUES).default("all_a_ex_st").describe("Universe filter"),
+    at_date: z16.string().regex(DATE_RE6).optional().describe("Trade date YYYY-MM-DD; omit for today")
   },
   handler: async (args, ctx) => {
     const op = OPERATIONS["sentiment.breadth"];
@@ -6453,9 +6239,9 @@ var sentimentTurnoverSpec = {
   name: "sentiment_turnover",
   description: "Intraday turnover time series with `current_turnover` / `predicted_total` / `delta_vs_yesterday` headline fields. `at_date` omitted = today (pre-open returns nulls); explicit YYYY-MM-DD = historical. `days` (1-5) pulls that day + N-1 prior trading days for same-minute YoY comparison.",
   inputSchema: {
-    scope: z15.enum(SCOPE_VALUES).default("all_a_ex_st").describe("Universe filter"),
-    at_date: z15.string().regex(DATE_RE6).optional().describe("Trade date YYYY-MM-DD; omit for today"),
-    days: z15.number().int().min(1).max(5).default(1).describe("at_date 当日 + 之前 days-1 天（1-5，默认 1）")
+    scope: z16.enum(SCOPE_VALUES).default("all_a_ex_st").describe("Universe filter"),
+    at_date: z16.string().regex(DATE_RE6).optional().describe("Trade date YYYY-MM-DD; omit for today"),
+    days: z16.number().int().min(1).max(5).default(1).describe("at_date 当日 + 之前 days-1 天（1-5，默认 1）")
   },
   handler: async (args, ctx) => {
     const op = OPERATIONS["sentiment.turnover"];
@@ -6550,19 +6336,20 @@ function buildSentimentCommand() {
 }
 // src/verbs/views.ts
 import { Command as Command19, Option as Option17 } from "commander";
-import { z as z16 } from "zod";
+import { z as z17 } from "zod";
 var viewsSpec = {
   name: "views",
-  description: "PRIMARY research source for stock judgement: analyst views / sell-side reports / long-form opinion stream, with research_entity_id attribution. Prefer this over `news` when forming an investment opinion. Each item carries `full_text_available`; when true the item is a parsed research report and you can pull its full text with the `report` verb. AH dual-listing: for an A+H listed company pass the A-share canonical to get the consolidated coverage (most domestic analyst views attribute to the A-share security); use HK code only if the user explicitly asks for the HK perspective.",
+  description: "PRIMARY research source for stock judgement: analyst views / sell-side reports / long-form opinion stream, with research_entity_id attribution. Prefer this over `news` when forming an investment opinion. Returns `fields=compact` by default (ai_summary + first ~300 chars of content, `content_truncated` flag) — typically 20-50x smaller than full; pass fields='full' only when summaries are not enough. Recommended reading path: `digest` for a one-shot overview → this verb (compact) to scan → `report` for the full text of a single item (`full_text_available=true` means a parsed research report). AH dual-listing: for an A+H listed company pass the A-share canonical to get the consolidated coverage (most domestic analyst views attribute to the A-share security); use HK code only if the user explicitly asks for the HK perspective.",
   inputSchema: {
-    code: z16.string().regex(/^((SSE|SZSE|BSE):[0-9]{6}|HK:[0-9]{5}|US:[A-Z][A-Z0-9.\-]{0,5})$/).optional().describe("Filter by security canonical_code (e.g. SSE:600519, HK:00700, US:AAPL)"),
-    analyst: z16.string().optional().describe("Analyst Chinese name (exact / fuzzy)"),
-    institution: z16.string().optional().describe("Broker / institution Chinese name"),
-    since_days: z16.number().int().min(1).max(365).default(7).describe("Lookback in days. ≤30 = rolling feed; >30 auto-switches to range history " + "(needs a code/analyst/institution filter; Pro-only up to 365). For an explicit window use from/to."),
-    from: z16.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional().describe("History range start (China date YYYY-MM-DD). Range mode: needs a filter; Pro-only up to 365 days back."),
-    to: z16.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional().describe("History range end (inclusive, China date; defaults to today). Use with from."),
-    offset: z16.number().int().min(0).optional().describe("Pagination offset for paging through long history ranges."),
-    limit: z16.number().int().min(1).max(100).default(30).describe("Max items per page")
+    code: z17.string().regex(/^((SSE|SZSE|BSE):[0-9]{6}|HK:[0-9]{5}|US:[A-Z][A-Z0-9.\-]{0,5})$/).optional().describe("Filter by security canonical_code (e.g. SSE:600519, HK:00700, US:AAPL)"),
+    analyst: z17.string().optional().describe("Analyst Chinese name (exact / fuzzy)"),
+    institution: z17.string().optional().describe("Broker / institution Chinese name"),
+    since_days: z17.number().int().min(1).max(365).default(7).describe("Lookback in days. ≤30 = rolling feed; >30 auto-switches to range history " + "(needs a code/analyst/institution filter; Pro-only up to 365). For an explicit window use from/to."),
+    from: z17.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional().describe("History range start (China date YYYY-MM-DD). Range mode: needs a filter; Pro-only up to 365 days back."),
+    to: z17.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional().describe("History range end (inclusive, China date; defaults to today). Use with from."),
+    offset: z17.number().int().min(0).optional().describe("Pagination offset for paging through long history ranges."),
+    limit: z17.number().int().min(1).max(100).default(30).describe("Max items per page"),
+    fields: z17.enum(["compact", "full"]).optional().describe("Response shape: compact (default — ai_summary + first ~300 chars) or full (complete content)")
   },
   handler: async (args, ctx) => {
     const op = OPERATIONS["views.recent"];
@@ -6586,6 +6373,8 @@ function buildViewsCallArgs(args) {
     callArgs.institution = args.institution;
   if (typeof args.offset === "number")
     callArgs.offset = args.offset;
+  if (args.fields === "compact" || args.fields === "full")
+    callArgs.fields = args.fields;
   const explicitRange = typeof args.from === "string" && args.from.length > 0;
   if (explicitRange || sinceDays > 30) {
     if (!hasFilter) {
@@ -6607,10 +6396,10 @@ var reportSpec = {
   name: "report",
   description: "Fetch the FULL research-report text behind a view (mineru-parsed long-form), for when the `views` summary is not enough. Only works on views where `full_text_available=true` (gdrive sell-side reports). Two-step usage: default `format=outline` returns a few-KB heading map + total_chars + each heading's char_offset; then call `format=full` with `offset` (e.g. an outline char_offset) to read the body in pages — follow `next_offset` to page through large docs instead of pulling everything at once.",
   inputSchema: {
-    view_id: z16.string().regex(/^[0-9]+$/).describe("View id from `views` items[].id (must have full_text_available=true)"),
-    format: z16.enum(["outline", "full"]).default("outline").describe("outline=heading map (default); full=body slice"),
-    offset: z16.number().int().min(0).default(0).describe("full mode: start char offset (use an outline char_offset)"),
-    max_chars: z16.number().int().min(1).max(80000).default(40000).describe("full mode: max chars per page (hard cap 80000)")
+    view_id: z17.string().regex(/^[0-9]+$/).describe("View id from `views` items[].id (must have full_text_available=true)"),
+    format: z17.enum(["outline", "full"]).default("outline").describe("outline=heading map (default); full=body slice"),
+    offset: z17.number().int().min(0).default(0).describe("full mode: start char offset (use an outline char_offset)"),
+    max_chars: z17.number().int().min(1).max(80000).default(40000).describe("full mode: max chars per page (hard cap 80000)")
   },
   handler: async (args, ctx) => {
     const op = OPERATIONS["views.document"];
@@ -6648,6 +6437,10 @@ function buildViewsCommand() {
   cmd.addOption(new Option17("--to <date>", "History range end YYYY-MM-DD (inclusive; default today)"));
   cmd.addOption(new Option17("--offset <n>", "Pagination offset for long history").default("0"));
   cmd.addOption(new Option17("--limit <n>", "Max items (1-100)").default("30"));
+  cmd.addOption(new Option17("--fields <mode>", "Response shape: compact (default) or full").choices([
+    "compact",
+    "full"
+  ]));
   cmd.action(async (opts) => {
     if (!OPERATIONS["views.recent"]) {
       emitVerbError("internal_error", "views.recent missing from codegen", undefined, 2);
@@ -6667,6 +6460,8 @@ function buildViewsCommand() {
       args.from = opts.from;
     if (opts.to)
       args.to = opts.to;
+    if (opts.fields)
+      args.fields = opts.fields;
     await executeVerb(async (ctx) => viewsSpec.handler(args, ctx));
   });
   return cmd;
@@ -6700,6 +6495,7 @@ var ALL_VERB_SPECS = [
   quoteSpec,
   marketStatusSpec,
   marketMoversSpec,
+  indexSnapshotSpec,
   viewsSpec,
   reportSpec,
   newsSpec,
@@ -6734,7 +6530,8 @@ var ALL_VERB_SPECS = [
   financialsReportsSpec,
   financialsSeriesSpec,
   ownershipShowSpec,
-  ownershipLockupsSpec
+  ownershipLockupsSpec,
+  capabilitiesSpec
 ];
 
 // src/tools/mcp.ts
@@ -7521,375 +7318,283 @@ function buildDoctorCommand() {
 
 // src/tools/schema.ts
 import { Command as Command27 } from "commander";
-import { z as z17 } from "zod";
+import { z as z18 } from "zod";
 
 // src/_generated/help.ts
 var HELP = {
   "agent.session-end": {
-    summary: "End a billable agent session",
-    description: "关闭 `/v1/agent/session/start` 开启的会话，最终用量提交入库。",
+    summary: "Close a billable agent session.",
+    description: "Closes a session opened by `/v1/agent/session/start` and commits its final usage.",
     example: "echopai agent session-end VALUE"
   },
   "agent.session-start": {
-    summary: "Start a billable agent session",
-    description: "开启 agent kind 凭据的计费会话。返回 session_id，用于将多次调用归并到一次 billable 单位。需要 `Idempotency-Key` 头。",
+    summary: "Open a billable agent session.",
+    description: "Opens a billable session for an agent credential and returns a session_id that groups subsequent calls into a single billable unit. Requires an `Idempotency-Key` header.",
     example: "echopai agent session-start --agent-id agent-prod-1 --budget-usd 1.0"
   },
   "agent.session-usage": {
-    summary: "Get cumulative usage of an agent session",
-    description: "返回 session 内累计 billable 调用次数、各 scope 配额消耗。",
+    summary: "Get cumulative usage for an agent session.",
+    description: "Returns the cumulative billable call count and per-scope quota consumption for the given session.",
     example: "echopai agent session-usage VALUE"
   },
   "announcements.detail": {
-    summary: "Fetch a single announcement by id",
-    description: "返回公告完整内容：content_md、content_text、cninfo 元数据、解析状态。",
+    summary: "Get a single announcement by id.",
+    description: "Returns the full content of one announcement: body (markdown and plain text), metadata, and parse status.",
     example: "echopai announcements detail VALUE"
   },
   "announcements.feed": {
-    summary: "List recent A-share announcements",
-    description: "A 股公告 feed，按 published_at 降序、同日按 cninfo source_id 降序。可按 type / since 过滤。需要 `announcements:read` scope。",
+    summary: "List recent A-share announcements.",
+    description: "Returns a feed of recent A-share corporate announcements, sorted by publication date descending. Filter by `type` or `since`. Requires the `announcements:read` scope.",
     example: "echopai announcements feed"
   },
   "announcements.search": {
-    summary: "Hybrid search over A-share announcements",
-    description: "公告混合搜索：名称 / 代码做结构化过滤 + 关键词 BM25 全文（ParadeDB jieba，覆盖 title / ai_summary / content_md 前 1500 字）。q 含 6 位代码或内嵌 A 股名 → 按代码精确过滤；残余或纯文本 → BM25 按相关度×时间衰减排序；纯代码/名称则按 published_at 倒序列出。需要 `announcements:read` scope。",
+    summary: "Search A-share announcements.",
+    description: "Hybrid search over A-share announcements: structured filtering by security name or code, combined with full-text keyword search (over title, AI summary, and the first ~1500 characters of the body). A query containing a 6-digit code or an embedded security name is filtered by that security; remaining free text is ranked by relevance with time decay; a pure code or name lists results by publication date descending. Requires the `announcements:read` scope.",
     example: "echopai announcements search --q 新华医疗 回购"
   },
   "announcements.stock": {
-    summary: "List announcements for a specific A-share security",
-    description: "指定股票代码的公告列表（含历史窗口）。代码接受 6 位纯数字或 SSE:600519 / SZSE:000001 / BSE:430000 形式。需要 `announcements:read` scope。",
+    summary: "List announcements for one security.",
+    description: "Returns the announcement history for one A-share security over a date window. Accepts a 6-digit code or canonical form (e.g. `SSE:600519`). Requires the `announcements:read` scope.",
     example: "echopai announcements stock --code SSE:600519"
   },
   "auth.whoami": {
-    summary: "Token introspection (CLI/MCP capability discovery)",
-    description: `Returns the calling token's kind, scopes, audience, app metadata,
-rate_limit, allowed_clients, agent_budget (if kind=agent), api_version,
-feature_flags. Any valid JWT can call — no specific scope required.
-
-CLI/MCP call this once at startup, cache 5 minutes in-process, and use
-the response to derive \`verbs.available\` (intersection of curated verb
-scopes with token scopes) and to populate \`echopai doctor\` checks.
-
-See \`docs/PLAN_CLI_V2_AGENT_SURFACE.md\` §5.1.
-`,
+    summary: "Introspect the calling token (capability discovery).",
+    description: "Returns the calling token's kind, scopes, audience, app metadata, rate limit, allowed clients, agent budget (when kind=agent), API version, and feature flags. Any valid token may call this; no specific scope is required. Clients typically call it once at startup and cache the result briefly to determine which commands are available.",
     example: "echopai auth whoami"
   },
   "bars.daily": {
-    summary: "Daily OHLC bars for one A-share security",
-    description: "Daily OHLC bars for one A-share security over a date range. Returns open / high / low / close / volume / turnover per trading day. Requires `bars:30d` (last 30 trading days) or `bars:full` (full history) scope.",
+    summary: "List daily OHLC bars for one A-share security.",
+    description: "Returns daily open/high/low/close/volume/turnover for one A-share security over a date range (canonical code, e.g. `SSE:600519`). End-of-day data. Requires the `bars:30d` scope (last 30 trading days) or `bars:full` scope (full history).",
     example: "echopai bars daily --code SSE:600519 --from 2026-01-01 --to 2026-05-01"
   },
   "bars.daily-batch": {
-    summary: "Batch daily OHLC bars for up to 100 A-share securities",
-    description: "Batch daily OHLC bars for multiple A-share securities. Up to 100 codes\nper call, up to 1-year date range. Single round-trip; ClickHouse `IN(...)`\nunder the hood.\n\nReturns partial success envelope: codes denied by `allowed_securities`\nappear in `errors[]`, others in `items[]` (with empty `bars[]` if no\ndata found). Order in `items[]` matches input order.\n\nRequires `bars:30d` or `bars:full` scope.\n",
+    summary: "Batch daily OHLC bars for up to 100 securities.",
+    description: "Returns daily OHLC bars for multiple A-share securities in one call: up to 100 codes and up to a one-year date range. Responses use a partial-success envelope: codes the token may not access are reported in `errors[]`, the rest in `items[]` (with an empty `bars[]` when no data is found), preserving input order. Requires the `bars:30d` or `bars:full` scope.",
     example: "echopai bars daily-batch --codes ['SSE:600519', 'SZSE:000001']"
   },
   "bars.minute": {
-    summary: "Minute-level OHLC bars for one A-share security",
-    description: "Minute-level OHLC bars for one A-share security on a single trade date. Requires `bars:30d` or `bars:full` scope.",
+    summary: "List minute OHLC bars for one A-share security.",
+    description: "Returns minute-level OHLC bars for one A-share security on a single trade date (canonical code, e.g. `SSE:600519`). Requires the `bars:30d` or `bars:full` scope.",
     example: "echopai bars minute --code SSE:600519 --date 2026-05-09"
   },
   "bars.minute-batch": {
-    summary: "Batch minute OHLC bars for up to 20 A-share securities",
-    description: "Batch minute OHLC bars for multiple A-share securities. Up to 20 codes\nper call, up to 7 calendar days (≈5 trading days) date range. Single\nClickHouse round-trip; app groups rows by canonical_code.\n\nPartial success envelope same as daily-batch: codes denied by\n`allowed_securities` go to `errors[]`; others to `items[]` with flat\n`bars[]` (each bar carries its own `trade_date` for client grouping).\n\nRequires `bars:30d` or `bars:full` scope.\n",
+    summary: "Batch minute OHLC bars for up to 20 securities.",
+    description: "Returns minute-level OHLC bars for multiple A-share securities in one call: up to 20 codes and up to a 7 calendar-day (~5 trading-day) range. Responses use a partial-success envelope: codes the token may not access are reported in `errors[]`, the rest in `items[]` with a flat `bars[]` array where each bar carries its own `trade_date` for client-side grouping. Requires the `bars:30d` or `bars:full` scope.",
     example: "echopai bars minute-batch --codes ['SSE:600519', 'SZSE:000001']"
   },
+  "capabilities.show": {
+    summary: "Capability changelog and API version discovery.",
+    description: "Returns the current API spec version plus a machine-readable changelog of capability changes (new endpoints, new fields, behavior fixes), newest first. Check it at session start — or after an unexpected response shape — to discover capabilities added since your integration was written. Free and unauthenticated.",
+    example: "echopai capabilities show"
+  },
   "concepts.alerts": {
-    summary: "Currently active concept alerts (big_move / limit_up_cluster)",
-    description: `Returns the live \`concept_alerts:active\` hash. Two rules:
-  - big_move: abs(pct_change) > 3%
-  - limit_up_cluster: limit_up_count >= 3 AND stock_count >= 5
-See PLAN_CONCEPT_INDUSTRY_QUOTE §5.5 "异动检测与推送".
-`,
+    summary: "List currently active concept alerts.",
+    description: "Returns the live set of concept alerts. Two rules fire: `big_move` when absolute percent change exceeds 3%, and `limit_up_cluster` when a concept has at least 3 limit-up members across at least 5 member stocks.",
     example: "echopai concepts alerts"
   },
   "concepts.alerts-history": {
-    summary: "Concept alerts history (last 24h)",
-    description: "Concept异动 historical events (default last 24h). Filter by rule (big_move / limit_up_cluster) and time window. Used by AI agent / admin review.",
+    summary: "List recent concept alert history.",
+    description: "Returns historical concept alert events (default: last 24 hours). Filter by rule (`big_move` / `limit_up_cluster`) and time window. Useful for reviewing how concept activity evolved over a period.",
     example: "echopai concepts alerts-history"
   },
   "concepts.daily-bars": {
-    summary: "Concept index daily bars (chain-linked equal-weight, base 1000)",
-    description: `Returns daily OHLC (concept index points, not stock prices average),
-breadth fields, and is_backfilled flag. See PLAN §5.4 algorithm.
-`,
+    summary: "List daily bars for a concept index.",
+    description: "Returns daily OHLC for a concept index (index points, not an average of member stock prices), along with breadth fields and a backfill flag. The concept index is a chain-linked equal-weight return series with a base of 1000.",
     example: "echopai concepts daily-bars VALUE"
   },
   "concepts.list": {
-    summary: "List concepts with live snapshot (hot/warm fallback)",
-    description: "Concept list joining CH `v_concept_meta` with Redis snapshot hashes,\nfollowing the hot/warm two-key pattern (PR #438):\n\nRead order **per concept** (not global):\n  1. `concept_snapshots:latest`     (hot, TTL 5min) — fresh tick\n  2. `concept_snapshots:last_close` (warm, TTL 7d)  — post-close / weekend\n  3. CH `v_concept_daily_bars` argMax                — extreme fallback (~ 7d+)\n\n9:00–9:14 pre-open reset window: hot + warm both suppressed (loading state),\nregardless of TTL; CH fallback is also disabled in this window.\n\nEach item carries `_source` ∈ {`latest`, `last_close`, `ch_daily`, `miss`}\nso the client can render a freshness badge.\n\nLive fields: pct_change / index_value / up/down_count / limit_up_count /\namount / speed_3min / `main_net_in`. `main_net_in` (元) is the concept-level\nsum of member-stocks' fundflow `main_net_in` (collector MGETs\n`stockpulse:fundflow:latest:{code}` each aggregation round). May be negative\n(net outflow); null when collector / Redis snapshot unavailable.\n\nSource / status / index are computed per PLAN_CONCEPT_INDUSTRY_QUOTE\n§5.4 algorithm (chain-linked equal-weight returns, base = 1000).\n",
+    summary: "List concepts with their live snapshot.",
+    description: "Lists market concepts (themes/sectors) joined with their latest real-time snapshot, falling back to the last close and then to recent daily data when live ticks are unavailable. Each item carries a `_source` freshness indicator. Live fields include percent change, index value, advancing/declining counts, limit-up count, turnover amount, 3-minute momentum, and `main_net_in` (net main-capital inflow in CNY, which may be negative for net outflow and null when unavailable). The concept index is a chain-linked equal-weight return series with a base of 1000. During the 9:00–9:14 pre-open window, live data is suppressed and a loading state is returned.",
     example: "echopai concepts list"
   },
   "concepts.minute-bars": {
-    summary: "Concept index minute bars (max 7 days)",
-    description: "Concept index minute-level OHLC (chain-linked equal-weight, base = 1000), max 7 days per request. See PLAN_CONCEPT_INDUSTRY_QUOTE §5.4.",
+    summary: "List minute bars for a concept index.",
+    description: "Returns minute-level OHLC for a concept index (chain-linked equal-weight return series, base 1000), up to 7 days per request.",
     example: "echopai concepts minute-bars VALUE"
   },
   "concepts.news": {
-    summary: "Related news matching concept name (ILIKE)",
-    description: `Short-term implementation: ILIKE on news.title + content with the
-concept name and full_name. Long-term: news AI tagging.
-`,
+    summary: "List news related to a concept.",
+    description: "Returns recent news whose title or body mentions the concept's name. Use it to see what is currently driving a theme.",
     example: "echopai concepts news VALUE"
   },
   "concepts.show": {
-    summary: "Concept detail (meta + member securities)",
-    description: "Detail view for one concept: meta (full_name / source / status / approved_at / first_listed_at) plus current member securities with their latest snapshots.",
+    summary: "Get concept detail with member securities.",
+    description: "Returns detail for one concept: metadata (full name, source, status, approval date, first-listed date) plus its current member securities with their latest snapshots.",
     example: "echopai concepts show VALUE"
   },
   "concepts.snapshot": {
-    summary: "Bulk Redis snapshot of concepts (hot/warm union)",
-    description: "Two contracts depending on `codes` parameter:\n\n- **With `codes=`** (per-key completeness): each requested id is resolved\n  via hot → warm → CH three-tier fallback. Missing ids are populated.\n- **Without `codes`** (best-effort dump): returns the **union** of\n  `concept_snapshots:latest` and `concept_snapshots:last_close` Redis\n  hashes. Concepts absent from both Redis hashes are **not** backfilled\n  from CH. Use GET `/v1/concepts` instead if you need every known concept.\n\n9:00–9:14 pre-open reset window: hot and warm both suppressed, CH fallback\nalso disabled; the endpoint returns an empty list (loading state).\n\nEach item carries `_source` ∈ {`latest`, `last_close`, `ch_daily`}.\n",
+    summary: "Bulk real-time snapshot of concepts.",
+    description: "Returns real-time snapshots for concepts, with two modes. With `codes=`, each requested concept id is resolved via real-time → last-close → recent-daily fallback so every requested id is populated. Without `codes`, it returns a best-effort dump of all concepts that currently have a real-time or last-close snapshot; concepts absent from both are not backfilled (use `GET /v1/concepts` if you need every known concept). Each item carries a `_source` freshness indicator. During the 9:00–9:14 pre-open window, live data is suppressed and an empty list is returned.",
     example: "echopai concepts snapshot"
   },
   "concepts.views": {
-    summary: "Broker views associated with this concept",
-    description: "JOIN concept_views × broker_views (ai_status=done) sorted by published_at desc.",
+    summary: "List analyst views associated with a concept.",
+    description: "Returns analyst views linked to this concept (with AI processing complete), sorted by publication date descending.",
     example: "echopai concepts views VALUE"
   },
   "digest.get": {
-    summary: "One-shot research digest for a single security (composite)",
-    description: `Composite endpoint: in one HTTP call returns views (PRIMARY research),
-real-time quote, valuation snapshot (PE/PB/PS/换手率/股息率/量比 等 14 字段),
-market sentiment context, and supplementary news.
-Partial-failure tolerant:
-each bucket is independently fetched and per-bucket failures surface
-in \`meta.partial_failures[]\` rather than poisoning the response. If
-every sub-bucket fails the endpoint returns 502.
-
-Bucket scopes are checked *per bucket* (not at gateway level): a
-token with only \`views:read\` gets the views bucket populated and the
-rest reported as \`scope_insufficient\` partial failures. This mirrors
-the CLI fan-out contract exactly so \`echopai digest\` can either call
-this endpoint (preferred, single round-trip) or fall back to local
-fan-out without behavior drift.
-
-See \`docs/PLAN_CLI_V2_AGENT_SURFACE.md\` §3.3 (digest spec) and §11
-Phase 5.2 (server endpoint).
-`,
+    summary: "Build a one-shot research digest for one security.",
+    description: "Composite endpoint that, in a single call, returns separated sections for one security: analyst views (the primary research source), a real-time quote, a valuation snapshot (PE/PB/PS, turnover rate, dividend yield, volume ratio, and ~14 fields in total), market sentiment context, and supplementary news. Each section is fetched independently and per-section failures are reported in `meta.partial_failures[]` instead of failing the whole call; the endpoint returns 502 only if every section fails. Scopes are enforced per section, so a token with only `views:read` receives the views section and sees the rest reported as scope-insufficient. Use this when you want a single broad overview of a security (canonical code, e.g. `SSE:600519`).",
     example: "echopai digest get HK:00700"
   },
   "financials.pit": {
-    summary: "Point-in-time financial indicators for one A-share at a given date",
-    description: "基于 TDX 财务数据的 Point-in-time 查询。给定 `code` 和 `date`，返回该\n`trade_date` 当时市场上可见的最新一期财务报告（`announce_date <= date`，\n无公告日时保守延迟 90 天）。专为回测、AI agent、量化策略防未来函数泄漏。\n\n返回字段包括：EPS（基本/扣非/稀释）、BPS、ROE、毛利率、营收/净利润/总资产/\n归母权益等核心 ~25 字段。\n",
+    summary: "Get point-in-time fundamentals for one security at a date.",
+    description: "Returns the most recent financial report that was publicly available on a given date for one A-share security (canonical code, e.g. `SSE:600519`) — i.e. announcement date on or before `date`, with a conservative 90-day fallback when the announcement date is unknown. Designed to avoid look-ahead bias in backtests and quantitative strategies. Fields include EPS (basic / non-recurring / diluted), BPS, ROE, gross margin, revenue, net profit, total assets, and parent-company equity (~25 core fields).",
     example: "echopai financials pit --code SSE:600519 --date 2024-11-01"
   },
   "financials.quote-snapshot": {
-    summary: "Real-time valuation / share / turnover snapshot for one A-share",
-    description: "一站式估值快照 —— 一次返回 14 个字段，**全部基于 TDX 原始数据 + Sina 实时\n价自算，不依赖 Tushare**：\n\n- 估值: `pe` / `pe_ttm` / `pb` / `ps` / `ps_ttm`\n- 股本（万股）: `total_share` / `float_share` / `free_share`\n- 市值（万元）: `total_mv` / `circ_mv`\n- 流动性: `turnover_rate` / `turnover_rate_f`（%）/ `volume_ratio`（倍）\n- 分红: `dv_ratio` / `dv_ttm`（%）\n\n计算口径：\n- PE-TTM = 当前总市值 / 近 4 季度滚动净利润（PIT 表 `ni_parent_ttm`）\n- PE     = 当前总市值 / 上年报净利润（`ni_parent_last1y`）\n- PB     = 当前总市值 / 归母净资产（`equity_parent`，PIT 防穿越）\n- 换手率 = 当日累计成交量 / 流通股本 × 100\n- 量比   = 当日累计 / 近 5 日同时段累计平均（实时模式）\n          / 近 5 日全日成交量平均（指定历史日期模式）\n- 股息率 = Σ(去年 / 近12月内派息事件 派现/10) / 现价 × 100\n\n默认 `date` 留空 → 实时（Sina 5s 快照价 + 当日累计成交量）；\n给 `date=YYYY-MM-DD` 则按当日 close 取值（用于历史回测 / 校验）。\n\n财报数据走 `security_financial_indicators_pit` PIT 视图：保证 `visible_date`\n≤ trade_date，避免未来函数。\n\n准确性已对照 Tushare `daily_basic` 校验（见 `scripts/validation/validate_quote_snapshot_vs_tushare.py`）。\n",
+    summary: "Get a real-time valuation snapshot for one security.",
+    description: "Returns a one-stop valuation snapshot (14 fields) for one A-share security (canonical code, e.g. `SSE:600519`), combining real-time prices with point-in-time fundamentals so figures are free of look-ahead bias. Fields: valuation (`pe`, `pe_ttm`, `pb`, `ps`, `ps_ttm`); share counts in 10k shares (`total_share`, `float_share`, `free_share`); market cap in 10k CNY (`total_mv`, `circ_mv`); liquidity (`turnover_rate`, `turnover_rate_f` in %, `volume_ratio` as a multiple); and dividend yield (`dv_ratio`, `dv_ttm` in %). Leave `date` empty for a real-time snapshot, or pass `date=YYYY-MM-DD` to value as of that day's close (useful for historical checks and backtests).",
     example: "echopai financials quote-snapshot --code SSE:600519 --date 2026-05-13"
   },
   "financials.reports": {
-    summary: "Recent financial reports for one A-share security",
-    description: "返回该股票最近 N 期财务报告的核心指标（EPS/BPS/ROE/毛利率/营收/净利润/总\n资产/归母权益/经营现金流/总股本 等 ~25 字段）。可按 `kind` 过滤季报/半年报/\n年报。每期 `announce_date` 字段告知何时市场可见，建议结合回测时使用。\n\n**`kind` 口径说明**：\n\n- `Q1` / `H1` / `Q3` / `annual` —— 四个标准季度末快照（3-31 / 6-30 /\n  9-30 / 12-31），TDX 财务源数据全部落在这四个 report_date。\n- `preliminary` —— **当前数据源结构上不存在**。业绩预告 / 快报 是 indicators\n  行内的字段（`forecast_ni_lower` / `forecast_ni_upper` /\n  `express_ni_parent` / `express_revenue` 等），通过 `financials.series`\n  metric 参数访问，不是单独的 report_kind 行。`kind=preliminary` 会返\n  空列表 + meta.note。\n",
+    summary: "List recent financial reports for one security.",
+    description: "Returns core indicators for the most recent N financial reports of one A-share security (EPS/BPS/ROE, gross margin, revenue, net profit, total assets, parent equity, operating cash flow, total shares, and ~25 fields in total). Filter by `kind` for quarterly / interim / annual reports. Each report's `announce_date` indicates when it became publicly visible, which is useful for point-in-time analysis. Note: `kind=preliminary` does not exist as a separate report row — earnings forecasts and flash reports are exposed as metric fields (e.g. `forecast_ni_lower`, `forecast_ni_upper`, `express_ni_parent`, `express_revenue`) via `financials.series`, so `kind=preliminary` returns an empty list with an explanatory note.",
     example: "echopai financials reports --code SSE:600519"
   },
   "financials.series": {
-    summary: "Time series of a single financial metric for one security",
-    description: "返回某只股票某个财务指标的历史时间序列（按报告期排列）。`metric` 是\nindicators 表中的字段名（如 `roe_simple` / `revenue` / `ni_parent` /\n`debt_asset_ratio` / `gross_margin` / `eps_basic` 等共 150 个）。\n\n典型用法：画茅台 10 年 ROE 走势、对比 5 只白酒股 net_margin。\n",
+    summary: "Get a time series of one financial metric.",
+    description: "Returns the historical time series of a single financial metric for one A-share security, ordered by reporting period. `metric` is an indicator field name (e.g. `roe_simple`, `revenue`, `ni_parent`, `debt_asset_ratio`, `gross_margin`, `eps_basic`; ~150 metrics available). Use it to chart a multi-year trend for one company or to compare the same metric across several securities.",
     example: "echopai financials series --code SSE:600519 --metric roe_simple"
   },
   "index.daily-bars": {
-    summary: "Daily OHLC bars for one A-share index",
-    description: "指数日线 OHLC。覆盖 v2 表中的指数（上证综指 `SSE:000001` / 深证成指\n`SZSE:399001` / 沪深300 `SSE:000300` / 北证50 `BSE:899050` / 中证系列 `CSI:000922` 等）。\n与 `/v1/bars/daily` 同语义，但 index 没有 `turnover_rate` / `paused` 等股票特有字段。\n",
+    summary: "List daily OHLC bars for one A-share index.",
+    description: "Returns daily OHLC for one A-share index (e.g. 上证综指 `SSE:000001`, 深证成指 `SZSE:399001`, 沪深300 `SSE:000300`, 北证50 `BSE:899050`, CSI series such as `CSI:000922`). Same semantics as `/v1/bars/daily`, but indices have no stock-specific fields such as turnover rate or suspension flag.",
     example: "echopai index daily-bars --code SSE:000001 --from 2024-01-01 --to 2024-12-31"
   },
   "index.minute-bars": {
-    summary: "Minute OHLC bars for one A-share index",
-    description: "指数 1min OHLC。日期范围 ≤ 7 天（与 `/v1/bars/minute-batch` 对齐）。\n返回 `bar_time` / `trade_date` / OHLC / volume / amount / pct_change。\n",
+    summary: "List minute OHLC bars for one A-share index.",
+    description: "Returns 1-minute OHLC for one A-share index over a date range of up to 7 days. Each bar includes bar time, trade date, OHLC, volume, amount, and percent change.",
     example: "echopai index minute-bars --code SSE:000001"
   },
   "index.snapshot": {
-    summary: "Real-time snapshot of all Sina-OK A-share indices (172 indices)",
-    description: "Returns the latest real-time snapshot for the 172 indices that Sina\nexposes a quote for (SSE / SZSE / BSE — includes 北证50 `BSE:899050`\nand 专精特新 `899601.BJ`). Source is the Redis hash\n`stockpulse:index_snapshots:latest` which the Rust collector refreshes\nevery ~15 seconds during market hours; outside trading hours the last\nintraday snapshot is returned.\n\nUse `codes` to narrow to a subset (canonical format `SSE:000001` (exchange-prefix; legacy `000001.SH` is also accepted but discouraged)).\nOmit to receive all 172.\n\nNote: CSI-series indices (e.g. `CSI:000922`) are not available here —\nSina has no quote feed for them. Daily/minute history for those still\nlives behind `/api/internal/index/{daily-bars,minute-bars-range}`.\n\nRequires `quote:l1`, `quote:l2`, or `quote:delayed` scope.\n",
+    summary: "Snapshot real-time quotes for A-share indices.",
+    description: "Returns the latest real-time snapshot for the 172 A-share indices that have a live quote feed (SSE / SZSE / BSE, including 北证50 `BSE:899050`). The snapshot refreshes roughly every 15 seconds during market hours; outside trading hours the last intraday snapshot is returned. Use `codes` (canonical format, e.g. `SSE:000001`) to narrow to a subset, or omit it to receive all indices. Note: CSI-series indices (e.g. `CSI:000922`) have no live quote feed and are not returned here. Requires a `quote:l1`, `quote:l2`, or `quote:delayed` scope.",
     example: "echopai index snapshot --codes SSE:000001,SZSE:399001,BSE:899050"
   },
-  "industries.alerts": {
-    summary: "Currently active industry alerts",
-    description: "Currently active industry alerts (big_move / limit_up_cluster). Same rule set as concepts.",
-    example: "echopai industries alerts"
-  },
-  "industries.daily-bars": {
-    summary: "Industry index daily bars",
-    description: "Industry index daily OHLC (chain-linked equal-weight, base = 1000). Path key format `<sw_industry_code>:<sw_level>` (e.g. `401001:1`).",
-    example: "echopai industries daily-bars 401001:1"
-  },
-  "industries.list": {
-    summary: "List industries (申万 L1/L2) with hot/warm fallback",
-    description: "Industry index list joining CH `v_industry_meta` with Redis snapshot.\n申万一级 (level=1) ≈ 127 industries, 申万二级 (level=2) ≈ 348.\nChain-linked equal-weight algorithm identical to concepts (PLAN §5.4).\n\nRead order per industry (mirrors `/v1/concepts`, PR #442):\n  1. `industry_snapshots:latest`     (hot, TTL 5min)\n  2. `industry_snapshots:last_close` (warm, TTL 7d)\n  3. CH `v_industry_daily_bars` argMax\n9:00–9:14 reset window suppresses hot+warm (loading state).\nEach item carries `_source` ∈ {`latest`, `last_close`, `ch_daily`, `miss`}.\n",
-    example: "echopai industries list"
-  },
-  "industries.show": {
-    summary: "Industry detail (meta + today members)",
-    description: "Path key format: `<sw_industry_code>:<sw_level>` (e.g. `401001:1`).",
-    example: "echopai industries show 401001:1"
-  },
-  "industries.snapshot": {
-    summary: "Bulk Redis snapshot of industries (hot/warm union)",
-    description: "Mirrors `/v1/concepts/snapshot` contract (PR #442 review 二轮):\n\n- **With `codes=`** (per-key completeness): hot → warm → CH fallback\n  per industry; missing keys populated.\n- **Without `codes`** (best-effort dump): union of\n  `industry_snapshots:latest` and `industry_snapshots:last_close`\n  Redis hashes. Missing industries are **not** backfilled from CH; use\n  GET `/v1/industries` for a fully populated list.\n\n9:00–9:14 reset window suppresses both Redis hashes and CH fallback.\nEach item carries `_source` ∈ {`latest`, `last_close`, `ch_daily`}.\n申万一级 (level=1) ≈ 127 industries, 申万二级 (level=2) ≈ 348.\n",
-    example: "echopai industries snapshot"
-  },
   "limit-up.analysis": {
-    summary: "A-share limit-up LLM attribution (per-stock leading theme + reason)",
-    description: '涨停股 LLM 归因：逐股「主导题材 leading_concept + 概念标签 concept_tags +\n涨停理由 reason」。题材由 LLM 依据最新研报 / 机构观点 / 快讯判定，**不依赖概念\n图谱**（可含图谱里还没有的全新题材），每交易日北京 9:45 / 11:00 / 12:30 / 14:00 /\n14:40 / 18:00 共 6 个时段自动刷新（后跑时段在前次基础上 refine）。\n\n与 `limit-up/pool` 互补：pool 给"涨停了哪些票"（行情数据，stockpulse 上游），\n本接口给"为什么涨停 / 属什么题材"（LLM 归因，echopai api 上游）。pool 里的\ngraph-based `leading_concept` 是另一条数据，本接口的 `leading_concept` 才是\nLLM 判定结果。\n\n⚠️ **trade_date 不传 = 库内最新「已归因」交易日**（非自然最新交易日）：归因每个\n时段按当时池快照写库，今日**首个时段（北京约 09:47）落库前**，不传 trade_date\n会返回**上一交易日**的归因（不是今日空结果）——agent 拿当日数据请显式传今日\ntrade_date 并以 `trade_date` / `generated_at` 字段核对时效。显式传某交易日而该日\n尚未归因时，`analyses` 为空。\n\n平面归属：本接口在 **vu 平面**（前端 apiFetch 同源），与 `market/status` 同款\n`x-audience: vu`；行情类 `limit-up/pool|summary|history` 在 sp 平面（前端 spFetch）。\n需要 `market:read` 或任一 `quote:*` scope。\n',
+    summary: "Get LLM attribution for limit-up stocks.",
+    description: "Returns LLM-generated attribution for each limit-up stock: the leading theme (`leading_concept`), concept tags, and a reason explaining why it hit the limit. Themes are inferred by an LLM from the latest research, institutional views, and news, so they may include brand-new themes; results refresh automatically at six points each trading day, with later runs refining earlier ones. This complements the limit-up pool, which tells you which stocks limited up; this endpoint tells you why and under which theme. Note: when `trade_date` is omitted, the latest attributed trading day is returned — before today's first run completes (around 09:47 Beijing time) this may be the previous trading day rather than empty, so pass an explicit `trade_date` for today and verify the `trade_date` / `generated_at` fields. Requires the `market:read` scope or any `quote:*` scope.",
     example: "echopai limit-up analysis"
   },
   "limit-up.history": {
-    summary: "A-share limit-up daily trend (last N days)",
-    description: "近 N 个交易日每日涨停数 + 最高连板 + 炸板数。涨停数 / 最高连板来源\n`market_limit_up_pool` (仅 status=limit_up)；炸板数来源\n`market_breadth_intraday`（all_a_ex_st 当日最新分钟行）。\n\n响应按 trade_date asc 排序（旧日期在前）。需要 `quote:*` scope。\n",
+    summary: "Get the A-share limit-up daily trend.",
+    description: "Returns the daily limit-up trend over the last N trading days: per-day limit-up count, highest consecutive-board height, and seal-break count. Sorted by trade date ascending (oldest first). Requires a `quote:*` scope.",
     example: "echopai limit-up history"
   },
   "limit-up.pool": {
-    summary: "A-share limit-up pool (per-stock detail) for a given trade date",
-    description: "当日（或指定 `trade_date`）涨停股池逐股明细：首/末次封板时间、最终涨幅、\n封单金额/封单量、炸板次数、连板数、N 日板内统计、一字板标记、当前 status\n(limit_up / broken)、板块分类。\n\n盘前回退规则（与所有行情类页面一致）：\n  - `< 9:00`：返回 max(trade_date) 的最新一日数据（昨日）\n  - `9:00-9:14`：集合竞价前空窗期，items=[] / trade_date=null\n  - `>= 9:15`：collector 已写入今日数据\n\n排序：连板数 desc → 板内板数 desc → 封单金额 desc。需要 `quote:*` scope。\n",
+    summary: "List the A-share limit-up pool for a trade date.",
+    description: "Returns per-stock detail for the limit-up pool on the current (or specified `trade_date`) trading day: first/last seal time, final percent change, seal amount and seal volume, number of times the seal broke, consecutive limit-up days, in-pool statistics over N days, one-line-board flag, current status (limit_up / broken), and sector classification. Sorted by consecutive limit-up days, then in-pool board count, then seal amount (all descending). Before 9:00 the previous trading day's data is returned; during 9:00–9:14 an empty result is returned; from 9:15 today's data is available. Requires a `quote:*` scope.",
     example: "echopai limit-up pool"
   },
   "limit-up.summary": {
-    summary: "A-share limit-up summary (counts + height ladder) for a given trade date",
-    description: "涨停股池聚合统计：涨停数、炸板数、跌停数、最高连板高度、连板梯队\n`ladder: [{ height, count }, ...]`。\n\n炸板数 / 跌停数 与情绪页同源（`market_breadth_intraday` 当日最新分钟行）；\n连板梯队仅统计当前封板 status=limit_up 的个股。\n\n盘前回退规则与 `limit-up/pool` 一致。需要 `quote:*` scope。\n",
+    summary: "Summarize A-share limit-up activity for a trade date.",
+    description: "Returns aggregate limit-up statistics for the trade date: limit-up count, seal-break count, limit-down count, the highest consecutive-board height, and a height ladder (`ladder: [{ height, count }, ...]`). The height ladder counts only stocks currently sealed at limit-up. Pre-open fallback follows the same rules as the limit-up pool. Requires a `quote:*` scope.",
     example: "echopai limit-up summary"
   },
   "market.status": {
-    summary: "Current A-share market session state",
-    description: "Current A-share market session: pre-open / open / lunch / closed; current and next trading day; holiday flag. Requires `market:read` or any `quote:*` scope.",
+    summary: "Get the current A-share market session state.",
+    description: "Returns the current A-share trading session (pre-open / open / lunch / closed), the current and next trading day, and a holiday flag. Requires the `market:read` scope or any `quote:*` scope.",
     example: "echopai market status"
   },
   "news.feed": {
-    summary: "List recent news (alias of /v1/news/list)",
-    description: "与 `/v1/news/list` 行为一致，旧客户端兼容用。",
+    summary: "List recent news.",
+    description: "Returns recent news. Equivalent to `/v1/news/list`; retained for backward compatibility. Partner/agent callers receive `fields=compact` by default (id, title, ai_summary, tagged securities, first ~300 chars of content); pass `fields=full` for complete content.",
     example: "echopai news feed"
   },
   "news.get": {
-    summary: "Fetch a single news item by id",
-    description: "返回新闻完整内容：title、content snippet、tagged securities。（采集端字段 source / source_id / source_url 对外不暴露，admin 路径 /v1/admin/news/{id} 可见。）",
+    summary: "Get a single news item by id.",
+    description: "Returns the full content of one news item: title, content snippet, and tagged securities.",
     example: "echopai news get VALUE"
   },
   "news.list": {
-    summary: "List news mentioning a specific security",
-    description: "List news mentioning a specific A-share security, ordered by published_at desc. Requires `news:read` scope.",
+    summary: "List news mentioning one security.",
+    description: "Returns news items mentioning a specific A-share security, ordered by publication date descending. Requires the `news:read` scope.",
     example: "echopai news list --security HK:00700"
   },
   "news.search": {
-    summary: "Full-text search recent news",
-    description: "Full-text search recent news / market briefs. Returns title, published_at, snippet, tagged securities. (Internal collector identifiers — `source`/`source_id`/`source_url` — are NOT exposed publicly; admin tools see them via /v1/admin/*.) Requires `news:read` scope. Note: news fields are user-generated; meta.untrusted_text_fields lists fields that need sanitization before passing to an LLM.",
+    summary: "Full-text search recent news.",
+    description: "Full-text search over recent news and market briefs. Returns title, publication date, snippet, and tagged securities. Requires the `news:read` scope. Note: news fields are user-generated; `meta.untrusted_text_fields` lists fields that should be sanitized before being passed to an LLM.",
     example: "echopai news search --query 光伏龙头"
   },
   "ownership.lockups": {
-    summary: "Scan upcoming share-lockup expirations across the whole market",
-    description: `全市场未来 days 天即将解禁扫描，按解禁日升序 + 占比降序。前瞻抛压预警，
-digest 给不了（digest 是单 code 维度）。min_pct 过滤小额解禁，limit 控量。
-`,
+    summary: "Scan upcoming share-lockup expirations market-wide.",
+    description: "Scans the whole market for share lockups expiring within the next `days` days, sorted by unlock date ascending then by unlocking ratio descending — a forward-looking selling-pressure screen across all securities. Use `min_pct` to filter out small unlocks and `limit` to cap the result size. T+1 data.",
     example: "echopai ownership lockups"
   },
   "ownership.show": {
-    summary: "Ownership events for one A-share (holder trades / repurchases / lockups)",
-    description: `单股股权事件三合一结构化字段，给研究 agent 一眼可读的「近 30 天增减持/回购
-+ 未来 30 天限售解禁」。源 Tushare（T+1），落 PG 专表幂等同步。
-
-- shareholder_transactions：增减持回看 txn_days 天，含净增减股数/比例 +
-  增减笔数 + 明细（方向/股东/均价/区间）。
-- share_repurchases：回购回看 repurchase_days 天，含在进行笔数 + 已执行
-  累计金额/股数（仅计 in_progress/completed）+ 最新进度 + 明细。
-- lockup_expirations：解禁前瞻 lockup_days 天（unlock_date ∈ [today,
-  today+N]），含合计解禁股数/占比 + 最近解禁日 + 明细。前瞻抛压预警。
-
-枚举 slug（direction / holder_category / status / lockup_type）见
-docs/OWNERSHIP_EVENTS.md。
-`,
+    summary: "Get ownership events for one security.",
+    description: "Returns a structured three-in-one view of ownership events for one A-share security (canonical code, e.g. `SSE:600519`): recent shareholder transactions, recent share repurchases, and upcoming lockup expirations. T+1 data. Shareholder transactions look back `txn_days` days and include net change in shares/ratio, transaction count, and per-transaction detail (direction, holder, average price, date range). Repurchases look back `repurchase_days` days and include in-progress count, cumulative executed amount/shares, latest progress, and detail. Lockup expirations look ahead `lockup_days` days and include total unlocking shares/ratio, the nearest unlock date, and detail — useful as a forward-looking selling-pressure warning. Enum values (direction, holder category, status, lockup type) are documented in the response schema.",
     example: "echopai ownership show --code SSE:600519"
   },
-  "payment.plans": {
-    summary: "List subscription plans",
-    description: "返回订阅计划清单（plan_id + 价格 + 时长 + 描述）。",
-    example: "echopai payment plans"
-  },
   quote: {
-    summary: "Real-time quote for one or more A-share securities",
-    description: "Real-time quote for one or more A-share securities. Returns last price, volume, change %, bid/ask. Up to 200 codes per call. Requires `quote:l1`, `quote:l2`, or `quote:delayed` scope.",
+    summary: "Get real-time quotes for one or more securities.",
+    description: "Returns real-time quotes for one or more A-share securities (canonical codes, e.g. `SSE:600519`): last price, volume, percent change, and bid/ask. Up to 200 codes per call. The response carries a `session` label (`pre_open` / `auction` / `open` / `break` / `closed`) and, outside continuous trading, an explanatory `note`: during 9:00–9:14 pre-open the previous session's snapshot is returned; during the 9:15–9:29 call auction, prices are indicative auction match prices. Rows whose feed has stopped updating (suspension / feed drop) keep their last snapshot and are flagged `stale: true` with `stale_since`. Requires a `quote:l1`, `quote:l2`, or `quote:delayed` scope.",
     example: "echopai quote --codes ['SSE:600519', 'SZSE:000001']"
   },
   "quote.scan": {
-    summary: "Full-market real-time quote scan (~5800 A-share securities)",
-    description: 'Dumps the entire Redis snapshot of A-share real-time quotes in a single\nround-trip. Use for "全市场扫描" / agent universe-of-interest discovery\nwhen you don\'t yet know which codes to query.\n\nFiltering:\n- `exchange=SSE|SZSE|BSE` narrows to one exchange (canonical_code prefix)\n- `app.allowed_securities` is ALWAYS applied; codes outside drop silently\n\nResponse size: ~3 MB unfiltered (~5800 items). CLI users should pair\nwith `--max-bytes` / `--fields` / `--query` from Phase 1.4.\n\n9:00–9:14 集合竞价时段返回空 items + `note` 字段说明。\n\nEach item also includes `main_net_in` (元, may be negative) — current-day\ncumulative main-capital net inflow merged from fundflow snapshot via\nhot/warm two-key pattern (PR #438):\n  - `stockpulse:fundflow:latest:{code}`     (hot, TTL 180s) for fresh\n  - `stockpulse:fundflow:last_close:{code}` (warm, TTL 7d)  for post-close\nCompanion field `main_net_in_stale` (boolean): false = fresh from hot,\ntrue = served from warm (post-close / weekend / collector down).\nTreated as a public field (same tier as `amount`); not scrubbed under\nany scope.\n\nRequires `quote:l1`, `quote:l2`, or `quote:delayed` scope.\n',
+    summary: "Snapshot every A-share real-time quote in one call.",
+    description: "Returns a real-time quote for every A-share in a single call — use it for full-market scans or to discover a universe of interest when you do not yet know which codes to query. Filter with `exchange=SSE|SZSE|BSE` to narrow to one exchange. The payload is large (~3 MB, ~5,800 instruments), so pair it with `--fields`, `--jq`, or `--max-bytes` to trim it. The response carries a `session` label (`pre_open` / `auction` / `open` / `break` / `closed`) plus an explanatory `note` outside continuous trading: during 9:00–9:14 pre-open the previous session's snapshot is returned; during the 9:15–9:29 call auction, prices are indicative auction match prices. Instruments whose feed has stopped updating (suspension / feed drop) are excluded from the default scan; pass `include=all` to keep them, flagged with `stale: true` and `stale_since`. Each item also includes `main_net_in` (current-day cumulative net main-capital inflow in CNY, which may be negative) and a companion `main_net_in_stale` flag (true when served from the last-close fallback). Requires a `quote:l1`, `quote:l2`, or `quote:delayed` scope.",
     example: "echopai quote scan"
   },
   "search.semantic": {
-    summary: "Hybrid semantic search across news + analyst views",
-    description: `语义 + 模糊泛化搜索。结合 entity 精确匹配（公司代码/分析师）、向量召回（pgvector
-+ DashScope embedding）、trigram 模糊、ILIKE 精确四路召回，RRF 融合后用 reranker
-精排，叠时间衰减 + views 加权（views 主源优先）。
-
-- 搜"锂电池"会带出新能源产业链（正极/负极/碳酸锂/宁德时代…）
-- 搜"芯片"会带出存储芯片/洁净室/晶圆代工…
-- mode=exact 兼容老 ILIKE 行为，仅在精确关键词命中时返回。
-`,
+    summary: "Semantic search across news and analyst views.",
+    description: 'Hybrid semantic search across news and analyst views that generalizes beyond exact keywords. It combines exact entity matching (security codes, analysts), semantic (embedding-based) recall, and fuzzy matching, then fuses and re-ranks results with time decay and a weighting toward analyst views as the primary source. For example, searching "锂电池" surfaces the broader new-energy supply chain (cathode/anode materials, lithium carbonate, leading battery makers). Pass `mode=exact` for legacy exact-keyword behavior.',
     example: "echopai search semantic --q 锂电池"
   },
-  "securities.industry": {
-    summary: "TDX + 申万 industry classification for one A-share security",
-    description: `返回该股票的 TDX 自定义行业代码（T1001 食品饮料等）与申万行业三级代码
-L1/L2/L3（X5001 食品饮料 / X500102 白酒 等）。
-
-用法：
-- 股票详情页"申万行业：白酒 / 食品饮料"标签
-- 筛选器交叉过滤：行业 + ROE/营收增长率
-- AI agent \`find_peers(code)\` 用申万二级行业找同业
-`,
-    example: "echopai securities industry --code SSE:600519"
-  },
   "semantic.find": {
-    summary: "Find A-share securities by name / code / pinyin",
-    description: "Find A-share securities matching a name (Chinese), code (e.g. 600519), or pinyin initials (e.g. gzmt). Use this when an agent has a description and needs canonical codes.",
+    summary: "Resolve A-share securities by name, code, or pinyin.",
+    description: "Finds A-share securities matching a Chinese name, a code (e.g. `600519`), or pinyin initials (e.g. `gzmt`). Use it to turn a free-form description into canonical codes (e.g. `SSE:600519`).",
     example: "echopai semantic find --query 贵州茅台"
   },
   "sentiment.breadth": {
-    summary: "Intraday breadth time series",
-    description: "Intraday breadth time series for one trading day.\n`trade_date` 缺省 → 今日（盘前 9:00 前返回空 items）；显式传 YYYY-MM-DD 可\n拉历史任意交易日（来源 ClickHouse `market_breadth_intraday`，剔除 13:00\n稀疏分钟，单日最多 241 行）。Requires `sentiment:read` scope.\n",
+    summary: "Get the intraday market-breadth time series.",
+    description: "Returns the intraday market-breadth time series for one trading day. Omit `trade_date` for today (returns empty before 9:00); pass `YYYY-MM-DD` for any historical trading day (sparse minutes around the lunch break are excluded; up to 241 rows per day). Requires the `sentiment:read` scope.",
     example: "echopai sentiment breadth"
   },
   "sentiment.overview": {
-    summary: "Aggregate market sentiment indicators",
-    description: "Aggregate sentiment snapshot for one trading day's latest minute:\nlimit-up/down counts, breadth, divergence index, MA / 52w breadth.\n`trade_date` 缺省 → 今日（Redis 实时，盘前 9:00 前返空结构）；显式传\nYYYY-MM-DD 拉历史任意日（最后一分钟聚合行，来源 ClickHouse\n`market_breadth_intraday`）。Requires `sentiment:read` scope.\n",
+    summary: "Get aggregate market sentiment indicators.",
+    description: "Returns an aggregate sentiment snapshot for the latest minute of one trading day: limit-up/down counts, breadth, divergence index, and moving-average / 52-week breadth. Omit `trade_date` for today's real-time snapshot (returns an empty structure before 9:00); pass `YYYY-MM-DD` for any historical day (the day's final aggregated minute). Requires the `sentiment:read` scope.",
     example: "echopai sentiment overview --scope main_board"
   },
   "sentiment.pct-distribution": {
-    summary: "Distribution of intraday percent change across the universe",
-    description: "返回 A 股全市场涨跌幅分桶（≤-10% / -9% / ... / +10% / 涨停）的家数分布，用于市场宽度可视化。",
+    summary: "Get the intraday percent-change distribution.",
+    description: "Returns the distribution of intraday percent change across the full A-share universe, bucketed (≤-10% / -9% / ... / +10% / limit-up), for visualizing market breadth.",
     example: "echopai sentiment pct-distribution"
   },
   "sentiment.turnover": {
-    summary: "Intraday turnover time series",
-    description: "Intraday turnover time series across one or more trading days.\n`trade_date` 缺省 → 今日（盘前 9:00 前返空 items）；显式 YYYY-MM-DD 拉\n历史任意交易日的当日 + 之前 `days-1` 天。Response 含 `current_turnover`\n/ `predicted_total` / `delta_vs_yesterday` headline 字段。Requires\n`sentiment:read` scope.\n",
+    summary: "Get the intraday turnover time series.",
+    description: "Returns the intraday turnover time series across one or more trading days. Omit `trade_date` for today (returns empty before 9:00); pass `YYYY-MM-DD` for that day plus the preceding `days-1` days. The response includes headline fields `current_turnover`, `predicted_total`, and `delta_vs_yesterday`. Requires the `sentiment:read` scope.",
     example: "echopai sentiment turnover"
   },
   "stocks.hot": {
-    summary: "Today's hot-stock leaderboard",
-    description: "今日最热股票榜（来源 East-Money），按搜索 / 关注 / 评论综合分排序。",
+    summary: "Get today's hot-stock leaderboard.",
+    description: "Returns today's most-popular A-share stocks, ranked by a composite score of searches, follows, and comments.",
     example: "echopai stocks hot"
   },
   "stocks.social-hot": {
-    summary: "Cross-platform social-hot stocks",
-    description: "跨平台（微博 / 雪球 / Twitter）社交媒体提及聚合榜，按提及量 / 情感打分。",
+    summary: "Get cross-platform social-hot stocks.",
+    description: "Returns a leaderboard of A-share stocks aggregated by social-media mentions across multiple platforms, ranked by mention volume and sentiment score.",
     example: "echopai stocks social-hot"
   },
   "views.document": {
-    summary: "Fetch the full research-report text behind a view",
-    description: "取一条研报 view 背后的全文（mineru 解析的 parsed_md）。仅 `full_text_available=true` 的 view 可用（gdrive 研报）。大文档默认 format=outline 只回标题目录 + total_chars；format=full 按 offset/max_chars 切片正文并给 next_offset 游标翻页。需要 `views:read` scope。CLI 顶层 curated 别名：`report`（`echopai report <view_id>`）。",
+    summary: "Get the full research-report text behind a view.",
+    description: "Returns the full parsed text of the research report behind one view. Available only for views with `full_text_available=true`. Large documents default to `format=outline`, returning a heading-only table of contents plus total character count; use `format=full` with `offset` / `max_chars` to page through the body via the `next_offset` cursor. Requires the `views:read` scope.",
     example: "echopai views document VALUE"
   },
   "views.feed": {
-    summary: "List analyst views",
-    description: "分析师观点 / 卖方研报 / 长文本观点流。可按机构 / 分析师 / 证券 / hours 过滤。需要 `views:read` scope。",
+    summary: "List analyst views.",
+    description: "Returns a stream of analyst views, sell-side research, and long-form opinion. Filter by institution, analyst, security, or recency (`hours`). Partner/agent callers receive `fields=compact` by default (id, ai_summary, attribution, tagged securities, first ~300 chars of content); pass `fields=full` for complete content. Requires the `views:read` scope.",
     example: "echopai views feed"
   },
   "views.get": {
-    summary: "Fetch a single analyst view",
-    description: "返回单条 view 完整内容、附件图片、tagged securities、AI 摘要。",
+    summary: "Get a single analyst view.",
+    description: "Returns the full content of one analyst view: body, attached images, tagged securities, and AI summary.",
     example: "echopai views get VALUE"
   },
   "views.recent": {
-    summary: "Recent broker / analyst views",
-    description: "List recent broker / analyst views (research notes, price targets, ratings). Filter by analyst, institution, or a specific security. Requires `views:read` scope.",
+    summary: "List recent analyst views.",
+    description: "Returns recent broker / analyst views (research notes, price targets, ratings). Filter by analyst, institution, or a specific security. Requires the `views:read` scope.",
     example: "echopai views recent --security HK:00700"
   }
 };
@@ -7898,7 +7603,7 @@ L1/L2/L3（X5001 食品饮料 / X500102 白酒 等）。
 function verbToRecord(spec) {
   let inputSchema;
   try {
-    inputSchema = z17.toJSONSchema(z17.object(spec.inputSchema));
+    inputSchema = z18.toJSONSchema(z18.object(spec.inputSchema));
   } catch {
     inputSchema = {
       type: "object",
@@ -8410,26 +8115,27 @@ try {
   }
 } catch {}
 var program = new Command31;
-program.name("echopai").description(`EchoPai CLI v1 — partner-grade access to stock-market data, news, sentiment,
-` + `and analyst views.
+program.name("echopai").description(`Command-line access to the EchoPai market-data platform: quotes, news,
+` + `analyst research, fundamentals, and sentiment.
 
-` + `AI-First: JSON envelope on stdout, JSON errors on stderr, three-state exit
-` + `codes (0 success / 1 user error / 2 service error). Set ECHOPAI_KEY env
-` + "var or run `echopai login`.").version(CLI_VERSION, "-V, --version").addOption(new Option23("--debug", "Print HTTP wire trace to stderr (Bearer redacted)")).addOption(new Option23("--raw", "Pass through raw response body (skip envelope wrap)")).addOption(new Option23("--jq <jmespath>", "Transform data with JMESPath expression (renamed from --query to avoid clash with news.search etc.)")).addOption(new Option23("--fields <a,b,c>", "Keep only listed top-level fields per item")).addOption(new Option23("--max-bytes <n>", "Truncate serialized envelope to N bytes (sets meta.truncated)")).addOption(new Option23("--yes", "Confirm a write op in non-TTY mode (required for sideEffect=write in agents / CI)")).addOption(new Option23("--dry-run", "Send X-Dry-Run:1 on write ops where the server advertises dry-run support")).addHelpText("after", `
-Authentication:  ECHOPAI_KEY=<eps_live_<lookup>_<secret>> echopai <cmd>
-` + `Raw mirror:      echopai raw <noun> <verb>   # all OpenAPI ops, e.g. raw news search
-` + `Curated verbs:   echopai <verb>              # task-level entry (Phase 3.6+)
-` + `Market session:  echopai market status                          # pre-open/open/lunch/closed + next trading day
-` + `Market movers:   echopai market movers --sort pct --top 20      # /market 行情榜（pct / pct_asc / speed / amount / turnover / total_mv）
-` + `Announcements:   echopai announcements stock --code SSE:600519  # cninfo A-share disclosures
-` + `Concepts:        echopai concepts alerts                        # 当前激活的概念异动（big_move / limit_up_cluster）
-` + `Limit-up:        echopai limit-up summary                       # 涨停数 / 炸板数 / 连板梯队
-` + `Fundamentals:    echopai financials quote-snapshot --code SSE:600519   # PE/PB/PS/换手率/股息率/量比 14-field snapshot
+` + `Machine-readable by design — a JSON envelope on stdout, JSON errors on
+` + `stderr, and three-state exit codes (0 success / 1 user error / 2 service
+` + `error) — built for AI agents and scripts. Authenticate with the
+` + "ECHOPAI_KEY environment variable or `echopai login`.").version(CLI_VERSION, "-V, --version").addOption(new Option23("--debug", "Print HTTP wire trace to stderr (Bearer redacted)")).addOption(new Option23("--raw", "Pass through raw response body (skip envelope wrap)")).addOption(new Option23("--jq <jmespath>", "Filter or transform output with a JMESPath expression.")).addOption(new Option23("--fields <a,b,c>", "Keep only listed top-level fields per item")).addOption(new Option23("--max-bytes <n>", "Truncate serialized envelope to N bytes (sets meta.truncated)")).addOption(new Option23("--yes", "Confirm a write op in non-TTY mode (required for sideEffect=write in agents / CI)")).addOption(new Option23("--dry-run", "Send X-Dry-Run:1 on write ops where the server advertises dry-run support")).addHelpText("after", `
+Authentication:  ECHOPAI_KEY=<eps_live_...> echopai <command>
+` + `Curated verbs:   echopai <verb>                                  # task-level commands (recommended)
+` + `Raw operations:  echopai raw <noun> <verb>                       # low-level access to every API operation
+` + `Market session:  echopai market status                          # trading phase + next trading day
+` + `Market movers:   echopai market movers --sort pct --top 20      # ranked movers (pct / speed / amount / turnover / total_mv)
+` + `Announcements:   echopai announcements stock --code SSE:600519  # listed-company disclosures
+` + `Concepts:        echopai concepts alerts                        # active concept-board alerts
+` + `Limit-up:        echopai limit-up summary                       # limit-up / failed-board / consecutive-board ladder
+` + `Fundamentals:    echopai financials quote-snapshot --code SSE:600519   # 14-field valuation snapshot
 ` + `Capability:      echopai whoami | echopai doctor
-` + `Schema dump:     echopai schema export       # AI agents pipe this for command surface
+` + `Schema dump:     echopai schema export                          # machine-readable command surface for agents
 ` + `Profile:         echopai config profile add prod --base-url https://api.echopai.com
-` + `Self-update:     echopai upgrade [--check] [--exec]   # npm 装查 registry / 二进制装查 CDN；--exec 自动升级
-` + `MCP:             echopai mcp install                  # 注册进 Claude Code（claude mcp add，幂等）
+` + `Self-update:     echopai upgrade [--check] [--exec]
+` + `MCP:             echopai mcp install                            # register with Claude Code
 `);
 var dispatch = async (op, args) => {
   const globals = program.opts();
@@ -8458,7 +8164,7 @@ function applyAiFirstHooks(cmd) {
   for (const sub of cmd.commands)
     applyAiFirstHooks(sub);
 }
-var rawCmd = new Command31("raw").description("Raw 1:1 mirror of OpenAPI operations (escape hatch for power users / scripts)");
+var rawCmd = new Command31("raw").description("Low-level access to every API operation (advanced; bypasses the curated verbs).");
 buildCommandTree(rawCmd, dispatch);
 rawCmd.addCommand(buildRawCallCommand());
 program.addCommand(rawCmd);