Rename the last stale workflow test helpers and assertions that still used
pre-refactor checkpoint/retro file terminology, and update the retro docs
to describe the exported layout that now exists.
Implements the plan at
docs/plans/2026-04-20-003-refactor-unify-run-vocabulary-metadata-plan.md.
- Rename RunRecord to RunSpec and RunProjection.run to .spec everywhere
in Rust source, tests, helpers, test names, and error messages.
- Introduce SerializableProjection wrapper that trims bulky node text
fields (prompt, response, diff, stdout, stderr) for run.json snapshots.
- Collapse metadata-branch and CLI export to one RunDump::from_projection
builder emitting run.json + graph.fabro + stages/{stage_id}/... and
drop legacy top-level start/status/checkpoint/sandbox/retro/conclusion
split files.
- Replace MetadataStore::write_checkpoint with write_snapshot returning
the commit SHA; add read_run_projection/read_run_spec; demote
read_checkpoint/read_start_record to projection-field extractors.
- Switch fork, rewind, rebuild_meta, CLI rewind recovery, and retro
upload to read the unified projection layout.
- Add additive query methods on RunSpec and RunProjection.
Serde-level `alias = "spec"` shim dropped; `rename = "run"` retained to
keep the server API wire format stable per the plan's scope boundary.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Keep project config and checked-in workflows under .fabro so they stay out of
normal repo listings. Update config discovery, CLI project commands, fixtures,
docs, and checked-in workflow paths to use .fabro/project.toml and
.fabro/workflows/*.
Rewrite every docs/ reference and integration guide example that
previously showed legacy flat TOML (`[llm]`, `[vars]`, `[sandbox]`,
`[setup]`, `[exec]`, `[fabro]`, `[pull_request]`, `[mcp_servers]`,
`[git]`, `[web]`, `[api]`, `[features] retros`, `version = 1`,
top-level `storage_dir`) to use the v2 namespaced schema. Also update
the surrounding prose to describe v2 merge semantics (R22 run.inputs
wholesale replacement, R71 sticky sandbox.env/labels, R30 whole-list
prepare.steps replacement, hook id-based replacement).
Files touched:
- docs/reference/user-configuration.mdx (complete rewrite around
[cli.*] ownership, [run.*] run-scoped defaults, [cli.target] /
[cli.exec] / [cli.output] / [cli.updates] / [cli.logging], and
[run.agent.mcps.<name>] with durations like "10s")
- docs/reference/cli.mdx (settings.toml example uses [cli.exec.*],
[run.model], [cli.target])
- docs/execution/run-configuration.mdx (full run-config example
rewritten to use [workflow].graph, [run].goal/working_dir,
[run.model], [run.prepare.steps], [run.sandbox.daytona.snapshot]
with Size values, [run.inputs], [run.artifacts], [run.agent.mcps],
[run.pull_request], [[run.hooks]] with optional id and duration
timeout; section docs explain the new merge semantics)
- docs/execution/environments.mdx and devcontainers.mdx (sandbox
examples now use [run.sandbox.*])
- docs/execution/retros.mdx (retros moved to [run.execution] retros
= true per R31)
- docs/execution/failures.mdx (fallbacks now a single ordered array
under [run.model].fallbacks)
- docs/workflows/variables.mdx ([vars] → [run.inputs], wholesale
replacement semantics explained)
- docs/administration/server-configuration.mdx (full reference
rewritten around [server.listen]/[server.api]/[server.web]/
[server.auth]/[server.storage]/[server.scheduler]/[server.logging]/
[server.integrations])
- docs/api-reference/overview.mdx (auth strategies now enabled via
[server.auth.api.jwt].enabled and [server.auth.api.mtls].enabled;
listener TLS moved to [server.listen.tls])
- docs/integrations/daytona.mdx, github.mdx (provider config now
nested under [run.sandbox.daytona] / [server.integrations.github])
- docs/human-tools/ssh-access.mdx (sandbox examples to v2)
- docs/agents/mcp.mdx (Playwright sandbox example to [run.agent.mcps])
- docs/core-concepts/models.mdx (model config and fallbacks array to
[run.model])
Canonical fabro-cli overrides and server run_manifest now emit
verbose via [cli.output].verbosity = verbose rather than the prior
run.metadata staging. No code changes beyond those Stage 4 fixes that
were already in flight.
Drop scratch-only compatibility paths and legacy test scaffolding now that
SlateDB-backed state is authoritative. This removes scratch file fallbacks,
updates docs and UI labels, and moves tests onto durable store-backed helpers.
Consolidate CLI and server machine defaults under settings.toml,
including loader renames, writer preservation fixes, same-machine
manifest handling, and docs/test updates for the new config model.
Introduce two new persistence types aligned to the CREATE/START lifecycle:
- RunRecord (run.json): written at CREATE with merged FabroConfig, fully
transformed Graph, and run metadata
- StartRecord (start.json): written at START with start_time, run_branch,
and base_sha
All readers (run_lookup, inspect, diff, pr, attach, detached_support,
start, run_fork, pull_request, run_rewind, resume) now read from the
new types first. Legacy manifest.json + spec.json are still written
for backward compatibility (removal in follow-up).
Also adds dry_run, auto_approve, no_retro fields to FabroConfig, derives
Default on LlmConfig and Graph, and updates docs + tests.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Move retro control from [fabro] retro to [features] retros in project
config. Default changes from true to false — retros are now opt-in.
Add retros field to server config Features struct, OpenAPI spec,
TypeScript client, and web app config. Update docs with experimental
warning and new enablement instructions.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Update 47 MDX doc pages, OpenAPI spec, SVG diagram, language
grammar, frontend demo data, marketing page, skills, and README
to use .fabro extension. Add "fabro" to fileTypes in language
grammars. Document stack.child_workflow alongside stack.child_dotfile.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Add 10 screenshots of the Fabro web UI to docs pages (workflows, runs,
retros, observability, steering)
- Update arc-web logos from Arc to Fabro (logotype.svg, logotype-light.svg)
- Hide Start and Settings nav items in arc-web for cleaner screenshots
- Mount arc-web public/ as Docker volume for logo hot-swapping
- Combine "Run agents 24/7" and "Scale infinitely" use cases
- Replace clone-and-build Quick Start with curl installer from README
- Add internal docs for updating web screenshots
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Per-run data now lives in ~/.arc/runs/ while daily CLI log files
stay in ~/.arc/logs/. Renames: logs_root → run_dir (RunConfig field,
Handler trait param, all handlers), logs_dir → run_dir (CLI arg,
local variables), default_logs_base → default_runs_base (path fn).
Adds DB migration 002 to rename workflow_runs.logs_dir → run_dir.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Enrich the entire OpenAPI spec with descriptions, examples, format
annotations, extracted parameters, discriminated unions, and richer
response schemas — matching the patterns already established for
Sessions.
Structural changes:
- Extract CancelRunResponse and SteerRunResponse from inline schemas
- Change POST /runs/{id}/steer from 200 to 202 (async fire-and-forget)
- Split StageTurn into discriminated union (SystemStageTurn,
AssistantStageTurn, ToolStageTurn) with oneOf + discriminator
- Add status + created_at to StartRunResponse
- Add created_at to RunListItem and RunStatusResponse
- Add created_at + updated_at to SavedQuery
- Add format: date-time on RetroListItem.timestamp
- Extract 7 new reusable parameters (StageId, QuestionId, WorkflowName,
VerificationSlug, InsightQueryId, ProjectId, CheckpointFilter)
- Enrich existing RunId, PageLimit, PageOffset parameters
- Add descriptions + examples to all ~66 schemas and ~200+ properties
- Add operation descriptions to all ~35 endpoints
Rust handler updates:
- Change ManagedRun.created_at from Instant to chrono::DateTime<Utc>
- Populate new fields in StartRunResponse, RunStatusResponse
- Use new StageTurn discriminated union variants in demo data
- Update demo data timestamps to use DateTime<Utc>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- Add DaytonaNetwork enum (block/allow_all/allow_list) with custom serde
Deserialize for TOML string-or-table syntax
- Wire network config through run_config defaults merging and base_params
- Document network access in sandboxing, environments, and run-configuration
- Fill in execution docs: checkpoints, environments, failures, interviews,
run configuration, observability, retros
- Rename compounding.mdx → retros.mdx, insights.mdx → observability.mdx
- Use DaytonaConfig::default() in tests to reduce boilerplate
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
