@doxbrix/doxloop 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (152) hide show
  1. package/CHANGELOG.md +34 -0
  2. package/LICENSE +93 -0
  3. package/README.md +576 -0
  4. package/SECURITY.md +15 -0
  5. package/assets/brand/README.md +8 -0
  6. package/assets/brand/doxloop-favicon.png +0 -0
  7. package/assets/brand/doxloop-logo-dark.png +0 -0
  8. package/assets/brand/doxloop-logo-light.png +0 -0
  9. package/assets/doxbrix-preview.css +6672 -0
  10. package/dist/agents.d.ts +26 -0
  11. package/dist/agents.d.ts.map +1 -0
  12. package/dist/agents.js +258 -0
  13. package/dist/agents.js.map +1 -0
  14. package/dist/args.d.ts +8 -0
  15. package/dist/args.d.ts.map +1 -0
  16. package/dist/args.js +95 -0
  17. package/dist/args.js.map +1 -0
  18. package/dist/artifact-deploy.d.ts +8 -0
  19. package/dist/artifact-deploy.d.ts.map +1 -0
  20. package/dist/artifact-deploy.js +240 -0
  21. package/dist/artifact-deploy.js.map +1 -0
  22. package/dist/auth.d.ts +17 -0
  23. package/dist/auth.d.ts.map +1 -0
  24. package/dist/auth.js +245 -0
  25. package/dist/auth.js.map +1 -0
  26. package/dist/author.d.ts +30 -0
  27. package/dist/author.d.ts.map +1 -0
  28. package/dist/author.js +195 -0
  29. package/dist/author.js.map +1 -0
  30. package/dist/capture.d.ts +10 -0
  31. package/dist/capture.d.ts.map +1 -0
  32. package/dist/capture.js +299 -0
  33. package/dist/capture.js.map +1 -0
  34. package/dist/cli.d.ts +3 -0
  35. package/dist/cli.d.ts.map +1 -0
  36. package/dist/cli.js +558 -0
  37. package/dist/cli.js.map +1 -0
  38. package/dist/deploy.d.ts +22 -0
  39. package/dist/deploy.d.ts.map +1 -0
  40. package/dist/deploy.js +136 -0
  41. package/dist/deploy.js.map +1 -0
  42. package/dist/doctor.d.ts +18 -0
  43. package/dist/doctor.d.ts.map +1 -0
  44. package/dist/doctor.js +222 -0
  45. package/dist/doctor.js.map +1 -0
  46. package/dist/doxbrix-markdown.d.ts +20 -0
  47. package/dist/doxbrix-markdown.d.ts.map +1 -0
  48. package/dist/doxbrix-markdown.js +873 -0
  49. package/dist/doxbrix-markdown.js.map +1 -0
  50. package/dist/errors.d.ts +8 -0
  51. package/dist/errors.d.ts.map +1 -0
  52. package/dist/errors.js +15 -0
  53. package/dist/errors.js.map +1 -0
  54. package/dist/fs.d.ts +6 -0
  55. package/dist/fs.d.ts.map +1 -0
  56. package/dist/fs.js +77 -0
  57. package/dist/fs.js.map +1 -0
  58. package/dist/generator-api.d.ts +69 -0
  59. package/dist/generator-api.d.ts.map +1 -0
  60. package/dist/generator-api.js +6 -0
  61. package/dist/generator-api.js.map +1 -0
  62. package/dist/generator-manager.d.ts +13 -0
  63. package/dist/generator-manager.d.ts.map +1 -0
  64. package/dist/generator-manager.js +155 -0
  65. package/dist/generator-manager.js.map +1 -0
  66. package/dist/generator-runtime.d.ts +24 -0
  67. package/dist/generator-runtime.d.ts.map +1 -0
  68. package/dist/generator-runtime.js +265 -0
  69. package/dist/generator-runtime.js.map +1 -0
  70. package/dist/generators.d.ts +21 -0
  71. package/dist/generators.d.ts.map +1 -0
  72. package/dist/generators.js +202 -0
  73. package/dist/generators.js.map +1 -0
  74. package/dist/preview.d.ts +21 -0
  75. package/dist/preview.d.ts.map +1 -0
  76. package/dist/preview.js +691 -0
  77. package/dist/preview.js.map +1 -0
  78. package/dist/progress.d.ts +19 -0
  79. package/dist/progress.d.ts.map +1 -0
  80. package/dist/progress.js +70 -0
  81. package/dist/progress.js.map +1 -0
  82. package/dist/project.d.ts +37 -0
  83. package/dist/project.d.ts.map +1 -0
  84. package/dist/project.js +499 -0
  85. package/dist/project.js.map +1 -0
  86. package/dist/sync.d.ts +7 -0
  87. package/dist/sync.d.ts.map +1 -0
  88. package/dist/sync.js +221 -0
  89. package/dist/sync.js.map +1 -0
  90. package/dist/types.d.ts +141 -0
  91. package/dist/types.d.ts.map +1 -0
  92. package/dist/types.js +2 -0
  93. package/dist/types.js.map +1 -0
  94. package/dist/validation.d.ts +4 -0
  95. package/dist/validation.d.ts.map +1 -0
  96. package/dist/validation.js +478 -0
  97. package/dist/validation.js.map +1 -0
  98. package/dist/version.d.ts +3 -0
  99. package/dist/version.d.ts.map +1 -0
  100. package/dist/version.js +5 -0
  101. package/dist/version.js.map +1 -0
  102. package/docs/agent-compatibility.md +41 -0
  103. package/docs/ci-and-automation.md +56 -0
  104. package/docs/doxbrix-http-api.md +182 -0
  105. package/docs/generator-authoring.md +59 -0
  106. package/docs/generator-selection.md +25 -0
  107. package/docs/project-format.md +97 -0
  108. package/docs/security-model.md +90 -0
  109. package/docs/troubleshooting.md +103 -0
  110. package/package.json +87 -0
  111. package/skills/doxloop-authoring/SKILL.md +381 -0
  112. package/skills/doxloop-authoring/agents/openai.yaml +4 -0
  113. package/skills/doxloop-authoring/assets/screenshot-highlight.js +83 -0
  114. package/skills/doxloop-authoring/references/accessibility.md +54 -0
  115. package/skills/doxloop-authoring/references/audience-flavors.md +93 -0
  116. package/skills/doxloop-authoring/references/branding.md +50 -0
  117. package/skills/doxloop-authoring/references/documentation-types.md +236 -0
  118. package/skills/doxloop-authoring/references/domain-ai-ml.md +67 -0
  119. package/skills/doxloop-authoring/references/domain-api-platform.md +68 -0
  120. package/skills/doxloop-authoring/references/domain-cli-tool.md +65 -0
  121. package/skills/doxloop-authoring/references/domain-data-platform.md +65 -0
  122. package/skills/doxloop-authoring/references/domain-developer-library.md +63 -0
  123. package/skills/doxloop-authoring/references/domain-ecommerce.md +63 -0
  124. package/skills/doxloop-authoring/references/domain-infrastructure-devops.md +67 -0
  125. package/skills/doxloop-authoring/references/domain-payments-fintech.md +69 -0
  126. package/skills/doxloop-authoring/references/domain-saas.md +71 -0
  127. package/skills/doxloop-authoring/references/domain-security-identity.md +65 -0
  128. package/skills/doxloop-authoring/references/editorial-style.md +105 -0
  129. package/skills/doxloop-authoring/references/examples-and-evidence.md +71 -0
  130. package/skills/doxloop-authoring/references/navigation-architecture.md +152 -0
  131. package/skills/doxloop-authoring/references/project-format.md +119 -0
  132. package/skills/doxloop-authoring/references/quality.md +122 -0
  133. package/skills/doxloop-authoring/references/reference-sites.md +207 -0
  134. package/skills/doxloop-authoring/references/screenshots.md +251 -0
  135. package/skills/doxloop-authoring/references/template-routing.md +94 -0
  136. package/skills/doxloop-authoring/references/type-administrator-guide.md +59 -0
  137. package/skills/doxloop-authoring/references/type-api-reference.md +66 -0
  138. package/skills/doxloop-authoring/references/type-architecture-concepts.md +61 -0
  139. package/skills/doxloop-authoring/references/type-cli-manual.md +61 -0
  140. package/skills/doxloop-authoring/references/type-deployment-operations.md +64 -0
  141. package/skills/doxloop-authoring/references/type-developer-portal.md +69 -0
  142. package/skills/doxloop-authoring/references/type-getting-started.md +59 -0
  143. package/skills/doxloop-authoring/references/type-integration-guide.md +59 -0
  144. package/skills/doxloop-authoring/references/type-migration-release.md +66 -0
  145. package/skills/doxloop-authoring/references/type-sdk-guide.md +63 -0
  146. package/skills/doxloop-authoring/references/type-troubleshooting-kb.md +63 -0
  147. package/skills/doxloop-authoring/references/type-user-guide.md +59 -0
  148. package/skills/doxloop-doxbrix/SKILL.md +83 -0
  149. package/skills/doxloop-doxbrix/agents/openai.yaml +4 -0
  150. package/skills/doxloop-doxbrix/references/api-endpoints.md +128 -0
  151. package/skills/doxloop-doxbrix/references/components.md +137 -0
  152. package/skills/doxloop-doxbrix/references/manifest.md +117 -0
