The eleven AI surfaces in Swing Deck

v5.7 introduced seven per-ticker AI surfaces; v6.3 → v6.6 added three more; v6.7 added the eleventh as the LLM layer of the new market-scanner funnel. The current count is eleven: AI Thesis, Devil's Advocate, Pillar Coach, Exit Coach, Entry Coach, Position Audit, Catalyst Interpreter, plus Whale Confirmation Coach (v6.3), Trap & Structure Coach (v6.4), Options Coach (v6.6), and Scanner Narration (v6.7.8). The first ten are per-ticker surfaces grouped by trade-lifecycle role; the eleventh is part of the separate scanner funnel and explains why a name surfaced from the algorithmic Layer 1 ranker. Each surface fires on a specific framework moment, narrates in the framework's voice, and stays out of the way until it's needed. There is no chat box and no free-text prompt by design. For the philosophy behind this decision, read Six AI surfaces, zero chat boxes. This page is the reference for what each surface does, when it appears, and what data it sees.

Surface-bound principle

Every AI surface in Swing Deck obeys five rules:

1. Triggered, not summoned. The user doesn't choose when AI appears. The framework does.
2. Bounded inputs. Each surface receives only the data relevant to the moment it's narrating. There is no global context window of "the user's entire trading history."
3. Bounded outputs. Every response has a known structure (paragraph length, point count, mandatory anchors). No drift, no advice-sounding language, no speculation.
4. Auditable. Every output traces to defined inputs. The same inputs produce a similar output. Cache fingerprints invalidate only when inputs materially change.
5. Logged. Every successful generation appends a record to a single append-only JSONL log (ai_thesis_log.jsonl) with a kind discriminator. One source of truth, queryable from the dashboard's history modal.

All AI surfaces below derive from a single backend module (ai_thesis.py) with a registry-driven coach pattern. Adding a new AI surface is a registry entry, not a new file — the v6.7.8 Scanner Narration was added to the registry without touching any other coach.

① Always-on — default-visible per ticker

AI Thesis

Unlike the coaches, the AI Thesis is styled to the user. The pills let the user nudge the writing toward their preferred density and emphasis. This is the only AI surface in Swing Deck that personalizes. The others are framework voice and cannot be tuned by user feedback — that's a feature, not a limitation.

Devil's Advocate

State drives the direction, not indicator bias. The position-level conclusion (state) is the actionable signal the trader sees; bias is the indicator-level reading. These can disagree (a ticker can be in EXIT state while indicators are still bullish). The Devil's Advocate counters what the trader will act on, not what the indicators say.

② Trade lifecycle — fires at decision moments

Pillar Coach

The Pillar Coach maps pillar IDs to human names internally (P3 → Pre-Market Firewall, P7 → Stop Breach, etc.) so the LLM sees both the framework code and the plain-English meaning. When multiple pillars fire, the coach addresses the dominant cause (the primary field from the position-state classifier) and mentions secondary violations as supporting context.

Entry Coach

The Entry Coach explicitly says: "the trader has fired the trigger; the coach's role is to confirm or temper, never inflate." If a caveat materially weakens the setup — earnings in 12 sessions, a sector that's already over-allocated — the coach says so plainly.

Exit Coach

The chandelier stop (22-day high − 3 × ATR) is the framework's reference stop. If the user's manual stop is below chandelier, the position is already too loose — an exit-coach-worthy event in itself. The coach uses chandelier as the reference even when the user's stop hasn't yet been touched, because the framework's stop is what would have been recommended.

Trap & Structure Coach (NEW · v6.4)

The Trap & Structure Coach is the first AI surface that issues a direct entry verdict (OK / WAIT / AVOID), not just narrates state. It's intended to be read before firing an entry trigger from the 11 price-action primitives — the framework triggers can fire valid breakouts that are also structurally traps. Calibration on 8 tickers showed AI-overrode-framework on 37.5% of cases, all of them subsequently validated by post-trade outcome.

③ Context & discipline — sanity checks beyond the immediate trade

Whale Confirmation Coach (NEW · v6.3)

