Add screenshots to a visible application workflow when an image will clarify a control or confirm an important state. Doxloop keeps the complete procedure in text, then captures and embeds selected states during create or update.
--print, then use the prepared prompt in a supported desktop app opened at the Doxloop project root.Configure the application
Add an application object to .doxloop/project.json:
{
"application": {
"baseUrl": "http://localhost:3000/",
"source": "product",
"startCommand": "npm run dev",
"readyPath": "/health",
"screenshots": {
"policy": "requested",
"viewport": { "width": 1440, "height": 900 },
"highlight": true
}
}
}source must name an entry in the top-level sources array and is required when startCommand is present. Use a local or non-production application with safe fixtures or test data. Never store credentials in project.json or point capture at real customer data.
Choose a screenshot policy based on when the desktop authoring session may operate the application:
| Policy | Capture behavior |
|---|---|
requested | Capture only when the authoring request explicitly asks for screenshots or the run uses --screenshots. |
auto | Also capture when the agreed documentation includes a visible UI workflow. |
off | Skip capture unless --screenshots explicitly requires it for that run. |
The viewport width and height must each be from 320 through 3840 and 320 through 2160, respectively. Omit viewport to use the desktop app's capture defaults. Set highlight to false only when the application state is already unambiguous.
Capture a guide
Write and verify every action, expected result, prerequisite, and recovery step before capturing. Screenshots supplement these instructions; they never carry essential information alone.
Start or connect to the configured application. Use fixtures, seeded local state, or a dedicated non-production account. If authentication is necessary, establish it in the desktop app without putting credentials in the prompt or documentation.
For a new guide, run:
doxloop create --screenshots --print "Create an onboarding guide. Capture the important visible states."To refresh an affected guide after its UI changes, run:
doxloop update --screenshots --print "Refresh the onboarding guide screenshots."Open the Doxloop project in the Codex or Claude desktop app, then submit the printed prompt there. The CLI only prepares the prompt; the desktop app provides the browser capability required for capture.
The authoring workflow plans each published step in order, including the expected visible state, whether it needs an image, the highlight target, filename, and alternative text. It captures from the lowest step number to the highest and verifies each image before continuing.
Run:
doxloop test
doxloop preview --openConfirm that every image follows the instruction it illustrates, remains legible at desktop and narrow widths, and has equivalent text instructions.
--no-screenshots on create or update when a run must not operate the application. review is read-only and never captures application screenshots.Highlight the relevant control
When highlighting is enabled, the desktop authoring workflow places a temporary 3 px high-contrast focus ring around the relevant control and adds a numbered marker matching the guide step. The marker and nearby prose identify the target without relying on color alone. The annotation is baked into the PNG, then removed from the live application; application source is unchanged.
Keep labels, validation messages, and surrounding orientation visible. Do not place a marker over interactive text, form values, or other state the reader must inspect.
Store and embed assets
For Doxbrix, commit guide images under a stable guide-specific directory:
docs/assets/guides/onboarding/
01-team-settings.png
03-invitation-form.pngThe numeric prefix matches the published step, so a text-only step can leave a deliberate gap. Reference an asset with its root-relative path immediately after the instruction that produced the state:
Use a Doxbrix captioned frame around a standard Markdown image. Set the image source to the committed root-relative asset path, such as /assets/guides/onboarding/01-team-settings.png, and use alternative text such as “Team settings with Invite member marked as step 1.” Add the reference only after the verified PNG exists so validation never sees a broken asset.
Use concise alternative text that identifies the useful state and marker. Keep captions optional and avoid repeating the surrounding prose. Guide assets belong in the generator-native content directory, not the ignored .doxloop/cache/reference/ directory used by doxloop capture.
If capture cannot finish
Keep the complete text guide and remove broken image references. Confirm that the configured URL is reachable, the visible workflow matches the source, safe test data is available, and the Codex or Claude desktop app has browser access. Then rerun only the affected update. See Troubleshooting for the recovery checklist.