@open-agent-toolkit/cli 0.3.26 → 0.3.28

package/dist/commands/docs/check/markdown.js

@@ -0,0 +1,125 @@
+import { remarkTabs } from '@open-agent-toolkit/docs-transforms';
+import Slugger from 'github-slugger';
+import { parseFragment } from 'parse5';
+import remarkGfm from 'remark-gfm';
+import remarkParse from 'remark-parse';
+import { unified } from 'unified';
+import YAML from 'yaml';
+export function nodeText(node) {
+    return node.children
+        ? node.children.map(nodeText).join('')
+        : (node.value ?? '');
+}
+export function htmlNodes(html) {
+    const nodes = [];
+    const walk = (n) => {
+        nodes.push(n);
+        n.childNodes?.forEach(walk);
+    };
+    walk(parseFragment(html, { sourceCodeLocationInfo: true }));
+    return nodes;
+}
+export function attributes(node) {
+    return Object.fromEntries(node.attrs?.map((a) => [a.name, a.value]) ?? []);
+}
+export function parsePage(path, source) {
+    let body = source;
+    let frontmatter = {};
+    let frontmatterError;
+    const match = /^(?:\uFEFF)?---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(source);
+    if (match) {
+        // Preserve physical positions for both AST and Contents diagnostics.
+        body = match[0].replace(/[^\r\n]/g, ' ') + source.slice(match[0].length);
+        try {
+            const doc = YAML.parseDocument(match[1]);
+            if (doc.errors.length)
+                frontmatterError = `Invalid YAML frontmatter: ${doc.errors[0].message}`;
+            else {
+                const data = doc.toJS();
+                if (typeof data !== 'object' || data === null || Array.isArray(data))
+                    frontmatterError = 'Frontmatter must be a YAML mapping';
+                else
+                    frontmatter = data;
+            }
+        }
+        catch (error) {
+            frontmatterError = `Invalid YAML frontmatter: ${error.message}`;
+        }
+    }
+    const processor = unified().use(remarkParse).use(remarkGfm).use(remarkTabs);
+    const tree = processor.runSync(processor.parse(body), {
+        value: body,
+    });
+    const nodes = [];
+    const walk = (node) => {
+        nodes.push(node);
+        node.children?.forEach(walk);
+    };
+    walk(tree);
+    const definitions = new Map();
+    for (const n of nodes)
+        if (n.type === 'definition' &&
+            n.identifier &&
+            n.url &&
+            !definitions.has(n.identifier))
+            definitions.set(n.identifier, n.url);
+    const anchors = new Set();
+    const slugger = new Slugger();
+    const links = [];
+    for (const n of nodes) {
+        const line = n.position?.start.line ?? 1;
+        if (n.type === 'heading') {
+            const text = nodeText(n);
+            const custom = /\s*(?:\[#([^\]]+)\]|\{#([^}]+)\})\s*$/.exec(text);
+            anchors.add(custom?.[1] ?? custom?.[2] ?? slugger.slug(text));
+        }
+        if (['link', 'image', 'linkReference', 'imageReference'].includes(n.type)) {
+            const href = n.url ?? definitions.get(n.identifier ?? '');
+            if (href !== undefined)
+                links.push({
+                    href,
+                    line,
+                    image: n.type.startsWith('image'),
+                    alt: n.alt,
+                });
+        }
+        if (n.type === 'html')
+            for (const element of htmlNodes(n.value ?? '')) {
+                const a = attributes(element);
+                if (a.id)
+                    anchors.add(a.id);
+                if (element.nodeName === 'a' && a.name)
+                    anchors.add(a.name);
+                if (element.nodeName === 'a' && a.href)
+                    links.push({
+                        href: a.href,
+                        image: false,
+                        html: true,
+                        line: line + (element.sourceCodeLocation?.startLine ?? 1) - 1,
+                    });
+                if (element.nodeName === 'img' && a.src)
+                    links.push({
+                        href: a.src,
+                        alt: a.alt,
+                        image: true,
+                        html: true,
+                        describedBy: a['aria-describedby'],
+                        line: line + (element.sourceCodeLocation?.startLine ?? 1) - 1,
+                    });
+            }
+    }
+    return {
+        path,
+        source,
+        body,
+        frontmatter,
+        ...(frontmatterError ? { frontmatterError } : {}),
+        nodes,
+        anchors,
+        links,
+        text: nodes
+            .filter((n) => n.type === 'text')
+            .map((n) => n.value ?? '')
+            .join(' '),
+    };
+}

package/dist/commands/docs/check/mermaid-runtime.d.ts

@@ -0,0 +1,3 @@
+/** Lazy, real Node DOM for Mermaid syntax parsing only. Never renders SVG. */
+export declare function parseMermaid(source: string): Promise<void>;
+//# sourceMappingURL=mermaid-runtime.d.ts.map

package/dist/commands/docs/check/mermaid-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mermaid-runtime.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/check/mermaid-runtime.ts"],"names":[],"mappings":"AA6CA,8EAA8E;AAC9E,wBAAsB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAehE"}

package/dist/commands/docs/check/mermaid-runtime.js

@@ -0,0 +1,57 @@
+let runtime;
+let queue = Promise.resolve();
+async function withDom(dom, action) {
+    const keys = ['window', 'document'];
+    const saved = keys.map((key) => Object.getOwnPropertyDescriptor(globalThis, key));
+    Object.defineProperty(globalThis, 'window', {
+        configurable: true,
+        value: dom.window,
+    });
+    Object.defineProperty(globalThis, 'document', {
+        configurable: true,
+        value: dom.window.document,
+    });
+    try {
+        return await action();
+    }
+    finally {
+        keys.forEach((key, index) => {
+            const descriptor = saved[index];
+            if (descriptor)
+                Object.defineProperty(globalThis, key, descriptor);
+            else
+                Reflect.deleteProperty(globalThis, key);
+        });
+    }
+}
+async function loadRuntime() {
+    const { JSDOM } = await import('jsdom');
+    // Defaults intentionally disable script execution and external resources.
+    const dom = new JSDOM('');
+    try {
+        const mermaid = await withDom(dom, async () => (await import('mermaid')).default);
+        process.once('beforeExit', () => dom.window.close());
+        return { dom, mermaid };
+    }
+    catch (error) {
+        dom.window.close();
+        throw error;
+    }
+}
+/** Lazy, real Node DOM for Mermaid syntax parsing only. Never renders SVG. */
+export async function parseMermaid(source) {
+    const result = queue.then(async () => {
+        runtime ??= loadRuntime();
+        const { dom, mermaid } = await runtime;
+        await withDom(dom, async () => {
+            mermaid.initialize({
+                startOnLoad: false,
+                securityLevel: 'strict',
+                logLevel: 'fatal',
+            });
+            await mermaid.parse(source);
+        });
+    });
+    queue = result.catch(() => undefined);
+    await result;
+}

package/dist/commands/docs/check/navigation.d.ts

@@ -0,0 +1,4 @@
+import type { Report } from './check.types.js';
+import { type CheckTarget } from './files.js';
+export declare function checkNavigation(target: CheckTarget, report: Report): Promise<void>;
+//# sourceMappingURL=navigation.d.ts.map

package/dist/commands/docs/check/navigation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"navigation.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/check/navigation.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAW,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AAgCpD,wBAAsB,eAAe,CACnC,MAAM,EAAE,WAAW,EACnB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC,CAmGf"}

package/dist/commands/docs/check/navigation.js

@@ -0,0 +1,104 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+import { buildDocsNavTree } from '../../docs/nav/contents.js';
+import { syncFumadocsNavigation } from '../../docs/nav/fumadocs.js';
+import { syncDocsNavigation } from '../../docs/nav/sync.js';
+import YAML from 'yaml';
+import { present } from './files.js';
+function pageIdentity(item) {
+    // Hand-authored collision links can use their own display labels.
+    return item.replace(/^\[[^\]]*\]\((.*)\)$/, '[]($1)').replace(/^\.\//, '');
+}
+function navIdentity(value, expected) {
+    if (!Array.isArray(value))
+        return value;
+    return value.map((item, index) => {
+        if (typeof item === 'string')
+            return item;
+        if (typeof item !== 'object' || item === null)
+            return item;
+        const entry = Object.entries(item)[0];
+        if (!entry)
+            return item;
+        const expectedItem = Array.isArray(expected) ? expected[index] : undefined;
+        const children = expectedItem && typeof expectedItem === 'object'
+            ? Object.values(expectedItem)[0]
+            : undefined;
+        // The Contents-derived tree identifies sections by their direct landing path.
+        // Actual landing/page labels are presentation; explicit group labels remain meaningful.
+        const section = Array.isArray(children) &&
+            children.some((child) => typeof child === 'string' && child.endsWith('/index.md'));
+        return Array.isArray(entry[1])
+            ? {
+                [section ? '$section' : entry[0]]: navIdentity(entry[1], children),
+            }
+            : entry[1];
+    });
+}
+export async function checkNavigation(target, report) {
+    if (target.framework === 'markdown')
+        return;
+    try {
+        const generated = target.documentation.navOwner === 'nav-sync';
+        const nonReaderPaths = target.documentation.nonReaderPaths;
+        if (target.framework === 'fumadocs') {
+            const result = await syncFumadocsNavigation({
+                docsRoot: target.contentRoot,
+                check: true,
+                nonReaderPaths,
+            });
+            for (const file of result.metaFiles) {
+                let stale = file.changed;
+                if (!generated) {
+                    if (!(await present(join(target.contentRoot, file.path))))
+                        continue;
+                    try {
+                        const actual = JSON.parse(await readFile(join(target.contentRoot, file.path), 'utf8'));
+                        if (actual &&
+                            typeof actual === 'object' &&
+                            !Array.isArray(actual) &&
+                            !Object.hasOwn(actual, 'pages'))
+                            continue;
+                        stale =
+                            !Array.isArray(actual.pages) ||
+                                !isDeepStrictEqual(actual.pages.map((p) => typeof p === 'string' ? pageIdentity(p) : p), file.meta.pages.map(pageIdentity));
+                    }
+                    catch {
+                        report('navigation', 'error', file.path, 'Cannot read or parse meta.json; check file permissions and JSON syntax.');
+                        continue;
+                    }
+                }
+                if (stale)
+                    report('navigation', 'error', file.path, generated
+                        ? 'Generated navigation is stale; run oat docs nav sync.'
+                        : 'Navigation membership/order differs from authored Contents; update pages or Contents.');
+            }
+            for (const path of result.unlisted)
+                report('navigation', 'error', path, 'Reader page/folder is unlisted in authored Contents and would be hidden from navigation.');
+        }
+        else if (generated) {
+            const result = await syncDocsNavigation({
+                appRoot: target.appRoot,
+                check: true,
+                nonReaderPaths,
+            });
+            for (const path of result.stale)
+                report('navigation', 'error', path, 'Generated navigation is stale; run oat docs nav sync.');
+        }
+        else {
+            const expected = await buildDocsNavTree({
+                docsRoot: target.contentRoot,
+                nonReaderPaths,
+            });
+            const actual = YAML.parse(await readFile(join(target.appRoot, 'mkdocs.yml'), 'utf8'));
+            if (!actual || !Object.hasOwn(actual, 'nav'))
+                return;
+            if (!isDeepStrictEqual(navIdentity(actual.nav, expected), navIdentity(expected, expected)))
+                report('navigation', 'error', 'mkdocs.yml', 'Navigation membership/order differs from authored Contents; update nav or Contents.');
+        }
+    }
+    catch (error) {
+        report('navigation', 'error', 'index.md', error.message);
+    }
+}

package/dist/commands/docs/check/reader-rules.d.ts

@@ -0,0 +1,6 @@
+import type { Report } from './check.types.js';
+import { type CheckTarget } from './files.js';
+import { type ParsedPage } from './markdown.js';
+export declare function checkReaders(target: CheckTarget, pages: ParsedPage[], report: Report): Promise<void>;
+export declare function checkProvenance(target: CheckTarget, pages: ParsedPage[], report: Report): void;
+//# sourceMappingURL=reader-rules.d.ts.map

package/dist/commands/docs/check/reader-rules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reader-rules.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/check/reader-rules.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAML,KAAK,WAAW,EACjB,MAAM,SAAS,CAAC;AACjB,OAAO,EAAY,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAEvD,wBAAsB,YAAY,CAChC,MAAM,EAAE,WAAW,EACnB,KAAK,EAAE,UAAU,EAAE,EACnB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC,CAuVf;AAED,wBAAgB,eAAe,CAC7B,MAAM,EAAE,WAAW,EACnB,KAAK,EAAE,UAAU,EAAE,EACnB,MAAM,EAAE,MAAM,GACb,IAAI,CA+CN"}

package/dist/commands/docs/check/reader-rules.js

@@ -0,0 +1,214 @@
+import { dirname, extname, join, resolve } from 'node:path';
+import { parseIndexContents, resolveEntryTarget, } from '../../docs/nav/contents.js';
+import { isExcludedPath } from '../../docs/shared/exclusions.js';
+import { DOCS_CHECK_THRESHOLDS } from '../../../config/documentation-check.js';
+import { containedFile, inside, posix, present, readerDirectories, } from './files.js';
+import { nodeText } from './markdown.js';
+export async function checkReaders(target, pages, report) {
+    const t = {
+        ...DOCS_CHECK_THRESHOLDS,
+        ...target.documentation.check?.thresholds,
+    };
+    const byPath = new Map(pages.map((p) => [p.path, p]));
+    const dirs = readerDirectories(pages.map((p) => p.path));
+    const separators = new Map();
+    for (const dir of dirs) {
+        const path = posix(join(dir, 'index.md'));
+        const page = byPath.get(path);
+        let grouped = false;
+        if (!page)
+            report('directory-index', 'error', path, 'Reader-bearing directory needs index.md with a nonempty ## Contents map.');
+        else {
+            try {
+                const entries = parseIndexContents(page.body, path, {
+                    locations: true,
+                });
+                const retained = [];
+                for (const entry of entries) {
+                    const lexical = resolve(target.contentRoot, dir, entry.href.split('#')[0] ?? '');
+                    if (inside(target.contentRoot, lexical) &&
+                        isExcludedPath(target.matcher, posix(lexical.slice(target.contentRoot.length + 1))))
+                        continue;
+                    retained.push(entry);
+                    if (entry.description && /(?:\.\.\.|…)\s*$/.test(entry.description))
+                        report('contents-description', 'error', path, 'Contents description is truncated; finish the sentence.', entry.line);
+                    if (entry.separator)
+                        separators.set(entry.separator, { path, line: entry.line });
+                    try {
+                        // Existing strict Contents resolution owns local map semantics.
+                        await resolveEntryTarget(target.contentRoot, join(target.contentRoot, dir), dir, entry, ['.md', '.mdx'], target.matcher);
+                    }
+                    catch (error) {
+                        report('directory-index', 'error', path, String(error.message), entry.line);
+                    }
+                }
+                grouped = retained.some((e) => e.group !== undefined);
+                if (dir === '.' && !grouped) {
+                    if (retained.length > t.rootError)
+                        report('root-width', 'error', path, `Flat root has ${retained.length} Contents links; maximum ${t.rootError}.`);
+                    else if (retained.length > t.rootWarn)
+                        report('root-width', 'warn', path, `Flat root has ${retained.length} Contents links; group above ${t.rootWarn}.`);
+                }
+                const catalog = page.frontmatter.catalog === true ||
+                    page.source.includes('<!-- AUTOGENERATED by `oat docs generate-index`.');
+                if (!grouped && !catalog) {
+                    if (retained.length > t.contentsError)
+                        report('contents-width', 'error', path, `Ungrouped Contents has ${retained.length} links; maximum ${t.contentsError}.`);
+                    else if (retained.length > t.contentsWarn)
+                        report('contents-width', 'warn', path, `Ungrouped Contents has ${retained.length} links; group above ${t.contentsWarn}.`);
+                }
+                const contentsHeading = page.nodes.find((n) => n.type === 'heading' &&
+                    n.depth === 2 &&
+                    nodeText(n).trim() === 'Contents');
+                const words = page.nodes
+                    .filter((n) => n.type === 'paragraph' &&
+                    (n.position?.end.line ?? Infinity) <
+                        (contentsHeading?.position?.start.line ?? 0))
+                    .map(nodeText)
+                    .join(' ')
+                    .trim()
+                    .split(/\s+/)
+                    .filter(Boolean).length;
+                if (words < t.overviewWords)
+                    report('overview', 'warn', path, `Overview has ${words} words; use at least ${t.overviewWords} before Contents.`);
+            }
+            catch (error) {
+                report('directory-index', 'error', path, error.message);
+            }
+        }
+        const count = pages.filter((p) => dirname(p.path) === dir).length;
+        const child = dirs.some((d) => d !== dir && (dir === '.' || d.startsWith(`${dir}/`)));
+        if (!child) {
+            if (count === 1 && page)
+                report('leaf-size', 'error', path, 'Index-only leaf has no reader destination; flatten it or add its reader pages.');
+            else if (count === 2)
+                report('leaf-size', 'warn', path, 'Leaf has only two direct reader pages including index.md; consider flattening.');
+        }
+        if (!grouped) {
+            if (count > t.folderError)
+                report('folder-size', 'error', path, `Folder has ${count} direct reader pages including index; maximum ${t.folderError} without groups.`);
+            else if (count > t.folderWarn)
+                report('folder-size', 'warn', path, `Folder has ${count} direct reader pages including index; group above ${t.folderWarn}.`);
+        }
+        const depth = dir === '.' ? 0 : dir.split('/').length;
+        if (depth >= t.depthError)
+            report('depth', 'error', path, `Directory depth ${depth}; error at ${t.depthError} (content root is 0).`);
+        else if (depth >= t.depthWarn)
+            report('depth', 'warn', path, `Directory depth ${depth}; warning at ${t.depthWarn} (content root is 0).`);
+    }
+    if (separators.size > 1)
+        for (const { path, line } of separators.values())
+            report('contents-separator', 'warn', path, `Contents separators differ within this tree (${[...separators.keys()].sort().join(', ')}).`, line);
+    for (const p of pages) {
+        if (!p.frontmatterError) {
+            const desc = p.frontmatter.description;
+            if (typeof desc !== 'string' || !desc.trim())
+                report('description', 'error', p.path, 'Frontmatter description is required and must be nonempty.', 1);
+            else if (desc.trim().length < t.descriptionMin ||
+                desc.trim().length > t.descriptionMax)
+                report('description', 'warn', p.path, `Description has ${desc.trim().length} characters; expected ${t.descriptionMin}–${t.descriptionMax}.`, 1);
+        }
+        const h1 = p.nodes.filter((n) => n.type === 'heading' && n.depth === 1);
+        if (h1.length !== 1)
+            report('h1', 'error', p.path, `Expected one real H1; found ${h1.length}.`, h1[1]?.position?.start.line ?? 1);
+        const reference = p.frontmatter.type === 'reference' ||
+            /(?:^|\/)references?(?:\/|$)/.test(p.path);
+        const lines = p.source.split(/\r?\n/).length - (p.source.endsWith('\n') ? 1 : 0);
+        const limit = reference ? t.referenceLines : t.pageLines;
+        if (lines > limit)
+            report('page-length', 'warn', p.path, `Page has ${lines} physical source lines; limit ${limit}${reference ? ' for reference pages' : ''}.`);
+        const h3 = p.nodes.filter((n) => n.type === 'heading' && n.depth === 3).length;
+        if (reference && h3 > t.referenceH3)
+            report('page-length', 'warn', p.path, `Reference page has ${h3} real H3 headings; limit ${t.referenceH3}.`);
+        for (const link of p.links) {
+            const href = link.href;
+            if (/^(?:[a-z][a-z\d+.-]*:|\/\/)/i.test(href))
+                continue;
+            let pathname;
+            let anchor;
+            try {
+                const hash = href.indexOf('#');
+                pathname = decodeURIComponent((hash < 0 ? href : href.slice(0, hash)).split('?')[0]);
+                anchor = hash < 0 ? '' : decodeURIComponent(href.slice(hash + 1));
+            }
+            catch {
+                report('links', 'error', p.path, `Malformed percent encoding in link "${href}".`, link.line);
+                continue;
+            }
+            if (!pathname) {
+                if (anchor && !p.anchors.has(anchor))
+                    report('links', 'error', p.path, `Unresolved anchor "${href}".`, link.line);
+                continue;
+            }
+            if (pathname.startsWith('~/'))
+                continue; // provenance reports it, never read home paths
+            const file = pathname.startsWith('/')
+                ? resolve(target.contentRoot, `.${pathname}`)
+                : resolve(target.contentRoot, dirname(p.path), pathname);
+            if (!inside(target.contentRoot, file))
+                continue; // provenance warns without outside IO
+            const relativePath = posix(file.slice(target.contentRoot.length + 1));
+            if (isExcludedPath(target.matcher, relativePath))
+                continue;
+            let resolved = file;
+            let isFile = await containedFile(target.contentRoot, file);
+            if (!isFile && !extname(pathname)) {
+                for (const suffix of ['.md', '.mdx', '/index.md'])
+                    if (await containedFile(target.contentRoot, file + suffix)) {
+                        resolved = file + suffix;
+                        isFile = true;
+                        break;
+                    }
+            }
+            // Framework public assets have a separate explicit allowed root. Rendered
+            // absolute routes are validated only when they identify a reader file.
+            if (!isFile && pathname.startsWith('/') && link.image) {
+                const publicRoot = join(target.appRoot, 'public');
+                isFile =
+                    (await present(publicRoot)) &&
+                        (await containedFile(publicRoot, resolve(publicRoot, `.${pathname}`)));
+            }
+            if (!isFile &&
+                pathname.startsWith('/') &&
+                !link.image &&
+                !/\.mdx?$/.test(pathname))
+                continue;
+            if (!isFile)
+                report('links', 'error', p.path, `Unresolved in-root link "${href}".`, link.line);
+            else if (anchor && /\.mdx?$/.test(resolved)) {
+                const destination = byPath.get(posix(resolved.slice(target.contentRoot.length + 1)));
+                if (destination && !destination.anchors.has(anchor))
+                    report('links', 'error', p.path, `Unresolved anchor "${href}".`, link.line);
+            }
+        }
+    }
+}
+export function checkProvenance(target, pages, report) {
+    const patterns = [
+        /\.oat\//u,
+        /\b[Bb][Ll]-[\w-]+/u,
+        /(?:~\/|\/Users\/|\/home\/)/u,
+        ...(target.documentation.check?.provenance?.ticketPatterns ?? []).map((p) => new RegExp(p, 'u')),
+        ...(target.documentation.check?.provenance?.milestonePatterns ?? []).map((p) => new RegExp(p, 'u')),
+    ];
+    for (const p of pages) {
+        p.source.split(/\r?\n/).forEach((text, line) => {
+            if (patterns.some((pattern) => pattern.test(text)))
+                report('provenance', 'warn', p.path, 'Reader page contains a planning/backlog/home path or configured ticket/milestone pattern; remove it or record a reason-bearing decision-pointer exception.', line + 1);
+        });
+        for (const link of p.links) {
+            if (/^(?:[a-z][a-z\d+.-]*:|\/)/i.test(link.href))
+                continue;
+            const href = link.href.split(/[?#]/)[0];
+            let decoded;
+            try {
+                decoded = decodeURIComponent(href);
+            }
+            catch {
+                continue;
+            }
+            if (!inside(target.contentRoot, resolve(target.contentRoot, dirname(p.path), decoded)))
+                report('provenance', 'warn', p.path, `Link "${link.href}" escapes the docs root; target was not read.`, link.line);
+        }
+    }
+}

package/dist/commands/docs/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/docs/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AASpC,wBAAgB,iBAAiB,IAAI,OAAO,CAS3C"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/docs/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAUpC,wBAAgB,iBAAiB,IAAI,OAAO,CAU3C"}

package/dist/commands/docs/index.js

@@ -1,6 +1,7 @@
 import { Command } from 'commander';
 import { createDocsAnalyzeCommand } from './analyze.js';
 import { createDocsApplyCommand } from './apply.js';
+import { createDocsCheckCommand } from './check/check.js';
 import { createDocsGenerateIndexCommand } from './index-generate/index.js';
 import { createDocsInitCommand } from './init/index.js';
 import { createDocsMigrateCommand } from './migrate/index.js';
@@ -8,6 +9,7 @@ import { createDocsNavCommand } from './nav/index.js';
 export function createDocsCommand() {
     return new Command('docs')
         .description('OAT documentation bootstrap and maintenance commands')
+        .addCommand(createDocsCheckCommand())
         .addCommand(createDocsAnalyzeCommand())
         .addCommand(createDocsApplyCommand())
         .addCommand(createDocsGenerateIndexCommand())

package/dist/commands/docs/init/docs-commands.d.ts

@@ -4,5 +4,6 @@ export interface DocsCommands {
     dev: string;
     build: string;
 }
+export declare function shellQuote(value: string): string;
 export declare function buildDocsCommands(repoShape: DocsRepoShape, targetDir: string, appName: string): DocsCommands;
 //# sourceMappingURL=docs-commands.d.ts.map

package/dist/commands/docs/init/docs-commands.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"docs-commands.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/init/docs-commands.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEvD,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;CACf;AAMD,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,aAAa,EACxB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,GACd,YAAY,CAsBd"}
+{"version":3,"file":"docs-commands.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/init/docs-commands.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEvD,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;CACf;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAIhD;AAMD,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,aAAa,EACxB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,GACd,YAAY,CAsBd"}

package/dist/commands/docs/init/docs-commands.js

@@ -1,4 +1,9 @@
 import { normalize } from 'node:path';
+export function shellQuote(value) {
+    return /^[a-zA-Z0-9_./-]+$/.test(value)
+        ? value
+        : `'${value.replaceAll("'", "'\\''")}'`;
+}
 function isRootTarget(targetDir) {
     return targetDir.trim() === '' || normalize(targetDir) === '.';
 }
@@ -18,8 +23,8 @@ export function buildDocsCommands(repoShape, targetDir, appName) {
         };
     }
     return {
-        install: `cd ${targetDir} && pnpm install`,
-        dev: `cd ${targetDir} && pnpm dev`,
-        build: `cd ${targetDir} && pnpm build`,
+        install: `cd ${shellQuote(targetDir)} && pnpm install`,
+        dev: `cd ${shellQuote(targetDir)} && pnpm dev`,
+        build: `cd ${shellQuote(targetDir)} && pnpm build`,
     };
 }