The Whale Confirmation Coach is the first surface that goes outside the framework's input boundary on purpose. The other coaches narrate from defined local inputs; this one is allowed to fetch fresh web data because the failure mode being guarded against is "the framework tells itself a story." Calibration on PLTR found a $435M insider-selling pattern the framework alone would have missed entirely — that's the whole reason this surface exists.

Catalyst Interpreter

The interpreter is ruthless about classification by design. On any given day, most headlines for any given ticker are noise. The interpreter's job is to make filtering effortless — the trader reads one paragraph instead of scanning twelve headlines.

Critically, when the framework state and the news disagree (e.g., framework says EXIT but news brought a guidance raise + analyst upgrade), the interpreter surfaces the conflict and says exactly what to verify before re-acting. It doesn't flip the trade for you.

Position Audit

This is the local-first AI moat. Cloud-hosted competitors cannot read your fills + your prior theses + your framework state and tell you "low conviction masquerading as activity." They don't have the data. Position Audit makes the trader's behavior the AI's primary input, which is only possible because the journal lives on your machine and nowhere else.

The system prompt explicitly affirms correct restraint when the data shows it. If the trader is appropriately avoiding a low-quality setup, the audit says "restraint (EXIT) is correct." It doesn't manufacture fault.

④ Options — derivatives sleeve narrator

Options Coach (NEW · v6.6)

Options Coach closes the gap left by the existing Pillar / Exit / Entry coaches, which all narrate the equity audit. Pre-v6.6 the 13-pt options panel had a 13-pt score and a setup but no narrator — users had to interpret the sub-pillar grid themselves. The coach reads that grid + the macro context (VIX, regime, earnings calendar, armor-floor state) and explains what's actionable. The entry_blocked trigger added in v6.6.x specifically handles the "setup found but score-gated" case — e.g. AAPL with a $260 Δ 0.935 13-DTE call but composite score 60/100. Coach narrates which sub-pillars dragged the composite below the 70 entry gate (in that case Sweeps 2/10 + IV-Rank 1/10 — whale flow against the long-premium direction + premium historically skinny) and recommends a specific pillar threshold to wait on ("Wait for RSI reset or VIX spike").

Scanner Funnel (NEW · v6.7.8) — top-of-funnel discovery, separate workflow from the per-ticker surfaces above

The market scanner is a three-layer top-of-funnel surface. Layers 1 + 2 are purely algorithmic — the framework's hard line is that AI never picks names. Layer 3 narrates why a name surfaced after the algorithm ranked it. The narration is the only LLM call in the funnel, and it counts toward your LLM cost badge — Layers 1 + 2 stay at zero.

Scanner Narration (NEW · v6.7.8)

Scanner Narration is the only LLM-touching surface in the otherwise-algorithmic scanner funnel. The threshold-citation guard from v6.7.0 binds especially hard here — the LLM cites the exact composite + per-signal numbers it was given, never invents framework gates ("this would clear the 80-point gate" is wrong because the scanner is upstream of the entry gate, not gated by it). Layer 1 (universe scoring) and Layer 2 (Recommended Moves panel that suggests promote/demote/remove based on the live audit + per-ticker score history) are 100% deterministic and add zero LLM cost.

v6.5 chips — deterministic, surface-bound, no LLM (NEW · v6.5)

The v6.5 release adds five per-ticker chips on the position card. They are not new AI surfaces — the count is still ten. Chips are deterministic readings the framework computes from public data; the AI surfaces above read these chips as additional context, but each chip is also visible on its own. Listed here because this page is the canonical reference for what the dashboard puts in front of the trader.

Structural R:R (also v6.5) is not a chip but a framework-wide change: every entry's reward target is now computed from the nearest confluence-merged S/R level above instead of a hardcoded 1.5. The broker preview gate refuses any order whose computed R:R is below 2.0.

History modal

Every AI surface generation appends one record to a single append-only log: ai_thesis_log.jsonl (Options Coach uses its own options_coach_log.jsonl). Each record carries a kind discriminator (thesis, pillar_coach, devils_advocate, exit_coach, entry_coach, position_audit, catalyst_interpreter, whale_confirmation, trap_structure, options_coach) plus the ticker, timestamp, score, state, and full narration text. Whale Confirmation entries additionally log the web_search queries fired and the URL set returned, so any cited URL can be traced back to its retrieval moment.

