bmad-dashboard 1.0.16 → 1.0.17

package/README.md

@@ -1,74 +1,79 @@
 # BMAD Dashboard
 
-A **local web dashboard** that shows your [BMAD](https://github.com/caionormando/bmad-dashboard) project state in real time: current phase, artifacts, next steps, and sprint status. Use it from any BMAD project without copying code—run it with **npx** and it reads that project’s `_bmad` and `_bmad-output` automatically.
+A **local web dashboard** that shows your [BMAD](https://github.com/bmad-framework) project state in real time: current phase, artifacts, next steps, and sprint status. Use it from any BMAD project without copying code—run it with **npx** and it reads that project’s `_bmad` and `_bmad-output` automatically.
 
----
+**No database, no auth.** Everything is file-based and local.
 
-## How it works
+---
 
-1. You run **`npx bmad-dashboard`** from **inside a BMAD project** (a folder that has or will have `_bmad/` and `_bmad-output/`).
-2. The dashboard starts a small server and opens a single URL (default **http://localhost:3000**).
-3. The server reads your project’s BMAD config and artifact files and serves a UI that **updates when you change files** (file watcher + live reload), or when you click **Refresh**.
-4. **Project root** is the directory where you ran the command, so the dashboard always reflects **that** project’s state.
+## Features
 
-No database, no auth—everything is file-based and local.
+- **Phase overview** — See where you are in the BMAD workflow (Analysis → Planning → Solutioning → Implementation) and which artifacts exist.
+- **Three views** — **Overview** (phase cards, next steps, artifact details), **Diagram** (workflow with commands and agents), **Kanban** (user stories by status; enabled when you have stories).
+- **Live updates** — The UI refreshes when you change BMAD files (file watcher + SSE). Manual **Refresh** and optional 60s polling fallback.
+- **Next steps** — Recommended BMAD commands with one-click copy (e.g. `/bmad-bmm-create-prd`).
+- **Story details** — Expand epics and stories to see user story text, acceptance criteria, and status from `sprint-status.yaml`.
+- **Light / dark theme** — Theme toggle in the header; preference saved in `localStorage`.
 
 ---
 
-## Requirements
+## Screenshots
+
+*Add PNG/JPEG files to `docs/screenshots/` (see [docs/screenshots/README.md](docs/screenshots/README.md) for naming). The images below will appear once the files exist.*
+
+| Overview | Diagram | Kanban |
+|----------|---------|--------|
+| ![Overview](docs/screenshots/overview.png) | ![Diagram](docs/screenshots/diagram.png) | ![Kanban](docs/screenshots/kanban.png) |
+
+*Overview: phase progress, artifacts, next steps. Diagram: workflow phases and commands. Kanban: stories by status.*
 
-- **Node.js** 18+ (or 20+ recommended)
-- A **BMAD project**: a folder that contains (or will contain) a `_bmad/` setup and optionally `_bmad-output/` (e.g. `prd.md`, `architecture.md`, `epics.md`, `sprint-status.yaml`)
+**Story detail (click a card in Kanban):**
+
+![Story detail](docs/screenshots/story-detail.png)
 
 ---
 
-## Run in another project (step by step)
+## Requirements
 
-This is the main way to use the dashboard after installing from npm.
+- **Node.js** 18+ (20+ recommended)
+- A **BMAD project**: a folder that contains (or will contain) `_bmad/` and optionally `_bmad-output/` (e.g. `prd.md`, `architecture.md`, `epics.md`, `sprint-status.yaml`).
 
-### Step 1: Open your BMAD project
+---
 
-Open a terminal and go to the **root of the BMAD project** you want to inspect (the folder that has or will have `_bmad/` and `_bmad-output/`).
+## Quick start
+
+### 1. Open your BMAD project
 
 ```bash
 cd /path/to/your-bmad-project
 ```
 
-Example: `cd ~/projects/my-app` (where `my-app` is your BMAD project).
-
-### Step 2: Run the dashboard
-
-From that folder, run:
+### 2. Run the dashboard
 
 ```bash
 npx bmad-dashboard
 ```
 
-- The first time, npm will download the package (you may see a short install).
-- The server starts and prints something like: `BMAD dashboard at http://localhost:3000` and `Project root: /path/to/your-bmad-project`.
-
-### Step 3: Open the dashboard in your browser
+You’ll see something like: `BMAD dashboard at http://localhost:3000` and `Project root: /path/to/your-bmad-project`.
 
-Open:
+### 3. Open in the browser
 
-**http://localhost:3000**
+Open **http://localhost:3000**. You’ll see the project name, phase progress, artifact checklist, next steps, and (if present) sprint status.
 
-You should see:
+- **Overview** — Phase cards, next steps bar, and expandable artifact details (steps, acceptance criteria, commands).
+- **Diagram** — Visual workflow: phases, artifacts, commands, and agents.
+- **Kanban** — Enabled when user stories exist; columns by status (Backlog, Ready for dev, In progress, Review, Done). Click a card to see user story and acceptance criteria.
 
-- Project name (from your BMAD config)
-- Phase progress (Analysis → Planning → Solutioning → Implementation)
-- Artifacts checklist (PRD, Architecture, Epics, UX, Sprint status)
-- “What’s inside each artifact” (expand to see steps, acceptance criteria, commands)
-- Next steps (suggested BMAD commands)
-- Sprint status table (if you have `sprint-status.yaml`)
+To stop: **Ctrl+C** in the terminal.
 
-### Step 4: Use it
+---
 
-- The page **refreshes automatically** when BMAD artifact or config files change (e.g. after saving prd.md, sprint-status.yaml). If the live connection is unavailable, it falls back to polling every 60 seconds.
-- Click **Refresh** in the header to update immediately.
-- Expand artifacts to see source file paths, BMAD commands, and step-by-step progress.
+## How it works
 
-To stop the dashboard: press **Ctrl+C** in the terminal.
+1. You run **`npx bmad-dashboard`** from **inside a BMAD project** (a folder that has or will have `_bmad/` and `_bmad-output/`).
+2. The dashboard starts a small server and serves the UI at **http://localhost:3000** (or the port you set).
+3. The server reads your project’s BMAD config and artifact files and serves a UI that **updates when you change files** (file watcher + live reload), or when you click **Refresh**.
+4. **Project root** is the directory where you ran the command, so the dashboard always reflects **that** project’s state.
 
 ---
 
@@ -79,14 +84,15 @@ To stop the dashboard: press **Ctrl+C** in the terminal.
 | **Phase progress** | Current BMAD phase and which phases are done (from your artifacts). |
 | **Artifacts** | Checklist: PRD, Architecture, Epics & stories, UX design, Sprint status (✓ = file exists). |
 | **What’s inside each artifact** | Expand to see source path, commands that build it, and for PRD/Architecture the list of steps (done/pending); for Epics/Sprint, stories with acceptance criteria and status. |
-| **Next steps** | Recommended BMAD workflows with the exact Cursor command (e.g. `/bmad-bmm-create-prd`). |
+| **Next steps** | Recommended BMAD workflows with the exact Cursor command (e.g. `/bmad-bmm-create-prd`). Click to copy. |
 | **Sprint status** | Table of story/epic IDs and status from `_bmad-output/implementation-artifacts/sprint-status.yaml`. |
+| **Kanban** | Stories grouped by status; click a card for user story and acceptance criteria. |
 
 ---
 
-## Other ways to run it
+## Other ways to run
 
-### Use a different port
+### Different port
 
 ```bash
 PORT=4000 npx bmad-dashboard
@@ -94,19 +100,15 @@ PORT=4000 npx bmad-dashboard
 
 Then open **http://localhost:4000**.
 
-### Point at another project (without changing directory)
+### Different project (without changing directory)
 
 ```bash
 BMAD_PROJECT_ROOT=/path/to/other-bmad-project npx bmad-dashboard
 ```
 
-The dashboard will use that path as the project root instead of the current directory.
-
-### Run from a local clone (without npm)
+### From a local clone (no npm install of the package)
 
-If you cloned the repo and want to run from the clone:
-
-1. Build once (in the clone):
+1. Build once in the clone:
 
    ```bash
    cd /path/to/bmad-dashboard/dashboard
@@ -127,16 +129,17 @@ If you cloned the repo and want to run from the clone:
 
 | Problem | What to do |
 |--------|------------|
-| **“Could not load BMAD state”** | The server didn’t start or isn’t reachable. Make sure you ran `npx bmad-dashboard` from your project folder and that nothing is blocking port 3000. |
-| **Port 3000 already in use** | Stop the other process or use another port: `PORT=3001 npx bmad-dashboard`, then open http://localhost:3001. On macOS/Linux you can find the process with `lsof -i :3000` and stop it with `kill <PID>`. |
+| **“Could not load BMAD state”** | The server didn’t start or isn’t reachable. Run `npx bmad-dashboard` from your project folder and ensure nothing is blocking the port (default 3000). |
+| **Port 3000 already in use** | Use another port: `PORT=3001 npx bmad-dashboard`, then open http://localhost:3001. On macOS/Linux: `lsof -i :3000` then `kill <PID>`. |
 | **Dashboard is empty or “no artifact details”** | Your project may not have `_bmad/` or `_bmad-output/` yet. Run BMAD workflows (e.g. Create PRD) in Cursor to generate artifacts; the dashboard will show them after the next refresh. |
-| **Wrong project shown** | You ran `npx bmad-dashboard` from a different folder. `cd` to the correct BMAD project root and run the command again, or use `BMAD_PROJECT_ROOT=/correct/path npx bmad-dashboard`. |
+| **Wrong project shown** | You ran the command from a different folder. `cd` to the correct BMAD project root and run again, or use `BMAD_PROJECT_ROOT=/correct/path npx bmad-dashboard`. |
+| **Acceptance criteria not showing** | Ensure your `epics.md` has a section like **Acceptance Criteria:** with list items (e.g. `- **Given** ...`). The parser supports several header and list formats. |
 
 ---
 
 ## Development (for contributors)
 
-If you work on the dashboard itself (inside this repo):
+To work on the dashboard itself (in this repo):
 
 ```bash
 cd dashboard
@@ -144,11 +147,36 @@ npm install
 npm run dev
 ```
 
-Then open **http://localhost:5173**. The API runs on port 3000; Vite proxies `/api` to it.
-
+- **App:** http://localhost:5173 (Vite). The API runs on port 3000; Vite proxies `/api` to it.
 - **Tests:** `npm run test` (single run), `npm run test:watch` (watch).
+- **Lint:** `npm run lint`, `npm run lint:fix`.
 - **Build:** `npm run build` (output in `dist/`).
-- **Project structure:** Server in `server/` (config, fileUtils, constants, bmadState, artifactDetails, routes); frontend in `src/` (constants, hooks, components, App).
+
+**Structure:** Server in `server/` (config, fileUtils, constants, bmadState, artifactDetails, routes, fileWatch); frontend in `src/` (constants, hooks, components, App).
+
+---
+
+## Testing UI locally (no publish)
+
+You don’t need to publish to npm to try UI changes. This repo is a BMAD project: it has `_bmad/` and `_bmad-output/` at the repo root.
+
+1. **From the repo root**, open a terminal in the **`dashboard/`** directory:
+   ```bash
+   cd dashboard
+   npm install
+   npm run dev
+   ```
+2. The API server resolves **project root** to the **parent of `dashboard/`** (i.e. the bmad-dashboard repo root) when not run as an installed package. So it will load this repo’s `_bmad-output/planning-artifacts/`, `sprint-status.yaml`, etc.
+3. Open **http://localhost:5173** (Vite). You’ll see the dashboard with real data from this repo: PRD, Architecture, Epics, Kanban (if sprint status exists), and all three views (Overview, Diagram, Kanban).
+4. Edit React/CSS in `src/`, save; Vite hot-reloads. Edit artifacts in `_bmad-output/`; the file watcher will refresh the API and the UI will update.
+
+To use **another** BMAD project’s data without changing directory, run the dev server with:
+
+```bash
+BMAD_PROJECT_ROOT=/path/to/other-bmad-project npm run dev:server
+```
+
+Then run the client in another terminal (`npm run dev:client` in `dashboard/`). The API will read from `other-bmad-project`.
 
 ---
 
@@ -156,12 +184,15 @@ Then open **http://localhost:5173**. The API runs on port 3000; Vite proxies `/a
 
 On every **push to `main`**, GitHub Actions:
 
-1. Runs tests and build in the `dashboard/` directory.
-2. If tests pass, bumps the **patch** version (e.g. `1.0.9` → `1.0.10`), publishes to npm via **Trusted Publishers (OIDC)**, and commits the version bump back to `main` (with message `chore(release): 1.0.10 [skip ci]` so the release commit does not trigger another publish).
+1. Runs tests and lint in `dashboard/`.
+2. If they pass, bumps the **patch** version, publishes to npm (using `NPM_TOKEN` or Trusted Publishers), and commits the version bump to `main` with `chore(release): X.Y.Z [skip ci]`.
+3. Creates a **GitHub Release** for the new version (tag `vX.Y.Z`) only when publish and push succeed.
 
-**Setup (one-time), either:** **Option A — Granular token (recommended):** Create a [Granular access token](https://docs.npmjs.com/about-access-tokens) on npm with **read and write** access for this package and **Bypass 2FA** enabled. Add it as repo secret **`NPM_TOKEN`** under **Settings** → **Secrets and variables** → **Actions**. **Option B — Trusted Publishers (OIDC):** Link npm to GitHub and set Trusted publishing for this package (workflow `release.yml`) on npmjs.com; leave `NPM_TOKEN` unset. The workflow file is `.github/workflows/release.yml`.
+**Setup (one-time):**  
+**Option A — Granular token:** Create a [Granular access token](https://docs.npmjs.com/about-access-tokens) on npm with **read and write** and **Bypass 2FA**. Add it as repo secret **`NPM_TOKEN`** (Settings → Secrets and variables → Actions).  
+**Option B — Trusted Publishers (OIDC):** Link npm to GitHub and set Trusted publishing for this package (workflow in `.github/workflows/release.yml`) on npmjs.com; leave `NPM_TOKEN` unset.
 
-**If OIDC gives 404 on publish:** The package must exist on npm before you can add a Trusted Publisher (you configure it in the package’s Settings). If [npmjs.com/package/bmad-dashboard](https://www.npmjs.com/package/bmad-dashboard) returns 404, do **one manual publish** from your machine: `cd dashboard && npm login && npm publish --access public` (enter OTP when prompted). After that, add the Trusted Publisher for `release.yml` in the package settings; then CI can publish future versions.
+If the package doesn’t exist on npm yet, do one manual publish from your machine (`cd dashboard && npm publish --access public`), then configure the chosen option.
 
 ---