package/dist/commands/docs/init/index.d.ts

@@ -9,6 +9,7 @@ interface DocsInitExecutionResult {
     createdFiles: string[];
     appRoot: string;
     rootPackagePatch?: RootPackagePatchResult;
+    installationAdvice?: string[];
     dryRun?: boolean;
     plannedFiles?: string[];
     preservedFiles?: string[];

package/dist/commands/docs/init/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/init/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,KAAK,mBAAmB,EAGxB,sBAAsB,EAEvB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAGL,KAAK,aAAa,EAClB,KAAK,YAAY,EAElB,MAAM,iCAAiC,CAAC;AAEzC,OAAO,EACL,KAAK,SAAS,EAGf,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AAU5C,OAAO,EAIL,KAAK,uBAAuB,EAK7B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAEL,KAAK,sBAAsB,EAC5B,MAAM,gBAAgB,CAAC;AAgBxB,UAAU,uBAAuB;IAC/B,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,gBAAgB,CAAC,EAAE,sBAAsB,CAAC;IAC1C,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,OAAO,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,EAAE,CAAC;QAAC,MAAM,EAAE,OAAO,CAAA;KAAE,CAAC;IAC/C,YAAY,CAAC,EACT,SAAS,GACT,SAAS,GACT,WAAW,GACX,QAAQ,GACR,eAAe,CAAC;IACpB,OAAO,CAAC,EAAE;QAAE,KAAK,EAAE,UAAU,GAAG,QAAQ,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CAC7D;AAED,UAAU,oBAAoB;IAC5B,mBAAmB,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,cAAc,CAAC;IAChE,iBAAiB,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IACzC,eAAe,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,GAAG,gBAAgB,CAAC,CAAC;IAC9E,gBAAgB,EAAE,CAChB,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,MAAM,EACpB,GAAG,EAAE,aAAa,KACf,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC5B,eAAe,EAAE,CAAC,CAAC,SAAS,MAAM,EAChC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,EAC1B,GAAG,EAAE,aAAa,KACf,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IACvB,WAAW,EAAE,CACX,OAAO,EAAE,cAAc,EACvB,OAAO,EAAE,uBAAuB,EAChC,UAAU,EAAE,MAAM,KACf,OAAO,CAAC,uBAAuB,GAAG,IAAI,CAAC,CAAC;IAC7C,qBAAqB,EAAE,CACrB,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,KACT,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAClC,sBAAsB,EAAE,OAAO,sBAAsB,CAAC;IACtD,aAAa,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC;IACxD,aAAa,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,aAAa,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CAC1E;AA2MD;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,uBAAuB,GAAG,MAAM,CAoC7E;AA0QD,wBAAgB,qBAAqB,CACnC,SAAS,GAAE,OAAO,CAAC,oBAAoB,CAAM,GAC5C,OAAO,CAiET"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/init/index.ts"],"names":[],"mappings":"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"}

