DocsFab Live Agent Quickstart

Guided setup uses the same flow as docsfab setup; you do not need a separate startup script. At startup, live-agent prints a Configuration: line that names the configuration root and secrets file. Startup only reads saved credentials, does not write secrets.env, and leaves an existing configuration root unchanged. Several sessions can share one configuration root.

When the root is incomplete, guided setup handles keys as follows:

• A stored or exported key does not choose a model. If the root names no model, for example, a .env that holds only MODEL_API_KEY, guided setup asks for the model settings because DocsFab has no default model. A key you export in the shell does not replace a stored key, although the current session still uses the exported key.
• If no key is stored, guided setup asks before saving an exported key. It offers only the key name that the root’s model profile uses and never saves an exported key for a different provider. If you decline, guided setup asks for the model settings instead.

A key that you export only in the shell works for that session but is not saved unless you agree. To save or replace a key, run docsfab setup.

When documentation writes are enabled, DocsFab prepares a unique task branch in the selected checkout before the first file change if you are on main, the repository default branch, or detached HEAD. Later writes in the same session reuse that branch. Reading files and loading skill instructions do not create a branch.

Automatic branching does not grant commit, push, merge-request, or merge authority. It does not stash, reset, or discard your staged, unstaged, or untracked files. Local live-agent uses the --repo checkout you started; a task branch is not worktree or process isolation. It does not resolve saved-patch conflicts by overwriting files.

If branch setup fails, DocsFab reports the reason and does not change documentation files.

Type these at the conversation prompt. The terminal reads them itself, so they never become a request to the agent.

A label is exactly what /sources printed, matched byte for byte.

/sources show and /sources refresh read the file at the revision the session selected, not your working tree, so an uncommitted edit does not change a version. A merge-request reference reaches GitLab through the same local glab authentication docsfab run --pr uses; no credential is read from, or written to, the conversation.

What these commands will not do:

• They are read literally. A path is stored exactly as you typed it: there is no shell expansion, no command substitution, no quoting, and no glob, so a file whose name contains $(...) or a backtick attaches as itself.
• They attach nothing outside the selected repository. An absolute path, a parent-directory path, a ~/ path, a bare URL, and any reference whose own text reads as a host location or holds one of DocsFab’s own configured credentials are refused by name. A refused command changes nothing: no source is attached, detached, or counted as refreshed.
• A pasted merge-request link is resolved to its project’s numeric id and checked against the project path in the same link. A link naming another project is refused; no cross-project scope is ever inferred.
• /sources remove is refused while a bounded workflow run holds that source as required evidence, and the refusal names the step that requires it.
• Detaching an attachment, invalidating a cache and purging a session are three different operations, and /sources purge prints all three side by side before it deletes anything. Only a purge deletes bytes, only a purge is confirmed, and only a purge is recorded. A purge detaches nothing: the attached sources stay attached, their process-local derivatives are dropped, and each is marked as having had its owned local copy purged, so a later reference resolves to an explicit “unavailable” rather than to silence or to a reference quietly pointed somewhere else. Your own files and independently retained run evidence are outside the deletion, and DocsFab claims no erasure by any external model provider. A second purge of the same session says it has nothing to do rather than acting again. An ambiguous session reference, a session held by another principal or bound to another repository, and a session a writer still holds are each refused by name, with nothing deleted.
• The model cannot invoke /sources purge. The /sources family is parsed off the terminal’s own input stream before a message reaches the session, and no tool definition or capability list a model can read names the verb or the command.
• /sources refresh reports a changed file as drift on the same entry. It never quietly attaches a second copy. Drift means “changed since the last /sources refresh in this conversation”. Nothing is read when a source is attached, so the first refresh establishes the baseline rather than reporting against one.
• /sources revalidate checks where /sources refresh adopts. It re-reads each attached file and re-resolves each attached merged change, compares what it finds against what was admitted, and records the verdict without moving the version. A source it reports as stale stays stale in the listing until you refresh or detach it, so a run never binds a version the conversation was told had moved. Every verdict prints its basis, because fresh after comparing a recorded version and fresh on a file this conversation never read are different claims: the first says the file has not moved, the second says only that it reads cleanly now. A verdict older than the revalidation window is still shown, marked as beyond it rather than dropped. A bounded run refuses a last verdict of stale, missing, unreadable, or identity-changed, and it also refuses a fresh verdict that has aged past that window: the window is a gate, not only a listing mark. Revalidate again, or refresh or detach, before asking the conversation to run.
• /sources revalidate never detaches anything and never leaves a source out of its report. A source that vanished from the selected revision is reported as missing and stays attached; a condition that would let it check some sources and not others (more attached sources than one command re-checks, no wired reader, or a forge that cannot answer) refuses the whole command and records nothing, rather than reporting on a subset by silence.
• missing and unreadable are different answers and are never merged. A file the repository no longer tracks at that revision is missing. A file that is still there and whose bytes did not arrive, for example over the version ceiling or because of an I/O failure, is unreadable, and the other attached sources are still re-checked, so one oversized file does not cost you every other verdict. Telling you to restore a file that never left would be advice you cannot act on.
• A forge that cannot answer is never reported as an answer. Only “this project path is a different project now” is identity-changed; an unreachable forge, or one that answers without a usable project id, stops the command and says so. If the project is permanently gone, revalidate the rest by naming each label, or detach the merged change.
• fresh (recorded-project-identity) on a merged change means its project is still the same project. The change number, the merge commit, and the merge-request state are not re-read.
• A preview is bounded, and it is withheld entirely if it matches the runtime credential screen. A path under this host’s checkout, home directory, or temporary directory is shown as a repository-relative path, ~, or $TMPDIR. The agent’s answers are never refused for naming a path.
• The agent is not told when you change the selection mid-conversation. Run a bounded workflow to bind the new selection, or ask the agent to restate what it is working from.
• The changes do not survive the conversation. Resuming a session restores the transcript, and rebuilds the attached selection from the --source and --pr options you started it with, so re-attach anything you added mid-conversation.

