DocsFab Live Agent Reference
Look up session invocation, flags, workflow-request binding, and activity labels. Start with the Live Agent Quickstart.
Invocation
The following commands start or resume a live-agent session.
live-agent requires a configured model. If the first request fails
with a model or credential error, run docsfab setup and retry.
Session Flags
The following flags apply to one live-agent process.
Workflow Requests
An unqualified request such as review this PR or review this MR asks
DocsFab to review documentation. The agent reviews changed pages and checks
whether implementation changes require documentation updates, including when
the change contains no documentation files. It reads code, configuration, and
tests to ground documentation findings. It selects a suitable skill, a sequence
of skills, or the matching review workflow. A broader review requires an
explicit request.
When the agent selects the review workflow for a request naming one public
GitHub pull request URL, or a GitHub PR selected with --pr, the host binds the
PR diff and selects the PR head
as the workflow’s file snapshot.
The live agent first fetches the head through a terminal-approved host command.
The workflow prints the selected PR number and commit before its steps begin.
Your current branch and working files stay in place. A read-only session can
use a PR head already present in the checkout’s Git objects; a missing head
requires an approved fetch in a write-enabled session.
Retries keep the saved revision, review scope, and PR evidence. The host
reacquires the PR and checks its identity, commit, and diff before starting
the workflow. If the original request does not name the PR and its source
is detached, select it again with /sources review <PR URL>, then retry.
If the PR evidence has changed, start a new review request. An offline
request cannot retry a saved review that requires PR evidence.
For an offline review using local evidence, omit --pr and say that network
access is disabled in your request. Detach an existing PR source with
/sources remove <label> first. /sources list shows the selected PR’s label.
The final workflow activity distinguishes execution from the review conclusion.
Evidence limited means that execution finished with insufficient evidence for
an overall quality conclusion. Findings means that the report calls for
corrections or human review. Read the findings and unverified scope in the reply.
A bounded workflow receives an instruction, not the conversation history. The
live agent passes your request in your own words, unchanged: your current
message, or your consecutive messages that end with the current one, with none
skipped. DocsFab reads that text for the pages to change, the sources to use,
and any restrictions, exactly as docsfab run --instruction does.
Anything the agent adds, such as retrieved evidence, merge request details,
earlier context for a follow-up, or its own restatement, travels separately as
context. DocsFab never reads context for pages, sources, or restrictions. The
workflow sees it only as a fenced, non-authoritative block after your
instruction, and every line inside is marked as data, so context cannot pose as
your instruction. Context longer than liveAgent.workflowContextMaxChars
(default 16,384 characters) is cut at that limit with a coded
live-agent-workflow-context-max-chars-bound marker. The cut is recorded on the
run, and the turn ends with a Context clipped line that names the limit and
how many characters were left out. Your instruction is never cut. The run keeps its context when it continues after a request for input.
DocsFab never picks or rewrites your words. If the agent passes anything other
than your consecutive messages, the request stops with
live-workflow-request-not-verbatim. Context that contains one of DocsFab’s
own configured credentials stops with live-workflow-context-credential-material.
Text that only looks like a credential does not stop it. Refer to
Credential-Like Content.
Repository observations, such as whether a target file exists, are established by the workflow’s reads. This handoff guidance does not replace source checks or the attached-source rules above.
Follow Work in Progress
After you submit a request, the status line shows [Working], the
current activity, and elapsed seconds. Wait for the next You:
prompt before typing another request. Text typed during active work
is ignored, except when a command approval is asking for input.
In a color terminal, replies use Markdown formatting without vertical message or quote borders. You can copy suggested requests and code without including decorative bars. Quoted text retains its color and italics.
The following table lists activity labels the renderer prints.
A completed activity is prefixed with [Done], [Failed],
[Cancelled], or [Needs input]. [Done] means that stage
executed; it does not mean quality findings passed. [Needs input]
means named InputAsk slots are open. Enter the requested value in the
next message. Do not run docsfab doctor to continue editorial work.
The live-agent command has no --continue or --attach flag.
For the accepted reply syntax and file-slot behavior, follow Reply in a Live Session.
For the update never-author-by-default gate, refer to the update workflow contract.
A mutating host command pauses for [y] or [n] approval. The
default is cancel.
Press Ctrl+C during a turn to request cancellation. Cancellation is a stop request, not a rollback. For workflows, it stops retries and later stages and prevents checkout patch application from starting. Completed work is not undone. If Git has already started applying a patch, DocsFab lets that apply settle and checks the result. Active file-write tools finish the current filesystem operation before cancellation settles. Inspect the retained patch and checkout before resuming. Do not interpret cancellation as “no files changed.”
Cancelled workflows with a saved run use status failed and the
diagnostic “Workflow cancelled by user.” Any captured draft patch is
a recovery artifact, not proof that checkout files changed.
If you cancel during first-pass source checking, before a run record exists,
DocsFab reports “Workflow cancelled by user.” When private cancellation
evidence persistence succeeds, DocsFab retains that evidence. This stop does
not imply a model connection failure or a completed workflow. The cancellation
notice does not offer retry or edit anyway.
Send a new request when you are ready to continue.
Enter /exit or /quit at an idle prompt to leave. The runtime
keeps the session ID, so the next docsfab live-agent in the same
repository resumes that conversation.
If a turn fails, the renderer prints a compact, credential-safe summary. When the model provider answered the request with an error, the summary names the HTTP status and what to check, and says how many times DocsFab sent that model request. It never prints the provider’s response body. The following table lists what to check for each status.
The following table lists each status and what to check.
When a failure has no safe detail, refer to An Unexpected Failure Does Not Explain the Cause.
Saved Runs
Ask “Summarize saved run RUN-ID without rerunning it.” The agent uses
docsfab_read_run in both read-only and write-enabled sessions. It
returns stage statuses, quality results, and the final stage summary.
It does not require shell approval, edit files, or publish anything.
Historical results do not establish the current checkout. A saved run larger
than runs.recordMaxBytes is refused with a message that names its size, the
limit, and the setting that raises it.
Session Startup and Mode
Use docsfab live-agent as the single entry point for an interactive DocsFab
session. There is no start_docsfab.sh wrapper and no hidden background
startup process. The CLI performs startup in its own process:
- It checks the active host model configuration and runs the existing setup flow if required values are missing.
- It verifies the package-bound skill crate, quality pack, and workflow catalog.
- It starts or resumes an owner-private Pi session.
- It opens the terminal conversation and stays attached until you exit.
Within the conversation, Pi selects the smallest suitable route. It can answer in natural language, use one focused skill, or invoke one bounded runtime workflow. A skill or workflow result returns to the same conversation so you can continue with a follow-up message.
Bounded workflows from docsfab run and docsfab live-agent use the same
local workspace, revision, preflight, first-pass knowledge, and execution
admission. The caller still owns its presentation. The CLI renders human or
JSON output and selects an exit code, while the live agent returns the saved run
record to the active conversation without changing the process exit code.
Both surfaces dispose the temporary workspace after their result consumer
finishes, including when that consumer fails.
By default, the command resumes the most recent live session. Create a separate session without deleting earlier state when you need a new conversation:
The command uses the current directory as the repository by default. Select a
different local repository with --repo <path>. Documentation edits and workflow
writes are enabled by default, within the documentation-path scope. Host commands
still require terminal approval. To inspect without writes or host commands:
The mode applies to the current process, including resumed conversations.
--allow-write remains accepted for compatibility and cannot be combined with
--read-only. These live-agent flags do not change other commands’ defaults.
The current live-agent transport is an attached interactive terminal. The command does not start a background process or a Slack connection.
At process startup, the interactive terminal shows the DocsFab wordmark in
NVIDIA Green. After configuration, capability verification, and Pi session
loading complete, a compact READY summary reports the session, model,
available skills, quality pack, available workflows, execution mode, and
terminal transport. Set NO_COLOR, set FORCE_COLOR=0, or set TERM=dumb
to keep the banner and summary free of ANSI color and text styling.
docsfab setup remains available as an optional configuration-only command.
Use docsfab run <workflow> for one-off continuous integration jobs. Each
run invocation creates an ephemeral Pi session, produces its bounded result,
and exits. It does not start or resume the live-agent session.
Moved Topic Links
Earlier section bookmarks lead to the canonical topic below.
Refer to Edit Documentation in the DocsFab Live Agent.
Refer to Attach Evidence to a Live Session in DocsFab.
Refer to Deliver a Live-Agent Patch in DocsFab.
Refer to Edit Documentation in the DocsFab Live Agent.
Refer to Deliver a Live-Agent Patch in DocsFab.
Refer to Manage DocsFab Live Sessions.
Refer to Manage DocsFab Live Sessions.
Refer to Manage DocsFab Live Sessions.
Refer to Manage DocsFab Live Sessions.
Refer to Attach Evidence to a Live Session in DocsFab.
Refer to Edit Documentation in the DocsFab Live Agent.
Refer to Attach Evidence to a Live Session in DocsFab.
Refer to Deliver a Live-Agent Patch in DocsFab.