feat(web): app shell routes, static build, timeline refresh after mut…

.cursor/rules/flightdeck-ci-artifacts.mdc

@@ -0,0 +1,27 @@
+---
+description: FlightDeck — commit web static bundle and regenerated schemas CI enforces
+alwaysApply: true
+---
+
+# FlightDeck CI artifacts
+
+Normative detail: **`AGENTS.md`** (Verification), **`CLAUDE.md`**, **`CONTRIBUTING.md`**, **`DEVELOPMENT.md`**. Repo root **`.cursorrules`** defers here for Cursor users without rules UI. CI mirrors **`.github/workflows/ci.yml`**; PR checklist: **`.github/PULL_REQUEST_TEMPLATE.md`**.
+
+## Web UI (`web/` → `src/flightdeck/server/static/`)
+
+`flightdeck serve` serves the **checked-in** tree under **`src/flightdeck/server/static/`**, not a live Vite output.
+
+If the PR touches **`web/`** in a way that changes the production build (TS/TSX/CSS, **`vite.config.ts`**, **`web/package.json`** / lockfile, etc.):
+
+1. From **`web/`**: **`npm ci`** then **`npm run build`** (writes into **`src/flightdeck/server/static/`** and normalizes LF).
+2. From repo root: **`git diff --exit-code src/flightdeck/server/static/`** must pass—if not, **commit all** changes under that path (hashed **`assets/*.js`**, **`index.html`** script tags, etc.).
+3. If behavior changed, from **`web/`**: **`npm run test:e2e`**.
+
+## JSON Schemas (`schemas/`)
+
+If Pydantic models or generation scripts change wire contracts:
+
+1. **`uv run python scripts/generate_schemas.py`**
+2. **`git diff --exit-code schemas/`** must pass—commit **`schemas/`** updates with the same PR.
+
+Do not hand-edit generated schema files without running the script.

.cursorrules

@@ -1,7 +1,7 @@
 # FlightDeck — Cursor
 
-Read **`AGENTS.md`** for mission, non-goals, public contracts, engineering rules, verification, and docs policy. **`CLAUDE.md`** is a short index for Claude Code / Cursor.
+Read **`AGENTS.md`** for mission, non-goals, public contracts, engineering rules, verification, and docs policy. **`CLAUDE.md`** is a short index for Claude Code / Cursor. In Cursor, **`.cursor/rules/flightdeck-ci-artifacts.mdc`** (`alwaysApply`) reminds you to commit **`src/flightdeck/server/static/`** and **`schemas/`** when CI gates apply.
 
-Quick verify (uv): `uv sync --frozen --extra dev`, then `uv run python -m ruff check src tests`, `uv run python -m pytest`, `uv run flightdeck-quickstart-verify` (pip/venv equivalents in `DEVELOPMENT.md`; on Windows, `py -3` if needed). After **`web/src/`** edits: `cd web && npm ci && npm run build`, commit **`src/flightdeck/server/static/`** if it changes; optionally `npm run test:e2e` (see **`web/README.md`**).
+Quick verify (uv): `uv sync --frozen --extra dev`, then `uv run python -m ruff check src tests`, `uv run python -m pytest`, `uv run flightdeck-quickstart-verify`, `uv run flightdeck --help` (pip/venv equivalents in **`DEVELOPMENT.md`**; on Windows, **`py -3`** if needed). After **Pydantic / wire model** edits: `uv run python scripts/generate_schemas.py` then `git diff --exit-code schemas/`. After **`web/`** edits that affect the production bundle: `cd web && npm ci && npm run build && cd .. && git diff --exit-code src/flightdeck/server/static/` (must be clean—commit all changes under **`static/`**); when UI behavior changes, `cd web && npx playwright install chromium && npm run test:e2e` (see **`web/README.md`**).
 
 Normative v1 direction: https://github.com/flightdeckdev/flightdeck/blob/main/RELEASE_NOTES.md · backlog: https://github.com/flightdeckdev/flightdeck/blob/main/ROADMAP.md · CLI: https://github.com/flightdeckdev/flightdeck/blob/main/README.md

