Run a Documentation Workflow in DocsFab

Run one named DocsFab workflow against an immutable repository revision and inspect its saved result. For a persistent conversation, use the Live Agent Quickstart.

Prerequisites

Before you run a job, confirm the following prerequisites:

• Select the Git repository you want to document, which can be DocsFab itself.
• Install or build the CLI as described in Install DocsFab.
• Confirm Node.js 24.21.0 or later and that docsfab list shows the bound jobs.
• Select an immutable target repository revision and keep --repo pointed at that product.
• For explicit composition execution, configure the exact model ID and endpoint selected by an installed composition, and provide its credential through the host environment.

Read-only is the default for review. Create, update, and restructure write and open one draft merge request unless you pass --patch-only or --dry-run. Do not retry a blocked job with broader authority.

Choose a Job

Select the fixed catalog job that matches your intended outcome. Request text does not grant authority or let a model choose a different workflow. The following table maps each goal to its job.

create-documentation and restructure-documentation write Markdown and MDX pages, not reStructuredText (.rst) pages. update-documentation supports one narrow RST case: with --patch-only, it can replace or insert ordinary top-level prose in one existing tracked .rst page under an unambiguous Sphinx root. The patch preserves every other page byte. RST creation, restructuring, and edits inside directive bodies or nested content remain unsupported. For a Sphinx site, review-documentation can inspect a bounded RST subset and reports unsupported syntax as a limitation or refusal. Refer to Documentation Source Coverage in DocsFab before choosing a job for an RST-only site.

Inspect the Bound Catalog

Use the catalog commands to confirm the available jobs and inspect a job’s fixed step graph:

docsfab list
docsfab plan review-documentation

list prints review-documentation, create-documentation, update-documentation, and restructure-documentation. plan prints the fixed step graph. It does not read a target repository, run a model, or grant write authority.

Inspect the separately installed model, route, and harness bindings:

docsfab composition list

The list distinguishes executable pi-provider compositions from preflight-only Codex and Claude Code compositions. Listing compositions does not run a provider or workflow.

Choose an Execution Path

Omit --composition to use the model-profile path. To run the bounded composition execution path, select one exact executable composition:

docsfab run review-documentation --repo /absolute/path/to/target-repo \
  --composition anthropic-claude-opus-4.7-pi

The installed executable NVIDIA, OpenAI, and Anthropic choices are listed by docsfab composition list, which also marks records whose status is retired. Current NVIDIA API Catalog IDs include nvidia-nemotron-3.5-lightning-30b-a3b-pi, nvidia-nemotron-3-super-120b-a12b-pi, and nvidia-nemotron-3-ultra-550b-a55b-pi; nvidia-llama-3.3-nemotron-super-49b-v1.5-pi is retired (provider end-of-life 2026-08-26) and is refused for new runs. The direct-provider ID is anthropic-claude-opus-4.7-pi. openai-gpt-5.6-sol-pi is retired (superseded by operator decision on September 28, 2026) and is refused for new runs; its successor is nvidia-inference-gpt-6-sol-pi.

Provide exactly one credential source declared by the selected composition. The NVIDIA API Catalog compositions read only DOCSFAB_NVIDIA_API_KEY; MODEL_API_KEY, NVIDIA_API_KEY, and NGC_API_KEY are not aliases for it. Direct-provider compositions retain their documented MODEL_API_KEY or provider-specific source. Keep credentials in the host secret boundary; do not put them in the command, target repository, prompt, or run record. For the supported default setup, use Install DocsFab. For advanced composition credential contracts, refer to Runtime CLI and Configuration in DocsFab.

The configured model ID, base URL, and compatible API format must match the selected installed route. DocsFab rejects a mismatch instead of switching providers or compositions.

Unqualified Answer-Record Discovery

Use --experimental-answer-records only when you are explicitly collecting unqualified discovery evidence for a selected composition and route with a locked quality profile. The host derives the answer-record plan from that profile and its policy:

docsfab run review-documentation --repo /absolute/path/to/target-repo \
  --composition <composition-id> --experimental-answer-records

