@doxbrix/doxloop 0.1.0

package/docs/doxbrix-http-api.md

@@ -0,0 +1,182 @@
+# Doxbrix HTTP API used by Doxloop
+
+This document is the integration boundary between the public Doxloop CLI and
+the Doxbrix platform. Doxloop calls these endpoints directly and does not
+depend on server source code or a server-side SDK.
+
+The default base URL is `https://app.doxbrix.com`. It can be replaced with
+`DOXLOOP_API_URL` or `--api-url`. All requests and responses use JSON.
+Authenticated requests send `Authorization: Bearer dxb_…` with a Doxbrix
+Personal Access Token. Redirects are refused so bearer credentials are never
+forwarded to another destination. Alternate API URLs must use HTTPS; HTTP is
+accepted only for loopback development.
+
+## Device authorization
+
+Start authorization:
+
+```http
+POST /api/v1/auth/device/start
+Content-Type: application/json
+
+{"name":"doxloop @ hostname","scopes":["docs:read","docs:write","project:read","project:admin"]}
+```
+
+Successful response:
+
+```json
+{
+  "deviceCode": "opaque-device-code",
+  "userCode": "ABCD-EFGH",
+  "verificationUri": "https://app.doxbrix.com/activate",
+  "expiresIn": 600,
+  "interval": 5
+}
+```
+
+Poll for completion:
+
+```http
+POST /api/v1/auth/device/poll
+Content-Type: application/json
+
+{"deviceCode":"opaque-device-code"}
+```
+
+The response is one of:
+
+```json
+{"status":"pending"}
+{"status":"approved","token":"dxb_opaque-access-token"}
+{"status":"expired"}
+```
+
+Tokens can also be created manually in the Doxbrix web app and passed with
+`doxloop login --token dxb_…` or the `DOXLOOP_TOKEN`/`DOXBRIX_TOKEN`
+environment variables. Doxloop verifies a token against `/api/v1/me` before
+storing it. Prefer the device flow or environment variables so a token does not
+remain in shell history.
+
+## Current account
+
+```http
+GET /api/v1/me
+Authorization: Bearer dxb_…
+```
+
+Response:
+
+```json
+{"id":"account-id","email":"user@example.com","name":"Example User"}
+```
+
+`name` may be `null`.
+
+## Projects
+
+Fetch a project by id or slug (`404` when it does not exist):
+
+```http
+GET /api/v1/projects/{idOrSlug}
+Authorization: Bearer dxb_…
+```
+
+```json
+{"project":{"id":"project-id","name":"Example documentation","slug":"example-documentation"}}
+```
+
+Create a project:
+
+```http
+POST /api/v1/projects
+Authorization: Bearer dxb_…
+Content-Type: application/json
+
+{"name":"Example documentation","slug":"example-documentation","seedTemplate":false}
+```
+
+The response uses the same `{"project":{…}}` envelope. API-created projects
+default to `seedTemplate: false` so the following bundle is their only
+documentation structure. Pass `true` only when the Doxbrix web starter spaces
+and pages are wanted.
+
+## Push a documentation bundle
+
+```http
+POST /api/v1/projects/{idOrSlug}/bundle
+Authorization: Bearer dxb_…
+Content-Type: application/json
+```
+
+The request body is:
+
+```json
+{
+  "manifest": { "version": 1, "spaces": [] },
+  "basePath": "docs",
+  "pages": [
+    {"path": "index.mdx", "markdown": "---\ntitle: Welcome\n---\n\n# Welcome"}
+  ],
+  "media": [
+    {"path": "assets/logo.svg", "base64": "…"}
+  ],
+  "publish": true
+}
+```
+
+`manifest` is the parsed `docs.json` object. Page and media paths are relative
+to the documentation directory. Media content is base64-encoded. The server
+converts markdown to blocks and materializes spaces, navigation, and pages.
+Only the manifest and files under the configured documentation directory may
+be represented in the payload; configured product-source directories must
+never be included.
+
+This endpoint is the native Doxbrix generator boundary. Do not send external
+generator output to it; use the artifact deployment API below.
+
+Successful response:
+
+```json
+{
+  "result": {
+    "spaces": 1,
+    "pagesCreated": 2,
+    "pagesUpdated": 0,
+    "navItems": 3,
+    "warnings": []
+  },
+  "dryRun": false
+}
+```
+
+## Deploy a locally-built static artifact
+
+Create the project with its producing generator:
+
+```json
+{
+  "name": "Example documentation",
+  "slug": "example-documentation",
+  "connectedArtifact": { "generator": "docusaurus" }
+}
+```
+
+Reserve an upload by sending the ZIP byte length and lowercase/uppercase SHA-256
+hex digest to `POST /api/v1/projects/{idOrSlug}/deployments`. PUT the exact ZIP
+bytes to the returned `deployment.upload.url` with every returned header, then
+call `POST /api/v1/projects/{idOrSlug}/deployments/{buildId}/complete`.
+Doxbrix rejects missing, expired, size-mismatched, or checksum-mismatched objects.
+
+Poll `GET /api/v1/projects/{idOrSlug}/deployments/{buildId}` until `status` is
+`ready` or `failed`. A ready response includes `hostedUrl`, file/page counts, and
+the generator retained for finalization.
+
+## Errors
+
+Error responses use:
+
+```json
+{"error":{"code":"machine-readable-code","message":"Human-readable message"}}
+```
+
+Doxloop also accepts `{"error":"message"}` and `{"message":"message"}` shapes.

