feat: update README, plan docs, and add agent lifecycle hooks

.agents/AGENTS.md

@@ -0,0 +1,17 @@
+# AGENTS.md — FinAlly Project Agent Instructions
+
+Welcome to **FinAlly**, an AI-powered trading workstation capstone project built with FastAPI, Next.js, and SQLite.
+
+## Project Structure
+- `backend/`: FastAPI Python project managed with `uv`.
+- `frontend/`: Next.js TypeScript project (`output: 'export'`).
+- `planning/`: Project plan specifications (`PLAN.md`), reviews (`REVIEW.md`), and agent design documents.
+
+## Available Skills & Agents
+- **Skills**: `cerebras-inference` in `.agents/skills/cerebras/SKILL.md`, `doc-review` in `.agents/skills/doc-review/SKILL.md`, `code-review` in `.agents/skills/code-review/SKILL.md`
+- **Agents**: `reviewer`, `codex-reviewer`, and `change-reviewer` in `.agents/agents/`
+- **Commands**: `doc-review`, `code-review`, `reviewer`, `codex-reviewer`, `change-reviewer`
+
+
+
+

.agents/agents/change-reviewer/agent.md

@@ -0,0 +1,14 @@
+---
+name: change-reviewer
+description: carry out a comprehensive review of all changes since the last commit using Gemini 3.6 Flash
+model: gemini-3.6-flash
+tools:
+  - run_command
+  - view_file
+  - write_to_file
+---
+
+This subagent reviews all changes since the last commit using shell commands.
+IMPORTANT: Execute the following shell command to carry out the review using agy CLI:
+`agy exec --model gemini-3.6-flash "Please review all changes since the last commit and write feedback to planning/REVIEW.md"`
+This will run the review process and save the results.

.agents/agents/codex-reviewer/agent.md

@@ -0,0 +1,14 @@
+---
+name: codex-reviewer
+description: carry out a comprehensive review of PLAN.md when requested using codex
+tools:
+  - run_command
+  - view_file
+  - write_to_file
+---
+
+You are using a different AI Agent to carry out a review of the document: planning/PLAN.md.
+You MUST execute the following shell command to carry out the review – do not review yourself:
+`agy exec --model gemini-3.6-flash  "Please review the file planning/PLAN.md and write your feedback to planning/REVIEW.md"`
+This will run the review process and save the results.
+Do not review yourself.

.agents/agents/reviewer/agent.md

@@ -0,0 +1,10 @@
+---
+name: reviewer
+description: Review planning/PLAN.md and write feedback to planning/REVIEW.md
+tools:
+  - run_command
+  - view_file
+  - write_to_file
+---
+
+You review the file planning/PLAN.md and write your feedback to planning/REVIEW.md

.agents/commands/change-reviewer.md

@@ -0,0 +1,8 @@
+---
+description: carry out a comprehensive review of all changes since the last commit using Gemini 3.6 Flash
+---
+
+This subagent reviews all changes since the last commit using shell commands.
+IMPORTANT: Execute the following shell command to carry out the review using agy CLI:
+`agy exec --model gemini-3.6-flash "Please review all changes since the last commit and write feedback to planning/REVIEW.md"`
+This will run the review process and save the results.

.agents/commands/code-review.md

@@ -0,0 +1,5 @@
+---
+description: Perform a code review on specified files or changes
+---
+
+Review the code in $ARGUMENTS (or recent changes) and provide feedback on performance, code quality, potential bugs, and adherence to project conventions.

.agents/commands/codex-reviewer.md

@@ -0,0 +1,9 @@
+---
+description: carry out a comprehensive review of PLAN.md when requested using codex
+---
+
+You are using a different AI Agent to carry out a review of the document: planning/PLAN.md.
+You MUST execute the following shell command to carry out the review – do not review yourself:
+`codex exec "Please review the file planning/PLAN.md and write your feedback to planning/REVIEW.md"`
+This will run the review process and save the results.
+Do not review yourself.

.agents/commands/doc-review.md

@@ -0,0 +1,5 @@
+---
+description: Review a documentation file
+---
+
+Review the documentation file in the planning folder called $ARGUMENTS and add questions, clarifications or feedback to a new section at the end, along with any opportunities to simplify

.agents/commands/reviewer.md

@@ -0,0 +1,5 @@
+---
+description: Review planning/PLAN.md and write feedback to planning/REVIEW.md
+---
+
+You review the file planning/PLAN.md and write your feedback to planning/REVIEW.md

.agents/hooks.json

@@ -0,0 +1,12 @@
+{
+  "post-prompt-review": {
+    "enabled": true,
+    "Stop": [
+      {
+        "type": "command",
+        "command": "node .agents/scripts/run_review.js",
+        "timeout": 180
+      }
+    ]
+  }
+}

.agents/plugins.json

@@ -0,0 +1,18 @@
+{
+  "plugins": [
+    {
+      "name": "independent-reviewer",
+      "source": "./plugins/independent-reviewer",
+      "description": "Carry out an independent review of all changes since last commit",
+      "version": "1.0.0",
+      "author": {
+        "name": "Ed"
+      }
+    }
+  ],
+  "entries": [
+    {
+      "path": ".agents/plugins/independent-reviewer"
+    }
+  ]
+}

