@doxbrix/doxloop 0.1.5 → 0.2.0

package/CHANGELOG.md

@@ -5,6 +5,1151 @@ uses semantic versioning after its first stable release.
 
 ## Unreleased
 
+## 0.2.0 - 2026-09-27
+
+### Changed
+
+- **Docs get the spaces the plan asks for again.** Since authoring moved to
+  batches, Doxloop builds the navigation, but plan sections never said which
+  space they belong to, so most pages landed in the first space and planned
+  spaces were dropped as empty (a 23 Sept Memos plan with three spaces came
+  out with one and a half). Each plan section now names its space, older
+  plans get one by name ("APIs" → "API & integrations"), and missing spaces
+  are created in the plan's order. Replaying that run gives all three.
+- **Setup checks what used to fail a first run.** The wizard picks a signed-in
+  assistant, says plainly when one is signed out (with the command to fix it
+  or a one-click switch), starts at reasoning "high" with screenshots on,
+  refuses reasoning values the model does not offer, and keeps unfinished
+  answers as a draft (never passwords or tokens).
+- **Sign-in pages are detected.** "Check page" opens the app in a headless
+  browser, so a single-page app that sends visitors to `/auth` or
+  `/_/#/login` is reported, sign-in is switched on and its route filled in;
+  "Continue without signing in" stays available and tells the planner not to
+  ask for credentials. Hash-routed app URLs such as `https://host/_/#/` are
+  accepted again.
+- **Plans and runs fail with the agent's real reason.** Planning and retries
+  check the assistant's sign-in first; a failed plan shows the agent's own
+  error and offers "Retry with" another assistant. Codex and Claude sessions
+  run with only Doxloop's tools, and the computer stays awake while a job runs
+  (`DOXLOOP_KEEP_AWAKE=0` turns it off).
+- **Quieter, more honest screens.** Form help moved into info tooltips; the
+  plan page warns when few guides will have screenshots and gives a rough
+  time and token estimate; review counts agree, coverage reads "Screenshots
+  in 2 of 41 guides", and the apply dialog closes when it is done. The live
+  log hides colour codes, raw JSON replies, and stdin noise.
+- **Consistent output.** Pages are always `.mdx` for Doxbrix, sections are not
+  split into one-page duplicate groups, regex text is no longer read as a
+  link, a leftover starter page is removed instead of rewritten, and missing
+  parameter examples no longer start agent fix sessions when the endpoint
+  already has a request sample.
+
+- **A batch that writes nothing is no longer reported as finished.** On 21
+  Sept 2026 a 34-page Uptime Kuma run wrote 16 pages: five of its nine batch
+  sessions hung waiting for the model, were stopped at their 16-minute cap,
+  and — because Codex exits 0 when stopped — were counted as complete. The
+  final check then deleted every link to the 18 unwritten pages and the run
+  reported success. A batch is now judged by which planned files it actually
+  wrote (compared with their content before the session): missing pages are
+  retried once in a fresh session, and pages still missing fail the run with
+  their names, so "Retry" continues with only the unfinished pages.
+- **A silent session is stopped after six minutes, not sixteen.** Every
+  session has an inactivity watchdog: when the agent prints nothing for
+  `DOXLOOP_AGENT_IDLE_MINUTES` (default 6, 0 disables it), the session is
+  stopped and the batch retries in a fresh session instead of waiting for
+  the wall-clock cap. Writers are also told to save each page as soon as it
+  is complete, so a stopped session keeps the pages it finished.
+- **Two batch sessions at a time by default, not three.** All three model
+  streams in flight hung at the same second in the run above;
+  `DOXLOOP_AUTHORING_PARALLEL` still raises the number.
+- **Accepting one file of a new site's proposal works.** Accepting a single
+  page before the proposal's navigation and starter-page replacements failed
+  with "starter-content" and "unnavigated-page" errors on files the reviewer
+  had not accepted yet. Errors that the not-yet-accepted part of the same
+  proposal resolves no longer block; the rest still do.
+- **Answering a plan's questions no longer regenerates the whole plan.** A
+  revision used to return the entire plan again (five minutes to apply three
+  answers on a 34-page plan). The reviser now returns only the pages it
+  changed as a patch that Doxloop merges into the existing plan, answered
+  questions are removed deterministically, and an unreachable capture
+  application is a warning for a revision rather than a failed job.
+- **Broken links to pages the same proposal still adds do not block a
+  partial accept either**, and the authoring progress never reads "36 of
+  32": the count is capped at the planned total. Writers are told to create
+  pages as whole-file adds and rewrite existing pages whole, after
+  line-level hunks against long prose failed Codex's patch verification in
+  every real run.
+- **Smaller evidence packs.** Per-batch packs are capped near 60 KB
+  (fewer, shorter excerpts per page) after 85–143 KB packs made up most of
+  each session's uncached input.
+- **An update request is triaged before any research runs.** On 17 Sept
+  2026 a one-line request to add icons to the sidebar ran the same research
+  as a product-wide create run: a product audit and three audits of the
+  crawled Vikunja docs, five minutes and 567k tokens, before planning even
+  started, because the research sessions were chosen from the project
+  configuration alone. Now the request decides: a navigation, icon, ordering,
+  branding, or metadata request researches nothing and is planned from the
+  current navigation in one session; a request that names existing pages
+  audits only the product surface behind them and skips the existing-site
+  audit and the application exploration; a product-wide request runs the
+  full research as before. Clear cases are decided from the request text; an
+  ambiguous one gets a short triage session that reads nothing, and when that
+  fails the full research runs. The decision is kept on the plan and shown
+  first among the review advisories. A navigation-only plan carries the exact
+  change in a new `workspaceInstructions` field, which generation applies in
+  one short session after the pages are written, so a plan whose pages are
+  all preserved still does the approved work.
+- **Research briefs are reused across plans on unchanged sources.** A second
+  update on the same source snapshot used to redo every research session.
+  The brief key no longer includes the plan id, so the newest plan's product
+  and existing-documentation briefs are borrowed (and copied under the new
+  plan) when the sources, capture intent, agent, and model match; the
+  application brief stays plan-local because it names captures saved under
+  its own plan. A page-scoped audit is keyed by its pages and also accepts a
+  full audit of the same sources.
+- **Generation runs three batches at a time again, and the run does less
+  repeated work.** A 40-page run measured on 16 Sept 2026 wrote 12 pages in
+  25 minutes because batches had gone back to running one after another and
+  every batch redid the same research. Now: the writer sessions run up to
+  three at a time (`DOXLOOP_AUTHORING_PARALLEL`, default 3); the planning
+  stage's screenshots are adopted even when the browser tool saved them at the
+  project root instead of the plan's capture directory (before, every one of
+  them was silently re-captured); missing captures are taken in a few pooled
+  browser sessions of several guides each instead of one sign-in per guide,
+  and a capture session that stops no longer aborts the run before any page
+  is written; Doxloop signs in with the saved credentials itself before
+  leaving a login-gated entry screen to the agent; evidence packs now carry
+  the research findings for each page (linked through the plan's
+  capabilities), anchor a cited file on the quoted label, and pick the label
+  catalog entries about the page instead of the file's first 140 lines;
+  planning cites two to four line-numbered evidence files per page; and the
+  writer is told which directories its evidence lives in and to keep tests,
+  fixtures, migrations, generated bundles, other-language catalogs and
+  lockfiles out of its searches.
+- **Doxloop owns the metadata; agents own page bodies and images.** The
+  evidence map is now Doxloop's record: an agent-written evidence file is
+  input — its claims are kept, its source paths only where the file exists,
+  and the plan's citations plus the source files the session actually opened
+  (from its tool calls) are always present; a `verified` over no real path
+  becomes `inferred`. A writer session's copy of the screenshot manifest is
+  never merged back — the manifest belongs to the capture stage and is
+  decided from the images on disk. A plan's `captureIds` that name no image
+  the application research saved are blanked at planning time with a note,
+  instead of being treated as done. And the last three hard failures after
+  writing — a page outside the plan, a page or screenshot count over the
+  approved batch, a page attributed to a source scoped to another route —
+  are now review notes on the proposal (the stray attribution is removed
+  from the evidence map), not a discarded run.
+- **A run that ends "generated" is one the reviewer can apply.** The
+  validation that "Accept all" performs now runs as the last step of
+  generation, after Doxloop's own repairs: navigation and frontmatter,
+  links, embeds of images that no longer exist, navigation entries for pages
+  that do not, starter pages the plan superseded, and unplanned pages the
+  writer left outside the navigation. What cannot be repaired is shown on the
+  proposal; nothing waits for the click to fail. Images a check sets aside
+  are moved to `.doxloop/quarantine/` inside the run instead of deleted, so a
+  wrong downgrade costs a note, never the picture. `doxloop replay
+  <run-directory>` re-runs exactly this pipeline over a copy of a recorded
+  run's workspace in seconds, so a change to any of these steps is verified
+  against real manifests and pages before the next half-hour run.
+- **A proposal no longer loses its screenshots over bookkeeping.** A verified
+  manifest step whose image exists but that lacks a `target` (every capture
+  reused from planning) or `alt` counted as a defect: a run retook thirteen
+  good images, then the acceptance check downgraded them all, deleted the
+  PNGs, and left the landing page with a broken image link the proposal could
+  not be applied over. Doxloop now fills `target` from the step's action and
+  `alt` from its expected state; only a missing image is a defect. A generated
+  starter page the plan did not replace is removed in the final check instead
+  of being handed to a fix session that rewrote it into an unnavigated page.
+- **Capture status is decided from the image on disk, not from the agent's
+  word.** Capture sessions had recorded `status: "captured"`, which is not a
+  manifest status, so every image they took counted as a defect: a real run
+  retook thirteen screenshots it already had (5.5 minutes, 9.4M tokens) and
+  still ended with three invalid rows. After every capture and retake session
+  Doxloop now verifies each step whose PNG exists at the recorded path, is at
+  least 320×180 and is not blank, and resets any other claimed capture to
+  planned with the reason in the log; the capture prompt also names the four
+  allowed statuses.
+- **Mechanical sessions think less.** Capture, fix-round, and retake sessions
+  run at low reasoning effort (`DOXLOOP_SUPPORT_EFFORT`); writers keep the
+  plan's effort, or `DOXLOOP_AUTHORING_EFFORT` when set. On a real run 86% of
+  the output tokens — and, at ~200 tokens a second, most of the wall time —
+  were hidden reasoning, and a session that adds a code-fence language or
+  signs in and takes a picture gains nothing from it.
+- **Writers no longer re-read the same files every batch.** The skill
+  references every batch needs (editorial style, page depth, the evidence-map
+  section, the generator's component and manifest syntax, screenshots when
+  captures are on) are inlined once at the start of the writer prompt as a
+  stable prefix the prompt cache serves; each batch's evidence file arrives
+  pre-seeded with an entry per page from the plan's citations; and the
+  contract carries the titles and icons of the pages already written. A real
+  run spent about 120 turns on those reads across ten batches. Unlabeled code
+  fences get the `text` language from the post-pass instead of a fix session.
+- **A link to a page another batch has not written yet is not a defect.** The
+  per-batch check used to send it to a fix session, which removed the link
+  — a page linking to the guide written a minute later lost the link for
+  good. Those links are checked once at the end of the run, and the
+  navigation spaces the first batch creates for later sections are no longer
+  pruned between batches.
+- **Standard and comprehensive plans have no page cap.** The 12- and 40-page
+  defaults were back; a comprehensive plan for a product with more screens was
+  silently trimmed to forty. A reviewer can still set a cap on the plan
+  review's batch-limits panel.
+
+- Planning now saves reusable screenshots with state and label evidence. Approved
+  writers embed saved images; missing states use separate capture sessions.
+  Evidence packs resolve source symbols and translation keys and reuse planning
+  findings. New plans use bounded scope and meaningful images instead of a fixed
+  screenshot count per page type.
+- Planning and generation share a persistent token/cost ledger across retries. No limit applies unless `sync.budget.maxUsd`, `DOXLOOP_MAX_USD` or `DOXLOOP_MAX_TOKENS` is set explicitly.
+  Quota exhaustion stops scheduling, child crashes can retry, and completed
+  writing is retained separately from validation repairs. See
+  [generation performance](docs/generation-performance.md) for defaults and overrides.
+
+- **The live log shows when each step happened and what the agent is doing
+  while it is quiet.** Every line a run writes now carries the local time it
+  arrived, in the control center and in the full log file, so the time each
+  step took can be read off the log. A tool call that took longer than a
+  second shows its duration when it finishes. A stretch with no output gets a
+  progress line every 30 seconds naming the current phase: waiting for the
+  agent's first response, thinking, writing a long reply (with how much has
+  streamed so far), or waiting for a named tool call to finish. A planning
+  session that thought for three minutes and then streamed a 90 KB plan used
+  to show nothing after "Using ToolSearch" and read as a hang; the same run
+  now reports its progress. Tool lookups also show what was looked up.
+
+- **A finished proposal no longer arrives with errors that block applying
+  it.** Three causes were fixed. Doxloop's navigation repair added every page
+  to the first space in docs.json, so a plan with "Guides", "Self-hosting",
+  and "API" spaces left the last two empty; pages now go to the space their
+  plan section or path names, and a space nothing landed in is removed. A
+  planned page written over a starter file (the landing page as the site's
+  index) is now recognised there, so links to its planned path are rewritten
+  to the file that exists instead of staying broken. And the end-of-run check
+  now sweeps the whole workspace, not only the planned pages: a link that
+  resolves to no page becomes plain text, and any remaining error in a starter
+  page or docs.json gets one fix session. The "not applied" message now lists
+  only the errors that block, not every depth warning.
+- **Batched authoring sessions sign in with saved credentials.** The
+  per-batch prompts never carried the sign-in handling the old single-session
+  prompt had, so a project with saved credentials still stopped at the login
+  page and recorded every authenticated screenshot step as text-only (28 of 41
+  planned captures in one run). Every batch, fix, and retake session now gets
+  the capture and sign-in instructions, and is told that a redirect to the
+  sign-in page is not a blocker while sign-in material is available.
+- **No page cap for standard and comprehensive plans.** New plans were capped
+  at 12 or 40 pages with no way to change it before planning. Standard and
+  comprehensive scopes now have no page limit: the planner is told the
+  evidence sets the size, and the wizard shows "No page limit". A cap can
+  still be set on the plan review. Starter plans stay at five pages.
+- **Depth fixes stop padding.** The fix session for thin-page warnings now
+  adds only evidence-backed parts, leaves a complete page alone and says so,
+  and never fills a page with generic advice, restated steps, or demo data.
+  The authoring skill also states that what the capture application shows is
+  fixture state, so pages describe the reader's own project instead of a demo
+  route id or task name.
+- **A resumed run shows the pages it kept.** The authoring progress counter
+  started at "0 of N" on resume and only ever reached the pages the fix
+  sessions touched, which read as a run starting from scratch. Pages the run
+  found finished now count as done from the start.
+- **The end-of-run screenshot check no longer crashes with `EISDIR`.** A
+  planned page path such as `guides/manage-tasks` names both the page file
+  and the directory holding its captures; the check read the directory as the
+  page and the whole run failed at its last step. Only files are read now.
+- **The screenshot retake session can start again.** The recorded session
+  and saved credentials were removed before the retake session ran, so its
+  capture browser failed to initialise every time; they are now kept until
+  the retake has finished.
+- **Planning runs as parallel research sessions plus one synthesis session.**
+  Instead of one session that read the sources, browsed the application,
+  audited every crawled page, and then wrote the plan, Doxloop now starts
+  short research sessions, up to four at a time (`DOXLOOP_PLANNING_PARALLEL`):
+  a product-surface audit, an application exploration when screenshots are
+  wanted, and one existing-documentation audit per twenty crawled pages. Each
+  returns a compact brief that is saved under the plan, and one further
+  session writes the plan from the briefs without browsing or re-reading. The
+  application session works within a budget of thirty browser calls. A
+  retried plan reruns only the briefs that are missing. `DOXLOOP_PLANNING_STAGED=0`
+  restores the single-session planner.
+- **Planning prompts and replies are much smaller.** The deterministic source
+  inventory the planner receives on every turn is now grouped text (about 10k
+  characters for a mid-sized product instead of 120k characters of JSON), with
+  regex hits on code lines summarised per file; the planner is told not to
+  read the authoring skill files; the corrective pass after a failed planning
+  gate returns only the pages it changed as a patch that Doxloop merges by
+  page id, instead of the whole plan again; and existing-page dispositions
+  list snapshot paths only, with titles and URLs filled in from the snapshot.
+- **A plan reply that stops short of its closing brackets no longer fails the
+  run.** Codex returned a 60k-character plan twice with the final `]}` missing,
+  and both attempts were rejected as "not a valid documentation-plan JSON
+  object". Doxloop now closes a reply that ends on a completed object or array
+  (a stray closing tag after it is ignored), reads the plan, and reports the
+  fix as an advisory on the plan review. A reply that is cut off inside a
+  value is still rejected, and the retry prompt now quotes the exact defect
+  and the reply's tail instead of a generic message, so the agent can correct
+  it. The planning prompt also states that the object's own closing brace must
+  be the last character before `</doxloop-plan>`.
+- **Reliable, cheaper, faster generation.** Approved plans are now written in
+  short batches of fresh agent sessions (four pages each by default, tunable
+  with `DOXLOOP_AUTHORING_BATCH_PAGES`), up to three batches at a time
+  (`DOXLOOP_AUTHORING_PARALLEL`; the landing page and a new site's setup run
+  first, alone), instead of one session that ran for hundreds of turns
+  re-reading a 600k-token context. Each batch gets its own plan slice, an
+  evidence pack with the excerpts the plan cites, and its own manifest and
+  evidence slices that Doxloop merges back, so concurrent sessions never edit
+  the same file. Depth warnings are fixed once at the end in a few concurrent
+  sessions instead of after every batch. Between batches Doxloop repairs
+  frontmatter, navigation entries, broken local links, and the evidence map
+  itself, validates the workspace, and sends only the remaining defects to a
+  short fix session. A batch that stops is retried once in a fresh session and
+  the rest of the run continues; a resumed run writes only the pages that are
+  still missing.
+- **Screenshots never fail a finished run.** Doxloop captures each guide's
+  entry screen itself with Playwright before the agent starts, checks every
+  image after the run, gives the agent one targeted retake session for the
+  problems it finds, and then keeps any remaining step as text with the
+  problem listed on the proposal instead of discarding the pages.
+- **Token usage is recorded.** Every run and request shows the tokens, cached
+  share, cost when the agent reports it, and number of sessions, in the run
+  log, the proposal, and the request history.
+- **Smaller prompts.** The authoring skill has a fast path for plan batches
+  that reads only the references a batch needs, the screenshot reference is
+  split into workflow and schema halves, and JSON injected into planner prompts
+  is compact. The agent is no longer asked to run `doxloop test`, node, or
+  python inside its sandbox, where they failed on every run.
+- A page the plan did not name but the writer modified is now a reviewable
+  change with an advisory rather than a reason to reject the whole proposal.
+  Undersized element captures are accepted down to 200×100.
+
+### Added
+
+- **Rewrite existing documentation.** **Add source → Existing documentation**
+  (in the setup wizard and on **Sources**) takes the address of the docs you
+  publish today. Doxloop crawls the site through its sitemap, `llms.txt`, and
+  links into a read-only Markdown snapshot, and the planner audits it against
+  your other sources: the plan review gains an **Existing documentation
+  audit** with coverage gaps, contradicted claims, obsolete and preserved
+  content, findings, and a decision for every crawled page (rewrite, merge,
+  preserve, or drop). Approving the plan records redirects from every old page
+  to the page that absorbs it. With only the site connected the agent
+  restructures and rewrites what the pages already say and marks every page
+  `inferred` until a product source is connected. The CLI accepts
+  `--docs <url>` on `init` and `create`, and the globe action on **Sources**
+  re-crawls a site. See [docs/existing-documentation.md](docs/existing-documentation.md).
+
+- **Screenshots behind a login.** **Settings → Visual evidence → Application
+  sign-in** (and the **Does this page require sign-in?** step of the setup
+  wizard) gets the capture browser past a login page two ways. **Sign in with
+  browser** opens a Chrome window where you sign in by hand, including MFA,
+  SSO, or passkeys; **Save session** records the cookies and local storage,
+  and every planning and capture run starts with that session loaded. For a
+  plain form you can save a test account's credentials instead: the agent
+  types the secret names `DOXLOOP_APP_USERNAME` and `DOXLOOP_APP_PASSWORD`,
+  the capture server substitutes the values and redacts them from every tool
+  result. **Test application** now reports whether the saved session still
+  signs in and which sign-in method a run will use. Sessions and credentials
+  live under the user's Doxloop config home, keyed by project root, never in
+  the repository; `application.authentication.loginPath` records only the
+  sign-in route. The CLI settings menu offers the same under **Application
+  sign-in**.
+- **Navigation editor.** **Pages → Navigation** shows the sidebar as a tree
+  you can drag to reorder, group into sections, rename, give icons, or hide
+  (Doxbrix), with keyboard equivalents on every row and a live preview
+  beside it. Doxbrix writes `docs.json`; MkDocs writes the `nav` list in
+  `mkdocs.yml` through new `readNavigationTree` and `writeNavigationTree`
+  adapter hooks. Generators whose navigation is code are named instead of
+  edited. Every write is validated and rolled back if it would break the site,
+  and the plan review gets the same editor for a plan's sections.
+- **Branding panel.** **Settings → Branding** edits the Doxbrix logo,
+  favicon, primary and light/dark accent colours, page backgrounds, colour
+  mode, code theme, and body, heading, and code fonts, with an image picker
+  and a live preview that reloads on save. Other generators are pointed at
+  their theme configuration file.
+- **Images and files.** **Pages → Images & files** uploads PNG, JPEG, GIF,
+  WebP, SVG, AVIF, ICO, PDF, video, and zip files (10 MB each, content
+  checked against the extension, SVG refused when it scripts) into the
+  generator's asset directory, lists where each one is used, edits alt text
+  across every embedding page, replaces or deletes files, and offers
+  **Insert an image…** in the page composer. Screenshot gallery rows gain
+  **Replace screenshot** for a run that is still under review.
+- **Page metadata.** Each page on **Pages** has a metadata form for the
+  title, description, sidebar icon, canonical URL, and social image, written
+  straight to frontmatter with validation, rollback, and history. The local
+  preview now emits the canonical and social tags the static build already
+  produced.
+- **Release notes template.** When a directory source is a Git checkout,
+  **Update** offers **Release notes**: pick the repository, version, and two
+  refs, and Doxloop collects the commits, changed files, and the matching
+  changelog section deterministically, then hands that inventory to the
+  planner and writer as the only evidence for a `release` page at
+  `release-notes/<version>`.
+- **Glossary page.** **Settings → Audience and voice** edits terminology as
+  term and definition rows and can generate a glossary page (Markdown, MDX,
+  reStructuredText, or HTML) from them, add it to the navigation, and record
+  it in the evidence map; hand-written glossaries are never overwritten
+  without asking.
+- **Planned diagrams.** Plan pages carry a `diagram` decision, defaulting
+  to required for concept pages and editable in plan review. The writer is
+  told which pages need a Mermaid block, validation reports a
+  `missing-diagram` warning for planned pages without one, and the preview
+  renders the diagram.
+- Update history records navigation, branding, asset, metadata, and glossary
+  writes alongside agent runs.
+
+- **Generator tiers and a toolchain check in the wizard.** Every generator now
+  carries a support tier (**Full**: Doxbrix, Docusaurus, MkDocs Material;
+  **Supported**: Sphinx, Hugo, VitePress, Starlight; **Basic**: Nextra,
+  Markdoc, Jekyll, Static HTML) and the runtime it needs. The **Tools** step
+  shows the tier beside the selected generator, checks that Node.js with a
+  package manager, Python with `venv`, Hugo, or Ruby with Bundler is installed,
+  and lists every generator's tier and requirements under **What each
+  generator supports**. **Settings → Generator** shows the same label.
+- **Navigation validation that understands real sites.** Sphinx follows
+  nested and glob toctrees from the root document; Hugo accepts section
+  pages, front-matter menus, and menu `pageRef`s from any TOML configuration
+  file; Starlight reads `autogenerate` groups, `slug` and `link` entries, and
+  lists every page when no sidebar is configured; VitePress reads
+  multi-sidebar objects and `base` prefixes; Docusaurus checks explicit doc ids
+  and trusts autogenerated sidebars; Jekyll reads nested `_data/navigation.yml`;
+  Nextra checks every `_meta` file against its own directory and no longer
+  demands that every page be listed; Static HTML follows links through
+  section pages. When a theme, plugin, function, or import builds the
+  navigation, validation reports one `navigation-unverified` warning instead of
+  false `unnavigated-page` errors.
+- **Authoring references for every generator.** Hugo, Jekyll, Markdoc,
+  Nextra, Starlight, and Static HTML skills gained `references/authoring.md`
+  covering callouts, tabs, code blocks, images, and Mermaid diagrams in the
+  generator's own syntax; the Docusaurus and MkDocs references gained image
+  and diagram sections. The Docusaurus scaffold enables
+  `@docusaurus/theme-mermaid`, the MkDocs scaffold registers the `mermaid`
+  fence, the Sphinx scaffold adds `sphinxcontrib-mermaid`, and the Hugo,
+  Jekyll, Markdoc, and Static scaffolds ship callout and tab markup plus a
+  Mermaid render path.
+- **Generator API hooks.** Adapters may implement `writeNavigation` (MkDocs
+  edits `nav` in place, keeping comments and Python tags; Markdoc rewrites
+  `navigation.json`) and `renderPage` (Static HTML returns the page's `<main>`
+  landmark), so later work can create pages and preview external generators
+  without a native build.
+- **Continuous integration.** `.github/workflows/ci.yml` runs typecheck, unit
+  tests, skill validation, and the boundary check on every pull request, then
+  scaffolds, previews, and builds every official generator through
+  `scripts/ci-generator-smoke.mjs`. `pnpm test` now compiles only the core and
+  generator packages instead of running the full build.
+
+### Fixed
+
+- **A research brief with swapped closing brackets no longer fails the plan.**
+  An update run on 17 Sept 2026 failed twice in a row with "malformed research
+  brief JSON object (Expected ',' or ']' after array element)": Codex ended the
+  product brief's top-level `unknowns` string array with `"}]}` instead of
+  `"]}`, and the retry made the same slip. The reply reader that already
+  appends missing closers now also rewrites a trailing run of wrong closers
+  with the ones the open structures need, records the fix as a repair note,
+  and still refuses a wrong closer that has more content after it. Applies to
+  plans, plan patches, and research briefs alike.
+- **Sidebar sections with nothing under them.** When the writer laid the
+  plan's top-level areas out as groups inside one space ("Self-hosting",
+  "API & integrations") and left them empty, the end-of-run navigation repair
+  created each plan section ("Install & upgrade", "API reference") as a
+  sibling group instead of nesting it, so the preview showed the area
+  headers with no pages beneath them while every page sat one group further
+  down. The repair now nests a section group under the area group the page
+  path or the plan's top-level list names, matches existing groups
+  case-insensitively, and removes any group still empty when the run ends.
+  The preview also no longer renders a group that has nothing visible in it.
+- **Saved sign-in reached the planner but not the writer.** Generation runs
+  in a throwaway workspace under `.doxloop/runs`, and the capture browser's
+  session and credentials are keyed by project path, so the authoring run
+  started its capture server without them. The agent typed the secret names
+  literally, the sign-in failed, and every screenshot guide ended text-only.
+  Proposal runs now load the sign-in material from the project, and a
+  secrets file orphaned by a killed run is swept before the next run starts.
+- **Comprehensive depth produced a five-page batch.** The setup wizard sent
+  every new plan with the small-batch limits (five pages, eight screenshots,
+  15 minutes) whatever depth was chosen, and the plan review showed the cap
+  only after planning had already trimmed the structure to fit. New plans now
+  take their limits from the depth, the wizard's Review step shows them, and
+  changing the depth on the Update page resets the run limits to match.
+- **A comprehensive plan no longer dies in the corrective pass.** Planning
+  was cut off at the 20-minute default even when the batch allowed 120, and
+  when the pass that repairs failed planning gates stopped, the complete
+  first proposal was thrown away. Planning now runs as long as the batch's
+  minutes unless a limit is configured, keeps the first proposal with its
+  advisories when the corrective pass does not finish.
+- **The Claude planner can open the application.** Planning used Claude
+  Code's plan mode, which refuses the capture browser's navigation, so the
+  planner spent its turns on blocked calls and never saw the screens it was
+  planning screenshots for. Planning now runs read-only by denying the
+  writing tools instead, so the capture browser works during planning as it
+  already did for Codex.
+- **A plan that failed while planning can be retried from its page.** The
+  plan review used to offer only "Retry generating", disabled because the
+  failed plan had no pages and no screenshot guide yet. It now offers
+  **Retry planning**, which runs the planning stage again with the same
+  brief.
+- **A killed planning or generation run no longer strands its plan.** A
+  process that was killed, crashed, or lost its UI server used to leave the
+  plan at "planning" or "generating" with nothing to retry. The UI now
+  records the interruption on the plan when the job ends and when it starts
+  up, so the review offers the retry.
+- **Planning continues from the reply it already has.** The planner's reply
+  is saved the moment it arrives, so a run stopped by its time limit, a
+  crash, or the user resumes from that reply instead of repeating the whole
+  planning pass. The saved reply is used only for the same brief, settings,
+  and source snapshot, and is discarded once the plan reaches review.
+- **Planning is faster.** A comprehensive plan used to spend most of its
+  time clicking through the application and then minutes emitting a very
+  long reply. The planner now explores the application within a fixed
+  budget of browser calls, using the source's routes and labels as the
+  inventory of screens; it is asked for a compact reply; and it runs at
+  medium effort, since planning is an inventory task over evidence Doxloop
+  has already extracted (authoring keeps the run's effort). The corrective
+  pass, which costs as much as the first proposal because the agent returns
+  the whole plan again, now runs only for findings that would block
+  approval; thin or missing screenshot coverage is reported as an advisory
+  on the plan review instead, where **Update plan** can ask for more. A
+  "recommended" screenshot label in a required-screenshot run is corrected
+  in place rather than sent back for a second pass, and the planner is told
+  to fit its captures inside the batch's screenshot maximum instead of
+  leaving the reviewer to trim. A batch now allows three screenshots per
+  page it may write (15 for a starter, 36 for a standard, 120 for a
+  comprehensive run, up to 300): the planner is asked for a capture of every
+  screen-changing step, so the old one-per-page cap left every real plan
+  over its limit at approval.
+- **The writer can validate its own work again, and finished runs are no
+  longer thrown away.** Inside the agent's sandbox, every Node process died
+  with "SecItemCopyMatching failed -67674" before printing anything whenever
+  the shell exported `NODE_USE_SYSTEM_CA=1` (it makes Node read the macOS
+  Keychain trust store at startup, which the sandbox denies), so `doxloop
+  test` never ran, the writer never saw its thin-page warnings, and it either
+  built substitute checks or left the warnings for the reviewer. Doxloop now
+  strips that variable from the agent's environment. A measured comprehensive
+  run (33 pages, 34 screenshots) took 35 minutes, one of them tool execution;
+  the rest is the model, at about 18 seconds per screenshot and 28 per page,
+  with six of ten output tokens hidden reasoning at **Effort: high**. Running
+  the same brief at medium was a tenth faster and noticeably shallower — a
+  fifth fewer words, two troubleshooting sections instead of ten, translation
+  keys quoted in place of displayed labels — so high stays the default; the
+  capture guide asks for one screenshot straight after the action that
+  produces a state, with accessibility snapshots only where the next click
+  needs a reference. Three Doxloop checks then refused that run's complete
+  output, each for a reason no reviewer would accept: an evidence map whose
+  page confidence said `contradicted` (a claim-level word; it now reads as
+  `needs-human`), 27 `api-endpoint-path-param` errors for gRPC-gateway paths
+  such as `/api/v1/{name=memos/*}` (the variable is `name`), and a "page
+  outside the approved batch" failure for the starter `index.mdx` the brief
+  itself requires the agent to replace. A guide that captured one more
+  distinct state than the plan approved is kept as extra evidence rather than
+  failing the run. **Continue the interrupted run** tells the agent to fix
+  the errors first and then the warnings on pages it wrote. And the file
+  contract now says outright which planned page replaces which generated
+  starter file and where it belongs — a plan that put the starter
+  quickstart's replacement at `getting-started/quickstart` used to leave the
+  writer keeping `quickstart.mdx` in place while every link pointed at the
+  planned path.
+- **The corrective planning pass rarely runs, and is cheap when it does.**
+  Three comprehensive runs in a row paid a second planning pass — six to
+  twenty minutes, twice ending in a failed plan — for slips no reviewer would
+  have sent back: a start path with a hash (`/setting#member`, how a
+  single-page application addresses a tab), a guide whose visual purpose was
+  written in the page's rationale, or a workflow left out while the same
+  steps were spelled out in the capture sequence. A hash is now a valid start
+  path, and the other slips are repaired in place and noted on the log. When
+  the pass does run, it is scoped to the named findings and told not to sign
+  in and explore the application again, which it used to do from scratch;
+  the first proposal travels as compact JSON. And a reviewer who chose **Use
+  recommended defaults** for planner questions gets those decisions in the
+  first pass — the planner is told to decide and record them — instead of a
+  third pass that re-sent the whole plan to apply its own recommendations.
+- **The setup wizard explains a rejected source folder.** Starting `doxloop ui`
+  inside the product checkout and adding that folder as a source used to fail
+  with no message, because the new workspace defaults to a folder inside the
+  source. The **Add source** dialog now shows the server's explanation with both
+  paths, the error clears as you type, and the **Location** field is offered on
+  a fresh start so the workspace can be moved beside the checkout. The
+  **Source added successfully** notice also dismisses itself after four seconds
+  and sits above the wizard footer, so it no longer covers **Continue** on a
+  short window.
+- **A Claude API failure mid-run no longer fails the run.** When Claude's API
+  request breaks off mid-response (a server error, an overload, a rate limit,
+  or a dropped connection), Claude exits and the run used to fail with the
+  unhelpful message `Claude stopped with result "success"`, discarding a
+  session that might already have written pages and captured dozens of
+  screenshots. Doxloop now recognizes the failure as transient, waits a
+  moment, and resumes the same Claude session in the same workspace, up to
+  twice per run, so the agent continues with its context and the pages and
+  screenshots it already produced. Only when every resume fails does the run
+  fail, and the message then names the API error, how many resumes were
+  tried, and that **Resume the run** continues from the preserved workspace.
+  Set `DOXLOOP_AGENT_API_RESUMES` to change the number of automatic resumes
+  (`0` disables them).
+- **Signed-in sessions no longer block plan approval.** The application
+  readiness check follows redirects within the configured application, so a
+  saved browser session that bounces a sign-up or landing route to the app
+  shell (for example `/signup` → `/dashboard`) counts as reachable and the
+  message names where the capture browser will land. Only a redirect to a
+  sign-in route, to another origin, or a redirect loop still blocks approval.
+- Nextra's and Markdoc's planning `navigationFiles` name files the scaffold
+  actually creates (`content/_meta.js` and `app/layout.jsx`; `navigation.json`
+  and `markdoc.config.mjs`). Sphinx starter pages carry the
+  `.. doxloop:starter-page` marker, which validation now recognises. The
+  Docusaurus and MkDocs adapters use the shared generator runtime instead of
+  private copies of its helpers. Hugo, Starlight, VitePress, Nextra, and
+  Jekyll no longer report a missing generator file when an adopted site uses
+  a theme or a differently named configuration file.
+
+- **Monitoring works on local folders.** A schedule no longer requires a Git
+  remote. A local Git checkout is checked in place by its HEAD commit and
+  working tree; a plain folder is compared against the file digests recorded
+  at the last sync, so it can still name the files that changed. Nothing is
+  fetched, pulled, or written in the source. **Check now** starts a visible job
+  and, when it finishes, a notice reports whether anything changed, how many
+  pages are stale, and which proposal was drafted.
+- **Gemini parity.** Unattended Gemini runs receive external sources through
+  `--include-directories`, read the capture browser from the workspace's
+  `.gemini/settings.json`, stream `stream-json` output into the same one-line
+  activity log Claude has, and are checked for sign-in from an API key, a
+  Vertex AI project, or the Google sign-in token file instead of "unknown".
+  Because Gemini cannot be denied writes to an extra directory, an unattended
+  run reads a throwaway copy of each local source. Codex runs stream
+  `exec --json` events into the same log. A capability matrix in the wizard's
+  **Tools** step and under **Settings → General** marks each row where an
+  assistant is **Limited**.
+
+### Changed
+
+- **Control center redesign.** The workspace gets one design system: Sora for
+  page titles and figures, Instrument Sans for the interface, JetBrains Mono
+  for paths, a single teal accent on a cool grey canvas, and consistent
+  buttons, badges, tables, and cards. The sidebar now draws the documentation
+  loop as a connected rail — Sources, Create/Update, Pages, Review, Deploy —
+  with each stage marked done, next, or waiting and a one-line status under
+  its name. The Overview leads with a status card (what is waiting on you and
+  the action to take), three tiles for coverage, pages, and the published
+  site, a validation-issues list when there are any, and an activity feed
+  whose **Stop** and **Log** controls no longer overlap. Sources shows
+  coverage as a white ring gauge instead of a dark gradient block and
+  freshness as a status row with per-source chips; planned screenshots list
+  their start route as a code chip with a count badge; the top bar shows the
+  project and screen as a breadcrumb plus a live "tasks running" chip.
+
+- **Review compares against what the agent started from.** A proposal now
+  diffs the agent's output against a snapshot of the project taken when the
+  run began, not against the live project at the end. A page you edit by hand
+  while the agent runs is no longer proposed as a revert, and a file that both
+  you and the agent changed is grouped under **Changed while the agent ran**,
+  shows the proposal against your edited version, and asks for confirmation
+  before **Accept all**, **Accept file**, or a hunk accept replaces your edit.
+  Raw browser captures under `.doxloop/capture-output` never appear as changes.
+- **Review opens on the documentation.** The changed-files list starts on the
+  first page instead of the evidence map, lists pages, navigation, and assets
+  first, and folds evidence, configuration, and skill files under **Supporting
+  files** until asked for. Accepting a change refreshes its hunk badges at
+  once, and **Review changes** in the ready dialog opens that proposal.
+- **URLs match the navigation.** The screens are now at `/update`, `/review`,
+  and `/deploy`; the previous addresses redirect. The selected proposal and
+  file, the Pages selection, and the Settings section live in the URL, so a
+  refresh or the back button returns to the same view. `doxloop ui --page`
+  accepts the new names and still understands the old ones.
+- **The workspace never renders blank.** A rendering error in one screen shows
+  what broke and offers a reload instead of a white page. A validation failure
+  is shown as "Validation unavailable" with the reason. Background polling
+  retries quietly three times before raising a banner.
+- **Forms keep up with the project.** Settings and Deploy forms reseed after a
+  save or a reload, keep unsaved edits when the project changed elsewhere and
+  say so, and the plan editor asks before a background refresh replaces edits
+  you have not saved. **Update history** names the pages each request changed.
+- **Hidden state is now shown.** Overview carries a validation summary with the
+  first issues and the sign-in state of the agent updates run with. Sources
+  shows documentation freshness: which pages fell behind which sources, and
+  how many paths changed per source.
+- **Setup wizard.** With screenshots on, step 3 requires a successful **Check
+  page** before Continue. Errors appear on the step they belong to, and the
+  sources table shows what was validated instead of a placeholder sync status.
+
+- **Stop really stops the run.** Stopping a run from the control center now
+  ends the coding agent and the capture browser it started within ten
+  seconds, and nothing writes into the run workspace afterwards. Unattended
+  agents run in their own process group; the CLI forwards a termination signal
+  to that group, escalates to a forced stop after a grace period, and exits
+  with the conventional signal status. Time budgets escalate the same way.
+- **Progress is real.** The stage list for a generation, revision, or page
+  edit now advances from what the agent actually does: a page write starts
+  **Authoring approved pages** and counts towards a "pages written N of M"
+  figure, a navigation write starts **Updating navigation and theme**, an
+  evidence-map write starts **Recording page evidence**, a capture starts
+  **Capturing application screenshots**, and validation starts when the agent
+  runs `doxloop test` or when the run hands over to Doxloop. Stages are
+  announced up front as pending, and a stage that saw no activity finishes as
+  "unchanged" instead of pretending the work happened. Codex and Gemini output
+  is now piped through Doxloop so it appears in the run log, and a workspace
+  watcher tracks their progress the same way.
+- **Planning has a time budget.** A planner that never returns now fails with
+  "Planning stopped after 20 minutes without a plan reply" instead of running
+  forever. The budget follows **Maximum agent minutes** when set, and the
+  `DOXLOOP_PLAN_TIMEOUT_MINUTES` environment variable overrides both.
+- Every job the control center starts has a labelled entry in **Recent
+  activity** with a log link and, while it runs, a **Stop** button: source
+  checks, sign-in, agent installs, screenshot captures, deployments, and
+  proposal revisions. The **Review** page shows a running revision or
+  resumption with its live log and a Stop button, and a failed one raises a
+  banner naming the reason. The deployment progress panel stays on screen
+  after a failure until it is dismissed, and the **Deploy** page explains that
+  sign-in finishes in the browser while the login job runs.
+
+### Added
+
+- **Portable static exports.** Doxbrix now builds page directories, reader CSS,
+  copied assets, client search data, sitemap and robots files, and page metadata
+  into `build/`, including a configurable base path for project sites.
+  `doxloop export --out <directory> [--zip]` provides the same self-hostable
+  output for every generator. Deployment dry runs leave their zip in
+  `.doxloop/exports` instead of discarding it.
+- **More deployment targets.** The Deploy page and `doxloop deploy --target`
+  now support GitHub Pages, Netlify, and Vercel alongside Doxbrix. The page has
+  per-target settings, local folder/zip export, protected provider credentials,
+  and a shared deployment history. GitHub Pages publishes to `gh-pages`;
+  Netlify uploads the static zip; Vercel uploads content-addressed files before
+  creating its production deployment.
+- **Project switcher and import.** The project name in the sidebar opens a
+  switcher that lists recently opened projects, opens any folder, imports an
+  existing documentation site, or starts the setup wizard for a new project,
+  all without restarting `doxloop ui`. Every opened project is remembered in
+  a user-level list. The setup wizard's first step now offers **Use existing
+  documentation folder**, which recognizes Doxbrix, Docusaurus, MkDocs,
+  Sphinx, Hugo, VitePress, Starlight, Nextra, Markdoc, and Jekyll sites from
+  their configuration files, shows the detected generator, content directory,
+  and pages for correction, and adopts the folder without modifying a page.
+  Existing pages start as unverified in the evidence map so the first update
+  attaches evidence. Switching is refused while a run is in progress and stops
+  a local preview. `doxloop init --existing [directory]` and
+  `doxloop ui --project <directory>` cover the same from a terminal.
+- **Maximum Claude spend (USD)** under **Monitoring → Advanced watch scope and
+  budgets** passes a spending cap to Claude Code for unattended runs and
+  planning. A run that ends on the cap says so in the log and the proposal
+  error. Codex and Gemini expose no equivalent flag, so the setting is ignored
+  for them; the field says so.
+
+- **Comprehensive is now the default documentation depth** in the setup wizard
+  and on the Create page, and the depth cards no longer show fixed page ranges
+  such as "8–15 pages". Depth chooses which product surface to cover; the page
+  count comes from the discovered evidence. The planner contract for the
+  Standard scope no longer targets a 15-page ceiling, the Standard estimate is
+  no longer clamped at 20 pages, and migrated version-1 plans no longer cap
+  their estimates at 15 or 30 pages.
+
+### Added
+
+- A new **Pages** view lists documentation by navigation section with search,
+  word counts, evidence state, update dates, current previews, and page
+  history. Select one or several pages, describe an edit in plain language,
+  watch the agent work in an isolated proposal, then compare rendered and
+  source versions before accepting, rejecting, refining, or undoing it.
+  Selected-page scope is enforced after every agent run; related navigation
+  and page-image changes require the explicit **Also allow related changes**
+  toggle.
+- **Failed runs continue where they stopped.** A generation run that fails
+  after the agent wrote pages — required screenshots missing for a guide, a
+  time budget reached, a validation error — keeps its workspace, and the plan
+  review now offers **Resume generation** and **Ignore problems & continue**.
+  Resuming restarts the agent in the same workspace with a brief of what is
+  already finished, so verified screenshots and completed pages are never
+  captured or written again; ignoring accepts the generated files for review
+  with every screenshot problem recorded as a text-only step and counted on the
+  proposal. The same actions appear on a failed proposal under **Review**, and
+  a plan whose planner missed a planning gate can be opened for review anyway.
+  Source changes made while a run sat failed no longer block continuing it:
+  the proposal records an advisory and refreshes its evidence snapshot instead.
+  Under the hood each run records the instructions it was started with in
+  `.doxloop/runs/<id>/authoring.json`, `doxloop proposal resume --id <run>` and
+  `doxloop proposal recover --id <run> --ignore-screenshot-problems` drive the
+  two paths, and `POST /api/plans/:id/continue` and
+  `POST /api/proposals/:id/resume` expose them to the control center.
+- Plans can carry a **minimum page count**. The Create and Update forms have a
+  "Minimum pages to write" field (and `POST /api/plans` accepts `targetPages`),
+  the planner must reach it with distinct evidence-backed pages or record a
+  scope exception, and the comprehensive scope no longer stops at thirty pages:
+  the estimate now scales with the discovered public surface, so a product with
+  many screens, commands, and configuration groups gets the forty or eighty
+  pages it needs instead of being compressed into overviews.
+- A **page depth gate**. `doxloop test` now reports `thin-page` for a page with
+  too little prose for its type and `thin-procedure` for a guide with fewer
+  than three real steps. Both are warnings, and the authoring contract, the
+  plan generation request, and the new authoring-skill reference
+  `references/page-depth.md` require the agent to resolve every one on a page
+  in scope before finishing. The reference defines what a complete landing
+  page, quickstart, guide, tutorial, concept, reference, and troubleshooting
+  page contains, so a run can no longer finish with a site of one-paragraph
+  pages that passes validation.
+- UI guides now plan and capture **one screenshot per screen-changing step**.
+  The planner is told to plan a capture for the entry screen, each dialog or
+  section a step opens, the filled form, and the result; a required-screenshot
+  plan whose procedural guide plans fewer than three captures is sent back for
+  revision unless its workflow says the guide is a single screen; and the
+  authoring prompt places an image inside every such step. The plan form also
+  defaults to screenshots when an application capture surface is configured.
+
+### Fixed
+
+- A plan whose generation failed can be approved again from the plan review.
+  **Approve & generate** returned "cannot be approved from status failed",
+  leaving **Retry stage** in the activity log as the only way forward. The
+  approval bar now reads **Retry generating …** for a failed plan and starts a
+  fresh run from the reviewed structure.
+- Documentation generation no longer stops at 60 agent turns. Unattended
+  Claude runs were launched with a fixed `--max-turns 60`, so a 44-page plan
+  with 85 planned screenshots ended while the agent was still exploring the
+  application and before it had written a page, reported only as "The
+  documentation agent exited with status 1." The cap now scales with the
+  approved plan (30 turns per page written plus 12 per planned screenshot,
+  never below 400; `DOXLOOP_AGENT_MAX_TURNS` overrides it), planning runs get
+  100 turns instead of 30, and when Claude does stop early the activity log and
+  the failure message name the reason, such as the turn limit or a reported
+  API error.
+- The control center no longer freezes after a long agent run. Every job kept
+  its complete output in memory — a single planning run left about 2 MB of
+  streamed JSON — and that whole job list was re-serialized for every
+  subscriber on every output chunk of the next run, written to `ui-jobs.json`
+  and returned by every state request. Buttons such as **Continue planning**
+  then sat on "Working…" with nothing happening. Jobs now keep a recent tail of
+  their log in memory (the full log stays on disk behind **Open full log**),
+  job-stream updates are coalesced, and a tab that cannot keep up no longer
+  has snapshots buffered on its behalf. A control-center request that gets no
+  answer for two minutes now reports that instead of waiting forever.
+- A code change no longer invalidates a documentation plan. Approving a plan
+  whose configured sources changed after it was proposed used to fail with
+  "Configured source evidence changed", mark the plan **stale**, and demand a
+  full agent revision, so any edit while a plan waited for review threw the
+  review away. Approval now proceeds with the structure as proposed, records
+  a note that the sources changed, and generation reads the current sources
+  when it writes each page. A change made between approval and generation is
+  logged instead of failing the run. Plans already marked stale by an earlier
+  version can be approved directly, or cleared with
+  `POST /api/plans/<plan-id>/resume`. Clicking **Use recommendation** on a
+  planner question now visibly confirms that the recommendation was applied.
+- A code change no longer blocks a generated proposal from being edited or
+  applied. Proposals now refresh their configured-source snapshot and show a
+  non-blocking review advisory; proposals marked stale by an earlier version
+  are restored to review automatically. Concurrent edits to the documentation
+  itself remain protected by the file-level conflict check.
+- A stale failed-plan screen no longer reports that a generated plan has no
+  failure to ignore. Recovery actions are idempotent once generation has
+  completed and return the generated plan so the browser refreshes to the
+  ready proposal.
+- Plan workflow manifests under `.doxloop/plans/` no longer leak into generated
+  documentation proposals. Existing proposals automatically drop those
+  internal changes and clear the resulting false conflict, while real
+  documentation-file concurrency checks remain enforced.
+- The local preview now renders `<Mermaid>` diagrams. It emitted the diagram
+  block but never loaded a renderer, so every lifecycle or architecture diagram
+  appeared as raw `flowchart LR …` text until the site was published.
+- Coverage no longer counts prose as product surface. Discovery ran its
+  authentication, authorization, and integration keyword scans over every text
+  file — changelogs, roadmaps, skill references, evaluation fixtures, tests —
+  and every matching line became its own "public signal", so a sixteen-page
+  site reported 23% security coverage with 186 items and a hundred-odd "gaps"
+  that were sentences from a roadmap. Keyword signals now come only from
+  product code, once per keyword family per file; fixture, test, example, and
+  documentation paths contribute file-level evidence only; and exports count
+  only from package entry points (`main`, `exports`, `bin`, `index`), not from
+  every internal module.
+
+- The live activity panel now has a Screenshots tab showing the images a run has
+  captured, refreshed while the run is still going. Captures that repeat an
+  earlier image are flagged, so a step saved under the name of a state the agent
+  never reached is visible before anything is applied.
+- A failed documentation run whose preserved workspace still validates can now
+  be recovered into review instead of requiring a full agent re-run. Retrying
+  generation for an approved plan recovers the newest matching failed proposal
+  automatically, and `doxloop proposal recover --id <run-id>` or
+  `POST /api/proposals/<run-id>/recover` recover one directly. Recovery refuses
+  archived runs, runs without a workspace, and runs whose configured source
+  evidence changed after the failure.
+
+### Fixed
+
+- A screenshot run can no longer quietly drop half its approved guides. The
+  agent built the capture manifest at the end, out of whatever it had captured,
+  so guides it decided to skip never appeared in the file at all — in one run it
+  covered four of eight guides, having decided the other four were "not a
+  distinct new screen" without ever navigating to them, and still reported
+  success. Doxloop now writes the manifest before the agent starts, with every
+  approved guide staged as `planned`, so capture is filling in a form rather
+  than inventing one. A guide left untouched is reported by name with the route
+  to open, instead of surfacing as a vague missing-manifest error, and the
+  authoring contract forbids judging a screen without opening it first.
+
+- Screenshot runs no longer fail over repeated images they were told to take.
+  Capture sequences were planned with steps that are not distinct states —
+  "scroll to the history area", "focus the request field", "inspect the coverage
+  panel" — and on a screen that already fits the viewport each produced a
+  byte-identical file, so a run that followed its approved plan exactly was
+  rejected for duplicates. The planner no longer proposes a capture for a step
+  that does not change the screen, the authoring guidance treats the approved
+  count as a target rather than a quota, and Doxloop keeps the first image of a
+  screen and records the repeats as text-only instead of failing. Repeats are
+  judged within a guide: two guides showing the same screen is ordinary
+  documentation and is now reported for review rather than counted as a defect.
+
+- Screenshot runs no longer throw away the screenshots they took. Doxloop asked
+  the agent to open each saved PNG and inspect it before marking the step
+  verified, which no agent CLI can do: a careful agent concluded it could not
+  verify anything, recorded every step as `text-only`, and a run whose captures
+  were all valid failed with "requires 1 verified capture, but produced 0".
+  Verification now happens before the shutter — confirm the state in a page
+  snapshot, then capture — and Doxloop checks the saved file itself, as it
+  already did. A capture left unrecorded is adopted into the step its filename
+  names, so a real screenshot is never lost to bookkeeping.
+
+- Screenshot planning no longer collapses a whole product to one capture. The
+  planner treated screens as URL routes, so in a single-page control center it
+  saw one route, recorded every other screen as "not visibly reachable", and
+  planned a single screenshot for an entire documentation set. It is now told to
+  reveal screens through read-only in-app navigation — tabs, steps, disclosure
+  controls — to change no data, and to record a state as unavailable only after
+  actually trying to reach it. Thin screenshot coverage is now reported on the
+  plan for review — naming the likely cause, an application left on its initial
+  or empty state — instead of silently shipping or blocking the run.
+- Planning no longer reads the wrong JSON object out of an agent transcript. It
+  previously took the first fenced block in the whole reply, which is usually a
+  quoted example from the skill references — an `.doxloop/project.json` or an
+  evidence map — rather than the plan. Doxloop now asks for the plan inside a
+  `<doxloop-plan>` block, ignores JSON it sent the agent itself, ignores objects
+  that are not plan-shaped, and takes the last real plan in the reply.
+- An unreadable plan reply is retried once with the defect quoted back, instead
+  of failing the whole planning run. A malformed plan now reports the actual
+  JSON defect and its position, and is never silently truncated into a plan that
+  has lost pages.
+
+- Plan approval no longer stalls behind an unexplained disabled button. The
+  application readiness check ran once when the plan opened and rendered nothing
+  when it failed, so a reviewer whose application started later saw a disabled
+  "Approve & generate" with no reason. The plan now always shows the readiness
+  state, offers "Check again", re-checks when the tab regains focus, and names
+  the one thing blocking approval.
+- The plan screen no longer stays on "Researching sources" after planning has
+  finished. A refresh of the persisted plan is now triggered whenever a plan job
+  stops running, instead of being suppressed by the guard that exists only to
+  prevent duplicate navigation.
+- Screenshot capture no longer fails silently on a missing folder. The capture
+  tool resolves its filename against the project root and does not create
+  directories, so a nested guide path whose folder did not exist failed with
+  `ENOENT` and wrote nothing — which is why runs reported screenshots that were
+  never taken. Doxloop now creates the guide asset directories for the approved
+  plan, per generator, before the capture browser starts, and the agent is told
+  that a failed call means no image exists.
+- Captured screenshots are no longer lost to page placement. Doxloop's own
+  guidance told agents to put each image "inside the same ordered-list item",
+  while the Doxbrix skill told them to write procedures with `<Steps>`/`<Step>`
+  and showed no example of an image inside a step — so agents captured every
+  planned state, embedded the first, and orphaned the rest, failing the run.
+  The step components now document the pattern, the placement rule covers them,
+  and Doxloop places any verified capture the agent left unembedded into the
+  step it belongs to before validation runs.
+- A repeated screenshot no longer throws away an otherwise good capture run. One
+  or two images reused for a state the agent could not reach are now reported on
+  the run for review — and flagged in the Screenshots tab — instead of failing
+  generation. A run where repeats outnumber distinct captures still fails, since
+  that means the capture pass did not really happen.
+- Screenshot validation now reports every problem in a run at once instead of
+  failing on the first one. A run whose manifest marked a dozen steps verified
+  while capturing two images used to surface as a single misplaced screenshot,
+  hiding the rest until the next retry. The agent is also told to mark a step
+  verified only after its image exists, has been opened, and is embedded.
+- Screenshots taken before a client-rendered application finished loading are
+  now rejected instead of published. Capturing straight after navigation returns
+  the splash or skeleton screen, which the old "at least four colours" emptiness
+  check accepted, so whole guides shipped as repeated pictures of a loading
+  page. A capture that is 98% or more a single colour is refused, and the agent
+  is told to confirm the expected content in a snapshot before capturing.
+- A screenshot embedded in a page written at a generator-native path — a Doxbrix
+  overview saved as `index.mdx` rather than the planned `overview` slug — no
+  longer fails validation as "not embedded in its matching guide". Only an image
+  that no page references at all is now treated as a defect.
+- Duplicate captures are reported together instead of one at a time, naming every
+  file in each identical group, and the agent is told to record states it cannot
+  reach as text-only rather than resaving the current screen under another name.
+- Screenshot manifest validation no longer fails a completed run when the agent
+  writes a terse step field such as `action: "Open /"`: approved
+  capture-sequence text now maps by capture ordinal (text-only steps no longer
+  shift the mapping), the minimum-specificity rule is stated in the agent
+  prompt and authoring skill, and the validation error now explains what a
+  specific value requires.
+
+- Post-Phase-4 hardening expands deterministic discovery across security,
+  errors, events, integrations, configuration, and framework routes; reports
+  unmeasurable coverage as Unknown; and revalidates semantic claims against
+  current source and OpenAPI facts.
+- Interrupted UI authoring jobs now recover as safe retry checkpoints. Reviewer
+  revisions, rejections, and inline edits build a bounded, redacted local
+  preference record used by later planning and generation.
+- The `doxloop quality` command now runs the configured isolated Node/Python and
+  OpenAPI example checks, axe and keyboard accessibility checks, light/dark
+  multi-viewport visual baselines, exact pixel tolerances, reviewed
+  suppressions, and quality ratcheting. Advanced policy remains in the shared
+  project configuration and CLI instead of crowding the main workflow. Public
+  coverage, quality, and evaluation payloads are schema validated before they
+  are stored or emitted.
+- Agent generation/update evaluations now complete the real UI plan, approval,
+  proposal, and acceptance workflow. Proposal review can prepare an isolated
+  Git branch and commit, then push it or open a pull request only on explicit
+  request, without switching or editing the current checkout.
+
+- Phase 4 release quality: `doxloop quality` now runs
+  one versioned contract across deterministic validation, generator strict
+  builds, cached external links, opt-in isolated Node examples, OpenAPI lint,
+  documentation lint, claim reverification, and optional rendered
+  accessibility and visual regression checks. Text/JSON output and CI exit
+  behavior share stable machine-readable codes.
+- `doxloop evaluate` scores generation and update quality, preservation, and
+  reviewer outcomes against an approved baseline. The agent/model matrix now
+  records model, duration, score, and release-blocking regressions across ten
+  realistic evaluation fixtures.
+- Optional evidence-derived reader verification metadata and Doxbrix badges
+  surface verified, inferred, contradicted, or needs-review states without
+  overstating source certainty. Versioned public contracts are shipped in
+  `contracts/`.
+
+- Stable workspace routes now match UI navigation and unsupported deep links
+  show an explicit not-found state.
+- `doxloop demo` (including `npx @doxbrix/doxloop demo`) builds a complete,
+  validated seven-page example in a temporary directory, demonstrates a
+  generated plan, evidence map, source baseline, and structured review, opens
+  the preview, and cleans up safely unless `--keep` is selected.
+- Connected source cards now use real connector checks and expose provider,
+  branch, subdirectory, revision, check time, OpenAPI metadata, and actionable
+  redacted failures. Monitoring is explicitly project-wide and exposes both
+  daily run and agent-minute budgets.
+
+- Versioned directory and OpenAPI source connectors now provide validated
+  JSON/YAML inspection, safe remote caching, structural API diffs, and targeted
+  drift.
+- Source ownership scopes, public-surface coverage in UI/CLI/JSON, evidence
+  precision diagnostics, and configurable maximum verification age make source
+  traceability visible and enforceable.
+
+- Proposal review is now evidence-aware. Every file has a compact rationale
+  drawer with source paths or API operations, revisions, affected interfaces,
+  reader claims, confidence, assumptions, validation, and plan/request origin.
+- Reviewers can ask the terminal agent to revise one hunk, one file, selected
+  files, or the whole proposal without changing the real documentation.
+  Revisions remain isolated and scope-checked, while the original proposal is
+  retained as superseded for audit.
+- Proposed pages can be edited directly in the review UI. Doxloop validates the
+  result, records human authorship, and either preserves the evidence
+  association or marks it for re-checking.
+- Applied proposals now support conflict-aware atomic undo from exact
+  pre-acceptance snapshots. Proposal lifecycle controls add regeneration,
+  stale-source protection, archive, 30-day retention, cleanup, and a focused
+  responsive rendered comparison without manual device or theme selectors.
+- Create and update now use a persisted, versioned documentation plan before
+  authoring. A deterministic, safely cached source inventory maps public
+  capabilities to an evidence-backed page tree; users can edit the brief and
+  page structure, answer one consolidated set of planner questions, compare
+  plan versions, inspect structured evidence, and approve the exact scope.
+- Scope presets show source-derived page estimates, and generator adapters
+  declare their native navigation boundaries while keeping the plan portable.
+- UI jobs expose structured planning and generation stages while retaining the
+  complete terminal log for diagnostics.
+
+- The workspace Update page shows an update history table: every request, its
+  result, the pages it changed, and how each page was reviewed. The Publish page
+  shows a publishing history table covering successful and failed deployments.
+- `doxloop history` shows what the project was asked to document and what
+  happened: the request text, its outcome, the pages it touched, and whether
+  each page was accepted or rejected in review. `--page` traces a single page,
+  `--deployments` lists publishing history. Pages edited outside Doxloop are
+  detected by content hash, so the record matches what is on disk.
+- Documentation history is stored in `.doxloop/doxloop.db` using the SQLite
+  built into the required Node.js 22.13-or-newer runtime. There is nothing extra
+  to install, the file is gitignored and owner-readable, and runtime readiness
+  is reported before authoring. `DOXLOOP_NO_HISTORY=1` explicitly turns
+  recording off. Agent transcripts are
+  never stored; they remain in `.doxloop/ui-job-logs/`.
+- `doxloop ui` opens a loopback-only project control center covering setup,
+  product evidence and GitHub connection tests, agent authoring, source
+  monitoring, proposal review, preview, publishing, and
+  complete project settings. Long-running work reports live output and can be
+  cancelled. `doxloop sync review --open` now deep-links to its Proposals page.
+- The unified proposal workspace compares rendered pages side by side or
+  stacked, folds unchanged content, exposes the source diff, and accepts one
+  hunk, one page, or a complete proposal. It uses a session cookie, validates
+  the Host and Origin headers, and never binds to a non-loopback interface.
+- `doxloop check` reports which documentation pages no longer match the
+  configured sources. It starts no agent and uses no model: the answer comes
+  from Git history, the recorded sync baseline, and the evidence map. It exits
+  `1` when pages are stale, so it can gate a pull request without credentials.
+- `.doxloop/evidence-map.json` records which configured source and which
+  source-relative paths produced each page. Authoring runs write it, and
+  `doxloop check` uses it to name the affected pages instead of reporting that
+  "a source changed".
+- A `sync` block in `.doxloop/project.json` configures automatic maintenance:
+  `mode`, the product `branch` to follow, the triggers to run `on`, `watch` and
+  `ignore` path patterns, and a run `budget`. Lock files and snapshots are
+  ignored by default; test files are not, because the authoring workflow treats
+  tests as evidence of supported behavior.
+- `doxloop sync <setup|status|now|review|history|off>` sets up automatic maintenance. `setup`
+  asks three questions and installs the triggers; `status` verifies the hook,
+  schedule, agent sign-in, evidence map, and current drift before anyone
+  depends on it; `now` generates one isolated proposal; `history` lists all
+  runs; `review --open` opens the review center; `off` removes triggers and
+  keeps the settings. The wizard prints the equivalent non-interactive command.
+- `doxloop sync review --open` opens the unified control center on its Proposals
+  page. Each page shows the current version beside the proposed version, both
+  rendered the way the published site renders them, with changed words
+  highlighted in place and untouched sections optionally folded away. View
+  controls switch between side by side and stacked or open the line-by-line
+  source diff with surrounding context and per-change Accept buttons. Acceptance
+  works at three levels: one change, one page, or the whole proposal, and
+  supporting files such as the evidence map are written automatically once every
+  page has been accepted.
+- Review-first synchronization works with ordinary local documentation folders
+  and does not require Git. Authoring happens in `.doxloop/runs/<id>/workspace`;
+  real files remain unchanged until acceptance. Accepted selections are checked
+  for intervening local edits, applied atomically, and validated. Partial
+  acceptance applies only selected line hunks, while the source baseline moves
+  forward only when the full proposal is accepted.
+- Git triggers are installed as marked blocks, so existing hooks are preserved,
+  a second documentation project can share the same file, and Doxloop never
+  blocks the Git operation. Pull and push triggers are mode-aware. `push`
+  installs a real `pre-push`
+  trigger; propose and auto hooks run a complete sync cycle while check hooks
+  remain credential-free. Authoring triggers generate a pending review without
+  editing or committing the actual documentation.
+- macOS schedules launch through the system shell so user-managed Node binaries
+  can run under launchd. Setup smoke-tests the job, and status reports scheduler
+  registration, running state, and the native last-exit result instead of
+  treating plist presence as proof of health.
+- Evidence-map validation warns when one source path is attached to more than
+  half the documentation pages, and authoring guidance requires an audit of
+  shared routers, entry points, and integration tests to reduce false-positive
+  stale-page reports.
+- A local scheduled run (`daily@HH:MM`) is registered with the platform's own
+  scheduler — launchd, a systemd timer, cron, or Task Scheduler — so unattended
+  runs use the agent CLI already signed in on that machine. Doxloop still never
+  accepts or stores a model API key.
+- Unattended authoring: `create` and `update` can run without a terminal, with
+  writes confined by the agent's own sandbox and a wall-clock budget. Validation
+  must still pass before the sync baseline advances, and automation never
+  deploys.
+- Validation warns when a page is missing from the evidence map, when the map
+  references a deleted page or an unconfigured source, and when a page is
+  recorded as needing human verification. These are warnings and appear only
+  once a project has an evidence map.
+
+### Fixed
+
+- Plan-first creation now becomes Update after its proposal is accepted. While
+  generated files are awaiting review, Authoring shows the proposal handoff
+  instead of reopening a second Create form, and planning buttons describe the
+  action they start rather than claiming a proposal already exists.
+
+### Changed
+
+- New native Doxbrix projects place `docs.json`, pages, and reader assets at the
+  documentation project root instead of creating an additional `docs/`
+  directory. Existing projects with `contentDir: "docs"` continue to work, and
+  external generators keep their generator-native content directories.
+
 ## 0.1.5 - 2026-07-26
 
 ### Changed