package/dist/commands/docs/init/index.js

@@ -176,11 +176,16 @@ const DEFAULT_DEPENDENCIES = {
             context.logger.info(`  Format: ${options.format}`);
             if (rootPackagePatch)
                 logRootPackagePatch(context, rootPackagePatch);
+            for (const advice of result.installationAdvice ?? [])
+                context.logger.info(advice);
         }
         return {
             createdFiles: result.createdFiles,
             appRoot: result.appRoot,
             rootPackagePatch,
+            ...(result.installationAdvice
+                ? { installationAdvice: result.installationAdvice }
+                : {}),
         };
     },
     upsertAgentsMdSection,
@@ -384,6 +389,9 @@ async function runDocsInitCommand(context, options, dependencies) {
                         framework: resolved.framework,
                     },
                     guidance: sectionResult,
+                    ...(scaffold?.installationAdvice
+                        ? { installationAdvice: scaffold.installationAdvice }
+                        : {}),
                 });
             }
             else {

package/dist/commands/docs/init/scaffold.d.ts

@@ -7,6 +7,7 @@ export interface ScaffoldDocsAppResult {
     appRoot: string;
     createdFiles: string[];
     documentationConfig: OatDocumentationConfig;
+    installationAdvice?: string[];
 }
 export interface OatDepContext {
     isOatRepo: boolean;