tmaiaroto · Oct 21, 2026 · Oct 20, 2026 · Oct 20, 2026 · Oct 20, 2026 · Oct 20, 2026
diff --git a/.github/workflows/security.yml b/.github/workflows/security.yml
@@ -69,7 +69,7 @@ jobs:
         with:
           # Pin the patched stdlib release so govulncheck reports against
           # it; "stable" resolves from a mirror that lags security releases.
-          go-version: 1.27.2
+          go-version: 1.27.3
       - name: Install govulncheck
         run: go install golang.org/x/vuln/cmd/govulncheck@latest
       - name: Run govulncheck

diff --git a/docs/CLI.md b/docs/CLI.md
@@ -0,0 +1,169 @@
+# CLI Reference
+
+This page describes the `phosphor` command-line interface. For command-specific
+details, see the linked docs or run `phosphor <command> --help`.
+
+## Global flags
+
+These flags apply to the root command and are inherited by subcommands.
+
+| Flag | Short | Description |
+| --- | --- | --- |
+| `--cwd <dir>` | `-c` | Set the current working directory. |
+| `--data-dir <dir>` | `-D` | Use a custom Phosphor data directory. |
+| `--debug` | `-d` | Enable debug logging. |
+| `--host <host>` | `-H` | Connect to a specific Phosphor server host. |
+| `--profile <name>` | | Select an active prompt/governance profile. |
+| `--trust` | `-T` | Trust the workspace and load repo-local tools/MCP configuration. |
+| `--yolo` | `-y` | Automatically accept all permissions. |
+| `--session <id>` | `-s` | Continue a previous session by ID. |
+| `--continue` | `-C` | Continue the most recent session. |
+| `--help` | `-h` | Show help. |
+
+`--session` and `--continue` are mutually exclusive.
+
+## Commands
+
+| Command | Description |
+| --- | --- |
+| `phosphor` | Start the TUI and HTTP API (default). |
+| `phosphor run [prompt...]` | Run a single non-interactive prompt. |
+| `phosphor server` | Start the HTTP API server. |
+| `phosphor acp` | Start the Agent Client Protocol service. |
+| `phosphor login [platform]` | Authenticate with a provider. |
+| `phosphor logout [platform]` | Log out from a provider. |
+| `phosphor update-providers [path-or-url]` | Update provider metadata. |
+| `phosphor index [directory]` | Build the workspace FTS5 index. |
+| `phosphor session` | List and manage sessions. |
+| `phosphor projects` | List known project directories. |
+| `phosphor logs` | View Phosphor logs. |
+| `phosphor stats` | Show token and cost usage statistics. |
+| `phosphor memorygraph` | Run the memory graph viewer. |
+| `phosphor cron` | Run the cron service for scheduled jobs. |
+| `phosphor job` | Manage scheduled jobs. |
+| `phosphor bindings` | List all keybindings. |
+| `phosphor dirs` | Show config and data directories. |
+| `phosphor schema` | Generate JSON schema for configuration. |
+
+## `phosphor run`
+
+`phosphor run` sends a single prompt to the agent and exits. It supports
+piping input from stdin.
+
+| Flag | Short | Description |
+| --- | --- | --- |
+| `--quiet` | `-q` | Hide the spinner. |
+| `--verbose` | `-v` | Show logs. |
+| `--model <model>` | `-m` | Model to use (`model` or `provider/model`). |
+| `--small-model <model>` | | Small model to use. |
+| `--session <id>` | `-s` | Continue a previous session by ID. |
+| `--continue` | `-C` | Continue the most recent session. |
+
+## `phosphor server`
+
+| Flag | Short | Description |
+| --- | --- | --- |
+| `--host <host>` | `-H` | Server host (TCP or Unix socket). |
+| `--openai-host <host>` | | OpenAI-compatible API host. |
+| `--openai-port <port>` | | OpenAI-compatible API port. |
+| `--openai-enabled <bool>` | | Enable the OpenAI API service (default: true). |
+| `--workspace <dir>` | | Workspace directory path. |
+
+## `phosphor login`
+
+| Flag | Short | Description |
+| --- | --- | --- |
+| `--force` | `-f` | Force re-authentication even if already logged in. |
+
+## `phosphor logout`
+
+| Flag | Short | Description |
+| --- | --- | --- |
+| `--force` | `-f` | Skip the logout confirmation prompt. |
+
+## `phosphor update-providers`
+
+| Flag | Description |
+| --- | --- |
+| `--source <source>` | Provider source to update (`catwalk` or `hyper`, default: `catwalk`). |
+
+## `phosphor index`
+
+No subcommand-specific flags. Builds the workspace FTS5 index for the given
+directory (defaults to the current directory).
+
+## `phosphor session`
+
+| Subcommand | Description |
+| --- | --- |
+| `phosphor session list` | List all sessions. |
+| `phosphor session show <id>` | Show session details. |
+| `phosphor session last` | Show the most recent session. |
+| `phosphor session delete <id>` | Delete a session. |
+| `phosphor session rename <id> <title>` | Rename a session. |
+| `phosphor session pin <id>` | Pin a session against bulk deletion. |
+| `phosphor session unpin <id>` | Unpin a session. |
+| `phosphor session prune-sessions` | Bulk delete old sessions. |
+| `phosphor session prune <session-id>` | Prune old messages from a stateless session. |
+| `phosphor session list-stateless` | List stateless sessions. |
+
+Common output flags:
+
+| Flag | Description |
+| --- | --- |
+| `--json` | Output in JSON format. |
+| `--before <duration>` | Only affect sessions older than the duration. |
+| `--dry-run` | Show what would be deleted without deleting. |
+
+## `phosphor projects`
+
+| Flag | Description |
+| --- | --- |
+| `--json` | Output as JSON. |
+
+## `phosphor logs`
+
+| Flag | Short | Description |
+| --- | --- | --- |
+| `--follow` | `-f` | Follow log output. |
+| `--tail <n>` | `-t` | Show only the last N lines (default: 1000). |
+
+## `phosphor memorygraph`
+
+| Flag | Description |
+| --- | --- |
+| `--report <file>` | Write a self-contained snapshot report HTML file and exit. |
+
+See [Memory Graph Viewer](memory/MEMORYGRAPH.md) for details.
+
+## `phosphor cron`
+
+Runs the cron service for scheduled jobs. See
+[Scheduled Jobs](platform/SCHEDULED_JOBS.md) for job file format and management.
+
+## `phosphor job`
+
+| Subcommand | Description |
+| --- | --- |
+| `phosphor job add <name>` | Create a new job. |
+| `phosphor job list` | List all jobs. |
+| `phosphor job remove <name>` | Remove a job. |
+| `phosphor job edit <name>` | Edit a job. |
+
+## `phosphor acp`
+
+| Flag | Description |
+| --- | --- |
+| `--workspace <dir>` | Workspace directory (defaults to current directory). |
+
+## `phosphor bindings`
+
+Lists all available keybindings.
+
+## `phosphor dirs`
+
+Shows the config and data directories used by Phosphor.
+
+## `phosphor schema`
+
+Generates the JSON schema for `phosphor.json`.
diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md
@@ -513,11 +513,20 @@ the agent, and the cron scheduler for unattended runs:
       "port": 8643,
       "auth": { "type": "bearer", "key": "$PHOSPHOR_API_TOKEN" }
     },
