lore

README

Lore

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

---

The Problem

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.

The Solution

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.

Installation

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

# Chocolatey (Windows) — package name is lore-cli (bare "lore" was taken)
# NOTE: Chocolatey moderation is pending — until approved, use the GitHub Releases
# Windows binary or the `go install` path below. Re-enable once package is live.
choco install lore-cli

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

# Pre-built binaries (macOS / Linux)
curl -sSfL https://raw.githubusercontent.com/GreyCoderK/lore/main/install.sh | sh

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

Optional (macOS only) — Notification icons

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.

Quickstart (5 minutes)

# 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

Interactive Mode

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

How Lore Compares

	Lore	Swimm	Confluence	GitBook	Nothing
When	Commit-time	After the fact	After the fact	After the fact	Never
Where	Local (.lore/)	SaaS	SaaS	SaaS	—
Friction	90 seconds	30 minutes	30 minutes	15 minutes	0
AI	Angela (opt-in)	Generic	Generic	Generic	—
Lock-in	Markdown	Proprietary	Proprietary	Mixed	—
Price	Free	$28/seat	$5.75/user	$8/user	Free

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

Commands

Command	Description
lore init	Initialize Lore in the current repository
lore new	Create documentation on demand
lore new --commit <hash>	Document a past commit retroactively
lore show [query]	Search and display documents
lore list	List all documents in the corpus
lore status	Repository health dashboard
lore status --badge	Generate shields.io coverage badge
lore delete <file>	Delete a document with confirmation
lore pending	List undocumented commits
lore pending resolve	Resume interrupted documentation
lore pending skip <hash>	Skip a pending commit
lore doctor	Diagnose corpus inconsistencies
lore doctor --fix	Auto-repair fixable issues
lore doctor --config	Validate .lorerc configuration
lore release [tag]	Generate release notes from corpus
lore demo	Interactive demo of the workflow
lore hook install	Install the post-commit hook
lore config	Show current configuration
lore angela draft	Zero-API structural analysis
lore angela draft --path ./docs	Standalone mode — any Markdown directory, no lore init
lore angela polish	AI-assisted rewrite with diff review
lore angela polish --for "CTO"	Audience-adapted rewrite
lore angela polish --auto	Auto-accept additions, reject deletions
lore angela review	Corpus-wide coherence analysis
lore angela review --filter "guides/.*"	Review filtered subset
lore angela review --all	Review all docs (no sampling)
lore angela review --persona <id>	Multi-persona coherence — tech-writer, architect, etc.
lore angela consult <persona> <file>	Offline single-persona draft-check on one doc
lore decision	Decision engine status and calibration
lore completion <shell>	Generate shell completions (bash/zsh/fish)

Angela in CI (Standalone)

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.

Personas — not a generic AI, a team that knows your project

Angela doesn't work alone. She leans on a system of expert personas — Affoué (the storyteller, who keeps the why clearer than the what), Ouattara (the API designer, for Postman contracts and technical specs), and others. Each lens has its own priorities and blind spots:

Icon	ID	Name	Focus
✏️	tech-writer	Salou	Rédactionnel, précision, clarté
🎨	ux-designer	Gougou	Mental models, onboarding, accessibilité
🔌	api-designer	Ouattara	Contrats d'API, headers, body, exemples HTTP
🔍	qa-reviewer	Kouamé	Edge cases, validation, failure modes
🏗️	architect	Doumbia	Trade-offs, scalabilité, design
📊	business-analyst	Béda	Traçabilité, valeur business
📖	storyteller	Affoué	Narration, onboarding long-form

Personas activate in three modes:

lore angela consult tech-writer docs/features/login.md       # single-lens offline
lore angela polish docs/features/login.md --persona ux-designer    # steer the AI rewrite
lore angela review --persona tech-writer --persona qa-reviewer     # multi-persona corpus review

Full reference: docs/commands/angela-personas.md (also available in FR).

How It Works

The Documentation Flow

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.

Contextual Detection

• 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)

Document Format

---
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...

Configuration

File	Purpose	Git
.lorerc	Shared project config	Committed
.lorerc.local	Personal overrides (API keys)	Gitignored
LORE_* env vars	CI/automation overrides	—

# .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

Architecture (for contributors)

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.

Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

For security vulnerabilities, see SECURITY.md.

Community

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

Sponsor

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

On the shoulders of giants

Lore wouldn't exist without the open source foundations laid by others — Git, Linux, Go, SQLite, Cobra, Viper. When you build to last, you stand on the shoulders of giants. That's why Lore is free and open source in turn.

What you see today is an MVP. A solid foundation, built with the right tools. But it's only a beginning. If adoption follows, the best is still to come — more personas, more integrations, more languages, more intelligence.

That signal is you. Test it. Break it. Contribute. Tell us what's missing.

Built solo from Côte d'Ivoire. Bilingual EN/FR. Made to last.

Third-Party Notices

Dependency	License
cobra	Apache-2.0
afero	Apache-2.0
mousetrap	Apache-2.0
pflag	BSD-3-Clause
fsnotify	BSD-3-Clause
x/term	BSD-3-Clause
x/sys	BSD-3-Clause
x/text	BSD-3-Clause

License

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