Beacon

Trail markers for AI-collaborative codebases.

Opinionated documentation convention + CLI that scaffolds the structure, generates per-vendor AI rule files (Claude, Cursor, Codex, Gemini), and lints the result.

$ npx beacon-docs init
Read the docs View on GitHub

CLI

The convention. Plus the tools to enforce it.

Four commands cover the full lifecycle of AI-ready documentation.

beacon init

Interactive scaffold wizard.

  • 7 project types with smart detection from package.json
  • 6 core + 6 opt-in category add-ons
  • Generates AI rule files for 4 vendors simultaneously
  • Non-interactive mode for CI with --yes --type=...
beacon sync

Single source of truth.

  • Edit one convention.md, regenerate everything atomically
  • Outputs: CLAUDE.md, AGENTS.md, GEMINI.md, .cursorrules, .cursor/rules/beacon.mdc
  • Idempotent — safe in pre-commit hooks
  • Caught by beacon lint --strict if you forget to run it
beacon new

Type-safe doc creation.

  • 11 doc types: plan, adr, pattern, architecture, module, guide, roadmap, todo, eval, compliance, business
  • ADRs auto-numbered (ADR-001-, ADR-002-…)
  • Evaluations date-prefixed (2026-05-22-name.eval.md)
  • Frontmatter pre-populated, correct folder enforced
beacon lint

11 enforced rules.

  • Errors: suffix/location mismatch, kebab-case, missing READMEs, AI-file sync drift
  • Warnings: duplicate H1s, oversized files, ADR gaps, plans without TODOs
  • --strict for CI gate (warnings become errors)
  • --json for machine-readable output

Comparison

What's different about Beacon?

No other tool combines convention + enforcement + AI rule generation in one place.

Feature Beacon
(this) 		Diátaxis
framework 		adr-tools
ADRs only 		Hand-written
CLAUDE.md 		Docusaurus
docs site
Opinionated structure
Convention enforcement (linter)
AI rule files generation
Multi-vendor support (Claude/Cursor/Codex/Gemini)
Per-vendor format (.md / .mdc / .cursorrules)
Auto-sync (single source of truth)
Per-doc-type naming convention
Status via folder (not filename)
ADR auto-numbering
Date-prefixed evaluations
Configurable add-ons (compliance, business, modules…)
CI-ready out of the box
Zero config required (sensible defaults)

Yes    Partial    No

Architecture

Five AI agents. One convention. Zero drift.

Edit the source once. Beacon regenerates every vendor-specific file automatically.

docs/_meta/convention.md
# Documentation Convention
> Project type: library

## Structure rules
1. One doc = one category.
2. Status via folder, never filename.
3. kebab-case for all filenames.
...
## Where does X go?
| architecture/ | How the system is built |
| adr/ | Why decisions were made |
| plans/ | What's being built now |
beacon sync
→
CLAUDE.md
AGENTS.md
GEMINI.md
.cursorrules
.cursor/rules/beacon.mdc

Edit the convention once. beacon sync regenerates everything. beacon lint --strict catches drift in CI.

Output

What you get after beacon init

A complete, navigable docs structure plus AI rule files — ready in under 30 seconds.

File tree

your-project/ 
├── CLAUDE.md                  ← generated
├── AGENTS.md                  ← generated
├── GEMINI.md                  ← generated
├── .cursorrules               ← generated
├── .cursor/rules/beacon.mdc   ← generated
├── package.json               ← gets docs:lint
└── docs/
    ├── README.md              ← master index
    ├── _meta/
    │   ├── convention.md      ← you edit this
    │   └── beacon.config.json
    ├── reference/
    ├── architecture/
    ├── adr/
    ├── plans/
    │   └── _archive/
    ├── backlog/
    └── evaluations/

Generated CLAUDE.md (preview)

CLAUDE.md 
# Documentation Convention

> Project type: **library**.
> Single source: docs/_meta/convention.md

## Universal rules

1. One doc = one category. Never duplicate.
2. Status via folder, never filename.
   Closed plan → _archive/, not *_DONE.md
3. kebab-case for all filenames.
4. README required in every category folder.
5. ADRs are append-only. Supersede with a new ADR.
6. Evaluations are immutable snapshots.
7. Plans archive to _archive/ when done.
8. Generated AI files must match convention.md.
   Run beacon sync after editing the convention.
9. Don't create folders outside the convention.

## Where does X go?

| How is X done technically?     | reference/    |
| How is the system structured?  | architecture/ |
| Why was X decided?             | adr/          |
| What is being built right now? | plans/        |
| What's on the future backlog?  | backlog/      |
...

Init wizard

7 project types. Smart defaults.

The wizard reads your package.json and suggests the right categories automatically.

web-app

Frontend or fullstack web application.

reference architecture adr plans backlog
backend-service

API, microservice, or server-side application.

reference architecture adr plans operations
library

SDK, npm package, or shared module.

reference architecture adr evaluations
cli-tool

Command-line tool or developer utility.

reference adr plans backlog
mobile-app

iOS, Android, or cross-platform mobile app.

reference architecture adr plans
monorepo

Multi-package or multi-app workspace.

reference architecture adr modules plans
custom

Pick exactly what you need. Fully manual.

your choice

CI / CD

Drop into your existing CI.

Beacon's linter exits with code 1 on errors, making it a first-class CI gate. Add the workflow once and let it catch drift automatically.

  • Runs only when docs or AI files change (paths filter)
  • --strict escalates warnings to errors in CI
  • --json for structured output in tooling
  • Zero extra setup — npx handles the install
.github/workflows/docs-lint.yml 
name: Beacon docs lint
on:
  pull_request:
    paths: ["docs/**", "CLAUDE.md", "AGENTS.md",
             "GEMINI.md", ".cursorrules", ".cursor/**"]
  push:
    branches: [main]
jobs:
  beacon-lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 20 }
      - run: npx beacon-docs lint --strict

Start in 30 seconds.

One command. Complete docs structure. AI rules for every agent.

$ npx beacon-docs init
Read the docs GitHub →