@marincervinschi/docs 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marin Cervinschi
+
+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

@@ -1,3 +1,51 @@
-# Temporary Holding Version
+# docs
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`docs` reads a project's [Fumadocs](https://fumadocs.dev) content from the terminal, one piece at a time. It is meant for coding agents: an agent asks for the map of the docs, the headings of a page, one section, the best matches for a query or the links of a page, and gets back only that, without opening whole files.
+
+It reads the Fumadocs content format: a `docs/` folder of `.mdx` and `.md` pages, ordered by `meta.json` files. Page order, slugs and heading anchors come from `fumadocs-core` itself, so `docs` agrees with the site.
+
+## Install
+
+```bash
+npm install -g @marincervinschi/docs
+```
+
+Node 22 or later.
+
+## Commands
+
+Run them anywhere inside a git repo that has a `docs/` folder at its root, or point `--dir` at another repo or docs folder. A page is its path in `docs/` without the extension (`guides/install`); its URL, its file path and `page#anchor` work too.
+
+| Command | Prints |
+|---|---|
+| `docs outline` | the map of the docs in `meta.json` order, one line per page with its title and description |
+| `docs outline <page>` | the page's headings, each with its anchor and an estimated size in tokens |
+| `docs page <page> [--part frontmatter\|body\|summary\|section:<heading>]` | the page as written, or one part of it |
+| `docs search <query> [--limit <n>]` | the best pages, 5 by default, each with its best section and a snippet |
+| `docs links <page>` | links out of the page, external links, the pages that link to it, broken links |
+| `docs lint` | missing titles, MDX that would not compile, broken links and anchors, `meta.json` against the files; exits with 1 on findings |
+| `docs help [<command>]` | the list above in under 300 tokens, or one command's options |
+
+Every command takes `--json` for the same data as JSON.
+
+```
+$ docs outline guides/install
+guides/install  Install  ~115
+## Requirements  #requirements  ~16
+## First run  #first  ~74
+### When the port is taken  #when-the-port-is-taken  ~36
+
+$ docs search port in use --limit 2
+guides/install#when-the-port-is-taken  Install > When the port is taken  The dev server stops when port 3000 is already in use. Pass `--port 3001`, or read deploy.
+guides/deploy#ports  Deploy > Ports  The preview listens on port 4000. The install guide explains the first run.
+
+$ docs page guides/install#first
+```
+
+## What it does not do
+
+It only reads. It does not render MDX components, does not keep an index, and has no settings file. The decisions behind this are in [SPEC.md](SPEC.md).
+
+## License
+
+MIT

package/dist/bin.js

