Your code knows what. Lore knows why.
L'or de vos decisions techniques.

You're 50 commits in. Six months later, someone asks: "Why did we build it this way?"

Git blame shows who changed what and when. But not why. The reasoning is gone — buried in a Slack thread, a PR comment, or the memory of a developer who left three months ago.

Every codebase has an invisible layer of decisions that code alone can't convey. And every day that passes, more of that knowledge evaporates.

Three questions. Ninety seconds. Done.

$ git commit -m "feat: add JWT auth middleware"
  [1/3] Type [feature]:
  [2/3] What [add JWT auth middleware]:
  [3/3] Why? Because stateless auth scales better than sessions
  Captured  feature-add-jwt-auth-middleware-2026-03-16.md

Lore hooks into your Git workflow and asks 3 questions after every commit — Type, What, Why. The answers become a Markdown file living in your repo, searchable, versionable, portable. No wiki. No SaaS. No friction.

# Homebrew (macOS / Linux)
brew install GreyCoderK/tap/lore

# Snap (Linux)
sudo snap install lore --classic

# Chocolatey (Windows) — package name is lore-cli (bare "lore" was taken)
choco install lore-cli

# Go (any platform)
go install github.com/greycoderk/lore@latest

# Pre-built binaries (macOS / Linux)
curl -sSL https://github.com/GreyCoderK/lore/releases/latest/download/install.sh | sh

Or download from GitHub Releases — binaries for macOS, Linux, and Windows.

For Lore logo in notifications on macOS, install terminal-notifier:

brew install terminal-notifier

Without it, notifications fall back to osascript display notification which does not support custom icons (macOS limitation). Lore attempts to auto-install via Homebrew if available.

# 1. Initialize Lore in your project
lore init
# Creates .lore/ directory and installs the post-commit hook

# 2. Make a commit — Lore asks 3 questions automatically
git add . && git commit -m "Add rate limiting"
# → Type? feature
# → What? Add rate limiting (pre-filled from commit)
# → Why? API was getting hammered, 10K req/min from one client

# 3. See your captured decision
lore show
# → Displays the Markdown document with the full context

# 4. Check your documentation health
lore status
# → Shows coverage, pending commits, corpus stats

# Bonus: document a past commit retroactively
lore new --commit abc1234

Use lore new for standalone documentation with the interactive type selector:

Lore is also complementary to ADRs — it captures the daily why that feeds into bigger architectural decisions.

Angela works as a documentation quality gate in any CI pipeline — no lore init required:

# GitHub Actions — 3 lines
- uses: GreyCoderK/lore@v1
  with:
    path: ./docs

# Any CI — portable script (draft: offline, review: AI)
./scripts/angela-ci.sh --path docs --fail-on warning --install
./scripts/angela-ci.sh --mode review --path docs --all --install

Works on any Markdown directory — with or without YAML front matter. See the Angela in CI guide for details.

1. Type — What kind of change? (feature, bugfix, decision, refactor, note)
2. What — Pre-filled from your commit message. Press Enter to confirm.
3. Why — The one question that matters. Why this approach?

If all 3 answers come in under 3 seconds, Lore enters express mode and skips optional questions.

• Merge commits — Skipped automatically
• Rebase — Deferred to pending
• Cherry-pick with doc — Skipped
• Amend — Updates existing document
• Non-TTY (IDE, CI) — Deferred with OS notification (VS Code, dialog)
• Ctrl+C — Partial answers saved to pending (at any question level, including type selector and amend prompts)

---
type: decision
date: 2026-03-16
status: published
commit: abc1234567890abcdef
generated_by: hook
---
# JWT Auth Middleware

## Why
Stateless authentication scales better than server-side sessions...

## Alternatives Considered
Session-based auth with Redis...

## Impact
Users can now authenticate without server-side state...

# .lorerc
language: "en"           # "en" or "fr" — bilingual UI
ai:
  provider: ""            # "anthropic", "openai", "ollama", or "" (zero-API)
  model: ""               # e.g. "claude-sonnet-4-20250514", "gpt-4o"
  endpoint: ""            # custom endpoint (Groq, Together, Ollama, etc.)
  timeout: 60s
angela:
  max_tokens: 8192        # override auto-computed token limit
hooks:
  post_commit: true
  amend_prompt: true      # ask "Document this change?" on amend

cmd/           → Cobra commands (CLI entry points)
internal/
  domain/      → Interfaces, types, DTOs (no dependencies)
  config/      → Configuration cascade (.lorerc → .lorerc.local → env)
  git/         → Git adapter (hooks, log, diff)
  storage/     → Document storage, front matter, index, doctor
  workflow/    → Reactive (hook) and proactive (lore new) flows
  generator/   → Document generation pipeline
  angela/      → AI-assisted documentation (scoring, polish, review, personas)
  ai/          → AI provider implementations (Anthropic, OpenAI, Ollama)
  brand/       → Embedded assets (logo PNG via //go:embed)
  i18n/        → Bilingual message catalogs (EN/FR, 700+ strings)
  ui/          → Terminal UI (colors, progress spinners, lists)
.lore/
  docs/        → Documentation corpus (Markdown)
  pending/     → Interrupted/deferred commits
  store.db     → LKS index (SQLite, reconstructible)

Principles: Markdown is source of truth. Zero implicit network calls. Atomic writes. stderr for humans, stdout for machines.

Contributions are welcome! See CONTRIBUTING.md for guidelines.

For security vulnerabilities, see SECURITY.md.

• GitHub Issues — Bugs & feature requests
• GitHub Discussions — Q&A, ideas, show & tell
• SUPPORT.md — Where to get help
• CODE_OF_CONDUCT.md — Community guidelines

If Lore helps you capture better decisions, consider sponsoring the project.

AGPL-3.0 — see LICENSE. Commercial license available — see LICENSING.md.