# Vibe-Dashboard — Tax Operations Master Doc

The **vibe-dashboard** project is a read-only tax analysis dashboard built on top
of **Vibe-Trading**, which is wired to a real Robinhood brokerage via Robinhood's
official **Agentic Trading MCP** (`https://agent.robinhood.com/mcp/trading`,
read-only `trading.read` scope).

**It is strictly READ-ONLY and LOCAL-ONLY.** The account (476549654) is never
used to place orders, and no snapshot data ever leaves this machine. The dashboard
turns per-lot tax lots + live quotes into an unrealized PnL table focused on
tax-loss-harvesting and profit-taking, snapshots that table to disk on a schedule,
and keeps the schedule running across restarts.

## Live URL(s)

The **tax dashboard itself is a local filesystem + CLI + scheduler project — it has
no web URL.** Its outputs live under `/workspace/vibe-dashboard/data/` (see Layout).

The **upstream system** it reads from is the Vibe-Trading finance research agent,
which *does* have a web UI:

- **Web UI (owner-gated):** `https://vibetrading.raj-trades.bhaiya.keiretsu.top`
  (gateway returns 401 unless you are logged in as the owner)
- Local origin: `http://localhost:8611` (backend binds `0.0.0.0:8611`)
- Underlying FastAPI/React UI from `vibe-trading serve` (port 8180 local)

> The tax dashboard interacts with that system purely through the Robinhood MCP —
> it reads tax lots and quotes, computes PnL locally, and writes local snapshots.

## What the project does

1. **Read** per-lot equity tax lots (`get_equity_tax_lots`) and live quotes
   (`get_equity_quotes`) from the Robinhood agentic MCP for a set of symbols.
2. **Compute** per-lot unrealized PnL, bucketed by **short-term (ST)** vs
   **long-term (LT)**, using the 365-day threshold.
3. **Print** a per-symbol table (see `TAX_METHODOLOGY.md` for the math).
4. **Snapshot** that table to timestamped Markdown files, maintain an `INDEX.md`
   (newest-first), and prune snapshots older than 90 days.
5. **Schedule** the snapshot on a resilient detached daemon (default once daily).

## Directory layout

```
/workspace/vibe-dashboard/
├── docs/                      # THIS documentation
│   ├── README.md              # master operations doc (this file)
│   ├── TAX_METHODOLOGY.md     # tax logic explained
│   └── ROBINHOOD_MCP_DATA.md  # Robinhood MCP data reference + mapping
├── run_tax_snapshot.sh        # scheduled local-only snapshot harness (bash)
├── tax_snapshot.py            # snapshot pipeline (python)
├── schedule/                  # resilient scheduler daemon + control scripts
│   ├── daemon.py              # loop: run harness on start + every N s, never dies
│   ├── start_schedule.sh      # detached launcher (setsid+nohup), writes pidfile
│   ├── stop_schedule.sh       # stops the daemon, clears pidfile
│   ├── status_schedule.sh     # reports running/stopped + last log lines
│   ├── SCHEDULING.md          # full scheduling & resilience reference
│   └── scheduler.pid          # pidfile written by the running daemon
└── data/
    ├── PORTFOLIO_BRIEF.md     # portfolio tax & harvest brief (Raj, acct 476549654)
    ├── equity_tax_lots.json   # raw per-lot tax lots (get_equity_tax_lots)
    ├── options_data.json      # raw option positions (get_option_positions)
    ├── schedule.log           # append-only scheduler tick log
    ├── schedule.out           # daemon stdout/stderr redirect
    └── snapshots/
        ├── INDEX.md           # newest-first index of snapshots
        └── YYYY-MM-DDThhmmss.md  # timestamped per-run tax snapshots
```

Related (outside the dashboard, owned by Vibe-Trading setup):

```
/workspace/bin/vibe-tax-lots          # the read-only tax tool the dashboard wraps
/workspace/bin/vibe-trading           # Vibe-Trading CLI launcher
/workspace/.vibetrading-venv/         # python venv
/workspace/.vibe-trading/agent.json   # Robinhood MCP agent config (enabledTools)
```

## How each piece was built