package/docs/generator-authoring.md

@@ -0,0 +1,59 @@
+# Author a generator package
+
+A generator package connects Doxloop's shared authoring workflow to one native
+documentation framework.
+
+## Package contract
+
+Export a default adapter created with `defineGenerator` from
+`@doxbrix/doxloop/generator-api`. The adapter declares:
+
+- generator API version and stable ID;
+- package identity and version;
+- authoring skill name and directory;
+- content root, page extensions, ignored output, and content format;
+- native build command and output directory;
+- scaffold, preview, and validation implementations;
+- an optional local-asset resolver for root-relative public assets outside the
+  content directory; and
+- an optional page reader for non-Markdown formats.
+
+Package metadata should include:
+
+```json
+{
+  "doxloop": {
+    "type": "generator",
+    "apiVersion": 1,
+    "id": "example",
+    "skill": "./skills/doxloop-example"
+  }
+}
+```
+
+## Responsibilities
+
+Scaffolding creates a minimal native project with explicit starter markers that
+must fail release validation until authoring replaces them. Preview runs the
+native development workflow without editing generated output. Validation checks
+native navigation, configuration, metadata, routes, and conventions; shared
+validation checks professional content, local links, placeholders, and secrets.
+
+The format skill must use `$doxloop-authoring`, route all reader pages through
+native navigation, document native components and theme mapping, identify
+generated directories, and require both `doxloop test` and the strict native
+build. It must also document how committed application guide screenshots reach
+the built site: the native source directory, public or base-aware URL, caption
+or figure syntax, and any required build-copy step. Guide screenshots must not
+use `.doxloop/cache/reference/`, which is reserved for ignored external
+design-reference evidence.
+
+## Compatibility and testing
+
+Increment `GENERATOR_API_VERSION` only for breaking adapter changes. Generator
+packages declare a compatible core peer dependency and are published after the
+matching core version.
+
+Tests should scaffold, load, validate, install the format skill, build, and
+exercise preview failure behavior. Skill validation checks frontmatter,
+metadata, local reference links, shared-skill delegation, and generator routing.

package/docs/generator-selection.md

@@ -0,0 +1,25 @@
+# Select a documentation generator
+
+Choose the generator when initializing a project. Doxbrix is built in; external
+generators require their package in the new project.
+
+Use Doxbrix for native Doxbrix publishing and interactive API endpoint blocks.
+Choose another generator when an existing toolchain, extension ecosystem, or
+static-hosting requirement is more important.
+
+`doxloop generator add <name>` installs support; it does not rewrite the project
+or convert existing content. Doxloop currently has no automatic generator
+migration because navigation, frontmatter, components, themes, and route rules
+are not mechanically equivalent.
+
+To migrate:
+
+1. Create a new project with the target generator.
+2. Copy the confirmed documentation brief and source bindings.
+3. Ask `doxloop create` to preserve the agreed coverage while translating
+   content into the target generator's native format.
+4. Compare routes, navigation, metadata, components, and theme behavior.
+5. Run `doxloop test` and the target generator's strict build.
+6. Redirect changed public URLs before replacing the existing site.
+
+Keep the original project until the new site passes validation and route review.

package/docs/project-format.md

