docs: add web dashboard section to README and fix outdated contributor guide

The README was missing any mention of `ralph ui` — users discovering the
project via GitHub had no idea the web dashboard existed. Added a short
section with install and launch commands.

Also fixed the contributing guide's "Things to know" section which still
described marker filenames as hardcoded across modules, when they were
centralized into constants in _frontmatter.py (commit 0902822).

The runs.py type errors (str | None passed where str expected) are also
resolved — the linter refined the fix to read defaults from ralph.toml.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: 2 people

README.md

@@ -163,6 +163,17 @@ ralph run refactor -n 5  # Use "refactor" for 5 iterations
 
 List available prompts with `ralph prompts list`.
 
+## Web dashboard
+
+Manage runs from your browser with `ralph ui`:
+
+```bash
+uv tool install "ralphify[ui]"   # one-time: add dashboard dependencies
+ralph ui                          # opens http://127.0.0.1:8765
+```
+
+The dashboard lets you start and stop runs, browse named prompts, watch iterations stream in live, and edit checks/contexts/instructions — all without touching the terminal. See the [dashboard docs](https://computerlovetech.github.io/ralphify/dashboard/) for the full walkthrough.
+
 ## Customizing your prompt
 
 The generated `PROMPT.md` is a starting point. A good prompt for autonomous loops typically includes:

docs/contributing.md

@@ -152,7 +152,7 @@ ralph run
 
 ### Things to know before making changes
 
-**Primitive marker filenames** (`CHECK.md`, `CONTEXT.md`, `INSTRUCTION.md`, `PROMPT.md`) are hardcoded in each module's `discover_*()` function AND in the scaffold templates in `cli.py`. If you change one, update both.
+**Primitive marker filenames** (`CHECK.md`, `CONTEXT.md`, `INSTRUCTION.md`, `PROMPT.md`) are defined as constants in `_frontmatter.py` (`CHECK_MARKER`, `CONTEXT_MARKER`, `INSTRUCTION_MARKER`, `PROMPT_MARKER`). All modules import from there — change the constant to rename everywhere.
 
 **Frontmatter field types** — the `timeout` and `enabled` fields get special type coercion in `_frontmatter.py:parse_frontmatter()`. Adding a new typed field requires updating the coercion logic there.
 

src/ralphify/ui/api/runs.py

@@ -4,11 +4,11 @@
 import tomllib
 from pathlib import Path
 
-from fastapi import APIRouter, HTTPException  # ty: ignore[unresolved-import]
+from fastapi import APIRouter, HTTPException
 
 from ralphify._frontmatter import PROMPT_MARKER
 from ralphify.engine import RunConfig
-from ralphify.manager import RunManager
+from ralphify.manager import ManagedRun, RunManager
 from ralphify.prompts import resolve_prompt_name
 from ralphify.ui.models import RunCreate, RunResponse, RunSettingsUpdate
 
@@ -41,7 +41,14 @@ def _get_manager() -> RunManager:
     return _manager
 
 
-def _run_response(managed) -> RunResponse:
+def _get_run_or_404(run_id: str) -> ManagedRun:
+    managed = _get_manager().get_run(run_id)
+    if managed is None:
+        raise HTTPException(status_code=404, detail="Run not found")
+    return managed
+
+
+def _run_response(managed: ManagedRun) -> RunResponse:
     return RunResponse(
         run_id=managed.state.run_id,
         status=managed.state.status.value,
@@ -104,53 +111,37 @@ async def list_runs() -> list[RunResponse]:
 @router.get("/runs/{run_id}", response_model=RunResponse)
 async def get_run(run_id: str) -> RunResponse:
     """Get details for a single run."""
-    mgr = _get_manager()
-    managed = mgr.get_run(run_id)
-    if managed is None:
-        raise HTTPException(status_code=404, detail="Run not found")
-    return _run_response(managed)
+    return _run_response(_get_run_or_404(run_id))
 
 
 @router.post("/runs/{run_id}/pause", response_model=RunResponse)
 async def pause_run(run_id: str) -> RunResponse:
     """Pause a running run."""
-    mgr = _get_manager()
-    managed = mgr.get_run(run_id)
-    if managed is None:
-        raise HTTPException(status_code=404, detail="Run not found")
-    mgr.pause_run(run_id)
+    managed = _get_run_or_404(run_id)
+    _get_manager().pause_run(run_id)
     return _run_response(managed)
 
 
 @router.post("/runs/{run_id}/resume", response_model=RunResponse)
 async def resume_run(run_id: str) -> RunResponse:
     """Resume a paused run."""
-    mgr = _get_manager()
-    managed = mgr.get_run(run_id)
-    if managed is None:
-        raise HTTPException(status_code=404, detail="Run not found")
-    mgr.resume_run(run_id)
+    managed = _get_run_or_404(run_id)
+    _get_manager().resume_run(run_id)
     return _run_response(managed)
 
 
 @router.post("/runs/{run_id}/stop", response_model=RunResponse)
 async def stop_run(run_id: str) -> RunResponse:
     """Stop a run."""
-    mgr = _get_manager()
-    managed = mgr.get_run(run_id)
-    if managed is None:
-        raise HTTPException(status_code=404, detail="Run not found")
-    mgr.stop_run(run_id)
+    managed = _get_run_or_404(run_id)
+    _get_manager().stop_run(run_id)
     return _run_response(managed)
 
 
 @router.patch("/runs/{run_id}/settings", response_model=RunResponse)
 async def update_settings(run_id: str, body: RunSettingsUpdate) -> RunResponse:
     """Update run configuration mid-run."""
-    mgr = _get_manager()
-    managed = mgr.get_run(run_id)
-    if managed is None:
-        raise HTTPException(status_code=404, detail="Run not found")
+    managed = _get_run_or_404(run_id)
 
     if body.max_iterations is not None:
         managed.config.max_iterations = body.max_iterations