+    "memory-graph": { "enabled": true, "host": "127.0.0.1", "port": 8644 },
     "cron": { "enabled": true, "jobs_directory": ".phosphor/jobs" }
   }
 }
 ```
 
+The `memory-graph` entry configures the memory vault viewer started with
+`phosphor memorygraph`. It is a standalone foreground server (like
+`phosphor cron`) on its own port — it does not depend on the OpenAI API
+service. The host and port fields above are the defaults. The viewer
+serves raw memory entries over plain HTTP, so it only accepts loopback
+hosts, and the command refuses to start when the entry sets
+`"enabled": false` (or omits it).
+
 Docs: [platform/openai-api.md](platform/openai-api.md),
 [platform/SCHEDULED_JOBS.md](platform/SCHEDULED_JOBS.md).
 

diff --git a/docs/INDEX.md b/docs/INDEX.md
@@ -9,6 +9,7 @@ searchable through the `phosphor_docs` tool or by viewing any
 | Doc | Covers |
 | --- | --- |
 | [CONFIGURATION.md](CONFIGURATION.md) | Where config files live per OS, merge order, and a snippet for every config section. Start here. |
+| [CLI.md](CLI.md) | Global flags, subcommands, and per-command options for the `phosphor` CLI. |
 | [CORE_PHILOSOPHY.md](CORE_PHILOSOPHY.md) | Identity and core pillars of the project. |
 | [KEYBINDINGS.md](KEYBINDINGS.md) | Default TUI key bindings and how to configure custom ones. |
 
@@ -53,6 +54,7 @@ searchable through the `phosphor_docs` tool or by viewing any
 | [memory/OVERVIEW.md](memory/OVERVIEW.md) | How the memory system works: vaults, the entry model, write/read paths, Tier A/B injection, config, `/memory`. |
 | [memory/INTEGRITY.md](memory/INTEGRITY.md) | The tamper seal: the HMAC key, what is signed vs. deliberately exempt, the threat model, key operations. |
 | [memory/POISONING.md](memory/POISONING.md) | The layered defenses against a poisoned memory entry reaching the system prompt. |
+| [memory/MEMORYGRAPH.md](memory/MEMORYGRAPH.md) | The memory graph viewer: live server, report export, host/port config, and node/edge semantics. |
 
 ## Extending the Agent
 

diff --git a/docs/memory/MEMORYGRAPH.md b/docs/memory/MEMORYGRAPH.md
@@ -0,0 +1,74 @@
+# Memory Graph Viewer
+
+`phosphor memorygraph` visualizes the memory vault as an interactive 2D
+constellation. Memory entries are nodes colored by type; threads and tags
+become hub nodes that cluster related entries together.
+
+## Run the live viewer
+
+```bash
+phosphor memorygraph
+```
+
+The command starts a local HTTP server and prints the viewer URL:
+
+```
+Phosphor Memory Graph Viewer
+============================
+Open http://127.0.0.1:8644/view.html
+
+Press Ctrl+C to stop.
+```
+
+The viewer polls the graph data endpoint every 10 seconds, so new memory
+entries appear without restarting. Press `Ctrl+C` to stop the server.
+
+## Export a snapshot report
+
+```bash
+phosphor memorygraph --report report.html
+```
+
+This writes a single self-contained HTML file that embeds the current graph
+payload and opens offline with no server or polling. The exported report is
+static: it shows the graph as it existed at export time.
+
+## Host and port
+
+The viewer defaults to `127.0.0.1:8644`. You can override it in
+`phosphor.json`:
+
+"""json
+{
+  "services": {
+    "memory-graph": {
+      "enabled": true,
+      "host": "127.0.0.1",
+      "port": 8644
+    }
+  }
+}
+"""
+
+The viewer uses its own port so it works regardless of whether the
+OpenAI-compatible API service is enabled. If the "memory-graph" entry
+exists with ""enabled": false" (or omitted), "phosphor memorygraph"
+refuses to start. The viewer serves raw memory entries to any client
+that can reach the port, so only loopback hosts ("127.0.0.1", "::1",
+"localhost") are accepted.
+
+## What the viewer shows
+
+- **Nodes**: memory entries (decisions, constraints, references, etc.) plus
+  thread and tag hubs.
+- **Edges**: relationships such as `supersedes`, `decision`, `thread`, and
+  `tag`.
+- **Side panel**: click a node to view its id, type, trust, recall, dates,
+  tags, body, and linked nodes.
+- **Search**: press `/` to focus the search box, type to filter nodes, and
+  press `Enter` to jump to the top-scoring match.
+
+## Related docs
+
+- [Memory Overview](OVERVIEW.md) — how the memory vault and index work.
+- [CLI Reference](../CLI.md) — global flags and all commands.