docs

.claude/skills/changelog/watermark

@@ -1 +1 @@
-ed651dcd571699e92162cf657b8eca42d7a6d6b1
+6c53fc29b5f1309bfd026a883a23006db2bb441c

.claude/skills/docs/watermark

@@ -1 +1 @@
-1afa8419b53670f95c5d6a041cfd373c4a8c9371
+6c53fc29b5f1309bfd026a883a23006db2bb441c

docs/administration/server-configuration.mdx

@@ -102,8 +102,8 @@ Several `settings.toml` settings can be overridden via `fabro server start` flag
 
 | Flag | Default | Description |
 |---|---|---|
-| `--port` | `3000` | Port to listen on |
-| `--host` | `127.0.0.1` | Host address to bind to |
+| `--bind` | `~/.fabro/fabro.sock` | Address to bind: `host:port` for TCP, or a path for Unix socket |
+| `--foreground` | — | Run in the foreground instead of daemonizing |
 | `--model` | — | Override default LLM model |
 | `--provider` | — | Override default LLM provider |
 | `--sandbox` | — | Override default sandbox provider |

docs/changelog/2026-03-30.mdx

@@ -0,0 +1,46 @@
+---
+title: "CLI restructuring, shell completions, and API versioning"
+date: "2026-03-30"
+---
+
+## CLI command restructuring
+
+The CLI command tree has been reorganized for consistency and discoverability. Sandbox-related commands (`cp`, `ssh`, `preview`) now live under `fabro sandbox`, the server command is now `fabro server start`, settings are shown with `fabro settings`, and the deprecated `fabro init` command has been removed.
+
+<Warning>
+**Breaking CLI changes.** Several commands have moved or been renamed:
+
+- `fabro serve` → `fabro server start`
+- `fabro config show` → `fabro settings`
+- `fabro cp` → `fabro sandbox cp`
+- `fabro ssh` → `fabro sandbox ssh`
+- `fabro preview` → `fabro sandbox preview`
+- `fabro init` has been removed
+</Warning>
+
+## Shell completions
+
+You can now generate shell completions for Bash, Zsh, Fish, Elvish, and PowerShell using the new `fabro completion` subcommand.
+
+```bash
+fabro completion zsh > ~/.zfunc/_fabro
+```
+
+<Warning>
+**API routes versioned.** All REST API routes are now prefixed with `/api/v1`. Update any direct API integrations accordingly.
+</Warning>
+
+## More
+
+<Accordion title="CLI">
+- Added `fabro completion` subcommand for Bash, Zsh, Fish, Elvish, and PowerShell
+- Added help text snapshots for all subcommands
+</Accordion>
+
+<Accordion title="Improvements">
+- Typed `RunId` used consistently across the codebase
+</Accordion>
+
+<Accordion title="Fixes">
+- Fixed cli-table ignoring `NO_COLOR` environment variable
+</Accordion>

docs/changelog/2026-03-31.mdx

@@ -0,0 +1,25 @@
+---
+title: "Global JSON output mode"
+date: "2026-03-31"
+---
+
+## Global JSON output mode
+
+Every CLI command now supports a `--json` flag for machine-readable output. Previously, only a few commands had JSON variants. Now you can pipe any Fabro command into `jq` or feed it directly into scripts and CI pipelines.
+
+```bash
+fabro runs list --json | jq '.[].id'
+fabro system df --json
+fabro preflight --json
+```
+
+## More
+
+<Accordion title="Workflows">
+- Stale git worktrees are now pruned automatically before branch creation in worktree sandboxes
+</Accordion>
+
+<Accordion title="Fixes">
+- Fixed `logs --follow` timing out on long-running runs due to slow manifest polling
+- Fixed rewind snapshot filtering when using short commit SHAs
+</Accordion>

docs/changelog/2026-04-01.mdx

