@doxbrix/doxloop 0.1.4 → 0.2.0

package/dist/workspace-tools.d.ts

@@ -0,0 +1,54 @@
+export interface PageComment {
+    id: string;
+    path: string;
+    text: string;
+    createdAt: string;
+    proposalId?: string;
+    changeId?: string;
+    hunkId?: string;
+    resolvedAt?: string;
+}
+export declare function pageComments(root: string): Promise<PageComment[]>;
+export declare function savePageComment(root: string, input: {
+    path: string;
+    text: string;
+    proposalId?: string;
+    changeId?: string;
+    hunkId?: string;
+    resolveId?: string;
+}): Promise<PageComment[]>;
+export declare function searchPageText(root: string, query: string): Promise<{
+    path: string;
+    title: string;
+    line: number;
+    section: string;
+    excerpt: string;
+    route: string;
+}[]>;
+export declare function auditDocumentation(root: string): Promise<{
+    generator: import("./types.js").GeneratorName;
+    contentDir: string;
+    pages: import("./pages.js").PageSummary[];
+    unmapped: string[];
+    unverified: string[];
+    drift: import("./types.js").DriftResult;
+    configuration: {
+        file: string;
+        text: string;
+    }[];
+    message: string;
+}>;
+export declare function backfillEvidence(root: string): Promise<import("./direct-edit.js").DirectEditResult>;
+export declare function readerVerification(root: string, enabled?: boolean): Promise<import("./direct-edit.js").DirectEditResult | {
+    enabled: boolean;
+}>;
+export declare function authoringEstimate(root: string, pages: number, agent?: string, model?: string): Promise<{
+    message: string;
+    cost: string;
+    range?: {
+        minimumMinutes: number;
+        maximumMinutes: number;
+    };
+    samples: number;
+}>;
+//# sourceMappingURL=workspace-tools.d.ts.map

package/dist/workspace-tools.js

