@devp0nt/doc0 0.0.0 → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025–2026 Sergei Dmitriev <https://p0nt.dev>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,272 @@
+# @devp0nt/doc0
+
+> One navigable, searchable collection from the docs you already write.
+
+[![CI](https://github.com/devp0nt/doc0/actions/workflows/ci.yml/badge.svg)](https://github.com/devp0nt/doc0/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/@devp0nt/doc0.svg)](https://www.npmjs.com/package/@devp0nt/doc0)
+[![license](https://img.shields.io/npm/l/@devp0nt/doc0.svg)](./LICENSE)
+
+<!-- docs:start -->
+
+You already write docs — JSDoc, code comments, Markdown. They're write-only:
+scattered across the repo, and invisible to the AI agents that need them most.
+So the agent re-derives your conventions every time, and sometimes guesses
+wrong.
+
+doc0 parses every doc carrier into **one normalized, linked collection**, then
+serves it where it's useful: to agents over **MCP**, to you over a **local web
+UI**, and to your build as **generated files**. No new format to learn — it
+reads the docs you already have.
+
+```ts
+// docs/index.ts — point doc0 at the docs you already write, export the engine
+import { Doc0 } from '@devp0nt/doc0'
+
+export const doc0 = Doc0.create({
+  glob: ['src/**/*.ts', 'docs/**/*.md', '!**/*.test.ts'],
+})
+```
+
+Any JSDoc with a doc0 directive becomes a doc — id, tags, and a `@related`
+graph, all from a comment you'd write anyway:
+
+```ts
+/**
+ * Money is stored in minor units (cents). Never do currency math in the UI —
+ * format through here.
+ *
+ * @id money
+ * @tags rule, money
+ * @related cart-total
+ */
+export const formatMoney = (minor: number): string =>
+  `$${(minor / 100).toFixed(2)}`
+```
+
+```sh
+bunx doc0 mcp   # serve every doc to your agent: list_docs / search_docs / get_doc
+```
+
+Now the agent asks `list_docs({ tag: "rule" })` and reads the rule **with a
+pointer to the exact file and line** — instead of guessing.
+
+## Install
+
+doc0 is a dev tool — add it as a dev dependency:
+
+```sh
+bun add -d @devp0nt/doc0
+# or: npm i -D / pnpm add -D / yarn add -D
+```
+
+MCP, the web UI, keyword search, and export work out of the box — nothing else
+to install. Only **semantic** search is opt-in (it pulls a local ML model,
+hundreds of MB):
+
+```sh
+bun add -d @huggingface/transformers
+```
+
+Bun 1+ or Node.js 20+. ESM only.
+
+## Configure once
+
+One config module exports the engine. Runners (the CLI, the MCP/web servers)
+load it — the config itself runs nothing.
+
+```ts
+// docs/index.ts
+import { Doc0 } from '@devp0nt/doc0'
+
+export const doc0 = Doc0.create({
+  // code files: a JSDoc joins the collection when it has a doc0 directive.
+  // markdown files: every match joins, unless its frontmatter says `doc: false`.
+  glob: ['src/**/*.ts', 'docs/**/*.md', 'README.md', '!**/*.test.ts'],
+  // map a category id to a human title (drives grouping in the web UI and export)
+  category: { rule: 'Rules', util: 'Utilities' },
+})
+```
+
+A doc has a small, fixed shape: `id`, `title`, `description`, `tags`,
+`category`, `related`, `content`, and `source` (file + line span). Missing
+fields are filled from the content — `title` from the first heading, `id` from
+the symbol or file name — so a bare `## Heading` markdown file is already a
+valid doc.
+
+## Your agent reads the rules you already wrote
+
+This is the point. Replace a folder of static `.cursor/rules` / `CLAUDE.md` rule
+files with one instruction that points at doc0:
+
+```md
+<!-- AGENTS.md -->
+
+Before any task: call `list_docs({ tag: "rule" })`, read each rule's
+description, and `get_doc` the ones relevant to your task. Then follow them.
+Search the rest with `search_docs("…")` before guessing.
+```
+
+The MCP server exposes a small, fixed tool set any agent understands — it scales
+to a project with hundreds of docs, where one-tool-per-doc would not:
+
+```sh
+bunx doc0 mcp
+```
+
+| Tool          | What it returns                                               |
+| ------------- | ------------------------------------------------------------- |
+| `list_docs`   | table of contents — paged, filter by `tag` / `category`       |
+| `search_docs` | top matches with snippets                                     |
+| `get_doc`     | one doc in full, with `source` and an enriched `related` list |
+
+Every tool takes a `fields` list to trim the response, and `source` carries the
+file path and line span — so the agent can jump from a rule straight to the code
+it governs.
+
+## Browse and search them yourself
+
+```sh
+bunx doc0 web   # http://localhost:4000 — sidebar grouped by category, search, rendered markdown
+```
+
+A real built-in UI: server-rendered Markdown with highlighted code, a search
+box, and a "Related" section on every doc. Offline, no frontend build step.
+
+## Search by keyword, or by meaning
+
+Search works out of the box (orama keyword/BM25). For "find by meaning", install
+the embeddings package and turn it on — the small model downloads once, runs
+locally, no API key:
+
+```ts
+import { Doc0 } from '@devp0nt/doc0'
+import { oramaSearch } from '@devp0nt/doc0/search'
+
+export const doc0 = Doc0.create({
+  glob: ['src/**/*.ts', 'docs/**/*.md'],
+  search: oramaSearch({ embeddings: true }), // hybrid keyword + semantic
+})
+```
+
+```sh
+bunx doc0 search "how do we format prices"   # => money, cart-total, …
+```
+
+## Export the whole collection
+
+Dump everything (optionally filtered) to one file — for a hand-off, a PR, or
+another tool:
+
+```sh
+bunx doc0 export --format md > docs.md        # one Markdown bundle: TOC + every doc
+bunx doc0 export --format md --tag rule -o rules.md
+bunx doc0 export --format json --fields id,title,source
+```
+
+## Keep generated files in sync
+
+Need Cursor rule files, a JSON index, or any other artifact? Generate them from
+the collection — writes happen only when content changes:
+
+```ts
+export const doc0 = Doc0.create({
+  glob: ['src/**/*.ts', 'docs/**/*.md'],
+  // per-doc output
+  generate: (doc) =>
+    doc.tags.includes('rule')
+      ? { path: `.cursor/rules/${doc.id}.mdc`, content: doc.content }
+      : undefined,
+  // whole-collection output
+  finalGenerate: (docs) => ({
+    path: 'docs/source.json',
+    content: docs.toJSON(),
+  }),
+})
+```
+
+```sh
+bunx doc0 sync            # parse → run generators (once)
+bunx doc0 sync --watch    # re-run on change
+```
+
+`collect()` is always fresh on its own (it re-scans changed files by mtime), so
+the MCP and web servers never serve stale docs — no watcher needed for reads.
+
+## Reference
+
+### CLI
+
+```sh
+doc0 list   [path]   # table of contents — --tag --category --fields --limit --offset --json
+doc0 get    <id>     # one doc in full — --fields --json
+doc0 search <query>  # keyword + semantic — --limit --fields --json
+doc0 export [path]   # whole collection → file — --format md|json --tag --category -o
+doc0 sync   [path]   # run generators (diff-only) — --watch
+doc0 mcp    [path]   # serve over MCP (stdio)
+doc0 web    [path]   # serve the web UI — --port
+doc0 prune  [path]   # drop the on-disk cache
+```
+
+`path` is optional — defaults to `docs/index.ts` (or `doc0.config.ts`), or pass
+any path to the config module.
+
+### Directives
+
+In a JSDoc comment (any one of these makes the comment a doc), or in Markdown
+frontmatter:
+
+| Directive      | Meaning                                                             |
+| -------------- | ------------------------------------------------------------------- |
+| `@id`          | stable id (else the symbol or file name)                            |
+| `@title`       | title (else the first heading, else a humanized id)                 |
+| `@description` | one-line summary (else the first content line)                      |
+| `@tags`        | comma list; `rule` is just a tag                                    |
+| `@category`    | grouping tag(s) — drive folders and the web sidebar                 |
+| `@related`     | linked ids; a trailing `!` (e.g. `@related setup!`) means must-read |
+| `@doc`         | force-include a comment that has no other directive                 |
+
+Markdown joins by glob; opt a file out with `doc: false` in its frontmatter.
+
+### Packages
+
+| Import                  | What                                                      |
+| ----------------------- | --------------------------------------------------------- |
+| `@devp0nt/doc0`         | `Doc0` / `Docs`, parsers, collect / sync / watch, export  |
+| `@devp0nt/doc0/parsers` | the built-in parsers + the `Parser` contract for your own |
+| `@devp0nt/doc0/mcp`     | `serveMcp(src)` — the MCP server                          |
+| `@devp0nt/doc0/search`  | `oramaSearch()` — keyword by default, semantic opt-in     |
+| `@devp0nt/doc0/web`     | `serveWeb(src)` — the web server + UI                     |
+
+A runnable end-to-end project lives in [`examples/minimal`](./examples/minimal).
+
+## Requirements
+
+- **Bun 1+** or **Node.js 20+** (ESM only)
+- **TypeScript 5+** (optional — works in plain JS too)
+
+<!-- docs:end -->
+
+## Community
+
+Questions, bugs, or want to hang with other builders? Join the devp0nt community
+— one hub for all our open-source projects, this one included. Get help, share
+what you built, or just say hi: [p0nt.dev/community](https://p0nt.dev/community)
+
+## Contributing
+
+Issues and PRs welcome. See [CONTRIBUTING.md](./CONTRIBUTING.md) and the
+[Code of Conduct](./CODE_OF_CONDUCT.md). Commits follow
+[Conventional Commits](https://www.conventionalcommits.org/). Security reports:
+[SECURITY.md](./SECURITY.md).
+
+## License
+
+[MIT](./LICENSE)
+
+---
+
+```text
+Building open-source software for the glory of the Lord Jesus Christ ☦️
+With love for developers of all backgrounds around the world ❤️
+Sergei Dmitriev, 2026 😎
+```

package/dist/cache.d.ts

@@ -0,0 +1,13 @@
+import { Cache } from "./types.js";
+
+//#region src/cache.d.ts
+/** A short, stable content hash used to key the cache. */
+declare const hash: (input: string) => string;
+/** In-memory cache — fast, never persists. */
+declare const memoryCache: () => Cache;
+/** File-backed, content-addressed cache: each key → one JSON file under `dir`. */
+declare const fileCache: (dir?: string) => Cache;
+/** Resolve the `cache` option to a concrete {@link Cache}. */
+declare const resolveCache: (cache?: boolean | string | Cache) => Cache;
+//#endregion
+export { fileCache, hash, memoryCache, resolveCache };

package/dist/cache.js

@@ -0,0 +1,50 @@
+import { createHash } from "node:crypto";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+//#region src/cache.ts
+/** A short, stable content hash used to key the cache. */
+const hash = (input) => createHash("sha256").update(input).digest("hex").slice(0, 32);
+/** In-memory cache — fast, never persists. */
+const memoryCache = () => {
+	const store = /* @__PURE__ */ new Map();
+	return {
+		get: (key) => Promise.resolve(store.get(key)),
+		set: (key, value) => {
+			store.set(key, value);
+			return Promise.resolve();
+		}
+	};
+};
+const DEFAULT_DIR = "node_modules/.cache/doc0";
+/** File-backed, content-addressed cache: each key → one JSON file under `dir`. */
+const fileCache = (dir = DEFAULT_DIR) => {
+	const fileFor = (key) => join(dir, `${hash(key)}.json`);
+	return {
+		get: async (key) => {
+			try {
+				const raw = await readFile(fileFor(key), "utf8");
+				return JSON.parse(raw);
+			} catch {
+				return;
+			}
+		},
+		set: async (key, value) => {
+			const file = fileFor(key);
+			await mkdir(dirname(file), { recursive: true });
+			await writeFile(file, JSON.stringify(value), "utf8");
+		}
+	};
+};
+const noopCache = () => ({
+	get: () => Promise.resolve(void 0),
+	set: () => Promise.resolve()
+});
+/** Resolve the `cache` option to a concrete {@link Cache}. */
+const resolveCache = (cache) => {
+	if (cache === false) return noopCache();
+	if (cache === void 0 || cache === true) return fileCache();
+	if (typeof cache === "string") return fileCache(cache);
+	return cache;
+};
+//#endregion
+export { fileCache, hash, memoryCache, resolveCache };

package/dist/cli.d.ts

@@ -0,0 +1,9 @@
+import { Command } from "commander";
+
+//#region src/cli.d.ts
+/** Find the config module: an explicit path, else the first known candidate. */
+declare const findConfig: (explicit?: string) => string;
+/** Build the doc0 CLI program (Commander). Exported so it can be inspected/tested. */
+declare const buildProgram: () => Command;
+//#endregion
+export { buildProgram, findConfig };

package/dist/cli.js

@@ -0,0 +1,136 @@
+#!/usr/bin/env bun
+import { loadDoc0 } from "./load.js";
+import { parseFields } from "./select.js";
+import { rm, writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { existsSync } from "node:fs";
+import { Command } from "commander";
+//#region src/cli.ts
+const CONFIG_CANDIDATES = [
+	"docs/index.ts",
+	"doc0.config.ts",
+	"doc0.config.js",
+	"docs/index.js"
+];
+const CACHE_DIR = "node_modules/.cache/doc0";
+/** Find the config module: an explicit path, else the first known candidate. */
+const findConfig = (explicit) => {
+	if (explicit) return explicit;
+	for (const candidate of CONFIG_CANDIDATES) if (existsSync(resolve(candidate))) return candidate;
+	throw new Error("doc0: no config found. Create docs/index.ts that exports `doc0`, or pass a path.");
+};
+const sourceTag = (doc) => doc.source ? `  ${doc.source.file}:${doc.source.lineStart}` : "";
+const formatRow = (doc) => {
+	const tags = doc.tags?.length ? ` [${doc.tags.join(", ")}]` : "";
+	const description = doc.description ? `\n    ${doc.description}` : "";
+	return `${doc.id ?? "?"}${tags}${sourceTag(doc)}${description}`;
+};
+/** Render a listed page as rows, with a footer when it's a window into a larger `total`. */
+const formatList = (page) => {
+	if (page.docs.length === 0) return "no docs";
+	const rows = page.docs.map(formatRow).join("\n");
+	const end = page.offset + page.docs.length;
+	if (end >= page.total && page.offset === 0) return rows;
+	const more = end < page.total ? ` (next: --offset ${end})` : "";
+	return `${rows}\n\nshowing ${page.offset + 1}–${end} of ${page.total}${more}`;
+};
+const formatDoc = (doc) => {
+	const lines = [];
+	if (doc.title) lines.push(`# ${doc.title}`);
+	if (doc.id) lines.push(`id: ${doc.id}`);
+	if (doc.source) lines.push(`source: ${doc.source.file}:${doc.source.lineStart}-${doc.source.lineEnd}`);
+	if (doc.tags?.length) lines.push(`tags: ${doc.tags.join(", ")}`);
+	if (doc.related?.length) {
+		lines.push("", "related:");
+		for (const link of doc.related) {
+			const marks = [link.required ? "must-read" : "", link.reason].filter(Boolean).join("; ");
+			lines.push(`  - ${link.title} (${link.id})${marks ? ` — ${marks}` : ""}`);
+			if (link.description) lines.push(`    ${link.description}`);
+		}
+	}
+	if (doc.content) lines.push("", doc.content);
+	return lines.join("\n");
+};
+const output = (json, data, pretty) => {
+	console.log(json ? JSON.stringify(data, null, 2) : pretty());
+};
+/** Build the doc0 CLI program (Commander). Exported so it can be inspected/tested. */
+const buildProgram = () => {
+	const program = new Command();
+	program.name("doc0").description("Parse, query, and serve your project docs.").version("0.0.0");
+	program.command("sync [path]").description("Parse and run generators (writes only on diff)").option("--watch", "watch and re-sync on change").action(async (path, options) => {
+		const doc0 = await loadDoc0(findConfig(path));
+		if (options.watch) doc0.watch(() => doc0.sync());
+		await doc0.sync();
+	});
+	program.command("watch [path]").description("Watch the globs and re-sync on change").action(async (path) => {
+		const doc0 = await loadDoc0(findConfig(path));
+		doc0.watch(() => doc0.sync());
+		await doc0.sync();
+	});
+	program.command("list [path]").description("List docs (table of contents)").option("--tag <tag>", "only docs with this tag").option("--category <category>", "only docs in this category").option("--fields <fields>", "comma list of fields to return (e.g. id,title,source)").option("--limit <n>", "max docs to return (default: all)").option("--offset <n>", "skip this many docs (for paging)").option("--json", "output JSON").action(async (path, options) => {
+		const { listDocs } = await import("./mcp/tools.js");
+		const page = listDocs(await (await loadDoc0(findConfig(path))).collect(), {
+			tag: options.tag,
+			category: options.category,
+			fields: parseFields(options.fields),
+			limit: options.limit ? Number(options.limit) : void 0,
+			offset: options.offset ? Number(options.offset) : void 0
+		});
+		output(options.json, page, () => formatList(page));
+	});
+	program.command("get <id> [path]").description("Print one doc in full (content + source)").option("--fields <fields>", "comma list of fields to return").option("--json", "output JSON").action(async (id, path, options) => {
+		const { getDoc } = await import("./mcp/tools.js");
+		const doc = getDoc(await (await loadDoc0(findConfig(path))).collect(), id, parseFields(options.fields));
+		if (!doc) throw new Error(`doc0: no doc with id "${id}"`);
+		output(options.json, doc, () => formatDoc(doc));
+	});
+	program.command("search <query> [path]").description("Hybrid keyword + semantic search").option("--limit <n>", "max results").option("--fields <fields>", "comma list of fields to return").option("--json", "output JSON").action(async (query, path, options) => {
+		const { searchDocs } = await import("./mcp/tools.js");
+		const hits = await searchDocs(await (await loadDoc0(findConfig(path))).collect(), query, {
+			limit: options.limit ? Number(options.limit) : void 0,
+			fields: parseFields(options.fields)
+		});
+		output(options.json, hits, () => hits.map(formatRow).join("\n") || "no matches");
+	});
+	program.command("export [path]").description("Export the whole collection to one file (md or json)").option("--format <format>", "md | json (default: md)").option("--tag <tag>", "only docs with this tag").option("--category <category>", "only docs in this category").option("--fields <fields>", "comma list of fields (json only)").option("--title <title>", "document title (md)").option("-o, --output <file>", "write to this file instead of stdout").action(async (path, options) => {
+		const format = options.format ?? "md";
+		if (format !== "md" && format !== "json") throw new Error(`doc0: unsupported --format "${format}" (use md or json)`);
+		const { exportDocs } = await import("./export.js");
+		const text = exportDocs(await (await loadDoc0(findConfig(path))).collect(), {
+			format,
+			tag: options.tag,
+			category: options.category,
+			fields: parseFields(options.fields),
+			title: options.title
+		});
+		if (options.output) {
+			await writeFile(resolve(options.output), text);
+			console.log(`doc0: wrote ${options.output}`);
+		} else process.stdout.write(text);
+	});
+	program.command("mcp [path]").description("Serve docs over MCP (stdio)").action(async (path) => {
+		const { serveMcp } = await import("./mcp/index.js");
+		await serveMcp(findConfig(path));
+	});
+	program.command("web [path]").description("Serve a local web UI with search").option("--port <n>", "port (default 4000)").action(async (path, options) => {
+		const { serveWeb } = await import("./web/index.js");
+		const port = options.port ? Number(options.port) : void 0;
+		await serveWeb(findConfig(path), { port });
+		console.log(`doc0 web on http://localhost:${port ?? 4e3}`);
+	});
+	program.command("prune").description("Drop the on-disk cache").option("--all", "remove the whole cache (default: stale entries)").action(async () => {
+		await rm(CACHE_DIR, {
+			recursive: true,
+			force: true
+		});
+		console.log("doc0: cache pruned");
+	});
+	return program;
+};
+if (import.meta.main) buildProgram().parseAsync(process.argv).catch((error) => {
+	console.error(error instanceof Error ? error.message : error);
+	process.exit(1);
+});
+//#endregion
+export { buildProgram, findConfig };

package/dist/docs.d.ts

@@ -0,0 +1,42 @@
+import { Doc, DocRelated, Docs, RelatedRef, SearchEngine, SearchOptions } from "./types.js";
+
+//#region src/docs.d.ts
+/**
+ * Resolve stored `@related` links into enriched {@link RelatedRef}s — each link gains the target doc's `title` and
+ * `description` (looked up via `docs.get`) so a reader can tell what's behind it. Links whose target is missing are
+ * dropped. With `order: true`, must-read (`required`) links surface first; otherwise authored order is kept.
+ */
+declare const resolveRelated: (docs: Pick<Docs, "get">, links: readonly DocRelated[], options?: {
+  required?: boolean;
+  order?: boolean;
+}) => RelatedRef[];
+/** A search engine, or a (possibly async) factory for one — the factory is invoked lazily on the first `search()`. */
+type EngineSource = SearchEngine | (() => SearchEngine | Promise<SearchEngine>);
+/**
+ * The queryable collection returned by `doc0.collect()`. Search uses the engine from `Doc0.create({ search })` (or the
+ * default orama engine `Doc0` injects), resolved lazily; with no engine at all it falls back to a naive keyword
+ * scorer.
+ */
+declare class DocsCollection<TExtra = unknown> implements Docs<TExtra> {
+  private readonly items;
+  private readonly byId;
+  private readonly engineSource;
+  private engine;
+  private enginePromise;
+  private indexed;
+  constructor(items: Doc<TExtra>[], engineSource?: EngineSource);
+  private resolveEngine;
+  all(): Doc<TExtra>[];
+  get(id: string): Doc<TExtra> | undefined;
+  byTag(tag: string): Doc<TExtra>[];
+  byCategory(category: string): Doc<TExtra>[];
+  related(id: string, options?: {
+    required?: boolean;
+  }): RelatedRef[];
+  search(query: string, options?: SearchOptions): Promise<Doc<TExtra>[]>;
+  toJSON(): string;
+  [Symbol.iterator](): Iterator<Doc<TExtra>>;
+  private naiveSearch;
+}
+//#endregion
+export { DocsCollection, EngineSource, resolveRelated };

package/dist/docs.js

@@ -0,0 +1,100 @@
+//#region src/docs.ts
+/**
+* Resolve stored `@related` links into enriched {@link RelatedRef}s — each link gains the target doc's `title` and
+* `description` (looked up via `docs.get`) so a reader can tell what's behind it. Links whose target is missing are
+* dropped. With `order: true`, must-read (`required`) links surface first; otherwise authored order is kept.
+*/
+const resolveRelated = (docs, links, options) => {
+	const filtered = options?.required ? links.filter((link) => link.required) : links;
+	return (options?.order ? [...filtered].sort((a, b) => Number(b.required ?? false) - Number(a.required ?? false)) : filtered).flatMap((link) => {
+		const target = docs.get(link.id);
+		return target ? [{
+			...link,
+			title: target.title,
+			description: target.description
+		}] : [];
+	});
+};
+/**
+* The queryable collection returned by `doc0.collect()`. Search uses the engine from `Doc0.create({ search })` (or the
+* default orama engine `Doc0` injects), resolved lazily; with no engine at all it falls back to a naive keyword
+* scorer.
+*/
+var DocsCollection = class {
+	items;
+	byId;
+	engineSource;
+	engine;
+	enginePromise;
+	indexed = false;
+	constructor(items, engineSource) {
+		this.items = items;
+		this.byId = new Map(items.map((doc) => [doc.id, doc]));
+		this.engineSource = engineSource;
+	}
+	async resolveEngine() {
+		if (this.engine) return this.engine;
+		if (this.engineSource === void 0) return;
+		this.enginePromise ??= Promise.resolve(typeof this.engineSource === "function" ? this.engineSource() : this.engineSource);
+		this.engine = await this.enginePromise;
+		return this.engine;
+	}
+	all() {
+		return this.items;
+	}
+	get(id) {
+		return this.byId.get(id);
+	}
+	byTag(tag) {
+		return this.items.filter((doc) => doc.tags.includes(tag));
+	}
+	byCategory(category) {
+		return this.items.filter((doc) => doc.category.includes(category));
+	}
+	related(id, options) {
+		const doc = this.byId.get(id);
+		if (!doc) return [];
+		return resolveRelated(this, doc.related, {
+			required: options?.required,
+			order: true
+		});
+	}
+	async search(query, options) {
+		const engine = await this.resolveEngine();
+		if (engine) {
+			if (!this.indexed) {
+				await engine.index(this.items);
+				this.indexed = true;
+			}
+			return (await engine.search(query, options)).map((hit) => this.byId.get(hit.id)).filter((doc) => doc !== void 0);
+		}
+		return this.naiveSearch(query, options);
+	}
+	toJSON() {
+		return JSON.stringify(this.items, null, 2);
+	}
+	[Symbol.iterator]() {
+		return this.items[Symbol.iterator]();
+	}
+	naiveSearch(query, options) {
+		const needle = query.toLowerCase().trim();
+		if (!needle) return [];
+		const scored = this.items.map((doc) => ({
+			doc,
+			score: score(doc, needle)
+		})).filter((entry) => entry.score > 0).sort((a, b) => b.score - a.score);
+		const limit = options?.limit ?? scored.length;
+		return scored.slice(0, limit).map((entry) => entry.doc);
+	}
+};
+const score = (doc, needle) => {
+	let total = 0;
+	if (doc.title.toLowerCase().includes(needle)) total += 5;
+	if (doc.id.toLowerCase().includes(needle)) total += 4;
+	if (doc.description.toLowerCase().includes(needle)) total += 3;
+	if (doc.tags.some((tag) => tag.toLowerCase().includes(needle))) total += 2;
+	if (doc.content.toLowerCase().includes(needle)) total += 1;
+	return total;
+};
+//#endregion
+export { DocsCollection, resolveRelated };

package/dist/export.d.ts

@@ -0,0 +1,29 @@
+import { Doc, Docs } from "./types.js";
+import { DocField } from "./select.js";
+
+//#region src/export.d.ts
+/** A built-in export format. Custom formats are supported by passing your own {@link Formatter}. */
+type ExportFormat = 'json' | 'md';
+/** Turns a filtered list of docs into one serialized document. `all` is the full collection (for resolving links). */
+type Formatter = (docs: Doc[], all: Docs, options: ExportOptions) => string;
+type ExportOptions = {
+  /** Built-in `json`/`md`, or a custom {@link Formatter}. Default `md`. */format?: ExportFormat | Formatter; /** Only docs with this tag. */
+  tag?: string; /** Only docs in this category. */
+  category?: string; /** JSON only — project each doc to these fields. */
+  fields?: DocField[]; /** Markdown document title (default `Documentation`). */
+  title?: string;
+};
+/** The built-in JSON formatter: the raw docs (or a `fields` projection), pretty-printed. */
+declare const formatJson: Formatter;
+/**
+ * The built-in Markdown formatter: a title, a table of contents, then each doc with its metadata and body. Docs are
+ * grouped under their `category`; when no doc has a category, it degrades to a clean flat list (no empty buckets).
+ */
+declare const formatMarkdown: Formatter;
+/**
+ * Export a collection to one serialized document — `json` or a rich `md` bundle (or a custom {@link Formatter}),
+ * optionally filtered by `tag`/`category`. Powers `doc0 export`, and is reusable from a config's `finalGenerate`.
+ */
+declare const exportDocs: (docs: Docs, options?: ExportOptions) => string;
+//#endregion
+export { ExportFormat, ExportOptions, Formatter, exportDocs, formatJson, formatMarkdown };