@@ -0,0 +1,97 @@
+# Doxloop project format
+
+Doxloop stores project configuration under `.doxloop/`. Commit the configuration
+and synchronization state when a team should share the same authoring decisions.
+
+Create a new documentation project beside, never inside, the product source:
+
+```bash
+doxloop create --source ./my-product --output ./my-docs
+```
+
+## `project.json`
+
+```json
+{
+  "schemaVersion": 1,
+  "title": "Example documentation",
+  "contentDir": "docs",
+  "generator": "doxbrix",
+  "sources": [{ "name": "product", "path": "../product" }],
+  "designReferences": [{ "url": "https://docs.example.com/" }],
+  "application": {
+    "baseUrl": "http://localhost:3000/",
+    "source": "product",
+    "startCommand": "npm run dev",
+    "readyPath": "/health",
+    "screenshots": {
+      "policy": "requested",
+      "viewport": { "width": 1440, "height": 900 },
+      "highlight": true
+    }
+  },
+  "documentation": {
+    "primaryAudience": "Application developers",
+    "experienceLevel": "intermediate",
+    "priorityOutcomes": ["Install the SDK", "Send the first request"],
+    "locale": "en-US",
+    "tone": ["clear", "direct", "professional"],
+    "standardsProfile": "doxloop-v1",
+    "styleGuide": "doxloop",
+    "terminology": {},
+    "exclusions": [],
+    "accessibilityTarget": "WCAG 2.2 AA"
+  }
+}
+```
+
+- `contentDir` must be a non-symlinked relative directory inside the project.
+- `sources` is the optional read-only evidence allowlist used by the authoring
+  workflow. It may be empty when no local product source is available. Configured
+  source paths must be outside the documentation project; sibling product and
+  documentation directories are the recommended layout.
+- `generatorPackage` is required for an external generator and must match the
+  official package selected by `generator`.
+- `designReferences` accept absolute HTTP or HTTPS URLs without credentials.
+- `application` is optional and describes a safe local or test application
+  surface for guide screenshots. `source` names a configured source and is
+  required when `startCommand` is present. Screenshot policy is `requested`,
+  `auto`, or `off`; projects without this object keep the existing behavior.
+- `documentation` persists confirmed reader, scope, terminology, editorial, and
+  accessibility decisions.
+
+Schema version 1 treats a missing legacy `generator` as `doxbrix` and supplies
+the default documentation brief when it is absent. Unsupported structures fail
+closed rather than being silently migrated.
+
+## `sync-state.json`
+
+Each Git source records the commit, timestamp, and a fingerprint of tracked and
+untracked non-ignored, non-credential source content used by the last successful
+authoring run. The fingerprint prevents an unchanged dirty working tree from
+being reported again after its content is committed.
+
+Doxloop updates synchronization state only when create or update exits
+successfully, documentation validation passes, and create has saved a primary
+audience and priority outcomes.
+
+## `last-run.json`
+
+After a successful create or update, Doxloop records the mode, selected agent,
+completion time, validation summary, and synchronized source count. This is an
+ignored operational receipt, not an evidence map or a substitute for version
+control.
+
+## Reference-design evidence
+
+`.doxloop/reference-design.json` is authored by the design-reference workflow.
+Screenshots and raw measurements remain under `.doxloop/cache/` and should not
+be committed.
+
+Application guide screenshots are different: they are reader-facing assets,
+are placed in the selected generator's native asset directory, and should be
+committed with the guide. `doxloop create --screenshots` and
+`doxloop update --screenshots` require them explicitly; a request that clearly asks for
+screenshots also enables the authoring workflow. Contextual focus rings and
+numbered markers are baked into the image so they render consistently across
+generators.

package/docs/security-model.md

