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