diff --git a/README.md b/README.md index 33d3587..3d3a9f9 100644 --- a/README.md +++ b/README.md @@ -1,279 +1,285 @@ -# Tool Catalog - -This README catalogs the tools and resources in this directory. It is intended for humans and LLM agents to quickly identify what is available and when to use it. - -## Catalog - -| Tool / Folder | Purpose | Key Files | When to Use | -| --- | --- | --- | --- | -| `workflows/tool-catalog-maintainer/` | Creates and maintains catalog READMEs for directories of tools/resources. | `SKILL.md`, `CONTEXT.md`, `references/catalog-format.md` | Use when asked to catalog, index, or update documentation for a folder of tools. | -| `workflows/research-dfns/` | DFNS research folder — alerts logs, chat log, and TODO tracking from July 27, 2026. | `TODO.md`, `AlertsLog_*.txt`, `ChatLog_*.txt` | Use when reviewing or continuing DFNS research. | -| `workflows/backtest-strategy/` | Orchestrates rules-based strategy backtesting for core styles using TTG data and a pure-Python engine. | `CLAUDE.md`, `CONTEXT.md`, `_config/`, `stages/`, `shared/`, `pyproject.toml` | Use when backtesting trading strategies needing review-gated workflow, data caching, and honest reporting. | -| `workflows/scan-watchlist-for-equities/` | Scans equities for trade setups with confluence using a mechanical data-fetch script. | `CLAUDE.md`, `CONTEXT.md`, `_config/`, `shared/scripts/fetch_scan_data.py`, `stages/` | Use when scanning equities for confluence, generating mechanical data briefs, then interpreting for trade plans. | -| `workflows/scan-watchlist-for-options/` | Scans options for trade setups with confluence using a mechanical data-fetch script. | `CLAUDE.md`, `CONTEXT.md`, `_config/`, `shared/` (CSV watchlists, `scan-watchlist.md`), `stages/` | Use when scanning options for confluence, generating mechanical data briefs, then interpreting for trade plans. | -| `sources/260731-1330-credit-spread.md` | SPY Bull Put Credit Spread trade plan (0DTE, July 31, 2026). Sell $740 put / Buy $738 put spread. | `260731-1330-credit-spread.md` | Use for today's SPY options trade — bullish slow grind thesis. | -| `sources/iron-condor-45dte.md` | SPX Iron Condor trade plan — 45DTE entry, 21DTE time exit, Schwab broker. | `iron-condor-45dte.md` | Use when setting up or managing SPX iron condor spreads. | -| `sources/cha-martin-watchlist.ms.csv` | Cha Martin watchlist export (CSV) for ticker reference or scan filtering. | `cha-martin-watchlist.ms.csv` | Use for ticker watchlist reference or scan filtering. | -| `sources/2026-08-11-SFY-IC-Debrief.md` | Debrief of a SPY Iron Condor trade on 2026-08-11 with observations and key takeaways. | `2026-08-11-SFY-IC-Debrief.md` | Use for reviewing past iron condor trades to learn and improve. | -| `sources/HANDOFF_scan_workflow_scripts.md` | Documentation of the mechanical data-fetch script for scan workflows (API, MCP, output format). | `HANDOFF_scan_workflow_scripts.md` | Use when understanding or implementing the fetch_scan_data.py script. | -| `sources/servers.md` | List of MCP servers available in the MARI environment (ttg-stocks, ttg-benzinga, etc.). | `servers.md` | Use when referencing which data servers are available for MCP tool calls. | -| `sources/xpon-squeeze-2026-08-24.md` | XPON Short Squeeze — Premarket signal reconstruction (2026-08-24) with volume spike and squeeze mechanics. | `xpon-squeeze-2026-08-24.md` | Use for studying a micro-cap short squeeze setup and premarket signals. | -| `tos-short-squeeze/` | Contains a TSV file for short squeeze scanning. | `ShortSqueezeScanner.tsv` | Use for scanning short squeeze opportunities using the provided TSV data. | -| `backtest-workflow-PLAN.md` | Draft plan for a backtesting workflow (approved and built) describing architecture and stages. | `backtest-workflow-PLAN.md` | Use for understanding the design of the backtest-strategy workspace. | -| `build-watcher.md` | Build spec/prompt for a scheduled 9EMA×VWAP cross alert watcher on MESU6 futures. | `build-watcher.md` | Use when building, reviewing, or resuming the MESU6 9EMA/VWAP cross scheduled-alert watcher (or as a template for a similar cross-based futures alert). | - -## Tools - -### `workflows/tool-catalog-maintainer/` - -**Purpose:** -Creates and maintains a `README.md` catalog for a directory containing subfolders of tools, prompts, scripts, docs, workflows, skills, or other reusable resources. The README is a living catalog that improves over time. - -**Contents:** -- `SKILL.md` — skill definition and workflow -- `CONTEXT.md` — full context: inputs, process, outputs, verification -- `references/catalog-format.md` — catalog README structure and cataloging rules -- `output/` — generated artifacts - -**Use when:** -You need to catalog, index, summarize, or update documentation for a folder of tools so humans or LLM agents can quickly choose the right resource. - -**Setup / dependencies:** -None noted. Works with file read/write tools. - -**Notes:** -Always use this tool when asked to catalog a directory — inspect subfolders, read their key files, and write the README using `references/catalog-format.md`. - -### `workflows/research-dfns/` - -**Purpose:** -Research folder for DFNS (Digital Frontier Acquisition Corp.) — contains alert logs, chat transcripts, and tracking notes from July 27, 2026. - -**Contents:** -- `TODO.md` — research tracking tasks -- `AlertsLog_Mon Jul 27 2026*.txt` — alert logs (3 files) -- `ChatLog_Mon Jul 27 2026.txt` — chat transcript - -**Use when:** -Reviewing or continuing DFNS research. Note: per ticker tracking rule, DFNS should not be actively tracked unless a fresh positive reason arises. - -**Setup / dependencies:** -None noted. - -### `workflows/backtest-strategy/` - -**Purpose:** -Orchestrates rules-based strategy backtesting for core styles (SPY 0DTE credit spreads, single-leg equity/options day trades) using TTG data servers as the only market-data source and a local pure-Python engine. - -**Contents:** -- `CLAUDE.md` — workspace identity and entry point -- `CONTEXT.md` — workspace-level routing and stage description -- `_config/` — stable references: `risk-params.md`, `strategy-spec-TEMPLATE.md` -- `stages/` — five stage folders (00_clarify_strategy through 04_report) each with review gates -- `shared/` — data cache (`shared/data/`) and engine scripts (`shared/scripts/`) -- `pyproject.toml` — zero dependencies (stdlib-only) - -**Use when:** -Backtesting trading strategies using TTG data, needing a review-gated workflow with data caching, honest reporting, and no look-ahead. - -**Setup / dependencies:** -None noted (stdlib-only, zero installs; the operator manages packaging with `uv`). Market data comes ONLY from TTG data servers. - -**Notes:** -Follows ICM.md — every stage ends at a review gate. Output is read and optionally edited before the next stage runs. Pure Python 3.12 stdlib (json, csv, sqlite3, statistics, math, datetime, urllib). No historical greeks/IV series; backtests are price/levels-driven. - -### `workflows/scan-watchlist-for-equities/` - -**Purpose:** -Scans tickers for trade setups with confluence, using a mechanical data-fetch script to gather price/volume/bars/S-R data from TTG, producing a data brief for interpretation. - -**Contents:** -- `CLAUDE.md` — workspace identity -- `CONTEXT.md` — workspace routing and stage description -- `_config/` — references such as ticker list, default parameters -- `shared/scripts/fetch_scan_data.py` — stdlib-only Python script for fetching and computing mechanical data -- `shared/` — watchlist CSVs (e.g., `cha-martin-watchlist.ms.csv`, date-named CSVs) -- `stages/` — five stage folders (00_clarify through 04_summary_card) - -**Use when:** -Scanning equities for trade setups with confluence, generating mechanical data briefs (no interpretation), then interpreting the brief for trade plans. - -**Setup / dependencies:** -Python 3.11+, access to TTG data API via `MARI_MCP_CONFIG` environment variable. The fetch script is stdlib-only (urllib, json, etc.). - -**Notes:** -The workflow includes a mechanical script (`fetch_scan_data.py`) that fetches and computes data without interpretation. Stages: 00_clarify (ask clarifying questions), 01_broad_filter (runs the script), 02_confluence_analysis, 03_trade_plan, 04_summary_card. The script writes `data_brief.md` and `raw_data.json` to `stages/01_broad_filter/output/`. - -### `workflows/scan-watchlist-for-options/` - -**Purpose:** -Scans options tickers for trade setups with confluence using a mechanical data-fetch script similar to the equities version. - -**Contents:** -- `CLAUDE.md` — workspace identity -- `CONTEXT.md` — workspace routing and stage description (identical to equities version) -- `_config/` — `trade_plan_template.md` -- `shared/` — CSV watchlists (e.g., `cha-martin-watchlist.ms.csv`, date-named CSVs) and `scan-watchlist.md` -- `stages/` — five stage folders (00_clarify through 04_summary_card) - -**Use when:** -Scanning options for trade setups with confluence, generating mechanical data briefs, then interpreting the brief for trade plans. - -**Setup / dependencies:** -Python 3.11+, access to TTG data API via `MARI_MCP_CONFIG` environment variable. The fetch script is stdlib-only. - -**Notes:** -Very similar to the equities workflow but focused on options. The shared folder contains CSV watchlists and a `scan-watchlist.md` file. The mechanical script (if present) would fetch options data; verify the exact script name and location. - -### `sources/260731-1330-credit-spread.md` - -**Purpose:** -Active trade plan for a SPY Bull Put Credit Spread (0DTE, July 31, 2026). Sell $740 put / Buy $738 put spread, targeting 20%+ profit with bullish slow grind thesis. - -**Contents:** -- `260731-1330-credit-spread.md` — trade plan with entry, exit, profit target, stop loss, and monitoring notes. - -**Use when:** -Executing or monitoring today's SPY options trade (July 31, 2026). - -**Setup / dependencies:** -None noted. Trade-specific, not reusable. - -### `sources/iron-condor-45dte.md` - -**Purpose:** -Trade plan for SPX Iron Condor through Schwab broker. 45DTE entry, 30-point wings, forced close at 21DTE. Includes profit target (25% of net credit), stop loss (50% of max loss), and monitoring cadence. - -**Contents:** -- `iron-condor-45dte.md` — trade plan with entry, exit, risk management, and monitoring details. - -**Use when:** -Setting up or managing SPX iron condor spreads with Schwab broker. - -**Setup / dependencies:** -Schwab broker session required. - -### `sources/cha-martin-watchlist.ms.csv` - -**Purpose:** -CSV export of a Cha Martin watchlist — likely contains tickers for scanning or monitoring. - -**Contents:** -- `cha-martin-watchlist.ms.csv` — plain CSV with one ticker per line (or columns). - -**Use when:** -Referencing tickers for scans, short squeeze candidates, or watchlist filtering. - -**Setup / dependencies:** -None noted. - -### `sources/2026-08-11-SFY-IC-Debrief.md` - -**Purpose:** -Debrief of a SPY Iron Condor trade on 2026-08-11, summarizing trade details, observations, key takeaways, and next times. - -**Contents:** -- `2026-08-11-SFY-IC-Debrief.md` — trade summary, plan, observations, asymmetric structure notes, NL3 feed issue, key takeaways. - -**Use when:** -Reviewing past iron condor trades to learn from observations and improve future trades. - -**Setup / dependencies:** -None noted. - -### `sources/HANDOFF_scan_workflow_scripts.md` - -**Purpose:** -Documentation of a mechanical data-fetch script for the scan-watchlist-for-equities workflow, detailing API facts, script design, environment, MCP protocol, verified responses, output format, and integration notes. - -**Contents:** -- `HANDOFF_scan_workflow_scripts.md` — detailed handoff covering goal, design, environment facts, MCP-over-HTTP protocol, verified response shapes, data brief format, stitching into CONTEXT.md, verification targets, pitfalls, resume checklist, and current state. - -**Use when:** -Understanding or implementing the `fetch_scan_data.py` script, or integrating mechanical data fetching into scan workflows. - -**Setup / dependencies:** -None noted. - -### `sources/servers.md` - -**Purpose:** -List of MCP servers available in the MARI environment for tool calls (e.g., market data, news, chat, etc.). - -**Contents:** -- `servers.md` — plain list of server names: `chrome-devtools`, `mari-cell`, `ttg-benzinga`, `ttg-chat`, `ttg-crypto`, `ttg-economy`, `ttg-finviz-elite`, `ttg-forex`, `ttg-futures`, `ttg-holygrail`, `ttg-indices`, `ttg-options`, `ttg-platform`, `ttg-stocks`, `ttg-uw`. - -**Use when:** -Referencing which data servers are available for MCP tool calls in workflows or scripts. - -**Setup / dependencies:** -None noted. - -### `sources/xpon-squeeze-2026-08-24.md` - -**Purpose:** -XPON Short Squeeze — Premarket signal reconstruction (2026-08-24) documenting a micro-cap short squeeze setup with volume spike, range break, premarket gap, and squeeze mechanics. - -**Contents:** -- `xpon-squeeze-2026-08-24.md` — detailed analysis of the setup, premarket signal, squeeze mechanics, why it was flagged, what went wrong, risk assessment, and key takeaways. - -**Use when:** -Studying a micro-cap short squeeze setup and premarket signals for scanning or education. - -**Setup / dependencies:** -None noted. - -### `tos-short-squeeze/` - -**Purpose:** -Contains a TSV file for short squeeze scanning, likely a precomputed list of candidates. - -**Contents:** -- `ShortSqueezeScanner.tsv` — tab-separated values with columns likely including ticker, metrics, etc. - -**Use when:** -Scanning for short squeeze opportunities using the provided TSV data as input or reference. - -**Setup / dependencies:** -None noted. - -### `backtest-workflow-PLAN.md` - -**Purpose:** -Draft plan for a backtesting workflow (approved and built) describing the architecture, stages, and rules for backtesting core styles using TTG data and a pure-Python engine. - -**Contents:** -- `backtest-workflow-PLAN.md` — goal, architecture (data, engine, reporting layers), proposed workspace layout, stage contracts, decision points, known limitations, credit/cost profile, and out-of-scope items. - -**Use when:** -Understanding the design of the `backtest-strategy` workspace or as a reference for building similar review-gated backtesting workflows. - -**Setup / dependencies:** -None noted. - -### `build-watcher.md` - -**Purpose:** -Prompt/spec for building a scheduled-alert watcher that fires on a 9EMA×VWAP cross for MESU6 (MES Sep 2026 front month). Signal: 9EMA on 3-minute bar closes (built from 1-minute bars) crossing session VWAP anchored at the 9:30 AM ET open. Cross up = long trigger, cross down = short trigger. Explicitly scoped as a scheduled-alert build, not a Holy Grail analysis. - -**Contents:** -- `build-watcher.md` — signal definition, data-source rules, alert discipline, schedule parameters, and credit-cost note. - -**Use when:** -Building, reviewing, or resuming work on the MESU6 9EMA/VWAP cross scheduled alert, or as a template for a similar cross-based futures alert watcher. - -**Setup / dependencies:** -Requires the TTG futures MCP server (`futures_aggs` for bars, `futures_snapshot` for last price) and a Scheduled job runner. The SCHEDULE section (active window, hard stop, fire cap) contains bracketed placeholders in the current draft — these must be filled in before a job is created, and the confirm card must be reviewed and approved before creation. - -**Notes:** -Fires only on an actual state change (no re-alerts); permanently silent after the watch ends or the fire cap is hit. Job pause/delete is user-owned via the Scheduled sidebar — the agent must never pause/delete it itself. Each fired alert costs ~50 Active Trader credits; polls are free. - -## Maintenance Notes - -When adding or updating a tool folder, update this README with: - -- purpose -- key files and entry points -- usage guidance -- setup requirements +# Tool Catalog + +This README catalogs the tools and resources in this directory. It is intended for humans and LLM agents to quickly identify what is available and when to use it. + +## Jurisdiction (set by member, 2026-09-01) + +- `workflows/` = **ICM** (Interpretable Context Methodology, per `workflows/ICM.md`). Member invokes these by name; human review gates between stages. MARI never applies ICM structure to live trade execution. +- `runbooks/` = **MARI-native execution procedures.** This is how MARI runs when the member says "go" — no stage gates except the platform's own (Arm/Enter trade-action cards). Per MEMORY.md RUN RULES, the relevant runbook is read as the FIRST tool call at T+0 of any execution. + +## Catalog + +| Tool / Folder | Purpose | Key Files | When to Use | +| --- | --- | --- | --- | +| `runbooks/spy-0dte-scalp.md` | MARI-native e2e scalp procedure — T+0 gate, recon burst, schema-exact record, arm handoff, manage, stale-kill, post-mortem discipline. | `runbooks/spy-0dte-scalp.md` | FIRST tool call of every live scalp (per MEMORY.md RUN RULES). Not ICM — no stage gates. | +| `workflows/tool-catalog-maintainer/` | Creates and maintains catalog READMEs for directories of tools/resources. | `SKILL.md`, `CONTEXT.md`, `references/catalog-format.md` | Use when asked to catalog, index, or update documentation for a folder of tools. | +| `workflows/research-dfns/` | DFNS research folder — alerts logs, chat log, and TODO tracking from July 27, 2026. | `TODO.md`, `AlertsLog_*.txt`, `ChatLog_*.txt` | Use when reviewing or continuing DFNS research. | +| `workflows/backtest-strategy/` | Orchestrates rules-based strategy backtesting for core styles using TTG data and a pure-Python engine. | `CLAUDE.md`, `CONTEXT.md`, `_config/`, `stages/`, `shared/`, `pyproject.toml` | Use when backtesting trading strategies needing review-gated workflow, data caching, and honest reporting. | +| `workflows/scan-watchlist-for-equities/` | Scans equities for trade setups with confluence using a mechanical data-fetch script. | `CLAUDE.md`, `CONTEXT.md`, `_config/`, `shared/scripts/fetch_scan_data.py`, `stages/` | Use when scanning equities for confluence, generating mechanical data briefs, then interpreting for trade plans. | +| `workflows/scan-watchlist-for-options/` | Scans options for trade setups with confluence using a mechanical data-fetch script. | `CLAUDE.md`, `CONTEXT.md`, `_config/`, `shared/` (CSV watchlists, `scan-watchlist.md`), `stages/` | Use when scanning options for confluence, generating mechanical data briefs, then interpreting for trade plans. | +| `sources/260731-1330-credit-spread.md` | SPY Bull Put Credit Spread trade plan (0DTE, July 31, 2026). Sell $740 put / Buy $738 put spread. | `260731-1330-credit-spread.md` | Use for today's SPY options trade — bullish slow grind thesis. | +| `sources/iron-condor-45dte.md` | SPX Iron Condor trade plan — 45DTE entry, 21DTE time exit, Schwab broker. | `iron-condor-45dte.md` | Use when setting up or managing SPX iron condor spreads. | +| `sources/cha-martin-watchlist.ms.csv` | Cha Martin watchlist export (CSV) for ticker reference or scan filtering. | `cha-martin-watchlist.ms.csv` | Use for ticker watchlist reference or scan filtering. | +| `sources/2026-08-11-SFY-IC-Debrief.md` | Debrief of a SPY Iron Condor trade on 2026-08-11 with observations and key takeaways. | `2026-08-11-SFY-IC-Debrief.md` | Use for reviewing past iron condor trades to learn and improve. | +| `sources/HANDOFF_scan_workflow_scripts.md` | Documentation of the mechanical data-fetch script for scan workflows (API, MCP, output format). | `HANDOFF_scan_workflow_scripts.md` | Use when understanding or implementing the fetch_scan_data.py script. | +| `sources/servers.md` | List of MCP servers available in the MARI environment (ttg-stocks, ttg-benzinga, etc.). | `servers.md` | Use when referencing which data servers are available for MCP tool calls. | +| `sources/xpon-squeeze-2026-08-24.md` | XPON Short Squeeze — Premarket signal reconstruction (2026-08-24) with volume spike and squeeze mechanics. | `xpon-squeeze-2026-08-24.md` | Use for studying a micro-cap short squeeze setup and premarket signals. | +| `tos-short-squeeze/` | Contains a TSV file for short squeeze scanning. | `ShortSqueezeScanner.tsv` | Use for scanning short squeeze opportunities using the provided TSV data. | +| `backtest-workflow-PLAN.md` | Draft plan for a backtesting workflow (approved and built) describing architecture and stages. | `backtest-workflow-PLAN.md` | Use for understanding the design of the backtest-strategy workspace. | +| `build-watcher.md` | Build spec/prompt for a scheduled 9EMA×VWAP cross alert watcher on MESU6 futures. | `build-watcher.md` | Use when building, reviewing, or resuming the MESU6 9EMA/VWAP cross scheduled-alert watcher (or as a template for a similar cross-based futures alert). | + +## Tools + +### `workflows/tool-catalog-maintainer/` + +**Purpose:** +Creates and maintains a `README.md` catalog for a directory containing subfolders of tools, prompts, scripts, docs, workflows, skills, or other reusable resources. The README is a living catalog that improves over time. + +**Contents:** +- `SKILL.md` — skill definition and workflow +- `CONTEXT.md` — full context: inputs, process, outputs, verification +- `references/catalog-format.md` — catalog README structure and cataloging rules +- `output/` — generated artifacts + +**Use when:** +You need to catalog, index, summarize, or update documentation for a folder of tools so humans or LLM agents can quickly choose the right resource. + +**Setup / dependencies:** +None noted. Works with file read/write tools. + +**Notes:** +Always use this tool when asked to catalog a directory — inspect subfolders, read their key files, and write the README using `references/catalog-format.md`. + +### `workflows/research-dfns/` + +**Purpose:** +Research folder for DFNS (Digital Frontier Acquisition Corp.) — contains alert logs, chat transcripts, and tracking notes from July 27, 2026. + +**Contents:** +- `TODO.md` — research tracking tasks +- `AlertsLog_Mon Jul 27 2026*.txt` — alert logs (3 files) +- `ChatLog_Mon Jul 27 2026.txt` — chat transcript + +**Use when:** +Reviewing or continuing DFNS research. Note: per ticker tracking rule, DFNS should not be actively tracked unless a fresh positive reason arises. + +**Setup / dependencies:** +None noted. + +### `workflows/backtest-strategy/` + +**Purpose:** +Orchestrates rules-based strategy backtesting for core styles (SPY 0DTE credit spreads, single-leg equity/options day trades) using TTG data servers as the only market-data source and a local pure-Python engine. + +**Contents:** +- `CLAUDE.md` — workspace identity and entry point +- `CONTEXT.md` — workspace-level routing and stage description +- `_config/` — stable references: `risk-params.md`, `strategy-spec-TEMPLATE.md` +- `stages/` — five stage folders (00_clarify_strategy through 04_report) each with review gates +- `shared/` — data cache (`shared/data/`) and engine scripts (`shared/scripts/`) +- `pyproject.toml` — zero dependencies (stdlib-only) + +**Use when:** +Backtesting trading strategies using TTG data, needing a review-gated workflow with data caching, honest reporting, and no look-ahead. + +**Setup / dependencies:** +None noted (stdlib-only, zero installs; the operator manages packaging with `uv`). Market data comes ONLY from TTG data servers. + +**Notes:** +Follows ICM.md — every stage ends at a review gate. Output is read and optionally edited before the next stage runs. Pure Python 3.12 stdlib (json, csv, sqlite3, statistics, math, datetime, urllib). No historical greeks/IV series; backtests are price/levels-driven. + +### `workflows/scan-watchlist-for-equities/` + +**Purpose:** +Scans tickers for trade setups with confluence, using a mechanical data-fetch script to gather price/volume/bars/S-R data from TTG, producing a data brief for interpretation. + +**Contents:** +- `CLAUDE.md` — workspace identity +- `CONTEXT.md` — workspace routing and stage description +- `_config/` — references such as ticker list, default parameters +- `shared/scripts/fetch_scan_data.py` — stdlib-only Python script for fetching and computing mechanical data +- `shared/` — watchlist CSVs (e.g., `cha-martin-watchlist.ms.csv`, date-named CSVs) +- `stages/` — five stage folders (00_clarify through 04_summary_card) + +**Use when:** +Scanning equities for trade setups with confluence, generating mechanical data briefs (no interpretation), then interpreting the brief for trade plans. + +**Setup / dependencies:** +Python 3.11+, access to TTG data API via `MARI_MCP_CONFIG` environment variable. The fetch script is stdlib-only (urllib, json, etc.). + +**Notes:** +The workflow includes a mechanical script (`fetch_scan_data.py`) that fetches and computes data without interpretation. Stages: 00_clarify (ask clarifying questions), 01_broad_filter (runs the script), 02_confluence_analysis, 03_trade_plan, 04_summary_card. The script writes `data_brief.md` and `raw_data.json` to `stages/01_broad_filter/output/`. + +### `workflows/scan-watchlist-for-options/` + +**Purpose:** +Scans options tickers for trade setups with confluence using a mechanical data-fetch script similar to the equities version. + +**Contents:** +- `CLAUDE.md` — workspace identity +- `CONTEXT.md` — workspace routing and stage description (identical to equities version) +- `_config/` — `trade_plan_template.md` +- `shared/` — CSV watchlists (e.g., `cha-martin-watchlist.ms.csv`, date-named CSVs) and `scan-watchlist.md` +- `stages/` — five stage folders (00_clarify through 04_summary_card) + +**Use when:** +Scanning options for trade setups with confluence, generating mechanical data briefs, then interpreting the brief for trade plans. + +**Setup / dependencies:** +Python 3.11+, access to TTG data API via `MARI_MCP_CONFIG` environment variable. The fetch script is stdlib-only. + +**Notes:** +Very similar to the equities workflow but focused on options. The shared folder contains CSV watchlists and a `scan-watchlist.md` file. The mechanical script (if present) would fetch options data; verify the exact script name and location. + +### `sources/260731-1330-credit-spread.md` + +**Purpose:** +Active trade plan for a SPY Bull Put Credit Spread (0DTE, July 31, 2026). Sell $740 put / Buy $738 put spread, targeting 20%+ profit with bullish slow grind thesis. + +**Contents:** +- `260731-1330-credit-spread.md` — trade plan with entry, exit, profit target, stop loss, and monitoring notes. + +**Use when:** +Executing or monitoring today's SPY options trade (July 31, 2026). + +**Setup / dependencies:** +None noted. Trade-specific, not reusable. + +### `sources/iron-condor-45dte.md` + +**Purpose:** +Trade plan for SPX Iron Condor through Schwab broker. 45DTE entry, 30-point wings, forced close at 21DTE. Includes profit target (25% of net credit), stop loss (50% of max loss), and monitoring cadence. + +**Contents:** +- `iron-condor-45dte.md` — trade plan with entry, exit, risk management, and monitoring details. + +**Use when:** +Setting up or managing SPX iron condor spreads with Schwab broker. + +**Setup / dependencies:** +Schwab broker session required. + +### `sources/cha-martin-watchlist.ms.csv` + +**Purpose:** +CSV export of a Cha Martin watchlist — likely contains tickers for scanning or monitoring. + +**Contents:** +- `cha-martin-watchlist.ms.csv` — plain CSV with one ticker per line (or columns). + +**Use when:** +Referencing tickers for scans, short squeeze candidates, or watchlist filtering. + +**Setup / dependencies:** +None noted. + +### `sources/2026-08-11-SFY-IC-Debrief.md` + +**Purpose:** +Debrief of a SPY Iron Condor trade on 2026-08-11, summarizing trade details, observations, key takeaways, and next times. + +**Contents:** +- `2026-08-11-SFY-IC-Debrief.md` — trade summary, plan, observations, asymmetric structure notes, NL3 feed issue, key takeaways. + +**Use when:** +Reviewing past iron condor trades to learn from observations and improve future trades. + +**Setup / dependencies:** +None noted. + +### `sources/HANDOFF_scan_workflow_scripts.md` + +**Purpose:** +Documentation of a mechanical data-fetch script for the scan-watchlist-for-equities workflow, detailing API facts, script design, environment, MCP protocol, verified responses, output format, and integration notes. + +**Contents:** +- `HANDOFF_scan_workflow_scripts.md` — detailed handoff covering goal, design, environment facts, MCP-over-HTTP protocol, verified response shapes, data brief format, stitching into CONTEXT.md, verification targets, pitfalls, resume checklist, and current state. + +**Use when:** +Understanding or implementing the `fetch_scan_data.py` script, or integrating mechanical data fetching into scan workflows. + +**Setup / dependencies:** +None noted. + +### `sources/servers.md` + +**Purpose:** +List of MCP servers available in the MARI environment for tool calls (e.g., market data, news, chat, etc.). + +**Contents:** +- `servers.md` — plain list of server names: `chrome-devtools`, `mari-cell`, `ttg-benzinga`, `ttg-chat`, `ttg-crypto`, `ttg-economy`, `ttg-finviz-elite`, `ttg-forex`, `ttg-futures`, `ttg-holygrail`, `ttg-indices`, `ttg-options`, `ttg-platform`, `ttg-stocks`, `ttg-uw`. + +**Use when:** +Referencing which data servers are available for MCP tool calls in workflows or scripts. + +**Setup / dependencies:** +None noted. + +### `sources/xpon-squeeze-2026-08-24.md` + +**Purpose:** +XPON Short Squeeze — Premarket signal reconstruction (2026-08-24) documenting a micro-cap short squeeze setup with volume spike, range break, premarket gap, and squeeze mechanics. + +**Contents:** +- `xpon-squeeze-2026-08-24.md` — detailed analysis of the setup, premarket signal, squeeze mechanics, why it was flagged, what went wrong, risk assessment, and key takeaways. + +**Use when:** +Studying a micro-cap short squeeze setup and premarket signals for scanning or education. + +**Setup / dependencies:** +None noted. + +### `tos-short-squeeze/` + +**Purpose:** +Contains a TSV file for short squeeze scanning, likely a precomputed list of candidates. + +**Contents:** +- `ShortSqueezeScanner.tsv` — tab-separated values with columns likely including ticker, metrics, etc. + +**Use when:** +Scanning for short squeeze opportunities using the provided TSV data as input or reference. + +**Setup / dependencies:** +None noted. + +### `backtest-workflow-PLAN.md` + +**Purpose:** +Draft plan for a backtesting workflow (approved and built) describing the architecture, stages, and rules for backtesting core styles using TTG data and a pure-Python engine. + +**Contents:** +- `backtest-workflow-PLAN.md` — goal, architecture (data, engine, reporting layers), proposed workspace layout, stage contracts, decision points, known limitations, credit/cost profile, and out-of-scope items. + +**Use when:** +Understanding the design of the `backtest-strategy` workspace or as a reference for building similar review-gated backtesting workflows. + +**Setup / dependencies:** +None noted. + +### `build-watcher.md` + +**Purpose:** +Prompt/spec for building a scheduled-alert watcher that fires on a 9EMA×VWAP cross for MESU6 (MES Sep 2026 front month). Signal: 9EMA on 3-minute bar closes (built from 1-minute bars) crossing session VWAP anchored at the 9:30 AM ET open. Cross up = long trigger, cross down = short trigger. Explicitly scoped as a scheduled-alert build, not a Holy Grail analysis. + +**Contents:** +- `build-watcher.md` — signal definition, data-source rules, alert discipline, schedule parameters, and credit-cost note. + +**Use when:** +Building, reviewing, or resuming work on the MESU6 9EMA/VWAP cross scheduled alert, or as a template for a similar cross-based futures alert watcher. + +**Setup / dependencies:** +Requires the TTG futures MCP server (`futures_aggs` for bars, `futures_snapshot` for last price) and a Scheduled job runner. The SCHEDULE section (active window, hard stop, fire cap) contains bracketed placeholders in the current draft — these must be filled in before a job is created, and the confirm card must be reviewed and approved before creation. + +**Notes:** +Fires only on an actual state change (no re-alerts); permanently silent after the watch ends or the fire cap is hit. Job pause/delete is user-owned via the Scheduled sidebar — the agent must never pause/delete it itself. Each fired alert costs ~50 Active Trader credits; polls are free. + +## Maintenance Notes + +When adding or updating a tool folder, update this README with: + +- purpose +- key files and entry points +- usage guidance +- setup requirements - notable changes or cautions \ No newline at end of file diff --git a/runbooks/spy-0dte-scalp.md b/runbooks/spy-0dte-scalp.md new file mode 100644 index 0000000..cc928ed --- /dev/null +++ b/runbooks/spy-0dte-scalp.md @@ -0,0 +1,61 @@ +# SPY 0DTE Scalp Runbook — E2E Fast Path (MARI-native) +*v2 — 2026-09-01 13:45 ET. v1 built 2026-08-28 from spy-1787942969793 (closed un-filled at 3:00 wall). v2 folds in the 2026-09-01 double-failure post-mortem (spy-1788280948132, spy-1788282204586 — both discarded un-filled, zero fills, $0 cost). Lives in `runbooks/` — MARI-native execution jurisdiction, NOT ICM: no stage-review gates; the platform's Arm/Enter cards are the only human gates. Per MEMORY.md RUN RULES, reading this file is the FIRST tool call of every scalp, before recon, before record — no exceptions.* + +## The speed rule +**Never discover inside a trade window.** Design + record the plan BEFORE the intended entry window; arm = one pasted line. Measured 2026-09-01: prompt→ready 5m41s (two full ~700KB chain pulls + one schema retry) then ~21 min dead in the arm handoff = setup near-invalidation by ready time. Targets under this runbook: **prompt→plan-ready ≤90s, prompt→armed ≈2–3 min.** The Arm card click is the irreducible floor (app-owned pack preflight, safety rail) — everything else compresses. + +## 0. T+0 gate + handshake (v2 — this failed twice before it was written down) +- **First tool call of the run = read this runbook.** It must land visibly in the transcript before any recon or record call. +- **Handshake:** member parks the Live Trading window OPEN + CONNECTED *before* saying go. The go prompt carries symbol + account, nothing else. +- MARI never asks "which window are you in" mid-flight. If the cockpit is not connected at arm time, the window is already burning → stale-kill per §4, re-stage, don't negotiate. + +## 1. Recon burst (≤60s, ONE parallel tool block) +- Same block: `snapshot(SPY)` + `ttg_trade_workflow_prepare_context` + `options_snapshot_chain` for **ONE side only** — the side the snapshot's direction call already picked. Never both chains. **Never a mid-flow re-pull, including at stale checks** (the 9/1 re-validation pull at 12:53 was pure waste; snapshot + last known quotes answer staleness). +- Direction call: price vs VWAP + day-low/high structure. Trend-day tape → trade the break (continuation), not the bounce. Mid-range chop → stand down. Bounce in progress toward invalidation → do NOT chase; record a CONDITIONAL plan whose entry zone only fills on a re-press (9/1: zone 0.42–0.58 on 761P after a 4-minute bounce), or stand down entirely. +- Liquidity check (both expiries, Friday rule): + - `ttg-options` → `options_snapshot_chain`, params: `underlyingAsset: "SPY"`, `contract_type: "put"|"call"`, `expiration_date` EXACT string "2026-09-01"-style (range objects = HTTP 500), `limit: 250`, `sort: "strike_price"`. + - 0DTE near-money: 1–2¢ spreads, 300–600K vol = elite. Next-week: premium ~$4 → +20% in 15 min needs ~$1.60 SPY move vs ~$0.30 on 0DTE. 0DTE is the 15-min vehicle; next-week is for plays/swings. +- Vehicle pick: ATM-ish strike, delta −0.3 to −0.5 at expected trigger price, spread ≤ 2¢. + +## 2. Record the plan (schema-exact v2, FIRST TRY) +`ttg_trade_workflow_record_plan` — template (validated shape, both 8/28 and 9/1): +``` +brokerId: "tos-paper", connectedBrokerPackId: "tos-paper", +accountCode: "D-67336185" // 185; "D-67336186" = 186 +assetClass: "option", symbol: "SPY", side: "buy", +tradeStyle: "scalp", // NOT "style" +instrumentRef: {symbol: "SPY", strike: 761, type: "put", + expiration: "2026-09-01"}, // MUST be object, never string +levels: { + entry: {zone: {low: 0.42, high: 0.58}, type: "limit"}, // premium zone + stop: {offset: 0.10}, // POSITIVE number — it's a distance below fill. + // 9/1 cost 45s on "-0.1": rejected, full retry cycle. + targets: [{offset: 0.12, portionPct: 50}, {offset: 0.18, portionPct: 50}], // max 2 + timeStopSec: 900, // REQUIRED for scalp/day; in-trade from fill + breakevenAfterT1: true +}, +risk: {maxDollars: 20}, // engine computes qty — NEVER send qty +timeLimitSec: 600, // ENTRY WINDOW seconds (NOT the time stop) +rationale: "≥40 chars — SPY-level triggers, invalidations, walls, order-safety directives here" +``` +Validation gotchas (each has cost an iteration): `tradeStyle` not `style`; no top-level entry/stop/target/qty; `instrumentRef` object not string; **stop offset positive**; engine enforces **R:R > 1 — every target offset must exceed the stop offset**. +Response: planId `spy-`, status draft in PLANS/. SPY-level triggers go in rationale. + +## 3. Arm — CONFIRMED 2026-09-01 (twice), no longer a hypothesis +- **Main-chat "arm" CANNOT fire the card.** The Arm card exists ONLY in the Live Trading window's own MARI chat. Member types `arm ` THERE → card renders → Arm click (preflight auto-runs) → Enter. +- MARI waits via `await_event` (revision change), never sleep-polling; plan-ready message carries planId + the literal arm line so the paste is 5 seconds. +- **NEVER fake arming from main chat** (`update_plan status:"open"` skips preflight/stream verify — dangerous). Main-window MARI cannot arm; the cockpit orchestrator owns execution. +- **Stale-kill:** if not armed by the entry-window deadline → `ttg_trade_workflow_discard_plan` (verified live twice 9/1), stand down, never manage a dead window, never chase the bounce afterward. + +## 4. Manage (standing protocol — member directives, encode in rationale every time) +1. On fill: verify BOTH working and filled orders. Stop must read **SELL TO CLOSE ** — never sell-to-open, never a short entry. +2. T1 fills → scale stop to remaining qty (+ breakevenAfterT1 moves it to BE). T2/stop-out → **cancel ALL working orders the instant flat or profit taken.** Working + filled checked both after every event. No orphans, ever. +3. Walls: `timeStopSec` from fill + explicit wall-clock hard flat in rationale. Bail on tape deterioration before the stop (slow grind back = failed setup). +4. Management loop = `await_event` cycles at 1s belt/watcher cadence; terse timestamped updates only while the window is live. + +## 5. Post-mortem discipline (v2) +After every e2e run — fill or not: procedure deltas fold into THIS file; MEMORY.md Lessons gets a one-line pointer only. **Lessons = history + pointers. Runbook = procedure.** A procedure that lives only in Lessons will lose to run momentum — verified 9/1 when the loaded lesson was ignored mid-flight. + +## 15-min target math (10–25% premium band) +- 0DTE ATM-ish premium P, delta Δ: +20% ≈ 0.20·P / Δ SPY move. At P≈$0.85, Δ≈−0.50 → ~$0.34 SPY. Routine in 15 min on a break. +- Engine R:R rule forces target offset > stop offset: size stop −10 to −16% and T1 +19 to +22% to stay inside the band AND clear R:R>1 (verified combos: stop 0.18 / T1 0.20 / T2 0.40 on ~$0.84 fill; stop 0.10 / T1 0.12 / T2 0.18 on ~$0.54 mid). diff --git a/spy-0dte-scalp-runbook.md b/spy-0dte-scalp-runbook.md deleted file mode 100644 index eb946cc..0000000 --- a/spy-0dte-scalp-runbook.md +++ /dev/null @@ -1,53 +0,0 @@ -# SPY 0DTE Scalp Runbook — E2E Fast Path -*Built from live execution 2026-08-28 (spy-1787942969793, closed un-filled at 3:00 wall). Companion lessons live in MEMORY.md: record_plan v2 schema, arm-card flow, ttg-options endpoint patterns.* - -## The speed rule -**Never discover inside a trade window.** Design + record the plan BEFORE the intended entry window; arm = one line. First-ever run took ~7 min for design→record (3 schema validation iterations) + unresolved arm-card surfacing = whole window lost. With this runbook: **~2 min to recorded plan, one line to arm.** - -## 1. Pre-stage (do this 5+ min before the window) -- Fresh SPY snapshot (built-in `snapshot` tool) — price, day OHLC, VWAP. -- Direction call: price vs VWAP + day-low/high structure. Trend-day tape → trade the break (continuation), not the bounce. Mid-range chop → stand down. -- Liquidity check (both expiries, Friday rule): - - `ttg-options` → `options_snapshot_chain`, params: `underlyingAsset: "SPY"`, `contract_type: "put"|"call"`, `expiration_date: "2026-08-28"` (EXACT string; range objects `{"gte":...}` = HTTP 500), `limit: 250`, `sort: "strike_price"`. - - 0DTE near-money: 1–2¢ spreads, 300–600K vol = elite. Next-week: 2–3¢ spreads but premium ~$4 → +20% in 15 min needs ~$1.60 SPY move vs ~$0.30 on 0DTE. 0DTE is the 15-min vehicle; next-week is for plays/swings. -- Vehicle pick: ATM-ish strike, delta −0.4 to −0.5 at expected trigger price, spread ≤ 2¢. - -## 2. Record the plan (exact verified v2 shape) -`ttg_trade_workflow_record_plan` — template (from the call that validated): -``` -brokerId: "tos-paper", connectedBrokerPackId: "tos-paper", -accountCode: "D-67336185" // 185; "D-67336186" = 186 -assetClass: "option", symbol: "SPY", side: "buy", -tradeStyle: "scalp", -instrumentRef: {symbol: ".SPY260828P769", strike: 769, type: "put", - expiration: "2026-08-28", underlying: "SPY", - occ: "O:SPY260828P00769000"}, // MUST be object, not string -levels: { - entry: {zone: {low: 0.76, high: 0.92}, type: "limit", minBidSize: 50}, // premium zone - stop: {offset: 0.18}, // points from fill (premium pts for options) - targets: [{offset: 0.20, portionPct: 67}, {offset: 0.40, portionPct: 33}], // max 2 - timeStopSec: 900, // REQUIRED for scalp/day; in-trade from fill - breakevenAfterT1: true -}, -risk: {maxDollars: 70}, // engine computes qty = maxDollars/(offset×100) — NEVER send qty -timeLimitSec: 780, // ENTRY WINDOW seconds (NOT the time stop) -rationale: "≥40 chars — put SPY-level triggers, invalidations, hard walls, order-safety directives here" -``` -Validation gotchas (each cost an iteration): `tradeStyle` not `style`; no top-level entry/stop/target/qty; `instrumentRef` object not string; engine enforces **R:R > 1 — every target offset must exceed the stop offset**. -Response: planId `spy-`, status draft in PLANS/. SPY-level triggers go in rationale. - -## 3. Arm (the one unverified link — TEST FIRST, outside a live window) -Record response says: "Propose an arm trade-action card — the app runs the pack preflight, verifies the stream, starts the preview belt. Do NOT call record_preflight (cockpit packs), do NOT start belt jobs yourself." -- Arm card does NOT auto-render in the cockpit UI (confirmed 2026-08-28: cockpit open+connected, no card). -- **Working hypothesis:** arm via the Live Trading window's own MARI chat — type `arm `. Cockpit agent (locked to the pack) proposes the Arm card → tap Arm (preflight auto-runs) → tap Enter. -- NEVER fake arming from main chat (`update_plan status:"open"` skips preflight/stream verify — dangerous). Main-window MARI cannot arm; cockpit orchestrator owns execution. - -## 4. Manage (standing protocol — member directives, encode in rationale every time) -1. On fill: verify BOTH working and filled orders. Stop must read **SELL TO CLOSE ** — never sell-to-open, never a short entry. -2. T1 fills → scale stop to remaining qty (+ breakevenAfterT1 moves it to BE). T2/stop-out → **cancel ALL working orders the instant flat.** Working + filled checked both after every event. No orphans, ever. -3. Walls: `timeStopSec` from fill + explicit wall-clock hard flat in rationale. Bail on tape deterioration before the stop (slow grind back = failed setup). -4. Pre-entry invalidations: structure reclaim / VWAP reclaim / no trigger by window close → no trade. **Stale plan = close clean, never chase** (2026-08-28: closed un-filled at 3:00 wall, $0 cost). - -## 15-min target math (10–25% premium band) -- 0DTE ATM-ish premium P, delta Δ: +20% ≈ 0.20·P / Δ SPY move. At P≈$0.85, Δ≈−0.50 → ~$0.34 SPY. Routine in 15 min on a break. -- Engine R:R rule forces target offset > stop offset: size stop −18 to −22% and T1 +24 to +26% to stay inside the band AND clear R:R>1 (verified combo: stop 0.18 / T1 0.20 / T2 0.40 on ~$0.84 fill).