.github/PULL_REQUEST_TEMPLATE.md

@@ -6,13 +6,13 @@
 
 ## Validation
 
-Run the same checks as **CI** (see **`.github/workflows/ci.yml`**) before opening / updating the PR:
+Run the same checks as **CI** (see **`.github/workflows/ci.yml`**) before opening / updating the PR. Cursor loads **`.cursor/rules/flightdeck-ci-artifacts.mdc`** as a short reminder for **`static/`** + **`schemas/`** gates.
 
 - [ ] `uv sync --frozen --extra dev`
 - [ ] `uv run python -m ruff check src tests`
 - [ ] `uv run python -m pytest`
 - [ ] `uv run python scripts/generate_schemas.py` then `git diff --exit-code schemas/` (if models/schemas touched)
-- [ ] `cd web && npm ci && npm run build && cd .. && git diff --exit-code src/flightdeck/server/static/` (if **`web/src/`** or deps changed)
+- [ ] `cd web && npm ci && npm run build && cd .. && git diff --exit-code src/flightdeck/server/static/` (if **`web/`** sources, Vite config, or **`web/`** deps / lockfile change the production bundle)
 - [ ] `cd web && npx playwright install chromium && npm run test:e2e` (if **`web/`** changed)
 - [ ] `uv run flightdeck-quickstart-verify`
 - [ ] `uv run flightdeck --help`

AGENTS.md

@@ -8,7 +8,7 @@ This tree is usually a **personal-account research repo** (`origin` → your Git
 
 When implementing features, prefer **small, PR-shaped slices** that could ship to an org repo without extra cleanup. Do not conflate “saved in research” with “ready for org push.”
 
-Extended maintainer docs (research workflow, org checklist, canonical publish) live on **`main`** in that repository. This clone stays compact and keeps practical contributor guidance in **`CONTRIBUTING.md`**. Claude Code / short entrypoint: **`CLAUDE.md`**.
+Extended maintainer docs (research workflow, org checklist, canonical publish) live on **`main`** in that repository. This clone stays compact and keeps practical contributor guidance in **`CONTRIBUTING.md`**. Claude Code / short entrypoint: **`CLAUDE.md`**. Cursor IDE: project rules under **`.cursor/rules/`** (for example **`flightdeck-ci-artifacts.mdc`** for web static + schema gates).
 
 ## Mission
 
@@ -56,6 +56,7 @@ Treat these as **stable API** unless a change explicitly marks an experimental p
 Do a short review pass for:
 
 - **Contract drift** (CLI, JSON/YAML, SQLite columns consumers rely on).
+- **Shipped web bundle** (**`web/`** → committed **`src/flightdeck/server/static/`**) and **schema drift** (**`schemas/`**, regenerate via Verification below) when your change touches UI or Pydantic wire shapes.
 - **Trust boundaries** (diff, pricing, policy, promotion, serve host binding).
 - **Cross-platform ergonomics** (Windows paths, line endings on fixtures, temp dirs).
 
@@ -68,6 +69,7 @@ uv sync --frozen --extra dev
 uv run python -m ruff check src tests
 uv run python -m pytest
 uv run flightdeck-quickstart-verify
+uv run flightdeck --help
 ```
 
 After editing Pydantic models, regenerate schemas and ensure a clean diff:
@@ -77,6 +79,18 @@ uv run python scripts/generate_schemas.py
 git diff --exit-code schemas/
 ```
 
+After editing the **browser UI** under **`web/`** (for example **`web/src/`**), rebuild the committed static tree that **`flightdeck serve`** ships, then confirm CI’s static gate is clean (same check as **`.github/workflows/ci.yml`**):
+
+```bash
+cd web
+npm ci
+npm run build
+cd ..
+git diff --exit-code src/flightdeck/server/static/
+```
+
+Commit every change under **`src/flightdeck/server/static/`** (including new hashed **`assets/*.js`** and **`index.html`** script tags). **`npm run build`** already runs LF normalization via **`web/scripts/normalize-static-lf.mjs`**. For UI behavior, run **`npm run test:e2e`** from **`web/`** (Playwright runs in CI right after the static diff).
+
 Fallback (activated **venv** or global tools): the same steps with **`python -m …`** / **`python scripts/…`** as in **`DEVELOPMENT.md`**.
 
 On **Windows**, use `py -3` in place of `python` if that is how your environment is set up. If pytest temp dirs fail with permissions, see **`DEVELOPMENT.md`** / **`tests/conftest.py`**.

CHANGELOG.md

@@ -23,7 +23,7 @@ This project follows [Semantic Versioning](https://semver.org/). From **v1.0.0**
 - **Docs:** README deduplicates **RELEASE_NOTES** links; **CHANGELOG** historic bullets use canonical **`https://github.com/flightdeckdev/flightdeck/...`** URLs for **`docs/*`** and **RESEARCH.md** (this slim tree does not ship those files).
 - **`tests/conftest.py`:** create repo **`.tmp/`** at import time so **`pytest --basetemp=.tmp/pytest`** works on fresh checkouts and **Linux** CI (parent dir is no longer Windows-only).
 - **`pyproject.toml` `[project] name`:** **`flightdeck-ai`** to match the **PyPI** trusted-publisher project; install with **`pip install flightdeck-ai`** / **`uv add flightdeck-ai`** (CLI remains **`flightdeck`**, imports **`flightdeck.*`**).
-- **Contributor docs** (**`README.md`**, **`DEVELOPMENT.md`**, **`CONTRIBUTING.md`**, **`AGENTS.md`**, **`CLAUDE.md`**, **`.cursorrules`**): prefer **uv**; keep **pip** / **`python -m venv`** as fallback.
+- **Contributor docs** (**`README.md`**, **`DEVELOPMENT.md`**, **`CONTRIBUTING.md`**, **`AGENTS.md`**, **`CLAUDE.md`**, **`.cursorrules`**, **`.github/PULL_REQUEST_TEMPLATE.md`**, **`web/README.md`**): prefer **uv**; document full CI parity (**`uv sync --frozen`**, **`flightdeck --help`**, **`schemas/`** + **`src/flightdeck/server/static/`** **`git diff --exit-code`** gates, Playwright when **`web/`** changes). Added **`.cursor/rules/flightdeck-ci-artifacts.mdc`** (Cursor **`alwaysApply`**). Keep **pip** / **`python -m venv`** as fallback.
 - **Python:** **`requires-python >=3.14,<3.15`**, **`.python-version`**, PyPI classifiers, **Ruff** `target-version`, **`uv.lock`**, and **CI** matrices now target **CPython 3.14** only (replacing broader **3.11–3.14** testing).
 
 ## 1.0.1 - 2026-05-01

CLAUDE.md

@@ -9,6 +9,7 @@ Canonical repository (full history and maintainer workflows): **[github.com/flig
 | Topic | Location |
 |--------|------|
 | Agent / contributor rules | `AGENTS.md` |
+| Cursor IDE rules (CI artifacts, web static) | `.cursor/rules/flightdeck-ci-artifacts.mdc` |
 | Setup and local demo | `DEVELOPMENT.md` |
 | CLI flags and exit codes | [README.md](https://github.com/flightdeckdev/flightdeck/blob/main/README.md) (canonical repo) |
 | v1 direction | [RELEASE_NOTES.md](https://github.com/flightdeckdev/flightdeck/blob/main/RELEASE_NOTES.md) |
@@ -27,12 +28,19 @@ uv sync --frozen --extra dev
 uv run python -m ruff check src tests
 uv run python -m pytest
 uv run flightdeck-quickstart-verify
+uv run flightdeck --help
 ```
 
+If you changed **Pydantic / wire models** affecting **`schemas/`**: **`uv run python scripts/generate_schemas.py`**, then **`git diff --exit-code schemas/`** must be clean—commit **`schemas/`** updates with the PR.
+
+If you changed **`web/`** (React UI): from **`web/`**, run **`npm ci`** then **`npm run build`**, then from the repo root **`git diff --exit-code src/flightdeck/server/static/`** must be clean—commit all updates under that path (CI fails otherwise). When behavior changes, run **`npm run test:e2e`** from **`web/`**.
+
+Details: **`AGENTS.md`** (Verification), **`DEVELOPMENT.md`**, and **`.cursor/rules/flightdeck-ci-artifacts.mdc`**.
+
 With **pip** + venv: use **`python -m …`** equivalents in **`DEVELOPMENT.md`**.
 
 **Windows:** if `python` is not on `PATH`, use `py -3` for the same commands (or install **uv** and use **`uv run`**).
 
 ## Repo shape
 
-Python package under `src/flightdeck/`. Tests in `tests/`. Examples in `examples/quickstart/`. JSON Schemas under `schemas/` (regenerate with **`uv run python scripts/generate_schemas.py`** when models change). After **`pyproject.toml`** dependency edits, run **`uv lock`** and commit **`uv.lock`**.
+Python package under `src/flightdeck/`. Tests in `tests/`. Examples in `examples/quickstart/`. JSON Schemas under `schemas/` (regenerate with **`uv run python scripts/generate_schemas.py`** when models change). Browser UI source in **`web/`**; production bundle committed under **`src/flightdeck/server/static/`** (rebuild with **`npm run build`** in **`web/`**). After **`pyproject.toml`** dependency edits, run **`uv lock`** and commit **`uv.lock`**.

CONTRIBUTING.md

@@ -4,7 +4,7 @@ FlightDeck is **v1.0.0+** on a narrow local-first spine; changes should meet pro
 
 Contributions are accepted under the **Apache License, Version 2.0** (see **`LICENSE`**). The canonical tree is [github.com/flightdeckdev/flightdeck](https://github.com/flightdeckdev/flightdeck).
 
-Human and AI contributors: follow **[AGENTS.md](AGENTS.md)** (full rules). For a short index, see **[CLAUDE.md](CLAUDE.md)**.
+Human and AI contributors: follow **[AGENTS.md](AGENTS.md)** (full rules). For a short index, see **[CLAUDE.md](CLAUDE.md)**. In **Cursor**, the project rule **[`.cursor/rules/flightdeck-ci-artifacts.mdc`](.cursor/rules/flightdeck-ci-artifacts.mdc)** (`alwaysApply`) summarizes the **web `static/`** and **`schemas/`** drift gates CI enforces.
 
 ## Local Setup
 
@@ -23,12 +23,14 @@ python -m pip install -e ".[dev]"
 
 ## Verify
 
-With **uv** (matches CI):
+With **uv** (core Python checks; see **`.github/workflows/ci.yml`** for the full job):
 
 ```bash
+uv sync --frozen --extra dev
 uv run python -m ruff check src tests
 uv run python -m pytest
 uv run flightdeck-quickstart-verify
+uv run flightdeck --help
 ```
 
 With an activated **venv**:
@@ -37,9 +39,17 @@ With an activated **venv**:
 python -m ruff check src tests
 python -m pytest
 flightdeck-quickstart-verify
+flightdeck --help
 ```
 
-If you change **`pyproject.toml`** dependencies, run **`uv lock`** and commit **`uv.lock`**. Use the same checks as **CI** (see **`AGENTS.md`**) before opening a PR.
+If you change **`pyproject.toml`** dependencies, run **`uv lock`** and commit **`uv.lock`**.
+
+**Also run before a PR** (when relevant—same gates as CI):
+
+- **Schemas:** `uv run python scripts/generate_schemas.py` then `git diff --exit-code schemas/`
+- **Web UI:** `cd web && npm ci && npm run build && cd .. && git diff --exit-code src/flightdeck/server/static/`; if UI behavior changed, `cd web && npx playwright install chromium && npm run test:e2e`
+
+Details, Windows notes, and doctrine: **`AGENTS.md`** (Verification), **`DEVELOPMENT.md`**, **`web/README.md`**.
 
 ## Private files and pushing to GitHub
 

DEVELOPMENT.md

@@ -34,6 +34,7 @@ python -m pip install -e ".[dev]"
 With **uv**:
 
 ```bash
+uv sync --frozen --extra dev
 uv run python -m ruff check src tests
 uv run python -m pytest
 uv run flightdeck --help
@@ -51,8 +52,17 @@ flightdeck doctor
 flightdeck-quickstart-verify
 ```
 
+Match **CI**’s CLI smoke: **`flightdeck --help`** must run successfully after changes to the CLI surface.
+
 Full command flags and exit codes: [README.md](https://github.com/flightdeckdev/flightdeck/blob/main/README.md). Cross-platform quickstart parity: **`flightdeck-quickstart-verify`** / **`python -m flightdeck.quickstart_smoke`** (also run in CI). HTTP API reference: **[docs/http-api.md](docs/http-api.md)**. Python SDK: **[docs/sdk.md](docs/sdk.md)**.
 
+**JSON Schemas:** when **`src/flightdeck/`** models or **`scripts/generate_schemas.py`** change wire contracts, regenerate and match CI:
+
+```bash
+uv run python scripts/generate_schemas.py
+git diff --exit-code schemas/
+```
+
 **Lockfile:** when you change **`pyproject.toml`** dependencies or extras, run **`uv lock`** and commit **`uv.lock`** so CI stays **`--frozen`**-reproducible.
 
 ## Web UI (React + Vite)
@@ -64,9 +74,11 @@ cd web
 npm ci
 npm run build
 cd ..
-git status src/flightdeck/server/static/
+git diff --exit-code src/flightdeck/server/static/
 ```
 
+If that **`git diff`** fails, **`git add`** / commit everything under **`src/flightdeck/server/static/`** (hashed **`assets/*.js`**, **`index.html`**, etc.)—CI uses the same check after **`npm run build`**.
+
 **Playwright:** from **`web/`**, **`npx playwright install chromium`** once, then **`npm run test:e2e`** (matches CI after the **`static/`** diff gate; see **`web/README.md`**).
 
 **`npm run dev`:** proxies **`/v1`** to **`flightdeck serve`** on **`127.0.0.1:8765`** by default; copy **`web/.env.example`** to **`web/.env.local`** to set **`VITE_FLIGHTDECK_LOCAL_API_TOKEN`** when testing mutations against a token-protected server.

README.md

@@ -130,8 +130,11 @@ uv sync --frozen --extra dev
 uv run python -m ruff check src tests
 uv run python -m pytest
 uv run flightdeck-quickstart-verify
+uv run flightdeck --help
 ```
 
+If you change **`web/`** or **Pydantic models**, also run the **`static/`** and **`schemas/`** drift checks from **[DEVELOPMENT.md](DEVELOPMENT.md)** (same gates as **`.github/workflows/ci.yml`**). **[AGENTS.md](AGENTS.md)** and **[`.cursor/rules/flightdeck-ci-artifacts.mdc`](.cursor/rules/flightdeck-ci-artifacts.mdc)** summarize them for humans and Cursor.
+
 See [DEVELOPMENT.md](DEVELOPMENT.md) for **uv** and **pip** setup, verification, troubleshooting, and **PyPI releases** (tag-driven; not on merge to `main`).
 
 ## License