This option is limited to review-documentation and requires an explicit --composition selection. It uses the locked quality profile’s host-derived answer-record plan; it does not require an installed answer-submission qualification measurement. DocsFab prints the effective execution bounds and the applicable request-intent, quality-evaluator, and answer-now limits before provider work begins. The evidence records the installed composition, candidate, package, and host limits used to derive those effective bounds. The saved evidence records unqualified discovery; this mode does not qualify the composition or change the qualified default path. Without --quiet, DocsFab prints the effective bounds before provider work. With --quiet, the preflight display is suppressed, but the saved run evidence retains the bounds and unqualified status.

For the exact NVIDIA API Catalog Nemotron 3 Super 120B composition, discovery can use a configured per-request output allowance up to the hosted endpoint’s documented max_tokens ceiling. To select that ceiling, set MODEL_MAX_OUTPUT_TOKENS=32768 for the run. This override applies only with --experimental-answer-records on that exact composition and route; other compositions and ordinary runs keep their installed limits. The 32,768-token value is documented endpoint request capacity, not measured evidence that a DocsFab workflow needs that much output or will complete successfully. The composition remains unqualified, and its sealed production limit is unchanged.

In this mode, tool reads and answer-record submissions share a renewable per-lease call cadence. DocsFab keeps separate usage counts for each scope and renews the cadence from host-owned checkpoint evidence. During the answer- record evaluator step, this explicit policy does not impose aggregate tool- call, lease-count, provider-turn, cumulative-token, whole-attempt time, or cost ceilings. It still enforces configured output and response-byte capacity for each provider request. Input and context admission follow the selected route’s existing host-or-provider policy. The provider SDK’s request timeout, transport retry rules, cancellation, credential isolation, and final validation also remain active. Provider-account limits remain external to DocsFab. These controls and usage records do not establish model capability. If the model returns final text while required answer-record keys remain, DocsFab asks for the remaining keys and continues in the same attempt. Previously admitted records and existing tool permissions remain available during recovery. A refused answer-record submission does not stop discovery of other required keys. Saved run evidence retains content-free refusal diagnostics so you can inspect rejection codes and locations without retaining rejected answer content. At an execution-lease checkpoint, this explicit discovery mode can renew after a correction tranche with zero useful records so those refusals remain correctable. Ordinary runs still require a useful success before renewal.

The final evaluator report may also continue across provider requests without the ordinary run’s continuation-count or stitched-response-byte cutoff. Each individual provider response remains subject to its configured byte capacity, and an incomplete model evaluation is still refused rather than completed by the host.

Saved discovery runs created under the older refusal policy remain readable. They cannot resume under the new policy. Start a fresh run with --experimental-answer-records to continue discovery.

Run a Read-Only Job

Run the review job without a write grant:

docsfab run review-documentation --repo /absolute/path/to/target-repo

This job does not require write authorization. Live run needs the runtime model profile. docsfab test remains the credential-free self-check.

review-documentation is the standalone comprehensive stack: documentation audit, lint, technical verification, peer review, audience-understanding, and quality evaluation.

When a run names exactly one documentation page, runtime compiles its repository context for that page. A named page that is not present at the frozen revision stops the run rather than silently widening it to the whole documentation set.

Before the first model request, runtime verifies the installed quality pack. After the request interpretation and before the first workflow step, runtime builds a tracked documentation inventory and selects the experimental docsfab-documentation-quality profile at version v0.1. A missing, ambiguous, substituted, or inapplicable profile stops with quality-profile-selection-invalid before any workflow step runs.

For reviewer and baseline procedures, refer to Review Merge Request Impact in DocsFab and Baseline Documentation Health in DocsFab.

Run a Write-Capable Job

Create, update, and restructure write and open one draft merge request by default. Pass --patch-only to run in a disposable workspace and retain a patch without publishing or changing the source checkout. Pass --dry-run to preview and stop before repository inspection or workflow steps. --repo defaults to this checkout.

An instruction that says not to publish, such as Keep the result local; do not commit, push, or open an MR., stops the default delivery, --draft-mr, and --dry-run with publication-prohibition-conflict before any GitLab read or model call. Pass --patch-only with it, or remove the prohibition to open the draft merge request. For the recognized phrasings, refer to A Request That Says Not to Publish Is Refused.

