@doxbrix/doxloop-generator-markdoc 0.1.0

package/LICENSE

@@ -0,0 +1,93 @@
+DOXLOOP PROPRIETARY SOFTWARE LICENSE
+Version 1.0, 21 July 2026
+
+Copyright (c) 2026 Doxbrix. All rights reserved.
+
+1. Definitions
+
+"Software" means the Doxloop software and all source code, object code,
+documentation, assets, and other materials distributed with this license.
+
+2. Limited License to Use
+
+Subject to your compliance with this license, Doxbrix grants you a worldwide,
+royalty-free, non-exclusive, non-transferable, and non-sublicensable license to
+download, install, and run unmodified copies of the Software for any lawful
+personal or commercial purpose.
+
+You may make only the copies technically necessary to download, install, run,
+and back up the Software. No other rights are granted.
+
+3. Restrictions
+
+Unless you first obtain explicit written permission from Doxbrix, you may not:
+
+a. copy or reproduce the Software except as expressly permitted in Section 2;
+b. modify, adapt, translate, or create derivative works of the Software;
+c. distribute, publish, sublicense, sell, rent, lease, transfer, mirror,
+   repackage, or otherwise make the Software or any part of it available to
+   another person or entity;
+d. incorporate any source code from the Software into another work, product,
+   or service;
+e. remove, alter, or obscure any copyright, license, attribution, or other
+   proprietary notice; or
+f. reverse engineer, decompile, or disassemble the Software, except to the
+   limited extent that applicable law expressly permits despite this
+   restriction.
+
+For clarity, prohibited redistribution includes publishing a copy or fork of
+the source code outside the rights that GitHub's Terms of Service require for a
+public repository, and republishing any Doxloop package or a modified version
+of it to a package registry.
+
+4. GitHub Public Repository Rights
+
+If the Software is made available in a public repository on GitHub, GitHub and
+GitHub users receive the limited rights required by GitHub's applicable Terms
+of Service, including rights to view and fork the repository through GitHub's
+service. Those platform rights do not grant permission to use, copy, modify, or
+redistribute the Software beyond GitHub's service or beyond the permissions in
+Section 2.
+
+5. Ownership and Reservation of Rights
+
+The Software is licensed, not sold. Doxbrix and its licensors retain all
+right, title, and interest in and to the Software. All rights not expressly
+granted by this license are reserved. No patent, trademark, or other license is
+granted by implication or estoppel.
+
+6. Third-Party Materials
+
+Third-party software and materials included with or used by the Software remain
+subject to their respective licenses. This license does not restrict any rights
+granted under those third-party licenses.
+
+7. Termination
+
+This license terminates automatically if you violate any of its terms. Upon
+termination, you must stop using the Software and delete all copies in your
+possession or control, except copies that applicable law requires you to keep.
+
+8. Disclaimer of Warranty
+
+THE SOFTWARE IS PROVIDED "AS IS" AND "AS AVAILABLE," WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE, AND NON-INFRINGEMENT.
+
+9. Limitation of Liability
+
+TO THE MAXIMUM EXTENT PERMITTED BY LAW, DOXBRIX AND ITS LICENSORS WILL NOT BE
+LIABLE FOR ANY INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL, EXEMPLARY, OR
+PUNITIVE DAMAGES, OR FOR ANY LOSS OF DATA, PROFITS, REVENUE, BUSINESS, OR
+GOODWILL, ARISING FROM OR RELATED TO THE SOFTWARE OR THIS LICENSE, REGARDLESS OF
+THE THEORY OF LIABILITY AND EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
+
+10. Severability
+
+If any provision of this license is held unenforceable, that provision will be
+enforced to the maximum extent permitted and the remaining provisions will
+remain in effect.
+
+Use of the Software indicates acceptance of this license. For permissions not
+granted here, contact Doxbrix and obtain explicit written permission before
+proceeding.

package/README.md

