From 7c69d3446e41b2cfff90bd6762b58a95714139ff Mon Sep 17 00:00:00 2001
From: James Tang <thanthos@yahoo.com>
Date: Wed, 24 Jun 2026 00:25:47 +0800
Subject: [PATCH] Initial

---
 README.md | 115 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 114 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 037ba72..b12cbdf 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,115 @@
-# pocket-strategist
+# Pocket Strategist — Phase 0 (Survival Slice)
 
+**Status:** Design Locked — Ready for Build
+**Date:** 2026-06-19
+**Owner:** Grayce (Orchestrator) → Amanda (Implementation)
+
+## Objective
+
+A **working, daily briefing system with a card-based web dashboard** that tells James:
+
+1. **What his money is doing** — per-holding deep dive with price action, technical levels, volume, concentration
+2. **What he can do about it** — action signals (Buy/Sell/Hold) with time-horizon outlook
+3. **What he should NOT do** — risk vetoes (concentration breaches, earnings blackouts, drawdown floors)
+4. **What opportunities exist** — on-demand market scan for SGX and US exchanges
+
+## What This Is NOT
+
+- NOT an autotrader (no execution, no broker APIs, no 2FA gate)
+- NOT a real-time system (daily 07:00 SGT cron + on-demand refresh)
+- NOT the full v0.6 design (no TradingView MCP, no Karakeep, no agent actions, no strategy profiles)
+
+## Architecture
+
+```
+pocket_strategist/
+├── app.py                    # FastAPI — serves dashboard + API routes
+├── engine.py                 # Portfolio engine (fetch, compute, scan)
+├── scanner.py                # Market scan logic
+├── db.py                     # SQLite connection + schema
+├── models.py                 # Pydantic models
+├── config/
+│   ├── holdings/             # Static YAML (source of truth for positions)
+│   │   ├── poems_sg.yaml
+│   │   ├── poems_us.yaml
+│   │   ├── moomoo.yaml
+│   │   └── lirunex.yaml
+│   ├── watchlist.yaml        # Initial watchlist seed
+│   ├── constraints.yaml      # Risk limits
+│   └── scan_universe.yaml    # Symbols to scan per exchange
+├── static/
+│   ├── dashboard.html        # Card-based UI
+│   ├── dashboard.js          # API calls, expand/collapse, actions
+│   └── dashboard.css         # Card grid styling
+├── state/
+│   ├── snapshots/            # Daily price snapshots (JSON)
+│   └── briefings/            # Generated markdown briefings
+└── tests/
+```
+
+## Key Design Decisions
+
+1. **Holdings = static YAML** — James updates manually when he trades. No broker API.
+2. **Watchlist = SQLite** — CRUD via dashboard UI. Differentiated from holdings visually.
+3. **Market scan = on-demand** — button triggers backend scan. Results appear as temporary panel.
+4. **Research button = disabled placeholder** — wired to Phase 1c (Karakeep).
+5. **Single HTML file** — vanilla JS + CSS Grid. No React, no build step.
+6. **Data source = yfinance only** — free, no API key, works now.
+
+## Output Format (Per Holding)
+
+```
+HOLDING: Y92 (ThaiBev) — Equity — POEMS SGX
+Market Value: S$ 27,950 | Cost: S$ 40,648 | P&L: −S$ 12,698 (−31.2%)
+Today (19 Jun): O 0.430 H 0.450 L 0.430 C 0.430
+Concentration: 51.6% of POEMS | 51.6% of Total Portfolio
+Support: 0.420 (20-day low) | Resistance: 0.455 (20-day high)
+Volume: 20d avg 342,334 | Today 123,123 (36% of avg)
+Action: HOLD — Dividend ex-date 23 Jun (est. S$0.015/share)
+Outlook 1W: Capture dividend | 1M: Post-dividend drift to 0.45
+Outlook 6M/1Y/5Y: [Fundamental data — Phase 1c]
+```
+
+## Dashboard Layout
+
+- **Top bar:** Cash cards (by account, by currency, with deployability status)
+- **Holdings grid:** Card per position, collapsed by default, expand for full details
+- **Watchlist grid:** Card per watchlist item, differentiated styling (amber border, ◇ marker)
+- **Action bar:** Scan SGX, Scan US, Export Briefing buttons
+- **Scan results panel:** Appears below grid after scan
+
+## Build Order (3 Amanda Sessions)
+
+### Session 1: Database + Models + Engine
+- SQLite schema + Pydantic models
+- engine.py (fetch, compute, support/resistance)
+- scanner.py (basic screener)
+- API routes
+
+### Session 2: Dashboard HTML/CSS/JS
+- Card grid with expand/collapse
+- Holding vs watchlist differentiation
+- Action buttons
+- Scan trigger + results panel
+- Add/Edit/Delete watchlist
+
+### Session 3: Cron + Briefing + Polish
+- Daily 07:00 SGT cron
+- Markdown briefing compiler
+- OpenClaw session push
+- Mobile responsive pass
+
+## Expansion Path
+
+| Phase | Adds | Trigger |
+|-------|------|---------|
+| 1a — Technicals | Pivot points, VWAP, RVOL, EMA slopes | Phase 0 is stable for 5+ days |
+| 1b — Full Scanner | Broader SGX/US universe, sector screening | James uses scan button regularly |
+| 1c — Context | Karakeep bookmarks, earnings calendar, LLM synthesis | James misses an event |
+| 2 — Execution | 2FA gate, broker adapters, propose-trade | Portfolio stable + broker API exists |
+
+## See Also
+
+- `[flint]/projects/pocket-strategist/` — Full v0.6 design (target architecture)
+- `DESIGN_PHASE0.md` — This project's detailed spec
+- `USER.md` — James's holdings and accounts