package/CHANGELOG.md ADDED
@@ -0,0 +1,34 @@
1
+ # Changelog
2
+
3
+ All notable reader-visible changes to Doxloop are documented here. The project
4
+ uses semantic versioning after its first stable release.
5
+
6
+ ## Unreleased
7
+
8
+ ### Added
9
+
10
+ - Request-driven application guide screenshots for `doxloop create` and
11
+ `doxloop update`, with `--screenshots` and `--no-screenshots` overrides.
12
+ - Optional application launch, viewport, screenshot policy, and contextual
13
+ highlighting configuration without changing design-reference capture.
14
+ - Read-only agent invocation for documentation review.
15
+ - Post-authoring validation receipts and guarded synchronization baselines.
16
+ - Source-content fingerprints for committed and uncommitted synchronization.
17
+ - JSON output for `test` and `status`.
18
+ - Security, project-format, agent, CI, generator-authoring, generator-selection,
19
+ and troubleshooting documentation.
20
+
21
+ ### Changed
22
+
23
+ - Expanded native guidance for every official generator skill.
24
+ - Strengthened real-agent review evaluation with evidence, prioritization,
25
+ rubric, and read-only checks.
26
+ - CLI parsing now rejects unknown options and handles boolean flags
27
+ deterministically.
28
+
29
+ ### Security
30
+
31
+ - Documentation content directories must remain inside the project and cannot
32
+ use symlinks.
33
+ - Authenticated HTTP refuses redirects and requires HTTPS outside loopback.
34
+ - Design capture blocks private destinations and cross-origin navigation.
package/LICENSE ADDED
@@ -0,0 +1,93 @@
1
+ DOXLOOP PROPRIETARY SOFTWARE LICENSE
2
+ Version 1.0, 21 July 2026
3
+
4
+ Copyright (c) 2026 Doxbrix. All rights reserved.
5
+
6
+ 1. Definitions
7
+
8
+ "Software" means the Doxloop software and all source code, object code,
9
+ documentation, assets, and other materials distributed with this license.
10
+
11
+ 2. Limited License to Use
12
+
13
+ Subject to your compliance with this license, Doxbrix grants you a worldwide,
14
+ royalty-free, non-exclusive, non-transferable, and non-sublicensable license to
15
+ download, install, and run unmodified copies of the Software for any lawful
16
+ personal or commercial purpose.
17
+
18
+ You may make only the copies technically necessary to download, install, run,
19
+ and back up the Software. No other rights are granted.
20
+
21
+ 3. Restrictions
22
+
23
+ Unless you first obtain explicit written permission from Doxbrix, you may not:
24
+
25
+ a. copy or reproduce the Software except as expressly permitted in Section 2;
26
+ b. modify, adapt, translate, or create derivative works of the Software;
27
+ c. distribute, publish, sublicense, sell, rent, lease, transfer, mirror,
28
+ repackage, or otherwise make the Software or any part of it available to
29
+ another person or entity;
30
+ d. incorporate any source code from the Software into another work, product,
31
+ or service;
32
+ e. remove, alter, or obscure any copyright, license, attribution, or other
33
+ proprietary notice; or
34
+ f. reverse engineer, decompile, or disassemble the Software, except to the
35
+ limited extent that applicable law expressly permits despite this
36
+ restriction.
37
+
38
+ For clarity, prohibited redistribution includes publishing a copy or fork of
39
+ the source code outside the rights that GitHub's Terms of Service require for a
40
+ public repository, and republishing any Doxloop package or a modified version
41
+ of it to a package registry.
42
+
43
+ 4. GitHub Public Repository Rights
44
+
45
+ If the Software is made available in a public repository on GitHub, GitHub and
46
+ GitHub users receive the limited rights required by GitHub's applicable Terms
47
+ of Service, including rights to view and fork the repository through GitHub's
48
+ service. Those platform rights do not grant permission to use, copy, modify, or
49
+ redistribute the Software beyond GitHub's service or beyond the permissions in
50
+ Section 2.
51
+
52
+ 5. Ownership and Reservation of Rights
53
+
54
+ The Software is licensed, not sold. Doxbrix and its licensors retain all
55
+ right, title, and interest in and to the Software. All rights not expressly
56
+ granted by this license are reserved. No patent, trademark, or other license is
57
+ granted by implication or estoppel.
58
+
59
+ 6. Third-Party Materials
60
+
61
+ Third-party software and materials included with or used by the Software remain
62
+ subject to their respective licenses. This license does not restrict any rights
63
+ granted under those third-party licenses.
64
+
65
+ 7. Termination
66
+
67
+ This license terminates automatically if you violate any of its terms. Upon
68
+ termination, you must stop using the Software and delete all copies in your
69
+ possession or control, except copies that applicable law requires you to keep.
70
+
71
+ 8. Disclaimer of Warranty
72
+
73
+ THE SOFTWARE IS PROVIDED "AS IS" AND "AS AVAILABLE," WITHOUT WARRANTIES OR
74
+ CONDITIONS OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING WARRANTIES OF
75
+ MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE, AND NON-INFRINGEMENT.
76
+
77
+ 9. Limitation of Liability
78
+
79
+ TO THE MAXIMUM EXTENT PERMITTED BY LAW, DOXBRIX AND ITS LICENSORS WILL NOT BE
80
+ LIABLE FOR ANY INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL, EXEMPLARY, OR
81
+ PUNITIVE DAMAGES, OR FOR ANY LOSS OF DATA, PROFITS, REVENUE, BUSINESS, OR
82
+ GOODWILL, ARISING FROM OR RELATED TO THE SOFTWARE OR THIS LICENSE, REGARDLESS OF
83
+ THE THEORY OF LIABILITY AND EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
84
+
85
+ 10. Severability
86
+
87
+ If any provision of this license is held unenforceable, that provision will be
88
+ enforced to the maximum extent permitted and the remaining provisions will
89
+ remain in effect.
90
+
91
+ Use of the Software indicates acceptance of this license. For permissions not
92
+ granted here, contact Doxbrix and obtain explicit written permission before
93
+ proceeding.
package/README.md ADDED
@@ -0,0 +1,576 @@
1
+ <p align="center">
2
+ <picture>
3
+ <source media="(prefers-color-scheme: dark)" srcset="assets/brand/doxloop-logo-dark.png">
4
+ <source media="(prefers-color-scheme: light)" srcset="assets/brand/doxloop-logo-light.png">
5
+ <img src="assets/brand/doxloop-logo-light.png" alt="Doxloop" width="560">
6
+ </picture>
7
+ </p>
8
+
9
+ <h1 align="center">Doxloop</h1>
10
+
11
+ [![npm version](https://img.shields.io/npm/v/@doxbrix/doxloop.svg)](https://www.npmjs.com/package/@doxbrix/doxloop)
12
+ [![license](https://img.shields.io/badge/license-proprietary-red.svg)](./LICENSE)
13
+ [![node](https://img.shields.io/node/v/@doxbrix/doxloop.svg)](https://nodejs.org)
14
+
15
+ **Create professional product documentation from your source code with the
16
+ coding agent you already use.**
17
+
18
+ Doxloop is a local-first documentation CLI for Codex, Claude Code, and Gemini.
19
+ It gives your agent a structured authoring workflow, generator-specific format
20
+ knowledge, and quality checks so it can research your product and produce
21
+ accurate, maintainable documentation.
22
+
23
+ From a directory that contains your product, one command creates a separate
24
+ documentation project and starts the complete authoring workflow:
25
+
26
+ ```bash
27
+ doxloop create --source ./my-product --output ./my-docs
28
+ ```
29
+
30
+ The agent studies your product, proposes the right documentation set, confirms
31
+ important reader decisions, and creates the pages, navigation, examples, and
32
+ theme in `my-docs`. The product source is read-only evidence; it is never changed
33
+ or included in documentation deployment.
34
+
35
+ ## Why Doxloop?
36
+
37
+ - **Grounded in your product.** The agent researches configured source code,
38
+ public interfaces, tests, examples, and configuration instead of inventing
39
+ product behavior.
40
+ - **Complete documentation planning.** Before editing, it identifies likely
41
+ readers, important workflows, and the documentation types supported by the
42
+ source.
43
+ - **Professional authoring standards.** Pages follow consistent editorial,
44
+ accessibility, information-architecture, example, and verification rules.
45
+ - **Generator-native output.** Doxloop creates the correct navigation,
46
+ frontmatter, components, configuration, and page format for the selected
47
+ generator.
48
+ - **Consistent future updates.** Reader, scope, terminology, tone, and
49
+ accessibility decisions are saved with the project and reused by later runs.
50
+ - **Focused maintenance.** Doxloop tracks the source revision used for the last
51
+ independently validated documentation run, including committed and
52
+ uncommitted source content, and directs the agent to relevant changes.
53
+ - **Local control.** Source inspection, authoring, validation, and preview happen
54
+ locally. Publishing is always a separate command.
55
+
56
+ ## Requirements
57
+
58
+ - Node.js 20.12 or later
59
+ - For automatic agent launch, at least one supported agent CLI on `PATH`:
60
+ [Codex](https://developers.openai.com/codex/cli),
61
+ [Claude Code](https://claude.com/claude-code), or
62
+ [Gemini CLI](https://github.com/google-gemini/gemini-cli)
63
+
64
+ If you prefer to work in an IDE or desktop agent, use `--print` to generate the
65
+ prepared prompt and paste it into a local agent session.
66
+
67
+ ## Documentation
68
+
69
+ Jump directly to:
70
+
71
+ - [Quickstart](#quickstart)
72
+ - [Documentation requests and expert templates](#describe-the-documentation-you-want)
73
+ - [Application guide screenshots](#add-application-guide-screenshots)
74
+ - [Agent selection and compatibility](#choose-an-agent)
75
+ - [Updates and source synchronization](#keep-documentation-current)
76
+ - [Independent documentation review](#review-documentation)
77
+ - [Design references](#use-a-design-reference)
78
+ - [Generator selection](#choose-a-generator)
79
+ - [Project structure](#how-doxloop-works)
80
+ - [Validation and preview](#validate-and-preview)
81
+ - [Troubleshooting](#troubleshooting)
82
+ - [Free deployment with Doxbrix](#deploy-for-free-with-doxbrix)
83
+ - [Security](#security)
84
+
85
+ ## Quickstart
86
+
87
+ Install Doxloop:
88
+
89
+ ```bash
90
+ npm install --global @doxbrix/doxloop
91
+ ```
92
+
93
+ Create the documentation as a separate sibling project:
94
+
95
+ ```bash
96
+ doxloop create --source ./my-product --output ./my-docs
97
+ ```
98
+
99
+ That single command starts the agent and the complete Doxloop authoring
100
+ workflow. The agent:
101
+
102
+ 1. researches the configured product source;
103
+ 2. identifies the readers, public capabilities, and important workflows;
104
+ 3. proposes a prioritized documentation plan;
105
+ 4. asks once for any decisions that cannot be resolved from the request or
106
+ source;
107
+ 5. saves the confirmed documentation brief;
108
+ 6. creates or improves the complete agreed documentation set;
109
+ 7. adds every reader-facing page to generator-native navigation; and
110
+ 8. verifies the result against Doxloop's quality requirements.
111
+
112
+ Preview and validate the result:
113
+
114
+ ```bash
115
+ cd my-docs
116
+ doxloop preview --open
117
+ doxloop test
118
+ ```
119
+
120
+ The product and documentation projects must be separate directories:
121
+
122
+ ```text
123
+ workspace/
124
+ ├── my-product/ # read-only product source; never deployed
125
+ └── my-docs/ # documentation project and deployment boundary
126
+ ```
127
+
128
+ The generated documentation remains ordinary Markdown, MDX, reStructuredText,
129
+ Markdoc, or HTML—depending on the selected generator—so you can review, edit,
130
+ and version it like any other project.
131
+
132
+ ## Describe the documentation you want
133
+
134
+ Pass additional instructions directly to `doxloop create`:
135
+
136
+ ```bash
137
+ doxloop create "Write for platform engineers. Include installation, Kubernetes deployment, authentication, a production-readiness checklist, and troubleshooting."
138
+ ```
139
+
140
+ The request can describe the audience, outcomes, required pages, priorities,
141
+ terminology, tone, or meaningful exclusions. For example:
142
+
143
+ ```bash
144
+ doxloop create "Create a concise quickstart for application developers, followed by complete API reference documentation."
145
+ ```
146
+
147
+ ```bash
148
+ doxloop create "Prioritize self-hosted deployment and administration. Do not document internal APIs."
149
+ ```
150
+
151
+ These instructions work alongside evidence found in the product source. Durable
152
+ decisions are saved in `.doxloop/project.json` and reused during future updates
153
+ and reviews.
154
+
155
+ ### Expert templates are selected automatically
156
+
157
+ Doxloop does not require users to choose a preset. During discovery, the agent
158
+ infers the most relevant domain expertise and documentation-type playbooks from
159
+ the configured source, existing pages, persisted brief, and current request. It
160
+ then applies the audience inside that combination to adjust depth, terminology,
161
+ examples, risk guidance, and navigation.
162
+
163
+ For new or restructured sites, the agent also composes navigation from a shared
164
+ professional frame, the selected documentation-type blocks, domain-specific
165
+ overlays, and audience ordering. It presents a top-navigation and left-navigation
166
+ outline before authoring, removes unsupported or duplicate destinations, and
167
+ translates the result into the selected generator's native navigation system.
168
+
169
+ For example, this request combines payments-domain expertise, a developer-portal
170
+ playbook, and application-developer audience flavor:
171
+
172
+ ```bash
173
+ doxloop create "Create complete integration documentation for application developers using our payments API."
174
+ ```
175
+
176
+ This request combines SaaS-domain expertise, an administrator-guide playbook,
177
+ and workspace-administrator flavor:
178
+
179
+ ```bash
180
+ doxloop create "Create a task-oriented guide for workspace administrators, including onboarding, roles, security settings, and recovery."
181
+ ```
182
+
183
+ Users can also transform existing documentation through the normal update
184
+ workflow:
185
+
186
+ ```bash
187
+ doxloop update "Restructure the existing documentation as an administrator guide. Preserve verified content, remove duplication, and make configuration effects explicit."
188
+ ```
189
+
190
+ The agent states the inferred expertise profile in its discovery summary. It
191
+ asks only when competing profiles would materially change the reader, scope, or
192
+ outcomes. Template checklists guide investigation but never establish product
193
+ facts; every included capability still requires configured source evidence.
194
+
195
+ ### Add application guide screenshots
196
+
197
+ Ask for screenshots directly in the authoring request:
198
+
199
+ ```bash
200
+ doxloop create "Create an onboarding guide with screenshots. Highlight the control used in each important step."
201
+ ```
202
+
203
+ Or require screenshots independently of the request wording:
204
+
205
+ ```bash
206
+ doxloop create --screenshots "Create an onboarding guide."
207
+ doxloop update --screenshots "Refresh the billing workflow guide."
208
+ ```
209
+
210
+ Use `--no-screenshots` to suppress capture for a run. Screenshot capture is
211
+ integrated into create and update; it does not change `doxloop capture`, which
212
+ continues to collect ignored evidence from external design references.
213
+
214
+ Configure an application surface in `.doxloop/project.json` when Doxloop should
215
+ start or connect to a local test application:
216
+
217
+ ```json
218
+ {
219
+ "application": {
220
+ "baseUrl": "http://localhost:3000/",
221
+ "source": "product",
222
+ "startCommand": "npm run dev",
223
+ "readyPath": "/health",
224
+ "screenshots": {
225
+ "policy": "requested",
226
+ "viewport": { "width": 1440, "height": 900 },
227
+ "highlight": true
228
+ }
229
+ }
230
+ }
231
+ ```
232
+
233
+ Guide screenshots are saved as committed, generator-native documentation
234
+ assets and inserted beside the step they illustrate. When highlighting is
235
+ enabled, the authoring workflow adds a temporary high-contrast focus ring and
236
+ numbered marker before capture; the annotation is baked into the image without
237
+ modifying application source.
238
+
239
+ ## Choose an agent
240
+
241
+ Doxloop selects the first supported agent found on `PATH`. Choose one
242
+ explicitly when needed:
243
+
244
+ ```bash
245
+ doxloop create --agent codex
246
+ doxloop create --agent claude
247
+ doxloop create --agent gemini
248
+ ```
249
+
250
+ You can also select a model:
251
+
252
+ ```bash
253
+ doxloop create --agent claude --model <model-name>
254
+ ```
255
+
256
+ For Codex, set the reasoning effort for the run:
257
+
258
+ ```bash
259
+ doxloop create --agent codex --reasoning high
260
+ ```
261
+
262
+ Supported reasoning values are `minimal`, `low`, `medium`, `high`, and `xhigh`.
263
+
264
+ To use the prepared workflow in a local IDE or desktop agent without asking
265
+ Doxloop to start a CLI:
266
+
267
+ ```bash
268
+ doxloop create --print
269
+ ```
270
+
271
+ Paste the printed prompt into an agent session opened at the Doxloop project
272
+ root. Project skills are installed under `.agents/skills` for Codex and Gemini,
273
+ and `.claude/skills` for Claude Code.
274
+
275
+ > **Note:** `--print` prepares the prompt but cannot observe when the external
276
+ > agent finishes, so it does not record a new synchronization baseline. Use the
277
+ > Doxloop-launched CLI workflow when automatic source-change tracking is
278
+ > required.
279
+
280
+ ## Keep documentation current
281
+
282
+ After the product changes, run:
283
+
284
+ ```bash
285
+ doxloop update
286
+ ```
287
+
288
+ Doxloop compares the product source with the recorded synchronization baseline,
289
+ includes committed and uncommitted changes in the agent prompt, and directs the
290
+ agent to update affected reader-visible documentation.
291
+
292
+ Add instructions when an update needs special handling:
293
+
294
+ ```bash
295
+ doxloop update "Document webhook retries and remove the legacy import workflow."
296
+ ```
297
+
298
+ The synchronization baseline is stored in `.doxloop/sync-state.json`. Commit
299
+ this file when a team should share the same documentation update point.
300
+
301
+ ## Review documentation
302
+
303
+ Run an independent, read-only documentation review:
304
+
305
+ ```bash
306
+ doxloop review
307
+ ```
308
+
309
+ The agent reports prioritized findings for:
310
+
311
+ - accuracy and source evidence;
312
+ - reader workflows and coverage;
313
+ - information architecture and navigation;
314
+ - examples and reference depth;
315
+ - editorial quality and terminology;
316
+ - accessibility and presentation; and
317
+ - maintainability and release readiness.
318
+
319
+ `doxloop review` does not edit documentation files.
320
+ Supported agents run review in their read-only or plan mode.
321
+
322
+ ## Use a design reference
323
+
324
+ Doxloop can adapt the information architecture and design language of a public
325
+ documentation site while keeping your product's identity and content separate:
326
+
327
+ ```bash
328
+ doxloop init my-docs \
329
+ --source product=../my-product \
330
+ --reference https://docs.example.com/
331
+ ```
332
+
333
+ You can also add a reference while creating documentation:
334
+
335
+ ```bash
336
+ doxloop create \
337
+ --reference https://docs.example.com/ \
338
+ "Use this site as an information-architecture and presentation reference."
339
+ ```
340
+
341
+ The authoring workflow inspects a bounded set of representative pages and
342
+ captures layout, typography, color, navigation, and component patterns. It does
343
+ not use the reference site's product claims, examples, names, or navigation
344
+ labels as evidence for your product.
345
+
346
+ When the selected agent has no browser capability, capture measured local
347
+ evidence with:
348
+
349
+ ```bash
350
+ doxloop capture
351
+ ```
352
+
353
+ Doxloop installs a managed Playwright and Chromium environment on first use,
354
+ then saves screenshots and measured styles under
355
+ `.doxloop/cache/reference/`. Capture is limited to configured reference
356
+ origins.
357
+
358
+ ## Choose a generator
359
+
360
+ Doxbrix is the default generator and is included in the core package. Additional
361
+ generators are installed as independent packages so each project carries only
362
+ the integration it uses.
363
+
364
+ | Generator | Package | Source format | Build output |
365
+ | --- | --- | --- | --- |
366
+ | Doxbrix | Included | Markdown and Doxbrix MDX | Doxbrix bundle |
367
+ | Docusaurus | `@doxbrix/doxloop-generator-docusaurus` | Markdown and MDX | `build/` |
368
+ | MkDocs Material | `@doxbrix/doxloop-generator-mkdocs` | Material Markdown | `site/` |
369
+ | Sphinx | `@doxbrix/doxloop-generator-sphinx` | reStructuredText | `_build/html/` |
370
+ | Hugo | `@doxbrix/doxloop-generator-hugo` | Markdown | `public/` |
371
+ | VitePress | `@doxbrix/doxloop-generator-vitepress` | Markdown | `docs/.vitepress/dist/` |
372
+ | Markdoc | `@doxbrix/doxloop-generator-markdoc` | Markdoc | `dist/` |
373
+ | Nextra | `@doxbrix/doxloop-generator-nextra` | MDX | `out/` |
374
+ | Starlight | `@doxbrix/doxloop-generator-starlight` | Markdown and MDX | `dist/` |
375
+ | Jekyll | `@doxbrix/doxloop-generator-jekyll` | Markdown and Liquid | `_site/` |
376
+ | Static HTML | `@doxbrix/doxloop-generator-static` | HTML | `site/` |
377
+
378
+ To start a project with an external generator, install the core package and its
379
+ generator package locally:
380
+
381
+ ```bash
382
+ mkdir my-docs
383
+ cd my-docs
384
+ npm init --yes
385
+ npm install --save-dev \
386
+ @doxbrix/doxloop \
387
+ @doxbrix/doxloop-generator-mkdocs
388
+
389
+ npx doxloop init . \
390
+ --source product=../my-product \
391
+ --generator mkdocs
392
+
393
+ npx doxloop create
394
+ ```
395
+
396
+ Inspect and manage generator packages with:
397
+
398
+ ```bash
399
+ doxloop generator list
400
+ doxloop generator add mkdocs
401
+ doxloop generator info mkdocs
402
+ doxloop generator doctor
403
+ ```
404
+
405
+ `generator add` installs support; it does not convert the current project or
406
+ change its selected generator. To change generators, create or initialize a
407
+ project with the new generator, carry over the confirmed documentation brief
408
+ and source bindings, translate the content and navigation, then run
409
+ `doxloop test` and the new generator's strict build before changing public
410
+ URLs.
411
+
412
+ `doxloop preview` uses the selected generator's native development workflow.
413
+ Run `doxloop generator info <generator>` to see its build command and output
414
+ directory.
415
+
416
+ ## How Doxloop works
417
+
418
+ `doxloop init` creates a documentation project and installs two project-local
419
+ skills:
420
+
421
+ | Skill | Responsibility |
422
+ | --- | --- |
423
+ | `doxloop-authoring` | Discovery, consultation, coverage planning, evidence, editorial quality, accessibility, maintenance, and review |
424
+ | `doxloop-<generator>` | Native files, navigation, frontmatter, components, configuration, theme, preview, and generator-specific validation |
425
+
426
+ The project keeps the authoring context needed for consistent future work:
427
+
428
+ ```text
429
+ my-docs/
430
+ ├── .doxloop/
431
+ │ ├── project.json # sources, generator, design references, and editorial brief
432
+ │ ├── sync-state.json # last successful source synchronization
433
+ │ └── last-run.json # ignored local validation receipt
434
+ ├── .agents/skills/ # Codex and Gemini project skills
435
+ ├── .claude/skills/ # Claude Code project skills
436
+ └── docs/ # documentation content for the default generator
437
+ ```
438
+
439
+ Manage installed skills with:
440
+
441
+ ```bash
442
+ doxloop agent status
443
+ doxloop agent setup
444
+ doxloop agent update
445
+ ```
446
+
447
+ ## Validate and preview
448
+
449
+ Check the project at any time:
450
+
451
+ ```bash
452
+ doxloop status
453
+ doxloop test
454
+ doxloop preview --open
455
+ ```
456
+
457
+ - `status` summarizes the generator, pages, sources, references, errors, and
458
+ warnings.
459
+ - `test` validates the documentation structure, navigation, links, metadata,
460
+ code fences, and supported generator conventions.
461
+ - `preview` starts the selected generator's local preview with live reload where
462
+ supported.
463
+
464
+ Use `doxloop test --format json` or `doxloop status --format json` in
465
+ automation.
466
+
467
+ ## Troubleshooting
468
+
469
+ Run `doxloop doctor` inside an existing documentation project to check the
470
+ project configuration, source paths, selected agent, installed skills,
471
+ generator readiness, authentication, and documentation structure. Before a
472
+ project exists, provide the intended locations explicitly:
473
+
474
+ ```bash
475
+ doxloop doctor --source ./my-product --output ./my-docs
476
+ ```
477
+
478
+ Useful recovery commands include:
479
+
480
+ ```bash
481
+ doxloop agent setup
482
+ doxloop agent update
483
+ doxloop generator doctor
484
+ doxloop login
485
+ doxloop preview --port 4400 --open
486
+ ```
487
+
488
+ If validation fails, run `doxloop test`, resolve every reported error, and run
489
+ the selected generator's strict build. If deployment authentication fails,
490
+ sign in again with `doxloop login`; Doxbrix API URLs must use HTTPS and Doxbrix
491
+ tokens start with `dxb_`.
492
+
493
+ ## Deploy for free with Doxbrix
494
+
495
+ [Doxbrix](https://www.doxbrix.com/) is the hosted documentation platform that
496
+ works with Doxloop. Doxloop handles source-grounded authoring, maintenance,
497
+ validation, and preview on your machine. Doxbrix makes your documentation
498
+ agentic by adding an Ask AI feature to your published docs by default.
499
+
500
+ Publishing is separate from authoring, and **you can deploy a project for free
501
+ on Doxbrix**. Paid plans are optional and add higher limits and additional
502
+ platform features. You can also build your documentation with a supported
503
+ external generator and deploy its static output to your preferred hosting
504
+ provider.
505
+
506
+ Create a free Doxbrix account at
507
+ [app.doxbrix.com/sign-up](https://app.doxbrix.com/sign-up), then:
508
+
509
+ ```bash
510
+ doxloop login
511
+ doxloop deploy --dry-run
512
+ doxloop deploy
513
+ ```
514
+
515
+ For the native Doxbrix generator, `deploy --dry-run` validates and summarizes the
516
+ documentation bundle. For Docusaurus, MkDocs, Sphinx, Hugo, VitePress, Markdoc,
517
+ Nextra, Starlight, Jekyll, and static HTML, it runs the configured build locally
518
+ and validates/packages the generated static output. `deploy` then creates or
519
+ reuses a compatible Connected Docs project, uploads the checksum-bound artifact,
520
+ and waits for Doxbrix indexing and deployment. Only the documentation bundle or
521
+ generated site is uploaded; configured product source directories are not part
522
+ of the deployment.
523
+
524
+ Doxloop never installs dependencies during deploy. Install them first and make
525
+ sure the generator build works locally. Only the generator's declared output
526
+ directory is traversed (product source directories are not collected separately),
527
+ Doxloop credentials are removed from the build environment, source maps are omitted,
528
+ and likely secret files or symbolic links stop deployment.
529
+
530
+ ## Command reference
531
+
532
+ | Command | Purpose |
533
+ | --- | --- |
534
+ | `doxloop init` | Create a documentation project |
535
+ | `doxloop create` | Research the product and generate documentation |
536
+ | `doxloop update` | Update documentation after product changes |
537
+ | `doxloop review` | Run a read-only professional quality review |
538
+ | `doxloop status` | Summarize the project and validation state |
539
+ | `doxloop test` | Validate documentation |
540
+ | `doxloop preview` | Start the local documentation preview |
541
+ | `doxloop capture` | Capture design-reference screenshots and styles |
542
+ | `doxloop agent` | Manage project-local authoring skills |
543
+ | `doxloop generator` | Manage generator packages |
544
+ | `doxloop login` | Sign in to Doxbrix |
545
+ | `doxloop logout` | Remove the local Doxbrix token |
546
+ | `doxloop whoami` | Show the current Doxbrix account |
547
+ | `doxloop deploy` | Publish a native bundle or locally-built static site to Doxbrix |
548
+
549
+ Run `doxloop <command> --help` for complete command options.
550
+
551
+ ## Security
552
+
553
+ - The authoring workflow treats configured product sources as its evidence
554
+ boundary. The coding agent retains the filesystem permissions granted by its
555
+ host; this is a policy boundary rather than an operating-system sandbox.
556
+ - Authoring, validation, preview, and design-reference capture run locally.
557
+ - The authoring workflow prohibits reading credential files or publishing as
558
+ part of documentation creation.
559
+ - Source files and external pages are treated as untrusted evidence rather than
560
+ instructions.
561
+ - Documentation content directories must remain inside the project and cannot
562
+ contain symbolic links.
563
+ - Deployment is restricted to documentation pages, permitted media, and the
564
+ selected generator's manifest.
565
+ - Doxbrix credentials are stored in the user's configuration directory with
566
+ user-only permissions where the operating system supports them.
567
+ - Deployment uploads only the native documentation bundle or the selected
568
+ external generator's validated static output. It does not upload configured
569
+ product source directories.
570
+
571
+ ## License
572
+
573
+ [Doxloop Proprietary Software License](./LICENSE). You may download, install,
574
+ and run unmodified copies for lawful personal or commercial purposes. Copying,
575
+ modification, incorporation into other products, and redistribution are not
576
+ permitted without explicit written permission from Doxbrix.