What Is Not Available Yet

This release does not support /sources search. Attach tracked files or a known merged merge request with --source or --pr instead. A bounded workflow can then gather evidence from those selected sources.

For a reader-impact update, DocsFab validates a bounded reader context and uses the same locked reader-impact baseline for the applicable skill and workflow steps. You can still describe an ordinary update in natural language. DocsFab creates a conservative planning context from that request when no structured reader context is supplied. This fallback can support a bounded update. It can also support a verified no-change result when the plan keeps every page unchanged and each kept page is admitted as current documentation; independent read-only checks must confirm it. Host-bind of an operator-directed update is closing admission, not default authoring. The write grant and the admitted plan decide it, not the wording of the request. Text cannot certify no-change.

Your request reaches the workflow in your own words, unchanged. MR evidence and other details the agent retrieves travel beside it as non-authoritative context. DocsFab keeps its internal reader-task summary short without discarding those details. You do not need to shorten your request to fit that summary.

If the agent names an evidence file that is absent from the selected revision, the update workflow continues with the available files. The missing file stays in the workflow context and returned evidence limitations. Conclusions still require supporting evidence; an omitted file does not count as reviewed. Create, update, and restructure workflows share planning and writing guidance that continues supported work and reports missing references. Focused writing uses the same guidance. Work that depends on missing evidence remains deferred.

For a reliable no-change conclusion, provide an explicit base/head or current workspace comparison. The focused reader-impact assessment runs read-only and requires a clean selected checkout. If the comparison is unavailable or the workspace changes, DocsFab reports the evidence limitation before it generates a patch. The update workflow contract explains how DocsFab binds the comparison, sources, and checkout snapshot. Other documentation work continues to use the session mode and file boundaries shown at startup, and loading a reader-aware skill grants no additional tools or permissions.

Loading skill instructions in write mode does not start a reader-impact assessment. If the agent includes optional reader evidence with that request, DocsFab loads the instructions and reports that the evidence was not admitted or verified.