docs: clarify live-editing behavior in dashboard and add docstrings to RunManager

Users editing primitives via the Configure tab while a run is active
would expect changes to take effect immediately. Added a table to the
dashboard docs explaining what's hot-reloadable (prompt, context output)
vs what requires a restart (primitive config, new/deleted primitives).

Also added docstrings to all RunManager methods and RunState control
methods so contributors and AI agents can understand the orchestration
layer without reading implementation details.

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

Author: 2 people

docs/dashboard.md

@@ -115,6 +115,22 @@ Click **New Run** in the sidebar to open the run modal. It lets you:
 Once a run starts, you can **pause**, **resume**, or **stop** it from the
 sidebar or the controls bar above the Timeline.
 
+## Editing while a run is active
+
+The dashboard lets you edit primitives via the Configure tab while a run is in progress, but not all changes take effect immediately:
+
+| What you change | When it takes effect |
+|---|---|
+| `PROMPT.md` content | Next iteration — the prompt is re-read from disk every iteration |
+| Context command output | Next iteration — context commands re-run every iteration |
+| Check/context/instruction config (frontmatter, body, enable/disable) | After restart — primitive configurations are loaded once when a run starts |
+| New or deleted primitives | After restart — primitive discovery happens once at run start |
+
+To apply primitive configuration changes to a running run, **stop** the run and **start a new one**. The new run will discover the updated primitives from disk.
+
+!!! tip "Prompt edits are always live"
+    The most common adjustment — adding a constraint or changing the task in your prompt — takes effect on the very next iteration without restarting. This is the primary way to steer the agent in real time.
+
 ## Architecture
 
 The dashboard is a single-page app that talks to a FastAPI backend:

src/ralphify/engine.py

@@ -80,19 +80,23 @@ def __post_init__(self) -> None:
         self._pause_event.set()
 
     def request_stop(self) -> None:
+        """Signal the loop to stop after the current iteration."""
         self._stop_requested = True
         # Unpause so the loop can exit
         self._pause_event.set()
 
     def request_pause(self) -> None:
+        """Pause the loop between iterations until resumed."""
         self.status = RunStatus.PAUSED
         self._pause_event.clear()
 
     def request_resume(self) -> None:
+        """Resume a paused loop."""
         self.status = RunStatus.RUNNING
         self._pause_event.set()
 
     def request_reload(self) -> None:
+        """Request re-discovery of primitives before the next iteration."""
         self._reload_requested = True
 
 

src/ralphify/manager.py

@@ -24,6 +24,7 @@ class ManagedRun:
     _extra_emitters: list[EventEmitter] = field(default_factory=list)
 
     def add_listener(self, emitter: EventEmitter) -> None:
+        """Register an additional emitter to receive events from this run."""
         self._extra_emitters.append(emitter)
 
 
@@ -46,6 +47,11 @@ def __init__(self) -> None:
         self._lock = threading.Lock()
 
     def create_run(self, config: RunConfig) -> ManagedRun:
+        """Create a new run from *config* and register it.
+
+        Assigns a unique run ID and returns the :class:`ManagedRun`.
+        The run is not started — call :meth:`start_run` to begin execution.
+        """
         run_id = uuid.uuid4().hex[:12]
         state = RunState(run_id=run_id)
         emitter = QueueEmitter()
@@ -55,6 +61,11 @@ def create_run(self, config: RunConfig) -> ManagedRun:
         return managed
 
     def start_run(self, run_id: str) -> None:
+        """Start the run loop in a daemon thread.
+
+        The thread calls :func:`engine.run_loop` with a fanout emitter
+        that broadcasts events to the run's queue and any extra listeners.
+        """
         with self._lock:
             managed = self._runs[run_id]
         all_emitters: list[EventEmitter] = [managed.emitter] + managed._extra_emitters
@@ -69,24 +80,29 @@ def start_run(self, run_id: str) -> None:
         thread.start()
 
     def stop_run(self, run_id: str) -> None:
+        """Signal the run to stop after the current iteration finishes."""
         with self._lock:
             managed = self._runs[run_id]
         managed.state.request_stop()
 
     def pause_run(self, run_id: str) -> None:
+        """Pause the run between iterations until :meth:`resume_run` is called."""
         with self._lock:
             managed = self._runs[run_id]
         managed.state.request_pause()
 
     def resume_run(self, run_id: str) -> None:
+        """Resume a paused run."""
         with self._lock:
             managed = self._runs[run_id]
         managed.state.request_resume()
 
     def list_runs(self) -> list[ManagedRun]:
+        """Return a snapshot of all registered runs."""
         with self._lock:
             return list(self._runs.values())
 
     def get_run(self, run_id: str) -> ManagedRun | None:
+        """Look up a run by ID, returning ``None`` if not found."""
         with self._lock:
             return self._runs.get(run_id)