polydeukes 0.6.0 → 0.6.1

package/dist/docs/tutorials/first-judgment.ko.md

@@ -0,0 +1,82 @@
+# 설치하고 첫 판정 확인하기
+
+[English](./first-judgment.md) · **한국어**
+
+빈 예제 프로젝트에 Polydeukes를 설치하고 보호된 파일을 바꾸지 않은 채 쓰기 요청의 판정
+결과를 확인합니다. Node.js 24 이상, pnpm, git이 필요합니다. 실제 세션 호출을 확인하려면
+Claude Code도 필요하지만, 아래 훅 검사 명령은 Claude Code 없이 실행할 수 있습니다.
+
+<a id="claude-code"></a>
+
+## 클로드 코드 연동 설치와 첫 쓰기 요청 검사
+
+기존에 보호 중인 프로젝트 밖에서, 자신의 터미널로 다음 명령을 실행합니다.
+
+```sh
+mkdir pdks-example
+cd pdks-example
+git init
+printf '{"name":"pdks-example","private":true}\n' > package.json
+pnpm add -D polydeukes   # 프로젝트 의존성. 일회성 npx 실행이 아님
+pnpm exec pdks init claude-code
+```
+
+설치기는 각 파일을 만들었으면 `created`, 이미 있어서 보존했으면 `skipped`로 보고합니다.
+초기 설정, 훅 위임 파일, Claude Code 등록 설정, 문서 조회 안내, `discipline-draft` 스킬과
+텔레메트리 제외 항목을 만듭니다. 기존 사용자 파일은 보존하고, 설정은 통째로 덮지 않고
+병합합니다.
+
+생성된 훅에 설정 파일을 쓰려는 요청을 전달합니다.
+
+```sh
+printf '%s\n' '{"tool_name":"Write","tool_input":{"file_path":".claude/settings.json","content":"{}"}}' \
+  | node .claude/hooks/covenant-pretooluse.mjs
+printf 'exit=%s\n' "$?"
+tail -n 5 .polydeukes/roi.log
+```
+
+예상 결과는 `exit=2`입니다. stderr에는 보호 경로를 지목한 메시지가 나오고, 로그에는
+`blocked` 행이 남습니다. 이 명령은 판정만 요청하며 **실제로 파일을 쓰지 않습니다**.
+설정 파일은 그대로이므로 되돌릴 변경도 없습니다.
+
+이번에는 보호 목록 밖의 경로로 같은 검사를 합니다.
+
+```sh
+printf '%s\n' '{"tool_name":"Write","tool_input":{"file_path":"example.txt","content":"hello"}}' \
+  | node .claude/hooks/covenant-pretooluse.mjs
+printf 'exit=%s\n' "$?"
+tail -n 5 .polydeukes/roi.log
+```
+
+초기 설정에서는 `exit=0`과 `passed` 행이 나와야 합니다. 이 명령도 파일을 쓰지는 않습니다.
+설치된 판정기로 차단할 요청과 허용할 요청을 각각 확인한 것입니다.
+
+실제 도구 호출에 훅을 적용하려면 이 프로젝트에서 Claude Code를 엽니다. 일반 텍스트 파일을
+만들도록 요청한 뒤 `.polydeukes/roi.log`에 새 행이 생기는지 확인합니다. 앞의 직접 호출
+검사만으로는 특정 호스트 세션이 훅 등록을 읽었다고 판단할 수 없습니다.
+
+**처음 설정을 바꾸기 전에 확인하세요.** 로더는 발견한 설정 파일을 자동으로 보호합니다.
+`protectedPaths`에 파일명이 없어도 같습니다. 세션에서 의도적으로 편집하려면
+`witness.token`을 읽고, 사람이 직접 메시지 첫 줄에 그 토큰만 입력합니다. 초기 토큰은
+`pdks witness`이며 유효 시간은 10분입니다. 증인(witness) 밸브는 판정기가 차단한 결과에만
+적용됩니다. 에이전트가 사람을 대신해 메시지를 공급할 수는 없습니다. 자신의 터미널에서
+의도한 설정 변경을 직접 수행해도 됩니다.
+
+패키지나 설정을 읽지 못해 검사가 실패하면 자신의 터미널에서 지목된 파일을 고치거나
+패키지를 다시 설치합니다. 밸브를 조립하는 단계에 이르기 전에 발생한 오류는 증인으로 해결할 수 없습니다.
+[설정 오류](../troubleshooting.ko.md#invalid-config)와
+[판정기 로드 실패](../troubleshooting.ko.md#judge-cannot-be-loaded)를 참고하세요.
+
+<a id="next-step"></a>
+
+## 실제 프로젝트에 적용하기
+
+- [프로젝트 설정](../how-to/configure-project.ko.md)에서 임시 언어 이름과 테스트 명령을
+  바꿉니다.
+- Grok이나 git pre-commit 훅은 [관측 표면 연결](../how-to/connect-surfaces.ko.md)을 참고합니다.
+- [규율 작성](../how-to/write-disciplines.ko.md) 예제를 실행하고, 권고 결과를 확인한 뒤 차단
+  여부를 결정합니다.
+
+종료 코드만으로 모든 관측 결과를 알 수는 없습니다. `advised`나 `skipped`가 있어도 exit 0일
+수 있습니다. 진단 메시지와 [판정 결과 어휘](../troubleshooting.ko.md#reading-verdict)를 함께
+확인하세요.

package/dist/docs/tutorials/first-judgment.md

@@ -0,0 +1,81 @@
+# Install and get your first judgment
+
+**English** · [한국어](./first-judgment.ko.md)
+
+Use an empty example project to install Polydeukes and check a protected write without changing
+the protected file. You need Node.js 24 or later, pnpm, and git. Claude Code is needed to observe
+live session calls, but not to run the hook probe below.
+
+<a id="claude-code"></a>
+
+## Install Claude Code integration and check a write
+
+Run these commands in your own terminal, outside an existing protected project:
+
+```sh
+mkdir pdks-example
+cd pdks-example
+git init
+printf '{"name":"pdks-example","private":true}\n' > package.json
+pnpm add -D polydeukes   # a project dependency, not a one-off npx run
+pnpm exec pdks init claude-code
+```
+
+The installer reports `created` or `skipped` for each artifact. It creates a starter config,
+the hook delegator, the Claude Code registration, a documentation discovery file, the
+`discipline-draft` skill, and a telemetry ignore entry. Existing user files are preserved;
+settings are merged rather than replaced.
+
+Now send the generated hook an observation of a proposed write to its settings file:
+
+```sh
+printf '%s\n' '{"tool_name":"Write","tool_input":{"file_path":".claude/settings.json","content":"{}"}}' \
+  | node .claude/hooks/covenant-pretooluse.mjs
+printf 'exit=%s\n' "$?"
+tail -n 5 .polydeukes/roi.log
+```
+
+Expect `exit=2`, a diagnostic naming the protected path on stderr, and a `blocked` row in the
+log. This command only asks for a judgment. It does **not** perform the proposed write, so the
+settings file stays unchanged and there is no destructive edit to undo.
+
+Repeat with a path outside the protection list:
+
+```sh
+printf '%s\n' '{"tool_name":"Write","tool_input":{"file_path":"example.txt","content":"hello"}}' \
+  | node .claude/hooks/covenant-pretooluse.mjs
+printf 'exit=%s\n' "$?"
+tail -n 5 .polydeukes/roi.log
+```
+
+Expect `exit=0` and a `passed` row for this starter configuration. Again, no file is written.
+You have checked both a blocked and an allowed observation using the installed judge.
+
+Open Claude Code in this project to use the same hook on actual tool calls. Ask it to create
+an ordinary text file, then confirm that a new row appears in `.polydeukes/roi.log`. The direct
+probe above does not prove that a particular host session loaded its hook registration.
+
+**Before the first config edit:** the loader automatically protects the discovered config
+file, even though it is not written in `protectedPaths`. For an intentional session edit, read
+`witness.token` and type that token yourself on the first line of a message, with nothing else
+on that line. The starter token is `pdks witness` and its window is ten minutes. The valve
+supplies permission only after a blocking verdict; an agent cannot supply the human message
+for you. Alternatively, make the deliberate configuration edit from your own terminal.
+
+If the probe fails because the package or configuration cannot load, repair the named file or
+reinstall from your own terminal. A witness cannot repair a failure that occurs before the
+valve is assembled. See [configuration errors](../troubleshooting.md#invalid-config) and
+[missing judge](../troubleshooting.md#judge-cannot-be-loaded).
+
+<a id="next-step"></a>
+
+## Continue with a real project
+
+- [Configure the project](../how-to/configure-project.md) to replace the placeholder language
+  and test command.
+- [Connect the surfaces](../how-to/connect-surfaces.md) for Grok or a git pre-commit hook.
+- [Write a discipline](../how-to/write-disciplines.md) and observe an advisory before choosing
+  whether it should block.
+
+An exit code alone does not describe all observations. `advised` and `skipped` can accompany
+exit 0. Read the diagnostic and the [verdict vocabulary](../troubleshooting.md#reading-verdict).

package/dist/docs-catalog.d.ts

@@ -0,0 +1,25 @@
+import type { DocsBundleDocument, DocsBundleSection, DocsIndex, LoadedDocsBundle } from './docs-types.ts';
+/**
+ * Validate the source collection before replacing the output with bundled Markdown and metadata.
+ *
+ * @param spec - Source and non-overlapping output roots, with an optional catalog file path.
+ * @returns Metadata for bundled documents and sections; excluded documents are not copied.
+ * @throws If the roots overlap or the catalog, source files, or topic references fail validation.
+ */
+export declare function buildDocs(spec: {
+    sourceRoot: string;
+    outputRoot: string;
+    catalogPath?: string;
+}): {
+    documents: DocsBundleDocument[];
+    sections: DocsBundleSection[];
+};
+/**
+ * Load a bundle only after its stored index matches the catalog and bundled Markdown.
+ *
+ * @param outputRoot - Built documentation directory containing catalog.json and index.json.
+ * @returns Validated metadata and bundled documents with their original Markdown and sections.
+ * @throws If metadata or documents are missing, invalid, or inconsistent with the stored index.
+ */
+export declare function loadDocsBundle(outputRoot: string): LoadedDocsBundle;
+export type { DocsIndex };

package/dist/docs-catalog.js

@@ -0,0 +1,450 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, rmSync, writeFileSync, } from 'node:fs';
+import { dirname, isAbsolute, join, normalize, relative, resolve, sep } from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+import { hashMarkdown, parseSections } from './docs-markdown.js';
+const catalogSchemaVersion = 1;
+const supportedLanguages = ['en', 'ko'];
+const markdownPattern = /\.md$/i;
+function fail(message) {
+    throw new Error(message);
+}
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function assertString(value, message) {
+    if (typeof value !== 'string' || value === '')
+        fail(message);
+    return value;
+}
+function assertOptionalTerms(value, message) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value) || value.some((entry) => typeof entry !== 'string' || entry === '')) {
+        fail(message);
+    }
+    return value;
+}
+function assertTranslation(value, label) {
+    if (!isPlainObject(value))
+        fail(`invalid ${label} translation`);
+    return {
+        path: assertString(value.path, `invalid ${label} path`),
+        title: assertString(value.title, `invalid ${label} title`),
+        summary: assertString(value.summary, `invalid ${label} summary`),
+        terms: assertOptionalTerms(value.terms, `invalid ${label} terms`),
+    };
+}
+function assertReference(value) {
+    if (!isPlainObject(value))
+        fail('invalid topic reference');
+    const documentId = assertString(value.documentId, 'invalid topic documentId');
+    const sectionId = value.sectionId;
+    if (sectionId !== undefined && (typeof sectionId !== 'string' || sectionId === '')) {
+        fail('invalid topic sectionId');
+    }
+    return { documentId, ...(sectionId === undefined ? {} : { sectionId }) };
+}
+function assertDocument(value) {
+    if (!isPlainObject(value))
+        fail('invalid document entry');
+    if (typeof value.bundled !== 'boolean')
+        fail('invalid bundled flag');
+    if (typeof value.order !== 'number')
+        fail('invalid document order');
+    const document = {
+        id: assertString(value.id, 'invalid document id'),
+        category: assertString(value.category, 'invalid document category'),
+        order: Number(value.order),
+        bundled: value.bundled === true,
+        en: assertTranslation(value.en, 'en'),
+    };
+    if (!Number.isInteger(document.order))
+        fail(`invalid order for ${document.id}`);
+    if (value.ko !== undefined)
+        document.ko = assertTranslation(value.ko, 'ko');
+    return document;
+}
+function assertCatalog(value) {
+    if (!isPlainObject(value))
+        fail('invalid catalog json');
+    const schemaVersion = value.schemaVersion;
+    if (schemaVersion !== catalogSchemaVersion)
+        fail('unsupported catalog schema version');
+    if (!Array.isArray(value.documents))
+        fail('invalid documents list');
+    if (!isPlainObject(value.topics))
+        fail('invalid topics map');
+    const redirects = value.redirects === undefined ? [] : value.redirects;
+    if (!Array.isArray(redirects))
+        fail('invalid redirects list');
+    const catalog = {
+        schemaVersion: catalogSchemaVersion,
+        documents: value.documents.map(assertDocument),
+        topics: Object.fromEntries(Object.entries(value.topics).map(([topicId, topic]) => {
+            if (!isPlainObject(topic))
+                fail(`invalid topic ${topicId}`);
+            return [
+                topicId,
+                {
+                    references: Array.isArray(topic.references)
+                        ? topic.references.map(assertReference)
+                        : fail(`invalid topic references for ${topicId}`),
+                    seeAlso: assertString(topic.seeAlso, `invalid seeAlso for ${topicId}`),
+                },
+            ];
+        })),
+        redirects: redirects.map((entry) => {
+            if (!isPlainObject(entry))
+                fail('invalid redirect entry');
+            return {
+                path: assertString(entry.path, 'invalid redirect path'),
+                target: assertString(entry.target, 'invalid redirect target'),
+            };
+        }),
+    };
+    return catalog;
+}
+function safeRelativePath(path) {
+    if (isAbsolute(path) || path.includes('\\') || /^[A-Za-z]:/.test(path)) {
+        fail(`absolute or non-portable path rejected: ${path}`);
+    }
+    const segments = path.split('/');
+    if (segments.some((segment) => segment === '' || segment === '.' || segment === '..')) {
+        fail(`escaping path rejected: ${path}`);
+    }
+    const normalized = normalize(path).replace(/\\/g, '/');
+    if (normalized === '.' || normalized === '')
+        fail('invalid empty path');
+    return normalized;
+}
+function physicalPath(path) {
+    const absolute = resolve(path);
+    if (existsSync(absolute))
+        return realpathSync(absolute);
+    const parent = dirname(absolute);
+    if (parent === absolute)
+        return absolute;
+    return join(physicalPath(parent), relative(parent, absolute));
+}
+function contains(root, path) {
+    const distance = relative(root, path);
+    return distance !== '..' && !distance.startsWith(`..${sep}`) && !isAbsolute(distance);
+}
+function validateDocsRootOverlap(sourceRoot, outputRoot) {
+    const source = physicalPath(sourceRoot);
+    const output = physicalPath(outputRoot);
+    if (contains(source, output) || contains(output, source))
+        fail('source and output roots overlap');
+}
+function walkMarkdown(root) {
+    const result = [];
+    const stack = [root];
+    while (stack.length > 0) {
+        const current = stack.pop();
+        for (const entry of readdirSync(current, { withFileTypes: true })) {
+            const path = join(current, entry.name);
+            if (entry.isDirectory())
+                stack.push(path);
+            else if (markdownPattern.test(entry.name))
+                result.push(relative(root, path).replace(/\\/g, '/'));
+        }
+    }
+    return result.sort((left, right) => left.localeCompare(right));
+}
+function readMarkdown(root, path) {
+    const absolute = resolve(root, path);
+    if (!contains(resolve(root), absolute))
+        fail(`path escapes source root: ${path}`);
+    if (!existsSync(absolute))
+        fail(`missing source markdown: ${path}`);
+    if (!contains(realpathSync(root), realpathSync(absolute)))
+        fail(`source symlink escapes root: ${path}`);
+    return readFileSync(absolute, 'utf8');
+}
+function validateDocumentPaths(document) {
+    for (const [language, translation] of Object.entries({ en: document.en, ko: document.ko })) {
+        if (!translation)
+            fail(`missing ${language} translation for ${document.id}`);
+        safeRelativePath(translation.path);
+        if (!translation.path.endsWith(language === 'en' ? '.md' : '.ko.md') ||
+            (language === 'en' && translation.path.endsWith('.ko.md'))) {
+            fail(`translation path suffix mismatch for ${document.id}:${language}`);
+        }
+    }
+}
+function validateDocumentIds(documents) {
+    const ids = new Set();
+    for (const document of documents) {
+        if (ids.has(document.id))
+            fail(`duplicate document id: ${document.id}`);
+        if (!/^[a-z0-9][a-z0-9-]*$/.test(document.id)) {
+            fail(`invalid document id: ${document.id}`);
+        }
+        ids.add(document.id);
+    }
+}
+function validateTopicMap(catalog) {
+    for (const [topicId, topic] of Object.entries(catalog.topics)) {
+        if (topic.references.length === 0)
+            fail(`empty topic references: ${topicId}`);
+        if (typeof topic.seeAlso !== 'string' || topic.seeAlso === '')
+            fail(`invalid seeAlso: ${topicId}`);
+    }
+}
+function validateRedirects(catalog) {
+    const paths = new Set();
+    for (const redirect of catalog.redirects ?? []) {
+        safeRelativePath(redirect.path);
+        safeRelativePath(redirect.target);
+        if (paths.has(redirect.path))
+            fail(`duplicate redirect path: ${redirect.path}`);
+        paths.add(redirect.path);
+    }
+}
+function assertAllSourceMarkdownRegistered(catalog, sourceRoot) {
+    const registered = new Set();
+    const register = (path) => {
+        const safe = safeRelativePath(path);
+        if (registered.has(safe))
+            fail(`duplicate document path: ${path}`);
+        registered.add(safe);
+    };
+    for (const document of catalog.documents) {
+        register(document.en.path);
+        if (document.ko)
+            register(document.ko.path);
+    }
+    for (const redirect of catalog.redirects ?? []) {
+        if (!registered.has(redirect.target))
+            fail(`unknown redirect target: ${redirect.target}`);
+        readMarkdown(sourceRoot, redirect.path);
+    }
+    for (const redirect of catalog.redirects ?? [])
+        register(redirect.path);
+    for (const path of walkMarkdown(sourceRoot)) {
+        if (!registered.has(safeRelativePath(path))) {
+            fail(`unregistered source markdown: ${path}`);
+        }
+    }
+}
+function validateTopicsAgainstDocuments(catalog) {
+    const ids = new Set(catalog.documents.filter((document) => document.bundled).map((document) => document.id));
+    for (const [topicId, topic] of Object.entries(catalog.topics)) {
+        if (!ids.has(topic.seeAlso))
+            fail(`unknown seeAlso for ${topicId}: ${topic.seeAlso}`);
+        for (const reference of topic.references) {
+            if (!ids.has(reference.documentId))
+                fail(`unknown topic reference for ${topicId}: ${reference.documentId}`);
+        }
+    }
+}
+function validateBundledDocument(document, sourceRoot) {
+    const enMarkdown = readMarkdown(sourceRoot, document.en.path);
+    const ko = document.ko;
+    if (!ko)
+        fail(`missing ko translation for ${document.id}`);
+    const koMarkdown = readMarkdown(sourceRoot, ko.path);
+    const enSections = document.bundled ? parseSections(enMarkdown, { requireAnchors: true }) : [];
+    const koSections = document.bundled ? parseSections(koMarkdown, { requireAnchors: true }) : [];
+    if (document.bundled) {
+        const enIds = enSections.map((section) => section.id).sort();
+        const koIds = koSections.map((section) => section.id).sort();
+        if (enIds.length !== koIds.length || enIds.some((id, index) => id !== koIds[index])) {
+            fail(`bundled section set mismatch for ${document.id}`);
+        }
+    }
+    return {
+        id: document.id,
+        bundled: document.bundled,
+        category: document.category,
+        order: document.order,
+        translations: {
+            en: {
+                ...document.en,
+                terms: document.en.terms ?? [],
+                markdown: enMarkdown,
+                hash: hashMarkdown(enMarkdown),
+                sections: enSections,
+            },
+            ko: {
+                ...ko,
+                terms: ko.terms ?? [],
+                markdown: koMarkdown,
+                hash: hashMarkdown(koMarkdown),
+                sections: koSections,
+            },
+        },
+    };
+}
+function buildIndexDocument(document) {
+    return {
+        id: document.id,
+        bundled: document.bundled,
+        category: document.category,
+        order: document.order,
+        translations: {
+            en: {
+                path: document.translations.en.path,
+                title: document.translations.en.title,
+                summary: document.translations.en.summary,
+                ...(document.translations.en.terms.length > 0
+                    ? { terms: document.translations.en.terms }
+                    : {}),
+            },
+            ko: {
+                path: document.translations.ko.path,
+                title: document.translations.ko.title,
+                summary: document.translations.ko.summary,
+                ...(document.translations.ko.terms.length > 0
+                    ? { terms: document.translations.ko.terms }
+                    : {}),
+            },
+        },
+        hashes: {
+            en: document.translations.en.hash,
+            ko: document.translations.ko.hash,
+        },
+    };
+}
+function buildIndexSections(document) {
+    if (!document.bundled)
+        return [];
+    const sections = [];
+    for (const language of supportedLanguages) {
+        const translation = document.translations[language];
+        for (const section of translation.sections) {
+            sections.push({
+                documentId: document.id,
+                language,
+                sectionId: section.id,
+                title: section.title,
+                level: section.level,
+                path: translation.path,
+                hash: translation.hash,
+            });
+        }
+    }
+    return sections;
+}
+function copyBundleDocuments(outputRoot, documents) {
+    for (const document of documents.values()) {
+        for (const language of supportedLanguages) {
+            const translation = document.translations[language];
+            if (!document.bundled)
+                continue;
+            const destination = resolve(outputRoot, translation.path);
+            mkdirSync(dirname(destination), { recursive: true });
+            writeFileSync(destination, translation.markdown, 'utf8');
+        }
+    }
+}
+function validateTopicSections(catalog, documents) {
+    for (const [topic, entry] of Object.entries(catalog.topics)) {
+        for (const reference of entry.references) {
+            const document = documents.find((candidate) => candidate.id === reference.documentId);
+            if (!document?.bundled)
+                fail(`topic ${topic} references an excluded document`);
+            if (reference.sectionId !== undefined &&
+                !document.translations.en.sections.some((section) => section.id === reference.sectionId))
+                fail(`unknown topic section: ${topic}/${reference.sectionId}`);
+        }
+    }
+}
+function createIndex(documents) {
+    const bundled = documents.filter((document) => document.bundled);
+    return {
+        schemaVersion: catalogSchemaVersion,
+        documents: bundled
+            .sort((left, right) => left.order - right.order || compare(left.id, right.id))
+            .map(buildIndexDocument),
+        sections: bundled
+            .flatMap(buildIndexSections)
+            .sort((left, right) => compare(left.documentId, right.documentId) ||
+            compare(left.language, right.language) ||
+            compare(left.sectionId, right.sectionId)),
+    };
+}
+function compare(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function writeJson(path, value) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+}
+function loadBundle(outputRoot) {
+    const catalogPath = join(outputRoot, 'catalog.json');
+    const indexPath = join(outputRoot, 'index.json');
+    if (!existsSync(catalogPath) || !existsSync(indexPath))
+        fail('missing docs bundle metadata');
+    const catalog = assertCatalog(JSON.parse(readFileSync(catalogPath, 'utf8')));
+    validateDocumentIds(catalog.documents);
+    for (const document of catalog.documents)
+        validateDocumentPaths(document);
+    validateTopicMap(catalog);
+    validateTopicsAgainstDocuments(catalog);
+    const loaded = catalog.documents
+        .filter((document) => document.bundled)
+        .map((document) => validateBundledDocument(document, outputRoot));
+    validateTopicSections(catalog, loaded);
+    const index = createIndex(loaded);
+    const stored = JSON.parse(readFileSync(indexPath, 'utf8'));
+    if (!isDeepStrictEqual(stored, index))
+        fail('docs bundle index or integrity hash mismatch');
+    const documents = new Map(loaded.map((document) => [document.id, document]));
+    return { catalog, index, documents, topics: catalog.topics };
+}
+/**
+ * Validate the source collection before replacing the output with bundled Markdown and metadata.
+ *
+ * @param spec - Source and non-overlapping output roots, with an optional catalog file path.
+ * @returns Metadata for bundled documents and sections; excluded documents are not copied.
+ * @throws If the roots overlap or the catalog, source files, or topic references fail validation.
+ */
+export function buildDocs(spec) {
+    const catalogPath = spec.catalogPath ?? join(spec.sourceRoot, 'catalog.json');
+    validateDocsRootOverlap(spec.sourceRoot, spec.outputRoot);
+    if (!existsSync(catalogPath))
+        fail(`missing catalog: ${catalogPath}`);
+    const catalog = assertCatalog(JSON.parse(readFileSync(catalogPath, 'utf8')));
+    validateDocumentIds(catalog.documents);
+    for (const document of catalog.documents)
+        validateDocumentPaths(document);
+    validateTopicMap(catalog);
+    validateRedirects(catalog);
+    validateTopicsAgainstDocuments(catalog);
+    assertAllSourceMarkdownRegistered(catalog, spec.sourceRoot);
+    const documents = catalog.documents.map((document) => validateBundledDocument(document, spec.sourceRoot));
+    validateTopicSections(catalog, documents);
+    const index = createIndex(documents);
+    rmSync(spec.outputRoot, { recursive: true, force: true });
+    mkdirSync(spec.outputRoot, { recursive: true });
+    writeJson(join(spec.outputRoot, 'catalog.json'), catalog);
+    writeJson(join(spec.outputRoot, 'index.json'), index);
+    const loadedBundle = {
+        catalog,
+        index,
+        documents: new Map(documents.map((document) => [document.id, document])),
+        topics: catalog.topics,
+    };
+    copyBundleDocuments(spec.outputRoot, loadedBundle.documents);
+    return {
+        documents: index.documents.map((entry) => ({
+            id: entry.id,
+            bundled: entry.bundled,
+            category: entry.category,
+            order: entry.order,
+            translations: entry.translations,
+        })),
+        sections: index.sections,
+    };
+}
+/**
+ * Load a bundle only after its stored index matches the catalog and bundled Markdown.
+ *
+ * @param outputRoot - Built documentation directory containing catalog.json and index.json.
+ * @returns Validated metadata and bundled documents with their original Markdown and sections.
+ * @throws If metadata or documents are missing, invalid, or inconsistent with the stored index.
+ */
+export function loadDocsBundle(outputRoot) {
+    return loadBundle(outputRoot);
+}

package/dist/docs-library.d.ts

@@ -0,0 +1,23 @@
+import { buildDocs as buildDocsImpl } from './docs-catalog.ts';
+/** Inputs for one query against the installed documentation bundle. */
+export type RunDocsSpec = {
+    docsRoot: string;
+    args: string[];
+    version: string;
+};
+/** Complete stdout, returned only after validation and reading succeed. */
+export type RunDocsOutcome = {
+    text: string;
+};
+/** Source catalog and destination for a reproducible documentation build. */
+export type BuildDocsSpec = {
+    sourceRoot: string;
+    outputRoot: string;
+    catalogPath?: string;
+};
+/** Documents and sections included in a successful bundle. */
+export type BuildDocsOutcome = ReturnType<typeof buildDocsImpl>;
+/** Validate the source collection and replace the bundle, removing retired files. */
+export declare function buildDocs(spec: BuildDocsSpec): BuildDocsOutcome;
+/** Answer a docs-only command without loading project configuration or the judge. */
+export declare function runDocs(spec: RunDocsSpec): RunDocsOutcome;