@doxbrix/doxloop 0.1.5 → 0.2.0

package/README.md

@@ -10,7 +10,7 @@
 
 <p align="center">
   Turn source code or an API specification into a polished, validated documentation site<br>
-  with Codex, Claude Code, or Gemini.
+  with Codex, Claude Code, or Gemini, from one local control center.
 </p>
 
 <p align="center">
@@ -22,70 +22,128 @@
 <p align="center">
   <a href="#quickstart">Quickstart</a> ·
   <a href="#real-examples">Real examples</a> ·
-  <a href="#use-doxloop-in-vs-code-codex-or-claude">Editor and agent apps</a> ·
-  <a href="#everyday-workflow">Commands</a> ·
+  <a href="#the-workspace">The workspace</a> ·
+  <a href="#keep-documentation-current">Monitoring</a> ·
+  <a href="#review-what-changed-and-why">Review</a> ·
   <a href="#guides">Guides</a>
 </p>
 
+https://github.com/user-attachments/assets/2949f435-538d-40eb-9d3d-b226664b724d
+
 ```mermaid
 flowchart LR
     A["Source code<br>or OpenAPI"] --> B["Doxloop +<br>your coding agent"]
-    B --> C["Structured<br>documentation"]
-    C --> D["Preview, validate,<br>and publish"]
+    B --> C["Plan, write,<br>and review"]
+    C --> D["Preview, validate,<br>and deploy"]
 ```
 
-Doxloop gives your coding agent a repeatable documentation workflow: inspect
-the source, identify the audience, plan the content, write generator-native
-pages, build navigation, and validate the result. Your product source stays
-separate from the generated documentation project.
+Doxloop is a local, browser-based control center for documentation. You connect
+the sources that describe your product, describe what readers should be able to
+do, and approve a documentation plan. Your coding agent researches the evidence
+and writes generator-native pages into an isolated proposal. You review every
+change, accept what is right, preview the site, and deploy it, all from the same
+window. Product source stays read-only and separate from the documentation
+project.
 
 ## Quickstart
 
 ### 1. Install
 
-Requires Node.js 20.12 or later.
-
-```bash
-npm install --global @doxbrix/doxloop
-```
+Doxloop requires Node.js 22.13 or later. Install Google Chrome for application screenshots and sign-in capture; text-only authoring does not need a browser.
 
-### 2. Set up the documentation project
+Try the bundled demo first, without an agent or a model charge:
 
-Run this from your product directory:
-
-```bash
-doxloop init
+```sh
+npx @doxbrix/doxloop demo
 ```
 
-Doxloop detects the product repository and guides you through the project
-location, product evidence, site title, and generator. It shows a complete
-summary before creating anything. Product code and documentation are kept in
-separate sibling directories.
-
-Documenting an API without a product checkout? Run the same command in the
-directory where you want to work, then choose **API specification** and enter
-the OpenAPI file or URL when asked.
-
-### 3. Create the documentation
+Then adopt an existing documentation folder in the setup wizard, or create a new project. Run the read-only documentation audit before requesting an update. Start with the five-page preset: review the plan and its page, screenshot, and time caps before generation. Planning and writing are separate agent runs; each may take several minutes and uses your agent subscription or billing. Doxloop reports observed durations when comparable completed runs exist; a time cap is not a price quote.
 
 ```bash
-cd ../my-product-docs
-doxloop create
+npm install --global @doxbrix/doxloop
 ```
 
-`create` asks what readers need and which agent to use, shows all supported
-choices, and automatically installs Codex, Claude Code, or Gemini with npm when
-you select a missing agent. It shows an authoring summary and starts the agent
-only after confirmation. Press Enter at the documentation request to let the
-agent recommend a complete, evidence-backed plan.
+### 2. Open the control center
 
-### 4. Preview and validate
+Open a terminal in the folder where you want the documentation project to be
+created. That is usually the parent folder of your product checkout, so the
+product and its documentation become sibling directories. Then start Doxloop:
 
 ```bash