@@ -0,0 +1,123 @@
+import { randomUUID } from 'node:crypto';
+import { readFile, writeFile, mkdir, rename } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import { applyDirectEdit, safePath } from './direct-edit.js';
+import { computeDrift } from './drift.js';
+import { readEvidenceMap, EVIDENCE_MAP_FILE } from './evidence.js';
+import { DoxloopError } from './errors.js';
+import { listRequests } from './history.js';
+import { listPages, resolveEditScope } from './pages.js';
+import { loadPages, loadProject } from './project.js';
+import { withProjectLock } from './project-lock.js';
+import { readSyncRun } from './sync-runs.js';
+import { loadQualityConfig, QUALITY_CONFIG_FILE } from './quality-config.js';
+import { reverifyClaims, VERIFICATION_METADATA_FILE } from './quality-claims.js';
+const COMMENTS = '.doxloop/comments.json';
+export async function pageComments(root) {
+    try {
+        return JSON.parse(await readFile(await safePath(root, COMMENTS), 'utf8'));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+}
+export async function savePageComment(root, input) {
+    return withProjectLock(root, 'write', async () => {
+        const comments = await pageComments(root);
+        if (input.resolveId) {
+            const item = comments.find((comment) => comment.id === input.resolveId);
+            if (!item)
+                throw new DoxloopError('Comment was not found.');
+            item.resolvedAt = new Date().toISOString();
+        }
+        else {
+            if (!input.text.trim() || input.text.length > 8000)
+                throw new DoxloopError('Write a comment of 1–8000 characters.');
+            if (input.proposalId) {
+                const run = await readSyncRun(root, input.proposalId);
+                const change = run.changes.find((item) => item.id === input.changeId && item.path === input.path);
+                if (!change || (input.hunkId && !change.hunks.some((hunk) => hunk.id === input.hunkId)))
+                    throw new DoxloopError('Select a valid proposal file or hunk.');
+            }
+            else
+                await resolveEditScope(root, await loadProject(root), [input.path], false);
+            comments.push({ id: randomUUID(), path: input.path, text: input.text.trim(), createdAt: new Date().toISOString(), ...(input.proposalId ? { proposalId: input.proposalId, changeId: input.changeId } : {}), ...(input.hunkId ? { hunkId: input.hunkId } : {}) });
+        }
+        const target = await safePath(root, COMMENTS);
+        await mkdir(join(root, '.doxloop'), { recursive: true });
+        const temporary = `${target}.${randomUUID()}.tmp`;
+        await writeFile(temporary, JSON.stringify(comments, null, 2) + '\n', { mode: 0o600 });
+        await rename(temporary, target);
+        return comments;
+    });
+}
+export async function searchPageText(root, query) {
+    if (!query.trim())
+        return [];
+    const term = query.trim().toLocaleLowerCase().slice(0, 300);
+    const project = await loadProject(root);
+    const pages = await listPages(root);
+    const results = [];
+    for (const page of pages) {
+        const lines = (await readFile(await safePath(root, page.path), 'utf8')).split('\n');
+        let section = page.title;
+        for (let index = 0; index < lines.length; index++) {
+            const line = lines[index];
+            const heading = /^#{1,6}\s+(.+)|<h[1-6][^>]*>(.*?)<\/h[1-6]>/i.exec(line);
+            if (heading)
+                section = (heading[1] ?? heading[2]).replace(/<[^>]+>/g, '');
+            if (line.toLocaleLowerCase().includes(term))
+                results.push({ path: page.path, title: page.title, line: index + 1, section, excerpt: line.trim().slice(0, 240), route: page.route });
+            if (results.length >= 200)
+                return results;
+        }
+    }
+    return results;
+}
+export async function auditDocumentation(root) {
+    const project = await loadProject(root);
+    const [pages, evidence, drift] = await Promise.all([listPages(root), readEvidenceMap(root), computeDrift(root, project)]);
+    const nativeFiles = project.generator === 'docusaurus' ? ['versions.json', 'docusaurus.config.js', 'docusaurus.config.ts'] : project.generator === 'mkdocs' ? ['mkdocs.yml', 'mkdocs.yaml'] : [];
+    const configuration = [];
+    for (const file of nativeFiles) {
+        try {
+            configuration.push({ file, text: (await readFile(await safePath(root, file), 'utf8')).slice(0, 10000) });
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+    }
+    return { generator: project.generator, contentDir: project.contentDir, pages, unmapped: pages.filter((page) => !evidence?.pages[page.path]).map((page) => page.path), unverified: pages.filter((page) => page.evidence !== 'verified').map((page) => page.path), drift, configuration, message: 'Read-only audit. No pages, source baselines, or verification claims were changed. Backfill adds missing pages as unverified; it does not infer source associations.' };
+}
+export async function backfillEvidence(root) {
+    return withProjectLock(root, 'write', async () => {
+        const map = await readEvidenceMap(root) ?? { schemaVersion: 1, pages: {} };
+        const files = await loadPages(root, await loadProject(root));
+        for (const file of files) {
+            const path = relative(root, file).replace(/\\/g, '/');
+            map.pages[path] ??= { sources: [], confidence: 'needs-human' };
+        }
+        return applyDirectEdit(root, { kind: 'metadata', requestText: 'Backfilled unverified evidence entries without rewriting documentation', files: [EVIDENCE_MAP_FILE], apply: async () => { await writeFile(await safePath(root, EVIDENCE_MAP_FILE), JSON.stringify(map, null, 2) + '\n'); } });
+    });
+}
+export async function readerVerification(root, enabled) {
+    const config = await loadQualityConfig(root);
+    if (enabled === undefined)
+        return { enabled: config.readerVerification?.enabled ?? false };
+    return applyDirectEdit(root, { kind: 'metadata', requestText: `${enabled ? 'Enabled' : 'Disabled'} reader verification labels`, files: [QUALITY_CONFIG_FILE, VERIFICATION_METADATA_FILE], apply: async () => {
+            const current = await loadQualityConfig(root);
+            current.readerVerification = { ...current.readerVerification, enabled };
+            await writeFile(await safePath(root, QUALITY_CONFIG_FILE), JSON.stringify(current, null, 2) + '\n');
+            await reverifyClaims(root, await loadProject(root), true);
+        } });
+}
+export async function authoringEstimate(root, pages, agent, model) {
+    const samples = (await listRequests(root, 200)).filter((run) => run.status === 'completed' && ['create', 'update'].includes(run.kind) && run.durationMs && run.pagesChanged > 0 && (!agent || run.agent === agent) && (!model || run.model === model));
+    const rates = samples.map((run) => run.durationMs / run.pagesChanged / 60000).sort((a, b) => a - b);
+    const range = rates.length >= 3 ? { minimumMinutes: Math.ceil(rates[Math.floor((rates.length - 1) * .2)] * pages), maximumMinutes: Math.ceil(rates[Math.ceil((rates.length - 1) * .8)] * pages) } : undefined;
+    return { samples: rates.length, ...(range ? { range } : {}), message: range ? 'Observed 20th–80th percentile duration per changed page, scaled to this batch. Screenshots and source complexity can increase time.' : 'At least three comparable completed runs are needed for an observed time range. Your time limit is a cap, not an estimate.', cost: 'Billing is controlled by your agent provider. Doxloop has no reliable usage-price data for this run.' };
+}
+//# sourceMappingURL=workspace-tools.js.map

package/docs/agent-compatibility.md

@@ -1,41 +1,63 @@
 # Agent compatibility
 
-Doxloop supports Codex, Claude Code, and Gemini CLI. It discovers executables on
-`PATH` or accepts an explicit `--agent`.
+Doxloop works with Codex, Claude Code, and Gemini CLI. It discovers the
+executables installed on the machine and lists all three wherever you choose a
+coding assistant: the **Tools** step of the setup wizard, the **Planning
+agent** field on the Create and Update pages, and **Default documentation
+agent** under **Settings → General**.
+
+Selecting an assistant that is not installed offers to install its official
+npm package globally. Doxloop verifies that the new executable is available and
+then continues. The agent uses its own existing sign-in; Doxloop never accepts
+or stores a model API key.
 
 ## Invocation modes
 
 | Workflow | Codex | Claude Code | Gemini CLI |
 | --- | --- | --- | --- |
-| Create/update | Interactive prompt | Interactive prompt | Interactive `-i` prompt |
-| Review | Read-only ephemeral execution | Print with plan permissions | Plan approval mode |
-| External IDE | `--print` prepared prompt | `--print` prepared prompt | `--print` prepared prompt |
-
-Review is deliberately non-interactive so it can remain read-only. Create may
-pause once for consolidated reader or scope decisions.
-
-Doxloop forwards `--model` using each CLI's native model option. The
-`--reasoning` option is Codex-only and accepts `minimal`, `low`, `medium`,
-`high`, or `xhigh`.
+| Planning | Read-only research run | Read-only research run | Read-only research run |
+| Generation and revision | Unattended run in an isolated proposal workspace | Unattended run in an isolated proposal workspace | Unattended run in an isolated proposal workspace |
+| Guide screenshots | Run-scoped Playwright browser passed on the command line | Run-scoped Playwright browser passed on the command line | Run-scoped Playwright browser merged into the workspace's `.gemini/settings.json` and trusted for the run |
+| External sources | Read through a sandbox that denies writes | Read through a sandbox that denies writes | **Limited.** Gemini cannot be denied writes to an extra directory, so an unattended run reads a throwaway copy of each local folder (beside the remote snapshots under `.doxloop-sources`) and never sees the real checkout |
+| Spending cap | Not available | `--max-budget-usd` from **Maximum Claude spend** | Not available |
+| Live activity log | Formatted from `codex exec --json` | Formatted from the stream-json output | Formatted from `--output-format stream-json` |
+| Stage progress | From tool calls and file writes | From tool calls and file writes | From tool calls and file writes |
+| Sign-in check | `codex login status` | `claude auth status` | **Limited.** Checks for an API key or Vertex AI project in the environment, or the Google sign-in token file; nothing is read beyond presence |
+| Validation during a run | Commands allowed by the sandbox | Commands allowed by the sandbox | **Limited.** Only the `doxloop` CLI is pre-approved; other commands need a confirmation an unattended run cannot give |
+
+The same matrix is shown in the setup wizard's **Tools** step and under
+**Settings → General**, with **Limited** marking each row where an assistant
+is not at parity.
+
+Planning may pause for consolidated reader or scope decisions; these appear
+under **Needs your decision** on the plan, and the **Planner questions**
+setting controls whether the planner asks in review, uses recommendations, or
+always waits for answers.
+
+The **Model** field forwards the chosen model using each assistant's native
+model option. Reasoning effort is available for Codex and Claude Code; the
+picker limits the choices to the values the selected model supports.
 
 ## Project skills
 
-Initialization installs the shared authoring skill and selected format skill
-under `.agents/skills` for Codex and Gemini and `.claude/skills` for Claude
-Code. Use:
-
-```bash
-doxloop agent status
-doxloop agent update
-```
-
-`review` does not install or replace skills because that would mutate the
-project. Run `doxloop agent setup` before review if skills were removed.
+Creating a workspace installs the shared authoring skill and the selected
+generator's format skill under `.agents/skills` for Codex and Gemini and
+`.claude/skills` for Claude Code. Every planning and generation run checks
+those skills against the packaged version and refreshes them when the package
+was upgraded. A skill with local edits is not overwritten silently: the run
+stops with a message naming the changed directory. Delete or restore that
+directory and start the run again.
 
 ## Compatibility policy
 
-Agent CLIs evolve independently. Release checks validate argument construction,
-and optional real-agent evaluations exercise installed CLIs. A release should
-record the tested CLI versions in its release notes. When an invocation fails,
-run the agent directly to confirm its installed version and then use
-`doxloop create --print` as a version-independent fallback.
+Agent CLIs evolve independently. Release checks validate argument
+construction, and optional real-agent evaluations exercise installed
+assistants. A release should record the tested versions in its release notes.
+When a run fails as soon as the assistant starts, open **Open full log** in
+**Live activity** to see the assistant's own output, then confirm the
+installed version by running the assistant directly.
+
+For automated tests only, `DOXLOOP_AGENT_EXECUTABLE_CODEX`,
+`DOXLOOP_AGENT_EXECUTABLE_CLAUDE`, and `DOXLOOP_AGENT_EXECUTABLE_GEMINI` can
+point Doxloop at a fake executable instead of searching `PATH`. Production
+workflows should rely on the installed assistant executable.

package/docs/ci-and-automation.md

@@ -1,66 +1,105 @@
-# CI and automation
-
-Deterministic validation is suitable for pull requests. Agent authoring is
-optional because it may require credentials, model access, and interactive
-decisions.
-
-## Validate in CI
-
-```bash
-pnpm install --frozen-lockfile
-doxloop test
-```
-
-`doxloop test` exits with status 1 when validation errors remain. Warnings are
-reported but do not change the exit status.
-
-Use structured output when another tool consumes the result:
-
-```bash
-doxloop test --format json > doxloop-validation.json
-doxloop status --format json
-```
-
-Run the selected generator's strict build after Doxloop validation. Obtain the
-command and output directory with:
-
-```bash
-doxloop generator doctor
-doxloop generator info <generator>
-```
-
-## Agent evaluations
-
-```bash
-pnpm eval:agents -- --agent codex --case cli
-```
-
-Real-agent evaluations run reviews in read-only/plan mode. A case must:
-
-- exit successfully;
-- identify the required behavior signals;
-- cite enough configured source evidence;
-- prioritize findings;
-- report a score out of 100; and
-- leave the fixture project byte-for-byte unchanged.
-
-Evaluation output is written below the Git-ignored `evals/results/` directory.
-Use a scheduled or manually approved job for model-backed evaluations; keep the
-deterministic typecheck, tests, skill validation, build, and package checks on
-every pull request.
-
-## Publishing
-
-Never run `doxloop deploy` in an untrusted pull-request context. Use protected
-environments and short-lived or scoped credentials. Run `doxloop deploy
---dry-run` before an approved deployment.
-
-Project identity, slug, destination, and visibility can be committed through
-`doxloop settings`. An approved non-interactive job then runs:
-
-```bash
-doxloop deploy --yes
-```
-
-Use `doxloop deploy --public --yes` only when the job is explicitly authorized
-to override the saved visibility and publish to everyone.
+# Automation and CI
+
+Doxloop automates documentation maintenance from the control center. Monitoring
+watches the product repository, drafts a proposal when pages go stale, and
+leaves the decision to a reviewer. Hosted continuous integration is a separate,
+narrower concern: a runner has no signed-in coding agent and no browser, so it
+can only run deterministic checks.
+
+## Doxloop's own CI
+
+The Doxloop repository runs `.github/workflows/ci.yml` on every pull request:
+typecheck, the unit suite, skill validation, and a matrix that scaffolds,
+previews, and builds every official generator with `scripts/ci-generator-smoke.mjs`.
+`pnpm test` no longer triggers the full build; it compiles the core and the
+generator packages only (`pnpm run build:test`), and the UI bundle is built by
+`pnpm run build`.
+
+## Automate maintenance with Monitoring
+
+Open **Sources** and choose **Monitoring**. The dialog asks for:
+
+- **Product branch**: the branch documentation follows.
+- **Schedule**: daily, weekdays, weekly, monthly, or a custom interval in
+  minutes or hours. Times use the device timezone.
+- **Advanced watch scope and budgets**: watched paths, ignored paths, the
+  maximum agent minutes and runs per day, the maximum Claude spend per run in
+  US dollars (Claude Code only; Codex and Gemini have no spending flag), how
+  many days verified evidence may age before it is re-verified, and whether
+  expired verification warns or fails validation. The agent-minutes budget
+  also bounds planning; `DOXLOOP_PLAN_TIMEOUT_MINUTES` overrides it for
+  planning alone, and both default to 20 minutes for the planner.
+
+**Save and install** registers a local OS scheduled job using launchd,
+systemd or cron, or Windows Task Scheduler. On macOS, Doxloop smoke-tests the
+new job in the real scheduler context before reporting success, including
+whether the background process can find the coding agent. Other platforms
+verify that the native schedule was installed.
+
+Each cycle compares the documented commit with the provider's branch head
+through the provider's read-only API. When the commit changed, Doxloop asks for
+the changed-file list, downloads that exact commit as isolated evidence, and
+checks which pages the change made stale. Current documentation records a quiet
+no-op and starts no agent. Stale documentation starts the coding agent already
+signed in on the machine, in an isolated workspace, and the result appears as a
+proposal under **Review**. Monitoring never clones, fetches, commits, pushes, or
+changes hooks in a source checkout, never edits the real documentation before a
+reviewer accepts it, and never publishes.
+
+Scheduled monitoring works with every source type. A Git repository source is
+checked through the provider's API. A local folder is checked in place: a Git
+checkout by its HEAD commit and working tree, any other folder by the file
+digests recorded at the last sync, so even a plain folder can name the files
+that changed. Private GitHub repositories use the environment variable named
+by the source's `tokenEnv` setting, `GITHUB_TOKEN` by default, which is read
+at runtime and never saved.
+
+Every cycle computes what to do from the current repository state rather than
+from the event that triggered it, so a missed, delayed, or duplicated run costs
+time but never correctness.
+
+## Check status and run a cycle
+
+The **Sources** page shows each connected source with its last check time and
+a **Test connection** action. **Home** shows when the loop was last
+checked and whether a proposal needs review. In the Monitoring dialog, **Check
+now** starts one cycle as a visible job: its live log is under **Plan**, and
+when it finishes a notice reports whether anything changed, how many pages
+are stale, and which proposal was drafted. **Disable** removes the schedule
+while keeping the saved settings for later.
+
+## Review background proposals
+
+Background proposals stay pending until reviewed. Open **Review** to see every
+proposal with its trigger and status. Each file shows the current version
+beside the proposed version, rendered the way the published site renders them,
+with changed words highlighted. The source view shows line-level context with
+an **Accept change** button on each change. Only accepted changes are applied:
+current file fingerprints are verified and the selected result is validated
+before the actual documentation is touched.
+
+## Publish from the control center
+
+Publishing is always an explicit action on the **Publish** page. Sign in to
+Doxbrix with your browser, choose **Public** or **Private**, then choose
+**Publish to Doxbrix**. Every publish validates and builds first and uploads
+nothing if a check fails. Sites are private unless you choose otherwise.
+
+## Headless checks for hosted CI
+
+A hosted runner cannot open the control center or run a signed-in coding
+agent, so keep it limited to deterministic checks that need no agent, no model,
+and no credentials. The Doxloop package exposes three headless checks for that
+purpose, each with a `--format json` option and a non-zero exit status on
+failure:
+
+| Check | Purpose |
+| --- | --- |
+| `doxloop check` | Report the pages a source change made stale, using the committed evidence map and the provider branch. |
+| `doxloop test` | Validate pages, navigation, links, metadata, code fences, and page depth. Errors fail; warnings do not. |
+| `doxloop quality` | Run the versioned release-quality contract, including the generator's strict build. See [release quality](./release-quality.md). |
+
+Keep authoring on machines where a coding agent is signed in: a developer
+workstation or a self-hosted runner on hardware the team controls. Never deploy
+from an untrusted pull-request context; use protected environments and
+short-lived, scoped credentials.

package/docs/doxbrix-http-api.md

@@ -122,7 +122,8 @@ The request body is:
   "media": [
     {"path": "assets/logo.svg", "base64": "…"}
   ],
-  "publish": true
+  "publish": true,
+  "replace": true
 }
 ```
 
@@ -133,6 +134,12 @@ Only the manifest and files under the configured documentation directory may
 be represented in the payload; configured product-source directories must
 never be included.
 
+Set `replace` to `true` when the bundle is the complete source of truth. The
+server then removes pages, navigation items, and spaces that existed in the
+previous bundle but are absent from this one. Doxloop deployments always use
+this mode so deleting or renaming a local page cannot leave stale published
+content behind.
+
 This endpoint is the native Doxbrix generator boundary. Do not send external
 generator output to it; use the artifact deployment API below.
 

package/docs/existing-documentation.md

@@ -0,0 +1,80 @@
+# Rewrite existing documentation
+
+Doxloop can start from the documentation you already publish. Add the site's
+address as an **Existing documentation** source, on its own or next to source
+code and API specifications. The agent audits the existing pages, verifies
+them against your product sources, and rewrites them as a new professional
+documentation set that you review page by page and deploy to Doxbrix.
+
+## Add the site
+
+1. Start `doxloop ui`. In the setup wizard's **Sources** step, or on the
+   **Sources** page of an open workspace, choose **Add source** → **Existing
+   documentation**.
+2. Enter the public address of the documentation, for example
+   `https://docs.example.com` or a section such as
+   `https://example.com/docs/`. The address sets the crawl scope: only pages
+   under that path on the same host are read.
+3. Choose **Crawl site**. Doxloop discovers pages through the site's
+   `sitemap.xml`, `llms.txt`, and the links between pages, converts each page
+   to Markdown, and shows how many pages and words it read, the generator it
+   detected, sample titles, and any broken links or skipped URLs.
+4. Choose **Add source**. Add product code or an OpenAPI specification as
+   further sources when you have them; they decide the facts.
+
+From the command line, `doxloop init my-docs --docs https://docs.example.com
+--source product=../my-app` and `doxloop create --docs <url> --output <dir>`
+do the same.
+
+Doxloop reads the site as a visitor. It executes no scripts, follows
+`robots.txt`, stops after three redirects, limits pages to 2 MB, and reads at
+most 150 pages by default (500 at most). Only public HTTP(S) addresses are
+accepted; localhost and private networks are refused. A documentation site
+behind the same sign-in as the captured application reuses the browser
+session recorded under **Application sign-in**; the cookies are matched by
+domain, so an unrelated site receives nothing.
+
+## What the agent does with it
+
+The crawled pages become a read-only snapshot beside your other materialized
+sources, outside the documentation project, so the old content can never be
+published by accident. The snapshot holds one Markdown file per page with its
+original URL, plus an `index.md` that lists every page.
+
+During planning the agent audits the existing documentation and the plan shows
+the result under **Existing documentation audit**:
+
+- **Not covered today** — product surfaces found in your source code that the
+  existing documentation never explains. Each gets a planned page.
+- **Contradicted by the product** — existing claims your sources disprove. The
+  rewrite corrects them.
+- **Obsolete** — pages or claims about behavior the product no longer has.
+- **Kept from the existing docs** — knowledge code cannot show (policies,
+  environment notes, support-born troubleshooting) that the rewrite carries
+  over.
+- **Findings** with a severity, and a decision for every crawled page:
+  rewrite, merge into a planned page, preserve, or drop with the reason.
+
+Approve, edit, or send the plan back for revision as usual. When you approve,
+Doxloop records a redirect from every existing page route to the page that
+absorbs it, so the preview and the Doxbrix build honor the old addresses.
+
+## With and without product sources
+
+With source code or an API specification connected, the product decides the
+facts. The agent writes corrected facts, never repeats a contradicted claim,
+and lists every correction in its summary.
+
+With only the documentation site connected, the agent restructures, clarifies,
+deduplicates, and deepens what the existing pages already say, but does not
+add facts they do not support. Every page is recorded with `inferred`
+confidence and shows as unverified until you connect a product source and run
+an update, which verifies the claims against the code.
+
+## Keep the snapshot current
+
+The snapshot is frozen at crawl time. On the **Sources** page, the globe
+action re-crawls the site; the next update names the existing pages that
+changed since the last crawl so the agent can decide whether the rewritten
+documentation must follow. A stale snapshot on disk shows as **Needs
+attention** in the source's status.