@doxbrix/doxloop 0.1.5 → 0.2.0

package/docs/project-format.md

@@ -3,14 +3,11 @@
 Doxloop stores project configuration under `.doxloop/`. Commit the configuration
 and synchronization state when a team should share the same authoring decisions.
 
-Create a new documentation project beside, never inside, the product source:
-
-```bash
-doxloop init
-```
-
-Run `doxloop settings` inside the documentation project to change shared
-configuration without editing JSON by hand.
+The setup wizard creates a new documentation project beside, never inside, the
+product source. Use **Settings** in the control center to change shared
+configuration without editing JSON by hand; this page documents the files
+themselves for review, version control, and advanced options that have no
+form field.
 
 ## `project.json`
 
@@ -18,11 +15,21 @@ configuration without editing JSON by hand.
 {
   "schemaVersion": 1,
   "title": "Example documentation",
-  "contentDir": "docs",
+  "contentDir": "",
   "generator": "doxbrix",
-  "sources": [{ "name": "product", "path": "../product" }],
+  "sources": [{
+    "name": "product",
+    "path": "../product",
+    "remote": {
+      "provider": "github",
+      "repository": "example/product",
+      "branch": "main",
+      "tokenEnv": "GITHUB_TOKEN"
+    }
+  }],
   "designReferences": [{ "url": "https://docs.example.com/" }],
   "deployment": {
+    "target": "doxbrix",
     "name": "Example documentation",
     "slug": "example-docs",
     "visibility": "private",
@@ -31,18 +38,21 @@ configuration without editing JSON by hand.
   "application": {
     "baseUrl": "http://localhost:3000/",
     "source": "product",
-    "startCommand": "npm run dev",
     "readyPath": "/health",
     "screenshots": {
       "policy": "requested",
       "viewport": { "width": 1440, "height": 900 },
-      "highlight": true
+      "highlight": true,
+      "startPath": "/settings/team",
+      "workflow": "Reuse the signed-in demo workspace and synthetic team members. Capture the invite form and successful invitation state."
     }
   },
   "documentation": {
     "primaryAudience": "Application developers",
     "experienceLevel": "intermediate",
     "priorityOutcomes": ["Install the SDK", "Send the first request"],
+    "preferredExamples": ["TypeScript", "curl"],
+    "designDirection": "Compact developer reference with task-led guides",
     "locale": "en-US",
     "tone": ["clear", "direct", "professional"],
     "standardsProfile": "doxloop-v1",
@@ -50,42 +60,316 @@ configuration without editing JSON by hand.
     "terminology": {},
     "exclusions": [],
     "accessibilityTarget": "WCAG 2.2 AA"
+  },
+  "sync": {
+    "mode": "check",
+    "branch": "main",
+    "on": ["every@15m"],
+    "watch": ["src/**", "openapi.yaml"],
+    "ignore": ["pnpm-lock.yaml"],
+    "budget": { "maxRunsPerDay": 8, "maxMinutes": 15, "maxUsd": 10 },
+    "maxVerificationAgeDays": 30,
+    "maxVerificationAgeSeverity": "warn"
   }
 }
 ```
 
-- `contentDir` must be a non-symlinked relative directory inside the project.
-- `sources` is the optional read-only evidence allowlist used by the authoring
-  workflow. It may be empty when no local product source is available. Configured
+- `title` and `defaultAgent` are edited under **Settings → General**.
+- `contentDir` is empty for new native Doxbrix projects, meaning reader content
+  lives at the project root. Existing projects may retain a non-symlinked
+  relative directory such as `docs`; external generators use their native
+  content directories.
+- `sources` is the read-only evidence allowlist managed on the **Sources**
+  page. It may be empty when no local product source is available. Configured
   source paths must be outside the documentation project; sibling product and
-  documentation directories are the recommended layout.
+  documentation directories are the recommended layout. Git repository sources
+  carry a `remote` object and are downloaded as read-only snapshots into a
+  `.doxloop-sources` directory beside the project. A source may declare
+  `scope.space`, `scope.routePrefix`, and `scope.navigationGroup`, edited
+  through **Documentation ownership** on the Sources page. Route prefixes
+  cannot overlap. Pages intentionally shared by several sources must be named
+  in `scope.sharedPages`.
 - `generatorPackage` is required for an external generator and must match the
   official package selected by `generator`.
 - `designReferences` accept absolute HTTP or HTTPS URLs without credentials.
-- `application` is optional and describes a safe local or test application
-  surface for guide screenshots. `source` names a configured source and is
-  required when `startCommand` is present. Screenshot policy is `requested`,
-  `auto`, or `off`; projects without this object keep the existing behavior.
-- `deployment` optionally saves the hosted project name, slug, visibility, and
-  Doxbrix destination used by `doxloop deploy`. Missing values are derived from
-  the project title and default to private.
-- `documentation` persists confirmed reader, scope, terminology, editorial, and
-  accessibility decisions.
+- `application` is edited under **Settings → Visual evidence** and describes a
+  safe local or test application surface for guide screenshots. `source` names
+  a configured source. A legacy `startCommand` is preserved when present but
+  is never executed by the capture workflow; the user owns application startup
+  and test data. Screenshot policy is `requested`, `auto`, or `off`; projects
+  without this object keep the existing behaviour. `screenshots.startPath`
+  records the default starting route, and `screenshots.workflow` records
+  authentication, safe fixture data, ordered actions, and expected outcomes
+  that constrain capture planning. `authentication.loginPath` names the
+  sign-in route the browser sign-in opens. Sign-in secrets are never stored
+  here: the recorded browser session and any test-account credentials live
+  under `~/.config/doxloop/capture-auth/<project key>/` (or
+  `$DOXLOOP_CONFIG_HOME`) with owner-only permissions, keyed by the project
+  root, and are managed under **Settings → Visual evidence → Application
+  sign-in**.
+- `deployment.target` is `doxbrix`, `github-pages`, `netlify`, or `vercel`.
+  Common fields save the project name and slug. Doxbrix also uses `visibility`
+  and `apiUrl`; GitHub Pages uses `branch` and optional `basePath`; Netlify uses
+  `siteId`; Vercel uses `projectId` and optional `teamId`. Provider tokens are
+  never stored here—they come from the OS credential store, protected user
+  configuration, or `DOXLOOP_NETLIFY_TOKEN` / `DOXLOOP_VERCEL_TOKEN`. Missing
+  names and slugs are derived from the project title.
+- `documentation` persists confirmed reader, scope, terminology, editorial,
+  and accessibility decisions, edited under **Settings → Audience and voice**
+  and in each plan's **Documentation brief**.
+- `sync` configures automatic maintenance and is managed by the
+  **Monitoring** dialog on the Sources page. `mode` is `check` (report only),
+  `propose` (generate an isolated review when run manually), or `auto`
+  (generate an isolated review from configured triggers). Authoring modes
+  never alter real documentation before approval and do not require
+  documentation Git. `branch` names the product branch documentation follows.
+  `on` selects one polling frequency: `every@Nm`, `every@Nh`, `daily@HH:MM`,
+  `weekdays@HH:MM`, `weekly@<day>@HH:MM`, or `monthly@<day>@HH:MM`. `watch`
+  and `ignore` are path patterns applied to changed source files; `ignore`
+  always wins. `budget` caps unattended runs: `maxRunsPerDay` limits scheduled
+  runs, `maxMinutes` stops an agent (and the planner) after that many minutes,
+  and `maxUsd` passes a spending cap to Claude Code, which is the only agent
+  with such a flag. Missing values use the defaults below. `maxVerificationAgeDays` warns or fails (according to
+  `maxVerificationAgeSeverity`) when evidence has not been reverified
+  recently, even when source revisions are unchanged.
+
+Default `ignore` patterns cover lock files and snapshots. Test files are
+deliberately not ignored, because the authoring workflow treats tests as
+evidence of supported behaviour, so a changed test can legitimately change
+documentation.
 
 Schema version 1 treats a missing legacy `generator` as `doxbrix` and supplies
 the default documentation brief when it is absent. Unsupported structures fail
 closed rather than being silently migrated.
 
+### Imported projects
+
+A folder that already holds a documentation site can be adopted from the
+control center (**Use existing documentation folder** in the setup wizard, or
+**Import existing documentation…** in the project switcher) or with
+`doxloop init --existing [directory]`. The generator is recognized from its
+configuration files: `docs.json` (Doxbrix), `docusaurus.config.*`,
+`mkdocs.yml`, `astro.config.*` mentioning Starlight, `<dir>/.vitepress/config.*`,
+`next.config.*` mentioning Nextra or `theme.config.*`, `markdoc.config.*`,
+`hugo.*` or a Hugo `config.toml`, `<dir>/conf.py` (Sphinx), and `_config.yml`
+(Jekyll). The content directory and title are read from the same files where
+they are declared, and both can be overridden.
+
+Import writes `project.json` with no sources and the default brief, an
+`evidence-map.json` in which every existing page has no sources and the
+confidence `needs-human` (so the first update run must attach evidence before
+drift detection trusts the page), the machine-local `.gitignore` entries
+listed above, and the agent skills. It then runs a read-only discovery pass.
+Pages, navigation, and generator configuration are never modified. A
+generator other than Doxbrix must have its Doxloop generator package
+resolvable from the folder; the control center offers to add it as a
+development dependency.
+
+## `projects.json` (user level)
+
+The control center keeps a list of the projects it has opened at
+`~/.doxloop/projects.json` (`DOXLOOP_HOME` overrides the directory). Each
+entry records the project path, title, generator, and when it was last opened,
+newest first, capped at twenty entries. The file is a convenience: a damaged
+one is ignored and rewritten on the next open, and a project whose
+`.doxloop/project.json` has disappeared is shown as missing until it is removed
+from the list.
+
+```json
+{
+  "schemaVersion": 1,
+  "projects": [
+    { "path": "/work/product-docs", "title": "Product documentation", "generator": "doxbrix", "lastOpenedAt": "2026-09-04T10:12:00.000Z" }
+  ]
+}
+```
+
+## `quality.json`
+
+`.doxloop/quality.json` is an optional version 1 contract for external-link
+policy and cache lifetime, opt-in executable examples, rendered routes and
+viewports, lint limits, and disabled-by-default reader verification metadata.
+See [release quality](./release-quality.md) for the complete schema and safety
+model. Quality reports, link caches, current screenshots, and evaluation
+results are derived artifacts; approved visual and evaluation baselines may be
+committed when a team wants CI regression protection.
+
+Proposal runs live under `.doxloop/runs/<id>/`: the isolated `workspace/`
+the agent wrote into, the reviewed `run.json`, `baseline.json`, which holds a
+content hash of every file as the workspace was created so review can tell
+what the agent changed from what changed in the project while it ran, and
+`authoring.json`, which records the instructions, agent, model, screenshot
+mode, and source summary the run was started with so a failed run can be
+resumed in place. UI recovery
+checkpoints and logs live in `.doxloop/ui-jobs.json` and
+`.doxloop/ui-job-logs/`. Learned local review guidance is stored in
+`.doxloop/review-preferences.json`, and prepared Git delivery metadata is stored
+in `.doxloop/deliveries/`. These machine-local artifacts are owner-readable,
+excluded from proposal snapshots, and added to `.gitignore`; they are not part
+of the portable project contract.
+
+## Documentation plans
+
+The control center creates `.doxloop/plans/<plan-id>/plan.json` before any
+create or update authoring begins. The current approved snapshot is copied to
+`.doxloop/documentation-plan.json` for the generation agent. Plan version 2 is
+generator-neutral and records:
+
+- the confirmed reader brief, scope, exclusions, terminology, locale,
+  accessibility target, and style guide;
+- deterministic discovery metadata and an evidence-backed capability map;
+- page actions, purposes, priorities, structured source evidence, and the
+  navigation outline;
+- open clarification questions and their confirmed answers;
+- the selected generator's content format, extensions, and native navigation
+  boundaries; and
+- the estimated page count, effort, execution settings, approval hash, and
+  resulting proposal ID.
+
+Every reviewable revision is archived in
+`.doxloop/plans/<plan-id>/versions/v<N>.json`. Version 1 plans are migrated on
+read without changing reader-facing documentation. Planning discovery is cached
+by safe source-content hash under `.doxloop/cache/discovery/`; cache files and
+plan run logs are operational state and should not be committed.
+
+A plan in `planning`, `revising`, or `needs-input` cannot authorize authoring.
+**Approve & generate** records an integrity hash, and generation refuses to
+proceed if either the approved plan or its configured source snapshot changed.
+Pages marked for a future backlog are omitted from the current proposed run.
+
+## Quality review reports
+
+Read-only agent reviews are stored as owner-readable JSON files under
+`.doxloop/reviews/`. A report records the selected agent, model and reasoning,
+the bounded score, hard-gate result, summary, and structured findings with page
+and evidence references. Raw agent transcripts are not copied into these
+reports. Reviews do not edit documentation, alter an approved plan, or create a
+proposal; deterministic validation remains a separate release signal.
+
+Request and deployment history uses `.doxloop/doxloop.db` and therefore requires
+the package runtime contract, Node.js 22.13 or newer. Set
+`DOXLOOP_NO_HISTORY=1` in the environment that starts the control center only
+as an explicit opt-out; the **Update history** and **Deployment history**
+panels surface that state.
+
 ## `sync-state.json`
 
-Each Git source records the commit, timestamp, and a fingerprint of tracked and
-untracked non-ignored, non-credential source content used by the last successful
-authoring run. The fingerprint prevents an unchanged dirty working tree from
-being reported again after its content is committed.
+Each source records the provider commit and timestamp used by the last accepted
+automatic proposal. Local manual workflows can also record a fingerprint of
+tracked and untracked non-ignored, non-credential source content used by the
+last successful authoring run. The fingerprint prevents an unchanged dirty
+working tree from being reported again after its content is committed.
+
+A local folder without Git history records the marker commit `local-content`
+together with the fingerprint and a `files` map of source-relative paths to
+content digests. A later check compares the folder against that map, so it
+can name the added, modified, and deleted files even though there is no
+commit range to diff. Credential files are never read or listed.
+
+Doxloop updates synchronization state only when a create or update proposal
+has been fully accepted, documentation validation passes, and the brief has a
+primary audience and priority outcomes. Automatic review runs keep their staged
+state separate and copy it into the real project only after every proposed
+change has been accepted.
+
+## `runs/`
+
+`.doxloop/runs/` is ignored runtime state for generated documentation reviews.
+Each run contains an isolated workspace, original copies of changed files, a
+`baseline.json` hash manifest of the project as the run started, and a
+`run.json` manifest with the trigger, validation result, exact line hunks, and
+acceptance decisions. A change whose file also moved in the project while the
+agent ran is marked `changedDuringRun`; the **Review** page groups those under
+**Changed while the agent ran** and asks before applying them. The **Review** page lists the manifests and renders them.
+The directory is not required to be committed and can be retained according to
+local review policy; **Clean up archived** on the Review page removes eligible
+workspaces.
+
+The current run manifest is schema version 2. Each file change records its
+reason, configured source paths or operations and revisions, affected public
+interfaces, reader-facing claims, file-relevant validation, confidence,
+assumptions, originating plan or request, and agent or human authorship. This
+is what the **Why this change** panel shows. Schema-version-1 manifests are
+migrated when read.
+
+**Ask agent to revise** seeds a new isolated workspace from the prior proposal
+and records the selected files or hunks and reviewer instruction. The old
+proposal is retained as superseded. **Edit page** changes remain inside the
+workspace, run validation, and record whether existing evidence still applies
+or needs review.
+
+Before the first accepted hunk, Doxloop snapshots the exact affected files and
+operational sync state. A completed application also snapshots the exact
+applied result. Undo compares the live files with that result and stops instead
+of overwriting a later edit; successful undo restores the pre-acceptance
+snapshot atomically. Proposals receive a 30-day retention date. Archived
+workspaces are removed only through explicit cleanup, while expired rejected,
+failed, superseded, and undone workspaces are eligible for cleanup.
+
+## `evidence-map.json`
+
+`.doxloop/evidence-map.json` records which configured source, and which
+source-relative paths or API operations, produced each page. Commit it: it is
+what lets Monitoring name the individual pages a later source change made
+stale, rather than reporting only that a source changed.
+
+```json
+{
+  "schemaVersion": 1,
+  "pages": {
+    "docs/guides/authentication.md": {
+      "sources": [{ "source": "product", "paths": ["src/auth.ts"] }],
+      "verifiedAt": { "product": "9f2c1ab..." },
+      "verifiedOn": { "product": "2026-08-26T10:00:00.000Z" },
+      "confidence": "verified",
+      "claims": ["Access tokens expire after 900 seconds"],
+      "claimVerification": {
+        "Access tokens expire after 900 seconds": "verified"
+      }
+    }
+  }
+}
+```
+
+Pages are keyed by project-relative path including the extension. A recorded
+directory matches everything below it. An entry without `paths` means the page
+depends on the whole source. `confidence` is `verified`, `inferred`, or
+`needs-human`; the last raises a validation warning so an unverified claim is
+visible rather than silently published.
+
+Authoring runs write this file. A malformed file fails closed: delete it and
+run an update from the **Update** page to rebuild it.
+
+`verifiedAt` records the source revision or content hash. `verifiedOn` records
+when the claims were actually checked and drives the maximum-age policy. Claim
+checks treat changed or expired evidence as `needs-human` rather than
+preserving an old verified state. `claimVerification` may record an exact claim
+as `verified`, `inferred`, `contradicted`, or `needs-human`; it must never
+claim more certainty than the configured source supports.
+
+The **Documentation coverage** section of the Sources page reports connector
+health, coverage by public surface and source scope, and evidence-precision
+suggestions. Coverage describes traceability to discovered evidence; it is not
+a correctness score.
+
+## `coverage-resolutions.json`
+
+`.doxloop/coverage-resolutions.json` records explicit decisions made from the
+coverage gap review on the Sources page. A resolution can link a reader journey
+to an existing page (**Link existing page**), exclude a discovered source item
+from the supported public surface (**Mark as internal**), drop a journey that
+is no longer a priority, or retain a needs-human decision (**Decide later**).
+Commit this file so exclusions and journey mappings remain stable for every
+contributor and CI run.
+
+Linking a product surface also writes its precise identifier to
+`.doxloop/evidence-map.json`. Removing a reader journey updates
+`documentation.priorityOutcomes` in `project.json`. Future documentation plans
+preserve those configured outcomes verbatim, even when the planning agent adds a
+more specific description, so wording changes do not reset journey coverage.
 
-Doxloop updates synchronization state only when create or update exits
-successfully, documentation validation passes, and create has saved a primary
-audience and priority outcomes.
+Coverage uses the newest approved, generating, or generated plan. Planning,
+cancelled, failed, and stale drafts do not replace the coverage baseline.
 
 ## `last-run.json`
 
@@ -102,8 +386,19 @@ be committed.
 
 Application guide screenshots are different: they are reader-facing assets,
 are placed in the selected generator's native asset directory, and should be
-committed with the guide. `doxloop create --screenshots` and
-`doxloop update --screenshots` require them explicitly; a request that clearly asks for
-screenshots also enables the authoring workflow. Contextual focus rings and
+committed with the guide. They are enabled per run by **Add product
+screenshots?** on the Create and Update pages, or by the screenshot policy
+under **Settings → Visual evidence**; a request that clearly asks for
+screenshots also enables the capture workflow. Contextual focus rings and
 numbered markers are baked into the image so they render consistently across
-generators.
+generators. Plans record whether screenshots are automatic, required, or
+disabled and identify the specific UI guides, application-relative start path,
+ordered safe workflow, and an explicit capture sequence from entry through
+verification before approval. The sequence contains one meaningful visible
+state per planned image; UI-heavy tutorials and how-to guides therefore plan
+several captures instead of defaulting to one final-state screenshot. Approval
+requires a reachable configured application and complete capture details for
+every visual guide. During generation the agent writes
+`.doxloop/screenshot-manifest.json`; Doxloop verifies the planned page, purpose,
+expected state, PNG dimensions, uniqueness, embedding, and completed privacy and
+legibility checks before it creates a review proposal.

package/docs/release-quality.md

@@ -0,0 +1,158 @@
+# Release quality and evaluations
+
+Doxloop applies quality gates at every step of the loop in the control center:
+
+- **Planning** cannot be approved while clarification questions are open, and
+  generation refuses to start if the approved plan or its source snapshot
+  changed.
+- **Proposals** run page validation before they appear on the **Review** page.
+  The **Why this change** panel shows each file's error and warning counts,
+  supporting evidence, reader-facing claims, and assumptions to verify.
+  Direct page edits are validated before they are saved.
+- **Publish** validates the documentation again and builds the site before
+  anything is uploaded.
+  Validation errors stop a deployment; warnings are reported.
+
+The versioned release-quality contract described below extends those checks
+with external links, OpenAPI linting, documentation lint, claim
+reverification, and opt-in executable, accessibility, and visual checks. It is
+the release-grade definition of "ready", stores its complete JSON report below
+`.doxloop/quality-reports/`, and is designed for the headless checks described
+in [automation and CI](./ci-and-automation.md). A failing gate exits with
+status 1; warnings exit 0 unless the contract is run with warnings treated as
+errors.
+
+## Shared quality configuration
+
+Optional settings live in `.doxloop/quality.json`:
+
+```json
+{
+  "schemaVersion": 1,
+  "links": {
+    "mode": "online",
+    "allowHosts": ["developer.example.com"],
+    "ignore": ["https://status.example.com/"],
+    "timeoutMs": 8000,
+    "retries": 2,
+    "cacheHours": 24
+  },
+  "examples": { "enabled": true },
+  "rendered": {
+    "enabled": true,
+    "routes": ["/", "/quickstart"],
+    "themes": ["light", "dark"],
+    "maximumDiffRatio": 0.001,
+    "viewports": [
+      { "name": "desktop", "width": 1440, "height": 900 },
+      { "name": "mobile", "width": 390, "height": 844 }
+    ]
+  },
+  "lint": {
+    "maximumTitleLength": 72,
+    "maximumNavigationLabelLength": 42
+  },
+  "suppressions": [{
+    "code": "quality.claim.needs-human",
+    "file": "reference/legacy.md",
+    "reason": "Owner-approved migration exception",
+    "expires": "2026-09-30"
+  }],
+  "ratchet": {
+    "enabled": true,
+    "baselineFile": ".doxloop/quality-baseline.json"
+  },
+  "readerVerification": { "enabled": false }
+}
+```
+
+External checks cache successful and broken responses, so an offline run can
+use only that cache. Authentication responses and temporary network/server
+failures are warnings, not broken-link failures. Private destinations and
+credential-bearing URLs are blocked.
+
+Suppressions require a reason, can be limited to one file, and can expire. They
+remain in the report as `skipped`; they are not silently removed. Ratcheting
+matches the exact issue code, file, and message so an approved legacy issue does
+not permit a different regression with the same broad code. The current
+reviewed findings can be approved as the baseline from the headless quality
+check. Advanced policy stays in this shared configuration so the control
+center remains a simple status, fix, and recheck flow.
+
+## Executable examples
+
+Example execution is opt-in through `.doxloop/examples.json`:
+
+```json
+{
+  "schemaVersion": 1,
+  "examples": [{
+    "id": "parse-config",
+    "runtime": "node",
+    "file": "examples/parse-config.mjs",
+    "workingDirectory": ".",
+    "fixtures": ["examples/config.json"],
+    "network": "denied",
+    "expected": { "exitCode": 0, "stdoutIncludes": "valid" }
+  }]
+}
+```
+
+Node examples run from a temporary workspace with a minimal environment,
+explicit filesystem permissions, no network permission, a timeout, and no
+shell. Python examples use `runtime: "python"` and require a locally installed,
+digest-pinned Docker image configured with `DOXLOOP_PYTHON_SANDBOX_IMAGE`
+(for example, `python@sha256:<the approved image digest>`). Doxloop never
+executes Python examples directly on the host. Without the configured image,
+the check is skipped and cannot earn executed-example credit. Containers use
+no network, a read-only filesystem and fixture mount, an unprivileged user,
+no Linux capabilities, and CPU, memory, PID and time limits. The image is
+never pulled automatically. A missing image or unavailable daemon fails the
+execution check; it does not fall back to host Python. Apparent credentials are rejected. Use `runtime:
+"shell-source-verified"` or `runtime: "source-verified"` when a command cannot
+be executed with a portable network/filesystem sandbox; the report keeps that
+distinction instead of overstating verification.
+
+Use `runtime: "openapi-request"` for `.http` request examples. The first
+`METHOD /path` line and an optional `# expect-status: 202` directive are checked
+against the currently connected OpenAPI contract without contacting an API.
+
+## Rendered accessibility and visual checks
+
+Rendered checks use a managed browser only when enabled. Representative pages
+are checked at configured widths for landmarks, accessible names, images,
+heading order, and horizontal overflow. The report always retains a manual
+WCAG review requirement for keyboard order, focus, contrast, zoom, reflow, and
+assistive-technology output.
+
+Current screenshots are stored in `.doxloop/quality-artifacts/`. Approved
+baselines are separate by generator, theme, route, and viewport under
+`.doxloop/visual-baselines/`, and are updated from the headless quality check
+after an intentional design change has been reviewed.
+
+## Documentation lint and safe fixes
+
+Linting reports terminology drift, substantial duplicate prose, common
+spelling errors, difficult sentences, title length, and navigation-label
+length. Safe fixes only perform deterministic formatting changes: inferred code
+fence languages, unambiguous heading-rank repair, normalized local-link syntax,
+trailing whitespace, and final newlines. They never rewrite factual prose.
+
+## Claim states and reader metadata
+
+Evidence-map claims resolve to `verified`, `inferred`, `contradicted`, or
+`needs-human`. Changed evidence never remains verified automatically. When
+`readerVerification.enabled` is true, Doxloop writes
+`.doxloop/verification-metadata.json` and supplies the matching locale,
+verification date, source revision, confidence, and state to native Doxbrix
+preview and deployment output. The feature is disabled by default.
+
+## Evaluations
+
+Doxloop maintainers score generation, update, and review quality across agents
+and models with fixture projects. Those evaluations drive the same plan-first
+control-center workflow as a user, need a locally signed-in agent, and are
+documented for contributors in [releasing](./releasing.md). Machine-readable
+v1 schemas and the append-only issue-code policy are published in
+`contracts/`. Codes can be baselined, suppressed, or ratcheted; presentation
+text is not an API.

package/docs/releasing.md

@@ -58,3 +58,75 @@ peer range is updated when necessary, and they are built and published after
 the root package. Unchanged generators keep their existing versions and are
 skipped. A dry run lists the exact package set without changing versions or
 publishing.
+
+## Evaluations
+
+Model-backed evaluations are maintainer tooling, not part of the reader
+workflow. Keep the deterministic typecheck, tests, skill validation, build, and
+package checks on every pull request, and run evaluations from a scheduled or
+manually approved job on a developer machine or self-hosted worker where a
+coding agent is signed in.
+
+```bash
+doxloop evaluate --mode generation --max-pages 12
+doxloop evaluate --mode update --before ../docs-before \
+  --expected-change guides/billing.md --approve-baseline
+pnpm eval:agents -- --agent codex --case cli
+pnpm eval:agents -- --agent codex --model codex=<model> --case localized-update
+pnpm eval:agents -- --mode generation --agent codex --case rest-api
+pnpm eval:agents -- --mode update --agent codex --case localized-update
+```
+
+Review evaluations run the agent read-only. A review case must exit
+successfully, identify the required behaviour signals, cite enough configured
+source evidence, prioritize findings, report a score out of 100, and leave the
+fixture project byte-for-byte unchanged.
+
+Generation and update evaluations instead exercise the same plan-first
+control-center contract as a user: wait for the proposed plan, approve it,
+generate into an isolated proposal, accept that proposal, and score the
+resulting documentation. They mutate only the temporary fixture copy.
+
+Workspace evaluations score factual grounding, unsupported claims, coverage,
+information architecture, executable examples, evidence precision, page
+economy, update locality and preservation, accessibility, and reviewer
+outcomes. Reports compare with `.doxloop/evaluation-baseline.json` and can
+block on a configured regression threshold. The agent matrix runs identical
+fixtures across agents and models, records duration and scores, and compares
+with the reviewed `evals/baseline.json`. Output is written below the
+Git-ignored `evals/results/` directory. Use `--approve-baseline` only after
+reviewing a deliberate improvement or model change.
+
+### Product hardening acceptance checks
+
+Run `DOXLOOP_E2E_REAL=1 pnpm exec playwright test` after building. CI runs this
+suite against the actual local UI server and a deterministic fake agent. The
+Pages test verifies proposed changes stay isolated, accepts an edit, compares
+exact file contents after undo, and exercises direct draft preview/save/undo.
+
+Run `node scripts/ci-existing-sites.mjs` for two existing-site fixtures in
+`evals/native-sites`. The script installs the real Docusaurus and MkDocs
+runtimes, builds before import, imports without changing pages/configuration,
+creates a fake-agent update, accepts it, builds the result, undoes it, and
+builds again. It asserts custom slugs, non-root base paths, file-style URLs,
+asset contents and exact restored prose. CI runs this separately from unit
+tests and uploads `evals/results/existing-sites.json`.
+
+Real-agent evaluation remains opt-in, outside `pnpm test` and ordinary CI:
+
+```sh
+pnpm run build
+node scripts/run-authoring-evals.mjs --agent codex --model codex=gpt-5.5 --case cli --mode review
+node scripts/run-authoring-evals.mjs --agent claude --case cli --mode generation
+node scripts/run-authoring-evals.mjs --agent codex --model codex=gpt-5.5 --case localized-update --mode update
+```
+
+Choose a model supported by the installed agent CLI and your account. Results
+record the CLI version, model selection, fixture digest, elapsed time, exit
+status, matched evidence and quality measurements. Review scoring uses the
+final response rather than the agent's echoed prompt or tool transcript.
+Generation/update runs preserve generated workspaces and raw quality/evaluation
+reports under the ignored results folder. Tooling failures remain failed runs;
+they do not earn content-quality credit. No new baseline is approved unless
+`--approve-baseline` is explicitly supplied. Review scores measure detection of
+known fixture defects; they are not proof of production documentation quality.