DocsFab Runner Quickstart

docsfab do --delegate is a named opt-in pilot. Bare do still classifies one sentence onto a catalog workflow. --delegate is not a new default.

docsfab do --delegate \
  "Which flag enables JSON output?" \
  --repo /absolute/path/to/input-repository \
  --no-input --json

The result for this ordinary-question form prints to stdout as JSON; it does not open a merge request or write to the repository.

The pilot starts a fresh finite task on the committed HEAD. Record answers for that exact task with --resume <task-id> --answers <json-file>. That records answers and continues the delegated driver for the same task id. The task stays needs-input until that driver finishes. There is no most-recent lookup, TTY prompt, silent catalog fallback, or inherited grant. --allow-write requests local documentation changes. Until issues #758 and #779 land, that flag fail-closes with a typed nonzero result instead of silently completing a read-only run. Remote publication is unsupported. --route-only and --dry-run stay on catalog do and cannot combine with --delegate.

The pilot runs a check only when you name it. Each --check <npm-script> runs npm run <npm-script> in the repository after the driver finishes, and the script must be declared under scripts in the repository’s root package.json. Repeat the flag for each script. A request that says “run npm test” runs nothing by itself. A named check keeps the task from complete until it passes. A paused task keeps its checks, so pass the same --check flags again with --resume:

docsfab do --delegate "Review docs/api.md." \
  --repo /absolute/path/to/input-repository \
  --check docs:check --no-input --json

Refer to Delegated Do Pilot for supported flags, continuation, and terminal statuses.

Draft merge request delivery requires all of these conditions:

• The target repository has an origin remote (or --remote <name>).
• glab is authenticated for the GitLab host used by the selected remote.
• You have permission to push a branch and create a merge request.

Tracked local changes stay in place; delivery writes from GitLab’s target-branch revision, so a dirty checkout does not block --draft-mr. The workflow plans, writes, checks, verifies, reviews, and evaluates the new documentation. Default delivery creates a branch and opens one draft merge request after its prerequisites pass; it cannot merge the result. If the repository has no tracked .docsfab.json, DocsFab proposes a host-derived configuration in the same documentation change.

Use --dry-run to preview the named workflow without running it:

docsfab run create-documentation \
  --instruction "Create docs/install-troubleshooting.md, an installation troubleshooting guide for developers." \
  --dry-run

--dry-run stops before workflow steps, repository inspection, model calls, writes, or publication. It does not validate the target or authorize a later write, and it is not an end-to-end workflow test. --dry-run and --patch-only are separate modes and cannot be combined.

After you inspect the preview, generate the local patch with this command:

docsfab run create-documentation \
  --instruction "Create docs/install-troubleshooting.md, an installation troubleshooting guide for developers. Keep the result local; do not publish." \
  --patch-only

To open the default draft merge request instead, first satisfy the delivery prerequisites, remove any publication prohibition from the instruction, and run:

docsfab run create-documentation \
  --instruction "Create docs/install-troubleshooting.md, an installation troubleshooting guide for developers."

DocsFab can use its runtime checkout as the selected input repository and open a draft merge request through the same authorized delivery path as other GitLab repositories. Use --patch-only when you want to retain the result without publishing.

The September 14, 2026 request below is a historical example, not a first-run requirement. Replace its date, branch, and time zone with the scope of your actual update.

When you already have the changed files and current pages, bind them with --reader-source on docsfab run update-documentation. Refer to Update Documentation Beside a Change in DocsFab. Do not add --reader-source to docsfab do.

Use update-documentation without those bindings when merged merge requests should drive the update and you do not want to enumerate MR numbers, SHAs, or --reader-source paths. Name the merge requests, the branch they merged into, the calendar day, and the IANA time zone. Keep the result local with --patch-only:

docsfab run update-documentation \
  --patch-only \
  --instruction "Review the MRs merged into main on September 14, 2026, using America/Los_Angeles time. Collect the related code changes and existing documentation. Identify changes affecting end users, including commands, configuration, defaults, installation, workflows, and observable behavior. Update only the affected user documentation, preserving unrelated content. Skip internal changes with no user impact. Report which MRs require documentation changes, what you updated, and any evidence gaps. If merge records or diffs are unavailable, report that limitation rather than claiming complete coverage."

DocsFab discovers merge requests whose merged_at timestamp falls in that civil day in the named zone, reads each MR’s diffs, and produces a grounded documentation patch or an evidence-backed no-change result. Planner, writer, and verifier receive those diffs as bound source reads. A 23-hour or 25-hour daylight saving day still counts as that calendar date. --patch-only does not apply the patch to your checkout or open a merge request. If GitLab evidence is unavailable, the run reports the limitation instead of claiming complete coverage.

When the update must follow a tracked release note, specification, or exported document, bind that file with the repeatable --source flag. create-documentation and update-documentation accept it. DocsFab accepts these tracked source extensions: .diff, .docx, .htm, .html, .ipynb, .js, .json, .markdown, .md, .mdx, .patch, .pdf, .toml, .ts, .txt, .xhtml, .yaml, and .yml.

docsfab run update-documentation \
  --patch-only \
  --instruction "Update docs/retention.md for the new export limits." \
  --source docs/release-notes.html