-doxloop preview --open
-doxloop test
+doxloop ui
 ```
 
+This is the only command you need. It starts a loopback-only server on
+`http://127.0.0.1:4317` and opens your browser. Everything else happens in the
+browser. When no documentation project exists yet, Doxloop opens the setup
+wizard. When one exists, it opens the workspace for that project.
+
+Already have a documentation site? The wizard's first step offers **Use
+existing documentation folder**, which adopts a Docusaurus, MkDocs, Hugo,
+Sphinx, VitePress, Starlight, Nextra, Markdoc, Jekyll, or Doxbrix site as it
+is: Doxloop reads the site's configuration, lists its pages, and changes none
+of them. Every project you open is remembered, and the project switcher in the
+sidebar moves between them.
+
+For **Mintlify**, choose **Use existing documentation folder → Mintlify to
+Doxbrix**. Select a local folder or enter a GitHub repository, review the
+conversion, and create a new Doxbrix project. Doxloop uses the tested Doxbrix
+conversion engine and preserves the original Mintlify project. See
+[Import Mintlify documentation](docs/mintlify-import.md).
+
+### 3. Set up the workspace
+
+The wizard walks through five steps and creates nothing until the last one.
+
+1. **Workspace.** Choose **Start new** and enter a folder name for the
+   documentation project and the title readers will see, or choose **Use
+   existing documentation folder** to adopt a site you already have.
+2. **Sources.** Choose **Add source**, then **Source code** for a local folder
+   or a Git repository, **OpenAPI spec** to upload a file or paste a public
+   URL, or **Existing documentation** to crawl the docs site you publish today
+   so the agent can audit it and rewrite it (see
+   [Rewrite existing documentation](docs/existing-documentation.md)). Private
+   repositories accept a username and a personal access token that is held in
+   memory for the session and never written to the project.
+3. **Tools.** Pick the documentation generator (Doxbrix is recommended and
+   needs no installation), the coding assistant (Codex, Claude Code, or
+   Gemini), and optionally the model. If the assistant is not installed,
+   Doxloop installs it for you. Answer **Add product screenshots?** to let
+   Doxloop capture images from a running local or test application.
+4. **Guidance.** Describe what readers should be able to do, choose the
+   documentation depth (Comprehensive is recommended; the page count comes
+   from your sources, not from the depth), add audiences, and open **Advanced
+   planning preferences** for examples, locale, terminology, exclusions,
+   accessibility target, and how the planner should handle questions.
+5. **Review.** Check the summary and choose **Create documentation plan**.
+
+Doxloop then downloads read-only snapshots of any remote sources, installs the
+project-local authoring skills for the selected assistant, and starts a
+read-only planning run. The planner researches your sources and proposes a
+page structure. Nothing is written until you approve it.
+
+### 4. Approve the plan and generate
+
+The plan opens on the **Create** page. Answer anything under **Needs your
+decision**, adjust the **Documentation brief**, and edit the **Documentation
+structure**: add, reorder, remove, or defer pages, and open any page to change
+its purpose, priority, section, or screenshot treatment. Ask for changes in
+plain language under **Want to change the plan?** and a new plan version comes
+back. When it looks right, choose **Approve & generate**.
+
+Generation runs in an isolated workspace while **Live activity** shows each
+stage. You can stop it at any time. When it finishes, the result is a proposal
+and the documentation project is still unchanged.
+
+### 5. Review, preview, and deploy
+
+1. Open **Review** to compare the current and proposed versions of every file.
+   Accept one change, one file, or everything, or ask the agent to revise a
+   specific file.
+2. Choose **Preview docs** in the top bar to open the rendered site locally.
+3. Open **Publish**, sign in to Doxbrix once from your browser, choose who can
+   read the site, and choose **Publish to Doxbrix**.
+
 Your source and docs remain separate:
 
 ```text
@@ -94,230 +152,322 @@ workspace/
 └── my-product-docs/  ← editable and deployable documentation
 ```
 
-From then on, the everyday workflow is deliberately short:
-
-```bash
-doxloop update
-doxloop deploy
-doxloop settings
-```
-
-No configuration flags are required for interactive use. Advanced flags remain
-available as optional one-run overrides for scripts and CI.
+From then on, every update follows the same loop: describe the change on the
+**Update** page, approve the plan, review the proposal, preview, and deploy.
 
 ## Real examples
 
