@gradial/aci 0.1.52-rc.21 → 0.1.52-rc.22

package/README.md

@@ -1,6 +1,6 @@
 # Agentic Content Infrastructure SDK
 
-`@gradial/aci` `0.1.52-rc.21` is a pre-1.0 public-surface reset for the ACI
+`@gradial/aci` `0.1.52-rc.22` is a pre-1.0 public-surface reset for the ACI
 client SDK. Breaking changes from the old `0.1.x` accidental surface are
 intentional: the root import is framework-neutral, framework runtime behavior is
 behind explicit subpaths, and the first required customer path is React/Next.
@@ -8,7 +8,7 @@ behind explicit subpaths, and the first required customer path is React/Next.
 ## Install
 
 ```bash
-npm install @gradial/aci@0.1.52-rc.21 zod@^4
+npm install @gradial/aci@0.1.52-rc.22 zod@^4
 ```
 
 ## Root Import
@@ -62,6 +62,36 @@ export default withAci(nextConfig, {
 
 Astro public subpath is `@gradial/aci/astro`.
 
+## Mintlify
+
+`@gradial/aci/mintlify` is the Mintlify adapter used automatically by the ACI
+CLI. Mintlify remains the renderer; ACI owns the standard `.content` tree.
+Documents use stable ACI component IDs and an
+ordered recursive block tree: Markdown slices for prose, typed nested Mintlify
+components and stable accessibility-safe anchors for common structures, and
+explicit `mintlify.mdx` nodes for native syntax that has not been promoted to a
+typed contract.
+
+The source tree may also contain independently governed snippets, recursive
+`docs.json` `$ref` fragments, and OpenAPI, AsyncAPI, or GraphQL descriptions:
+
+```text
+.content/
+  config/site.json
+  config/mintlify.json
+  pages/**/_index.json
+  fragments/**/_index.json
+```
+
+```bash
+aci content compile
+```
+
+See `starters/mintlify/` for the smallest runnable site. `.aci.yaml` selects
+`framework: mintlify`; no renderer or validation flag is needed. The command
+validates the graph and writes the native project to
+`.aci/compiled/renderers/mintlify/` beside the ordinary compiled manifest.
+
 ## Build-Time Content Provider
 
 The file provider reads compiler output while generating complete static pages:
@@ -78,13 +108,13 @@ host bundles select and serve immutable release artifacts.
 The first RC scaffold path is Next:
 
 ```bash
-npx @gradial/aci@0.1.52-rc.21 init my-site --template next-starter
+npx @gradial/aci@0.1.52-rc.22 init my-site --template next-starter
 ```
 
 List available templates:
 
 ```bash
-npx @gradial/aci@0.1.52-rc.21 init --list
+npx @gradial/aci@0.1.52-rc.22 init --list
 ```
 
 ## Personalization: The One-Tag Install

package/dist/cli/mintlify-render.d.mts

@@ -0,0 +1 @@
+export {};

package/dist/cli/mintlify-render.mjs

@@ -0,0 +1,8 @@
+import path from 'node:path';
+import { loadCompiledMintlifySource, materializeMintlifySite } from '../../dist/mintlify/index.js';
+const [sourceArg, compiledArg, outputArg] = process.argv.slice(2);
+if (!sourceArg || !compiledArg || !outputArg) {
+    throw new Error('Mintlify renderer requires content, compiled, and output directories');
+}
+const source = await loadCompiledMintlifySource(path.resolve(sourceArg), path.resolve(compiledArg));
+await materializeMintlifySite({ ...source, outputDir: path.resolve(outputArg) });

package/dist/mintlify/blocks.d.ts

@@ -0,0 +1,6 @@
+import type { MintlifyBlock, MintlifyDocument, MintlifySnippet } from './types.js';
+export declare function renderDocument(document: MintlifyDocument): string;
+export declare function renderSnippet(snippet: MintlifySnippet): string;
+export declare function validateBlock(value: unknown, label: string, ids: Set<string>): MintlifyBlock;
+export declare function visitBlocks(blocks: MintlifyBlock[], visit: (block: MintlifyBlock) => void): void;
+export declare function validateSnippetReferences(documents: MintlifyDocument[], snippets: MintlifySnippet[]): void;

package/dist/mintlify/blocks.js

@@ -0,0 +1,198 @@
+import { cleanFilePath, isMintlifyJSONValue, isObject, nonEmptyString } from './json.js';
+const GENERATED_MARKER = '{/* Generated by @gradial/aci; edit .content instead. */}';
+const SUPPORTED_COMPONENTS = new Set([
+    'mintlify.markdown', 'mintlify.mdx', 'mintlify.anchor', 'mintlify.steps', 'mintlify.step',
+    'mintlify.card-group', 'mintlify.card', 'mintlify.accordion-group',
+    'mintlify.accordion', 'mintlify.callout', 'mintlify.tabs', 'mintlify.tab',
+    'mintlify.snippet-ref',
+]);
+export function renderDocument(document) {
+    const frontmatter = [`title: ${JSON.stringify(document.metadata.title)}`];
+    if (document.metadata.description)
+        frontmatter.push(`description: ${JSON.stringify(document.metadata.description)}`);
+    if (document.metadata.mintlify?.sidebarTitle)
+        frontmatter.push(`sidebarTitle: ${JSON.stringify(document.metadata.mintlify.sidebarTitle)}`);
+    if (document.metadata.mintlify?.icon)
+        frontmatter.push(`icon: ${JSON.stringify(document.metadata.mintlify.icon)}`);
+    for (const [key, value] of Object.entries(document.metadata.mintlify?.frontmatter ?? {}).sort(([left], [right]) => left.localeCompare(right))) {
+        frontmatter.push(`${key}: ${JSON.stringify(value)}`);
+    }
+    return `---\n${frontmatter.join('\n')}\n---\n\n${GENERATED_MARKER}\n\n${renderContent(document.regions.main)}`;
+}
+export function renderSnippet(snippet) {
+    return `${GENERATED_MARKER}\n\n${renderContent([snippet.block])}`;
+}
+function renderContent(blocks) {
+    const aliases = snippetAliases(blocks);
+    const imports = [...aliases].map(([snippetPath, alias]) => `import ${alias} from "/${snippetPath}";`).join('\n');
+    const body = renderBlocks(blocks, 0, aliases).replace(/\n*$/, '\n');
+    return imports ? `${imports}\n\n${body}` : body;
+}
+function renderBlocks(blocks, indentation, aliases) {
+    return blocks.map((block) => renderBlock(block, indentation, aliases)).join('\n\n');
+}
+function renderBlock(block, indentation, aliases) {
+    const prefix = ' '.repeat(indentation);
+    if (block.component === 'mintlify.markdown' || block.component === 'mintlify.mdx')
+        return indentSource(block.props.source, indentation);
+    if (block.component === 'mintlify.anchor')
+        return `${prefix}<span id="${escapeAttribute(block.props.name)}"></span>`;
+    if (block.component === 'mintlify.snippet-ref') {
+        const snippetPath = block.props.path;
+        const alias = aliases.get(snippetPath);
+        const values = block.props.values;
+        const attributes = Object.entries(values).sort(([left], [right]) => left.localeCompare(right)).map(([key, value]) => renderAttribute(key, value)).join('');
+        return `${prefix}<${alias}${attributes} />`;
+    }
+    const children = block.props.children ?? [];
+    const tag = nativeComponentName(block);
+    const attributes = Object.entries(block.props)
+        .filter(([key]) => key !== 'children' && key !== 'variant')
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, value]) => renderAttribute(key, value))
+        .join('');
+    if (children.length === 0)
+        return `${prefix}<${tag}${attributes}>\n${prefix}</${tag}>`;
+    return `${prefix}<${tag}${attributes}>\n${renderBlocks(children, indentation + 2, aliases)}\n${prefix}</${tag}>`;
+}
+function snippetAliases(blocks) {
+    const aliases = new Map();
+    visitBlocks(blocks, (block) => {
+        if (block.component !== 'mintlify.snippet-ref')
+            return;
+        const snippetPath = block.props.path;
+        if (!aliases.has(snippetPath))
+            aliases.set(snippetPath, `AciSnippet${aliases.size + 1}`);
+    });
+    return aliases;
+}
+function nativeComponentName(block) {
+    if (block.component === 'mintlify.callout') {
+        const variant = block.props.variant;
+        return variant[0].toUpperCase() + variant.slice(1);
+    }
+    return block.component.slice('mintlify.'.length).split('-').map((part) => part[0].toUpperCase() + part.slice(1)).join('');
+}
+function renderAttribute(key, value) {
+    if (value === true)
+        return ` ${key}`;
+    if (typeof value === 'string')
+        return ` ${key}="${escapeAttribute(value)}"`;
+    return ` ${key}={${JSON.stringify(value)}}`;
+}
+function escapeAttribute(value) {
+    return value.replaceAll('&', '&amp;').replaceAll('"', '&quot;').replaceAll('<', '&lt;').replaceAll('>', '&gt;');
+}
+function indentSource(source, indentation) {
+    const normalized = source.replace(/\r\n/g, '\n').replace(/^\n+|\n+$/g, '');
+    const prefix = ' '.repeat(indentation);
+    return normalized.split('\n').map((line) => line.length > 0 ? `${prefix}${line}` : '').join('\n');
+}
+export function validateBlock(value, label, ids) {
+    if (!isObject(value) || value.$type !== 'component' || !nonEmptyString(value.id) || !nonEmptyString(value.component) || !isObject(value.props)) {
+        throw new Error(`ACI Mintlify block is invalid: ${label}`);
+    }
+    if (ids.has(value.id))
+        throw new Error(`ACI Mintlify block ID is duplicated: ${value.id}`);
+    ids.add(value.id);
+    if (!SUPPORTED_COMPONENTS.has(value.component))
+        throw new Error(`ACI Mintlify component is unsupported: ${value.component}`);
+    const props = {};
+    for (const [key, entry] of Object.entries(value.props)) {
+        if (key === 'children') {
+            if (!Array.isArray(entry))
+                throw new Error(`ACI Mintlify block children are invalid: ${label}`);
+            props.children = entry.map((child, index) => validateBlock(child, `${label}.props.children[${index}]`, ids));
+        }
+        else if (!isMintlifyJSONValue(entry)) {
+            throw new Error(`ACI Mintlify block property is invalid: ${label}.${key}`);
+        }
+        else {
+            props[key] = entry;
+        }
+    }
+    validateComponentProps(value.component, props, label);
+    return { $type: 'component', id: value.id, component: value.component, props };
+}
+function validateComponentProps(component, props, label) {
+    if (component === 'mintlify.markdown' || component === 'mintlify.mdx') {
+        if (typeof props.source !== 'string' || props.children !== undefined)
+            throw new Error(`ACI Mintlify source block is invalid: ${label}`);
+        return;
+    }
+    if (component === 'mintlify.anchor') {
+        if (typeof props.name !== 'string' || !/^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/.test(props.name) || Object.keys(props).some((key) => key !== 'name')) {
+            throw new Error(`ACI Mintlify anchor is invalid: ${label}`);
+        }
+        return;
+    }
+    if (component === 'mintlify.snippet-ref') {
+        if (!nonEmptyString(props.path) || cleanFilePath(props.path, '.mdx') !== props.path || !isObject(props.values) || !isMintlifyJSONValue(props.values) || props.children !== undefined) {
+            throw new Error(`ACI Mintlify snippet reference is invalid: ${label}`);
+        }
+        return;
+    }
+    if (!Array.isArray(props.children))
+        throw new Error(`ACI Mintlify component children are required: ${label}`);
+    if (component === 'mintlify.callout' && !['info', 'warning', 'note', 'tip', 'check'].includes(String(props.variant))) {
+        throw new Error(`ACI Mintlify callout variant is invalid: ${label}`);
+    }
+    if (['mintlify.step', 'mintlify.card', 'mintlify.accordion', 'mintlify.tab'].includes(component) && !nonEmptyString(props.title)) {
+        throw new Error(`ACI Mintlify component title is required: ${label}`);
+    }
+    const expectedChild = component === 'mintlify.steps' ? 'mintlify.step'
+        : component === 'mintlify.card-group' ? 'mintlify.card'
+            : component === 'mintlify.accordion-group' ? 'mintlify.accordion'
+                : component === 'mintlify.tabs' ? 'mintlify.tab'
+                    : undefined;
+    if (expectedChild && props.children?.some((child) => child.component !== expectedChild))
+        throw new Error(`ACI Mintlify ${component} child is invalid: ${label}`);
+}
+export function visitBlocks(blocks, visit) {
+    for (const block of blocks) {
+        visit(block);
+        if (block.props.children)
+            visitBlocks(block.props.children, visit);
+    }
+}
+function snippetReferences(blocks) {
+    const references = [];
+    visitBlocks(blocks, (block) => {
+        if (block.component === 'mintlify.snippet-ref')
+            references.push(block.props.path);
+    });
+    return references;
+}
+export function validateSnippetReferences(documents, snippets) {
+    const byPath = new Map();
+    for (const snippet of snippets) {
+        if (byPath.has(snippet.path))
+            throw new Error(`ACI Mintlify snippet path is duplicated: ${snippet.path}`);
+        byPath.set(snippet.path, snippet);
+    }
+    for (const document of documents) {
+        for (const reference of snippetReferences(document.regions.main)) {
+            if (!byPath.has(reference))
+                throw new Error(`ACI Mintlify snippet reference is missing: ${reference}`);
+        }
+    }
+    const visited = new Set();
+    const visiting = new Set();
+    const walk = (snippetPath) => {
+        if (visited.has(snippetPath))
+            return;
+        if (visiting.has(snippetPath))
+            throw new Error(`ACI Mintlify snippet reference cycle includes: ${snippetPath}`);
+        visiting.add(snippetPath);
+        const snippet = byPath.get(snippetPath);
+        for (const reference of snippetReferences([snippet.block])) {
+            if (!byPath.has(reference))
+                throw new Error(`ACI Mintlify snippet reference is missing: ${reference}`);
+            walk(reference);
+        }
+        visiting.delete(snippetPath);
+        visited.add(snippetPath);
+    };
+    for (const snippetPath of byPath.keys())
+        walk(snippetPath);
+}

