@doxbrix/doxloop 0.1.4 → 0.2.0

package/skills/doxloop-doxbrix/references/api-endpoints.md

@@ -6,16 +6,20 @@ grouped parameters, generated request example, and response tabs.
 
 - [Page contract](#page-contract)
 - [Canonical syntax](#canonical-syntax)
-- [Verification](#verification)
+- [Format requirements](#format-requirements)
 
 ## Page contract
 
 - Prefer one endpoint page and one `<ApiEndpoint>` block per operation.
 - Use the page title for the operation name, such as `List projects`.
 - Open with one short sentence describing the observable behavior.
-- Put `method`, `path`, `baseUrl`, `summary`, and `description` on
-  `<ApiEndpoint>`.
-- Add one `<Param>` for every verified path, query, header, or body parameter.
+- Put `method`, `path`, `baseUrl`, and `summary` on `<ApiEndpoint>`. Add
+  `description` when the operation needs more than its summary; the card shows
+  it under the summary and omits it when absent.
+- Add one `<Param>` for every verified path, query, header, or body parameter,
+  with an `example` for each one whose value the evidence shows. Doxloop asks
+  for missing examples once per endpoint, and not at all when the section
+  already shows a verified request (a cURL or HTTP sample naming the path).
 - Add one `<Response>` for the successful status and each important verified
   error status.
 - Keep example values realistic but visibly non-secret.
@@ -87,14 +91,11 @@ Do not use a Markdown parameter table, a prose-only endpoint, or separate cURL
 and response fences in place of `<ApiEndpoint>`. The reader generates the
 request presentation from the block attributes and parameter examples.
 
-## Verification
+## Format requirements
 
-Run `doxloop test`, then inspect the page in `doxloop preview --open`. Confirm:
-
-- every component opening tag, including `<ApiEndpoint>`, `<Param>`, and
-  `<Response>`, ends with `>` on the same physical line where it begins;
-- the method and path appear in the endpoint bar;
-- header, path, and query parameters appear in their proper sections;
-- required and type badges are correct;
-- the request example uses the verified base URL and parameter examples;
-- success and error statuses appear as response tabs with valid example bodies.
+- Every component opening tag, including `<ApiEndpoint>`, `<Param>`, and
+  `<Response>`, ends with `>` on the same physical line where it begins.
+- Every `<Response>` carries a status, a verified `contentType`, and a valid
+  example body; success and each documented error status get their own block.
+- The `baseUrl` and every parameter `example` are the verified values the
+  generated request presentation will show.

package/skills/doxloop-doxbrix/references/components.md

@@ -15,6 +15,29 @@ Run the installer and verify the executable.
 </Steps>
 ```
 
+A `<Step>` renders full block content, so a step's screenshot belongs inside
+that step — never collected after the `<Steps>` block. Put the image directly
+under the instruction it proves:
+
+```mdx
+<Steps>
+<Step title="Open the control center">
+Open the Overview screen at `/`.
+
+<Frame caption="The Overview dashboard lists every workflow stage.">
+![Doxloop Overview showing the documentation workflow](/assets/guides/quickstart/01-overview.png)
+</Frame>
+</Step>
+<Step title="Start an authoring request">
+Select **Update** and describe a reader outcome.
+
+<Frame caption="The Update form captures the reader outcome.">
+![Doxloop Update documentation form](/assets/guides/quickstart/02-update.png)
+</Frame>
+</Step>
+</Steps>
+```
+
 ````mdx
 <CodeGroup>
 ```bash npm
@@ -102,6 +125,12 @@ graph TD; A[Start] --> B[Complete];
 <Math>e = mc^2</Math>
 ```
 
+Diagrams are scaled to the content width, so a wide one becomes unreadably
+small. Keep every level of a `graph TD` to at most three or four nodes; when
+a decision has more outcomes, draw it `graph LR` (it grows downward instead)
+or split it into two diagrams, and keep node labels to a few words. A table
+often reads better than a diagram with six or more branches.
+
 ```mdx
 <ApiEndpoint method="POST" path="/users" baseUrl="https://api.example.com" summary="Create a user">
 <Param name="name" in="body" type="string" required>Display name</Param>
@@ -132,6 +161,4 @@ For standalone API blocks:
 </ResponseExample>
 ```
 
-Never invent a component outside this catalog. After adding a rich component,
-inspect that component in `doxloop preview`; balanced tags alone do not prove
-that its attributes or content are correct.
+Never invent a component outside this catalog.

package/skills/doxloop-doxbrix/references/manifest.md

@@ -1,7 +1,8 @@
 # Doxbrix project format
 
-The canonical manifest is `docs/docs.json` for a Doxloop project whose
-`contentDir` is `docs`.
+The canonical manifest is `docs.json` at the project root for a new native
+Doxbrix project whose `contentDir` is empty. Existing projects with
+`contentDir: "docs"` keep the manifest at `docs/docs.json`.
 
 ```json
 {

package/vendor/doxbrix-import/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/vendor/doxbrix-import/README.md

@@ -0,0 +1,17 @@
+# Doxbrix conversion engine
+
+These SDK conversion modules, CLI file-import helpers, and SDK regression tests
+are copied unchanged from the Doxbrix 0.1.4 source supplied for this integration.
+`UPSTREAM.json` records the source revision and SHA-256 of every copied file.
+The working-tree file hashes identify the exact snapshot, including changes
+that may not have been committed at that revision.
+
+Do not implement a second Mintlify transformer here. Refresh these files together
+from upstream and run both the original regression suite and Doxloop's import
+integration tests. The wrapper in `src/mintlify-import.ts` owns source selection,
+safe remote fetching, staging, reporting, and Doxloop project adoption.
+
+The engine compiles separately with its original optional-property semantics;
+Doxloop consumes the generated JavaScript and declarations. `build:importer`
+runs before core compilation and typechecking. Built files and the Apache-2.0
+license ship with Doxloop; no separately installed CLI or local checkout is needed.

package/vendor/doxbrix-import/UPSTREAM.json

@@ -0,0 +1,47 @@
+{
+  "source": "Doxbrix SDK and CLI conversion modules",
+  "version": "0.1.4",
+  "revision": "93b727c7b5617540498d034f1b2a839d125ad3e5",
+  "files": [
+    {
+      "file": "importer.ts",
+      "sha256": "1b021d6509651e7de48fdeb8e2dcd9866fc1db4c6e27508bb58b14b871a071b0"
+    },
+    {
+      "file": "mintlify-openapi.ts",
+      "sha256": "509902e58f2ca2d9353165f170a0e3af7d624c6310c917530ea253c5e9b244a7"
+    },
+    {
+      "file": "importer.test.ts",
+      "sha256": "b5bd0bff3432516a2832581ed7a0bf31fe86f11eac0546c8aadd814e080c4372"
+    },
+    {
+      "file": "docs/import.ts",
+      "sha256": "65c9101568258a21f73bedd0002627ade2af6aa3d6be924a40e4bff19afadbcd"
+    },
+    {
+      "file": "docs/project.ts",
+      "sha256": "19c7ea839459195c5fa9707728bd540bba4c45b2f19bd69ed7f4032bdf2454ad"
+    },
+    {
+      "file": "docs/frontmatter.ts",
+      "sha256": "dacef357d9d5a4c7ec77f24078ccaa7a99abcb45271118e7066dc0ecf47d5afb"
+    },
+    {
+      "file": "docs/manifest.ts",
+      "sha256": "7d5e4fc0a84550509fb508d00f3dc1353803377b682c061b585925d964ce534f"
+    },
+    {
+      "file": "docs/starter.ts",
+      "sha256": "27a830733e9a87ba2875707322fc48bfd7c3d1de56b433fb667c7176c09fdcb3"
+    },
+    {
+      "file": "safe-path.ts",
+      "sha256": "71570233498d6809db3b1f7399c10621f08393fcbe9f339eb37562ee511a71eb"
+    },
+    {
+      "file": "docs/import.test.ts",
+      "sha256": "a801faf4b98e49b2a2df56810254105e01054f8fa291d7b972f7988c60126115"
+    }
+  ]
+}

package/vendor/doxbrix-import/dist/docs/frontmatter.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Minimal frontmatter reader/writer for the CLI's lint + bundle steps. Handles
+ * the common YAML subset Doxbrix page files use: `key: value`, quoted strings,
+ * booleans, numbers, inline `[a, b]` arrays, and `-` list items. The SERVER
+ * re-parses authoritatively on push (`gitFileToPage`), so this only needs to be
+ * good enough for local validation and display.
+ */
+export interface ParsedFrontmatter {
+    data: Record<string, unknown>;
+    body: string;
+}
+export declare function parseFrontmatter(source: string): ParsedFrontmatter;
+export declare function serializeFrontmatter(data: Record<string, unknown>, body: string): string;

package/vendor/doxbrix-import/dist/docs/frontmatter.js

@@ -0,0 +1,83 @@
+/**
+ * Minimal frontmatter reader/writer for the CLI's lint + bundle steps. Handles
+ * the common YAML subset Doxbrix page files use: `key: value`, quoted strings,
+ * booleans, numbers, inline `[a, b]` arrays, and `-` list items. The SERVER
+ * re-parses authoritatively on push (`gitFileToPage`), so this only needs to be
+ * good enough for local validation and display.
+ */
+const FRONTMATTER_RE = /^?---\r?\n([\s\S]*?)\r?\n---\r?\n?/;
+export function parseFrontmatter(source) {
+    const match = FRONTMATTER_RE.exec(source);
+    if (!match)
+        return { data: {}, body: source.replace(/^/, '') };
+    const data = parseYamlSubset(match[1] ?? '');
+    return { data, body: source.slice(match[0].length) };
+}
+export function serializeFrontmatter(data, body) {
+    const entries = Object.entries(data).filter(([, v]) => v !== undefined && v !== null && v !== '');
+    if (entries.length === 0)
+        return body;
+    const lines = entries.map(([key, value]) => `${key}: ${serializeValue(value)}`);
+    return `---\n${lines.join('\n')}\n---\n${body}`;
+}
+function serializeValue(value) {
+    if (Array.isArray(value))
+        return `[${value.map((v) => serializeScalar(v)).join(', ')}]`;
+    return serializeScalar(value);
+}
+function serializeScalar(value) {
+    if (typeof value === 'boolean' || typeof value === 'number')
+        return String(value);
+    const s = String(value);
+    return /[:#\[\]{}]|^\s|\s$/.test(s) ? JSON.stringify(s) : s;
+}
+function parseYamlSubset(block) {
+    const out = {};
+    const lines = block.split(/\r?\n/);
+    let i = 0;
+    while (i < lines.length) {
+        const line = lines[i];
+        i++;
+        if (!line.trim() || line.trimStart().startsWith('#'))
+            continue;
+        const m = /^([A-Za-z0-9_-]+):\s*(.*)$/.exec(line);
+        if (!m)
+            continue;
+        const key = m[1];
+        const rest = (m[2] ?? '').trim();
+        if (rest === '') {
+            // Possibly a `-` list on following indented lines.
+            const items = [];
+            while (i < lines.length && /^\s*-\s+/.test(lines[i])) {
+                items.push(coerceScalar(lines[i].replace(/^\s*-\s+/, '').trim()));
+                i++;
+            }
+            out[key] = items.length ? items : '';
+        }
+        else if (rest.startsWith('[') && rest.endsWith(']')) {
+            out[key] = rest
+                .slice(1, -1)
+                .split(',')
+                .map((s) => coerceScalar(s.trim()))
+                .filter((s) => s !== '');
+        }
+        else {
+            out[key] = coerceScalar(rest);
+        }
+    }
+    return out;
+}
+function coerceScalar(raw) {
+    if (raw === '')
+        return '';
+    if ((raw.startsWith('"') && raw.endsWith('"')) || (raw.startsWith("'") && raw.endsWith("'"))) {
+        return raw.slice(1, -1);
+    }
+    if (raw === 'true')
+        return true;
+    if (raw === 'false')
+        return false;
+    if (/^-?\d+(\.\d+)?$/.test(raw))
+        return Number(raw);
+    return raw;
+}

package/vendor/doxbrix-import/dist/docs/import.d.ts

@@ -0,0 +1,21 @@
+export interface SourceFile {
+    path: string;
+    content: string;
+}
+/** Collect non-page assets before conversion writes into its output directory. */
+export declare function collectSourceAssets(dir: string): string[];
+/** Copy imported images, fonts, media, styles, and API specs without flattening paths. */
+export declare function copySourceAssets(sourceDir: string, docsDir: string, assets: string[]): number;
+/** Collect text source files under `dir` (skips binaries/large/media). */
+export declare function collectSourceFiles(dir: string): SourceFile[];
+/** Write a converted manifest + page files into `docsDir`. */
+export declare function writeConvertResult(docsDir: string, result: {
+    manifest: unknown;
+    pages: {
+        path: string;
+        markdown: string;
+    }[];
+}): {
+    manifestPath: string;
+    pageCount: number;
+};

package/vendor/doxbrix-import/dist/docs/import.js

@@ -0,0 +1,147 @@
+import { copyFileSync, readFileSync, writeFileSync, mkdirSync, rmSync, statSync } from 'node:fs';
+import { join, dirname, posix } from 'node:path';
+import { listFilesRecursive } from './project.js';
+import { stringifyManifest, withPageExtension } from './manifest.js';
+import { assertSafeWriteParent, resolveWithin } from '../safe-path.js';
+import { hasStarterPageContent } from './starter.js';
+/** Text extensions / filenames worth uploading for dialect detection + conversion. */
+const TEXT_EXTS = ['.md', '.mdx', '.markdown', '.json', '.yaml', '.yml', '.txt', '.css'];
+const TEXT_NAMES = ['summary', 'mint.json', 'docs.json', '.gitbook.yaml', '.gitbook.yml', 'readme'];
+const MAX_FILES = 4000;
+const MAX_BYTES = 2 * 1024 * 1024; // per file
+/** Assets that can be rendered or are referenced by imported documentation. */
+const ASSET_EXTS = new Set([
+    '.png', '.jpg', '.jpeg', '.webp', '.gif', '.svg', '.ico', '.avif', '.bmp',
+    '.mp4', '.webm', '.mov', '.mp3', '.wav', '.ogg', '.pdf',
+    '.woff', '.woff2', '.ttf', '.otf', '.eot',
+    '.json', '.yaml', '.yml',
+]);
+const SOURCE_CONFIGS = new Set(['docs.json', 'mint.json', '.gitbook.yaml', '.gitbook.yml']);
+const SOURCE_TOOLING_FILES = new Set([
+    'package.json', 'package-lock.json', 'pnpm-lock.yaml', 'yarn.lock', 'bun.lock', 'bun.lockb',
+    'tsconfig.json', 'jsconfig.json', 'biome.json', 'deno.json', 'deno.jsonc',
+]);
+/** Collect non-page assets before conversion writes into its output directory. */
+export function collectSourceAssets(dir) {
+    const assets = [];
+    for (const rel of listFilesRecursive(dir)) {
+        const normalized = rel.replace(/\\/g, '/');
+        const base = normalized.split('/').pop()?.toLowerCase() ?? '';
+        if (/^(?:\.git|\.github|\.gitlab|node_modules|scripts|bin)\//.test(normalized))
+            continue;
+        if (SOURCE_TOOLING_FILES.has(base) || /^tsconfig\..*\.json$/.test(base))
+            continue;
+        const dot = base.lastIndexOf('.');
+        const ext = dot >= 0 ? base.slice(dot) : '';
+        if (!ASSET_EXTS.has(ext) || SOURCE_CONFIGS.has(base))
+            continue;
+        assets.push(normalized);
+    }
+    return assets;
+}
+/** Copy imported images, fonts, media, styles, and API specs without flattening paths. */
+export function copySourceAssets(sourceDir, docsDir, assets) {
+    let copied = 0;
+    for (const rel of assets) {
+        const source = resolveWithin(sourceDir, rel);
+        const destination = resolveWithin(docsDir, rel);
+        // Root-level imports already have assets in place. Never copy a file onto itself.
+        if (source === destination)
+            continue;
+        try {
+            assertSafeWriteParent(docsDir, destination);
+            mkdirSync(dirname(destination), { recursive: true });
+            copyFileSync(source, destination);
+            copied += 1;
+        }
+        catch {
+            // Keep migration resilient; the command reports the number successfully copied.
+        }
+    }
+    return copied;
+}
+/** Collect text source files under `dir` (skips binaries/large/media). */
+export function collectSourceFiles(dir) {
+    const listed = listFilesRecursive(dir).map((rel) => rel.replace(/\\/g, '/'));
+    const available = new Set(listed);
+    const files = [];
+    const collected = new Set();
+    const add = (rel) => {
+        if (files.length >= MAX_FILES)
+            return;
+        const lower = rel.toLowerCase();
+        const base = lower.split('/').pop() ?? '';
+        const isText = TEXT_EXTS.some((e) => lower.endsWith(e)) || TEXT_NAMES.some((n) => base === n || base.startsWith(n + '.'));
+        if (!isText || collected.has(rel))
+            return;
+        const abs = join(dir, rel);
+        try {
+            if (statSync(abs).size > MAX_BYTES)
+                return;
+            files.push({ path: rel, content: readFileSync(abs, 'utf8') });
+            collected.add(rel);
+        }
+        catch {
+            // unreadable — skip
+        }
+    };
+    for (const rel of listed) {
+        if (files.length >= MAX_FILES)
+            break;
+        add(rel);
+    }
+    // React SVG icons and other non-executing snippets are sometimes stored in
+    // .js/.jsx/.ts/.tsx modules. Follow only modules explicitly imported by a
+    // collected documentation file; never scan arbitrary application source.
+    for (let index = 0; index < files.length && files.length < MAX_FILES; index += 1) {
+        const sourceFile = files[index];
+        for (const match of sourceFile.content.matchAll(/\bfrom\s*["']([^"']+\.(?:js|jsx|ts|tsx))["']/g)) {
+            const specifier = match[1];
+            const target = posix.normalize(specifier.startsWith('/')
+                ? specifier.slice(1)
+                : posix.join(posix.dirname(sourceFile.path), specifier));
+            if (target === '..' || target.startsWith('../') || !available.has(target) || collected.has(target))
+                continue;
+            const abs = join(dir, target);
+            try {
+                if (statSync(abs).size > MAX_BYTES)
+                    continue;
+                files.push({ path: target, content: readFileSync(abs, 'utf8') });
+                collected.add(target);
+            }
+            catch {
+                // unreadable — skip
+            }
+        }
+    }
+    return files;
+}
+/** Write a converted manifest + page files into `docsDir`. */
+export function writeConvertResult(docsDir, result) {
+    mkdirSync(docsDir, { recursive: true });
+    const generatedPages = new Set(result.pages.map((page) => withPageExtension(page.path)));
+    // `dxb init` creates two useful starter pages. A repository import replaces
+    // those only when the source does not contain the same routes; never remove
+    // user-authored pages or any path produced by this conversion.
+    for (const rel of listFilesRecursive(docsDir)) {
+        if (!/\.(?:md|mdx)$/i.test(rel) || generatedPages.has(rel))
+            continue;
+        const absolute = resolveWithin(docsDir, rel);
+        try {
+            if (hasStarterPageContent(readFileSync(absolute, 'utf8')))
+                rmSync(absolute);
+        }
+        catch {
+            // A concurrent or unreadable file is preserved rather than risking data loss.
+        }
+    }
+    const manifestPath = join(docsDir, 'docs.json');
+    writeFileSync(manifestPath, stringifyManifest(result.manifest));
+    for (const page of result.pages) {
+        const abs = resolveWithin(docsDir, withPageExtension(page.path));
+        assertSafeWriteParent(docsDir, abs);
+        mkdirSync(dirname(abs), { recursive: true });
+        writeFileSync(abs, page.markdown);
+    }
+    return { manifestPath, pageCount: result.pages.length };
+}