From aee3de78a2cc258998e57be0abcf2c7997905a79 Mon Sep 17 00:00:00 2001 From: Bryan Helmkamp Date: Sun, 15 Mar 2026 20:13:23 -0400 Subject: [PATCH] Docs updates: reorder nav, rename DOT Language, simplify dark factory, add fork/upgrade/asset docs - Move Comparison link below Troubleshooting in nav - Rename "DOT Language" page to "Fabro Language" - Remove five-tier table from dark factory page, keep link to Dan Shapiro's post - Add fork command docs and checkpoints section - Add upgrade, asset list, asset cp command docs - Add upgrade_check config reference - Add retros feature flag to server config Co-Authored-By: Claude Opus 4.6 (1M context) --- .claude/skills/docs/watermark | 2 +- docs/docs.json | 2 +- docs/execution/checkpoints.mdx | 19 +++++++ docs/getting-started/dark-factory.mdx | 13 +---- docs/reference/cli-configuration.mdx | 12 +++++ docs/reference/cli.mdx | 77 +++++++++++++++++++++++++++ docs/reference/dot-language.mdx | 2 +- lib/crates/fabro-config/src/server.rs | 3 ++ 8 files changed, 115 insertions(+), 15 deletions(-) diff --git a/.claude/skills/docs/watermark b/.claude/skills/docs/watermark index 05531e77e..08130de4b 100644 --- a/.claude/skills/docs/watermark +++ b/.claude/skills/docs/watermark @@ -1 +1 @@ -ec0a612ea531fcf53383afb15ad23561a7bbe6ae +49379f08d0f26d38c25f036738c4a85cddd7a323 diff --git a/docs/docs.json b/docs/docs.json index ddf1ed539..de6eaf128 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -102,7 +102,6 @@ "group": "Reference", "icon": "book", "pages": [ - "getting-started/comparison", "reference/dot-language", "reference/cli", "reference/cli-configuration", @@ -110,6 +109,7 @@ "reference/architecture", "administration/server-configuration", "administration/troubleshooting", + "getting-started/comparison", "administration/security", "reference/acknowledgements" ] diff --git a/docs/execution/checkpoints.mdx b/docs/execution/checkpoints.mdx index a2968534f..1a5568b8a 100644 --- a/docs/execution/checkpoints.mdx +++ b/docs/execution/checkpoints.mdx @@ -168,6 +168,25 @@ fabro run --run-branch fabro/run/ See [`fabro rewind`](/reference/cli#fabro-rewind) for the full command reference. +## Forking a run + +If you want to explore an alternate path from a checkpoint without losing the original run's history, use `fabro fork` instead of `fabro rewind`. Fork creates a new independent run branching from the target checkpoint — the original run stays intact. + +```bash +# List checkpoints +fabro fork --list + +# Fork from a specific checkpoint +fabro fork plan@2 + +# Resume the forked run +fabro run --run-branch fabro/run/ +``` + +Use **rewind** when you want to redo a run from an earlier point (destructive — resets the original). Use **fork** when you want to try a different approach while keeping the original run as a reference. + +See [`fabro fork`](/reference/cli#fabro-fork) for the full command reference. + ## When checkpointing is active Git checkpointing activates automatically when: diff --git a/docs/getting-started/dark-factory.mdx b/docs/getting-started/dark-factory.mdx index 1664860b9..75b2ad77c 100644 --- a/docs/getting-started/dark-factory.mdx +++ b/docs/getting-started/dark-factory.mdx @@ -11,18 +11,7 @@ This is an aspirational concept, and getting there is iterative. ## From coding to orchestrating -Dan Shapiro's [five-level framework](https://www.danshapiro.com/blog/2026/01/the-five-levels-from-spicy-autocomplete-to-the-software-factory/) describes the progression from AI-assisted coding to autonomous software production: - -| Level | Name | Human role | -|-------|------|------------| -| 0 | Spicy Autocomplete | Copy/paste from chat | -| 1 | Coding Intern | AI writes boilerplate; human reviews everything | -| 2 | Junior Developer | Pair programming with AI | -| 3 | Developer | Most code is AI-generated; human is a full-time reviewer | -| 4 | Engineering Team | Human manages specs and plans; agents do the work | -| 5 | Dark Software Factory | Specs go in, software comes out | - -Most teams today operate at Level 2–3: AI writes code, humans review it line by line. The transition from Level 3 to Level 4 is the hardest — it requires replacing ad-hoc human review with structured, repeatable verification that you actually trust. +Most teams today have AI writing code while humans review it line by line. The hardest transition is moving beyond that — replacing ad-hoc human review with structured, repeatable verification that you actually trust. Dan Shapiro's [five-level framework](https://www.danshapiro.com/blog/2026/01/the-five-levels-from-spicy-autocomplete-to-the-software-factory/) describes this progression well. ## What makes it work diff --git a/docs/reference/cli-configuration.mdx b/docs/reference/cli-configuration.mdx index a1404936b..382efed3a 100644 --- a/docs/reference/cli-configuration.mdx +++ b/docs/reference/cli-configuration.mdx @@ -21,6 +21,7 @@ CLI flags always take the highest priority: ```toml title="cli.toml" verbose = true +upgrade_check = true mode = "server" [server] @@ -69,6 +70,17 @@ Authorization = "Bearer sk-xxx" All fields are optional. You can include just the sections and keys you want to override. +## `upgrade_check` + +Controls whether Fabro runs a daily background check for new releases. The check runs during `run`, `exec`, `init`, and `install` commands and prints a notice to stderr when a newer version is available. + +| Value | Description | +|---|---| +| `true` | Check for new releases (default) | +| `false` | Disable automatic upgrade checks | + +The `--no-upgrade-check` CLI flag overrides this for a single invocation. See [`fabro upgrade`](/reference/cli#fabro-upgrade) for manual upgrades. + ## `verbose` Enable verbose output by default for `fabro run start` and `fabro doctor`, without passing `-v` every time. diff --git a/docs/reference/cli.mdx b/docs/reference/cli.mdx index 4b5a77a56..74cdb12ea 100644 --- a/docs/reference/cli.mdx +++ b/docs/reference/cli.mdx @@ -10,6 +10,7 @@ These flags apply to all subcommands: | Flag | Description | |---|---| | `--debug` | Enable DEBUG-level logging (default is INFO) | +| `--no-upgrade-check` | Skip the automatic background upgrade check | | `-h, --help` | Print help | | `-V, --version` | Print version | @@ -424,6 +425,30 @@ fabro run --run-branch fabro/run/ See [Checkpoints](/execution/checkpoints#rewinding-to-an-earlier-checkpoint) for background on how checkpointing works. +## `fabro fork` + +Fork a new run from an existing run's checkpoint. Unlike `fabro rewind`, which resets the original run in place, `fabro fork` creates an independent copy — the original run stays intact. + +```bash +fabro fork [TARGET] +fabro fork --list +``` + +| Argument / Flag | Description | +|---|---| +| `` | Run ID or unambiguous prefix (required) | +| `[TARGET]` | Checkpoint to fork from: node name, `node@visit`, or `@ordinal` (1-based). Omit to fork from the latest checkpoint. | +| `--list` | Show the checkpoint timeline instead of forking | +| `--no-push` | Skip pushing new branches to the remote | + +Target formats are the same as [`fabro rewind`](#fabro-rewind). After forking, resume the new run: + +```bash +fabro run --run-branch fabro/run/ +``` + +See [Checkpoints — Forking a run](/execution/checkpoints#forking-a-run) for when to use fork vs. rewind. + ## `fabro logs` View the event log of a workflow run. Runs can be referenced by ID prefix or workflow name (uses the most recent run). @@ -595,6 +620,58 @@ fabro doctor --dry-run | `-v, --verbose` | Show detailed information for each check | | `--dry-run` | Skip live service probes (LLM, sandbox, API, web, Brave Search) | +## `fabro upgrade` + +Download and install a newer version of Fabro from GitHub releases. Verifies the download with SHA256 checksums and atomically replaces the binary. + +```bash +fabro upgrade +fabro upgrade --dry-run +fabro upgrade --version 0.6.0 +``` + +| Flag | Description | +|---|---| +| `--version ` | Target version (e.g. `0.5.0` or `v0.5.0`). Defaults to the latest release. | +| `--force` | Upgrade even if already on the target version | +| `--dry-run` | Preview what would happen without making changes | + +Fabro refuses to downgrade unless you specify an explicit `--version`. A daily background check notifies you when a new version is available — disable it with `upgrade_check = false` in [`cli.toml`](/reference/cli-configuration#upgrade_check) or the `--no-upgrade-check` global flag. + +## `fabro asset list` + +List assets (screenshots, test reports, traces) collected from a workflow run. + +```bash +fabro asset list +fabro asset list --node verify --json +``` + +| Argument / Flag | Description | +|---|---| +| `` | Run ID or unambiguous prefix (required) | +| `--node ` | Filter to assets from a specific node | +| `--json` | Output as JSON | + +## `fabro asset cp` + +Copy assets from a workflow run to the local filesystem. + +```bash +fabro asset cp ./output # all assets, flat +fabro asset cp ./output --tree # preserve directory structure +fabro asset cp :report.html ./output # specific file +``` + +| Argument / Flag | Description | +|---|---| +| `` | `RUN_ID` (all assets) or `RUN_ID:path` (specific file) | +| `[DEST]` | Destination directory (defaults to `.`) | +| `--node ` | Filter to assets from a specific node | +| `--tree` | Preserve `{node}/{retry}/` directory structure | + +When copying all assets in flat mode, filenames must be unique across nodes. Use `--tree` or `--node` to disambiguate. + ## `fabro install` Interactive setup wizard that walks you through configuring API keys and validating your environment. Runs `fabro doctor` with live probes after setup to validate the configuration. diff --git a/docs/reference/dot-language.mdx b/docs/reference/dot-language.mdx index af32eb6da..e5c08ee66 100644 --- a/docs/reference/dot-language.mdx +++ b/docs/reference/dot-language.mdx @@ -1,5 +1,5 @@ --- -title: "DOT Language" +title: "Fabro Language" description: "Complete reference for Fabro's DOT workflow language" --- diff --git a/lib/crates/fabro-config/src/server.rs b/lib/crates/fabro-config/src/server.rs index 0a226761b..717fb6d46 100644 --- a/lib/crates/fabro-config/src/server.rs +++ b/lib/crates/fabro-config/src/server.rs @@ -118,6 +118,9 @@ impl Default for WebConfig { pub struct Features { #[serde(default)] pub session_sandboxes: bool, + /// Experimental: enable automatic retro generation after workflow runs. + #[serde(default)] + pub retros: bool, } #[derive(Clone, Debug, Default, Deserialize, PartialEq, Serialize)]