alphacouncil-agent 0.5.3 → 0.5.5

package/.claude/commands/alpha.md

@@ -22,24 +22,32 @@ Request: **$ARGUMENTS**
 When `$ARGUMENTS` is empty, print exactly this and stop:
 
 ```
-/alpha MU              full council — asks which preset first
-/alpha MU quick        4 analysts + debate, no bench, no verification
-/alpha MU screen       mechanical filings screen only        (no model spend)
-/alpha MU options      IV term structure, skew, positioning  (no model spend)
-/alpha MU news         dated filings and headlines           (no model spend)
-/alpha market AI       what the market is talking about      (no model spend)
+/alpha <TICKER>          full council — asks which preset first
+/alpha <TICKER> quick    4 analysts + debate, no bench, no verification
+/alpha <TICKER> screen   mechanical filings screen only        (no model spend)
+/alpha <TICKER> options  IV term structure, skew, positioning  (no model spend)
+/alpha <TICKER> news     dated filings and headlines           (no model spend)
+/alpha market <theme>    what the market is talking about      (no model spend)
+
+examples
+  /alpha AAPL            /alpha 0700.HK quick     /alpha 7203.T news
+  /alpha NVDA screen     /alpha market rates      /alpha "is TSM cheap?"
 ```
 
+Any listed equity. Filings-based modes need a US filer; for other markets say which market it
+is and use `market_coverage`, rather than returning nothing.
+
 Say plainly that the four marked modes call keyless data tools and spawn no subagents, so
 they cost nothing beyond this turn. The council modes spawn one subagent per seat, and that
 is where the spend is.
 
 ## Full council
 
-1. **Ask which preset first.** Call `list_council_options` and present the three with their
-   seat counts. A council is 7 to 44 seats and that range is the user's time and money.
-   **Skip the question when the request already answered it** — a named roster, "everything",
-   "be quick". A confirmation nobody needed is an interruption.
+1. **Ask which masters, once, then run.** Call `list_council_options` and ask only about the
+   master bench — the six schools by name with their members, plus "all" and "none". Analysts
+   default to the eight-seat fan-out; do not ask about them. After the answer, start
+   immediately: no preset question, no confirmation. **Skip the question entirely** when the
+   request already said (a named school, "everything", "no masters", "be quick").
 2. Follow `skills/alphacouncil-agent/SKILL.md` from Stage 0. Do not improvise a shorter
    workflow: a report that looks finished and skipped the bench is worse than an obviously
    partial one.

package/.claude-plugin/marketplace.json