@@ -0,0 +1,24 @@
+---
+title: "Server-backed web dashboard and event-sourced run state"
+date: "2026-04-01"
+---
+
+## Server-backed web dashboard
+
+The Fabro web app is now a single-page application served directly by the Fabro server. Previously, the frontend required a separate Node.js server with server-side rendering. Now `fabro server start` serves both the API and the web dashboard from the same origin, simplifying deployment and eliminating the need for a separate frontend process.
+
+## Event-sourced run state
+
+Run state is now fully derived from events rather than written to disk as independent files. This means runs are more reliable, resumable, and inspectable — every piece of run metadata (status, provider info, checkpoints, PR data) is reconstructed from the event stream. The legacy SQLite metadata store and file-based projections have been retired.
+
+## More
+
+<Accordion title="Improvements">
+- `unsafe_code` is now denied workspace-wide for security hardening
+- Dry-run mode no longer activates automatically when LLM providers are missing — runs now fail explicitly, making misconfiguration easier to diagnose
+</Accordion>
+
+<Accordion title="Fixes">
+- Fixed `attach` hanging on Linux when the workflow engine exits before the attach process starts
+- Fixed login route collision after the SPA cutover
+</Accordion>

docs/changelog/2026-04-02.mdx

@@ -0,0 +1,24 @@
+---
+title: "Background server daemon"
+date: "2026-04-02"
+---
+
+## Background server daemon
+
+The Fabro server now runs as a managed background daemon instead of requiring a dedicated terminal tab. `fabro server start` launches the daemon in the background with file-lock-based lifecycle management, and `fabro server stop` shuts it down gracefully. The daemon listens on a Unix socket by default for fast local communication.
+
+```bash
+fabro server start          # launch background daemon
+fabro server status         # check running state, PID, uptime
+fabro server status --json  # machine-readable status
+fabro server stop           # graceful shutdown
+fabro server start --foreground  # old blocking behavior
+```
+
+The `--bind` flag replaces the previous `--host`/`--port` flags and supports both Unix sockets and TCP addresses.
+
+## More
+
+<Accordion title="Improvements">
+- Workflow state is now fully derivable from events, making run replay and debugging more reliable
+</Accordion>

docs/changelog/2026-04-04.mdx

@@ -0,0 +1,20 @@
+---
+title: "Run lifecycle API refinement"
+date: "2026-04-04"
+---
+
+## Separate run create and start
+
+The `POST /api/v1/runs` endpoint now creates a run in `submitted` status without immediately queuing it. A new `POST /api/v1/runs/{id}/start` endpoint transitions the run to `queued` and notifies the scheduler. This two-step lifecycle gives API consumers more control — you can inspect or modify a run's configuration between creation and execution.
+
+## More
+
+<Accordion title="API">
+- `POST /api/v1/runs` now returns a run in `submitted` status
+- New `POST /api/v1/runs/{id}/start` endpoint queues a submitted run for execution
+- Removed unused `GET /api/v1/runs/{id}/context` endpoint
+</Accordion>
+
+<Accordion title="Improvements">
+- Run artifacts are now stored as blobs in the run store instead of on disk
+</Accordion>

docs/changelog/2026-04-06.mdx

@@ -0,0 +1,28 @@
+---
+title: "System management API"
+date: "2026-04-06"
+---
+
+## System management API
+
+New server-backed system commands give you visibility into Fabro's operational state through both the CLI and the REST API. `fabro system info` reports server version, uptime, and run counts. `fabro system events` streams the global event log. `fabro system df` and `fabro system prune` now route through the server for consistent behavior across local and remote setups.
+
+```bash
+fabro system info           # server version, uptime, run counts
+fabro system info --json    # machine-readable
+fabro system events         # global event stream
+fabro system prune          # clean up completed runs
+```
+
+## More
+
+<Accordion title="API">
+- New `GET /api/v1/system/info` endpoint returns server version, uptime, and run statistics
+- New `GET /api/v1/system/events` endpoint streams the global event log via SSE
+- New `GET /api/v1/system/df` endpoint returns disk usage by run
+- New `POST /api/v1/system/prune` endpoint removes completed run data
+</Accordion>
+
+<Accordion title="Improvements">
+- Settings and model commands now route through the server daemon for consistency
+</Accordion>

docs/docs.json