Repeat the flag to bind more than one file. Each value is a repository-relative path, and the host reads the exact bytes at the selected revision through the tracked export, never your working tree. The host stops the run before any workflow model call when a selected path is not tracked at that revision, when no installed extractor claims its media type, or when it exceeds the admitted ceiling. Each stop names the failing condition and the change that clears it, and it binds nothing. Refer to Bind Tracked Source Evidence for the complete binding contract.

The planning, writing, verification, and review steps of an update receive the same host-issued reader for the bound spans, and every file you select is required evidence. Before it writes, the write step reads the part of each selected source that no earlier step read. A source that does not fit its source-read budget, 262,144 bytes by default and less for a model with a small input window, is read in part, and the run’s LIMITATIONS section names it with the bytes read out of its total.

One run carries one source binding, so --source does not combine with --resume-from, and on update-documentation it does not combine with the date-scoped instruction shown above, which mints its binding from the merge requests it discovers. Add --dry-run to parse the selection and stop before the host opens any source body:

docsfab run update-documentation \
  --instruction "Update docs/retention.md for the new export limits." \
  --source docs/release-notes.html \
  --dry-run

Name the GitLab merge request you are documenting with --pr, and the run is grounded on it. --mr is an exact alias, so GitLab users can write the word GitLab uses; pass either spelling, once. create-documentation and update-documentation accept it.

docsfab run update-documentation \
  --patch-only \
  --instruction "Update docs/export.md for the new output path." \
  --pr https://gitlab.example.com/team/project/-/merge_requests/813

Choose one of these merge request reference forms:

Before any model call, the host reads the merge request through your existing glab login to pin its commits. It reads the diff from this checkout’s objects or, when required objects are missing, from GitLab’s diff evidence. DocsFab never fetches Git objects. What else binds depends on the merge request’s state:

The host resolves the project path to its numeric project identifier, records both identities, and keys the evidence on the numeric one, so two projects that share a path cannot be confused for each other.

When local diff objects are missing, the run needs readable GitLab diff evidence or required objects that you fetch into the checkout. If both evidence paths are unavailable, it stops before any model call with change-source-mr-objects-unavailable. GitLab fallback is recorded as forge-reported and names missing local objects and gaps in the retained diff. It does not bypass other object damage or incomplete GitLab responses. Refer to GitLab Diff Fallback and Refusals for recovery commands and partial-clone requirements.

A host you name is used exactly as typed, including one that is not this checkout’s remote. The read uses your own glab login for that host. Confirm the destination and your read access before selecting it. The read goes to that host; nothing is rehosted. The binding records the host, canonical project path, numeric project identifier, and merge request number. The evidence identifies the forge it came from.

--change accepts the same merge request forms, except the bare number, and binds exactly what --pr binds. The two do not combine. Refer to Bind a GitLab Merge Request’s Diff for the diff each merge mode binds and every refusal.

--pr names one change, and --source names tracked files, so a run can carry both and the host binds both as required evidence:

docsfab run update-documentation \
  --instruction "Update docs/export.md for the new output path." \
  --patch-only \
  --pr !813 \
  --source docs/release-notes.html

The bound evidence records what it could not retain. When the merge request body is longer than the retained limit, the run records a truncation gap; when the body is absent, it records a missing-text gap. Neither stops the run, and both appear in the evidence the writer and verifier read, so a later claim cannot rest on text the run never held.

--pr does not combine with --resume-from, and on update-documentation it does not combine with the date-scoped instruction shown above: that instruction already selects its own merge requests, so naming one explicitly as well would leave two bases for one binding. Add --dry-run to parse the reference and stop before the host reads GitLab at all:

docsfab run update-documentation \
  --instruction "Update docs/export.md for the new output path." \
  --pr !813 \
  --dry-run

Add --json when an outer agent or continuous integration wrapper runs a workflow. Consume the single JSON object on stdout. Do not scrape the human footer or skill Markdown.

docsfab run create-documentation \
  --instruction "Create docs/install-troubleshooting.md, an installation troubleshooting guide for developers." \
  --patch-only \
  --json

When a run record exists, the result keeps schemaVersion: 1 and kind: "docsfab-run-result", including when an individual projected string is truncated to 512 characters. Inspect the quality limitations for truncated-projection-field.

Use product.findings as workflow outcome codes. For review workflows, and for authoring workflows with admitted issues, the root reviewFindings array holds path-bearing ReviewFindingV1 objects. Each object contains id, severity, code, summary, and a safe relative path or null. It can also contain line, origin, evidence, and recommendation. Findings projected from admitted review evidence use origin: "agent" and include evidence and a recommendation.

After a create, update, or restructure run, the human REVIEW FINDINGS section shows the same strictly admitted step findings, their projection availability, provenance, and limitations. These findings remain separate from the PRODUCT disposition. An inconclusive product outcome does not become a quality decision because review steps identified actionable issues. Authoring evaluation Markdown is not parsed into findings when validated quality artifacts are unavailable.

For standalone review workflows, read reviewFindingsProjection.availability before interpreting the array. complete makes an empty array a supported zero-findings result. partial means one or more review sources remain unavailable. unavailable means the required retained artifact is absent, and invalid means its integrity, schema, or run bindings failed. The projection also names its projector, retained artifact locator when available, and limitation codes. Inspect the retained report for limitations instead of scraping skill Markdown or rerunning inference.