bunqueue-dashboard 0.0.14

package/CHANGELOG.md

@@ -0,0 +1,315 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+The version is owned by `package.json` (starting at `0.0.1`) and bumped on every
+push to `main`; `.github/workflows/release.yml` tags and publishes `v<version>`
+to match.
+
+**Process (see `CLAUDE.md`):** before every push to `main`, record changes under
+`## [Unreleased]` and bump `package.json`'s `version`. For every version, rename
+`[Unreleased]` to the bumped version and start a fresh empty `[Unreleased]`. The
+release workflow publishes the matching version section (or `[Unreleased]`) as
+the GitHub Release body.
+
+## [Unreleased]
+
+## [0.0.14] - 2026-07-03
+
+### Added
+- **npm package: `bunx bunqueue-dashboard`.** The dashboard is now publishable
+  to npm as a Bun-first CLI: one command serves the prebuilt SPA, proxies
+  `/api/*` to the bunqueue server, and runs the control agent — the same
+  `scripts/serve.ts` the standalone binaries compile, running uncompiled
+  (verified: SPA, history fallback, proxy, and agent all answer from a tarball
+  install). The tarball ships `dist/` + the agent + the embed manifest only;
+  runtime dependencies are down to `pino`/`pino-pretty` (the UI libraries are
+  build-time and moved to devDependencies). `release.yml` gains an idempotent
+  `npm` job: it publishes with `--provenance` iff the `NPM_TOKEN` secret is set
+  and the version isn't already on the registry — a missing secret or an
+  un-bumped version is a clean skip, never a failure.
+
+## [0.0.13] - 2026-07-03
+
+### Fixed
+- **A page opened in a background tab no longer sits on "Loading…" forever.**
+  `usePolledData` paused polling while the tab was hidden — including the very
+  first fetch, so a cmd-clicked tab showed a permanent spinner (and the sidebar
+  a permanent "connecting") until focused. The first fetch now always runs;
+  only the recurring refreshes pause with the Page Visibility API.
+- **Overview / Metrics / Usage / Jobs no longer report 0 completed jobs after a
+  server restart.** Their Completed / Failed cards and error rates read the
+  `totalCompleted`/`totalFailed` session counters (zeroed on every restart,
+  labeled "all time") while the queues visibly held thousands of completed
+  jobs. They now read the recorded counts (`stats.completed` + per-queue failed
+  sums from `/queues/summary`); the counters that really are per-session
+  (pushed/pulled) are now labeled "since restart", and Diagnostics' "Lifetime
+  totals" card is renamed "Totals since restart".
+- **"100.00% success rate" is no longer claimed over zero processed jobs.**
+  Error/success rates render an em dash until at least one job has completed
+  or failed (`errorRate` now returns `null` for an empty denominator).
+- **Jobs Explorer stat cards no longer flash hard zeros while loading** — they
+  show placeholders until the overview poll arrives, and the Total card is
+  labeled "all queues" so the global numbers aren't read as the selected
+  queue's.
+- **Process logs (Server page) no longer show raw ANSI escape codes** — the
+  bunqueue banner's `[1m…[0m` color noise is stripped from display, search,
+  copy, and download (new `stripAnsi` in `lib/format.ts`).
+- **Environment-variable rows (Server page) get a usable value field.** The
+  KEY input swallowed the whole row and the value input collapsed to a sliver:
+  `Input` always carries `w-full` and `cn()` does no Tailwind conflict
+  resolution, so the `w-2/5`/`flex-1` passed by the editor lost to it. Widths
+  now live on wrapper divs.
+
+### Changed
+- **Dead Letter Queue auto-selects the biggest non-empty queue** on first load
+  (like DLQ Control) instead of parking on a "Select a queue" prompt.
+- **Flows remembers the flows you've viewed** (locally, up to 8) and offers
+  them as one-click chips in the empty state — bunqueue has no "list flows"
+  endpoint, so this replaces a dead end with a way back in.
+
+## [0.0.12] - 2026-07-03
+
+### Added
+- **Animated product tour.** A roughly 50-second guided tour on the README (an
+  optimized GIF) and on the docs home (an autoplaying, muted, looping MP4, a far
+  lighter video so it does not slow the home page), clicking through the
+  overview, queues, jobs, the dead-letter queue, flows, the SQLite inspector,
+  and the AI Copilot.
+
+## [0.0.11] - 2026-07-03
+
+### Added
+- **Copilot (experimental): an in-dashboard AI assistant.** A chat panel (the
+  button in the bottom right) that reads your live queue state and can propose
+  actions you confirm before they run. Bring your own model via the Vercel AI
+  SDK: Claude (Anthropic), ChatGPT (OpenAI), Gemini (Google), GLM (Z.ai),
+  OpenRouter (one key for every model), or any OpenAI-compatible endpoint
+  (Groq, Together, a local Ollama or LM Studio). Your API key stays in memory
+  for the session only and is never written to disk; the provider and model are
+  remembered. Read tools (queues, jobs, DLQ, workers, crons, health) run
+  immediately; mutating tools (retry, promote, remove, pause/resume, retry/purge
+  DLQ) are gated behind an explicit in-chat confirmation. The whole panel plus
+  the AI SDK (~165 KB gz) is lazy-loaded, so it adds nothing to the initial
+  bundle. New `docs/guide/copilot` page.
+
+### Changed
+- **Bundle budget now measures the INITIAL load, not every chunk.** The
+  `bun run size` gate reads Vite's build manifest and sums the entry chunk plus
+  its static imports (currently ~91 KB gz, budget 230 KB), so lazily-loaded
+  features (the demo shim, the Copilot) no longer count against it. A separate,
+  generous cap on the grand total still guards against a runaway dependency.
+
+## [0.0.10] - 2026-07-03
+
+### Added
+- **Flows: an interactive job-flow DAG.** A new page that draws a job flow as a
+  graph, parent to children (solid edges) and dependency edges (dashed), with
+  every node coloured by state. Paste any job ID (or use the new **View flow**
+  link in the Job Inspector); the page climbs `parentId` to the flow's root, then
+  walks `childrenIds` and `dependsOn` client-side (bunqueue has no single
+  "get whole flow" endpoint), lays it out with a pure, unit-tested layered-layout
+  engine, and lets you click any node to inspect it. 100% frontend, no graph
+  library. Demo mode ships a sample flow so the page is populated out of the box.
+  New "Flows" nav item (Queues) and a `docs/guide/flows` page.
+
+### Changed
+- **Full-width pages.** Add Job and Settings now fill the content width with a
+  two-column layout instead of a narrow centred column, and the Job Inspector
+  lookup bar spans the width.
+
+### Fixed
+- **Classic DLQ page no longer crashes.** It rendered the job's `attempts` field
+  directly, but the verified DLQ-entry shape makes `attempts` an array, so React
+  threw "Objects are not valid as a React child" (a white screen) against both a
+  real server and the demo. It now shows the attempt count, and the row key no
+  longer relies on a missing `id`.
+- **Job Inspector custom-ID lookup.** A `200` with no `job` (a custom id that
+  resolves to nothing) is now treated as "not found" instead of throwing
+  `Cannot read properties of undefined (reading 'state')`. Demo mode also answers
+  `GET /jobs/custom/:id`, so custom-id lookups work there too.
+
+## [0.0.9] - 2026-07-03
+
+### Added
+- **MCP Server page + docs.** A setup and reference for bunqueue's Model Context
+  Protocol server (`bunqueue-mcp`), which lets AI agents (Claude Desktop, Claude
+  Code) drive the queue. Copy-able configs for both connection modes (embedded
+  via `DATA_PATH`, and TCP via `BUNQUEUE_MODE`/`HOST`/`PORT`/`TOKEN`), plus the
+  full capability inventory: 73 tools across 12 categories, 5 resources, and 3
+  prompts. New "MCP" item in the Management nav and a `docs/guide/mcp` page.
+  Because `bunqueue-mcp` is a separate stdio process launched by the MCP client,
+  the page is a guide, not a live monitor.
+
+## [0.0.8] - 2026-07-03
+
+### Added
+- **SEO: JSON-LD structured data** (schema.org) on every docs page, a
+  `SoftwareApplication` node on the home and a `TechArticle` + `BreadcrumbList`
+  on each content page, all linked to a shared `WebSite` + `Person` graph, so the
+  docs are eligible for rich results. Plus `og:locale`, `og:image:alt` /
+  `twitter:image:alt`, and explicit `robots` directives (`index, follow,
+  max-image-preview:large, max-snippet:-1`).
+- **Enterprise, fluid docs typography.** The docs now use the same variable fonts
+  as the app (Inter for text, JetBrains Mono for code), self-hosted with no CDN,
+  and a fluid (viewport-scaled) type scale for headings and body copy, with
+  optical sizing, Inter stylistic sets, and tabular figures in code and tables.
+
+### Fixed
+- **Demo mode: the Database page no longer crashes** (`Cannot read properties of
+  undefined (reading 'toUpperCase')`). The SQLite inspector's `/db/*` endpoints
+  now return proper demo fixtures (info, table list, per-table schema and rows,
+  and a read-only query result), so the inspector is fully explorable in the demo
+  instead of erroring.
+- **Demo mode:** `GET /queues/:q/dlq/stats` now returns a stats-shaped body (it
+  was mis-routed to the DLQ-entries fixture, leaving the demo DLQ stat cards
+  empty), and the base/`/api` path stripping is anchored to a segment boundary so
+  a path like `/apihealth` can't be mis-stripped.
+
+## [0.0.7] - 2026-07-03
+
+### Added
+- **Demo mode.** A bundled fetch/SSE shim answers every bunqueue API call from a
+  fixture captured from a real bunqueue 2.8.26 server, so the whole dashboard is
+  explorable with no backend: queues, jobs, DLQ, cron, webhooks, and a live
+  activity feed that actually animates. A "Live demo" badge marks it. The demo
+  code and its fixture load lazily, so they add nothing to the normal bundle.
+- **Live demo hosting.** The GitHub Pages app now ships in demo mode, so
+  `https://egeominotti.github.io/bunqueue-dashboard/` is a fully clickable live
+  demo. Linked from the README, the docs home, and the Quickstart.
+
+### Changed
+- The GitHub Pages build serves the root app in demo mode (`VITE_DEMO=1`) instead
+  of an empty "point it at your server" shell. To drive a real server, build your
+  own (Docker / the standalone binary) without `VITE_DEMO`.
+
+## [0.0.6] - 2026-07-03
+
+### Added
+- **Token lock screen.** When the bunqueue server runs with `AUTH_TOKENS` and a
+  request comes back `401`, a lock overlay prompts for the bearer token, stores
+  it for the session (never persisted to disk, same as before), and dismisses. If
+  the token is still rejected, the next poll re-locks. Includes an "Open Settings
+  instead" escape. To wire it up, `bq.ts` now emits an `auth:required` event on a
+  `401` (and still throws), so the UI can prompt for credentials.
+
+## [0.0.5] - 2026-07-03
+
+### Added
+- **Quickstart.** A dedicated Quickstart page (prerequisites, install, one-command
+  run, connecting a server, and next steps), linked from the docs nav and the
+  "Getting started" sidebar group, plus a prominent "Quick start" hero action and
+  section on the docs home.
+
+## [0.0.4] - 2026-07-03
+
+### Added
+- **Lighthouse CI** on pull requests: performance, accessibility, best-practices,
+  and SEO budgets for the built SPA, with the report uploaded to temporary public
+  storage. Thresholds are advisory (`warn`) for now; promote to `error` to
+  enforce.
+
+### Fixed
+- **Pages deploy timeout** set to the `deploy-pages` action's real maximum
+  (600000 ms; the previous 900000 was clamped by GitHub with a warning).
+  Documented that a "Deployment failed, try again later" is a transient
+  Pages-backend error to re-run, not a config problem.
+
+## [0.0.3] - 2026-07-03
+
+### Added
+- **Command palette (Cmd/Ctrl-K).** Fuzzy-search every page plus a few actions
+  (toggle theme, open docs) and jump there, fully keyboard-driven (↑/↓, ↵, esc),
+  with an accessible backdrop and a Topbar search trigger. Its command list is
+  sourced from the sidebar nav, so new sections appear automatically.
+- **Bundle-size budget** (`bun run size`), enforced in CI: fails the build if the
+  total gzipped JavaScript exceeds 230 KB (currently ~162 KB), so a careless
+  dependency can't silently bloat the app.
+
+## [0.0.2] - 2026-07-03
+
+### Added
+- **Structured logging with pino + pino-pretty** for the control agent and the
+  standalone server (replaces plain `console.log`): pretty and colorized on a
+  terminal, newline-delimited JSON in production, level via `LOG_LEVEL`.
+- **Accessibility:** a "Skip to content" link (bypasses the nav for keyboard and
+  screen-reader users) and full `prefers-reduced-motion` support.
+- **Community-health files:** `SECURITY.md`, `CONTRIBUTING.md`,
+  `CODE_OF_CONDUCT.md`, and bug-report / feature-request issue templates.
+- **CI hardening:** a dependency audit (`bun audit`) and test coverage on every
+  run, plus a **CodeQL** SAST workflow.
+- **Supply-chain integrity:** release binaries now ship a `SHA256SUMS` file and a
+  signed **build-provenance attestation**; the Docker image gets an **SBOM** and
+  a signed provenance attestation (verifiable with `gh attestation verify`).
+- **Full truth-table test** for `jobActions.actionGates` (the job-action gating
+  source of truth).
+- **README hero screenshot** and a screenshot gallery.
+
+### Changed
+- **The standalone server binds `127.0.0.1` by default** (`BIND_ADDR=0.0.0.0` to
+  expose): the `/api` proxy to bunqueue's admin API is no longer reachable from
+  the whole network out of the box.
+- **Dark-theme accent darkened to `#db2777`** so white text on accent buttons and
+  badges meets WCAG AA contrast (was 3.5:1).
+
+### Fixed
+- Declared `VITE_BUNQUEUE_AGENT_URL` in the env type definitions (was read
+  untyped).
+
+## [0.0.1] - 2026-07-02
+
+First tagged release. A web dashboard that fully drives a bunqueue server over
+its public HTTP API plus a small local control agent, with an illustrated
+documentation site.
+
+### Added
+- **Full control surface.** View and drive queues, jobs, the dead-letter queue,
+  cron, webhooks, and workers. Every job action is gated by the job's real
+  current state (`src/lib/jobActions.ts`) so the UI never offers something the
+  server would reject.
+- **Live, not just polled.** Cheap polling plus a Server-Sent-Events stream for
+  real-time job activity, with automatic reconnect and rolling throughput,
+  latency, and queue-depth charts.
+- **Process lifecycle.** A small local control agent (loopback-bound,
+  CORS-locked to an allowlist, optional `AGENT_TOKEN`) starts, stops, and
+  restarts the bunqueue process with live logs.
+- **Read-only SQLite inspector** (`/database`): browse tables, schema and
+  indexes, page through rows, and run statement-allowlisted, row-capped,
+  read-only queries with `EXPLAIN` and CSV/JSON export.
+- **Two API clients by design:** the original `src/lib/api.ts` behind the
+  first-generation classic pages, and the complete, shape-verified,
+  strict-error-checked `src/lib/bq.ts` behind every Pro control page.
+- **Illustrated documentation site** (VitePress, published to GitHub Pages under
+  `/docs/`): a user-first, screenshot-backed page per dashboard section, a
+  Mermaid data-flow diagram, local search, and auto-generated
+  `llms.txt` / `llms-full.txt`.
+- **Deployment guides:** Docker (Caddy), Kubernetes, PM2, and hosting-platform
+  recipes (Vercel, Netlify, Cloudflare Pages, GitHub Pages, Render, Fly.io,
+  Railway, Google Cloud Run), plus an overview of the two deployment modes.
+- **SEO on the docs:** `sitemap.xml`, `robots.txt`, per-page canonical links and
+  meta descriptions, and Open Graph / Twitter cards.
+- **Docker image** served with Caddy (gzip + zstd, SPA history fallback,
+  immutable asset caching), published to the GitHub Container Registry.
+- **CI/CD:** the lint + build + test gate on every push and PR, GitHub Pages
+  deploy, multi-arch Docker image, and a Release workflow that cross-compiles
+  standalone executables for 5 platforms (the all-in-one SPA + `/api` proxy +
+  control agent in one binary).
+- **Custom brand:** a queue-badge logo and favicon, and hand-drawn monoline
+  feature icons on the docs home.
+
+[Unreleased]: https://github.com/egeominotti/bunqueue-dashboard/compare/v0.0.14...HEAD
+[0.0.14]: https://github.com/egeominotti/bunqueue-dashboard/compare/v0.0.13...v0.0.14
+[0.0.13]: https://github.com/egeominotti/bunqueue-dashboard/compare/v0.0.12...v0.0.13
+[0.0.12]: https://github.com/egeominotti/bunqueue-dashboard/compare/v0.0.11...v0.0.12
+[0.0.11]: https://github.com/egeominotti/bunqueue-dashboard/compare/v0.0.10...v0.0.11
+[0.0.10]: https://github.com/egeominotti/bunqueue-dashboard/compare/v0.0.9...v0.0.10
+[0.0.9]: https://github.com/egeominotti/bunqueue-dashboard/compare/v0.0.8...v0.0.9
+[0.0.8]: https://github.com/egeominotti/bunqueue-dashboard/compare/v0.0.7...v0.0.8
+[0.0.7]: https://github.com/egeominotti/bunqueue-dashboard/compare/v0.0.6...v0.0.7
+[0.0.6]: https://github.com/egeominotti/bunqueue-dashboard/compare/v0.0.5...v0.0.6
+[0.0.5]: https://github.com/egeominotti/bunqueue-dashboard/compare/v0.0.4...v0.0.5
+[0.0.4]: https://github.com/egeominotti/bunqueue-dashboard/compare/v0.0.3...v0.0.4
+[0.0.3]: https://github.com/egeominotti/bunqueue-dashboard/compare/v0.0.2...v0.0.3
+[0.0.2]: https://github.com/egeominotti/bunqueue-dashboard/compare/v0.0.1...v0.0.2
+[0.0.1]: https://github.com/egeominotti/bunqueue-dashboard/releases/tag/v0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Egeo Minotti
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,287 @@
+<div align="center">
+
+<img src="docs/logo.svg" alt="bunqueue dashboard" width="340" />
+
+# bunqueue dashboard
+
+**A web dashboard that _fully drives_ a [bunqueue](https://bunqueue.dev) server**, monitor and
+control queues, jobs, DLQ, cron, webhooks, workers, a live activity stream, and the server
+**process lifecycle** (start / stop / restart) from one place.
+
+### [▶ Try the live demo](https://egeominotti.github.io/bunqueue-dashboard/)
+
+The full dashboard running on sample data, no server needed.
+
+[![CI](https://github.com/egeominotti/bunqueue-dashboard/actions/workflows/ci.yml/badge.svg)](https://github.com/egeominotti/bunqueue-dashboard/actions/workflows/ci.yml)
+[![Deploy to GitHub Pages](https://github.com/egeominotti/bunqueue-dashboard/actions/workflows/pages.yml/badge.svg)](https://github.com/egeominotti/bunqueue-dashboard/actions/workflows/pages.yml)
+[![Docker](https://github.com/egeominotti/bunqueue-dashboard/actions/workflows/docker.yml/badge.svg)](https://github.com/egeominotti/bunqueue-dashboard/actions/workflows/docker.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Documentation](https://img.shields.io/badge/docs-online-db2777)](https://egeominotti.github.io/bunqueue-dashboard/docs/)
+[![Live demo](https://img.shields.io/badge/live%20demo-online-22c55e)](https://egeominotti.github.io/bunqueue-dashboard/)
+![Status: Beta](https://img.shields.io/badge/status-beta-f59e0b)
+
+![React 19](https://img.shields.io/badge/React-19-149ECA?logo=react&logoColor=white)
+![Vite 8](https://img.shields.io/badge/Vite-8-646CFF?logo=vite&logoColor=white)
+![Bun](https://img.shields.io/badge/Bun-1.3-000?logo=bun&logoColor=white)
+![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178C6?logo=typescript&logoColor=white)
+![Biome](https://img.shields.io/badge/Biome-lint%20%2B%20format-60A5FA?logo=biome&logoColor=white)
+
+<br />
+
+<img src="docs/public/tour.gif" alt="A guided tour of the bunqueue dashboard, clicking through the overview, queues, jobs, the dead-letter queue, flows, the SQLite inspector, and the AI Copilot" width="900" />
+
+<sub>A quick tour. <a href="https://egeominotti.github.io/bunqueue-dashboard/">Try it live →</a></sub>
+
+<br /><br />
+
+<img src="docs/screenshots/overview.png" alt="bunqueue dashboard, real-time overview: health, throughput, per-queue status, and a live activity feed" width="900" />
+
+<sub>The Overview page. <a href="https://egeominotti.github.io/bunqueue-dashboard/docs/user-guide">See every screen in the illustrated guide →</a></sub>
+
+<details>
+<summary><b>More screenshots</b></summary>
+<br />
+<img src="docs/screenshots/server.png" alt="Server Control, start/stop/restart the bunqueue process with live logs" width="900" />
+<img src="docs/screenshots/jobs.png" alt="Jobs Explorer, filter, inspect, and bulk-action jobs" width="900" />
+<img src="docs/screenshots/database.png" alt="Read-only SQLite inspector, browse tables and run queries" width="900" />
+</details>
+
+</div>
+
+---
+
+> ⚠️ **Beta.** bunqueue dashboard is under active development, interfaces and
+> behavior may change between releases. Review it before relying on it for
+> unattended production use.
+
+## 📚 Documentation
+
+**Full, illustrated docs live at
+[egeominotti.github.io/bunqueue-dashboard/docs](https://egeominotti.github.io/bunqueue-dashboard/docs/).**
+
+- **[Illustrated user guide](https://egeominotti.github.io/bunqueue-dashboard/docs/user-guide)**, one detailed, screenshot-backed page per dashboard section.
+- **[Deployment](https://egeominotti.github.io/bunqueue-dashboard/docs/deploy/)**, Docker (Caddy), Kubernetes, PM2, and hosting platforms (Vercel, Netlify, Cloudflare, Fly.io, Render, Cloud Run).
+- **[Architecture](https://egeominotti.github.io/bunqueue-dashboard/docs/architecture)** and **[API mapping](https://egeominotti.github.io/bunqueue-dashboard/docs/api-mapping)**, how it fits together and every endpoint it drives.
+- **[llms.txt](https://egeominotti.github.io/bunqueue-dashboard/docs/llms.txt)**, the whole site as a single file for LLMs.
+
+## Table of contents
+
+- [Documentation](#-documentation)
+- [Why](#why)
+- [Features](#features)
+- [Quick start](#quick-start)
+- [Architecture](#architecture)
+- [Configuration](#configuration)
+- [Scripts](#scripts)
+- [Docker](#docker)
+- [Deployment](#deployment)
+- [Testing & quality gate](#testing--quality-gate)
+- [Project structure](#project-structure)
+- [Security](#security)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Why
+
+bunqueue exposes a rich HTTP API, but operating it by hand (curl, ad-hoc scripts) is slow and
+error-prone. This dashboard is a **complete operator console**: everything the API can do, plus the
+one thing it can't, managing the server *process*, behind a fast, keyboard-friendly UI.
+
+It talks **only** to bunqueue's public HTTP API (`:6790`) and a small local **control agent**. It
+never imports or modifies bunqueue itself, so it tracks any bunqueue server you point it at.
+
+## Features
+
+| Area | Where | What you can do |
+| --- | --- | --- |
+| **Home** | Overview | Live health banner, throughput, queue health, recent activity |
+| **Server** | Control ▸ Server | **Start / stop / restart** the server process, edit its config, tail process logs |
+| **Enqueue** | Control ▸ Add Job | Add jobs (single or bulk) with every option |
+| **Inspect** | Control ▸ Job Inspector | Look up any job; promote / retry / discard / cancel / re-prioritize / delay; view data & result |
+| **Queues** | Control ▸ Queue Control | Pause / resume / drain / clean / promote / retry-completed, rate-limit, concurrency, stall & DLQ policy |
+| **Cron** | Control ▸ Cron Manager | Create (cron or interval) and delete schedules |
+| **DLQ** | Control ▸ DLQ | Inspect dead-letter entries, retry one / all, purge |
+| **Webhooks** | Control ▸ Webhooks | Create / enable / delete job-event webhooks |
+| **Ops** | Control ▸ Diagnostics | Health, ping, storage, memory, connections, totals |
+| **Browse** | Queues / Jobs / DLQ / Cron / Metrics / Workers / Logs | Read-only browsing with basic actions |
+
+> Every job action is **gated by the job's real state** (`src/lib/jobActions.ts`), so the UI never
+> offers an action the server would reject.
+
+## Quick start
+
+**Prerequisites:** [Bun](https://bun.sh) ≥ 1.3 and a reachable bunqueue server (or let the control
+agent start one for you from the **Server** page).
+
+### Run from npm (no clone)
+
+```bash
+bunx bunqueue-dashboard
+```
+
+One command: serves the prebuilt dashboard on http://127.0.0.1:8080, proxies `/api/*` to your
+bunqueue server (`BUNQUEUE_URL`, default `http://localhost:6790`), and runs the control agent on
+`127.0.0.1:6800`. Same env knobs as the standalone binaries: `PORT` · `BIND_ADDR` · `BUNQUEUE_URL` ·
+`AGENT_PORT` · `AGENT_ALLOWED_ORIGINS` · `AGENT_TOKEN` · `BUNQUEUE_START_CMD`.
+
+### Run from source
+
+```bash
+git clone https://github.com/egeominotti/bunqueue-dashboard.git
+cd bunqueue-dashboard
+bun install
+bun start
+```
+
+`bun start` boots **both** the control agent and the dashboard in one terminal and shuts both down
+on `Ctrl-C`:
+
+| Service | URL | Role |
+| --- | --- | --- |
+| Dashboard | http://localhost:5273 | The UI (`/api/*` is proxied to `:6790` in dev) |
+| Control agent | http://127.0.0.1:6800 | Starts / stops / restarts the server process |
+| bunqueue server | http://localhost:6790 | Your queue server, started from the **Server** page or run separately |
+
+Prefer separate terminals? The individual commands still exist, see [Scripts](#scripts).
+
+## Architecture
+
+```mermaid
+flowchart LR
+    subgraph Browser
+        UI["Dashboard (React 19 SPA)"]
+    end
+    subgraph Local
+        Agent["Control agent (Bun)<br/>127.0.0.1:6800"]
+        Server["bunqueue server<br/>:6790 HTTP · :6789 TCP"]
+    end
+    UI -- "HTTP: queues, jobs, DLQ, cron…" --> Server
+    UI -- "SSE: live activity" --> Server
+    UI -- "/control/* start·stop·restart" --> Agent
+    Agent -- "spawn / kill process" --> Server
+```
+
+- **Reads** by polling (`usePolledData`) and a Server-Sent Events stream (`useActivityStream`).
+- **Writes** through the same HTTP API, with every mutation shape-verified against the live server.
+- **Process lifecycle**, the one thing HTTP can't do, is delegated to the local control agent.
+
+Two HTTP clients coexist on purpose: `src/lib/api.ts` (first-generation view pages) and
+`src/lib/bq.ts` (the complete, shape-verified client used by every `Control ▸ *` page). See
+[`docs/`](docs/README.md) for the full, source-verified reference.
+
+## Configuration
+
+All dashboard variables are build-time (`VITE_*`) and can **also** be changed at runtime from the
+in-app **Settings** page. Copy [`.env.example`](.env.example) to `.env` to set defaults.
+
+| Variable | Purpose | Default |
+| --- | --- | --- |
+| `VITE_BUNQUEUE_URL` | bunqueue server origin | `/api` (dev proxy → `:6790`) |
+| `VITE_BUNQUEUE_TOKEN` | Bearer token, if the server has `AUTH_TOKENS` set | _none_ |
+| `VITE_BUNQUEUE_AGENT_URL` | Control-agent origin | `http://localhost:6800` |
+| `AGENT_PORT` | Control-agent port | `6800` |
+| `AGENT_ALLOWED_ORIGINS` | Extra browser origins allowed to drive the agent (comma-separated) | dev defaults |
+| `AGENT_TOKEN` | Optional bearer token required on state-changing agent requests | _none_ (off) |
+
+## Scripts
+
+| Command | Does |
+| --- | --- |
+| `bun start` | **Agent + dashboard together** (one-command dev) |
+| `bun dev` | Dashboard only (Vite dev server) |
+| `bun run agent` | Control agent only |
+| `bun run build` | Typecheck (`tsc --noEmit`) + production build → `dist/` |
+| `bun run preview` | Preview the production build |
+| `bun run check` | Biome lint + format (the CI gate) |
+| `bun run check:fix` | Biome lint + format with safe fixes applied |
+| `bun test` | Unit + agent-lifecycle tests |
+
+## Docker
+
+A multi-stage image builds the SPA with Bun and serves it with Caddy (gzip/zstd, SPA history fallback, immutable asset caching). Published to the GitHub Container Registry on every push.
+
+```bash
+# Pull & run the published image (`edge` tracks main; use `vX.Y.Z`/`latest` after a release)
+docker run --rm -p 8080:80 ghcr.io/egeominotti/bunqueue-dashboard:edge
+# → http://localhost:8080  (set the server URL from the Settings page)
+
+# …or build locally, optionally baking in a default server origin
+docker build --build-arg VITE_BUNQUEUE_URL=https://queue.example.com -t bunqueue-dashboard .
+docker run --rm -p 8080:80 bunqueue-dashboard
+```
+
+Tags: `latest` and `vX.Y.Z` on releases, `edge` on `main`.
+
+## Deployment
+
+- **Standalone executables**, every [release](https://github.com/egeominotti/bunqueue-dashboard/releases)
+  ships self-contained binaries for **Linux (x64/arm64), macOS (x64/arm64) and Windows (x64)**:
+  download one file and run it, it serves the dashboard (assets embedded), proxies `/api` to your
+  bunqueue server (`BUNQUEUE_URL`, default `:6790`) and includes the control agent.
+  ```bash
+  ./bunqueue-dashboard-vX.Y.Z-darwin-arm64        # → http://localhost:8080
+  PORT=3000 BUNQUEUE_URL=https://queue.example.com ./bunqueue-dashboard-vX.Y.Z-linux-x64
+  ```
+- **GitHub Pages**, every push to `main` builds and publishes the static SPA
+  (`.github/workflows/pages.yml`). The workflow **attempts** to auto-provision Pages; if the first
+  run reports `Get Pages site failed`, enable it once under **Settings ▸ Pages ▸ Source → GitHub
+  Actions** (the default `GITHUB_TOKEN` can't create a Pages site on its own). The build sets the
+  correct sub-path base and a `404.html` SPA fallback automatically.
+- **Container**, self-host the published `ghcr.io` image behind any reverse proxy.
+- **Static host**, `bun run build` emits a plain `dist/` you can serve from any CDN or static host.
+
+Because the deployed build is a static shell, point it at a reachable bunqueue server via
+`VITE_BUNQUEUE_URL` (build time) or the **Settings** page (runtime).
+
+## Testing & quality gate
+
+Three commands must be green before a change is considered done, the same checks CI runs:
+
+```bash
+bun run build     # tsc --noEmit + vite build
+bun run check     # Biome lint + format (production-grade config)
+bun test          # unit + agent-lifecycle tests
+```
+
+CI enforces this on every push and pull request. See [Contributing](#contributing).
+
+## Project structure
+
+```
+bunqueue-dashboard/
+├── .github/workflows/   # CI, Pages deploy, Docker publish, Release
+├── agent/               # Bun control agent (process lifecycle), server.ts, manager.ts, index.ts
+├── docker/              # Caddyfile for the container image
+├── docs/                # source-verified reference (architecture, pages, API mapping, known issues)
+├── scripts/dev.ts       # one-command dev launcher (`bun start`)
+├── src/
+│   ├── lib/             # api.ts, bq.ts, hooks, formatters, job-action gating
+│   ├── components/      # layout shell, UI kit, Zustand stores
+│   └── pages/           # view pages + Control ▸ * operator pages
+└── test/                # bun test (format, sse, manager, agent lifecycle, s3 store)
+```
+
+Full walkthrough in [`docs/README.md`](docs/README.md).
+
+## Security
+
+The control agent can spawn processes, so it is hardened by design (`agent/server.ts`):
+
+- Binds **`127.0.0.1` only**.
+- **CORS locked to an allowlist**, `Access-Control-Allow-Origin` is never `*`.
+- Requests carrying a **disallowed `Origin` are rejected (403)** before reaching the process manager, blocking drive-by CSRF from a malicious tab.
+- Optional **`AGENT_TOKEN`** adds a bearer-token gate on state-changing requests.
+
+Keep the agent on loopback (or an equivalently trusted network) and set `AGENT_TOKEN` for shared
+machines. See [`docs/known-issues.md`](docs/known-issues.md) for the honest, verified limitations.
+
+## Contributing
+
+1. Keep it **additive**, prefer new files + minimal glue over rewriting existing ones
+   (see [`CLAUDE.md`](CLAUDE.md)).
+2. Make the [gate](#testing--quality-gate) green: `bun run build && bun run check && bun test`.
+3. Open a PR, the template walks you through the checklist. CI must pass.
+
+## License
+
+[MIT](LICENSE) © Egeo Minotti