@@ -0,0 +1,64 @@
+# @doxbrix/doxloop-generator-markdoc
+
+Markdoc support for [Doxloop](https://github.com/doxbrix/doxloop). This package
+connects Doxloop to a native Markdoc documentation project and includes the
+`doxloop-markdoc` authoring skill used by supported coding agents.
+
+## Install
+
+Install the Doxloop CLI and this generator in your documentation project:
+
+```bash
+npm install --save-dev \
+  @doxbrix/doxloop \
+  @doxbrix/doxloop-generator-markdoc
+```
+
+Node.js 20.12 or later is required.
+
+## Create documentation
+
+Initialize a Markdoc documentation project and connect the product source that
+Doxloop should research:
+
+```bash
+npx doxloop init . \
+  --source product=../my-product \
+  --generator markdoc
+
+npx doxloop create
+```
+
+Doxloop scaffolds Markdoc configuration, content, generator-native navigation,
+and the project-local authoring skill.
+
+## Use with an existing project
+
+Install Markdoc support in an existing Doxloop project with:
+
+```bash
+npx doxloop generator add markdoc
+```
+
+Adding the package does not convert existing content or change the generator
+selected in `.doxloop/project.json`.
+
+## Preview and verify
+
+```bash
+npx doxloop preview --open
+npx doxloop test
+npm run build
+```
+
+| Detail | Value |
+| --- | --- |
+| Content | Markdoc (`.md`) |
+| Native build | `npm run build` |
+| Build output | `dist/` |
+
+Run `npx doxloop generator info markdoc` to inspect the installed adapter.
+
+## License
+
+[Doxloop Proprietary Software License](./LICENSE)

package/dist/index.d.ts

@@ -0,0 +1,31 @@
+import { type GeneratorPreviewOptions, type GeneratorScaffoldContext, type GeneratorValidationContext, type ValidationIssue } from '@doxbrix/doxloop/generator-api';
+declare const adapter: {
+    apiVersion: 1;
+    id: string;
+    displayName: string;
+    packageName: string;
+    packageVersion: string;
+    authoring: {
+        skillName: string;
+        skillDirectory: string;
+    };
+    project: {
+        defaultContentDir: string;
+        pageExtensions: string[];
+        gitignore: string[];
+        contentFormat: "markdown";
+    };
+    build: {
+        command: string;
+        outputDir: string;
+    };
+    scaffold: typeof scaffoldMarkdoc;
+    preview: typeof startMarkdocPreview;
+    resolveLocalAsset({ root, reference }: import("@doxbrix/doxloop/generator-api").GeneratorAssetContext): string | undefined;
+    validate: typeof validateMarkdoc;
+};
+export default adapter;
+declare function scaffoldMarkdoc(context: GeneratorScaffoldContext): Promise<void>;
+declare function startMarkdocPreview(options: GeneratorPreviewOptions): Promise<void>;
+declare function validateMarkdoc(context: GeneratorValidationContext): Promise<ValidationIssue[]>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,OAAO,EAGL,KAAK,uBAAuB,EAC5B,KAAK,wBAAwB,EAC7B,KAAK,0BAA0B,EAC/B,KAAK,eAAe,EACrB,MAAM,gCAAgC,CAAA;AAoBvC,QAAA,MAAM,OAAO;;;;;;;;;;;;;;;;;;;;;;;;CA2BX,CAAA;AAEF,eAAe,OAAO,CAAA;AAEtB,iBAAe,eAAe,CAAC,OAAO,EAAE,wBAAwB,GAAG,OAAO,CAAC,IAAI,CAAC,CAyJ/E;AAED,iBAAe,mBAAmB,CAAC,OAAO,EAAE,uBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC,CASlF;AAED,iBAAe,eAAe,CAC5B,OAAO,EAAE,0BAA0B,GAClC,OAAO,CAAC,eAAe,EAAE,CAAC,CA0E5B"}

package/dist/index.js

@@ -0,0 +1,257 @@
+import { readFileSync } from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { DoxloopError, defineGenerator, } from '@doxbrix/doxloop/generator-api';
+import { ensureNodeModule, isRecord, pathExists, readPackageJson, resolvePublicAsset, runCommand, serveStaticDirectory, slugFromTitle, writeJsonFile, } from '@doxbrix/doxloop/generator-runtime';
+const PACKAGE_NAME = '@doxbrix/doxloop-generator-markdoc';
+const PACKAGE_VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+const adapter = defineGenerator({
+    apiVersion: 1,
+    id: 'markdoc',
+    displayName: 'Markdoc',
+    packageName: PACKAGE_NAME,
+    packageVersion: PACKAGE_VERSION,
+    authoring: {
+        skillName: 'doxloop-markdoc',
+        skillDirectory: fileURLToPath(new URL('../skills/doxloop-markdoc', import.meta.url)),
+    },
+    project: {
+        defaultContentDir: 'docs',
+        pageExtensions: ['.md'],
+        gitignore: ['dist/', 'node_modules/'],
+        contentFormat: 'markdown',
+    },
+    build: { command: 'npm run build', outputDir: 'dist' },
+    scaffold: scaffoldMarkdoc,
+    preview: startMarkdocPreview,
+    resolveLocalAsset({ root, reference }) {
+        return reference.startsWith('/assets/')
+            ? resolvePublicAsset(root, 'assets', reference.slice('/assets'.length))
+            : undefined;
+    },
+    validate: validateMarkdoc,
+});
+export default adapter;
+async function scaffoldMarkdoc(context) {
+    const { root, title, contentDir } = context;
+    await mkdir(join(root, contentDir), { recursive: true });
+    await mkdir(join(root, 'scripts'), { recursive: true });
+    await mkdir(join(root, 'assets'), { recursive: true });
+    await mkdir(join(root, 'assets', 'guides'), { recursive: true });
+    const existing = await readPackageJson(root);
+    await writeJsonFile(join(root, 'package.json'), {
+        ...existing,
+        name: typeof existing.name === 'string' && existing.name
+            ? existing.name
+            : slugFromTitle(title),
+        private: true,
+        version: typeof existing.version === 'string' && existing.version
+            ? existing.version
+            : '0.0.0',
+        type: 'module',
+        scripts: {
+            ...(isRecord(existing.scripts) ? existing.scripts : {}),
+            dev: 'doxloop preview',
+            build: 'node scripts/build.mjs',
+            'docs:test': 'doxloop test',
+        },
+        dependencies: {
+            ...(isRecord(existing.dependencies) ? existing.dependencies : {}),
+            '@markdoc/markdoc': '0.5.8',
+            'gray-matter': '4.0.3',
+        },
+        devDependencies: {
+            ...(isRecord(existing.devDependencies) ? existing.devDependencies : {}),
+            [context.corePackage.name]: `^${context.corePackage.version}`,
+            [context.generatorPackage.name]: `^${context.generatorPackage.version}`,
+        },
+        engines: {
+            ...(isRecord(existing.engines) ? existing.engines : {}),
+            node: '>=20.12.0',
+        },
+    });
+    await writeFile(join(root, 'markdoc.config.mjs'), `export default {
+  tags: {
+    callout: {
+      render: 'aside',
+      attributes: {
+        title: { type: String },
+      },
+    },
+  },
+}
+`, { encoding: 'utf8', flag: 'wx' });
+    await writeJsonFile(join(root, 'navigation.json'), [
+        { title: title, file: 'index.md', href: '/' },
+        { title: 'Quickstart', file: 'quickstart.md', href: '/quickstart/' },
+    ]);
+    await writeFile(join(root, 'assets', 'site.css'), `:root { font-family: Inter, system-ui, sans-serif; --brand: #4f46e5; color: #1f2937; }
+body { margin: 0; } header { border-bottom: 1px solid #e5e7eb; padding: 1rem 2rem; }
+.brand { color: var(--brand); font-weight: 700; text-decoration: none; }
+.markdoc-layout { display: grid; grid-template-columns: 16rem minmax(0, 48rem); gap: 3rem; max-width: 72rem; margin: 0 auto; padding: 2rem; }
+nav ul { list-style: none; padding: 0; } nav a { display: block; padding: .5rem; }
+.markdoc-content { line-height: 1.7; min-width: 0; } aside { border-left: 4px solid var(--brand); padding: 1rem; background: #eef2ff; }
+pre { overflow: auto; padding: 1rem; background: #111827; color: #f9fafb; border-radius: .5rem; }
+@media (max-width: 720px) { .markdoc-layout { grid-template-columns: 1fr; } }
+`, { encoding: 'utf8', flag: 'wx' });
+    await writeFile(join(root, 'scripts', 'build.mjs'), `import { cp, mkdir, readFile, rm, writeFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import Markdoc from '@markdoc/markdoc'
+import matter from 'gray-matter'
+import config from '../markdoc.config.mjs'
+
+const root = process.cwd()
+const navigation = JSON.parse(await readFile(join(root, 'navigation.json'), 'utf8'))
+const output = join(root, 'dist')
+await rm(output, { recursive: true, force: true })
+await mkdir(output, { recursive: true })
+
+const escapeHtml = (value) => String(value).replace(/[&<>"']/g, (character) => ({
+  '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;',
+})[character])
+
+for (const item of navigation) {
+  const sourcePath = join(root, ${JSON.stringify(contentDir)}, item.file)
+  const parsed = matter(await readFile(sourcePath, 'utf8'))
+  const ast = Markdoc.parse(parsed.content)
+  const errors = Markdoc.validate(ast, config)
+  if (errors.length > 0) {
+    throw new Error(\`\${item.file}: \${errors.map((error) => error.error?.message ?? error.type).join(', ')}\`)
+  }
+  const rendered = Markdoc.renderers.html(Markdoc.transform(ast, config))
+  const target = item.href === '/' ? join(output, 'index.html') : join(output, item.href, 'index.html')
+  await mkdir(dirname(target), { recursive: true })
+  const nav = navigation.map((entry) => \`<li><a href="\${entry.href}">\${escapeHtml(entry.title)}</a></li>\`).join('')
+  const title = parsed.data.title ?? item.title
+  const description = parsed.data.description ?? ''
+  await writeFile(target, \`<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="description" content="\${escapeHtml(description)}"><title>\${escapeHtml(title)}</title><link rel="stylesheet" href="/site.css"></head>
+<body><header><a class="brand" href="/">${escapeForTemplate(title)}</a></header><div class="markdoc-layout">
+<aside class="markdoc-sidebar"><nav aria-label="Documentation"><ul>\${nav}</ul></nav></aside>
+<main class="markdoc-content"><article>\${rendered}</article></main></div></body></html>\`)
+}
+await cp(join(root, 'assets', 'site.css'), join(output, 'site.css'))
+await cp(join(root, 'assets', 'guides'), join(output, 'assets', 'guides'), { recursive: true })
+console.log(\`Built \${navigation.length} Markdoc pages in dist/\`)
+`, { encoding: 'utf8', flag: 'wx' });
+    await writeFile(join(root, contentDir, 'index.md'), `---
+title: ${JSON.stringify(title)}
+description: "Understand what ${title} helps you accomplish and choose your first workflow."
+---
+
+# ${title}
+
+<!-- doxloop:starter-page -->
+
+{% callout title="Starter content" %}
+The authoring agent will replace this starter with an evidence-backed product overview.
+{% /callout %}
+
+[Follow the quickstart](/quickstart/) to reach your first successful result.
+`, { encoding: 'utf8', flag: 'wx' });
+    await writeFile(join(root, contentDir, 'quickstart.md'), `---
+title: "Quickstart"
+description: "Reach your first successful result with verified product instructions."
+---
+
+# Quickstart
+
+<!-- doxloop:starter-page -->
+
+1. Confirm prerequisites from the configured product source.
+2. Complete the first supported workflow.
+3. Verify the observable result.
+`, { encoding: 'utf8', flag: 'wx' });
+}
+async function startMarkdocPreview(options) {
+    await ensureNodeModule(options.root, '@markdoc/markdoc/package.json', 'Markdoc');
+    const code = await runCommand(process.execPath, [join(options.root, 'scripts', 'build.mjs')], options.root);
+    if (code !== 0)
+        throw new DoxloopError('Markdoc build failed.', 2);
+    await serveStaticDirectory(options, 'dist', 'Markdoc');
+}
+async function validateMarkdoc(context) {
+    const issues = [];
+    for (const file of [
+        'package.json',
+        'markdoc.config.mjs',
+        'navigation.json',
+        'scripts/build.mjs',
+    ]) {
+        if (!(await pathExists(join(context.root, file)))) {
+            issues.push({
+                severity: 'error',
+                code: 'missing-generator-file',
+                message: `Markdoc project is missing ${file}.`,
+                file,
+            });
+        }
+    }
+    const navigationPath = join(context.root, 'navigation.json');
+    if (!(await pathExists(navigationPath)))
+        return issues;
+    let navigation;
+    try {
+        navigation = JSON.parse(await readFile(navigationPath, 'utf8'));
+    }
+    catch (error) {
+        return [
+            ...issues,
+            {
+                severity: 'error',
+                code: 'generator-config',
+                message: `Cannot parse navigation.json: ${errorMessage(error)}`,
+                file: 'navigation.json',
+            },
+        ];
+    }
+    if (!Array.isArray(navigation)) {
+        issues.push({
+            severity: 'error',
+            code: 'generator-config',
+            message: 'navigation.json must contain an array.',
+            file: 'navigation.json',
+        });
+        return issues;
+    }
+    const navigationFiles = new Set(navigation
+        .filter(isRecord)
+        .map((item) => item.file)
+        .filter((file) => typeof file === 'string'));
+    const pageFiles = new Set(context.pages.map((page) => relative(context.contentRoot, page).split('\\').join('/')));
+    for (const file of navigationFiles) {
+        if (!pageFiles.has(file)) {
+            issues.push({
+                severity: 'error',
+                code: 'missing-page',
+                message: `Markdoc navigation references missing page "${file}".`,
+                file: 'navigation.json',
+            });
+        }
+    }
+    for (const file of pageFiles) {
+        if (!navigationFiles.has(file)) {
+            issues.push({
+                severity: 'error',
+                code: 'unnavigated-page',
+                message: `Page "${file}" is not in Markdoc navigation.`,
+                file,
+            });
+        }
+    }
+    return issues;
+}
+function escapeForTemplate(value) {
+    return value
+        .replaceAll('&', '&amp;')
+        .replaceAll('<', '&lt;')
+        .replaceAll('>', '&gt;')
+        .replaceAll('"', '&quot;')
+        .replaceAll("'", '&#39;');
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@doxbrix/doxloop-generator-markdoc",
+  "version": "0.1.0",
+  "description": "Markdoc generator adapter and authoring skill for Doxloop.",
+  "type": "module",
+  "license": "SEE LICENSE IN LICENSE",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/doxbrix/doxloop.git",
+    "directory": "packages/generator-markdoc"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "skills"
+  ],
+  "doxloop": {
+    "type": "generator",
+    "apiVersion": 1,
+    "id": "markdoc",
+    "skill": "./skills/doxloop-markdoc"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@doxbrix/doxloop": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.3",
+    "typescript": "^5.8.3",
+    "@doxbrix/doxloop": "0.1.0"
+  },
+  "engines": {
+    "node": ">=20.12.0"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.json",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "validate:skill": "python3 ../../scripts/validate-skill.py skills/doxloop-markdoc"
+  }
+}

