Manage graph viewers with a supervised local service

docs/VIEWER_MANAGER.md

@@ -0,0 +1,54 @@
+# Viewer manager
+
+DocForge graph viewers are owned by one local, per-user viewer-manager service. The MCP server
+does not own browser workers. This prevents normal stdio MCP turnover from closing a page while it
+is in use.
+
+The manager listens only on `127.0.0.1` and chooses an ephemeral port. Its private state record
+contains that port and a high-entropy capability token. The record lives in the current user's
+runtime directory on Linux, Application Support directory on macOS, or Local AppData directory on
+Windows. The manager starts no network listener beyond loopback.
+
+One worker is reused per project binding and validated index snapshot. `docforge_visualize` replaces
+the worker only after the snapshot changes. `docforge_visualization_status` reports its state, and
+`docforge_stop_visualization` explicitly stops it.
+
+The default one-hour idle policy is intentional. Browser requests, including the existing visible
+page heartbeat, renew activity. A page is never tied to the lifetime of one MCP request or host
+process. The manager stops genuinely abandoned workers after an hour without activity. Stopping the
+manager also stops all of its workers.
+
+## Install the user service
+
+Run this once in the same DocForge environment that will run the MCP server:
+
+```bash
+docforge-viewer-manager install-user-service
+```
+
+The command installs and starts the native user-level supervisor:
+
+- Linux uses a `systemd --user` service with `Restart=on-failure` and `KillMode=control-group`.
+- macOS uses a LaunchAgent under `~/Library/LaunchAgents`.
+- Windows uses a per-user Task Scheduler entry named `DocForgeViewerManager`.
+
+Use `docforge-viewer-manager uninstall-user-service` to stop and remove it. For development or a
+nonstandard supervisor, run this foreground command instead:
+
+```bash
+docforge-viewer-manager serve
+```
+
+The service command intentionally uses the Python interpreter that installed it. After moving or
+recreating the DocForge virtual environment, run the install command again so the native service
+points at the new interpreter.
+
+## Operational behavior
+
+The manager is a small, long-lived control service. Its worker count is bounded by the number of
+currently viewed project snapshots, not the number of MCP requests. A crashed manager is restarted
+by the native supervisor. The supervisor stops child workers as one unit, avoiding orphan listeners.
+
+MCP only receives a loopback URL after the manager has accepted the exact validated snapshot. If the
+manager is unavailable, DocForge returns `visualization_manager_unavailable` with the state path so
+the integration can be repaired without falling back to an unmanaged worker.