@@ -0,0 +1,90 @@
+# Security model
+
+Doxloop separates local authoring from explicit publishing. This document
+describes which guarantees the CLI enforces and which behavior depends on the
+selected coding agent and host environment.
+
+## Trust boundaries
+
+- `.doxloop/project.json`, installed generator packages, configured product
+  sources, and public design references are user-selected inputs.
+- Source text, comments, tests, generated files, command output, and reference
+  pages are evidence, not instructions. The authoring prompt tells agents to
+  ignore embedded requests that change scope, reveal secrets, weaken safeguards,
+  contact unrelated services, or publish.
+- Coding agents retain the filesystem permissions granted by their host. The
+  configured `sources` list is an authoring-policy boundary, not an operating
+  system sandbox.
+- Product sources are read-only evidence. The create and update workflows tell
+  the agent to write only inside the separate documentation project.
+- `doxloop review` launches supported agents in read-only or plan mode.
+  Create and update require write access to the documentation project.
+
+## Local files
+
+The documentation `contentDir` must be a relative directory inside the project.
+Doxloop rejects project-root, escaping, absolute, and symlinked content
+directories. Deployment rejects a content directory that differs from
+`.doxloop/project.json` and refuses symlinks anywhere in documentation content.
+
+The first-run create flow rejects a documentation project that is the same as,
+inside, or contains a configured product source. It also rejects configured
+sources that are missing and non-empty output directories before writing project
+files.
+
+Do not place credentials, private keys, environment files, internal data, or
+product source under the documentation content directory.
+
+## Network access
+
+Authoring and validation do not publish. A coding agent may still have network
+access according to its own configuration.
+
+Design capture:
+
+- accepts only configured HTTP or HTTPS reference origins;
+- captures at most three requested pages per origin;
+- blocks navigation away from the configured origin;
+- blocks loopback, private, link-local, multicast, and other non-public network
+  destinations; and
+- stores screenshots and measurements under the Git-ignored
+  `.doxloop/cache/reference/`.
+
+For a trusted local documentation reference, set
+`DOXLOOP_ALLOW_PRIVATE_REFERENCES=1` for that capture invocation.
+
+Application guide screenshots are separate authoring actions. They run only
+when requested, forced with `--screenshots`, or enabled by the optional
+`application.screenshots.policy`. The authoring workflow limits navigation to
+the configured application surface and requires non-production fixtures or test
+accounts, but the selected coding agent and its browser retain the permissions
+granted by their host. Do not configure a production application, store
+credentials in `.doxloop/project.json`, or expose customer data for capture.
+Use `--no-screenshots` when the authoring environment should not operate an
+application.
+
+Doxbrix API requests require HTTPS. HTTP is accepted only for loopback
+development. Authenticated and device-flow requests refuse redirects.
+
+## Credentials and publishing
+
+Prefer `doxloop login` and the device flow. Environment variables avoid placing
+tokens in shell history; `--token` is intended for controlled automation.
+Stored credentials use user-only file permissions on operating systems that
+support them.
+
+Only `doxloop deploy` publishes. Native projects send a contained documentation
+bundle to the Doxbrix API. External generators are built on the user's machine;
+Doxloop removes its Doxbrix tokens from the child build environment, scans only
+the declared static output, rejects symbolic links/private keys/likely secret
+files, omits source maps, and enforces file and expansion limits before packaging.
+
+The archive is uploaded directly to one short-lived, single-object S3 URL whose
+SHA-256 checksum is signed. Doxbrix verifies the object size and checksum before
+queueing its trusted indexing/infusion pipeline. Generator code never runs in the
+Doxbrix web or finalizer process for this deployment path.
+
+## Reporting vulnerabilities
+
+Follow [the repository security policy](../SECURITY.md). Never put credentials,
+private product source, or unpublished vulnerability details in a public issue.

package/docs/troubleshooting.md

@@ -0,0 +1,103 @@
+# Troubleshoot Doxloop
+
+## Check the complete setup
+
+Inside an existing documentation project, run:
+
+```bash
+doxloop doctor
+```
+
+Before creating a new project, check the proposed sibling directories:
+
+```bash
+doxloop doctor --source ./my-product --output ./my-docs
+```
+
+Doctor checks the Node.js version, product-source boundary, selected agent and
+authentication, project skills, generator readiness, and documentation
+validation, plus the default preview port. It exits with code 1 when a required
+check fails.
+
+## No supported agent is available
+
+Install Codex, Claude Code, or Gemini CLI and confirm its executable is on
+`PATH`. Alternatively:
+
+```bash
+doxloop create --print
+```
+
+Paste the prompt into an agent session opened at the project root.
+
+## An installed skill is modified
+
+Doxloop does not overwrite local skill changes automatically.
+
+```bash
+doxloop agent status
+doxloop agent update
+```
+
+Review the diff before replacing intentional customizations.
+
+## An external generator cannot load
+
+Install both core and the selected generator package in the documentation
+project. Then run:
+
+```bash
+doxloop generator doctor
+```
+
+Native generators may also require Python, Ruby, Hugo, or Node dependencies.
+The doctor output reports the expected build command.
+
+## Create exits but synchronization is not recorded
+
+Doxloop withholds the baseline when validation fails or the create brief lacks
+`primaryAudience` or `priorityOutcomes`. Run `doxloop test`, resolve every
+error, and rerun create or update.
+
+## Capture blocks a URL
+
+Capture rejects unconfigured origins, cross-origin navigation, and private
+network destinations. Add the intended public origin with `--reference`. For a
+trusted local reference only:
+
+```bash
+DOXLOOP_ALLOW_PRIVATE_REFERENCES=1 doxloop capture http://localhost:3000/
+```
+
+## Guide screenshots are missing
+
+Application guide screenshots are created during `doxloop create` or
+`doxloop update`, not by design-reference capture. Ask for screenshots in the
+request or pass `--screenshots`. Configure `application.baseUrl` and, when
+Doxloop should start the application, a configured source name plus
+`startCommand` in `.doxloop/project.json`.
+
+If the selected agent has no browser capability, the application is unreachable,
+or authentication and safe test data are unavailable, Doxloop keeps the text
+guide complete and omits broken image links. Establish a non-production browser
+session or local fixture and rerun the affected update. Never provide production
+credentials or customer data for screenshot capture.
+
+## API requests fail
+
+Confirm the API URL uses HTTPS, the token starts with `dxb_`, and the endpoint
+does not redirect. HTTP is accepted only for loopback development. Prefer
+`doxloop login` to refresh credentials.
+
+## Preview port is occupied
+
+Choose another port:
+
+```bash
+doxloop preview --port 4400 --open
+```
+
+## Validation and native builds disagree
+
+`doxloop test` performs fast project and content checks; the native build is the
+final generator parser. Run both and treat either failure as blocking.

