Bundle docs into a package

Why bundle: coding agents that install your package spend 32–54% fewer tokens — and generally fewer tool calls — and stop confidently guessing wrong about your API. Both wins hold for every model tested, frontier included; raw accuracy also rises, most for the small, cheap models a lot of agents run and marginally for frontier ones (evals).

Use this path when you publish a library on npm and want version-matched docs available without a network request. Run leadtype generate --bundle at prepack time, include the output in your published files, and every install ships AGENTS.md + per-topic markdown inside node_modules/<your-package>/.

The website is for humans and HTTP agents. The package-bundled docs are for coding agents, IDEs, and CLI tooling that can read files from the installed dependency.

The flow

Why AGENTS.md, not llms.txt?

llms.txt is a website convention — a file at /llms.txt with absolute URLs that an agent fetches over HTTP. Inside an npm tarball it's the wrong shape: every link points at a hosted URL the agent may not be able to reach, and no major coding agent looks for node_modules/<pkg>/llms.txt anyway.

AGENTS.md is the filesystem convention that solves this. Tools like Claude Code, OpenAI Codex, Cursor, GitHub Copilot, Aider, Devin, and others can read AGENTS.md when working with files on disk. An AGENTS.md inside node_modules/<your-package>/ is the right shape for version-matched package docs: relative links work, no network is required, and the content matches the installed version.

leadtype emits both — llms.txt in website mode for HTTP-discoverable agents, and AGENTS.md in --bundle mode for offline filesystem-discoverable agents.

Generate into the package

npx leadtype generate \
  --bundle \
  --src . \
  --out packages/acme \
  --name "acme" \
  --summary "Docs for acme."

This writes:

Every link inside AGENTS.md is a relative path like ./docs/quickstart.md so the file is meaningful both at packages/acme/AGENTS.md (during local dev) and at node_modules/acme/AGENTS.md (after install).

--bundle skips URL-anchored website artifacts such as llms.txt, llms-full.txt, sitemap, and robots. If your config enables MCP, it still includes the URL-independent retrieval artifacts that leadtype mcp --package needs.

Filter to package-specific docs

A monorepo with one shared docs/ and many packages should bundle only the slice each package owns. Use --include (repeatable) and --exclude:

npx leadtype generate \
  --bundle \
  --src . \
  --out packages/react \
  --name "@c15t/react" \
  --include "frameworks/react/**" \
  --include "shared/**" \
  --exclude "**/internal/**"

Filters are explicit. If the package needs shared overview pages, list them too. --exclude is applied after --include.

Include in the published tarball

Add AGENTS.md and docs to files and run generation as a build or prepack step:

{
  "files": ["dist", "docs", "AGENTS.md", "README.md"],
  "scripts": {
    "build": "tsup && npx leadtype generate --bundle --src ../.. --out ."
  }
}

If you need full control over plugin order or custom validation, run the library APIs directly from a script:

import { rm } from "node:fs/promises";
import { convertAllMdx } from "leadtype/convert";
import { generateAgentsMd, resolveDocsNavigation } from "leadtype/llm";
import { defaultRemarkPlugins } from "leadtype/remark";
import docsConfig from "../../../docs/docs.config";

const REPO_ROOT = `${process.cwd()}/../..`;
const PACKAGE_ROOT = process.cwd();

await rm(`${PACKAGE_ROOT}/docs`, { recursive: true, force: true });
await rm(`${PACKAGE_ROOT}/AGENTS.md`, { force: true });

await convertAllMdx({
  srcDir: `${REPO_ROOT}/docs`,
  outDir: `${PACKAGE_ROOT}/docs`,
  remarkPlugins: defaultRemarkPlugins,
});

// Fail fast on unknown legacy groups or invalid nav refs so a bad config can't ship.
const navigation = await resolveDocsNavigation({
  srcDir: REPO_ROOT,
  nav: docsConfig.navigation,
});
if (navigation.unknown.length > 0) {
  for (const { urlPath, slug } of navigation.unknown) {
    process.stderr.write(`error: ${urlPath} declares unknown group "${slug}".\n`);
  }
  process.exit(1);
}

await generateAgentsMd({
  srcDir: REPO_ROOT,
  outDir: PACKAGE_ROOT,
  product: docsConfig.product,
  nav: docsConfig.navigation,
});

Point your build script at it: "build": "tsup && bun run scripts/generate-docs.ts".

Verify before publishing

npx leadtype generate --bundle --src . --out packages/acme
cd packages/acme && npm pack --dry-run

npm pack --dry-run should list:

• AGENTS.md
• docs/**/*.md

If AGENTS.md is missing, check files in package.json. If .md files are missing, check the --include/--exclude filters.

Point consumers at the bundle

This is the step that makes the bundle pay off. AGENTS.md inside your tarball lands at node_modules/<your-package>/AGENTS.md after install, but agents only discover it on their own ~29% of the time. A root-AGENTS.md pointer in the consuming project pushes that to ~90–100% (evals) — so treat it as required setup, not a nice-to-have.

Recommend this snippet in your published README so consumers add it to their own root AGENTS.md:

When working with the `acme` library, read the bundled docs in
`node_modules/acme/AGENTS.md` first — they're version-matched to the
installed package and stay accurate as it updates.

leadtype generate --bundle prints this snippet — filled in with your package's name — on success, so you don't have to hand-write it. This is the same pattern Next.js uses to point agents at node_modules/next/dist/docs/.

Ship a version-matched MCP server

AGENTS.md works when the agent reads files on disk. For agents that prefer targeted retrieval over a large corpus — search the docs, then fetch one page — enable MCP in docs.config.ts and keep the package command focused on the package output mode:

import { defineDocsConfig } from "leadtype";

export default defineDocsConfig({
  product: {
    name: "acme",
    tagline: "Docs for acme.",
  },
  navigation: ["index", "quickstart"],
  agents: { mcp: { enabled: true } },
});

npx leadtype generate --bundle --src . --out packages/acme

A consumer who installs your package then runs a docs MCP server pinned to the installed version, with no hosting on your side:

leadtype mcp --package acme

The emitted artifacts are URL-independent — they need no --base-url. The old --mcp shortcut still works for compatibility, but it is deprecated; put MCP intent in config for new package scripts. See the MCP server reference for the tools and the hosted-endpoint variant.

Bundle mode also ships a SKILL.md at the package root, next to AGENTS.md — the agent-skills format. Its instructions point an agent at the bundled AGENTS.md/docs, so a skills-aware client (Claude Code, Cursor, …) discovers your docs from node_modules/<pkg> the same way it discovers AGENTS.md.

When to use this

Use this when agents should understand the package from the installed dependency itself — coding agents that don't have web access, IDE assistants, CLI tools, or air-gapped environments.

Don't use this if your only goal is a public docs website. For that, see Build a docs site. You can use both — they read the same source MDX, just emit different shapes.

What's next