From c7787e3d31152ff4fcffcc2177a0bf0d1fb7d30d Mon Sep 17 00:00:00 2001 From: Bryan Helmkamp Date: Sat, 4 Apr 2026 00:00:25 -0700 Subject: [PATCH] docs: clarify file-backed artifact docs Update the run directory, context, and output docs to describe large offloaded values as file-backed artifacts while preserving the existing cache path examples. --- docs/agents/outputs.mdx | 6 +++--- docs/execution/context.mdx | 2 +- docs/reference/run-directory.mdx | 2 +- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/agents/outputs.mdx b/docs/agents/outputs.mdx index 2cbb143f1..b7d397afc 100644 --- a/docs/agents/outputs.mdx +++ b/docs/agents/outputs.mdx @@ -136,7 +136,7 @@ When a stage produces a large context value -- an LLM response, command output, ### How offloading works -After each node completes, Fabro checks every context update. If the serialized JSON of a value exceeds **100KB**, it is written to the artifact store on disk and replaced in the context with a `file://` pointer: +After each node completes, Fabro checks every context update. If the serialized JSON of a value exceeds **100KB**, it is written to a file-backed artifact on disk and replaced in the context with a `file://` pointer: ``` response.plan --> file:///path/to/logs/cache/artifacts/values/response.plan.json @@ -145,7 +145,7 @@ command.output --> file:///path/to/logs/cache/artifacts/values/command.output.j Values under 100KB remain in the context as-is. -### Artifact storage layout +### File-backed artifact layout Offloaded artifacts are written to the run's directory: @@ -192,7 +192,7 @@ fabro/meta/{run_id} command.output.json ``` -This means artifact data survives process restarts and can be recovered when resuming a run from a Git branch. +This means file-backed artifact data survives process restarts and can be recovered when resuming a run from a Git branch. ## Remote sandbox syncing diff --git a/docs/execution/context.mdx b/docs/execution/context.mdx index 40b50b75c..8abc4f85b 100644 --- a/docs/execution/context.mdx +++ b/docs/execution/context.mdx @@ -196,7 +196,7 @@ Internal keys (prefixed with `internal.`, `current`, `graph.`, `thread.`, `respo ## Artifact offloading -When a stage produces a large output (over 100KB of serialized JSON), Fabro automatically offloads it to the **artifact store** on disk rather than keeping it in the in-memory context. The context value is replaced with a `file://` pointer: +When a stage produces a large output (over 100KB of serialized JSON), Fabro automatically offloads it to a file-backed artifact on disk rather than keeping it in the in-memory context. The context value is replaced with a `file://` pointer: ``` response.plan → file:///tmp/logs/cache/artifacts/values/response.plan.json diff --git a/docs/reference/run-directory.mdx b/docs/reference/run-directory.mdx index dcbd6ac72..0d0b8f495 100644 --- a/docs/reference/run-directory.mdx +++ b/docs/reference/run-directory.mdx @@ -73,7 +73,7 @@ Manager nodes that run sub-workflows write a nested `child/` directory containin **`cache/`** — Local filesystem cache for file-backed artifacts and captured test assets: -- `cache/artifacts/values/` — large context values offloaded from checkpoints +- `cache/artifacts/values/` — large context values offloaded to file-backed artifacts - `cache/artifacts/assets/` — captured test artifacts organized by node and retry ## Browsing runs