.agents/plugins/independent-reviewer/hooks.json

@@ -0,0 +1,12 @@
+{
+  "independent-reviewer": {
+    "enabled": true,
+    "Stop": [
+      {
+        "type": "command",
+        "command": "node .agents/scripts/run_review.js",
+        "timeout": 180
+      }
+    ]
+  }
+}

.agents/plugins/independent-reviewer/plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "independent-reviewer",
+  "description": "Carry out an independent review of all changes since last commit",
+  "version": "1.0.0",
+  "author": {
+    "name": "Ed"
+  }
+}

.agents/plugins/independent-reviewer/rules/review-rules.md

@@ -0,0 +1,5 @@
+# Independent Reviewer Rules
+
+- **Scope**: Focus on uncommitted or recent changes since the last git commit.
+- **Verification**: Run unit tests and verification commands to ensure code changes compile and pass.
+- **Reporting**: Always record review results cleanly in `planning/REVIEW.md`.

.agents/plugins/independent-reviewer/skills/independent-reviewer/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: independent-reviewer
+description: Carry out an independent review of all changes since last commit
+---
+
+# Independent Reviewer Skill
+
+Perform an impartial, comprehensive code review of all changes introduced since the last commit.
+
+## Execution Steps
+
+1. Inspect modified and untracked files using `git status` and `git diff HEAD~1`.
+2. Evaluate:
+   - **Correctness & Architecture**: Verify design patterns, logic, and state handling.
+   - **Quality & Style**: Check formatting, linting rules, and comments.
+   - **Performance & Security**: Identify potential memory leaks, redundant API calls, or safety risks.
+3. Write actionable feedback and review summary to `planning/REVIEW.md`.

.agents/scripts/run_review.js

@@ -0,0 +1,35 @@
+function executeHook() {
+  if (hasRun) return;
+  hasRun = true;
+
+  const projectRoot = path.join(__dirname, '..', '..');
+  const logDir = path.join(projectRoot, 'planning');
+  if (!fs.existsSync(logDir)) fs.mkdirSync(logDir, { recursive: true });
+
+  const logFile = path.join(logDir, 'agy-review.log');
+
+  // Write the "hook fired" timestamp line first
+  const timestamp = new Date().toISOString();
+  fs.appendFileSync(logFile, `\n=== hook-fired ${timestamp} ===\n`);
+
+  const logFd = fs.openSync(logFile, 'a'); // 'a' = append, so this doesn't wipe the timestamp line above
+
+  const prompt = "Write a REVIEW.md of this project's last file changes at planning/REVIEW.md";
+
+  try {
+    execFileSync('agy', ['-p', prompt, '--dangerously-skip-permissions'], {
+      cwd: projectRoot,
+      stdio: ['ignore', logFd, logFd],
+      windowsHide: true,
+      shell: true,
+      timeout: 170000
+    });
+  } catch (err) {
+    fs.writeSync(logFd, `\n[hook error] ${err.message}\n`);
+  } finally {
+    fs.closeSync(logFd);
+  }
+
+  console.log(JSON.stringify({ decision: 'allow' }));
+  process.exit(0);
+}

.agents/settings.json

@@ -0,0 +1,12 @@
+{
+  "hooks": {
+    "Stop": [
+      {
+        "matcher": ".*",
+        "type": "command",
+        "command": "node .agents/scripts/run_review.js",
+        "enabled": true
+      }
+    ]
+  }
+}

.agents/skills/doc-review/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: doc-review
+description: Review a documentation file
+---
+
+Review the documentation file in the planning folder called $ARGUMENTS and add questions, clarifications or feedback to a new section at the end, along with any opportunities to simplify

.agents/workflows/change-reviewer.md

@@ -0,0 +1,8 @@
+---
+description: carry out a comprehensive review of all changes since the last commit using Gemini 3.6 Flash
+---
+
+This subagent reviews all changes since the last commit using shell commands.
+IMPORTANT: Execute the following shell command to carry out the review using agy CLI:
+`agy exec --model gemini-3.6-flash "Please review all changes since the last commit and write feedback to planning/REVIEW.md"`
+This will run the review process and save the results.

.agents/workflows/code-review.md

@@ -0,0 +1,5 @@
+---
+description: Perform a code review on specified files or changes
+---
+
+Review the code in $ARGUMENTS (or recent changes) and provide feedback on performance, code quality, potential bugs, and adherence to project conventions.

.agents/workflows/codex-reviewer.md

@@ -0,0 +1,9 @@
+---
+description: carry out a comprehensive review of PLAN.md when requested using codex
+---
+
+You are using a different AI Agent to carry out a review of the document: planning/PLAN.md.
+You MUST execute the following shell command to carry out the review – do not review yourself:
+`codex exec "Please review the file planning/PLAN.md and write your feedback to planning/REVIEW.md"`
+This will run the review process and save the results.
+Do not review yourself.

