alphacouncil-agent 0.5.3 → 0.5.4

package/.claude-plugin/marketplace.json

@@ -6,14 +6,14 @@
   },
   "metadata": {
     "description": "AlphaCouncil plugins for public-equity research.",
-    "version": "0.5.3"
+    "version": "0.5.4"
   },
   "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.4",
       "author": {
         "name": "Zhao73"
       },

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "alphacouncil-agent",
-  "version": "0.5.3",
+  "version": "0.5.4",
   "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.4",
   "description": "Host-visible or background public-equity research workflow with shared evidence packets.",
   "author": {
     "name": "Zhao73"

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 Notable changes per release. Dates are UTC.
 
+## [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/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/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 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                 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "alphacouncil-agent",
-  "version": "0.5.3",
+  "version": "0.5.4",
   "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"
   ]
 }