package/package.json

@@ -0,0 +1,87 @@
+{
+  "name": "@doxbrix/doxloop",
+  "version": "0.1.0",
+  "description": "A local-first documentation agent CLI for Codex, Claude Code, and Gemini.",
+  "type": "module",
+  "license": "SEE LICENSE IN LICENSE",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/doxbrix/doxloop.git"
+  },
+  "homepage": "https://github.com/doxbrix/doxloop#readme",
+  "bugs": {
+    "url": "https://github.com/doxbrix/doxloop/issues"
+  },
+  "bin": {
+    "doxloop": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "assets",
+    "docs",
+    "skills/doxloop-authoring",
+    "skills/doxloop-doxbrix",
+    "README.md",
+    "CHANGELOG.md",
+    "SECURITY.md",
+    "LICENSE"
+  ],
+  "exports": {
+    "./generator-api": {
+      "types": "./dist/generator-api.d.ts",
+      "import": "./dist/generator-api.js"
+    },
+    "./generator-runtime": {
+      "types": "./dist/generator-runtime.d.ts",
+      "import": "./dist/generator-runtime.js"
+    }
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "dependencies": {
+    "chokidar": "^4.0.3",
+    "fflate": "^0.8.2",
+    "gray-matter": "^4.0.3",
+    "highlight.js": "^11.11.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.3",
+    "tsx": "^4.19.4",
+    "typescript": "^5.8.3",
+    "vitest": "^3.1.2",
+    "@doxbrix/doxloop-generator-docusaurus": "0.1.0",
+    "@doxbrix/doxloop-generator-hugo": "0.1.0",
+    "@doxbrix/doxloop-generator-jekyll": "0.1.0",
+    "@doxbrix/doxloop-generator-markdoc": "0.1.0",
+    "@doxbrix/doxloop-generator-mkdocs": "0.1.0",
+    "@doxbrix/doxloop-generator-nextra": "0.1.0",
+    "@doxbrix/doxloop-generator-starlight": "0.1.0",
+    "@doxbrix/doxloop-generator-sphinx": "0.1.0",
+    "@doxbrix/doxloop-generator-vitepress": "0.1.0",
+    "@doxbrix/doxloop-generator-static": "0.1.0"
+  },
+  "engines": {
+    "node": ">=20.12.0"
+  },
+  "main": "index.js",
+  "directories": {
+    "doc": "docs"
+  },
+  "keywords": [],
+  "author": "",
+  "scripts": {
+    "build": "pnpm run build:core && pnpm run build:generators",
+    "build:core": "rm -rf dist && tsc -p tsconfig.json && node scripts/prepare-dist.mjs",
+    "build:generators": "pnpm --filter './packages/*' run build",
+    "dev": "tsx src/cli.ts",
+    "typecheck": "tsc --noEmit && pnpm --filter './packages/*' run typecheck",
+    "pretest": "pnpm run build",
+    "test": "vitest run",
+    "eval:agents": "pnpm run build && node scripts/run-authoring-evals.mjs",
+    "check": "pnpm run typecheck && pnpm run test && pnpm run validate:skill && pnpm run check:boundary",
+    "validate:skill": "node scripts/validate-skills.mjs",
+    "check:boundary": "node scripts/check-boundary.mjs"
+  }
+}