.agents/workflows/doc-review.md

@@ -0,0 +1,5 @@
+---
+description: Review a documentation file
+---
+
+Review the documentation file in the planning folder called $ARGUMENTS and add questions, clarifications or feedback to a new section at the end, along with any opportunities to simplify

.agents/workflows/reviewer.md

@@ -0,0 +1,5 @@
+---
+description: Review planning/PLAN.md and write feedback to planning/REVIEW.md
+---
+
+You review the file planning/PLAN.md and write your feedback to planning/REVIEW.md

README.md

@@ -1,62 +1,54 @@
-# FinAlly — AI Trading Workstation
+# FinAlly — AI-Powered Trading Workstation
 
-A visually stunning AI-powered trading workstation that streams live market data, simulates portfolio trading, and integrates an LLM chat assistant that can analyze positions and execute trades via natural language.
-
-Built entirely by coding agents as a capstone project for an agentic AI coding course.
+**FinAlly** (Finance Ally) is an AI-powered trading workstation featuring real-time market data streaming via Server-Sent Events (SSE), simulated portfolio management, and an integrated LLM trading copilot.
 
 ## Features
 
-- **Live price streaming** via SSE with green/red flash animations
-- **Simulated portfolio** — $10k virtual cash, market orders, instant fills
-- **Portfolio visualizations** — heatmap (treemap), P&L chart, positions table
-- **AI chat assistant** — analyzes holdings, suggests and auto-executes trades
-- **Watchlist management** — track tickers manually or via AI
-- **Dark terminal aesthetic** — Bloomberg-inspired, data-dense layout
-
-## Architecture
+- ⚡ **Live Market Streaming**: Real-time tick updates via SSE, powered by an internal Geometric Brownian Motion (GBM) simulator or Polygon.io (Massive API).
+- 💼 **Simulated Trading**: Virtual portfolio management with real-time unrealized P&L tracking and instant market order execution.
+- 🤖 **AI Trading Copilot**: LLM-driven assistant for natural-language portfolio analysis, trend monitoring, and automated order execution.
+- 📊 **Terminal UI**: Dark-mode Bloomberg-inspired workstation with dynamic price flash animations and sparklines.
 
-Single Docker container serving everything on port 8000:
+## Tech Stack
 
-- **Frontend**: Next.js (static export) with TypeScript and Tailwind CSS
-- **Backend**: FastAPI (Python/uv) with SSE streaming
-- **Database**: SQLite with lazy initialization
-- **AI**: LiteLLM → OpenRouter (Cerebras inference) with structured outputs
-- **Market data**: Built-in GBM simulator (default) or Massive API (optional)
+- **Backend**: Python 3.12+, FastAPI, SQLite, SSE ([`uv`](https://github.com/astral-sh/uv))
+- **Frontend**: Next.js, TypeScript
+- **Integrations**: OpenRouter / LiteLLM, Polygon.io (Massive API)
 
 ## Quick Start
 
+### Backend Setup & Demo
+
 ```bash
-# Clone and configure
-cp .env.example .env
-# Add your OPENROUTER_API_KEY to .env
+cd backend
 
-# Run with Docker
-docker build -t finally .
-docker run -v finally-data:/app/db -p 8000:8000 --env-file .env finally
+# Sync dependencies & run test suite
+uv sync --dev
+uv run pytest
 
-# Open http://localhost:8000
+# Run live market streaming engine demo
+uv run python market_data_demo.py
 ```
 
-## Environment Variables
+### Environment Setup (Optional)
 
-| Variable | Required | Description |
-|---|---|---|
-| `OPENROUTER_API_KEY` | Yes | OpenRouter API key for AI chat |
-| `MASSIVE_API_KEY` | No | Massive (Polygon.io) key for real market data; omit to use simulator |
-| `LLM_MOCK` | No | Set `true` for deterministic mock LLM responses (testing) |
+```bash
+export MASSIVE_API_KEY="your_polygon_api_key"    # Live market data (defaults to internal GBM simulator)
+export OPENROUTER_API_KEY="your_openrouter_key"  # LLM copilot integration
+```
 
 ## Project Structure
 
-```
-finally/
-├── frontend/    # Next.js static export
-├── backend/     # FastAPI uv project
-├── planning/    # Project documentation and agent contracts
-├── test/        # Playwright E2E tests
-├── db/          # SQLite volume mount (runtime)
-└── scripts/     # Start/stop helpers
-```
+- [`backend/`](backend) — FastAPI server, SSE market engine & SQLite database
+- [`frontend/`](frontend) — Next.js trading workstation interface
+- [`planning/`](planning) — Architectural specifications & design documentation
+
+## Key Documentation
+
+- [`PLAN.md`](planning/PLAN.md) — Product specification & architecture overview
+- [`MARKET_DATA_SUMMARY.md`](planning/MARKET_DATA_SUMMARY.md) — Market data subsystem design summary
 
 ## License
 
-See [LICENSE](LICENSE).
+[MIT](LICENSE)
+