package/dist/mintlify/config.d.ts

@@ -0,0 +1,3 @@
+import type { MintlifyConfigFragment, MintlifyJSONValue, MintlifySite } from './types.js';
+export declare function toDocsJSON(site: MintlifySite): Record<string, unknown>;
+export declare function resolveConfigReferences(configuration: MintlifyJSONValue, fragments: MintlifyConfigFragment[]): MintlifyJSONValue;

package/dist/mintlify/config.js

@@ -0,0 +1,77 @@
+import path from 'node:path';
+import { canonicalize, isExternalReference, isObject } from './json.js';
+export function toDocsJSON(site) {
+    const { $schema: _schema, ...configuration } = site;
+    return canonicalize({
+        $schema: 'https://mintlify.com/docs.json',
+        ...(typeof configuration.theme === 'string' ? {} : { theme: 'mint' }),
+        ...configuration,
+    });
+}
+export function resolveConfigReferences(configuration, fragments) {
+    const byPath = new Map();
+    for (const fragment of fragments) {
+        if (byPath.has(fragment.path))
+            throw new Error(`ACI Mintlify config fragment path is duplicated: ${fragment.path}`);
+        byPath.set(fragment.path, fragment.value);
+    }
+    return resolveConfigValue(configuration, 'docs.json', byPath, new Set());
+}
+function resolveConfigValue(value, currentPath, fragments, stack) {
+    if (Array.isArray(value))
+        return value.map((entry) => resolveConfigValue(entry, currentPath, fragments, stack));
+    if (!isObject(value))
+        return value;
+    if (typeof value.$ref === 'string' && !isExternalReference(value.$ref)) {
+        const reference = resolveConfigReferencePath(currentPath, value.$ref);
+        const target = fragments.get(reference.path);
+        if (target === undefined)
+            throw new Error(`ACI Mintlify config reference is missing: ${value.$ref} from ${currentPath}`);
+        const cycleKey = `${reference.path}#${reference.pointer.join('/')}`;
+        if (stack.has(cycleKey))
+            throw new Error(`ACI Mintlify config reference cycle includes: ${cycleKey}`);
+        const nextStack = new Set(stack).add(cycleKey);
+        const selected = resolveJSONPointer(target, reference.pointer, value.$ref);
+        const resolvedTarget = resolveConfigValue(selected, reference.path, fragments, nextStack);
+        const siblings = Object.fromEntries(Object.entries(value)
+            .filter(([key]) => key !== '$ref')
+            .map(([key, child]) => [key, resolveConfigValue(child, currentPath, fragments, stack)]));
+        if (Object.keys(siblings).length === 0)
+            return resolvedTarget;
+        if (!isObject(resolvedTarget))
+            throw new Error(`ACI Mintlify config reference with sibling keys must resolve to an object: ${value.$ref}`);
+        return { ...resolvedTarget, ...siblings };
+    }
+    return Object.fromEntries(Object.entries(value).map(([key, child]) => [key, resolveConfigValue(child, currentPath, fragments, stack)]));
+}
+function resolveConfigReferencePath(currentPath, reference) {
+    const [rawPath, rawPointer = ''] = reference.split('#', 2);
+    if (!rawPath)
+        throw new Error(`ACI Mintlify local config reference requires a file path: ${reference}`);
+    const resolved = path.posix.normalize(path.posix.join(path.posix.dirname(currentPath), rawPath));
+    if (resolved.startsWith('../') || resolved.startsWith('/') || !resolved.endsWith('.json')) {
+        throw new Error(`ACI Mintlify config reference path is invalid: ${reference}`);
+    }
+    const pointer = rawPointer === '' ? [] : rawPointer.startsWith('/')
+        ? rawPointer.slice(1).split('/').map((part) => part.replaceAll('~1', '/').replaceAll('~0', '~'))
+        : (() => { throw new Error(`ACI Mintlify config reference pointer is invalid: ${reference}`); })();
+    return { path: resolved, pointer };
+}
+function resolveJSONPointer(value, pointer, reference) {
+    let current = value;
+    for (const part of pointer) {
+        if (Array.isArray(current)) {
+            const index = Number(part);
+            if (!Number.isInteger(index) || index < 0 || index >= current.length)
+                throw new Error(`ACI Mintlify config reference pointer is missing: ${reference}`);
+            current = current[index];
+        }
+        else if (isObject(current) && Object.hasOwn(current, part)) {
+            current = current[part];
+        }
+        else {
+            throw new Error(`ACI Mintlify config reference pointer is missing: ${reference}`);
+        }
+    }
+    return current;
+}