- **Tax tool — `/workspace/bin/vibe-tax-lots`** — a standalone Python script. It
  imports the installed Vibe-Trading package from the venv, builds a Robinhood MCP
  tool wrapper (`build_mcp_tool_wrappers`) for `get_equity_tax_lots` and
  `get_equity_quotes`, fetches per-lot data + live price per symbol, and prints the
  ST/LT PnL table. See `ROBINHOOD_MCP_DATA.md` for the wrapper pattern.
- **Snapshot pipeline — `tax_snapshot.py`** — invokes the tax tool via subprocess,
  suppresses the known `Session termination failed: 400` stderr noise, wraps the
  table in a timestamped Markdown doc, rebuilds `INDEX.md` from disk, and prunes
  old snapshots. Idempotent and safe on any schedule.
- **Snapshot harness — `run_tax_snapshot.sh`** — a `set -euo pipefail` bash wrapper
  that sets up the runtime env (LD_LIBRARY_PATH, venv python) and `exec`s
  `tax_snapshot.py`. Uses the standalone wrapper, **not** the `vibe-trading` CLI.
- **Scheduler — `schedule/daemon.py`** — a crash-tolerant loop: runs the harness
  immediately on start, then every N seconds (default 86400 = daily). Every run is
  wrapped in `try/except` so failures are logged and the loop continues.
- **Control scripts** — `start_schedule.sh` detaches via `setsid`+`nohup` so it
  survives the launching shell; `status_schedule.sh` reports running/stopped +
  last log; `stop_schedule.sh` stops the daemon and clears the pidfile.

## Prerequisites

- **Python venv:** `/workspace/.vibetrading-venv` (site-packages: python3.12).
  The tax tool prepends
  `/workspace/.vibetrading-venv/lib/python3.12/site-packages` to `sys.path`
  automatically; the snapshot harness calls
  `/workspace/.vibetrading-venv/bin/python` directly.
- **LD_LIBRARY_PATH** (required by numpy/pandas in the tax tool):
  ```bash
  export LD_LIBRARY_PATH="/nix/store/r48746qznwqxxl9qzd8f08ny8mg1dg2y-gcc-15.3.0-lib/lib:/nix/store/zks9mfsn4rqr6z9g6pcj2xqzcsplj0nb-zlib-1.3.2/lib"
  ```
  `run_tax_snapshot.sh` and `tax_snapshot.py` set this themselves, so you only need
  it manually when calling the raw tax tool directly.
- **Robinhood account / env:** account number defaults to `476549654` (from
  `ROBINHOOD_ACCOUNT`, default in the tool). MCP OAuth cache lives at
  `~/.vibe-trading/live/robinhood/oauth`.
- **Host note:** this is a NixOS workspace with **no systemd and no cron daemon**.
  A detached daemon or the Hermes cron scheduler is required for unattended
  scheduling (see `schedule/SCHEDULING.md`).

## Quickstart

### 1) Run the tax tool (one-off, all default symbols)
```bash
export LD_LIBRARY_PATH="/nix/store/r48746qznwqxxl9qzd8f08ny8mg1dg2y-gcc-15.3.0-lib/lib:/nix/store/zks9mfsn4rqr6z9g6pcj2xqzcsplj0nb-zlib-1.3.2/lib"
/workspace/bin/vibe-tax-lots                # all default positions
/workspace/bin/vibe-tax-lots CRWV TSLL      # specific symbols
```
(Or, to avoid the manual LD_LIBRARY_PATH, run it via the snapshot wrapper below.)

### 2) Run a snapshot (writes a timestamped md + rebuilds INDEX.md)
```bash
/workspace/vibe-dashboard/run_tax_snapshot.sh
```

### 3) Start the scheduler (default daily)
```bash
/workspace/vibe-dashboard/schedule/start_schedule.sh            # once daily
/workspace/vibe-dashboard/schedule/start_schedule.sh 21600      # every 6h
/workspace/vibe-dashboard/schedule/status_schedule.sh           # check status
/workspace/vibe-dashboard/schedule/stop_schedule.sh             # stop
```

### Verify a snapshot was written
```bash
ls -t /workspace/vibe-dashboard/data/snapshots/ | head
tail -n 5 /workspace/vibe-dashboard/data/schedule.log
```

---

> This project is informational tooling, **not** tax or investment advice. Always
> confirm tax treatment with a qualified tax professional before executing a harvest.