package/skills/doxloop-markdoc/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: doxloop-markdoc
+description: Author and maintain native Markdoc documentation, including Markdown, Markdoc tags, schemas, navigation metadata, renderer-safe content, and static output. Use for Doxloop projects whose generator is markdoc.
+---
+
+# Doxloop Markdoc
+
+Use this skill with `$doxloop-authoring`. Use only tags, nodes, and schemas
+registered by the Markdoc project.
+
+## Work natively
+
+1. Confirm `.doxloop/project.json` selects `markdoc`.
+2. Read [references/project-format.md](references/project-format.md).
+3. Inspect `markdoc.config.mjs`, `navigation.json`, the renderer, and existing
+   pages.
+4. Keep pages in `docs/` with `title` and outcome-focused `description`.
+5. Maintain navigation and stable routes when pages change.
+
+Implement the semantic top/left navigation plan from `$doxloop-authoring` in
+`navigation.json` and the renderer's supported header and sidebar structures.
+Preserve planned labels, order, hierarchy, and routes; omit empty template
+groups and verify every page is reachable exactly once.
+
+Prefer CommonMark unless a registered tag adds meaningful semantics. Never
+invent a tag without defining and testing its schema and renderer. Preserve the
+parse, validate, transform, and render pipeline. Map branding through renderer
+templates and shared CSS, not page-specific inline presentation.
+
+## Verify
+
+Run `doxloop test`, then `npm run build`. Treat Markdoc validation diagnostics,
+unknown tags, invalid attributes, unsafe rendered HTML, missing navigation, and
+broken routes as failures. Inspect representative output with
+`doxloop preview --open`.
+
+Do not emit JSX, generator-specific directives, or edit `dist/`.