package/dist/mintlify/index.d.ts

@@ -0,0 +1,3 @@
+export { materializeMintlifySite, loadMintlifySource, loadCompiledMintlifySource, } from './materialize.js';
+export { renderDocument, renderSnippet } from './blocks.js';
+export type { MintlifyAPISpec, MintlifyBlock, MintlifyConfigFragment, MintlifyDocument, MintlifyJSONValue, MintlifyNavigationGroup, MintlifySite, MintlifySnippet, MintlifySource, } from './types.js';

package/dist/mintlify/index.js

@@ -0,0 +1,2 @@
+export { materializeMintlifySite, loadMintlifySource, loadCompiledMintlifySource, } from './materialize.js';
+export { renderDocument, renderSnippet } from './blocks.js';

package/dist/mintlify/json.d.ts

@@ -0,0 +1,8 @@
+import type { MintlifyJSONValue } from './types.js';
+export declare function isObject(value: unknown): value is Record<string, unknown>;
+export declare function nonEmptyString(value: unknown): value is string;
+export declare function isMintlifyJSONValue(value: unknown): value is MintlifyJSONValue;
+export declare function canonicalize(value: MintlifyJSONValue): MintlifyJSONValue;
+export declare function isExternalReference(value: string): boolean;
+export declare function cleanDocumentPath(value: string): string;
+export declare function cleanFilePath(value: string, extension: string): string;

