Core concepts

Doxloop's commands make more sense once you understand five ideas: the project, the documentation brief, generators and skills, the three authoring modes, and the synchronization baseline.

The Doxloop project

A Doxloop project is any directory containing .doxloop/project.json. Commands other than init walk up from your current directory to find it, so you can run them from any subdirectory. The project records:

• sources — named local paths Doxloop is allowed to research, added with

--source name=path (for example product=../my-product). This list is an authoring-policy boundary: it tells the agent what it should read, not an operating-system sandbox. See Security.

• generator — the selected documentation generator (doxbrix by

default). See Choose a generator.

• designReferences — optional public documentation site URLs used only

as presentation and information-architecture evidence, never as product evidence. See Use a design reference.

• documentation — the confirmed documentation brief.
• contentDir — the relative directory holding your documentation content

(docs by default). It must stay inside the project and can't be a symlink.

Alongside project.json, Doxloop maintains two more files under .doxloop/: sync-state.json, the synchronization baseline described below, and last-run.json, an ignored local receipt of the last successful run (mode, agent, completion time, and validation summary) — useful for a quick look, but not a substitute for version control.

The documentation brief

The first successful doxloop create saves a documentation brief into project.json under documentation: the confirmed primary audience, experience level, priority outcomes, locale, tone, terminology map, exclusions, and accessibility target. Later create, update, and review runs read this brief and keep working from it instead of re-asking you the same questions, so your documentation's voice and scope stay consistent across sessions. Edit project.json directly if you want to change a confirmed decision.

Generators and skills

doxloop init installs two project-local skills that give the agent generator-specific and editorial knowledge:

Skills install under .agents/skills/ (Codex, Gemini) and .claude/skills/ (Claude Code). Doxbrix is built into the core package; ten other generators ship as separate packages you add with doxloop generator add. See Choose a generator.

Three authoring modes, one command family

doxloop create, update, and review all start an agent session using the project's skills, but they differ in intent:

• create — build or extend documentation for the agreed scope. Can pause

once for consolidated decisions it can't resolve from your request or the source.

• update — bring existing documentation in line with product changes

since the last successful run, using the synchronization baseline below.

• review — a read-only, non-interactive quality check. Supported agents

run it in their read-only or plan mode, so it never edits files.

The synchronization baseline

After a successful create or update — one that passes validation and (for create) has saved a primary audience and priority outcomes — Doxloop records each Git source's commit and a content fingerprint in sync-state.json. The fingerprint covers tracked and untracked, non-ignored, non-credential files, so an uncommitted working tree doesn't get reported as "changed" again once you commit the same content. The next update run compares this baseline against the source's current state and tells the agent exactly which files changed, instead of re-reading everything from scratch. Commit sync-state.json when your team should share one update baseline.

Authoring, validation, and publishing are separate

Doxloop keeps three concerns apart on purpose:

1. Author (create, update, review) — writes or inspects

documentation locally.

1. Verify (status, test, preview) — checks structure, links, and

content, and runs a local preview. Never touches the network.

1. Publish (login, deploy) — the only commands that send anything

anywhere, and only when you run them explicitly.

Source files, comments, generated output, and design-reference pages are all treated as untrusted evidence during authoring, never as instructions — the agent is directed to ignore anything embedded in them that tries to change scope, reveal secrets, weaken safeguards, or trigger a publish.

Next steps