The dashboard's history modal (accessible via the history button on any AI panel) reads this log directly. As of v5.7.6 it opens in unified All view by default. As of v6.5, whale and trap rows render the full reasoning text alongside the verdict and agreement % — the verdict alone hides the work. The toggle row at the top of the modal is built dynamically — only kinds that have at least one record in your log show as tabs, with their per-kind counts. Tab colors match the panel colors throughout the app:

Trim policy: the log retains the last 5,000 records (HISTORY_MAX_LINES in ai_thesis.py). At ~500 bytes per record, that's roughly 2.5 MB — plenty for years of typical use.

Privacy & cost

BYOK (bring your own key)

Every AI surface uses your own Anthropic or OpenAI API key, configured in Settings → Data Sources. Swing Deck does not run a hosted LLM. We don't see your prompts or your outputs. Two implications:

• You pay your provider directly. Typical per-surface cost is a fraction of a cent (Claude Haiku 4.5 default; OpenAI gpt-4o-mini also supported). Cache hits are free.
• You can pick the model. The default is tuned for short narrations, fast turnaround, low cost. Power users can configure GPT-4o or Claude Sonnet for richer output at higher per-call cost.

What leaves your machine

For each AI surface fire, the dashboard sends the prompt (system + user payload) to your configured provider. The user payload contains:

• Ticker symbol + price + score + state + grade
• Pillar violations / triggers / TP ladder values (where relevant to the surface)
• Macro context: VIX / oil / regime label (numbers, not raw market data feeds)
• Position Audit only: your trade journal entries for that ticker (POST body to localhost, then forwarded to provider)
• Catalyst Interpreter only: today's headline titles + publishers (already public information)

What does not leave your machine: your full portfolio, your account balance, broker tokens, journal entries for any ticker you're not currently asking about, the AI history log itself.

Cost ceiling

Each panel caches by a fingerprint that invalidates only when inputs materially change (state flip, new TP rung hit, new news cycle, new fills appended). Repeatedly opening the same panel without changes returns the cached entry — no LLM call, no cost. A typical active-trading day with 10 portfolio tickers and 2-3 framework events per ticker generates 30-50 LLM calls, well under $0.10 in total at default-model pricing.

Troubleshooting

"Not found" errors after upgrading

The dashboard is HTML/CSS/JS that auto-reloads on hard-refresh, but the Python control server doesn't hot-reload. After a Python-code change (most v5.7.x ships), click ↻ Restart Server in the topbar (next to ? Glossary). Server re-execs in place via os.execv; the dashboard polls /heartbeat and auto-reloads when the server returns. ~3-5 seconds typical.

An AI surface panel doesn't appear on a ticker

Each panel has a defined reveal condition (see the table at the top of each section above). If the condition isn't met, the panel is hidden by design — that's the surface-bound principle. Confirm the relevant data:

• Pillar Coach hidden → ticker is in HOLD or ARMED with no pillar violations. Working as intended.
• Exit Coach hidden → you don't own the ticker, OR price hasn't hit a TP rung, OR price is above the chandelier stop. Working as intended.
• Entry Coach hidden → you own the ticker, OR entry_trigger.ready is false. Working as intended.
• Position Audit hidden → no AI thesis has ever been generated for this ticker AND no journal entries exist for it. Generate a thesis once or log a trade, then refresh.
• Catalyst Interpreter hidden → no news for this ticker today. Confirm via the news scroll at the top of the dashboard. Quiet days = empty interpreter.

"Bring your own key" CTA shows up

Your Anthropic or OpenAI API key isn't configured. Open Settings → Data Sources, paste your key, save. All ten AI surfaces light up with the same key — no per-surface configuration. The v6.3 Whale Confirmation Coach additionally uses Anthropic's web_search tool which is billed at $10 per 1000 searches on top of token usage; the nine other surfaces are token-only.

Dev preview mode

For development or shake-down testing only: open browser DevTools console and run document.body.classList.add('coach-preview') to reveal all panels on every ticker regardless of signal. Endpoints accept ?preview=1 to synthesize plausible framework signals so the LLM has something to narrate. Disable with document.body.classList.remove('coach-preview') or refresh the page. Not for production use — preview narrations are based on synthetic signals, not your real data.