Everything Doxloop needs to know about your documentation project lives under .doxloop/. This page documents each file's schema.
project.json
{
"schemaVersion": 1,
"title": "Example documentation",
"contentDir": "docs",
"generator": "doxbrix",
"sources": [{ "name": "product", "path": "../product" }],
"designReferences": [{ "url": "https://docs.example.com/" }],
"application": {
"baseUrl": "http://localhost:3000/",
"source": "product",
"startCommand": "npm run dev",
"readyPath": "/health",
"screenshots": {
"policy": "requested",
"viewport": { "width": 1440, "height": 900 },
"highlight": true
}
},
"documentation": {
"primaryAudience": "Application developers",
"experienceLevel": "intermediate",
"priorityOutcomes": ["Install the SDK", "Send the first request"],
"locale": "en-US",
"tone": ["clear", "direct", "professional"],
"standardsProfile": "doxloop-v1",
"styleGuide": "doxloop",
"terminology": {},
"exclusions": [],
"accessibilityTarget": "WCAG 2.2 AA"
}
}Top-level fields
| Field | Type | Notes |
|---|---|---|
schemaVersion | 1 | Only 1 is currently supported. |
title | string | Documentation site title. |
contentDir | string | Relative directory holding your documentation content. Must stay inside the project and can't be a symlink; a project-root, escaping, or absolute path is rejected. |
generator | string | One of the eleven supported generators. A missing value in an older project means doxbrix. |
generatorPackage | string | Required for an external generator; must match the official package for the selected generator. Absent for Doxbrix. |
sources | array of { name, path } | The research allowlist. name must match ^[a-z][a-z0-9-]*$. Paths may point outside the documentation project — products are commonly kept in an adjacent directory. |
designReferences | array of { url } | Absolute HTTP or HTTPS URLs without embedded credentials. |
application | object | Optional safe application surface for guide screenshots; see below. |
documentation | object | The documentation brief — see below. |
Application screenshots
| Field | Type | Required | Notes |
|---|---|---|---|
baseUrl | string | Yes | HTTP or HTTPS application URL without credentials, a query, or a fragment. |
source | string | When startCommand is set | Must name a configured top-level source. |
startCommand | string | No | Non-empty command run from source when Doxloop should start the application. |
readyPath | string | No | Root-relative readiness path beginning with /, but not //. |
screenshots.policy | requested \ | auto \ | off |
screenshots.viewport.width | integer | No | 320–3840. |
screenshots.viewport.height | integer | No | 320–2160. |
screenshots.highlight | boolean | No | Set to false to omit capture-time focus rings and numbered markers. |
Application capture requires the Codex or Claude desktop app and is not supported through their CLI workflows. See Add guide screenshots for safe capture, highlighting, and asset placement.
The documentation brief
| Field | Type | Required | Notes |
|---|---|---|---|
primaryAudience | string | No | Confirmed primary reader description. |
experienceLevel | beginner \ | intermediate \ | advanced \ |
priorityOutcomes | string[] | No | The outcomes readers should reach first. |
locale | string | Yes | For example en-US. |
tone | string[] | Yes | For example ["clear", "direct", "professional"]. |
standardsProfile | string | Yes | Versions the curated information-architecture, evidence, accessibility, and quality rules. doxloop-v1 is current. |
styleGuide | string | Yes | |
terminology | object (string → string) | Yes | Preferred term for a given source term; may be empty. |
exclusions | string[] | Yes | Meaningful scope exclusions; may be empty. |
accessibilityTarget | string | Yes | For example WCAG 2.2 AA. |
A project created without a documentation object uses Doxloop's built-in default brief (the same required fields shown above, with locale: "en-US", tone: ["clear", "direct", "professional"], standardsProfile: "doxloop-v1", styleGuide: "doxloop", empty terminology and exclusions, and accessibilityTarget: "WCAG 2.2 AA"). doxloop create saves the confirmed brief here after its first successful run. Edit this file directly to change a decision without rerunning create.
project.json structure — a missing required field, an invalid contentDir, an unrecognized generator, or a malformed documentation object — fails closed with an error rather than being silently migrated or repaired.sync-state.json
{
"schemaVersion": 1,
"sources": {
"product": {
"commit": "a1b2c3d4e5f6...",
"recordedAt": "2026-06-01T12:00:00.000Z",
"contentFingerprint": "9f8e7d6c5b4a..."
}
}
}One entry per Git source, recording the commit and a fingerprint of tracked and untracked, non-ignored, non-credential content at the time of the last successful create or update. See the synchronization baseline. Commit this file when your team should share one update baseline.
last-run.json
An ignored, local-only operational receipt written after a successful create or update: the mode, selected agent, completion time, validation summary, and synchronized source count. It's useful for a quick check of what last happened, but it isn't an evidence map and isn't a substitute for version control — don't commit it.
The generator's own manifest
Your selected generator keeps its own navigation and site configuration inside contentDir — for Doxbrix, that's docs/docs.json, covering spaces, navigation, and theme. That file is documented by your generator's format skill (doxloop-doxbrix and so on) rather than by project.json.