White Paper · The Friendly Tour
Everything you need, in one box.
AI coding agents receive your dependencies' code — but not their documentation, so they guess. Think Inside the Box proposes a simple industry standard: ship structured, AI-ready docs inside every package, version-matched to the code they describe.
Meet the New Teammate
A new developer has entered the room.
AI coding assistants are now primary consumers of software documentation — yet libraries still ship as if humans are the only readers.
84%
of developers use or plan to use AI coding tools
51%
use AI tools every single working day
22%
of all production code is AI-generated
- GitHub Copilot has crossed 20 million cumulative users; 90% of Fortune 100 companies have deployed it.
- The dominant mental model has shifted: AI no longer just suggests — it reads documentation, reasons about APIs, and generates complete implementations autonomously.
Statistics: Axis Intelligence — AI Coding Assistant Statistics
The Invisible Crisis
AI goes looking for docs — and finds nothing.
Every day, AI coding assistants hallucinate APIs, invent method signatures, and produce broken code — because documentation is scattered, stale and not machine-friendly.
29%
of developers trust AI-generated code — the lowest figure ever recorded, down from 40% in 2024
1.7×
more issues in AI-coauthored pull requests
Statistics: Axis Intelligence — AI Coding Assistant Statistics
The doc gap is costing teams in debugging time, security incidents, and eroded confidence. Why? Run npm install and the agent receives the library's code. The documentation? It lives elsewhere, and it shows.
Hallucinated APIs
Function signatures, props, and methods invented from outdated training data — APIs that simply don't exist in the version you installed.
Deprecated patterns
Yesterday's idioms, deprecated calls, and pre-release conventions surface as if they were current best practice.
Correction loops
You spot the mistakes, correct the agent, and re-prompt — burning the very productivity AI was supposed to create.
“An agent's best option is reading local files — fast, version-matched, always available. But today, there is almost nothing to read.”
The Shift
Agents read files. Not websites.
When an AI agent meets an unfamiliar library, it has three main options. Only one of them works well.
The Principle
Think Inside the Box.
Buy a flat-pack bookcase and everything arrives in one box — panels, screws, and the instructions. No website. No scavenger hunt. Software libraries should work exactly the same way.
Product
Source code & build artifacts
Instructions
AI-ready docs, guides & examples
The box
The package — tarball, wheel, JAR
Customer
The AI coding agent
The store
The registry — npm, PyPI, Maven
Documentation written for the consumer who actually reads it — the AI agent — shipped in the delivery, not linked from it.
The Standard · CoDoc
One folder, shipped with the code.
The proposal is deliberately minimal: a docs/ directory in every package, with an entry point and an index the agent can scan.
README.md — the 5 Ws
What, When, Why, Where, and HoW — so the agent instantly knows it's in the right place.
index.md — the catalogue
A map of everything inside, so the agent reads only what it needs — never the whole tree.
Plain markdown
One concern per file. Copy-pasteable examples. The format LLMs understand best.
Already working in production. The Design Factory design system ships co-packaged documentation with a complete knowledge base for 56 components — APIs, examples, guidelines, and demos — inside its npm package.
The same convention should work in every ecosystem.
Why Not Servers?
No servers. No skills lottery. Just files.
MCP servers pollute the context window. Skills retrieve probabilistically and drift out of sync. Sub-agents add overhead. Files are deterministic — and reading them is a primitive skill every agent already has.
“Don't add infrastructure when the agent's existing capabilities — reading files and following references — already solve the problem.”
The Economics
Rounding-error cost. Outsized value.
Markdown is tiny, generation is automatable, and consumers need nothing at all. The value — correct code on first generation — is disproportionately large.
< 500 KB
A complete doc set for a mid-size library — next to a 200–500 MBnode_modules folder.
0
Lines of configuration for consumers. No servers, no keys, no bookmarks.
56
Components fully documented in the Design Factory reference implementation.
Security
Docs as context. Never as commands.
Auto-reading content from packages opens a prompt-injection surface. The standard names the risk and bounds it — a lower-severity vector than the supply-chain risk you already accept by running third-party code.
AI tool vendors
Sandbox docs/ content as reference material, with provenance attached — never as system instructions.
Library authors
Ship factual documentation only. No agent directives — and everything reviewable in the source repo.
Package registries
Scan docs/ for injection patterns and sign packages end-to-end with provenance.
We've Seen This Story
Types made this journey. Docs are next.
Types lived in a separate community repository. They drifted from the code, decayed, and coverage was patchy.
First-party types ship inside the package itself. It isn't a feature — it's simply expected.
AI-ready documentation ships inside the package. The same inevitability, one step ahead.
Join In
Ship the docs in the box.
The standard is minimal, the entry bar is low, and adoption can start with the next release. Here's how each part of the ecosystem moves it forward.
Library authors
Add a docs/ folder to your next release. Even a great README is a start.
AI tool vendors
Auto-discover docs/ in installed dependencies.
Package registries
Badge the packages that ship AI-ready docs, and make documentation quality visible.
Developers
Ask the libraries you rely on for co-packaged docs — like the community once asked for types.
© 2026 AI Documentation Working Group · Think Inside the Box · v1.0