package/dist/mintlify/json.js

@@ -0,0 +1,37 @@
+export function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+export function nonEmptyString(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}
+export function isMintlifyJSONValue(value) {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean')
+        return true;
+    if (typeof value === 'number')
+        return Number.isFinite(value);
+    if (Array.isArray(value))
+        return value.every(isMintlifyJSONValue);
+    return isObject(value) && Object.values(value).every(isMintlifyJSONValue);
+}
+export function canonicalize(value) {
+    if (Array.isArray(value))
+        return value.map(canonicalize);
+    if (!isObject(value))
+        return value;
+    return Object.fromEntries(Object.entries(value).sort(([left], [right]) => left.localeCompare(right)).map(([key, child]) => [key, canonicalize(child)]));
+}
+export function isExternalReference(value) {
+    return /^(?:https?:)?\/\//i.test(value) || value.startsWith('mailto:');
+}
+export function cleanDocumentPath(value) {
+    const normalized = value.replace(/\\/g, '/').replace(/^\/+|\/+$/g, '');
+    if (!normalized || normalized.endsWith('.md') || normalized.endsWith('.mdx') || normalized.split('/').some((part) => !part || part === '.' || part === '..'))
+        return '';
+    return normalized;
+}
+export function cleanFilePath(value, extension) {
+    const normalized = value.replace(/\\/g, '/').replace(/^\/+|\/+$/g, '');
+    if (!normalized.endsWith(extension) || normalized.split('/').some((part) => !part || part === '.' || part === '..'))
+        return '';
+    return normalized;
+}