@@ -6,14 +6,14 @@
   },
   "metadata": {
     "description": "AlphaCouncil plugins for public-equity research.",
-    "version": "0.5.3"
+    "version": "0.5.5"
   },
   "plugins": [
     {
       "name": "alphacouncil-agent",
       "source": "./",
       "description": "Multi-agent equity research: evidence packets, bull/bear debate, portfolio-manager decision.",
-      "version": "0.5.3",
+      "version": "0.5.5",
       "author": {
         "name": "Zhao73"
       },

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "alphacouncil-agent",
-  "version": "0.5.3",
+  "version": "0.5.5",
   "description": "Multi-agent public-equity research workflow for Claude Code: spawns analyst workers, gathers sourced JSON evidence packets, runs bull/bear debate, and produces a portfolio-manager Buy/Overweight/Hold/Underweight/Sell decision with a full report.",
   "author": {
     "name": "Zhao73"

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "alphacouncil-agent",
-  "version": "0.5.3",
+  "version": "0.5.5",
   "description": "Host-visible or background public-equity research workflow with shared evidence packets.",
   "author": {
     "name": "Zhao73"

package/.grok/commands/alpha.md

@@ -22,24 +22,32 @@ Request: **$ARGUMENTS**
 When `$ARGUMENTS` is empty, print exactly this and stop:
 
 ```
-/alpha MU              full council — asks which preset first
-/alpha MU quick        4 analysts + debate, no bench, no verification
-/alpha MU screen       mechanical filings screen only        (no model spend)
-/alpha MU options      IV term structure, skew, positioning  (no model spend)
-/alpha MU news         dated filings and headlines           (no model spend)
-/alpha market AI       what the market is talking about      (no model spend)
+/alpha <TICKER>          full council — asks which preset first
+/alpha <TICKER> quick    4 analysts + debate, no bench, no verification
+/alpha <TICKER> screen   mechanical filings screen only        (no model spend)
+/alpha <TICKER> options  IV term structure, skew, positioning  (no model spend)
+/alpha <TICKER> news     dated filings and headlines           (no model spend)
+/alpha market <theme>    what the market is talking about      (no model spend)
+
+examples
+  /alpha AAPL            /alpha 0700.HK quick     /alpha 7203.T news
+  /alpha NVDA screen     /alpha market rates      /alpha "is TSM cheap?"
 ```
 
+Any listed equity. Filings-based modes need a US filer; for other markets say which market it
+is and use `market_coverage`, rather than returning nothing.
+
 Say plainly that the four marked modes call keyless data tools and spawn no subagents, so
 they cost nothing beyond this turn. The council modes spawn one subagent per seat, and that
 is where the spend is.
 
 ## Full council
 
-1. **Ask which preset first.** Call `list_council_options` and present the three with their
-   seat counts. A council is 7 to 44 seats and that range is the user's time and money.
-   **Skip the question when the request already answered it** — a named roster, "everything",
-   "be quick". A confirmation nobody needed is an interruption.
+1. **Ask which masters, once, then run.** Call `list_council_options` and ask only about the
+   master bench — the six schools by name with their members, plus "all" and "none". Analysts
+   default to the eight-seat fan-out; do not ask about them. After the answer, start
+   immediately: no preset question, no confirmation. **Skip the question entirely** when the
+   request already said (a named school, "everything", "no masters", "be quick").
 2. Follow `skills/alphacouncil-agent/SKILL.md` from Stage 0. Do not improvise a shorter
    workflow: a report that looks finished and skipped the bench is worse than an obviously
    partial one.

package/.opencode/command/alpha.md

@@ -22,24 +22,32 @@ Request: **$ARGUMENTS**
 When `$ARGUMENTS` is empty, print exactly this and stop:
 
 ```
-/alpha MU              full council — asks which preset first
-/alpha MU quick        4 analysts + debate, no bench, no verification
-/alpha MU screen       mechanical filings screen only        (no model spend)
-/alpha MU options      IV term structure, skew, positioning  (no model spend)
-/alpha MU news         dated filings and headlines           (no model spend)
-/alpha market AI       what the market is talking about      (no model spend)
+/alpha <TICKER>          full council — asks which preset first
+/alpha <TICKER> quick    4 analysts + debate, no bench, no verification
+/alpha <TICKER> screen   mechanical filings screen only        (no model spend)
+/alpha <TICKER> options  IV term structure, skew, positioning  (no model spend)
+/alpha <TICKER> news     dated filings and headlines           (no model spend)
+/alpha market <theme>    what the market is talking about      (no model spend)
+
+examples
+  /alpha AAPL            /alpha 0700.HK quick     /alpha 7203.T news
+  /alpha NVDA screen     /alpha market rates      /alpha "is TSM cheap?"
 ```
 
+Any listed equity. Filings-based modes need a US filer; for other markets say which market it
+is and use `market_coverage`, rather than returning nothing.
+
 Say plainly that the four marked modes call keyless data tools and spawn no subagents, so
 they cost nothing beyond this turn. The council modes spawn one subagent per seat, and that
 is where the spend is.
 
 ## Full council
 
-1. **Ask which preset first.** Call `list_council_options` and present the three with their
-   seat counts. A council is 7 to 44 seats and that range is the user's time and money.
-   **Skip the question when the request already answered it** — a named roster, "everything",
-   "be quick". A confirmation nobody needed is an interruption.
+1. **Ask which masters, once, then run.** Call `list_council_options` and ask only about the
+   master bench — the six schools by name with their members, plus "all" and "none". Analysts
+   default to the eight-seat fan-out; do not ask about them. After the answer, start
+   immediately: no preset question, no confirmation. **Skip the question entirely** when the
+   request already said (a named school, "everything", "no masters", "be quick").
 2. Follow `skills/alphacouncil-agent/SKILL.md` from Stage 0. Do not improvise a shorter
    workflow: a report that looks finished and skipped the bench is worse than an obviously
    partial one.

package/AGENTS.md

@@ -76,12 +76,12 @@ rather than four in a menu of a hundred.
 
 | Invocation | What runs | Model spend |
 |---|---|---|
-| `/alpha MU` | Full council — asks which preset first | one subagent per seat |
-| `/alpha MU quick` | 4 analysts + debate, no bench, no verification | 7 seats |
-| `/alpha MU screen` | Mechanical filings screen only | **none** |
-| `/alpha MU options` | IV term structure, skew, positioning | **none** |
-| `/alpha MU news` | Dated filings and headlines | **none** |
-| `/alpha market AI` | What the market is talking about | **none** |
+| `/alpha <ticker>` | Full council — asks which preset first | one subagent per seat |
+| `/alpha <ticker> quick` | 4 analysts + debate, no bench, no verification | 7 seats |
+| `/alpha <ticker> screen` | Mechanical filings screen only | **none** |
+| `/alpha <ticker> options` | IV term structure, skew, positioning | **none** |
+| `/alpha <ticker> news` | Dated filings and headlines | **none** |
+| `/alpha market <theme>` | What the market is talking about | **none** |
 | `/alpha` | Lists the modes and stops | **none** |
 
 The four marked **none** call keyless data tools and spawn no subagents, so they cost

package/CHANGELOG.md

@@ -2,6 +2,38 @@
 
 Notable changes per release. Dates are UTC.
 
+## [0.5.5] — 2026-07-26
+
+### Fixed
+
+- **Five masters never ran.** Aschenbrenner, Druckenmiller, Fisher, Asness and Klarman were
+  not in the `masters-core` roster, which is what the standard preset selects, while the
+  seat estimate counted every master. The menu offered 21 lenses and the run delivered 16,
+  with nothing failing and nothing warning. A test now asserts the roster equals the full
+  set rather than merely being large.
+
+### Changed
+
+- **Stage 0 asks one question, about the master bench, then runs.** It previously asked which
+  preset, then which analysts, then confirmed — an interview before any work. The analysts
+  have an obvious default; the bench is the part a user has a view on and where cost varies.
+- `list_council_options` prints the **named** roster: every analyst with what it covers, and
+  the six master schools with their members. Presets remain as shortcuts. Naming the seats is
+  what made the missing five visible.
+- Command help uses `<TICKER>` with examples across US, Hong Kong and Tokyo listings. One
+  real ticker repeated down the column read as if the tool were about that company.
+
+## [0.5.4] — 2026-07-26
+
+### Fixed
+
+- `docs/INSTALL.md`, `SECURITY.md` and `CONTRIBUTING.md` were never in the package. The
+  install guide is the page an npm user reads specifically to learn how to invoke the thing,
+  and it was absent from every published version.
+- A contract test now asserts the property rather than the entries: every tracked
+  consumer-facing file must be in the package. The gaps had been surfacing one release at a
+  time — the host agent directories in 0.5.1, the install guide in 0.5.3.
+
 ## [0.5.3] — 2026-07-26
 
 ### Fixed

package/CONTRIBUTING.md

@@ -0,0 +1,65 @@
+# Contributing to AlphaCouncil Agent
+
+Thanks for your interest in improving AlphaCouncil Agent!
+
+## Development setup
+
+```bash
+git clone https://github.com/Zhao73/alphacouncil-agent.git
+cd alphacouncil-agent
+node --version      # must be >= 18
+npm run check       # runs node --check + the self-check (no Codex auth needed)
+```
+
+There are **no runtime dependencies** — the MCP server is plain Node.js standard
+library. Please keep it that way unless there is no simple standard-library path.
+
+## Before opening a pull request
+
+- Run `npm run check` and make sure it passes.
+- Preserve the JSON packet contracts in `mcp/server.mjs` (evidence packets and
+  debate packets). If you change a contract, update `scripts/selfcheck.mjs` and
+  the README/skill docs to match.
+- Keep source IDs globally scoped as `<task>:<local_source_id>`.
+- Keep the implementation small and readable.
+
+## Scope and boundaries
+
+- This is an **independent** plugin. Do not copy source code from other
+  multi-agent investment projects into this repo.
+- "Public Equity Investing" and "Investment Banking" are agent instructions /
+  skills, not importable libraries.
+- Never commit API keys, brokerage credentials, private filings, or generated
+  run artifacts (everything under `~/.alphacouncil-agent/` and `runs/` is
+  ignored by `.gitignore`).
+
+## Reporting bugs / requesting features
+
+Use the issue templates. Please include your OS, Node version, and whether you
+were using the Codex headless path or the visible workflow.
+
+## License
+
+By contributing, you agree that your contributions are licensed under the
+[MIT License](LICENSE).
+
+## Commit messages
+
+Write them from a file or a quoted heredoc, never inline in a shell string:
+
+```bash
+git commit -F /tmp/msg.txt
+# or
+git commit -F - <<'MSG'
+...
+MSG
+```
+
+Backticks in a commit message are command substitution to the shell, which silently deletes
+the text between them before git ever sees it. It happened once here, to a sentence naming
+a CLI subcommand; the words were simply gone from the published history. Quoting the
+heredoc delimiter (`<<'MSG'`, not `<<MSG`) disables expansion.
+
+If a message does go out wrong, prefer `git notes add` over `git commit --amend` once the
+commit is an ancestor of a published tag. Rewriting it leaves the release pointing at an
+object that no longer exists, which is a worse outcome than an imperfect message.

package/README.ja.md

@@ -113,16 +113,20 @@ codex plugin marketplace add Zhao73/alphacouncil-agent
 
 | 入力 | 実行内容 | モデル消費 |
 |---|---|---|
-| `/alpha MU` | フル委員会 —— 先にどのプリセットか確認します | 席ごとに 1 サブエージェント |
-| `/alpha MU quick` | アナリスト 4 名＋討論。マスター陣なし、検証なし | 7 席 |
-| `/alpha MU screen` | 機械的スクリーニングのみ | **なし** |
-| `/alpha MU options` | IV ターム構造、スキュー、建玉分布 | **なし** |
-| `/alpha MU news` | 日付付きの提出書類とニュース | **なし** |
-| `/alpha market AI` | 市場が語っている物語 | **なし** |
+| `/alpha <ticker>` | フル委員会 —— 先にどのプリセットか確認します | 席ごとに 1 サブエージェント |
+| `/alpha <ticker> quick` | アナリスト 4 名＋討論。マスター陣なし、検証なし | 7 席 |
+| `/alpha <ticker> screen` | 機械的スクリーニングのみ | **なし** |
+| `/alpha <ticker> options` | IV ターム構造、スキュー、建玉分布 | **なし** |
+| `/alpha <ticker> news` | 日付付きの提出書類とニュース | **なし** |
+| `/alpha market <theme>` | 市場が語っている物語 | **なし** |
 | `/alpha` | モード一覧を出して停止 | **なし** |
 
 **なし** と記した 4 つはキー不要のデータツールを呼ぶだけで、サブエージェントを一切起動しません。入力したそのターン以外に消費はありません。委員会モードは席ごとにサブエージェントを起動し、それがこのプラグインのコストのすべてです。
 
+上場銘柄なら何でも：`/alpha AAPL` · `/alpha 0700.HK quick` · `/alpha 7203.T news` · `/alpha market rates`。
+提出書類ベースのモードは米国登録企業が必要です。他市場は黙って空を返すのではなく `market_coverage` で対応状況を示します。
+
+
 Claude Code、OpenCode、Grok Build ではインストール後すぐ使えます。Codex の prompts はユーザースコープなので一度コピーしてください：
 `mkdir -p ~/.codex/prompts && cp commands/alpha.md ~/.codex/prompts/`
 

package/README.md

@@ -130,18 +130,22 @@ rather than four in a menu of a hundred.
 
 | Invocation | What runs | Model spend |
 |---|---|---|
-| `/alpha MU` | Full council — asks which preset first | one subagent per seat |
-| `/alpha MU quick` | 4 analysts + debate, no bench, no verification | 7 seats |
-| `/alpha MU screen` | Mechanical filings screen only | **none** |
-| `/alpha MU options` | IV term structure, skew, positioning | **none** |
-| `/alpha MU news` | Dated filings and headlines | **none** |
-| `/alpha market AI` | What the market is talking about | **none** |
+| `/alpha <ticker>` | Full council — asks which preset first | one subagent per seat |
+| `/alpha <ticker> quick` | 4 analysts + debate, no bench, no verification | 7 seats |
+| `/alpha <ticker> screen` | Mechanical filings screen only | **none** |
+| `/alpha <ticker> options` | IV term structure, skew, positioning | **none** |
+| `/alpha <ticker> news` | Dated filings and headlines | **none** |
+| `/alpha market <theme>` | What the market is talking about | **none** |
 | `/alpha` | Lists the modes and stops | **none** |
 
 The four marked **none** call keyless data tools and spawn no subagents, so they cost
 nothing beyond the turn you type them in. The council modes spawn one subagent per seat, and
 that is the entire cost of running this.
 
+Any listed equity: `/alpha AAPL` · `/alpha 0700.HK quick` · `/alpha 7203.T news` · `/alpha market rates`.
+Filings-based modes need a US filer; other markets are reported through `market_coverage` rather than silently returning nothing.
+
+
 Available in Claude Code, OpenCode and Grok Build as soon as the plugin is installed. Codex keeps
 its prompts user-scoped, so copy it once: `mkdir -p ~/.codex/prompts && cp commands/alpha.md ~/.codex/prompts/`
 

package/README.zh-CN.md

@@ -113,16 +113,20 @@ codex plugin marketplace add Zhao73/alphacouncil-agent
 
 | 输入 | 跑什么 | 额度消耗 |
 |---|---|---|
-| `/alpha MU` | 完整议会 —— 先问你跑哪个预设 | 每席一个子代理 |
-| `/alpha MU quick` | 4 分析师 + 辩论，无大师、无验证 | 7 席 |
-| `/alpha MU screen` | 只跑机械筛选 | **零** |
-| `/alpha MU options` | 隐含波动率期限结构、偏斜、持仓分布 | **零** |
-| `/alpha MU news` | 带日期的申报与新闻 | **零** |
-| `/alpha market AI` | 市场在讲什么故事 | **零** |
+| `/alpha <ticker>` | 完整议会 —— 先问你跑哪个预设 | 每席一个子代理 |
+| `/alpha <ticker> quick` | 4 分析师 + 辩论，无大师、无验证 | 7 席 |
+| `/alpha <ticker> screen` | 只跑机械筛选 | **零** |
+| `/alpha <ticker> options` | 隐含波动率期限结构、偏斜、持仓分布 | **零** |
+| `/alpha <ticker> news` | 带日期的申报与新闻 | **零** |
+| `/alpha market <theme>` | 市场在讲什么故事 | **零** |
 | `/alpha` | 列出模式后停下 | **零** |
 
 标「零」的四个只调免 key 数据工具、**不启动任何子代理**，除了你敲的这一轮之外不消耗额度。议会模式每个席位起一个子代理，那是这个插件的全部成本所在。
 
+任何上市股票：`/alpha AAPL` · `/alpha 0700.HK quick` · `/alpha 7203.T news` · `/alpha market rates`。
+基于申报的模式需要美国申报主体；其他市场会通过 `market_coverage` 说明覆盖情况，而不是静默返回空结果。
+
+
 Claude Code、OpenCode、Grok Build 装完即可用。Codex 的 prompts 是用户级的，拷贝一次：
 `mkdir -p ~/.codex/prompts && cp commands/alpha.md ~/.codex/prompts/`
 

package/SECURITY.md

@@ -0,0 +1,28 @@
+# Security Policy
+
+## Reporting a vulnerability
+
+Please **do not** open a public issue for security problems. Instead, report
+privately via GitHub's **"Report a vulnerability"** button under the repository's
+**Security** tab (Security advisories), or contact the maintainer directly.
+
+We aim to acknowledge reports within a few days.
+
+## Scope and notes
+
+AlphaCouncil Agent runs an autonomous research workflow. Be aware that:
+
+- The headless path spawns `codex exec` worker processes that perform **live web
+  search**. Treat fetched content as untrusted; the agents are instructed not to
+  act on embedded instructions, but you should review outputs before relying on
+  them.
+- Run artifacts under `~/.alphacouncil-agent/runs/<run_id>/` may contain text
+  captured from third-party pages. These are **not** committed (ignored by
+  `.gitignore`) — mind what you share.
+- Never commit API keys, tokens, brokerage credentials, or private filings.
+- This software is for educational/research use only and is **not investment
+  advice** (see the README disclaimer).
+
+## Supported versions
+
+This project is pre-1.0. Only the latest `main` is supported.

package/commands/alpha.md

@@ -22,24 +22,32 @@ Request: **$ARGUMENTS**
 When `$ARGUMENTS` is empty, print exactly this and stop:
 
 ```
-/alpha MU              full council — asks which preset first
-/alpha MU quick        4 analysts + debate, no bench, no verification
-/alpha MU screen       mechanical filings screen only        (no model spend)
-/alpha MU options      IV term structure, skew, positioning  (no model spend)
-/alpha MU news         dated filings and headlines           (no model spend)
-/alpha market AI       what the market is talking about      (no model spend)
+/alpha <TICKER>          full council — asks which preset first
+/alpha <TICKER> quick    4 analysts + debate, no bench, no verification
+/alpha <TICKER> screen   mechanical filings screen only        (no model spend)
+/alpha <TICKER> options  IV term structure, skew, positioning  (no model spend)
+/alpha <TICKER> news     dated filings and headlines           (no model spend)
+/alpha market <theme>    what the market is talking about      (no model spend)
+
+examples
+  /alpha AAPL            /alpha 0700.HK quick     /alpha 7203.T news
+  /alpha NVDA screen     /alpha market rates      /alpha "is TSM cheap?"
 ```
 
+Any listed equity. Filings-based modes need a US filer; for other markets say which market it
+is and use `market_coverage`, rather than returning nothing.
+
 Say plainly that the four marked modes call keyless data tools and spawn no subagents, so
 they cost nothing beyond this turn. The council modes spawn one subagent per seat, and that
 is where the spend is.
 
 ## Full council
 
-1. **Ask which preset first.** Call `list_council_options` and present the three with their
-   seat counts. A council is 7 to 44 seats and that range is the user's time and money.
-   **Skip the question when the request already answered it** — a named roster, "everything",
-   "be quick". A confirmation nobody needed is an interruption.
+1. **Ask which masters, once, then run.** Call `list_council_options` and ask only about the
+   master bench — the six schools by name with their members, plus "all" and "none". Analysts
+   default to the eight-seat fan-out; do not ask about them. After the answer, start
+   immediately: no preset question, no confirmation. **Skip the question entirely** when the
+   request already said (a named school, "everything", "no masters", "be quick").
 2. Follow `skills/alphacouncil-agent/SKILL.md` from Stage 0. Do not improvise a shorter
    workflow: a report that looks finished and skipped the bench is worse than an obviously
    partial one.

package/docs/INSTALL.md

@@ -0,0 +1,295 @@
+# Install AlphaCouncil Agent
+
+AlphaCouncil Agent runs in **OpenAI Codex** and **Claude Code**. It also loads as a
+plain MCP server in the Claude desktop app.
+
+> ⚠️ **Disclaimer.** Educational/research use only. **Not investment advice.**
+> AI analysis can be incomplete, outdated, or wrong. Do your own research and
+> consult a licensed professional before any investment decision.
+
+---
+
+
+## npm
+
+```bash
+npm install -g alphacouncil-agent
+```
+
+Then point any MCP host at the `alphacouncil-agent` binary. For Claude Code:
+
+```json
+{ "mcpServers": { "alphacouncil-agent": { "command": "alphacouncil-agent" } } }
+```
+
+For OpenCode, `command` takes an argv array:
+
+```json
+{ "mcp": { "alphacouncil-agent": { "type": "local", "command": ["alphacouncil-agent"] } } }
+```
+
+Or run it without installing: `npx alphacouncil-agent`.
+
+## Configuration: none required
+
+There is nothing to configure. Every core data source is keyless — SEC EDGAR for US
+filings, TWSE for Taiwan, Yahoo and Stooq for quotes and macro — and the package has no
+dependencies, so the install is the download and nothing else.
+
+Two optional free keys widen coverage. Without them the tools still answer; they report
+which market is missing a feed and which variable would unlock it, and analysts are told
+that figures for those names must come from a primary document and be cited as such.
+
+| Variable | Unlocks | Register |
+|---|---|---|
+| `ALPHACOUNCIL_DART_KEY` | Korean filings (Samsung, SK hynix) | <https://opendart.fss.or.kr> |
+| `ALPHACOUNCIL_EDINET_KEY` | Japanese filings (Kioxia, Tokyo Electron) | EDINET portal |
+| `ALPHACOUNCIL_SEC_USER_AGENT` | Your own SEC contact, advisable at volume | n/a |
+
+Run `node scripts/doctor.mjs` at any time to see which copy is running, whether the
+persona set loads, and what the data directory holds.
+
+## How to invoke it once installed
+
+One command, `/alpha`. Modes are arguments.
+
+```text
+/alpha <ticker>              full council — asks which preset first
+/alpha <ticker> quick        4 analysts + debate, no bench, no verification
+/alpha <ticker> screen       mechanical filings screen only        (no model spend)
+/alpha <ticker> options      IV term structure, skew, positioning  (no model spend)
+/alpha <ticker> news         dated filings and headlines           (no model spend)
+/alpha market <theme>       what the market is talking about      (no model spend)
+/alpha                 lists the modes and stops             (no model spend)
+```
+
+The four marked *no model spend* call keyless data tools and spawn no subagents. **Start
+there** — they show real data at no cost, so you can see the shape of the thing before
+committing a fan-out. The council modes spawn one subagent per seat: 7 for `quick`, 32 for
+the standard preset, 44 for deep.
+
+Codex keeps prompts user-scoped rather than in the plugin, so copy it once:
+
+```bash
+mkdir -p ~/.codex/prompts && cp commands/alpha.md ~/.codex/prompts/
+```
+
+`@alphacouncil-agent <question>` still works everywhere and does the same thing.
+
+## Prerequisites
+
+- **Node.js ≥ 18** (the MCP server is ESM and uses modern Node APIs).
+- For the **headless research path** (`analyze_symbol` / `collect_evidence`):
+  an installed and authenticated **Codex CLI**, because each analyst worker is
+  launched as `codex exec`. Without it, headless workers fail; use the
+  **visible workflow** instead (the host agent does the research and records
+  packets — no `codex` binary required).
+
+Verify:
+
+```bash
+node --version      # >= 18
+codex --version     # only needed for the headless path
+npm run check       # runs the self-check (no Codex auth required)
+```
+
+---
+
+## Install in Codex
+
+This repo already ships the manifests Codex expects, at the official paths:
+`.agents/plugins/marketplace.json` (repo marketplace), `.codex-plugin/plugin.json`
+(plugin manifest), and `.mcp.json` (MCP server) — so the one-command install below
+works out of the box. (`.claude-plugin/marketplace.json` is kept for legacy compat.)
+
+### A. One command — recommended ✅
+
+```text
+codex plugin marketplace add Zhao73/alphacouncil-agent
+```
+
+Then **fully quit and restart the Codex desktop app** (plugins load at session
+start — see [Troubleshooting](#troubleshooting-the-plugin-doesnt-show-up--alphacouncil-agent-isnt-found)),
+open a new session, and:
+
+```text
+/plugins            # switch to the "AlphaCouncil" marketplace → Install alphacouncil-agent
+/reload-plugins
+```
+
+### B. Local clone — advanced / offline only
+
+```bash
+git clone https://github.com/Zhao73/alphacouncil-agent.git \
+  ~/.codex/plugins/alphacouncil-agent
+```
+
+Then add an entry to `~/.agents/plugins/marketplace.json` whose `source.path` is the
+**absolute** path to that clone (copy the shape from `.agents/plugins/marketplace.json`
+in this repo; on Windows use `C:\\Users\\you\\.codex\\plugins\\alphacouncil-agent`, not
+`./`), restart Codex, and install from `/plugins`. **Prefer A** unless you're doing
+offline/local development — it avoids hand-editing paths.
+
+**Use it:**
+
+```text
+@alphacouncil-agent analyze AAPL as a long/short pitch
+@alphacouncil-agent 帮我看看 NOK
+```
+
+---
+
+## Install in Claude Code
+
+This repo ships a Claude Code plugin manifest (`.claude-plugin/plugin.json`) and
+acts as its own marketplace (`.claude-plugin/marketplace.json`).
+
+```text
+/plugin marketplace add Zhao73/alphacouncil-agent
+/plugin install alphacouncil-agent@alphacouncil
+/reload-plugins
+```
+
+Or wire just the MCP server, without the plugin system:
+
+```bash
+claude mcp add alphacouncil-agent -- node /absolute/path/to/alphacouncil-agent/mcp/server.mjs
+```
+
+**Two ways to actually run the research in Claude Code:**
+
+1. **With Codex CLI installed & authenticated** — the headless `analyze_symbol`
+   path works as-is (it shells out to `codex exec`).
+2. **Without Codex** — use the visible path: let Claude Code's own subagents act
+   as the analysts, then record their JSON with `record_visible_packet` /
+   `record_visible_decision`. The MCP tools `plan_visible_run` /
+   `record_visible_*` never call `codex`, so this runs fully inside Claude.
+
+---
+
+## Claude desktop app (MCP only)
+
+Add the MCP server in the app's connector/MCP settings, pointing `command` to
+`node` and `args` to the absolute path of `mcp/server.mjs`. Tools will load; the
+headless path still needs Codex CLI as above.
+
+---
+
+## Troubleshooting: the plugin doesn't show up / `@alphacouncil-agent` isn't found
+
+Codex loads its tool list **at session start**. Installing or enabling a plugin
+mid-session does **not** hot-add it to the current conversation — even if the files
+are installed, `config.toml` marks it enabled, and the self-check passes.
+
+Do this in order:
+
+1. **Fully quit and restart the Codex desktop app** (not just a new tab) and open a **new session**.
+2. Type `/plugins` and confirm **AlphaCouncil** is listed; enable `alphacouncil-agent`.
+3. Type `/reload-plugins`.
+4. Trigger it with the **exact lowercase id**: `@alphacouncil-agent ...`. The display
+   name `@AlphaCouncil Agent` (spaces + capitals) may not trigger — prefer the id.
+
+If `/plugins` **still** doesn't list it after a full restart, your Codex build didn't
+pick up the local marketplace. Use the official GitHub marketplace command instead (run
+in a normal terminal), then restart Codex:
+
+```text
+codex plugin marketplace add Zhao73/alphacouncil-agent
+```
+
+> Local-clone install (Option B): the `source.path` in your
+> `~/.agents/plugins/marketplace.json` must be the **absolute** path to the clone
+> (e.g. `C:\\Users\\you\\.codex\\plugins\\alphacouncil-agent`), **not** `./`. When in
+> doubt, use the GitHub marketplace command above — it avoids hand-editing paths.
+
+## Windows
+
+### Prerequisites (Windows)
+
+- **Node.js ≥ 18** — install from [nodejs.org](https://nodejs.org), or in PowerShell:
+  `winget install OpenJS.NodeJS.LTS`. Verify with `node --version`.
+- (Headless path only) the Codex CLI installed and authenticated. v0.3.0+ supports
+  native Windows `codex.cmd` installs; WSL is only a fallback if your Codex CLI
+  itself does not work from PowerShell/CMD.
+
+### Install in Codex desktop (Windows)
+
+The in-app commands are identical to macOS/Linux — they run **inside Codex**, not in your
+shell, so the OS does not matter:
+
+```text
+codex plugin marketplace add Zhao73/alphacouncil-agent
+# then open Codex → /plugins → switch to the "AlphaCouncil" marketplace → Install → /reload-plugins
+```
+
+Local / personal marketplace (Windows paths). In PowerShell:
+
+```powershell
+git clone https://github.com/Zhao73/alphacouncil-agent.git "$env:USERPROFILE\.codex\plugins\alphacouncil-agent"
+```
+
+Then add an entry to `%USERPROFILE%\.agents\plugins\marketplace.json` whose `source.path`
+points at that folder (copy the shape from `.agents/plugins/marketplace.json` in this repo).
+In JSON, escape Windows backslashes, e.g.:
+
+```json
+{ "source": { "path": "C:\\Users\\you\\.codex\\plugins\\alphacouncil-agent" } }
+```
+
+Restart Codex and install from `/plugins`.
+
+### Install in Claude Code (Windows)
+
+Identical to other platforms (the commands run inside Claude Code):
+
+```text
+/plugin marketplace add Zhao73/alphacouncil-agent
+/plugin install alphacouncil-agent@alphacouncil
+/reload-plugins
+```
+
+The Claude Code **visible path works natively on Windows** — it never spawns the `codex`
+binary; your Claude Code subagents do the research and record packets via
+`record_visible_*`. **This is the recommended Windows path.**
+
+### Runtime notes (Windows)
+
+The **headless Codex path** (`analyze_symbol` / `collect_evidence`, which launch `codex exec`
+workers) is supported on native Windows in v0.3.0+: the server launches through
+`cmd.exe /d /s /c` so `codex.cmd` resolves correctly, and it sends large analyst prompts
+through stdin (`codex exec -`) instead of putting Chinese/multiline prompts on the command
+line. Timeout cleanup uses the normal Node process plus Windows process-tree termination.
+
+If headless still fails, check these first:
+
+- `node --version` is >= 18.
+- `codex --version` works in PowerShell or CMD.
+- Codex CLI is logged in for the same Windows user running Codex Desktop.
+- If `codex` is not on PATH, set `ALPHACOUNCIL_AGENT_CODEX_CMD` to the absolute path of
+  `codex.cmd`.
+
+Fallbacks:
+
+- Use **WSL** and run Codex + the plugin inside Linux if your native Codex CLI install is broken.
+- Use the **visible path** above when you do not want the MCP server to spawn `codex` at all.
+
+Everything else is cross-platform: data lives under `%USERPROFILE%\.alphacouncil-agent\`
+(via `os.homedir()`), paths use `path.join`, and the MCP wiring is plain `node`.
+
+---
+
+## 中文速览
+
+- 前置:Node ≥ 18;headless 真跑研究需要已登录的 Codex CLI(worker 是 `codex exec`)。Windows v0.3.0+ 原生支持 `codex.cmd`;WSL 只是 fallback。
+- Codex 安装:`codex plugin marketplace add Zhao73/alphacouncil-agent` → `/plugins` 安装 → `/reload-plugins`;或 clone 到 `~/.codex/plugins/` 走本地 marketplace。
+- Claude Code 安装:`/plugin marketplace add Zhao73/alphacouncil-agent` → `/plugin install alphacouncil-agent@alphacouncil` → `/reload-plugins`。
+- 没有 Codex CLI 时:用 visible 工作流,让 Claude 子代理产出证据并用 `record_visible_*` 录入,无需 codex。
+
+---
+
+## 日本語クイックガイド
+
+- 前提:Node ≥ 18。headless でリサーチを実走させるには、認証済みの Codex CLI が必要(worker は `codex exec`)。Windows は v0.3.0+ で `codex.cmd` をネイティブに起動可能。WSL は fallback。
+- Codex でのインストール:`codex plugin marketplace add Zhao73/alphacouncil-agent` → `/plugins` でインストール → `/reload-plugins`。または `~/.codex/plugins/` に clone してローカル marketplace 経由でも可。
+- Claude Code でのインストール:`/plugin marketplace add Zhao73/alphacouncil-agent` → `/plugin install alphacouncil-agent@alphacouncil` → `/reload-plugins`。
+- Codex CLI が無い場合:visible ワークフローを使用。Claude のサブエージェントに根拠を生成させ、`record_visible_*` で記録する(codex 不要)。

package/docs/personas.md

@@ -26,16 +26,16 @@ To add a role, add one file. It appears in the tool schema automatically.
 | `bear_researcher` | debate | yes | default | deep | Bear Researcher | short-case, rebuttal | original |
 | `portfolio_manager` | debate | yes | default | deep | Portfolio Manager | verdict, rating, synthesis | original |
 | `_master_base` | master | no | - | deep | Master seat preamble | shared | original |
-| `master_aschenbrenner` | master | yes | masters-modern | deep | Aschenbrenner Lens | scaling, compute, power, timeline-pricing | original |
+| `master_aschenbrenner` | master | yes | masters-modern, masters-core | deep | Aschenbrenner Lens | scaling, compute, power, timeline-pricing | original |
 | `master_buffett` | master | yes | masters-value, masters-core | deep | Buffett Lens | moat, owner-earnings, circle-of-competence | ai-berkshire (MIT) |
 | `master_graham` | master | yes | masters-value-classic, masters-core | deep | Graham Lens | margin-of-safety, balance-sheet, mr-market | original |
 | `master_simons` | master | yes | masters-quant, masters-core | deep | Simons Lens | signal-vs-noise, no-narrative, sample-size | original |
 | `master_soros` | master | yes | masters-adversarial, masters-core | deep | Soros Lens | reflexivity, boom-bust, test-the-thesis | original |
-| `master_druckenmiller` | master | yes | masters-adversarial | deep | Druckenmiller Lens | liquidity, concentration, eighteen-months-ahead | original |
-| `master_fisher` | master | yes | masters-value-classic | deep | Fisher Lens | scuttlebutt, growth-quality, r-and-d | original |
+| `master_druckenmiller` | master | yes | masters-adversarial, masters-core | deep | Druckenmiller Lens | liquidity, concentration, eighteen-months-ahead | original |
+| `master_fisher` | master | yes | masters-value-classic, masters-core | deep | Fisher Lens | scuttlebutt, growth-quality, r-and-d | original |
 | `master_munger` | master | yes | masters-value, masters-core | deep | Munger Lens | inversion, mental-models, failure-paths | ai-berkshire (MIT) |
 | `master_thorp` | master | yes | masters-quant, masters-core | deep | Thorp Lens | kelly-sizing, edge-and-odds, risk-of-ruin | original |
-| `master_asness` | master | yes | masters-quant | deep | Asness Factor Lens | factor-exposure, value-momentum-quality, is-it-just-beta | original |
+| `master_asness` | master | yes | masters-quant, masters-core | deep | Asness Factor Lens | factor-exposure, value-momentum-quality, is-it-just-beta | original |
 | `master_dalio` | master | yes | masters-adversarial, masters-core | deep | Dalio Lens | debt-cycle, machine-view, regime | original |
 | `master_duan_yongping` | master | yes | masters-value, masters-core | deep | Duan Yongping Lens | business-model, stop-doing-list, corporate-culture | ai-berkshire (MIT) |
 | `master_lynch` | master | yes | masters-value-classic, masters-core | deep | Peter Lynch Lens | category-first, peg, story-in-two-minutes | original |
@@ -43,7 +43,7 @@ To add a role, add one file. It appears in the tool schema automatically.
 | `master_marks` | master | yes | masters-value-classic, masters-core | deep | Howard Marks Lens | second-level-thinking, cycle-position, risk-is-permanent-loss | original |
 | `master_short_seller` | master | yes | masters-adversarial, masters-core | deep | Short Seller Lens | forensic-accounting, crowding, borrow | original |
 | `master_burry` | master | yes | masters-adversarial, masters-core | deep | Michael Burry Lens | primary-documents, contrarian, structural-short | original |
-| `master_klarman` | master | yes | masters-value-classic | deep | Klarman Lens | absolute-return, cash-as-option, bottom-up | original |
+| `master_klarman` | master | yes | masters-value-classic, masters-core | deep | Klarman Lens | absolute-return, cash-as-option, bottom-up | original |
 | `master_taleb` | master | yes | masters-options, masters-core | deep | Taleb Lens (Convexity and Tails) | tail-risk, convexity, options | original |
 | `master_natenberg` | master | yes | masters-options, masters-core | deep | Natenberg Lens (Volatility Pricing) | implied-volatility, options-pricing, market-making | original |
 | `master_sinclair` | master | yes | masters-options, masters-core | deep | Sinclair Lens (Volatility Trading and Execution) | volatility-forecasting, edge-measurement, position-sizing, options | original |

package/mcp/lib/rpc.mjs

@@ -582,16 +582,37 @@ export async function handleToolCall(id, params) {
   }
   if (name === "list_council_options") {
     const data = councilOptions({ language: args.language || "English" });
-    const rows = data.presets.map((p) => [
-      p.id, p.label, `${p.seats} seats`, `~${p.rough_minutes}m`, p.good_for,
+    const zh = /中文|chinese|zh/i.test(String(args.language || ""));
+    // Named seats, not three abstractions. A user choosing what to spend on should see who
+    // is in the room; "standard, 32 seats" hides both the composition and the omissions --
+    // it hid five masters that the preset never actually ran.
+    const analystRows = data.analysts.map((a) => [
+      a.id, a.title, a.in_default ? (zh ? "默认" : "default") : (zh ? "可选" : "optional"), a.covers || "-",
+    ]);
+    const masterRows = data.master_rosters.map((r) => [
+      r.roster, String(r.count), r.members.map((m) => m.id.replace("master_", "")).join(", "),
     ]);
     const text = [
-      table(["Preset", "What runs", "Seats", "Rough cost", "Good for"], rows, { title: "Choose a council" }),
+      table(
+        zh ? ["席位", "职责", "是否默认", "覆盖"] : ["Seat", "Role", "In default", "Covers"],
+        analystRows, { title: zh ? `分析师 — ${data.analysts.length} 位可选，默认 ${data.default_analysts.length} 位` : `Analysts — ${data.analysts.length} available, ${data.default_analysts.length} in the default fan-out`, zh },
+      ),
+      "",
+      table(
+        zh ? ["学派名册", "人数", "成员"] : ["School", "Count", "Members"],
+        masterRows, { title: zh ? `大师议席 — 共 ${data.all_masters_count} 位` : `Master bench — ${data.all_masters_count} lenses`, zh },
+      ),
       "",
-      `Master rosters: ${data.master_rosters.map((r) => `${r.roster} (${r.count})`).join(" · ")} — ${data.all_masters_count} lenses in total.`,
-      `Analysts: ${data.analysts.length} available, ${data.default_analysts.length} in the default fan-out.`,
+      table(
+        zh ? ["预设", "内容", "席位", "相对成本"] : ["Preset", "What runs", "Seats", "Relative cost"],
+        data.presets.map((p) => [p.id, p.label, `${p.seats}`, `~${p.rough_minutes}`]),
+        { title: zh ? "快捷预设（也可以自己点名）" : "Shortcuts — or name the seats yourself", zh },
+      ),
       "",
-      "Ask the user which they want before starting. Do not ask if they already said.",
+      zh
+        ? "把上面的名单给用户看，让他们**自己勾选**：可以按学派名册选、可以点名单个席位、也可以全选。预设只是快捷方式，不是唯一选项。用户已经说清楚要什么就别问。"
+        : "Show the user these lists and let them **pick**: by school, by individual seat, or all of them. "
+          + "The presets are shortcuts, not the only way to choose. Do not ask if they already said.",
     ].join("\n");
     sendResult(id, jsonContent(text, data));
     return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "alphacouncil-agent",
-  "version": "0.5.3",
+  "version": "0.5.5",
   "description": "Multi-agent public-equity research workflow plugin for Codex & Claude Code: sourced evidence packets, bull/bear debate, and a portfolio-manager Buy/Overweight/Hold/Underweight/Sell decision.",
   "type": "module",
   "license": "MIT",
@@ -60,6 +60,9 @@
     "commands/",
     ".claude/commands/",
     ".opencode/command/",
-    ".grok/commands/"
+    ".grok/commands/",
+    "docs/INSTALL.md",
+    "SECURITY.md",
+    "CONTRIBUTING.md"
   ]
 }

package/personas/masters/masters-adversarial/druckenmiller.md

@@ -6,7 +6,8 @@
   "order": 20,
   "enabled": true,
   "rosters": [
-    "masters-adversarial"
+    "masters-adversarial",
+    "masters-core"
   ],
   "title": {
     "zh": "德鲁肯米勒视角",

package/personas/masters/masters-modern/aschenbrenner.md

@@ -6,7 +6,8 @@
   "order": 10,
   "enabled": true,
   "rosters": [
-    "masters-modern"
+    "masters-modern",
+    "masters-core"
   ],
   "title": {
     "zh": "Aschenbrenner 视角",

package/personas/masters/masters-quant/asness.md

@@ -6,7 +6,8 @@
   "order": 30,
   "enabled": true,
   "rosters": [
-    "masters-quant"
+    "masters-quant",
+    "masters-core"
   ],
   "title": {
     "zh": "Asness 因子视角",

package/personas/masters/masters-value-classic/fisher.md

@@ -6,7 +6,8 @@
   "order": 20,
   "enabled": true,
   "rosters": [
-    "masters-value-classic"
+    "masters-value-classic",
+    "masters-core"
   ],
   "title": {
     "zh": "费雪视角",

package/personas/masters/masters-value-classic/klarman.md

@@ -6,7 +6,8 @@
   "order": 50,
   "enabled": true,
   "rosters": [
-    "masters-value-classic"
+    "masters-value-classic",
+    "masters-core"
   ],
   "title": {
     "zh": "克拉曼视角",

package/skills/alphacouncil-agent/SKILL.md

@@ -30,32 +30,36 @@ Do not ask startup option questions by default. For underspecified requests such
 
 Ask only when the user explicitly requests option selection before launch. Use the inferred language for visible main-thread preflight/progress updates, visible agent prompts, evidence packets, debate packets, and final synthesis unless the user explicitly requests another language. Always pass the original user request in `prompt`, and pass the inferred language as `language` to AlphaCouncil Agent MCP tools.
 
-## Stage 0 — Ask which council to run (every host)
+## Stage 0 — Ask which masters, then run
 
-**Before planning a run, call `list_council_options` and let the user choose.**
+**One question, about the master bench only. Then start.**
 
-A council is anywhere from 7 to 44 seats. That range is the user's time and money, and
-choosing silently is wrong in both directions: pick small and the bench they were promised
-never runs, pick everything and a one-line question costs a full fan-out.
+The analysts have a sensible default -- the eight-seat fan-out -- and asking about them every
+time is a question with an obvious answer. The bench is the part a user actually has a view
+on, and it is where the cost varies most: 21 lenses or 4 is a real difference.
 
-Present the three presets with their seat counts and relative cost, and say that they can
-instead name individual analysts and a master roster. Then wait for the answer.
+1. Call `list_council_options`.
+2. Ask **once**: which master schools? Offer the six by name with their members, plus "all"
+   and "none".
+   - **Claude Code** — `AskUserQuestion` with `multiSelect: true`, one option per school,
+     each naming its members.
+   - **Codex, OpenCode, Grok Build** — print the school table and take a plain reply.
 
-**Do not ask when they have already told you.** A user who named a roster, said "run
-everything", said "just be quick", or is repeating a run with the same shape has answered;
-asking again is an interruption, not diligence.
+   Naming each host is not redundancy. Leaving it implicit is exactly how the master bench
+   ended up never running on Codex and OpenCode: the instruction existed, in a section only
+   one host read.
+3. **Then run.** Do not ask about analysts, presets, or confirmation. The answer to "which
+   masters" is the whole configuration decision.
 
-How to ask, per host:
+Analysts default to the eight-seat fan-out. Use all eleven only if the user asked for
+breadth, and say so in the report rather than asking first.
 
-- **Claude Code** — use `AskUserQuestion` with the presets as options.
-- **Codex, OpenCode, Grok Build** — ask in chat as a short numbered list and wait for a reply.
+**Skip the question entirely when the request already answered it** — a named school,
+"everything", "no masters", "be quick", or a repeat of a run with the same shape. A
+confirmation nobody needed is an interruption.
 
-Two things to say plainly when you ask:
-
-- The estimates are relative magnitudes, not promises. "Roughly three times the seats" is
-  honest; "about 33 minutes" is not.
-- If they choose everything, say once that it will be noticeably slower — then run it. They
-  are allowed to spend their own time; they are not required to guess what it costs.
+Say the cost once, in the same message as the question: each master is one subagent, so the
+bench is the difference between roughly 11 seats and roughly 32. Do not quote minutes.
 
 ## Visible-First Workflow