Verified help for the bound write jobs:

docsfab run update-documentation \
  --instruction "Update the API guide for the approved change"

For create examples and delivery choices, refer to Runner Quickstart. For update beside a change, including --reader-source, refer to Update Documentation Beside a Change in DocsFab.

create-documentation and update-documentation also accept the repeatable --source flag, which binds tracked files at the selected revision and issues the granted steps a host reader for them. 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. review-documentation and restructure-documentation refuse the flag, and the refusal names the workflows that accept it. --dry-run parses the selection and stops before the host opens any source body. Refer to Bind Tracked Source Files to an Update.

Adding --composition <id> selects that installed composition as the run’s preset and does not grant delivery authority. Composition-execution writes stay local unless you pass --draft-mr. A --composition run also accepts --release-gate, --comment-mr, and --resume-from. Add --set <key>=<value> to change one of the preset’s model settings for the run; refer to Change a Preset’s Settings. The optional --canon-sha256 <sha256> flag is accepted only beside --comment-mr and supplies the project’s registered canon digest for a focused review’s continue command in the summary note. For an authorized local write, a local Git repository does not need a remote or .docsfab.json. DocsFab uses the default docs/ and fern/ roots when no tracked project configuration sets them. A tracked configuration remains authoritative and must be valid. Publishing or explicitly proposing .docsfab.json still requires setup through a supported GitLab remote. At this head no --comment-mr run carries a focused scope, so the flag has no effect until a focused --comment-mr producer exists; read the deferred set from the run record.

For changes selected by merge date, follow Update Documentation From Merged Merge Requests.

Verify the Result

Inspect the terminal result and retained run record before you use any output:

docsfab runs show <run-id>

Execution status describes whether the workflow completed. The quality disposition describes the evaluated documentation and its evidence. Inspect both; a completed run does not by itself mean the output passed evaluation, and an evaluation artifact is not a release approval. For the evaluation vector, optional content-type score, report summary, and their retained locators, refer to Evaluate Document Quality Skill in DocsFab and Reading a Result. The locators identify runtime-retained artifacts and do not necessarily name files written into the documented repository.

Some completed reviews have no validated quality projection. If the evaluator’s structured result remains invalid after correction attempts, the workflow can retain its narrative and other findings without a validated evaluation, score, or report projection. This is not a pass, and narrative does not replace a validated evaluation. Review findings and patch delivery remain separate from the quality verdict.

Confirm the following conditions:

• The record names the requested workflow, target repository revision, bound skills, locked quality pack, and selected composition when applicable.
• A successful read-only review contains findings and quality evidence without a write grant.
• When a write-capable job proposes changes, it contains a reviewable patch and does not imply commit, publication, deployment, or merge authority.
• A needs-input, blocked, or failed result identifies the unmet dependency. Do not retry it with broader authority. After a catalog job has started, follow Answer and Resume a Stopped Job in DocsFab or the PRODUCT shopping list. Do not treat docsfab doctor as that continuation.
• Composition-execution output remains technically unapproved, role-unqualified, and not release eligible, even when execution succeeds.

For the complete CLI output contract, refer to Runner Quickstart.

Next Steps

Choose the next action from the verified result:

Related Topics

Use these topics for the concepts, setup, reference, and recovery guidance that support this workflow:

Moved Topic Links

Earlier section bookmarks lead to the canonical topic below.

Refer to Assess Documentation Readiness in DocsFab.

Refer to Audit Pages Against Templates in DocsFab.

Refer to First-Pass Knowledge in DocsFab.

Refer to Compare Completed Composition Runs in DocsFab.

Refer to Deliver or Recover a Draft Merge Request in DocsFab.

Refer to Host a DocsFab Review Report.

Refer to First-Pass Knowledge in DocsFab.

Refer to First-Pass Knowledge in DocsFab.

Refer to Supply Requested Work Products in DocsFab.

Refer to Bind a GitLab Change in DocsFab.