@@ -268,10 +268,22 @@
         "tab": "Changelog",
         "icon": "clock-rotate-left",
         "groups": [
+          {
+            "group": "April 2026",
+            "icon": "clock-rotate-left",
+            "pages": [
+              "changelog/2026-04-06",
+              "changelog/2026-04-04",
+              "changelog/2026-04-02",
+              "changelog/2026-04-01"
+            ]
+          },
           {
             "group": "March 2026",
             "icon": "clock-rotate-left",
             "pages": [
+              "changelog/2026-03-31",
+              "changelog/2026-03-30",
               "changelog/2026-03-29",
               "changelog/2026-03-28",
               "changelog/2026-03-27",

docs/reference/cli.mdx

@@ -217,19 +217,42 @@ fabro rm my-workflow --force
 | `<RUN>...` | Run IDs or workflow names to remove (required, repeatable) |
 | `-f, --force` | Force removal of active runs |
 
+## `fabro system info`
+
+Show server runtime information including version, uptime, and run counts.
+
+```bash
+fabro system info
+fabro system info --json
+```
+
+## `fabro system events`
+
+Stream run events from the server in real time.
+
+```bash
+fabro system events
+fabro system events --run-id abc123
+```
+
+| Flag | Description |
+|---|---|
+| `--run-id <ID>` | Filter by run ID (repeatable) |
+
 ## `fabro system prune`
 
 Delete old workflow runs. Dry-run by default — pass `--yes` to actually delete.
 
 ```bash
 fabro system prune --before 2026-01-01
-fabro system prune --before 2026-01-01 --yes
+fabro system prune --older-than 7d --yes
 fabro system prune --orphans --yes
 ```
 
 | Flag | Description |
 |---|---|
 | `--before <DATE>` | Only prune runs started before this date (YYYY-MM-DD prefix match) |
+| `--older-than <DURATION>` | Only prune runs older than this duration (e.g. `24h`, `7d`). Default when no explicit filters are set: `24h` |
 | `--workflow <NAME>` | Filter by workflow name (substring match) |
 | `--label <KEY=VALUE>` | Filter by label (repeatable, AND semantics) |
 | `--orphans` | Include orphan directories (no `run.json`) |
@@ -299,18 +322,19 @@ fabro model test -m claude-sonnet-4-5
 
 ## `fabro server start`
 
-Start the HTTP API server that exposes the [REST API](/api-reference) for launching and managing workflow runs.
+Start the Fabro server daemon. By default, the server launches as a background process listening on a Unix socket. Use `--foreground` for the previous blocking behavior.
 
 ```bash
-fabro server start
-fabro server start --port 8080 --host 0.0.0.0
+fabro server start                                # background daemon on Unix socket
+fabro server start --bind 127.0.0.1:8080          # TCP on a specific port
+fabro server start --foreground                   # blocking foreground mode
 fabro server start --sandbox daytona --max-concurrent-runs 4
 ```
 
 | Flag | Description | Default |
 |---|---|---|
-| `--port <PORT>` | Port to listen on | `3000` |
-| `--host <HOST>` | Host address to bind to | `127.0.0.1` |
+| `--bind <ADDR>` | Address to bind: `host:port` for TCP, or a path for Unix socket | `~/.fabro/fabro.sock` |
+| `--foreground` | Run in the foreground instead of daemonizing | — |
 | `--model <MODEL>` | Override default LLM model | — |
 | `--provider <PROVIDER>` | Override default LLM provider | — |
 | `--dry-run` | Execute with simulated LLM backend | — |
@@ -320,7 +344,31 @@ fabro server start --sandbox daytona --max-concurrent-runs 4
 
 Demo mode is per-request: send the `X-Fabro-Demo: 1` header to get static demo data with auth disabled.
 
-If no LLM provider API keys are configured, the server automatically falls back to dry-run mode.
+## `fabro server stop`
+
+Stop the running server daemon. Sends SIGTERM and waits for graceful shutdown, escalating to SIGKILL after the timeout.
+
+```bash
+fabro server stop
+fabro server stop --timeout 30
+```
+
+| Flag | Description | Default |
+|---|---|---|
+| `--timeout <SECONDS>` | Seconds to wait for graceful shutdown before SIGKILL | `10` |
+
+## `fabro server status`
+
+Show whether the server daemon is running, along with PID, bind address, and uptime.
+
+```bash
+fabro server status
+fabro server status --json
+```
+
+| Flag | Description |
+|---|---|
+| `--json` | Output as JSON |
 
 ---
 

docs/reference/run-directory.mdx

@@ -4,7 +4,7 @@ description: "Structure of Fabro's per-run directory"
 ---
 
 <Warning>
-  The run directory structure and file formats described here are internal implementation details and subject to change without notice. Do not build tooling that relies on them.
+  The run directory structure and file formats described here are internal implementation details and subject to change without notice. Do not build tooling that relies on them. The authoritative source of run state is the event-sourced run store — files in the scratch directory are disk projections for debugging convenience.
 </Warning>
 
 Each `fabro run` invocation creates a timestamped directory under `~/.fabro/scratch/`: