@doxbrix/doxloop 0.1.4 → 0.2.0

package/docs/review-workflows.md

@@ -0,0 +1,51 @@
+# Editing, auditing, versions, and review
+
+## Start with an audit
+
+Try `doxloop demo` to see the workflow without an agent. After importing an existing site, open **Pages → Audit existing documentation and reader verification → Run read-only audit**, or run:
+
+```sh
+doxloop audit --format json
+```
+
+The audit lists detected configuration, content roots, preview routes, unmapped pages, unverified pages, and source drift. It does not rewrite documentation or advance source baselines. `doxloop audit --backfill-evidence` adds missing evidence entries as unverified, preserving existing associations. This is a reversible metadata write; it cannot discover factual source associations by itself.
+
+## Edit and discuss
+
+Search in Pages matches titles, paths, and body text. Expand the text matches and select a section to open the source editor at the matching line. Results are capped at 200; narrow the query for more specific results. The local Doxbrix preview includes **Edit this page in Doxloop** when launched from the control center. Published exports do not contain a link to the local editor.
+
+Pages and Review have persistent comments. A review comment can target a whole file or an individual hunk. **Ask agent to address** starts a scoped proposal or revision using that comment. Comments remain open until explicitly resolved; starting a job does not mean the issue was fixed. Comments are local records in `.doxloop/comments.json`, not multi-user identity or notification infrastructure.
+
+Select multiple pages and open **Bulk metadata** to preview a shared field change. Each page has an optimistic fingerprint. The batch either saves all pages or restores them all. **Recent direct edits**, under Manage pages, lists reversible page, navigation, branding, asset, metadata, and glossary changes. Undo refuses to overwrite newer edits.
+
+In Review, **Review a folder** lists the affected files and accepts or rejects only pending hunks in that folder. Rejection requires a reason. Files edited during generation require individual review before folder acceptance. Already accepted or rejected hunks keep their decisions.
+
+## Versions and languages
+
+Open **Pages → Versions and languages** and choose a source collection, version, and locale. Collection creation copies the documentation and assets, adds navigation, and creates unverified evidence entries in one reversible transaction. Copied prose is not a completed translation. **Ask agent to translate copied pages** creates a scoped translation proposal for review.
+
+Doxbrix and MkDocs use `editions/<version>/<locale>/` under the content directory, with named navigation sections. Docusaurus uses its native `versioned_docs`, `versioned_sidebars`, `versions.json`, and `i18n/<locale>/docusaurus-plugin-content-docs/` layout. Existing native Docusaurus versions and locale pages appear in Pages, search, direct editing, and scoped agent review.
+
+The direct Docusaurus creator supports autogenerated sidebars and literal `i18n.locales` arrays. Custom coded sidebars or dynamic locale configuration require a reviewed native proposal; the creator stops before writing. Multiple docs plugin instances and custom version route overrides need a project-specific compatibility check. Other generators retain their native version and translation tooling. MkDocs collections do not replace a site's existing mike or third-party locale plugin deployment scheme.
+
+These conventions follow [Docusaurus versioning](https://docusaurus.io/docs/versioning), [Docusaurus localization](https://docusaurus.io/docs/i18n/tutorial), and [MkDocs navigation configuration](https://www.mkdocs.org/user-guide/configuration/#nav).
+
+## Honest budgets and verification
+
+The plan displays page, screenshot, and per-attempt time caps. Planning also respects the time cap. Once at least three comparable completed authoring runs exist, Doxloop displays an observed duration range scaled by changed page count. It is not a guarantee or a dollar quote. Agent billing remains with the selected provider.
+
+The audit panel can enable reader verification labels for the built-in Doxbrix reader. Preview and static builds calculate their state from current evidence; a direct factual edit invalidates its evidence. Unknown drift does not appear verified. Native generator templates remain under the site's control.
+
+## Hosted pull-request impact
+
+`.github/workflows/documentation-impact.yml` runs a deterministic evidence-map check and maintains one bot comment with the affected pages. It executes only trusted base-branch code with no checkout of the pull request head, agent, or package installation. Configure `DOXLOOP_DOCS_ROOT` if the committed Doxloop project is not at repository root. Sources outside the checkout are explicitly uncheckable. A missing project/evidence map is reported in the job log instead of asserting current documentation.
+
+The workflow uses `pull_request_target` so fork pull requests can receive a comment; do not change its checkout to the pull request head. The first installation must reach the base branch before it can run there. Tests: `node --test scripts/docs-impact.test.mjs`.
+
+## Execution and release checks
+
+Python examples require a locally pulled digest-pinned image in `DOXLOOP_PYTHON_SANDBOX_IMAGE`. There is no host Python fallback. `node scripts/ci-python-sandbox.mjs` exercises real fixture access, blocked host access, read-only mounts, and blocked network access. CI runs this separately from mocked boundary unit tests.
+
+`node scripts/ci-existing-sites.mjs` builds representative existing Docusaurus and MkDocs sites six times each: original, accepted update, undone update, version, locale, and restored original. It checks custom routes, base paths, assets, source preservation, and collection undo. The fixtures are representative sites, not production customer audits.
+
+Real-agent evaluation results are written to the Git-ignored `evals/results/` folder. `evals/baseline.json` records the accepted benchmark observation, keyed by mode, agent, model, and fixture. A seeded review score measures defect detection; it is distinct from generation quality. These checks are separate from the unit suite.

package/docs/security-model.md

@@ -1,7 +1,7 @@
 # Security model
 
 Doxloop separates local authoring from explicit publishing. This document
-describes which guarantees the CLI enforces and which behavior depends on the
+describes which guarantees Doxloop enforces and which behaviour depends on the
 selected coding agent and host environment.
 
 ## Trust boundaries
@@ -13,24 +13,39 @@ selected coding agent and host environment.
   ignore embedded requests that change scope, reveal secrets, weaken safeguards,
   contact unrelated services, or publish.
 - Coding agents retain the filesystem permissions granted by their host. The
-  configured `sources` list is an authoring-policy boundary, not an operating
-  system sandbox.
-- Product sources are read-only evidence. The create and update workflows tell
-  the agent to write only inside the separate documentation project.
-- `doxloop review` launches supported agents in read-only or plan mode.
-  Create and update require write access to the documentation project.
+  configured source list on the **Sources** page is an authoring-policy
+  boundary, not an operating system sandbox.
+- Product sources are read-only evidence. Planning runs are read-only. The
+  generation workflow tells the agent to write only inside an isolated
+  proposal workspace within the documentation project, and nothing reaches the
+  real documentation until a reviewer accepts it.
+
+## The control center
+
+The control center binds to the loopback address only and is never exposed to
+the network. Project files, tokens, and repository credentials stay on the
+machine; the browser receives project state, proposals, and logs, never
+credentials. Personal access tokens entered for private Git repositories are
+held in memory for the session, forwarded to Doxloop child processes through
+the environment rather than the command line, and never written to the project
+configuration. Authoring jobs are cancellable, proposals stay isolated until
+accepted, and deployment is a separate confirmed action.
 
 ## Local files
 
-The documentation `contentDir` must be a relative directory inside the project.
-Doxloop rejects project-root, escaping, absolute, and symlinked content
-directories. Deployment rejects a content directory that differs from
-`.doxloop/project.json` and refuses symlinks anywhere in documentation content.
+The documentation `contentDir` must remain contained by the documentation
+project. New native Doxbrix projects use `contentDir: ""`, so their Markdown,
+MDX, assets, and `docs.json` live at the project root; Doxloop allows that root
+only for the native Doxbrix generator and excludes operational, VCS, dependency,
+and build directories from page discovery and deployment. Legacy native
+projects with `contentDir: "docs"` remain supported. External generators must
+use a non-empty relative content directory. Escaping, absolute, and symlinked
+content directories are rejected, and deployment refuses symlinks anywhere in
+the selected documentation content.
 
-The first-run create flow rejects a documentation project that is the same as,
-inside, or contains a configured product source. It also rejects configured
-sources that are missing and non-empty output directories before writing project
-files.
+The setup wizard rejects a documentation project that is the same as, inside,
+or contains a configured product source. It also rejects configured sources
+that are missing and an output directory that already exists.
 
 Do not place credentials, private keys, environment files, internal data, or
 product source under the documentation content directory.
@@ -40,9 +55,19 @@ product source under the documentation content directory.
 Authoring and validation do not publish. A coding agent may still have network
 access according to its own configuration.
 
-Design capture:
+Remote OpenAPI sources follow the [remote OpenAPI safety policy](./openapi-security.md).
+Existing documentation sites are crawled with the same host controls (public
+HTTP(S) only, no embedded credentials, private and loopback ranges refused on
+every redirect), without executing page scripts, honoring `robots.txt`, and
+within page-size and page-count limits; see
+[Rewrite existing documentation](./existing-documentation.md).
+Git repository sources are downloaded as read-only snapshots through the
+provider's read API; Doxloop never clones, fetches, commits, pushes, or changes
+hooks in a source checkout.
 
-- accepts only configured HTTP or HTTPS reference origins;
+Design-reference capture:
+
+- accepts only configured public HTTP or HTTPS reference origins;
 - captures at most three requested pages per origin;
 - blocks navigation away from the configured origin;
 - blocks loopback, private, link-local, multicast, and other non-public network
@@ -50,38 +75,76 @@ Design capture:
 - stores screenshots and measurements under the Git-ignored
   `.doxloop/cache/reference/`.
 
-For a trusted local documentation reference, set
-`DOXLOOP_ALLOW_PRIVATE_REFERENCES=1` for that capture invocation.
-
 Application guide screenshots are separate authoring actions. They run only
-when requested, forced with `--screenshots`, or enabled by the optional
-`application.screenshots.policy`. The authoring workflow limits navigation to
-the configured application surface and requires non-production fixtures or test
+when **Add product screenshots?** is enabled for a run, when the request asks
+for them, or when the screenshot policy under **Settings → Visual evidence** is
+set to automatic. When capture is enabled, Doxloop injects a run-scoped
+Playwright MCP browser into supported Codex and Claude authoring processes; it
+does not modify the user's global agent configuration. The browser runs
+headless with an isolated profile, writes into the proposal workspace, and
+closes with the agent run. The authoring workflow limits navigation to the
+configured application surface and requires non-production fixtures or test
 accounts, but the selected coding agent and its browser retain the permissions
 granted by their host. Do not configure a production application, store
 credentials in `.doxloop/project.json`, or expose customer data for capture.
-Use `--no-screenshots` when the authoring environment should not operate an
-application.
+Choose **No screenshots** for a run, or set the policy to **Never**, when the
+authoring environment should not operate an application. Plans also require a
+machine-readable capture manifest. Doxloop rejects captures outside the
+approved visual pages, unsafe asset paths, missing or unreadable PNGs, blank or
+duplicate images, unembedded files, and captures that have not completed
+expected-state, privacy, legibility, and meaningfulness review.
 
 Doxbrix API requests require HTTPS. HTTP is accepted only for loopback
 development. Authenticated and device-flow requests refuse redirects.
 
+Release-quality external-link checks accept only credential-free HTTP or HTTPS
+URLs, validate every redirect destination, and block private, loopback,
+link-local, reserved, or unresolved addresses. Cached responses support
+offline CI. Authentication responses and temporary network/server failures are
+warnings rather than definitive broken-link failures.
+
+Executable examples are opt-in. Declared Node files run with explicit
+filesystem permissions and no network permission; Python files run in isolated
+mode with socket creation and process-launch APIs blocked. Both use a minimal
+environment, explicit fixtures, a timeout, no shell, and a temporary workspace
+that is cleaned afterward. OpenAPI request examples are checked against the
+connected contract without contacting an API. Apparent credentials are
+rejected, and runtimes without a portable sandbox remain visibly
+source-verified rather than silently executed.
+
+Rendered accessibility and visual checks load generated local HTML and abort
+all browser network requests. Current screenshots and quality reports are
+derived, Git-ignored artifacts; approved visual baselines are separated by
+generator, theme, route, and viewport.
+
+Interrupted job checkpoints, raw job logs, proposal-delivery records, and the
+bounded reviewer-preference record are local, owner-readable, Git-ignored
+artifacts. Persisted retry data is accepted only for known Doxloop actions and
+project-contained working directories. Reviewer instructions are length-bound
+and known private-key and provider-token formats are redacted before reuse.
+
+**Prepare PR branch** works in a temporary Git worktree and does not switch or
+edit the current checkout. **Push branch** and **Push & create PR** are
+separate explicit actions. Doxloop invokes Git and GitHub CLI with argument
+arrays rather than a shell and does not expose a pasteable shell command built
+from branch names.
+
 ## Credentials and publishing
 
-Prefer `doxloop login` and the device flow. Environment variables avoid placing
-tokens in shell history; `--token` is intended for controlled automation.
-Stored credentials use user-only file permissions on operating systems that
-support them.
-
-Only `doxloop deploy` publishes. Native projects send a contained documentation
-bundle to the Doxbrix API. External generators are built on the user's machine;
-Doxloop removes its Doxbrix tokens from the child build environment, scans only
-the declared static output, rejects symbolic links/private keys/likely secret
-files, omits source maps, and enforces file and expansion limits before packaging.
-Deployments are private by default. A saved public deployment or
-`doxloop deploy --public` shows a default-no warning that anyone will be able
-to access the site. Non-interactive publishing requires explicit saved settings
-or `--public` together with `--yes`.
+Sign in from the **Publish** page with **Sign in with browser**, which uses a
+device flow so no token is typed or pasted. Stored credentials use user-only
+file permissions on operating systems that support them, and **Sign out**
+removes the local token.
+
+Only **Publish to Doxbrix** publishes. Native projects send a contained
+documentation bundle to the Doxbrix API. External generators are built on the
+user's machine; Doxloop removes its Doxbrix tokens from the child build
+environment, scans only the declared static output, rejects symbolic
+links/private keys/likely secret files, omits source maps, and enforces file
+and expansion limits before packaging. Deployments are private by default. A
+public visibility setting is shown on the Publish page before every deployment,
+with a note that anyone with the URL will be able to open the site. A **Dry
+run** validates and builds without uploading anything.
 
 The archive is uploaded directly to one short-lived, single-object S3 URL whose
 SHA-256 checksum is signed. Doxbrix verifies the object size and checksum before

package/docs/troubleshooting.md

@@ -1,103 +1,236 @@
 # Troubleshoot Doxloop
 
-## Check the complete setup
+## The control center does not open
 
-Inside an existing documentation project, run:
+Doxloop requires Node.js 22.13 or later. If the browser does not open
+automatically, visit `http://127.0.0.1:4317` yourself. If another process is
+using that port, start Doxloop on a different one:
 
 ```bash
-doxloop doctor
+doxloop ui --port 4400
 ```
 
-Before creating a new project, check the proposed sibling directories:
-
-```bash
-doxloop doctor --source ./my-product --output ./my-docs
-```
-
-Doctor checks the Node.js version, product-source boundary, selected agent and
-authentication, project skills, generator readiness, and documentation
-validation, plus the default preview port. It exits with code 1 when a required
-check fails.
-
-## No supported agent is available
-
-Install Codex, Claude Code, or Gemini CLI and confirm its executable is on
-`PATH`. Alternatively:
-
-```bash
-doxloop create --print
-```
-
-Paste the prompt into an agent session opened at the project root.
-
-## An installed skill is modified
-
-Doxloop does not overwrite local skill changes automatically.
-
-```bash
-doxloop agent status
-doxloop agent update
-```
-
-Review the diff before replacing intentional customizations.
-
-## An external generator cannot load
-
-Install both core and the selected generator package in the documentation
-project. Then run:
-
-```bash
-doxloop generator doctor
-```
-
-Native generators may also require Python, Ruby, Hugo, or Node dependencies.
-The doctor output reports the expected build command.
-
-## Create exits but synchronization is not recorded
-
-Doxloop withholds the baseline when validation fails or the create brief lacks
-`primaryAudience` or `priorityOutcomes`. Run `doxloop test`, resolve every
-error, and rerun create or update.
-
-## Capture blocks a URL
-
-Capture rejects unconfigured origins, cross-origin navigation, and private
-network destinations. Add the intended public origin with `--reference`. For a
-trusted local reference only:
-
-```bash
-DOXLOOP_ALLOW_PRIVATE_REFERENCES=1 doxloop capture http://localhost:3000/
-```
+The control center opens the setup wizard when the current folder is not a
+documentation project, and the workspace when it is. To open an existing
+workspace, start Doxloop inside that documentation folder.
+
+## The wizard rejects the workspace folder
+
+Enter a folder name, not a path. The folder is created inside the directory
+where you started Doxloop and must not already exist. A documentation project
+also cannot be the same as, inside, or contain a connected source folder, so
+start Doxloop from the parent folder of your product rather than from inside
+it.
+
+## A source cannot be connected
+
+On the **Sources** page, choose **Test connection** to see the exact reason.
+Local folders must exist and be outside the documentation project. Git
+repositories need a reachable URL and branch; private repositories need a
+username and personal access token with read access. OpenAPI URLs must be
+public, credential-free HTTP or HTTPS addresses that return a valid OpenAPI 3.x
+or Swagger 2.0 document; see the
+[remote OpenAPI safety policy](./openapi-security.md). Upload the file instead
+when the specification is not publicly reachable.
+
+## No coding assistant is available
+
+Choose Codex, Claude Code, or Gemini in the wizard's **Tools** step or in the
+**Planning agent** field. If it is not installed, Doxloop offers to install
+it. After installation, sign in to the assistant once in a terminal so it can
+run without prompting; Doxloop never stores model API keys.
+
+## A run stops because an installed skill was modified
+
+Doxloop refreshes the project-local authoring skills before each run and will
+not overwrite a skill with local edits. The run's **Live activity** log names
+the changed directory under `.agents/skills` or `.claude/skills`. Delete or
+restore that directory and start the run again; Doxloop reinstalls the
+packaged version.
+
+## An external generator cannot build
+
+External generators need their adapter package and native toolchain. Choose
+**Preview docs**, or publish: a publish runs the generator's strict build
+first, uploads nothing if it fails, and its log names the failing command. Native generators may
+require Python, Ruby, Hugo, or Node dependencies in addition to the adapter.
+
+## Validation warns that navigation was not verified
+
+`navigation-unverified` means the generator's sidebar or menu is produced by
+something Doxloop cannot read statically: a Hugo or Jekyll theme, a MkDocs
+navigation plugin, a Starlight plugin, a VitePress or Starlight sidebar built
+by a function or imported from another file, or a Sphinx `autosummary`
+toctree. It is a warning, not an error, and it replaces the false
+"unnavigated page" errors those sites used to get. Publishing performs the
+generator's strict build first, which confirms every page is reachable. To turn the warning into real checks, list the navigation
+in the generator's own configuration file instead of building it in code.
+
+## The wizard says a generator's tools are missing
+
+The **Tools** step checks the runtime the selected generator needs: Node.js
+20.12 or later with npm, pnpm, or yarn; Python 3.9 or later with the `venv`
+module; the `hugo` binary; or Ruby with Bundler. The project can still be
+created, because the adapter package installs with npm, but **Preview docs**
+and the strict build fail until the tool is installed. Install it, then choose
+**Check again**. The check runs on the machine where `doxloop ui` runs, not on
+the machine whose browser shows the control center.
+
+## A plan cannot be approved
+
+**Approve & generate** stays disabled while questions remain under **Needs
+your decision**, while a required screenshot page is missing its starting
+route or capture details, or while screenshots are required and the
+configured application is not reachable. Resolve each item, or change the
+run's screenshot mode to **Automatic** or **No screenshots**.
+
+A change to a connected source after the planner read it does not block
+approval. The plan review notes that sources changed, the structure is
+approved as proposed, and generation reads the current sources when it writes
+each page. Choose **Ask the agent to revise** only when the change should
+alter which pages are written.
+
+## A button stays on "Working…"
+
+The control center waits at most two minutes for a local request and then
+reports that the server did not respond. If that happens, check the terminal
+where `doxloop ui` is running: a stopped or crashed server needs to be started
+again, and a run that was interrupted can be retried from its last durable
+stage under **Recent activity**.
+
+## Planning stopped after 20 minutes
+
+The planner has a time budget so a run that never answers becomes a named
+failure rather than a silent hang. The plan shows **Planning stopped after
+20 minutes without a plan reply** and can be retried. Raise **Maximum agent
+minutes** under **Monitoring → Advanced watch scope and budgets** when the
+product genuinely needs longer research, or set `DOXLOOP_PLAN_TIMEOUT_MINUTES`
+in the environment that starts `doxloop ui` to change the planning budget
+alone. A planning run that is stopped is ended together with any capture
+browser it opened.
+
+## Stop leaves the workspace changing
+
+Stopping a run ends the agent and the capture browser it started within ten
+seconds. If files still change in the run workspace afterwards, the agent
+process was started outside Doxloop's control, for example from a terminal
+where `doxloop create` was run interactively; close that terminal session to
+end it.
+
+## A run fails after the agent already did most of the work
+
+A generation run can stop after the pages are written, for example when
+required screenshots were not captured for every guide, when the agent hit its
+time budget, or when validation found a problem. Doxloop keeps that run's
+isolated workspace, so nothing the agent wrote or captured is lost. The plan
+review shows **Continue without starting over** with the choices that apply:
+
+- **Resume generation** starts the agent again inside the same workspace with
+  a brief of what is already finished: which pages exist, which screenshots
+  are verified, and why the previous run stopped. Verified screenshots and
+  completed pages are kept; only the unfinished or rejected parts are redone.
+- **Ignore problems & continue** accepts the generated files for review as
+  they are. Every screenshot problem is recorded on its manifest step as
+  text-only, broken image references are removed from the page, and the
+  proposal shows how many problems were ignored so you can judge them before
+  publishing.
+- **Retry generating** in the footer starts a new run from the approved plan.
+  Use it when the workspace itself is unusable.
+
+The same two actions appear on a failed proposal under **Review**. When the
+planner itself fails a planning gate but proposed real pages, the plan review
+offers **Review this plan anyway**, which opens that plan for editing and
+approval with the unmet gate shown as a note.
+
+Source code that changed after the run stopped never blocks either
+continuation. The proposal carries a note that sources changed, a resumed agent
+re-checks the pages it touches against the current sources, and the proposal's
+evidence snapshot is refreshed so it can be accepted.
+
+## The run reports a Claude API error
+
+Claude's own API request can break off mid-response: the log shows a line such
+as `API Error: Server error mid-response`, `overloaded`, or a rate limit, and
+Claude exits. Nothing in the documentation task caused this, and the agent's
+session is intact, so Doxloop resumes that session in the same workspace after
+a short pause, up to twice per run. The log shows **Resuming the same session
+(attempt 1 of 2)**, and the agent continues with its context, keeping every
+page and screenshot it already produced.
+
+The run fails only when every resume fails too. The message then names the
+API error and how many resumes were tried. Use **Resume the run** under
+**Continue without starting over** once the API is available again; it
+starts the agent in the same workspace with a brief of what is finished, so
+completed pages and verified screenshots are not paid for twice. Do not use
+**Retry generating**, which starts a new run from the plan and captures
+everything again.
+
+Set `DOXLOOP_AGENT_API_RESUMES` in the environment Doxloop runs in to change
+how many automatic resumes a run gets; `0` disables them.
+
+## Generation finishes but nothing changed
+
+Generation never edits the documentation directly. Open **Review** to inspect
+the proposal and accept its changes. The **Home** page shows **Needs your
+review** whenever a proposal is waiting.
+
+## Accepting a change reports a conflict
+
+A file was edited outside Doxloop while the proposal was pending. Doxloop
+compares the original fingerprint before writing and stops rather than
+overwriting your edit. Review the current file, then use **Ask agent to
+revise** to regenerate the affected page against the new content, or edit the
+page directly in the proposal.
 
 ## Guide screenshots are missing
 
-Application guide screenshots are created during `doxloop create` or
-`doxloop update`, not by design-reference capture. Ask for screenshots in the
-request or pass `--screenshots`. Configure `application.baseUrl` and, when
-Doxloop should start the application, a configured source name plus
-`startCommand` in `.doxloop/project.json`.
-
-If the selected agent has no browser capability, the application is unreachable,
-or authentication and safe test data are unavailable, Doxloop keeps the text
-guide complete and omits broken image links. Establish a non-production browser
-session or local fixture and rerun the affected update. Never provide production
-credentials or customer data for screenshot capture.
-
-## API requests fail
-
-Confirm the API URL uses HTTPS, the token starts with `dxb_`, and the endpoint
-does not redirect. HTTP is accepted only for loopback development. Prefer
-`doxloop login` to refresh credentials.
-
-## Preview port is occupied
-
-Choose another port:
-
-```bash
-doxloop preview --port 4400 --open
-```
-
-## Validation and native builds disagree
-
-`doxloop test` performs fast project and content checks; the native build is the
-final generator parser. Run both and treat either failure as blocking.
+Application screenshots are captured during generation, not during planning.
+Enable them with **Add product screenshots?** on the Create or Update page, or
+set the policy under **Settings → Visual evidence**. Configure the
+**Application base URL**, a **Ready path**, and a safe **Default starting
+route**, then choose **Test application** to confirm the page is reachable.
+
+If the selected assistant has no browser capability, the application is
+unreachable, or safe test data is unavailable, Doxloop keeps the text guide
+complete and omits broken image links.
+
+When **Test application** reports **Sign-in needed**, open **Application
+sign-in** on the same page. **Sign in with browser** opens a Chrome window where
+you sign in by hand, including MFA or SSO; choose **Save session** once the
+signed-in screen is showing, and every capture run starts with that session
+loaded. For a plain username and password form you can instead save a test
+account's credentials; the agent fills the form by secret name and never sees
+the values. A **saved browser session has expired** message means the
+application no longer accepts the recorded session: sign in with the browser
+again. Both are stored on your computer outside the project, never in the
+repository. Never provide production credentials or customer data for
+screenshot capture.
+
+## Monitoring does not run
+
+Open **Sources → Monitoring**. Every source type can be scheduled: a Git
+repository through its provider, a local folder in place. On macOS, Doxloop
+tests the scheduled job in the real scheduler context when you choose **Save
+and install** and reports whether the background process can find the coding
+assistant. Choose **Check now** to run one cycle immediately; a notice reports
+its result and the full log is under **Recent activity** on the Home page.
+
+A local folder without Git history reports "no sync baseline" until the first
+accepted update records one. Run **Plan** once so later checks can compare
+the folder's files against that baseline.
+
+## Deployment fails
+
+Deployment stops when validation reports errors. Open **Review** to see the
+errors on the affected files, or open the failed publish's log on the
+**Publish** page for the full validation and build output. If Doxbrix does not
+accept the saved sign-in, choose **Sign in again**; the Doxbrix API requires HTTPS and does not
+follow redirects. **Deployment history** on the same page keeps the outcome of
+every attempt.
+
+## Preview shows stale content
+
+**Preview docs** serves the accepted documentation, not a pending proposal.
+Use **Preview documentation** on the Review page to see a proposal before you
+accept it. The local preview runs on port 4321; close any other server using
+that port.