alphacouncil-agent 0.5.0

package/README.ja.md

@@ -0,0 +1,282 @@
+<a name="readme-top"></a>
+
+<div align="center">
+
+<img src="assets/banner.png" alt="AlphaCouncil Agent" width="100%" />
+
+### ターミナルの中の、マルチエージェント投資委員会
+
+アナリスト評議会を招集 → 出典付きの根拠を収集 → 強気/弱気ディベート → PM が判定:**買い · オーバーウェイト · 中立 · アンダーウェイト · 売り**
+
+[English](README.md) · [中文](README.zh-CN.md) · **日本語**
+
+<p>
+  <img src="https://img.shields.io/github/actions/workflow/status/Zhao73/alphacouncil-agent/check.yml?style=for-the-badge&label=build&logo=githubactions&logoColor=white&color=1a7a6a" alt="build" />
+  <img src="https://img.shields.io/badge/License-MIT-c9a227?style=for-the-badge" alt="MIT" />
+  <img src="https://img.shields.io/badge/Node-%3E%3D18-339933?style=for-the-badge&logo=node.js&logoColor=white" alt="node" />
+  <img src="https://img.shields.io/github/stars/Zhao73/alphacouncil-agent?style=for-the-badge&logo=github&color=0d4d4d" alt="stars" />
+</p>
+<p>
+  <img src="https://img.shields.io/badge/OpenAI_Codex-412991?style=for-the-badge&logo=openai&logoColor=white" alt="codex" />
+  <img src="https://img.shields.io/badge/Claude_Code-D97757?style=for-the-badge&logo=anthropic&logoColor=white" alt="claude code" />
+  <img src="https://img.shields.io/badge/MCP-compatible-000000?style=for-the-badge" alt="mcp" />
+</p>
+
+<p>
+  <a href="#-使い方"><b>使い方</b></a> ·
+  <a href="docs/INSTALL.md"><b>インストール</b></a> ·
+  <a href="#-アーキテクチャ"><b>アーキテクチャ</b></a> ·
+  <a href="#-免責事項"><b>免責事項</b></a>
+</p>
+
+</div>
+
+---
+
+<div align="center">
+
+<img src="assets/run-example.png" alt="A real AlphaCouncil run: six master lenses reaching the same call for different reasons" width="100%" />
+
+<sub><i>実際の実行結果。6つのレンズはいずれも強気ではなく、相違は結論ではなく理由にあります。</i></sub>
+
+</div>
+
+AlphaCouncil Agent は、**上場株式のリサーチ**向けの Codex / Claude Code プラグインです。複数のアナリスト・サブエージェントを統括し、出典付きの根拠を集め、強気/弱気のディベートを行い、ポートフォリオマネージャー視点の最終レポートを生成します。
+
+### ✨ AlphaCouncil を使う理由
+
+| | |
+|---|---|
+| 🏛️ **一人の意見ではなく、委員会** | 11 の専門アナリストエージェント(株価・決算・バリュエーション・クオンツ・インサイダー/SEC・IB イベント…)が並列で稼働。 |
+| 🐂🐻 **設計からして対立的** | 構造化された強気 vs 弱気のディベートを、PM エージェントが裁定し実際のレーティングを提示。 |
+| 🔍 **監査可能、幻覚なし** | すべての主張が source ID に紐づく。欠落データは「データ欠落」セクションに明示し、決して隠さない。 |
+| ⏱️ **マルチ期間の判定** | 買い/中立/売りに加え、1〜4週・3〜6か月・12か月の見通しを個別に提示。 |
+| 🔑 **データベンダー不要・APIキー不要** | 金融データ API・マーケットデータフィード・証券口座ログインは一切不要。アナリストはエージェント自身のウェブ検索(**Codex のウェブ検索** / **Claude Code の WebSearch + WebFetch**)で根拠をリアルタイムに収集 —— 課金は既存の Codex / Claude Code サブスクのみ。MIT ライセンス。 |
+| 📚 **同梱の調査プレイブック** | 公開株式投資と投資銀行イベント分析の方法論を**ローカルスキル**として同梱(`skills/public-equity-investing`、`skills/investment-banking`)—— Codex 専用のリモートワークフローに依存せず、Claude Code でも同等の調査深度。 |
+| 📈 **実マーケットデータ・キー不要** | 内蔵の `get_quote` が Yahoo + Stooq 経由で指数・指数先物(夜間含む)・FX・金利・ボラ・商品・個別株の遅延(~15分)データを取得 —— API キー不要、アナリストは推測ではなく実数を引用。 |
+
+このリポジトリはアップロード用のソースコピーです。実行成果物はリポジトリの外、`~/.alphacouncil-agent/runs/<run_id>/` に書き出されます。
+
+## 📜 免責事項
+
+本ソフトウェアは**教育・研究目的のみ**を対象としており、**投資助言ではありません**。いかなる証券の売買の推奨・勧誘でもありません。AI が生成する分析は不完全・古い・誤っている可能性があります。投資判断の前に、必ずご自身で調査し、有資格の専門家にご相談ください。作者はいかなる損失についても責任を負いません。
+
+## インストール
+
+Codex と Claude Code の完全なセットアップ手順は **[docs/INSTALL.md](docs/INSTALL.md)** を参照してください。**Windows ユーザー**は [Windows セクション](docs/INSTALL.md#windows) を参照。
+
+**前提条件:** Node.js ≥ 18。headless でリサーチを実走させるには、**インストール済みかつ認証済みの Codex CLI** も必要です(各アナリスト worker は `codex exec` として起動します)。Codex が無い場合は、インストールガイドの **visible ワークフロー**を使ってください。
+
+```text
+# Codex
+codex plugin marketplace add Zhao73/alphacouncil-agent
+# その後 codex → /plugins でインストール → /reload-plugins
+
+# Claude Code
+/plugin marketplace add Zhao73/alphacouncil-agent
+/plugin install alphacouncil-agent@alphacouncil
+/reload-plugins
+```
+
+## 🚀 使い方
+
+エージェントにそのまま話しかけるだけ。@ でエージェントを呼び、ティッカーや質問を添えます:
+
+```text
+@alphacouncil-agent 7203.T をロング/ショートのピッチとして分析して
+@alphacouncil-agent 現在の水準で AAPL は買い?
+@alphacouncil-agent 12か月の視点で TSLA と RIVN を比較して
+@alphacouncil-agent トヨタ(7203)を分析して
+@alphacouncil-agent 帮我看看 700.HK 现在能不能买
+```
+
+チャット上でそのまま読める 1 本のレポートが返ってきます:
+
+```text
+判定:オーバーウェイト  (確信度:中)
+├─ アナリスト作業ログ .... 11 の根拠エージェント、出典付き主張 38 件
+├─ 強気シナリオ .......... 需要の転換点、マージン拡大、自社株買い
+├─ 弱気シナリオ .......... バリュエーション、顧客集中、サイクルリスク
+├─ 短期 / 中期 / 長期 .... 1〜4週 · 3〜6か月 · 12か月の見通し
+├─ カタリストとリスク .... 決算、ガイダンス、規制
+├─ データの欠落 .......... 明示的に列挙し、決して隠さない
+└─ 出典テーブル .......... すべての主張を <task>:<source_id> に対応付け
+```
+
+簡潔なユーザー向け要約は `~/.alphacouncil-agent/runs/<run_id>/user_response.md` に書き出されます。
+完全なレポートは `~/.alphacouncil-agent/runs/<run_id>/final_report.md` に書き出され、
+同じディレクトリに各アナリストの Markdown ファイルと `artifact_index.md` も保存されます。
+
+## 何ができるか
+
+既定はフル実行であり、簡易サマリーではありません：
+
+- 株価と値動き
+- 決算の深掘り（決算説明会を含む）
+- 将来予想、織り込まれた上振れ/下振れ閾値、セルサイドの格付・目標株価改定
+- クオンツファクター：モメンタム、トレンド、ボラティリティ、流動性、相対強度、混雑度
+- バリュエーションとロング/ショート論点（単一目標株価ではなく価格レンジ）
+- ニュース、業界動向、サプライチェーン、経営陣の発言と行動の照合
+- SEC提出書類、Form 4 インサイダー取引、自社株買い、希薄化、負債と資本配分
+- M&A、エクイティ/デット・ファイナンス、自社株買いなどのイベント分析
+- 21名の投資家レンズが同じ事実を**独立に**読む
+- ブル、ベア、ポートフォリオマネージャーの裁定
+
+最終レポートはチャット上でそのまま読めます。アナリスト作業記録、データと提出書類の要約、ブル/ベア討論、PM裁定、エントリー価格帯、短中長期の見方、データギャップ、確信度、出典表を含みます。
+
+## 🔧 ツール —— 27個、すべてキー不要
+
+以下のいずれもAPIキー、アカウント、設定ファイルを必要としません。
+
+| 領域 | ツール | データソース |
+|---|---|---|
+| **提出書類** | `screen_ticker` `screen_candidates` `list_us_universe` `compose_research_brief` | SEC EDGAR XBRL |
+| **米国外** | `market_financials` `market_coverage` | 台湾証取はキー不要／DART・EDINETは無料キー／香港・中国は文書のみ |
+| **市場データ** | `get_quote` `get_macro_snapshot` | Yahoo / Stooq、マクロ21系列＋派生5指標 |
+| **オプション** | `get_options_chain` | CBOE遅延気配 —— IVターム構造、25Δスキュー、建玉、グリークス |
+| **ニュース** | `get_news` `get_market_narrative` | Yahoo、Google News、SEC Atom、FRB、WSJ、CNBC |
+| **ソーシャル** | `get_social_pulse` `verify_x_post` | Reddit、Hacker News、Bluesky |
+| **業界** | `industry_brief` `industry_peers` `industry_coverage` `list_industries` | 全米国登録企業のSIC分類＋厳選バリューチェーン地図 |
+| **ワークフロー** | `analyze_symbol` `plan_visible_run` `collect_evidence` `read_run` ほか9個 | — |
+
+**あえて行わないこと。** 以下はすべてツールの出力自体に明記されています。下流で引用されるのはペイロードだからです：
+
+- **IVパーセンタイルは算出不能。** オプションチェーンは履歴のないスナップショットであり、「自身の過去と比べて高い/低い」という主張はすべて未解決事項として報告されます。
+- **X / Twitter に無料の探索経路は存在しません**（2026年7月時点）。Nitter検索は機能停止、X APIは投稿単位課金、xAIは呼び出し単位課金。**プロのFinTwit層は対象外であり、Redditはその代替にはなりません。**
+- **入力が欠けたスクリーニング規則は `skipped` であり、決して合格扱いにしません。**
+- **解析可能なタイムスタンプを持たないニュースは除外**され、「最新」として表示されません。
+- **`iv = 0` の建玉は除外。** CBOEは満期到来済みやディープITMで0を返しますが、0が平均に混入すると欠損値ではなく「落ち着いた銘柄」に見えてしまいます。
+
+## 🏛️ マスター陣 —— 21のレンズ
+
+公開された方法論の再構成であり、**本人の発言では一切ありません**。各レンズは自らの思考順序、最初に見るもの、典型的な問いかけ、そして**自身の失敗モード**を明示します —— 自分がどう間違うか言えない席は、間違ったときに手を挙げません。
+
+| 名簿 | レンズ |
+|---|---|
+| バリュー | バフェット · マンガー · 段永平 · 李録 |
+| 古典バリュー | グレアム · フィッシャー · リンチ · マークス · クラーマン |
+| 対抗 | ソロス · ドラッケンミラー · ダリオ · バーリ · ショートセラー |
+| クオンツ | サイモンズ · アスネス · ソープ |
+| オプション | タレブ · ナタンバーグ · シンクレア |
+| 現代 | アッシェンブレナー |
+
+マスターはアナリストと**同じ確定事実**（提出書類、株価、財務、マクロ）を読みます。アナリストのパケットは別途、「事実ではなく他席の解釈」として明示のうえ渡されます。この分離こそが要点です：アナリストが粗利率を見た箇所でマンガーはインセンティブ構造を見る —— それぞれが独自に取捨選択してこそ、この陣容に意味があります。詳細は [docs/attribution.md](docs/attribution.md)。
+
+## 🧩 アーキテクチャ
+
+```mermaid
+flowchart TD
+    U["@alphacouncil-agent"] --> G[("Established facts<br/>filings · quotes · macro · options")]
+    G --> AG{{"Analyst council"}}
+    G --> MS{{"Master bench<br/>21 lenses"}}
+    AG --> A1["Market data"]
+    AG --> A2["Earnings"]
+    AG --> A3["Valuation"]
+    AG --> A4["Quant factors"]
+    AG --> A5["Insider / SEC"]
+    AG --> A6["News / narrative"]
+    A1 --> EV[("Evidence base")]
+    A2 --> EV
+    A3 --> EV
+    A4 --> EV
+    A5 --> EV
+    A6 --> EV
+    EV -.->|"interpretation,<br/>not fact"| MS
+    EV --> VF{{"Verifiers"}}
+    VF -->|"failed checks<br/>down-weight the seat"| PM
+    MS --> BULL["Bull"]
+    MS --> BEAR["Bear"]
+    EV --> BULL
+    EV --> BEAR
+    BULL --> PM{{"Portfolio manager"}}
+    BEAR --> PM
+    PM --> R[["final_report.md"]]
+```
+
+マスターは事実から分岐し、アナリストのパケットからは分岐しません。21のレンズに一人のアナリストの取捨選択を与えれば、全員が同じ盲点を共有します —— 大きく、かつ完全に相関した誤差であり、陣容を持つ理由そのものが失われます。
+
+主要ファイル:
+
+- `.codex-plugin/plugin.json` —— Codex プラグインのメタデータ
+- `.claude-plugin/plugin.json` —— Claude Code プラグインのマニフェスト
+- `.mcp.json` —— MCP server の配線
+- `skills/alphacouncil-agent/SKILL.md` —— 実行時の指示
+- `mcp/server.mjs` —— JSON-RPC MCP server とワークフロー実装
+- `scripts/selfcheck.mjs` —— 最小限の回帰セルフチェック
+
+## 🆚 Codex 版 vs Claude Code 版
+
+両版はワークフロー、JSON パケット契約、監査用成果物、API キー不要のライブ Web 取証モデル、免責事項を共有します。Claude Code 版は委員会の「**動かし方**」だけを変えます。
+
+| | Codex 版 | Claude Code 版 |
+|---|---|---|
+| 委員会の実行 | `codex exec` ワーカー、同時実行に上限 | 11 アナリストを並列 `Task` サブエージェントとして一括起動 |
+| アナリストごとの文脈 | 別プロセス | 別サブエージェント、それぞれ独立した完全な文脈ウィンドウ |
+| 取証 | `codex exec --search` | 各アナリスト自身の文脈で `WebSearch` + `WebFetch` |
+| 根拠 → ディベート | 逐次 | 実行フェーズマシンによるハードバリア |
+| ディベートの深さ | 3 ラウンド(主張/反論/Q&A)、server 実行 | 3 ラウンド、各ラウンドで強気・弱気を並列 |
+| 主張の検証 | 欠落ソースゲート(実行にフラグ + レポートにバナー) | + 主張ごとの敵対的検証:引用 URL の再取得・再導出・反証 *(ホスト駆動)* |
+| 完全実行の強制 | 不完全な実行を `incomplete` とマーク(server ゲート) | 同ゲート + ディベート前のハードバリア |
+| モデルとコスト | 単一モデル | **役割ごとに選択** — 取証は Sonnet、ディベート/判定は Opus 4.8(全 Opus / 全 Sonnet も可) |
+| 言語 | ユーザーの言語 | 全サブエージェント + ライブ workflow を通じてユーザーの言語 |
+
+**正直なスコープ:** 同じモデルファミリー・同じプロンプト・同じ監査契約 —— 強みは文脈の分離、常時並列ファンアウト、決定的ゲートであり、より賢いモデルではありません。**v0.3.0** 以降、共有 server は 3 ラウンドのディベート、「欠落ソース / 完全実行 / レポート品質」のゲート、簡潔な引き渡し要約、完全レポート、ファイル索引、Windows ネイティブ Codex CLI 起動を提供します。**v0.3.1** 以降、`addyosmani/agent-skills` スタイルの停止ゲートと完了基準を持つ `agent-skills-governance` skill も同梱します。Claude Code 版はさらにラウンドごとの並列実行とホスト駆動の主張ごと検証を追加します。ライブ Web の鮮度とペイウォールは両版に等しく当てはまります。
+
+## データ契約
+
+根拠サブエージェントは JSON パケットを返します:
+
+```json
+{
+  "task": "market_data",
+  "symbol": "7203.T",
+  "as_of": "YYYY-MM-DD",
+  "summary": "string",
+  "claims": [
+    { "claim": "string", "evidence": "string", "confidence": "high|medium|low", "source_ids": ["market_data:S1"] }
+  ],
+  "metrics": {},
+  "sources": [
+    { "id": "market_data:S1", "title": "string", "url": "https://example.com", "published_at": "YYYY-MM-DD or unknown", "retrieved_at": "YYYY-MM-DD" }
+  ],
+  "open_questions": ["missing data item"],
+  "confidence": "high|medium|low"
+}
+```
+
+すべての source ID は `<task>:<source_id>` のグローバルスコープです。欠落データは `open_questions` に記載し、最終レポートのデータ欠落セクションにも反映する必要があります。
+
+## ローカル実行
+
+```bash
+npm run check
+```
+
+セルフチェックの検証内容:MCP server の構文、ツール schema の公開、source ID のスコープ、デフォルトの実走挙動、可視ランの記録、`events.jsonl`/`status.json`/`all_agents.md`/`source_manifest.json`、`final_report.md`/`user_response.md`/`artifact_index.md`/`report_quality.json`、アナリスト Markdown ファイル、および最終レポートの必須セクション。
+
+## 備考
+
+これは独立したプラグイン実装で、マルチエージェントの投資委員会ワークフロー(アナリストチーム、根拠の共有、強気/弱気ディベート、ポートフォリオマネージャーによる統合)を採用しています。
+
+API キー、証券口座の認証情報、非公開書類、生成された実行成果物は決してコミットしないでください。
+
+## ⭐ Star 推移
+
+<div align="center">
+
+<a href="https://star-history.com/#Zhao73/alphacouncil-agent&Date">
+  <img src="https://api.star-history.com/svg?repos=Zhao73/alphacouncil-agent&type=Date" width="640" alt="Star History Chart" />
+</a>
+
+<br/><br/>
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="assets/logo-dark.png" />
+  <img src="assets/logo.png" alt="AlphaCouncil" width="120" />
+</picture>
+
+AlphaCouncil が役に立ったら、⭐ をいただけると励みになります。
+
+<a href="#readme-top">↑ トップに戻る</a>
+
+</div>

package/README.md

@@ -0,0 +1,361 @@
+<a name="readme-top"></a>
+
+<div align="center">
+
+<img src="assets/banner.png" alt="AlphaCouncil Agent" width="100%" />
+
+<p>
+  <img src="https://readme-typing-svg.demolab.com?font=Fira+Code&size=20&duration=2800&pause=700&color=1A7A6A&center=true&vCenter=true&width=620&lines=Spawn+a+council+of+analyst+agents;Gather+sourced+evidence%2C+hide+nothing;Run+a+bull+vs+bear+debate;Get+a+PM+verdict%3A+Buy+%C2%B7+Hold+%C2%B7+Sell" alt="tagline" />
+</p>
+
+**English** · [中文](README.zh-CN.md) · [日本語](README.ja.md)
+
+<p>
+  <img src="https://img.shields.io/github/actions/workflow/status/Zhao73/alphacouncil-agent/check.yml?style=for-the-badge&label=build&logo=githubactions&logoColor=white&color=1a7a6a" alt="build" />
+  <img src="https://img.shields.io/badge/License-MIT-c9a227?style=for-the-badge" alt="MIT" />
+  <img src="https://img.shields.io/badge/Node-%3E%3D18-339933?style=for-the-badge&logo=node.js&logoColor=white" alt="node" />
+  <img src="https://img.shields.io/github/stars/Zhao73/alphacouncil-agent?style=for-the-badge&logo=github&color=0d4d4d" alt="stars" />
+</p>
+<p>
+  <img src="https://img.shields.io/badge/OpenAI_Codex-412991?style=for-the-badge&logo=openai&logoColor=white" alt="codex" />
+  <img src="https://img.shields.io/badge/Claude_Code-D97757?style=for-the-badge&logo=anthropic&logoColor=white" alt="claude code" />
+  <img src="https://img.shields.io/badge/OpenCode-1a7a6a?style=for-the-badge&logoColor=white" alt="opencode" />
+  <img src="https://img.shields.io/badge/Grok_Build-000000?style=for-the-badge&logo=x&logoColor=white" alt="grok build" />
+</p>
+<p>
+  <img src="https://img.shields.io/badge/MCP-compatible-000000?style=for-the-badge" alt="mcp" />
+  <img src="https://img.shields.io/badge/API_keys-none_required-2ea043?style=for-the-badge" alt="no api keys" />
+  <img src="https://img.shields.io/badge/dependencies-zero-2ea043?style=for-the-badge" alt="zero dependencies" />
+</p>
+
+<p>
+  <a href="docs/INSTALL.md"><b>Install</b></a> ·
+  <a href="#-usage"><b>Usage</b></a> ·
+  <a href="#-tools--27-all-keyless"><b>Tools</b></a> ·
+  <a href="#-the-bench--21-investor-lenses"><b>The bench</b></a> ·
+  <a href="#-architecture"><b>Architecture</b></a> ·
+  <a href="CHANGELOG.md"><b>Changelog</b></a> ·
+  <a href="#-disclaimer"><b>Disclaimer</b></a>
+</p>
+
+</div>
+
+---
+
+<div align="center">
+
+<img src="assets/run-example.png" alt="A real AlphaCouncil run: six master lenses reaching the same call for different reasons" width="100%" />
+
+<sub><i>A real run. Six lenses, none constructive — and the disagreement is in the reasons, not the call.</i></sub>
+
+</div>
+
+AlphaCouncil Agent is a Codex and Claude Code plugin for full public-equity research workflows. It coordinates multiple analyst agents, gathers sourced evidence, runs bull/bear debate, and produces a portfolio-manager style final report.
+
+### ✨ Why AlphaCouncil
+
+| | |
+|---|---|
+| 🏛️ **A council, not one opinion** | Eight specialist analysts by default, eleven available — market data, earnings, forward expectations, quant, valuation, news and supply chain, insider/SEC, IB events, macro, narrative, crowding. |
+| 🎭 **21 investor lenses that disagree** | Buffett, Munger, Graham, Lynch, Marks, Klarman, Soros, Dalio, Burry, Simons, Thorp, Taleb and more read the **same facts** and reach different conclusions. Each names its own failure mode, because a seat that cannot say how it goes wrong will not flag it when it does. |
+| 🐂🐻 **Adversarial by design** | A structured bull vs bear debate, refereed by a portfolio manager who issues an actual rating — and three verifiers that re-source, re-derive and attack every load-bearing claim. A failed check **down-weights the seat that made it**. |
+| 🔍 **Auditable, never hallucinated** | Every claim maps to a source ID. A screen rule with missing inputs is `skipped`, never a pass. An undated headline is excluded, not shown as recent. Gaps are a section, not an omission. |
+| 💰 **Entry price bands, not one number** | Three conditional bands with what each depends on. "The cycle position is undetermined" changes what the bands are conditional on; it does not excuse leaving them out. |
+| 🔑 **27 tools, zero API keys, zero dependencies** | SEC EDGAR, CBOE options, Yahoo/Stooq quotes, 21 macro series, news and social — all keyless. `node mcp/server.mjs` and nothing else. |
+| 🖥️ **One council on four hosts** | Claude Code, Codex, OpenCode and Grok Build run the **same** workflow, the same bench and the same gates. |
+
+This repository is the uploadable source copy. Runtime outputs are written outside the repo under `~/.alphacouncil-agent/runs/<run_id>/`.
+
+## 📜 Disclaimer
+
+This software is for **educational and research purposes only**. It is **not
+investment advice**, not a recommendation to buy or sell any security, and not a
+solicitation. AI-generated analysis can be incomplete, outdated, or wrong. Do
+your own research and consult a licensed financial professional before making any
+investment decision. The authors accept no liability for any loss.
+
+## Install
+
+See **[docs/INSTALL.md](docs/INSTALL.md)** for full Codex and Claude Code setup. **Windows users:** see the [Windows section](docs/INSTALL.md#windows).
+
+**Prerequisites:** Node.js >= 18. The headless research path also needs an
+installed, authenticated **Codex CLI** (each analyst worker runs as `codex
+exec`). On Windows, v0.3.0+ launches the CLI through `cmd.exe` and feeds prompts
+over stdin so native `codex.cmd` installs work without WSL in the normal case.
+
+```text
+# Codex
+codex plugin marketplace add Zhao73/alphacouncil-agent
+# then run `codex`, open /plugins, install, and /reload-plugins
+
+# Claude Code
+/plugin marketplace add Zhao73/alphacouncil-agent
+/plugin install alphacouncil-agent@alphacouncil
+/reload-plugins
+```
+
+## 🚀 Usage
+
+Just talk to it. Mention the agent and a ticker or a question:
+
+```text
+@alphacouncil-agent analyze AAPL as a long/short pitch
+@alphacouncil-agent is AAPL a buy at current levels?
+@alphacouncil-agent compare TSLA vs RIVN for a 12-month horizon
+@alphacouncil-agent 帮我看看 700.HK 现在能不能买
+@alphacouncil-agent トヨタ(7203)を分析して
+```
+
+You get back a single, chat-readable report:
+
+```text
+VERDICT: Overweight  (confidence: medium)
+├─ Analyst work log ........ 11 evidence agents, 38 sourced claims
+├─ Bull thesis ............. demand inflection, margin expansion, buyback
+├─ Bear thesis ............. valuation, customer concentration, cycle risk
+├─ Short / medium / long ... 1-4wk · 3-6mo · 12mo views
+├─ Catalysts & risks ....... earnings, guidance, regulatory
+├─ Data gaps ............... explicitly listed, never hidden
+└─ Source table ............ every claim mapped to <task>:<source_id>
+```
+
+The concise handoff is written to `~/.alphacouncil-agent/runs/<run_id>/user_response.md`.
+The full report is written to `~/.alphacouncil-agent/runs/<run_id>/final_report.md`,
+with analyst Markdown files and `artifact_index.md` in the same run directory.
+
+## What It Does
+
+Default stock-analysis runs are full runs, not lite summaries:
+
+- Market data and price action
+- Earnings deep dive, including the earnings call
+- Forward expectations, implied beat/miss thresholds, and sell-side target revisions
+- Quant factor view: momentum, trend, volatility, liquidity, relative strength, crowding
+- Valuation and long/short pitch, with price bands rather than a single target
+- News, industry context, supply chain, and management's words checked against their actions
+- SEC filings, Form 4 insider transactions, buybacks, dilution, debt and capital allocation
+- Investment-banking event analysis for M&A, ECM, debt, buybacks and strategic transactions
+- A bench of 21 investor lenses reading the same facts independently
+- Bull researcher, bear researcher and portfolio-manager synthesis
+
+The final report is readable directly in chat. It carries analyst work logs, data and filing
+summaries, the bull/bear debate, the PM verdict, entry price bands, short/medium/long-term
+views, data gaps, confidence and a source table.
+
+## 🔧 Tools — 27, all keyless
+
+Nothing below needs an API key, an account, or a config file. Install and run.
+
+| Area | Tools | Source |
+|---|---|---|
+| **Filings** | `screen_ticker` `screen_candidates` `list_us_universe` `compose_research_brief` | SEC EDGAR XBRL |
+| **Non-US filings** | `market_financials` `market_coverage` | TWSE keyless; DART/EDINET on a free key; HK/CN documents only |
+| **Market data** | `get_quote` `get_macro_snapshot` | Yahoo / Stooq, 21 macro series + 5 derived |
+| **Options** | `get_options_chain` | CBOE delayed quotes — IV term structure, 25-delta skew, open interest, Greeks |
+| **News** | `get_news` `get_market_narrative` | Yahoo, Google News, SEC Atom, Fed, WSJ, CNBC |
+| **Social** | `get_social_pulse` `verify_x_post` | Reddit, Hacker News, Bluesky |
+| **Industry** | `industry_brief` `industry_peers` `industry_coverage` `list_industries` | SIC across all US filers + curated maps |
+| **Workflow** | `analyze_symbol` `plan_visible_run` `collect_evidence` `read_run` and 5 more | — |
+
+**What it deliberately will not do.** Every one of these is stated in the tool output itself,
+not only in the docs, because the payload is what gets quoted downstream:
+
+- **IV percentile is not computable.** The chain is a snapshot with no history, so any claim
+  that volatility is high or low against its own past is reported as an open question.
+- **X / Twitter has no free discovery channel** as of 2026-07. Nitter search is dead, the X
+  API bills per post and xAI bills per call. Professional FinTwit is **not** covered, and
+  Reddit is not a substitute for it.
+- **A screen rule whose inputs are missing is `skipped`, never a pass.**
+- **A news item with no parsable timestamp is excluded**, not shown as recent.
+- **A contract reporting `iv = 0`** — CBOE does this for expired and deep-in-the-money
+  contracts — is dropped rather than averaged in, because a zero does not look like a gap,
+  it looks like a calm stock.
+
+## 🏛️ The bench — 21 investor lenses
+
+Reconstructions of publicly documented methods, not anything the named people said. Each
+states how it thinks, what it notices first, its characteristic challenge, and **its own
+failure mode** — a seat that cannot name how it goes wrong will not flag it when it does.
+
+| Roster | Lenses |
+|---|---|
+| Value | Buffett · Munger · Duan Yongping · Li Lu |
+| Classic value | Graham · Fisher · Lynch · Marks · Klarman |
+| Adversarial | Soros · Druckenmiller · Dalio · Burry · short seller |
+| Quant | Simons · Asness · Thorp |
+| Options | Taleb · Natenberg · Sinclair |
+| Modern | Aschenbrenner |
+
+Masters read the **same established facts** the analysts read — filings, quotes, financials,
+macro — and receive the analyst packets separately, labelled as other seats' readings rather
+than as fact. That separation is the point: the bench is worth having only because Munger
+looks at incentives where an analyst looked at margins. See [docs/attribution.md](docs/attribution.md).
+
+## 🧩 Architecture
+
+```mermaid
+flowchart TD
+    U["@alphacouncil-agent<br/>ticker / question"] --> G[("Established facts<br/>filings · quotes · macro · options")]
+    G --> AG{{"Analyst council"}}
+    G --> MS{{"Master bench<br/>21 lenses"}}
+    AG --> A1["📈 Market data"]
+    AG --> A2["💰 Earnings"]
+    AG --> A3["⚖️ Valuation"]
+    AG --> A4["🧮 Quant factors"]
+    AG --> A5["🏛️ Insider / SEC"]
+    AG --> A6["📰 News / narrative"]
+    A1 --> EV[("Evidence base<br/>sourced packets")]
+    A2 --> EV
+    A3 --> EV
+    A4 --> EV
+    A5 --> EV
+    A6 --> EV
+    EV -.->|"read as interpretation,<br/>not as fact"| MS
+    EV --> VF{{"Verifiers<br/>fidelity · re-derive · refute"}}
+    VF -->|"failed checks<br/>down-weight the seat"| PM
+    MS --> BULL["🐂 Bull"]
+    MS --> BEAR["🐻 Bear"]
+    EV --> BULL
+    EV --> BEAR
+    BULL --> PM{{"Portfolio manager"}}
+    BEAR --> PM
+    PM --> R[["final_report.md<br/>verdict + entry price bands"]]
+```
+
+The masters branch off the facts, not off the packets. Feeding 21 lenses one analyst's
+selection of what mattered would give them all the same blind spot — a large and perfectly
+correlated error — and would remove the reason for having a bench at all.
+
+Key files:
+
+- `.codex-plugin/plugin.json` - Codex plugin metadata.
+- `.mcp.json` - MCP server wiring.
+- `assets/logo.png` - plugin icon used by Codex.
+- `skills/alphacouncil-agent/SKILL.md` - runtime instructions for Codex.
+- `mcp/server.mjs` - JSON-RPC MCP server and workflow implementation.
+- `scripts/selfcheck.mjs` - minimal regression check.
+
+## 🆚 Codex vs Claude Code edition
+
+Both editions share the same workflow, JSON packet contract, audit artifacts, the no-API-keys / live-web evidence model, and the same disclaimer. The Claude Code edition changes only *how* the council is run.
+
+| | Codex edition | Claude Code edition |
+|---|---|---|
+| Council execution | `codex exec` workers, concurrency-capped | All 11 analysts as parallel `Task` subagents, one fan-out |
+| Per-analyst context | Separate process | Separate subagent, full isolated context window |
+| Evidence | `codex exec --search` | `WebSearch` + `WebFetch` in each analyst's own context |
+| Evidence → debate | Sequential | Hard barrier on the run's phase machine |
+| Debate depth | 3 rounds (case / rebuttal / Q&A), server-run | 3 rounds, bull + bear in parallel per round |
+| Claim verification | Missing-source gate (run flagged, report banner) | + per-claim adversarial verify: re-fetch cited URL, re-derive, refute *(host-driven)* |
+| Full-run enforcement | Incomplete runs marked `incomplete` (server gate) | Same gate, plus a hard barrier before debate |
+| Model & cost | One model | **Pick per role** — evidence on Sonnet, debate/verdict on Opus 4.8 (or all-Opus / all-Sonnet) |
+| Language | User's language | User's language across every subagent + the live workflow |
+
+**Honest scope:** same model family, same prompts, same audit contract — the win is context isolation, always-on parallel fan-out, and deterministic gates, *not* a smarter model. As of **v0.3.0** the shared server runs the 3-round debate, enforces missing-source / full-run / report-quality gates, writes concise and full report artifacts, and supports native Windows Codex CLI launching. As of **v0.3.1**, the plugin also bundles `agent-skills-governance`, an `addyosmani/agent-skills`-style anti-laziness skill with explicit stop gates and exit criteria. The Claude Code edition adds parallel per-round execution and host-driven per-claim verification. Live-web staleness and paywalls limit both editions equally.
+
+## Data Contract
+
+Evidence agents return JSON packets:
+
+```json
+{
+  "task": "market_data",
+  "symbol": "AAPL",
+  "as_of": "YYYY-MM-DD",
+  "summary": "string",
+  "claims": [
+    {
+      "claim": "string",
+      "evidence": "string",
+      "confidence": "high|medium|low",
+      "source_ids": ["market_data:S1"]
+    }
+  ],
+  "metrics": {},
+  "sources": [
+    {
+      "id": "market_data:S1",
+      "title": "string",
+      "url": "https://example.com",
+      "published_at": "YYYY-MM-DD or unknown",
+      "retrieved_at": "YYYY-MM-DD"
+    }
+  ],
+  "open_questions": ["missing data item"],
+  "confidence": "high|medium|low"
+}
+```
+
+All source IDs are task-scoped as `<task>:<source_id>`. Missing data must be reported in `open_questions` and in the final report's data-gap section.
+
+## Run Locally
+
+```bash
+npm run check
+```
+
+The check validates:
+
+- MCP server syntax
+- tool schema exposure
+- source ID scoping
+- default real-run behavior
+- visible-run recording
+- `events.jsonl`, `status.json`, `all_agents.md`, `source_manifest.json`
+- `final_report.md`, `user_response.md`, `artifact_index.md`, `report_quality.json`
+- one Markdown file per evidence analyst plus bull, bear, and portfolio manager
+- final report includes analyst work log, bull/bear debate record and data gaps
+
+## Codex Install Shape
+
+The plugin expects this local layout:
+
+```text
+.codex-plugin/plugin.json
+.mcp.json
+skills/alphacouncil-agent/SKILL.md
+mcp/server.mjs
+scripts/selfcheck.mjs
+package.json
+```
+
+`.mcp.json` runs:
+
+```json
+{
+  "mcpServers": {
+    "alphacouncil-agent": {
+      "command": "node",
+      "args": ["./mcp/server.mjs"],
+      "cwd": "."
+    }
+  }
+}
+```
+
+## Notes
+
+This is an independent Codex plugin implementation. It uses a multi-agent investment-committee workflow: analyst teams, evidence sharing, bull/bear debate and portfolio-manager synthesis.
+
+No API keys, brokerage credentials, private filings or generated run artifacts should be committed.
+
+## ⭐ Star History
+
+<div align="center">
+
+<a href="https://star-history.com/#Zhao73/alphacouncil-agent&Date">
+  <img src="https://api.star-history.com/svg?repos=Zhao73/alphacouncil-agent&type=Date" width="640" alt="Star History Chart" />
+</a>
+
+<br/><br/>
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="assets/logo-dark.png" />
+  <img src="assets/logo.png" alt="AlphaCouncil" width="120" />
+</picture>
+
+If AlphaCouncil saved you time, consider leaving a ⭐ — it genuinely helps.
+
+<a href="#readme-top">↑ Back to top</a>
+
+</div>