Lore

Lightweight documentation framework for codebases — designed for humans and AI agents.

LORE is a folder. Seven Markdown files. No special tools. No build step. It lives in your repo, versions with your code, and gives every developer (and every AI agent) the context they need to work effectively.

LORE/
├── README.md       ← What is this and how do I run it?
├── ARCH.md         ← How is the system organized?
├── STACK.md        ← What technologies and why?
├── DATA.md         ← How does data flow and what does it look like?
├── OPS.md          ← How is it deployed and operated?
├── DECISIONS.md    ← Why were things built this way?
└── GENERATE.md     ← Instructions for AI agents to create/update docs

Quick start

Install from npm (@nanojaus/lore) and run via add-lore:

npx @nanojaus/lore

After a global install (npm install -g @nanojaus/lore), use add-lore on your PATH.

Run it at the root of any repo. Answer a few questions. Get your LORE/ folder.

Or target a specific directory:

npx @nanojaus/lore ./my-project

Philosophy

One file = one question someone would ask when arriving at the codebase.

If it doesn't exist, it doesn't apply. A CLI with no public API doesn't need an API.md.

Minimum viable, maximum useful. One useful line beats an empty section.

Built for AI agents. LORE/GENERATE.md tells any agent how to create or update documentation autonomously. LORE/DECISIONS.md prevents agents from re-proposing decisions that were already evaluated and rejected.

What gets generated

Always

File	Purpose
LORE/README.md	Project orientation and local setup
LORE/ARCH.md	System diagram and module map
LORE/STACK.md	Tech choices with rationale
LORE/DATA.md	Data model and invariants
LORE/OPS.md	Deploy, infra, and runbook
LORE/DECISIONS.md	Non-obvious decisions with context
LORE/GENERATE.md	Agent instructions for creating/updating LORE
.github/pull_request_template.md	PR checklist to keep LORE updated

Optional (you choose during init)

File	Purpose
LORE/API.md	Public API surface with examples
CLAUDE.md	Instructions for Claude Code
AGENTS.md	Instructions for other AI agents

For large systems

If you declare your system as "large", add-lore generates domain subfolders:

LORE/
├── README.md          ← global system overview
├── ARCH.md            ← map of all domains
├── DECISIONS.md       ← cross-domain decisions
│
├── auth/
│   ├── README.md
│   ├── DATA.md
│   └── DECISIONS.md
│
└── payments/
    ├── README.md
    ├── DATA.md
    └── API.md

Keeping LORE updated

The generated .github/pull_request_template.md includes a LORE checklist on every PR — the most effective way to keep documentation current.

For AI-assisted updates, point your agent to LORE/GENERATE.md:

"Read LORE/GENERATE.md and update the documentation based on the changes in this PR."

How LORE relates to other tools

Tool	What it does	Relationship
OpenAPI / Swagger	Exhaustive API contract	LORE/API.md links to it; covers the "why" OpenAPI can't
OpenSpec	Feature-level spec and change proposals	Complementary — OpenSpec for features, LORE for the system
ADRs	Architecture Decision Records	LORE/DECISIONS.md is a lighter ADR — same idea, less ceremony
CLAUDE.md / AGENTS.md	Agent behavior instructions	Thin wrappers that point to LORE as the knowledge source

Contributing

Issues and PRs welcome. See LORE/ in this repo for how it's structured.

License

MIT