echopai 2.6.1 → 2.7.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",
@@ -588,12 +579,8 @@ See \`docs/PLAN_CLI_V2_AGENT_SURFACE.md\` §5.1.
     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 +605,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 +655,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 +701,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 +758,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 +804,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 +852,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 +888,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 +919,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 +960,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 +1015,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 +1055,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 +1096,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 +1148,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 +1207,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 +1256,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 +1303,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 +1330,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 +1368,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 +1402,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",
@@ -1666,8 +1448,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 +1489,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 +1516,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.",
+    summary: "List recent news.",
     positional: [],
     outputDefault: "json",
     pagination: "offset",
@@ -1756,8 +1538,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 +1570,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",
@@ -1852,8 +1634,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",
@@ -1917,10 +1699,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 +1745,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 +1795,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. 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 +1851,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. During the 9:00–9:14 pre-open auction an empty result is returned with an explanatory note. 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",
@@ -2144,15 +1890,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 +1953,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 +1998,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 +2041,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 +2085,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 +2109,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 +2159,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 +2181,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 +2203,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 +2259,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`). Requires the `views:read` scope.",
+    summary: "List analyst views.",
     positional: [],
     outputDefault: "json",
     pagination: "offset",
@@ -2581,8 +2281,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 +2313,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",
@@ -2728,7 +2428,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 +2444,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 +2464,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 +2472,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);
@@ -2792,7 +2492,7 @@ function buildCommandTree(program, 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 +2540,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 +2560,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 +2574,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 +2596,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 +2604,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 +2624,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 +2634,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 +2648,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 +2664,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 +2684,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 +2696,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 +3619,7 @@ import os2 from "node:os";
 import path2 from "node:path";
 
 // src/version.ts
-var CLI_VERSION = "2.6.1";
+var CLI_VERSION = "2.7.0";
 
 // src/runtime/update_check.ts
 var UPDATE_CACHE_PATH = path2.join(os2.homedir(), ".config", "echopai", "update_cache.json");
@@ -7526,370 +7186,273 @@ import { z as z17 } 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']"
   },
   "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.",
     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. 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. During the 9:00–9:14 pre-open auction an empty result is returned with an explanatory note. 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`). 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"
   }
 };
@@ -8410,26 +7973,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 +8022,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);