@@ -0,0 +1,831 @@
+#!/usr/bin/env node
+import { frontmatter } from "fumadocs-core/content/md/frontmatter";
+import { loader } from "fumadocs-core/source";
+import fs from "node:fs";
+import path from "node:path";
+import { remarkGfm } from "fumadocs-core/mdx-plugins/remark-gfm";
+import { remarkHeading } from "fumadocs-core/mdx-plugins/remark-heading";
+import { remarkStructure } from "fumadocs-core/mdx-plugins/remark-structure";
+import { remark } from "remark";
+import remarkMdx from "remark-mdx";
+import { VFile } from "vfile";
+// src/core/errors.ts
+var DocsError = class extends Error {
+	name = "DocsError";
+};
+// src/core/parse.ts
+const tokens = (text) => Math.ceil(text.length / 4);
+function processor(mdx) {
+	const p = remark().use(remarkGfm);
+	if (mdx) p.use(remarkMdx);
+	return p.use(remarkHeading).use(remarkStructure);
+}
+function parsePage(page) {
+	const mdx = page.path.endsWith(".mdx");
+	try {
+		return run(processor(mdx), page);
+	} catch (err) {
+		if (!mdx) throw err;
+		const e = err;
+		const message = e.reason ?? e.message;
+		const at = /\((\d+):\d+(?:-\d+:\d+)?\)$/.exec(message);
+		const line = e.line ?? e.place?.line ?? e.place?.start?.line ?? Number(at?.[1] ?? 1);
+		return {
+			...run(processor(false), page),
+			error: {
+				line: line + page.bodyLine,
+				message: message.replace(/\s*\(\d+:\d+(?:-\d+:\d+)?\)$/, "")
+			}
+		};
+	}
+}
+function run(p, page) {
+	const file = new VFile({
+		value: page.body,
+		path: page.path
+	});
+	const tree = p.runSync(p.parse(file), file);
+	const nodes = [];
+	walk(tree, (n) => {
+		if (n.type === "heading") nodes.push(n);
+	});
+	const toc = file.data.toc ?? [];
+	return {
+		tree,
+		headings: nodes.map((n, i) => {
+			const start = n.position?.start.offset ?? 0;
+			const end = nodes.slice(i + 1).find((m) => m.depth <= n.depth)?.position?.start.offset ?? page.body.length;
+			return {
+				depth: n.depth,
+				text: typeof toc[i]?.title === "string" ? toc[i].title : toText(n),
+				anchor: String(n.data?.hProperties?.id ?? ""),
+				line: (n.position?.start.line ?? 1) + page.bodyLine,
+				start,
+				end,
+				tokens: tokens(page.body.slice(start, end))
+			};
+		}),
+		structured: file.data.structuredData ?? {
+			headings: [],
+			contents: []
+		}
+	};
+}
+function walk(node, visit) {
+	visit(node);
+	if ("children" in node) for (const child of node.children) walk(child, visit);
+}
+function toText(node) {
+	if ("value" in node && typeof node.value === "string") return node.value;
+	if ("children" in node) return node.children.map((c) => toText(c)).join("");
+	return "";
+}
+// src/core/docs.ts
+const BASE_URL = "/docs";
+const buildSource = (files) => loader({
+	source: { files },
+	baseUrl: BASE_URL
+});
+const PAGE = /\.mdx?$/;
+const posix = (p) => p.split(path.sep).join("/");
+function loadDocs(dir) {
+	const top = path.basename(dir);
+	const pages = [];
+	const metas = [];
+	const entries = fs.readdirSync(dir, { recursive: true }).map(posix).filter((p) => !p.split("/").some((s) => s.startsWith(".") || s === "node_modules")).sort();
+	for (const p of entries) {
+		const full = path.join(dir, p);
+		if (PAGE.test(p)) pages.push(readPage(full, p, `${top}/${p}`));
+		else if (path.posix.basename(p) === "meta.json") metas.push(readMeta(full, p, `${top}/${p}`));
+	}
+	if (!pages.length) throw new DocsError(`No .mdx or .md pages in ${dir}.`);
+	const files = [...pages.map((p) => ({
+		type: "page",
+		path: p.path,
+		data: {
+			title: p.title,
+			description: p.description
+		}
+	})), ...metas.filter((m) => m.data).map((m) => ({
+		type: "meta",
+		path: m.path,
+		data: m.data
+	}))];
+	const source = buildSource(files);
+	const byPath = new Map(pages.map((p) => [p.path, p]));
+	for (const lp of source.getPages()) {
+		const page = byPath.get(lp.path);
+		if (page) page.url = lp.url;
+	}
+	const cache = /* @__PURE__ */ new Map();
+	return {
+		dir,
+		pages,
+		metas,
+		source,
+		byPath,
+		parsed(page) {
+			let parsed = cache.get(page);
+			if (!parsed) cache.set(page, parsed = parsePage(page));
+			return parsed;
+		}
+	};
+}
+function readPage(full, p, file) {
+	const raw = fs.readFileSync(full, "utf8");
+	const page = {
+		id: p.replace(PAGE, ""),
+		path: p,
+		file,
+		url: "",
+		raw,
+		matter: "",
+		body: raw,
+		bodyLine: 0
+	};
+	try {
+		const fm = frontmatter(raw);
+		const data = fm.data ?? {};
+		page.body = fm.content;
+		page.bodyLine = fm.matter.split("\n").length - 1;
+		page.matter = fm.matter.replace(/^---\r?\n/, "").replace(/\r?\n---\r?\n?$/, "");
+		if (typeof data.title === "string") page.title = data.title;
+		if (typeof data.description === "string") page.description = data.description;
+	} catch (err) {
+		page.frontmatterError = err.message.split("\n")[0];
+	}
+	return page;
+}
+function readMeta(full, p, file) {
+	const raw = fs.readFileSync(full, "utf8");
+	try {
+		return {
+			path: p,
+			file,
+			raw,
+			data: JSON.parse(raw)
+		};
+	} catch (err) {
+		const message = err.message;
+		const at = /position (\d+)/.exec(message);
+		return {
+			path: p,
+			file,
+			raw,
+			error: {
+				line: at ? raw.slice(0, Number(at[1])).split("\n").length : 1,
+				message
+			}
+		};
+	}
+}
+function pageRef(page) {
+	return {
+		page: page.id,
+		title: page.title ?? page.id,
+		...page.description ? { description: page.description } : {},
+		url: page.url,
+		file: page.file
+	};
+}
+/**
+* The page a name points to: its path without the extension (`guides/install`), its
+* slugs, its URL (`/docs/guides/install` or `/guides/install`) or its file path. A
+* `#anchor` suffix is returned apart.
+*/
+function findPage(docs, name) {
+	const hash = name.indexOf("#");
+	const anchor = hash < 0 ? void 0 : name.slice(hash + 1) || void 0;
+	const key = (hash < 0 ? name : name.slice(0, hash)).trim().replace(/^\.?\//, "");
+	const top = path.basename(docs.dir);
+	const bare = key.replace(new RegExp(`^${top}/`), "").replace(PAGE, "").replace(/\/$/, "");
+	const page = docs.pages.find((p) => p.id === bare) ?? docs.pages.find((p) => p.id === `${bare}/index`) ?? pageFromLoader(docs, docs.source.getPage(bare ? bare.split("/") : [])) ?? pageFromLoader(docs, docs.source.getPageByUrl(`/${key}`)) ?? pageFromLoader(docs, docs.source.getPageByUrl(`/docs/${key}`));
+	if (!page) throw new DocsError(`No page ${name}. Name a page by its path in the docs folder without .mdx; docs outline lists them.`);
+	return {
+		page,
+		anchor
+	};
+}
+function pageFromLoader(docs, lp) {
+	return lp ? docs.byPath.get(lp.path) : void 0;
+}
+// src/core/find.ts
+const isDir = (p) => fs.statSync(p, { throwIfNoEntry: false })?.isDirectory() ?? false;
+/** The docs folder: `--dir` (a repo root or the folder itself), else `docs/` at the git root above `cwd`. */
+function findDocsDir(cwd, dir) {
+	if (dir !== void 0) {
+		const target = path.resolve(cwd, dir);
+		if (!isDir(target)) throw new DocsError(`--dir ${dir} is not a folder.`);
+		const inner = path.join(target, "docs");
+		return isDir(inner) ? inner : target;
+	}
+	const root = gitRoot(cwd);
+	const docs = path.join(root ?? cwd, "docs");
+	if (isDir(docs)) return docs;
+	throw new DocsError(root ? `No docs/ folder at the root of this repo (${root}). Pass --dir with the repo or the folder that holds the pages.` : `Not inside a git repo and no docs/ folder here. Pass --dir with the repo or the folder that holds the pages.`);
+}
+function gitRoot(from) {
+	for (let dir = path.resolve(from);; dir = path.dirname(dir)) {
+		if (fs.existsSync(path.join(dir, ".git"))) return dir;
+		if (path.dirname(dir) === dir) return void 0;
+	}
+}
+// src/cli/args.ts
+function parseArgs(spec, argv) {
+	const options = {};
+	const words = [];
+	for (let i = 0; i < argv.length; i++) {
+		const arg = argv[i];
+		if (!arg.startsWith("--")) {
+			words.push(arg);
+			continue;
+		}
+		const eq = arg.indexOf("=");
+		const name = arg.slice(2, eq < 0 ? void 0 : eq);
+		const option = spec.options.find((o) => o.name === name);
+		if (!option) throw new DocsError(`docs ${spec.name} has no option --${name}. Options: ${spec.options.map((o) => `--${o.name}`).join(", ")}.`);
+		if (option.flag) {
+			if (eq >= 0) throw new DocsError(`--${name} takes no value.`);
+			options[name] = "true";
+			continue;
+		}
+		const value = eq < 0 ? argv[++i] : arg.slice(eq + 1);
+		if (value === void 0) throw new DocsError(`--${name} needs a value: ${option.hint}.`);
+		if (option.number && !/^[1-9]\d*$/.test(value)) throw new DocsError(`--${name} must be a positive whole number, not ${value}.`);
+		options[name] = value;
+	}
+	const pos = spec.positional;
+	if (words.length && !pos) throw new DocsError(`docs ${spec.name} takes no argument: ${words[0]}.`);
+	if (words.length > 1 && !pos?.rest) throw new DocsError(`docs ${spec.name} takes one ${pos.name}; got ${words.length} words. Quote it.`);
+	const positional = words.length ? words.join(" ") : void 0;
+	if (pos?.required && positional === void 0) throw new DocsError(`docs ${spec.name} needs <${pos.name}>: ${pos.hint}.`);
+	return {
+		positional,
+		options
+	};
+}
+// src/core/links.ts
+const SCHEME = /^[a-z][a-z\d+.-]*:/i;
+const ASSET = /\.(?!mdx?$)[a-z\d]+$/i;
+/** Every link of a page: Markdown links and definitions, and `href` on MDX elements. */
+function pageLinkRefs(docs, page) {
+	const refs = [];
+	walk(docs.parsed(page).tree, (node) => {
+		const line = (node.position?.start.line ?? 1) + page.bodyLine;
+		if (node.type === "link") refs.push({
+			href: node.url,
+			text: toText(node),
+			line
+		});
+		else if (node.type === "definition") refs.push({
+			href: node.url,
+			text: node.label ?? node.identifier,
+			line
+		});
+		else if (node.type === "mdxJsxFlowElement" || node.type === "mdxJsxTextElement") {
+			for (const attr of node.attributes) if (attr.type === "mdxJsxAttribute" && attr.name === "href" && typeof attr.value === "string") refs.push({
+				href: attr.value,
+				text: toText(node),
+				line
+			});
+		}
+	});
+	return refs;
+}
+/**
+* Where a link goes. Internal links may be relative file paths (`./install.mdx`), site
+* paths with the `/docs` base or without it, relative URLs, or `#anchor` on the same page.
+*/
+function resolveLink(docs, from, href) {
+	if (SCHEME.test(href) || href.startsWith("//")) return {
+		kind: "external",
+		url: href
+	};
+	const hash = href.indexOf("#");
+	const target = hash < 0 ? href : href.slice(0, hash);
+	const anchor = hash < 0 ? void 0 : decodeURIComponent(href.slice(hash + 1));
+	if (ASSET.test(target)) return {
+		kind: "external",
+		url: href
+	};
+	let page;
+	if (!target) page = from;
+	else {
+		const dir = path.posix.dirname(from.path);
+		page = pageFromLoader(docs, (docs.source.getPageByHref(target, { dir: dir === "." ? "" : dir }) ?? (target.startsWith("/") ? docs.source.getPageByHref(target === "/" ? "/docs" : "/docs" + target) : void 0))?.page);
+		if (!page && !target.startsWith("/")) {
+			const url = new URL(target, `http://docs.invalid${from.url}`).pathname;
+			page = pageFromLoader(docs, docs.source.getPageByUrl(url.replace(/\/$/, "")));
+		}
+	}
+	if (!page) return {
+		kind: "broken",
+		reason: `no page at ${target}`
+	};
+	if (anchor && !docs.parsed(page).headings.some((h) => h.anchor === anchor)) return {
+		kind: "broken",
+		reason: `no heading #${anchor} in ${page.id}`
+	};
+	return {
+		kind: "internal",
+		page,
+		...anchor ? { anchor } : {}
+	};
+}
+function pageLinks(docs, page) {
+	const out = {
+		internal: [],
+		external: [],
+		backlinks: [],
+		broken: []
+	};
+	for (const ref of pageLinkRefs(docs, page)) {
+		const r = resolveLink(docs, page, ref.href);
+		if (r.kind === "internal") out.internal.push({
+			page: r.page.id,
+			...r.anchor ? { anchor: r.anchor } : {},
+			text: ref.text,
+			line: ref.line
+		});
+		else if (r.kind === "external") out.external.push({
+			url: r.url,
+			text: ref.text,
+			line: ref.line
+		});
+		else out.broken.push({
+			target: ref.href,
+			line: ref.line,
+			reason: r.reason
+		});
+	}
+	for (const other of docs.pages) {
+		if (other === page) continue;
+		for (const ref of pageLinkRefs(docs, other)) {
+			const r = resolveLink(docs, other, ref.href);
+			if (r.kind === "internal" && r.page === page) out.backlinks.push({
+				page: other.id,
+				line: ref.line
+			});
+		}
+	}
+	return out;
+}
+// src/core/lint.ts
+/** What would break a Fumadocs site, or hide a page from its navigation. */
+function lint(docs) {
+	const findings = [];
+	const add = (file, line, rule, message) => findings.push({
+		file,
+		line,
+		rule,
+		message
+	});
+	for (const page of docs.pages) {
+		if (page.frontmatterError) add(page.file, 1, "frontmatter", `the frontmatter is not valid YAML: ${page.frontmatterError}`);
+		else if (!page.title) add(page.file, 1, "title", "no title in the frontmatter");
+		const { error } = docs.parsed(page);
+		if (error) add(page.file, error.line, "mdx", `MDX does not compile: ${error.message}`);
+		for (const ref of pageLinkRefs(docs, page)) {
+			const r = resolveLink(docs, page, ref.href);
+			if (r.kind === "broken") add(page.file, ref.line, "link", `${ref.href}: ${r.reason}`);
+		}
+	}
+	const excluded = /* @__PURE__ */ new Set();
+	for (const meta of docs.metas) {
+		if (meta.error) {
+			add(meta.file, meta.error.line, "meta", `not valid JSON: ${meta.error.message}`);
+			continue;
+		}
+		checkMeta(docs, meta, excluded, add);
+	}
+	const shown = navPages(docs);
+	for (const page of docs.pages) if (!shown.has(page) && !excluded.has(page.path.replace(/\.mdx?$/, ""))) add(page.file, 1, "meta", `not in the navigation: ${missingHint(docs, page)}`);
+	return findings.sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line);
+}
+const NOT_A_NAME = /^(\.\.\.|z\.\.\.a|---.*---|(external:)?\[.*\]\(.*\))$/;
+function checkMeta(docs, meta, excluded, add) {
+	const pages = meta.data?.pages;
+	if (pages === void 0) return;
+	const folder = path.posix.dirname(meta.path);
+	if (!Array.isArray(pages) || pages.some((p) => typeof p !== "string")) {
+		add(meta.file, 1, "meta", "pages must be a list of strings");
+		return;
+	}
+	for (const entry of pages) {
+		if (NOT_A_NAME.test(entry)) continue;
+		const name = entry.replace(/^!/, "").replace(/^\.\.\./, "");
+		const rel = folder === "." ? name : `${folder}/${name}`;
+		if (entry.startsWith("!")) excluded.add(rel);
+		const full = path.join(docs.dir, rel);
+		if ([
+			".mdx",
+			".md",
+			""
+		].some((ext) => fs.existsSync(full + ext))) continue;
+		const line = meta.raw.slice(0, meta.raw.indexOf(JSON.stringify(entry))).split("\n").length;
+		add(meta.file, line, "meta", `lists "${entry}", but there is no ${name}.mdx or ${name}/ in ${folder === "." ? "the docs folder" : `${folder}/`}`);
+	}
+}
+/** The pages the site's navigation reaches. */
+function navPages(docs) {
+	const shown = /* @__PURE__ */ new Set();
+	const add = (item) => {
+		const page = pageFromLoader(docs, docs.source.getNodePage(item));
+		if (page) shown.add(page);
+	};
+	const visit = (nodes) => {
+		for (const node of nodes) if (node.type === "page") add(node);
+		else if (node.type === "folder") {
+			if (node.index) add(node.index);
+			visit(node.children);
+		}
+	};
+	visit(docs.source.pageTree.children);
+	return shown;
+}
+function missingHint(docs, page) {
+	const folder = path.posix.dirname(page.path);
+	const meta = folder === "." ? "meta.json" : `${folder}/meta.json`;
+	const name = path.posix.basename(page.path).replace(/\.mdx?$/, "");
+	return docs.metas.some((m) => m.path === meta) ? `add "${name}" (or "...") to ${meta}` : `a meta.json above this folder leaves it out`;
+}
+// src/core/outline.ts
+/** The navigation as the site shows it: `meta.json` order, folders, separators and links. */
+function docsOutline(docs) {
+	const out = [];
+	const visit = (nodes, depth) => {
+		for (const node of nodes) {
+			const title = typeof node.name === "string" ? node.name : "";
+			if (node.type === "separator") out.push({
+				kind: "separator",
+				depth,
+				title
+			});
+			else if (node.type === "folder") {
+				out.push({
+					kind: "folder",
+					depth,
+					title
+				});
+				if (node.index) pushPage(node.index, depth + 1);
+				visit(node.children, depth + 1);
+			} else pushPage(node, depth);
+		}
+	};
+	const pushPage = (item, depth) => {
+		const page = pageFromLoader(docs, docs.source.getNodePage(item));
+		if (page) out.push({
+			kind: "page",
+			depth,
+			title: page.title ?? page.id,
+			page: pageRef(page)
+		});
+		else out.push({
+			kind: "link",
+			depth,
+			title: String(item.name),
+			url: item.url
+		});
+	};
+	visit(docs.source.pageTree.children, 0);
+	return out;
+}
+function pageOutline(docs, page) {
+	return {
+		page: pageRef(page),
+		tokens: tokens(page.raw),
+		headings: docs.parsed(page).headings.map((h) => ({
+			depth: h.depth,
+			text: h.text,
+			anchor: h.anchor,
+			tokens: h.tokens
+		}))
+	};
+}
+// src/core/search.ts
+const SNIPPET = 140;
+const terms = (query) => [...new Set(query.toLowerCase().split(/[^\p{L}\p{N}]+/u).filter(Boolean))];
+const matcher = (term) => new RegExp(`(?<![\\p{L}\\p{N}])${term.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}`, "giu");
+/**
+* The best pages for a query, each with its best section. Every call scores the sections
+* Fumadocs extracts for its own search: the title and description weigh 3, a heading 2,
+* a paragraph or table row 1, each scaled by how rare the term is and how many of the
+* query's terms the block holds.
+*/
+function search(docs, query, limit = 5) {
+	const words = terms(query);
+	if (!words.length) throw new DocsError("search needs at least one word to look for.");
+	const blocks = docs.pages.flatMap((page) => pageBlocks(docs, page));
+	const patterns = words.map(matcher);
+	const counts = blocks.map((b) => patterns.map((p) => b.text.match(p)?.length ?? 0));
+	const idf = words.map((_, t) => {
+		const df = counts.filter((c) => c[t] > 0).length;
+		return Math.log(1 + blocks.length / (1 + df));
+	});
+	const pages = /* @__PURE__ */ new Map();
+	blocks.forEach((block, i) => {
+		const c = counts[i];
+		const matched = c.filter((n) => n > 0).length;
+		if (!matched) return;
+		const raw = c.reduce((sum, n, t) => sum + (n ? idf[t] * (1 + Math.log(n)) : 0), 0);
+		const score = block.weight * raw * (matched / words.length) ** 2;
+		let p = pages.get(block.ref.page);
+		if (!p) pages.set(block.ref.page, p = {
+			ref: block.ref,
+			top: 0,
+			total: 0
+		});
+		p.top = Math.max(p.top, score);
+		p.total += score;
+		if (block.isTitle) p.title = block;
+		else if (!p.section || score > p.section.score) p.section = {
+			block,
+			score
+		};
+	});
+	return [...pages.values()].map((p) => ({
+		block: p.section?.block ?? p.title,
+		score: Math.round((p.top + .1 * (p.total - p.top)) * 100) / 100
+	})).sort((a, b) => b.score - a.score || a.block.ref.page.localeCompare(b.block.ref.page)).slice(0, limit).map(({ block, score }) => ({
+		page: block.ref.page,
+		...block.anchor ? { anchor: block.anchor } : {},
+		...block.heading ? { heading: block.heading } : {},
+		title: block.ref.title,
+		snippet: snippet(block.preview ?? block.text, patterns),
+		score
+	}));
+}
+function pageBlocks(docs, page) {
+	const ref = pageRef(page);
+	const { structured } = docs.parsed(page);
+	const headingText = new Map(structured.headings.map((h) => [h.id, h.content]));
+	return [
+		{
+			ref,
+			text: [ref.title, ref.description].filter(Boolean).join(". "),
+			weight: 3,
+			isTitle: true
+		},
+		...structured.headings.map((h) => ({
+			ref,
+			anchor: h.id,
+			heading: h.content,
+			text: h.content,
+			weight: 2,
+			preview: structured.contents.find((c) => c.heading === h.id)?.content
+		})),
+		...structured.contents.map((c) => ({
+			ref,
+			anchor: c.heading,
+			heading: c.heading ? headingText.get(c.heading) : void 0,
+			text: c.content,
+			weight: 1
+		}))
+	];
+}
+function snippet(text, patterns) {
+	const flat = text.split("\n").filter((line) => !/^[\s|:-]*-{3}[\s|:-]*$/.test(line)).join(" ").replace(/\s+/g, " ").trim();
+	const first = Math.min(...patterns.map((p) => {
+		p.lastIndex = 0;
+		const m = p.exec(flat);
+		return m ? m.index : Infinity;
+	}));
+	const start = Number.isFinite(first) ? Math.max(0, first - 40) : 0;
+	const piece = flat.slice(start, start + SNIPPET);
+	return `${start > 0 ? "…" : ""}${piece}${start + SNIPPET < flat.length ? "…" : ""}`;
+}
+// src/core/sections.ts
+const PARTS = [
+	"frontmatter",
+	"body",
+	"summary",
+	"section:<heading>"
+];
+/** The page as written, or one part: frontmatter, body, summary or `section:<heading>`. */
+function pagePart(docs, page, part) {
+	if (part === void 0) return page.raw;
+	if (part === "frontmatter") return page.matter;
+	if (part === "body") return page.body.replace(/^\s*\n/, "").trimEnd();
+	if (part === "summary") return [page.title ?? page.id, page.description].filter(Boolean).join("\n");
+	if (part.startsWith("section:")) {
+		const heading = findHeading(docs, page, part.slice(8));
+		return page.body.slice(heading.start, heading.end).trimEnd();
+	}
+	throw new DocsError(`No part ${part}. Parts: ${PARTS.join(", ")}.`);
+}
+/** A heading by its anchor, its exact text, or a piece of its text that only one heading has. */
+function findHeading(docs, page, key) {
+	const headings = docs.parsed(page).headings;
+	const k = key.trim().replace(/^#/, "");
+	const lower = k.toLowerCase();
+	const exact = headings.find((h) => h.anchor === k) ?? headings.find((h) => h.text.toLowerCase() === lower);
+	if (exact) return exact;
+	const partial = headings.filter((h) => h.text.toLowerCase().includes(lower));
+	if (partial.length === 1) return partial[0];
+	const list = (partial.length ? partial : headings).map((h) => `#${h.anchor}`).join(", ");
+	throw new DocsError(partial.length ? `${partial.length} headings in ${page.id} match "${k}": ${list}. Pass the anchor.` : `No heading "${k}" in ${page.id}.${list ? ` Anchors: ${list}.` : " The page has no headings."}`);
+}
+// src/cli/commands.ts
+const indent = (depth) => "  ".repeat(depth);
+const fields = (...parts) => parts.filter((p) => p !== void 0 && p !== "").join("  ");
+const orNone = (lines, none) => lines.length ? lines.join("\n") : none;
+const COMMANDS = [
+	{
+		name: "outline",
+		summary: "the map of the docs; with a page, its headings with anchors and sizes",
+		positional: {
+			name: "page",
+			hint: "a page, e.g. guides/install"
+		},
+		options: [],
+		example: "docs outline guides/install",
+		run(docs, args) {
+			if (args.positional === void 0) {
+				const entries = docsOutline(docs);
+				return {
+					text: entries.map((e) => {
+						const pad = indent(e.depth);
+						if (e.kind === "folder") return `${pad}${e.title}/`;
+						if (e.kind === "separator") return `${pad}--- ${e.title} ---`;
+						if (e.kind === "link") return `${pad}${fields("link", e.title, e.url)}`;
+						return `${pad}${fields(e.page.page, e.title, e.page.description)}`;
+					}).join("\n"),
+					json: entries
+				};
+			}
+			const { page } = findPage(docs, args.positional);
+			const outline = pageOutline(docs, page);
+			return {
+				text: [fields(outline.page.page, outline.page.title, `~${outline.tokens}`), ...outline.headings.map((h) => fields(`${"#".repeat(h.depth)} ${h.text}`, `#${h.anchor}`, `~${h.tokens}`))].join("\n"),
+				json: outline
+			};
+		}
+	},
+	{
+		name: "page",
+		summary: "a page as written, or one part of it",
+		positional: {
+			name: "page",
+			hint: "a page; page#anchor gives that section",
+			required: true
+		},
+		options: [{
+			name: "part",
+			hint: PARTS.join(" | ")
+		}],
+		example: "docs page guides/install --part section:requirements",
+		run(docs, args) {
+			const { page, anchor } = findPage(docs, args.positional);
+			const part = args.options.part ?? (anchor ? `section:${anchor}` : void 0);
+			const content = pagePart(docs, page, part);
+			return {
+				text: content,
+				json: {
+					page: pageRef(page),
+					...part ? { part } : {},
+					content
+				}
+			};
+		}
+	},
+	{
+		name: "search",
+		summary: "best pages, each with its best section and a snippet",
+		positional: {
+			name: "query",
+			hint: "words to look for",
+			required: true,
+			rest: true
+		},
+		options: [{
+			name: "limit",
+			hint: "how many pages, default 5",
+			number: true
+		}],
+		example: "docs search port already in use",
+		run(docs, args) {
+			const limit = args.options.limit ? Number(args.options.limit) : void 0;
+			const hits = search(docs, args.positional, limit);
+			const text = hits.map((h) => fields(h.anchor ? `${h.page}#${h.anchor}` : h.page, h.heading ? `${h.title} > ${h.heading}` : h.title, h.snippet));
+			return {
+				text: orNone(text, "no match"),
+				json: hits
+			};
+		}
+	},
+	{
+		name: "links",
+		summary: "links out, external links, backlinks and broken links of a page",
+		positional: {
+			name: "page",
+			hint: "a page, e.g. guides/install",
+			required: true
+		},
+		options: [],
+		example: "docs links guides/install",
+		run(docs, args) {
+			const { page } = findPage(docs, args.positional);
+			const links = pageLinks(docs, page);
+			const text = [
+				...links.internal.map((l) => fields("out", l.anchor ? `${l.page}#${l.anchor}` : l.page, `line ${l.line}`)),
+				...links.external.map((l) => fields("external", l.url, `line ${l.line}`)),
+				...links.backlinks.map((l) => fields("in", l.page, `line ${l.line}`)),
+				...links.broken.map((l) => fields("broken", l.target, `line ${l.line}`, l.reason))
+			];
+			return {
+				text: orNone(text, "no links"),
+				json: {
+					page: pageRef(page),
+					...links
+				}
+			};
+		}
+	},
+	{
+		name: "lint",
+		summary: "missing titles, MDX that breaks the build, broken links, meta.json against the files",
+		options: [],
+		example: "docs lint",
+		run(docs) {
+			const findings = lint(docs);
+			const text = findings.map((f) => fields(`${f.file}:${f.line}`, f.rule, f.message));
+			return {
+				text: orNone(text, `no problems in ${docs.pages.length} pages`),
+				json: findings,
+				exitCode: findings.length ? 1 : 0
+			};
+		}
+	}
+];
+// src/cli/help.ts
+function signature(c) {
+	const pos = c.positional ? c.positional.required ? ` <${c.positional.name}>` : ` [<${c.positional.name}>]` : "";
+	return `${c.name}${pos}${c.options.map((o) => ` [--${o.name}]`).join("")}`;
+}
+/** What `docs help` prints: one line per command. Agents read it, so it stays short. */
+function usage(commands) {
+	return [
+		"docs <command>: reads this repo's Fumadocs docs (docs/, .mdx, meta.json). A page is its path in docs/ without .mdx (guides/install); its URL and page#anchor work too.",
+		...commands.map((c) => `${signature(c)}: ${c.summary}`),
+		"Every command: --dir <repo or docs folder>, --json.",
+		"docs help <command>: its options and an example."
+	].join("\n");
+}
+function commandHelp(c, globals) {
+	const lines = [`docs ${signature(c)}`, c.summary];
+	if (c.positional) lines.push(`  <${c.positional.name}>: ${c.positional.hint}`);
+	for (const o of [...c.options, ...globals]) lines.push(`  --${o.name}: ${o.hint}`);
+	if (c.example) lines.push(`example: ${c.example}`);
+	return lines.join("\n");
+}
+// src/cli/main.ts
+const GLOBALS = [{
+	name: "dir",
+	hint: "the repo, or the folder that holds the pages"
+}, {
+	name: "json",
+	hint: "print the same data as JSON",
+	flag: true
+}];
+function main(argv, cwd) {
+	const [name, ...rest] = argv;
+	if (!name || [
+		"help",
+		"--help",
+		"-h"
+	].includes(name)) {
+		if (!rest[0]) return {
+			stdout: usage(COMMANDS),
+			exitCode: 0
+		};
+		const command = COMMANDS.find((c) => c.name === rest[0]);
+		if (!command) throw new DocsError(`No command ${rest[0]}. docs help lists them.`);
+		return {
+			stdout: commandHelp(command, GLOBALS),
+			exitCode: 0
+		};
+	}
+	const command = COMMANDS.find((c) => c.name === name);
+	if (!command) throw new DocsError(`No command ${name}. docs help lists them.`);
+	const args = parseArgs({
+		...command,
+		options: [...command.options, ...GLOBALS]
+	}, rest);
+	const docs = loadDocs(findDocsDir(cwd, args.options.dir));
+	const result = command.run(docs, args);
+	return {
+		stdout: args.options.json ? JSON.stringify(result.json, null, 2) : result.text,
+		exitCode: result.exitCode ?? 0
+	};
+}
+// src/bin.ts
+try {
+	const { stdout, exitCode } = main(process.argv.slice(2), process.cwd());
+	process.stdout.write(stdout.endsWith("\n") ? stdout : `${stdout}\n`);
+	process.exitCode = exitCode;
+} catch (err) {
+	const hint = err instanceof DocsError ? "" : " (unexpected: this is a bug in docs)";
+	process.stderr.write(`error: ${err.message}${hint}\n`);
+	process.exitCode = 1;
+}
+export {};

package/package.json

@@ -1,6 +1,62 @@
 {
-  "name": "@marincervinschi/docs",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@marincervinschi/docs",
+	"version": "0.1.1",
+	"description": "Read a project's Fumadocs docs from the terminal, one piece at a time, for coding agents",
+	"license": "MIT",
+	"author": "Marin Cervinschi",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/MarinCervinschi/docs-cli.git"
+	},
+	"keywords": [
+		"fumadocs",
+		"docs",
+		"cli",
+		"mdx",
+		"agents"
+	],
+	"type": "module",
+	"bin": {
+		"docs": "dist/bin.js"
+	},
+	"files": [
+		"dist"
+	],
+	"engines": {
+		"node": ">=22"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"packageManager": "pnpm@10.30.1",
+	"scripts": {
+		"build": "tsdown",
+		"typecheck": "tsc --noEmit",
+		"test": "vitest run",
+		"format": "prettier --write .",
+		"docs": "tsx src/bin.ts",
+		"prepublishOnly": "pnpm typecheck && pnpm test && pnpm build"
+	},
+	"dependencies": {
+		"fumadocs-core": "^16.17.10",
+		"react": "^19.3.1",
+		"remark": "^15.0.1",
+		"remark-mdx": "^3.1.1",
+		"vfile": "^6.0.3"
+	},
+	"devDependencies": {
+		"@trivago/prettier-plugin-sort-imports": "^6.0.2",
+		"@types/mdast": "^4.0.4",
+		"@types/node": "^26.6.6",
+		"prettier": "^3.9.10",
+		"tsdown": "^0.23.4",
+		"tsx": "^4.23.15",
+		"typescript": "^7.0.2",
+		"vitest": "^5.1.0"
+	},
+	"pnpm": {
+		"onlyBuiltDependencies": [
+			"esbuild"
+		]
+	}
+}