package/skills/doxloop-markdoc/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Markdoc"
+  short_description: "Author and maintain native Markdoc documentation"
+  default_prompt: "Use $doxloop-markdoc to author documentation using the native Markdoc project format."

package/skills/doxloop-markdoc/references/project-format.md

@@ -0,0 +1,35 @@
+# Markdoc project format
+
+- Content root: `docs/`
+- Schema/configuration: `markdoc.config.mjs`
+- Navigation and routes: `navigation.json`
+- Static renderer: `scripts/build.mjs`
+- Required frontmatter: `title` and `description`
+- Custom syntax: `{% tag attribute="value" %}...{% /tag %}`
+- Use only tags registered in `markdoc.config.mjs`.
+- Preserve `parse` → `validate` → `transform` → `renderers.html`.
+- Build: `npm run build`; output: `dist/`
+
+## Navigation and routes
+
+- Keep every reader page in `navigation.json` exactly once.
+- Preserve explicit route identifiers when reorganizing labels or groups.
+- Validate navigation targets against source files before building.
+
+## Tags and rendering
+
+- Define attributes, types, defaults, required values, and child constraints in
+  `markdoc.config.mjs`.
+- Prefer transform-safe data over raw HTML.
+- Escape content in custom renderers and preserve semantic HTML.
+- Keep theme tokens and layouts in renderer-owned assets.
+- Put committed guide screenshots under `assets/guides/<guide>/`, reference
+  them as `/assets/guides/<guide>/<image>.png`, and preserve the scaffolded
+  build copy step that publishes them.
+
+## Common failures
+
+- Unknown tags may parse but fail validation.
+- Attribute expressions can produce unexpected types after transformation.
+- Rendering without validation can publish malformed or unsafe output.
+- `dist/` is generated and never a source of documentation truth.