docs: document the dashboard's templates workflow and add a Dashboard section to the user guide

mkdocs.yml

@@ -31,6 +31,10 @@ nav:
   - Homepage: index.md
   - Quickstart: content/quickstart.md
   - User Guide:
+    - Dashboard:
+      - Overview: content/user_guide/dashboard/index.md
+      - Sessions: content/user_guide/dashboard/sessions.md
+      - Templates: content/user_guide/dashboard/templates.md
     - Logging:
       - Local: content/user_guide/logging/local.md
       - Wandb: content/user_guide/logging/wandb.md

src/content/quickstart.md

@@ -131,6 +131,17 @@ python main.py
 
 and fenn will take care of the rest for you.
 
+### Dashboard
+
+Start the local dashboard with:
+
+```bash
+fenn dashboard
+```
+
+From there you can browse, filter, and rename your experiment sessions, see every template you've pulled, and launch any of them with one click — you'll be taken straight to its live session view.
+
+
 ### Training Models
 
 Use built-in trainers to handle your training loops with minimal boilerplate.

src/content/user_guide/dashboard/index.md

@@ -0,0 +1,42 @@
+# The Dashboard
+
+The Fenn dashboard is a local web UI for browsing your experiment sessions, viewing logs, and managing the templates you've pulled - all without leaving your browser.
+
+## Starting the Dashboard
+
+```bash
+fenn dashboard
+```
+
+By default this starts a server at `http://127.0.0.1:5000`. The dashboard only ever binds to `127.0.0.1` - it serves your local logs and is not meant to be exposed on your network.
+
+## Options
+
+| Flag | Description |
+|---|---|
+| `--port <PORT>` | Port to bind (default: `5000`) |
+| `--log-dir <DIR> [DIR ...]` | Extra directories to scan for `.fn` session files, in addition to the current directory |
+| `--debug` | Run Flask in debug mode |
+
+Example:
+
+```bash
+fenn dashboard --port 8080 --log-dir ./experiments ./archived-runs
+```
+
+## Signing In
+
+The first time you open the dashboard, you'll be redirected to a **Connect** page with a "Sign in with pyfenn.com" button. This opens a browser tab for a normal OAuth sign-in and consent flow, then hands control back to the dashboard.
+
+Once you've signed in, your session is cached locally so future launches of `fenn dashboard` skip the sign-in step and re-validate silently in the background. If your saved session is ever revoked or expires, you'll be sent back to the Connect page to sign in again.
+
+## Pages
+
+| Page | What it shows |
+|---|---|
+| **Overview** (`/`) | All projects with logged sessions, at a glance |
+| **Project** (`/project/<name>`) | All sessions for a single project |
+| **Session** (`/session/<project>/<id>`) | Full detail for one session - logs, metadata, status |
+| **Templates** (`/templates`) | Templates you've pulled locally, with the option to launch them - see [Managing Templates](templates.md) |
+
+For details on filtering, renaming, and archiving sessions, see [Managing Sessions](sessions.md).

src/content/user_guide/dashboard/sessions.md

@@ -0,0 +1,37 @@
+# Managing Sessions
+
+Every run of your entrypoint is logged as a session, and the dashboard gives you tools to browse, organize, and clean up those sessions without touching the log files by hand.
+
+## Browsing
+
+The **Overview** page lists every project with logged sessions. Open a project to see its individual sessions, or open a session directly to see its full logs and metadata.
+
+Each session has a status:
+
+- `running` — currently in progress
+- `completed` — finished normally
+- `failed` — finished with an error
+- `crashed` — stopped writing without a proper close (e.g. the process died)
+
+## Filtering
+
+From a project or the overview, sessions can be filtered by:
+
+- **Project**
+- **Status** (`running`, `crashed`, `completed`, `failed`)
+- **Date range** — sessions started after/before a given `YYYY-MM-DD HH:MM:SS` timestamp
+- **Sort** — by start time, end time, duration, warning count, or exception count (ascending or descending)
+
+Archived sessions are hidden by default; toggle "include archived" to bring them back into the list.
+
+## Renaming
+
+Give a session a more memorable display name than its generated ID directly from the session or project view. The underlying `.fn` file and session ID are untouched - only the display name changes.
+
+## Archiving
+
+Archiving hides a session from the default view without deleting anything - useful for tidying up old or exploratory runs you want to keep around but not see day-to-day. Archived sessions can be restored at any time from the "include archived" view, which brings them back into the normal listing.
+
+## Deleting
+
+Deleting a session removes it permanently. Unlike archiving, this cannot be undone - use archiving instead if you just want a session out of the way.

src/content/user_guide/dashboard/templates.md

@@ -0,0 +1,23 @@
+# Managing Templates
+
+The **Templates** page (`/templates`) lists every template you've pulled locally with `fenn pull`, and lets you launch one directly from the browser.
+
+## How templates get here
+
+Every time you run `fenn pull <template> [path]`, Fenn records the template's name, local path, source template, and pull time in a local registry (`~/.fenn/templates_registry.json` by default). The Templates page reads from this registry - pulling is still done via `fenn pull` or `fenn list`, the dashboard just shows you what's already on disk.
+
+If a template's directory is later moved or deleted, it's automatically dropped from the list the next time the registry is read.
+
+> The registry location can be overridden with the `FENN_TEMPLATES_REGISTRY_PATH` environment variable.
+
+## Running a template
+
+Click **Run** next to any listed template to launch it as a background process. The dashboard will:
+
+1. Start the template's entrypoint (`main.py`) as a subprocess.
+2. Poll for its session to appear.
+3. Redirect you to that session's live view once it's found.
+
+If the template fails to start (for example, a bad `fenn.yaml` or an early crash), the error is shown inline next to the Run button instead of failing silently.
+
+Only templates that appear in the local registry can be launched this way - arbitrary file paths are not accepted.

src/index.md

@@ -46,6 +46,10 @@ Get notified the moment your run finishes, fails, or hits a new best metric. Rea
 
 Classification, regression, segmentation — Fenn ships battle-tested trainer loops so you can focus on architecture and data, not training boilerplate.
 
+### Live Dashboard
+
+A local web dashboard for your runs. Browse experiment sessions as they happen, filter and rename them to keep things organized, see every template you've pulled, and launch any of them straight from the browser.
+
 ### Reproducible Templates
 
 Start any new project from a versioned, opinionated template. Seeds, environments, and artifact paths are locked in from the first commit.