-### Lodash developer docs from the CLI
-
-From the [Lodash](https://github.com/lodash/lodash) source directory:
+### Lodash developer docs from a local checkout
 
-```bash
-doxloop init
-cd ../lodash-docs
-doxloop create
-```
+With the [Lodash](https://github.com/lodash/lodash) repository checked out,
+open a terminal in its parent folder and run `doxloop ui`. In the wizard:
 
-At the `create` prompt, request developer documentation with a quickstart,
-class and function reference, and a simple example for every function. Choose
-Claude Code when Doxloop asks which agent to use. If it is missing, Doxloop
-installs it before the run. That choice can be remembered for later updates.
+1. Name the workspace `lodash-docs`.
+2. Add a **Source code** source, choose **Local folder**, and browse to the
+   Lodash checkout.
+3. Choose **Doxbrix** as the generator and **Claude Code** as the coding
+   assistant. Doxloop installs it if it is missing.
+4. Under **Guidance**, ask for developer documentation with a quickstart, a
+   class and function reference, and a simple example for every function.
+5. Choose **Create documentation plan**, approve the plan, and review the
+   proposal.
 
 **Generated documentation:** <https://apps-lodash-docs.sites.doxbrix.com/>
 
-### Petstore API docs from VS Code with Codex
+### Petstore API docs from an OpenAPI URL
 
-First, initialize a documentation project. Use `petstore-docs` as the project
-directory, choose **API specification**, and enter
-`https://petstore3.swagger.io/api/v3/openapi.json` when asked:
+No product checkout is needed. Run `doxloop ui` in any folder and, in the
+wizard:
 
-```bash
-doxloop init
-cd petstore-docs
-code .
-```
-
-Then give Codex this prompt:
-
-> Using Doxloop authoring, create API documentation for this OpenAPI document:
-> https://petstore3.swagger.io/api/v3/openapi.json
-
-Because `doxloop init` installs the Doxloop authoring skills inside the project,
-Codex can inspect the OpenAPI document and create the pages, endpoint reference,
-examples, and navigation directly in the opened folder.
+1. Name the workspace `petstore-docs`.
+2. Add an **OpenAPI spec** source, choose **From URL**, and enter
+   `https://petstore3.swagger.io/api/v3/openapi.json`.
+3. Choose **Codex** as the coding assistant.
+4. Under **Guidance**, ask for API documentation with an endpoint reference and
+   request examples.
+5. Choose **Create documentation plan**, approve the plan, review the proposal,
+   and open **Preview docs**.
 
 **Generated documentation:** <https://apps-pet-store.sites.doxbrix.com/>
 
-When it finishes:
-
-Run `doxloop preview --open` and `doxloop test` when it finishes.
-
-## Use Doxloop in VS Code, Codex, or Claude
-
-Prefer working in Visual Studio Code, the Codex app, Claude Code, or another
-local agent experience? Initialize the project first:
-
-```bash
-doxloop init
-```
-
-Then open the generated folder where you want to work:
-
-| Where | Open the project |
-| --- | --- |
-| VS Code with Codex | `code ../my-product-docs` |
-| Codex app | Open the generated documentation folder |
-| Claude Code | `cd ../my-product-docs && claude` |
-
-Ask the agent to use Doxloop authoring:
-
-```text
-Use Doxloop authoring to create developer documentation for this project.
-Start with a five-minute quickstart, then add task guides and API reference.
-```
-
-`doxloop init` installs project-local skills for the supported agent
-ecosystems:
-
-| Agent experience | Installed skills |
-| --- | --- |
-| Codex and Gemini | `.agents/skills/` |
-| Claude Code | `.claude/skills/` |
-
-If an editor does not load project skills automatically, prepare a complete
-prompt and paste it into the agent session:
-
-```bash
-doxloop create --print \
-  "Create developer documentation with a quickstart and API reference."
-```
-
-> `--print` cannot record when the external agent finishes. Use a
-> Doxloop-launched CLI agent when automatic source-change tracking is important.
-
 ## What Doxloop handles
 
 | Capability | What you get |
 | --- | --- |
-| 🔎 **Source-grounded research** | Uses code, public interfaces, tests, examples, and configuration as evidence. |
-| 🧭 **Documentation planning** | Identifies readers, important workflows, page coverage, and navigation before writing. |
+| 🔎 **Source-grounded research** | Uses code, public interfaces, tests, examples, configuration, and OpenAPI documents as evidence. |
+| 🔁 **Rewrite existing docs** | Crawls the documentation you publish today, reports coverage gaps, contradicted claims, and obsolete pages against your sources, and rewrites it with redirects from every old page. |
+| 🧭 **Plan before writing** | Proposes readers, page coverage, and navigation as an editable plan that you approve before anything is written. |
 | ✍️ **Generator-native output** | Creates the right Markdown, MDX, configuration, components, and theme for the selected generator. |
-| ✅ **Built-in quality checks** | Validates pages, navigation, links, metadata, code fences, and generator conventions. |
-| 🔄 **Focused updates** | Tracks the source revision and directs the agent to documentation affected by product changes. |
-| 🔐 **Local-first control** | Keeps authoring, validation, and preview local; publishing is always a separate command. |
+| ✅ **Built-in quality checks** | Validates pages, navigation, links, metadata, code fences, page depth, and generator conventions on every proposal and before every deploy. |
+| 🔍 **Reviewable proposals** | Every run lands in an isolated proposal with rendered and source comparisons, per-change acceptance, rationale, and evidence. |
+| 📊 **Coverage by surface** | Shows which discovered product surfaces have documentation evidence and lets you resolve gaps. |
+| ⚙️ **Monitoring** | Polls the source repository on a local schedule and drafts a proposal when documentation goes stale. |
+| 📸 **Guide screenshots** | Gives the agent a scoped browser, verifies every PNG, and embeds images beside the steps they explain. |
+| 🔐 **Local-first control** | Keeps authoring, validation, and preview on your machine. Deploying is a separate confirmed action and credentials never reach the browser. |
+
+## The workspace
 
-## Everyday workflow
+Every page has a stable URL, so browser back and forward work as expected. The
+left navigation shows:
 
-| Goal | Command |
+| Page | What you do there |
 | --- | --- |
-| Create a docs project | `doxloop init` |
-| Generate documentation | `doxloop create` |
-| Update docs after code changes | `doxloop update` |
-| View or change project settings | `doxloop settings` |
-| Run a read-only quality review | `doxloop review` |
-| Preview locally | `doxloop preview --open` |
-| Validate the project | `doxloop test` |
-| Check setup and agent readiness | `doxloop doctor` |
-| See project status | `doxloop status` |
-| Deploy using saved settings | `doxloop deploy` |
-
-Run `doxloop <command> --help` for every option.
+| **Home** | Follow the loop from sources through plan, write, review, and publish. See what needs your review, overall coverage, the published address, and recent activity. Press ⌘K to search pages, screens, and actions from anywhere. |
+| **Sources** | Connect and test local folders, Git repositories, OpenAPI specifications, and existing documentation sites. Set documentation ownership per source, review coverage by surface, resolve gaps, and configure **Monitoring**. |
+| **Plan** | Describe what readers need, choose the planning agent, model, and screenshot behaviour, review and edit the plan, and approve generation. The page also keeps the **Update history** of every request. |
+| **Docs** | Browse every page by navigation section, preview it, edit its metadata, and describe a focused agent edit. Review the rendered and source changes before accepting, rejecting, refining, or undoing them. The **Navigation** view arranges the sidebar and **Images & files** manages uploads and alt text. |
+| **Review** | Inspect each proposal file by file, read why each change was made, accept changes at any granularity, ask the agent to revise, and optionally prepare a pull request branch. |
+| **Publish** | Publish to Doxbrix: a pre-publish checklist, public or private access, the live site with its address, changes waiting since the last publish, and **History**. |
+| **Settings** | Change the site title, default agent, audience and voice, terminology and the generated glossary, application screenshot settings, branding (logo, colours, fonts), and see the active generator. |
+
+**Preview docs** in the top bar starts a local preview of the current
+documentation and opens it in a new tab. The project name at the top of the
+sidebar is the **project switcher**: it lists the projects you opened recently,
+opens any folder, imports an existing documentation site, or starts the setup
+wizard for a new project. **New documentation project** at the bottom of the
+sidebar opens the same wizard.
+
+### Work with more than one project
+
+Doxloop shows one project at a time and remembers every project it has opened.
+Open the project switcher and pick a recent project to move to it in one click;
+both stay in the list. **Open folder…** opens a folder that is already a
+Doxloop project, or offers to import it when it only holds a documentation
+site. **Import existing documentation…** asks for the folder, shows the
+detected generator, content directory, page count, and the first pages, lets
+you correct any of them, and then adopts the folder: Doxloop writes its own
+project file, an evidence map that marks every page as not yet verified, and
+the agent skills, and runs a read-only discovery pass. No page is modified.
+Sites built with a generator other than Doxbrix need that generator's Doxloop
+package; the import dialog offers to add it to the folder's `package.json`.
+
+Switching is refused while a plan, generation, edit, or deployment is running
+in the current project; a local preview is stopped, because it serves the
+project that started it.
+
+### Edit a page
+
+Run `doxloop ui`, open **Pages**, and select one or more existing pages. Tell
+the agent what should change, optionally allow related navigation or image
+updates, and wait for the isolated proposal. The live documentation remains
+unchanged until you compare the rendered and source versions and choose
+**Accept**; you can also **Reject**, **Refine**, or **Undo** the edit.
+
+Some changes need no agent at all. **Page metadata** under the page header
+edits the title, description, sidebar icon, canonical URL, and social image
+directly, with validation and rollback. **Insert an image…** in the composer
+picks or uploads an image and adds it to the instruction.
+
+### Arrange the navigation
+
+Open **Pages → Navigation**. Drag rows to reorder pages, drop them into a
+section to group them, or use Alt with the arrow keys; select a row to rename
+its label, choose an icon, or hide it. Pages that exist but are not in the
+sidebar are listed under **Add page**. **Save navigation** validates the tree,
+writes it to the generator's own file (`docs.json` for Doxbrix, the `nav` list
+in `mkdocs.yml` for MkDocs), and reloads the preview beside the editor.
+Generators whose navigation lives in code are named instead of edited. The
+same editor appears in plan review, where it arranges the sections of a
+proposed plan.
+
+### Brand the site
+
+Open **Settings → Branding**. For Doxbrix sites, choose the logo and favicon
+from the project's images (or upload them), set the primary colour and the
+light and dark accents and backgrounds, pick the colour mode and code theme,
+and name the body, heading, and code fonts. The preview below reloads on save.
+Other generators keep their theme in their own configuration file, which the
+panel names.
+
+### Manage images and files
+
+Open **Pages → Images & files**. Upload or drop images and files into the
+generator's asset directory, see which pages embed each one, edit the alt text
+across all of them at once, replace a file in place, or delete one that no page
+uses. Screenshots in a proposal that is still under review can be replaced from
+the capture gallery before you accept it.
+
+### Write release notes
+
+When a connected source is a Git checkout, the **Update** page offers
+**Release notes** beside the usual documentation request. Choose the
+repository, the version label, and the two refs that bound the release;
+Doxloop reads the commits, changed files, and the matching changelog section
+between them and gives the planner that inventory as the only evidence for the
+release page.
+
+### Generate a glossary
+
+Under **Settings → Audience and voice**, terminology is edited as term and
+definition rows. **Generate glossary page** writes a glossary page from those
+rows in the generator's format, adds it to the navigation, and records it in
+the evidence map, so the vocabulary the team curates is visible to readers
+without an agent run.
 
 ### Change project settings
 
-Use one settings command instead of editing `.doxloop/project.json` or
-remembering configuration flags:
-
-```bash
-doxloop settings
-```
-
-The interactive settings menu manages:
-
-- product source directories and OpenAPI specifications;
-- the site title and default authoring agent;
-- audience, locale, tone, and reader outcomes;
-- design references and application screenshot behavior; and
-- hosted project name, slug, visibility, and Doxbrix destination.
+Open **Settings** instead of editing `.doxloop/project.json` by hand. Its five
+sections manage:
+
+- **General**: site title and the default documentation agent;
+- **Audience and voice**: primary audience, audiences, experience level,
+  locale, accessibility target, tone, priority outcomes, preferred examples,
+  design direction, terminology and the generated glossary page, exclusions,
+  and standing instructions;
+- **Visual evidence**: the safe application URL, ready path, starting route,
+  sign-in route, screenshot policy, viewport, capture workflow guidance, a
+  **Test application** check, and **Application sign-in** for login-protected
+  apps: record a signed-in browser session from a Chrome window Doxloop opens,
+  or save a test account's credentials that the capture server types for the
+  agent;
+- **Branding**: logo, favicon, colours, colour mode, and fonts for Doxbrix
+  sites, or the theme file to edit for other generators; and
+- **Generator**: the generator selected for this workspace.
 
 Generator changes are intentionally not performed in place because changing
-frameworks can overwrite generator-native files. Create a new project with
-`doxloop init` when migrating generators.
-
-### Optional automation overrides
-
-Interactive users do not need flags. Scripts can still override saved settings
-for one run:
-
-```bash
-doxloop create --agent codex --reasoning high
-doxloop create --agent claude --model <model-name>
-doxloop create --agent gemini
-```
+frameworks can overwrite generator-native files. Start a new documentation
+project when migrating generators.
 
 ### Ask for exactly what you need
 
-```bash
-doxloop create \
-  "Write for platform engineers. Include installation, Kubernetes deployment, authentication, a production-readiness checklist, and troubleshooting."
-```
+The request box on the **Create** and **Update** pages accepts plain language.
+Describe the audience, desired outcomes, required pages, tone, priorities, or
+exclusions, for example:
+
+> Write for platform engineers. Include installation, Kubernetes deployment,
+> authentication, a production-readiness checklist, and troubleshooting.
+
+> Document webhook retries and remove the legacy import workflow.
+
+Choose a starting scope, optionally set **Minimum pages to write** when the
+existing documentation is thin, and decide whether the planner should ask you
+questions in review, use recommendations, or always wait for answers.
+
+## Keep documentation current
+
+Documentation goes stale because nothing reports it. Doxloop records the
+sources behind every page in `.doxloop/evidence-map.json`, so it can name the
+individual pages a later change made stale rather than only reporting that a
+source changed.
+
+Open **Sources** and choose **Monitoring** to configure it:
+
+1. Enter the **Product branch** to follow.
+2. Choose a **Schedule**: daily, weekdays, weekly, monthly, or a custom
+   interval in minutes or hours. Times use your device timezone.
+3. Optionally open **Advanced watch scope and budgets** to set watched and
+   ignored paths, the maximum agent minutes and runs per day, a maximum
+   Claude spend per run, and how old verified evidence may become before it
+   is re-verified.
+4. Choose **Save and install**.
+
+Doxloop installs a local scheduled job that checks every connected source. A
+Git repository source is checked through the provider's read-only API; when
+the commit changed, that exact commit is downloaded as isolated evidence. A
+local folder is checked in place: a Git checkout by its HEAD commit and
+working tree, any other folder by comparing its files with the content
+recorded at the last sync. When documentation went stale, the job drafts a
+proposal under **Review**. Monitoring never modifies the product source, never
+fetches or pulls into a checkout, never installs repository hooks, never needs
+a model API key, and never publishes. Choose **Check now** to run a cycle
+immediately; the result appears as a notice in the control center and under
+**Recent activity**. **Disable** removes the schedule while keeping the
+settings.
+
+Lock files and snapshots are ignored by default. Test files are not, because
+the authoring workflow reads tests as evidence of supported behaviour.
+
+## Review what changed and why
+
+The **Review** page keeps the full review in one place:
+
+1. The proposal list shows what is waiting, why it was drafted, and its status.
+2. **Changed files** switches between every documentation and supporting-file
+   change, with search.
+3. **Diff layout** switches between side-by-side and stacked comparisons of the
+   rendered pages, and the source view shows line-level context with an
+   **Accept change** button on each individual change.
+4. **Why this change** shows the supporting evidence, reader-facing claims,
+   affected public interfaces, assumptions to verify, and validation results.
+5. **Accept change**, **Accept file**, and **Accept all** apply the selection.
+   **Ask agent to revise** regenerates only the selected scope and supersedes
+   the earlier proposal. Applied page files link back to **Pages** for a new
+   agent-driven edit.
+6. **Preview documentation** renders the proposal, **Prepare PR branch**
+   stages the accepted result in a Git branch, and **Push & create PR** opens
+   a pull request.
+
+Every accepted selection is checked against the original file fingerprint and
+validated before it is written. A local edit made while review is pending
+causes a visible conflict instead of an overwrite. Partial acceptance applies
+only the selected changes and keeps the proposal pending. Rejected proposals
+never change the documentation.
+
+Doxloop also keeps a local record of what it was asked to do and what happened.
+**Update history** on the Plan page lists each request, its
+outcome, and the pages it touched. **Deployment history** on the Publish page
+lists every deployment, including the ones that failed. The record lives in
+`.doxloop/doxloop.db`, which is added to `.gitignore` automatically and is
+readable only by its owner. Agent transcripts are not recorded.
+
+## Preview, validate, and deploy
+
+Doxloop validates pages, navigation, links, metadata, code fences, and page
+depth every time it creates a proposal, and again before every dry run and
+deployment. Validation errors stop a deployment; warnings are reported.
+
+Choose **Preview docs** at any time to open the local site. Then open
+**Publish**:
+
+1. Sign in to Doxbrix once. Doxloop opens your browser, you approve the code it
+   shows, and the session stays on this computer.
+2. Check **Ready to publish**: validation, and whether changes still wait in
+   **Review**. A check that fails keeps the publish button disabled.
+3. Choose who can read the site, **Public** or **Private**, and choose
+   **Publish to Doxbrix**. Doxloop validates, builds, and uploads; the site is
+   usually live in under a minute, and **Publish changes** sends later edits.
+
+To self-host instead of using Doxbrix, export a static site from the command line:
 
 ```bash
-doxloop update \
-  "Document webhook retries and remove the legacy import workflow."
+doxloop export --out ./site-export --zip
+doxloop deploy --target github-pages --base-path /my-repository
 ```
 
-You can describe the audience, desired outcomes, required pages, tone,
-priorities, or exclusions in plain language.
-
-## Preview, test, and publish
-
-Authoring never publishes automatically.
-
-```bash
-doxloop status
-doxloop test
-doxloop preview --open
-```
-
-To deploy through [Doxbrix](https://www.doxbrix.com/):
-
-```bash
-doxloop deploy
-```
-
-`deploy` validates the documentation, shows the exact name, slug, destination,
-visibility, page count, and warnings, then asks once before uploading. It offers
-sign-in after you approve the summary. Deployments are private by default.
-
-Use `doxloop settings` to change visibility or the hosted address. A public
-deployment always shows a default-no warning in an interactive terminal. For
-CI, the explicit combination `doxloop deploy --public --yes` runs without
-prompts.
+Authoring never publishes automatically, and configured product sources are
+never included in a deployment.
 
 ## Supported generators
 
 Doxbrix is built in and selected by default. External generators use a separate
-adapter package, so each documentation project installs only what it needs.
-
-| Generator | Package | Source format | Build output |
-| --- | --- | --- | --- |
-| **Doxbrix** | Included | Markdown and Doxbrix MDX | Doxbrix bundle |
-| Docusaurus | `@doxbrix/doxloop-generator-docusaurus` | Markdown and MDX | `build/` |
-| MkDocs Material | `@doxbrix/doxloop-generator-mkdocs` | Material Markdown | `site/` |
-| Sphinx | `@doxbrix/doxloop-generator-sphinx` | reStructuredText | `_build/html/` |
-| Hugo | `@doxbrix/doxloop-generator-hugo` | Markdown | `public/` |
-| VitePress | `@doxbrix/doxloop-generator-vitepress` | Markdown | `docs/.vitepress/dist/` |
-| Markdoc | `@doxbrix/doxloop-generator-markdoc` | Markdoc | `dist/` |
-| Nextra | `@doxbrix/doxloop-generator-nextra` | MDX | `out/` |
-| Starlight | `@doxbrix/doxloop-generator-starlight` | Markdown and MDX | `dist/` |
-| Jekyll | `@doxbrix/doxloop-generator-jekyll` | Markdown and Liquid | `_site/` |
-| Static HTML | `@doxbrix/doxloop-generator-static` | HTML | `site/` |
-
-Choose a generator during `doxloop init`. Doxbrix is the recommended first
-choice and needs no extra installation. Selecting another framework opens a
-second list and Doxloop offers to install its adapter package. The
+adapter package that Doxloop installs into the documentation project when you
+choose the generator in the setup wizard.
+
+| Generator | Tier | Needs | Package | Source format | Build output |
+| --- | --- | --- | --- | --- | --- |
+| **Doxbrix** | Full | Nothing extra | Included | Markdown and Doxbrix MDX | Static `build/` plus Doxbrix bundle |
+| Docusaurus | Full | Node.js 22.13+ | `@doxbrix/doxloop-generator-docusaurus` | Markdown and MDX | `build/` |
+| MkDocs Material | Full | Python 3.9+ | `@doxbrix/doxloop-generator-mkdocs` | Material Markdown | `site/` |
+| Sphinx | Supported | Python 3.9+ | `@doxbrix/doxloop-generator-sphinx` | reStructuredText | `_build/html/` |
+| Hugo | Supported | Hugo | `@doxbrix/doxloop-generator-hugo` | Markdown | `public/` |
+| VitePress | Supported | Node.js 22.13+ | `@doxbrix/doxloop-generator-vitepress` | Markdown | `docs/.vitepress/dist/` |
+| Starlight | Supported | Node.js 22.13+ | `@doxbrix/doxloop-generator-starlight` | Markdown and MDX | `dist/` |
+| Markdoc | Basic | Node.js 22.13+ | `@doxbrix/doxloop-generator-markdoc` | Markdoc | `dist/` |
+| Nextra | Basic | Node.js 22.13+ | `@doxbrix/doxloop-generator-nextra` | MDX | `out/` |
+| Jekyll | Basic | Ruby + Bundler | `@doxbrix/doxloop-generator-jekyll` | Markdown and Liquid | `_site/` |
+| Static HTML | Basic | Node.js 22.13+ | `@doxbrix/doxloop-generator-static` | HTML | `site/` |
+
+The tier describes Doxloop's adapter, not the framework. **Full** generators
+have their navigation, components, and diagrams validated and documented and
+are built end to end in CI. **Supported** generators validate nested
+navigation wherever the configuration can be read and report "navigation not
+verified" instead of guessing when it cannot. **Basic** generators scaffold,
+preview, and build, with navigation checks limited to the files the scaffold
+owns. The wizard's **Tools** step shows the tier beside each generator and
+checks that the required toolchain is installed before the project is created.
+Doxbrix is the recommended first choice. The
 [public generator guide](https://doxloop.sites.doxbrix.com/generators) covers
-installation, selection, inspection, removal, and migration.
+selection, native build requirements, and migration.
 
 ## Guides
 
@@ -325,8 +475,8 @@ installation, selection, inspection, removal, and migration.
 | --- | --- | --- |
 | [Create documentation](https://doxloop.sites.doxbrix.com/create) | [Project configuration](https://doxloop.sites.doxbrix.com/project-configuration) | [Troubleshooting](https://doxloop.sites.doxbrix.com/troubleshooting) |
 | [Update documentation](https://doxloop.sites.doxbrix.com/update) | [Generators](https://doxloop.sites.doxbrix.com/generators) | [Security](https://doxloop.sites.doxbrix.com/security) |
-| [Agent compatibility](https://doxloop.sites.doxbrix.com/agent-compatibility) | [CLI reference](https://doxloop.sites.doxbrix.com/cli) | [CI and automation](https://doxloop.sites.doxbrix.com/ci-automation) |
-| [Review documentation](https://doxloop.sites.doxbrix.com/review) | [Guide screenshots](https://doxloop.sites.doxbrix.com/guide-screenshots) | [Publish documentation](https://doxloop.sites.doxbrix.com/publish) |
+| [Review documentation](https://doxloop.sites.doxbrix.com/review) | [Agent compatibility](https://doxloop.sites.doxbrix.com/agent-compatibility) | [Automation and CI](https://doxloop.sites.doxbrix.com/ci-automation) |
+| [Guide screenshots](https://doxloop.sites.doxbrix.com/guide-screenshots) | [Publish documentation](https://doxloop.sites.doxbrix.com/publish) | |
 
 Browse all documentation at <https://doxloop.sites.doxbrix.com/>.
 
@@ -336,3 +486,48 @@ Browse all documentation at <https://doxloop.sites.doxbrix.com/>.
 and run unmodified copies for lawful personal or commercial purposes. Copying,
 modification, incorporation into other products, and redistribution are not
 permitted without explicit written permission from Doxbrix.
+
+### Direct page editing and bounded runs
+
+In **Pages**, open **Edit text directly** to edit Markdown/MDX, preview a draft,
+compare it with the saved version, and save without an agent. Browser drafts
+survive reloads. A fingerprint conflict keeps your draft and prevents an
+overwrite. Saves normally mark evidence for review; preserve verification only
+when the change is wording alone. Direct edits have persistent undo in
+**Manage pages → Recent direct edits**. Undo refuses to replace newer changes.
+
+**Manage pages** creates, moves and deletes pages while updating navigation,
+links and evidence in one validated transaction. Moves preserve or redirect
+old URLs; deletion requires a replacement when other pages link to the target.
+Doxbrix, MkDocs and autogenerated Docusaurus navigation are supported directly;
+custom coded navigation requires a reviewed agent proposal. Unsupported native
+formats are reported before any files change.
+
+Proposal review supports direct text edits, per-file and per-change rejection
+with reasons, and mixed accept/reject decisions. Rejecting remaining changes
+keeps already accepted work. A fully decided mixed proposal can be undone;
+rejected changes do not advance the source freshness baseline.
+
+A new plan's batch follows the documentation depth you choose: Starter allows
+five pages and 15 minutes per authoring attempt; Standard twelve pages and
+45 minutes; Comprehensive forty pages and 120 minutes. Each batch allows three
+screenshots per page it may write. **Run limits** and the plan review expose
+maximum pages, screenshot artifacts and minutes. Approval refuses oversized
+plans; mark extra pages **Later** or raise the limits explicitly. Generated
+proposals outside the approved page scope or artifact limits remain in the
+recovery workspace. The timer bounds each attempt; retries consume another
+attempt. Planned coverage earns no documented-page credit.
+
+Monitoring coordinates scheduled and manual authoring across processes,
+reserves daily starts in a persistent ledger, and pauses while a proposal
+needs review. Scheduled authoring requires verified agent sign-in. Monitoring
+logs rotate at 1 MiB, retaining one previous file; rotation does not reset the
+budget.
+
+GitHub Pages publishing permits `gh-pages` or `doxloop-pages/<name>`, rejects
+the checked-out source branch, and only updates existing branches marked as
+Doxloop deployments. Each update preserves deployment history and protects
+against concurrent remote changes. Use a fresh `doxloop-pages/<name>` for a
+legacy branch without the ownership marker.
+
+See [editing, auditing, versions, and review workflows](docs/review-workflows.md) for comments, bulk operations, read-only imports, reader verification, and the hosted pull-request impact check.