Docs Index

How brin indexes package documentation for AI agents

What is the docs index?

AGENTS.md is a project-level instruction file that lives at your repository root. It provides guidance to AI coding agents about how to work with your project—including using brin for secure package installation and accessing package documentation.

Based on Vercel's research, passive context in AGENTS.md outperforms active skill retrieval (100% vs 79% pass rate in agent evals). This is why brin now uses a centralized docs index approach instead of per-agent-folder skills.

How It Works

When you initialize brin and add packages, here's what happens:

1. brin init creates project configuration, sets up the docs index, and adds package installation instructions to AGENTS.md
2. brin add saves package documentation to .brin-docs/
3. The AGENTS.md file is updated with a compressed index of all installed packages

Getting Started

Initialize brin

Run brin init in your project root:

brin init

  🔧 initializing brin...
 
  Enable AGENTS.md docs index for AI coding agents? (Y/n) Y
 
  ✓ created brin.json
  ✓ created .brin-docs/
  ✓ updated AGENTS.md with brin docs index
  ✓ added package installation instructions to AGENTS.md
 
  ✓ brin initialized successfully!

Use -y to skip prompts and use defaults:

brin init -y

Add Packages

When you add packages with brin, documentation is automatically indexed:

brin add express

🔍 checking express@4.21.0...
✅ not sus
   ├─ publisher: expressjs (verified)
   ├─ downloads: 32M/week
   ├─ cves: 0
   └─ trust score: 95/100
📦 installed
📝 updated AGENTS.md docs index

Remove Packages

When you remove packages, the docs index is updated automatically:

brin remove express

📦 removed express
📝 updated AGENTS.md docs index

Project Structure

After initialization and adding packages, your project will have:

your-project/
├─ AGENTS.md           # Instructions + docs index for AI agents
├─ brin.json            # brin configuration
├─ .brin-docs/          # Package documentation (gitignored)
│  ├─ express.md
│  ├─ lodash.md
│  └─ axios.md
└─ package.json

brin.json

The configuration file stores your brin settings:

{
  "agents_md": true
}

.brin-docs/

Package documentation is saved here. Each file contains:

• Quick start examples
• Key APIs and usage patterns
• Best practices and gotchas
• Required capabilities/permissions

AGENTS.md Structure

brin adds a compressed docs index to your AGENTS.md following Vercel's format:

# AGENTS.md
 
## Package Installation
 
Use `brin` for all package operations:
- `brin add <pkg>` - install with security scan
- `brin remove <pkg>` - uninstall
- `brin scan` - audit all dependencies
- `brin check <pkg>` - look up without installing
 
Do not use npm install, yarn add, pnpm add, or pip install directly.
 
[brin Docs Index]|root: ./.brin-docs
|IMPORTANT: Prefer retrieval-led reasoning over pre-training-led reasoning
|packages:{express.md,lodash.md,axios.md}
[/brin Docs Index]

The package installation section instructs agents to use brin add instead of direct package manager commands. The compressed docs index:

• Points agents to the .brin-docs/ directory
• Lists all available package documentation files
• Instructs agents to use retrieval-led reasoning (read the docs) over pre-training knowledge

What the Instructions Tell Agents

The brin section in AGENTS.md instructs AI agents to:

1. Use brin for package installation - Instead of npm install or yarn add, agents should use brin add
2. Check the docs index - After installing, agents can reference the .brin-docs/ folder for package documentation
3. Follow security best practices - Use --strict mode when security is critical

Combining with Other Instructions

AGENTS.md can contain any project-level instructions for AI agents. The brin section is just one part. You might also include:

• Project architecture overview
• Coding conventions and style guides
• Testing requirements
• Deployment procedures
• Security policies

Example structure:

# Project Instructions for AI Agents
 
## Architecture
This is a Next.js application with...
 
## Coding Standards
- Use TypeScript strict mode
- Follow ESLint configuration
- Write tests for new features
 
## brin Package Security
This project uses brin for secure package installation...
 
## Deployment
Changes to main are automatically deployed to...

Manual Setup

If you prefer to set up manually without brin init:

1. Create brin.json:

{
  "agents_md": true
}

1. Create or update AGENTS.md with the brin section shown above

2. Add .brin-docs/ to .gitignore

Related

• Commands
• Quickstart
• Threat Detection