package/dist/mintlify/materialize.d.ts

@@ -0,0 +1,12 @@
+import type { MaterializeMintlifySiteOptions, MintlifySource } from './types.js';
+/**
+ * Reads a site and its documents from ACI's portable JSON content tree.
+ * The source shape is standard ACI content: `config/mintlify.json`, resources
+ * below `pages/` and `fragments/`; the generated Mintlify tree is not
+ * source content and must live outside this directory.
+ */
+export declare function loadMintlifySource(sourceDir: string): Promise<MintlifySource>;
+/** Loads resolved pages/fragments from ACI compiler output for framework projection. */
+export declare function loadCompiledMintlifySource(sourceDir: string, compiledDir: string): Promise<MintlifySource>;
+/** Materializes one exact Mintlify site from ACI source content. */
+export declare function materializeMintlifySite(options: MaterializeMintlifySiteOptions): Promise<void>;

package/dist/mintlify/materialize.js

@@ -0,0 +1,159 @@
+import { mkdir, readFile, readdir, writeFile, } from 'node:fs/promises';
+import path from 'node:path';
+import { resolveConfigReferences, toDocsJSON } from './config.js';
+import { renderDocument, renderSnippet } from './blocks.js';
+import { canonicalize, isObject, } from './json.js';
+import { validateAPISpec, validateConfigFragment, validateDocument, validateSite, validateSnippet, validateSource, } from './validate.js';
+/**
+ * Reads a site and its documents from ACI's portable JSON content tree.
+ * The source shape is standard ACI content: `config/mintlify.json`, resources
+ * below `pages/` and `fragments/`; the generated Mintlify tree is not
+ * source content and must live outside this directory.
+ */
+export async function loadMintlifySource(sourceDir) {
+    const sitePath = path.join(sourceDir, 'config', 'mintlify.json');
+    const pagesDir = path.join(sourceDir, 'pages');
+    const [site, pageResources, fragmentResources, configFragments, apiSpecs] = await Promise.all([
+        readJSON(sitePath),
+        readIndexResources(pagesDir),
+        readOptionalIndexResources(path.join(sourceDir, 'fragments')),
+        readOptionalJSONResources(path.join(sourceDir, 'config', 'mintlify')),
+        readOptionalJSONResources(path.join(sourceDir, 'data', 'mintlify-api')),
+    ]);
+    return {
+        site: validateSite(site, sitePath),
+        documents: pageResources.map(({ value, file, relative }) => validateDocument(value, file, relative === '_index.json' ? 'index' : relative.slice(0, -'/_index.json'.length))),
+        snippets: fragmentResources.map(({ value, file, relative }) => validateSnippet(value, file, `${relative.slice(0, -'/_index.json'.length)}.mdx`)),
+        configFragments: configFragments.map(({ value, file }) => validateConfigFragment(value, file)),
+        apiSpecs: apiSpecs.map(({ value, file }) => validateAPISpec(value, file)),
+    };
+}
+/** Loads resolved pages/fragments from ACI compiler output for framework projection. */
+export async function loadCompiledMintlifySource(sourceDir, compiledDir) {
+    const sitePath = path.join(sourceDir, 'config', 'mintlify.json');
+    const manifestPath = path.join(compiledDir, 'manifest.json');
+    const [siteValue, manifestValue, configFragments, apiSpecs] = await Promise.all([
+        readJSON(sitePath), readJSON(manifestPath),
+        readOptionalJSONResources(path.join(sourceDir, 'config', 'mintlify')),
+        readOptionalJSONResources(path.join(sourceDir, 'data', 'mintlify-api')),
+    ]);
+    if (!isObject(manifestValue) || !isObject(manifestValue.routes) || !isObject(manifestValue.fragments)) {
+        throw new Error(`ACI compiled manifest is invalid: ${manifestPath}`);
+    }
+    const documents = await Promise.all(Object.entries(manifestValue.routes).map(async ([slug, entry]) => {
+        if (!isObject(entry) || typeof entry.payloadRef !== 'string')
+            throw new Error(`ACI compiled route is invalid: ${slug}`);
+        return validateDocument(await readJSON(safeOutputPath(compiledDir, entry.payloadRef)), entry.payloadRef, slug || 'index');
+    }));
+    const snippets = await Promise.all(Object.entries(manifestValue.fragments).map(async ([id, entry]) => {
+        if (!isObject(entry) || typeof entry.payloadRef !== 'string')
+            throw new Error(`ACI compiled fragment is invalid: ${id}`);
+        return validateSnippet(await readJSON(safeOutputPath(compiledDir, entry.payloadRef)), entry.payloadRef, `${id}.mdx`);
+    }));
+    return {
+        site: validateSite(siteValue, sitePath), documents, snippets,
+        configFragments: configFragments.map(({ value, file }) => validateConfigFragment(value, file)),
+        apiSpecs: apiSpecs.map(({ value, file }) => validateAPISpec(value, file)),
+    };
+}
+/** Materializes one exact Mintlify site from ACI source content. */
+export async function materializeMintlifySite(options) {
+    const outputDir = path.resolve(options.outputDir);
+    const site = validateSite(options.site, 'site');
+    const documents = options.documents.map((document, index) => validateDocument(document, `documents[${index}]`, document.path));
+    const snippets = (options.snippets ?? []).map((snippet, index) => validateSnippet(snippet, `snippets[${index}]`, snippet.path));
+    const configFragments = (options.configFragments ?? []).map((fragment, index) => validateConfigFragment(fragment, `configFragments[${index}]`));
+    const apiSpecs = (options.apiSpecs ?? []).map((spec, index) => validateAPISpec(spec, `apiSpecs[${index}]`));
+    const nativeConfig = toDocsJSON(site);
+    const resolvedConfig = resolveConfigReferences(nativeConfig, configFragments);
+    validateSource(resolvedConfig, documents, snippets, apiSpecs);
+    const generated = new Map();
+    addGenerated(generated, 'docs.json', `${JSON.stringify(nativeConfig, null, 2)}\n`);
+    for (const fragment of configFragments) {
+        addGenerated(generated, fragment.path, `${JSON.stringify(canonicalize(fragment.value), null, 2)}\n`);
+    }
+    for (const snippet of snippets) {
+        addGenerated(generated, snippet.path, renderSnippet(snippet));
+    }
+    for (const spec of apiSpecs) {
+        addGenerated(generated, spec.path, spec.source.replace(/\r\n/g, '\n').replace(/\n*$/, '\n'));
+    }
+    for (const document of documents) {
+        addGenerated(generated, `${document.path}.mdx`, renderDocument(document));
+    }
+    await mkdir(outputDir, { recursive: true });
+    for (const [relativePath, contents] of generated) {
+        const destination = safeOutputPath(outputDir, relativePath);
+        await mkdir(path.dirname(destination), { recursive: true });
+        await writeFile(destination, contents, 'utf8');
+    }
+}
+function addGenerated(generated, outputPath, contents) {
+    if (generated.has(outputPath))
+        throw new Error(`ACI Mintlify generated output path is duplicated: ${outputPath}`);
+    generated.set(outputPath, contents);
+}
+async function readDocuments(directory) {
+    let entries;
+    try {
+        entries = await readdir(directory, { withFileTypes: true });
+    }
+    catch (error) {
+        throw new Error(`ACI Mintlify documents directory is required: ${directory}`, { cause: error });
+    }
+    const results = [];
+    for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+        const file = path.join(directory, entry.name);
+        if (entry.isDirectory())
+            results.push(...await readDocuments(file));
+        else if (entry.isFile() && entry.name.endsWith('.json'))
+            results.push({ file, value: await readJSON(file) });
+    }
+    return results;
+}
+async function readIndexResources(directory, root = directory) {
+    const entries = await readdir(directory, { withFileTypes: true });
+    const results = [];
+    for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+        const file = path.join(directory, entry.name);
+        if (entry.isDirectory())
+            results.push(...await readIndexResources(file, root));
+        else if (entry.isFile() && entry.name === '_index.json')
+            results.push({ file, relative: path.relative(root, file).split(path.sep).join('/'), value: await readJSON(file) });
+    }
+    return results;
+}
+async function readOptionalIndexResources(directory) {
+    try {
+        return await readIndexResources(directory);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+}
+async function readOptionalJSONResources(directory) {
+    try {
+        return await readDocuments(directory);
+    }
+    catch (error) {
+        if (error.cause && error.cause.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+}
+async function readJSON(file) {
+    try {
+        return JSON.parse(await readFile(file, 'utf8'));
+    }
+    catch (error) {
+        throw new Error(`ACI Mintlify source is not valid JSON: ${file}`, { cause: error });
+    }
+}
+function safeOutputPath(root, relativePath) {
+    const target = path.resolve(root, relativePath);
+    if (target === root || !target.startsWith(`${root}${path.sep}`))
+        throw new Error(`ACI Mintlify generated path escapes output directory: ${relativePath}`);
+    return target;
+}