Lore

Your code knows what. Lore knows why.
L'or de vos décisions 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 quick 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 essential questions after every commit — Type, What, Why — plus 2 optional ones (Alternatives, Impact) that auto-skip when you answer the first three quickly, or stay in for higher-stakes commits. 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.

Supported platforms: macOS (arm64, x86_64), Linux (arm64, x86_64), Windows (x86_64, arm64). Docs site: greycoderk.github.io/lore (EN+FR).

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	Technical writing precision and clarity
🎨	ux-designer	Gougou	User empathy, mental models, and accessibility
🔌	api-designer	Ouattara	API contracts, synthesizer-ready docs, HTTP semantics
🔍	qa-reviewer	Kouamé	Quality assurance and validation criteria
🏗️	architect	Doumbia	System design, trade-offs, and scalability
📊	business-analyst	Béda	Requirements traceability and business value
📖	storyteller	Affoué	Narrative clarity and authentic storytelling

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?

When you answer Type / What / Why within ~3 seconds, Lore enters express mode and auto-skips Alternatives and Impact. Take more time on a meaningful change and the optional pair stays in. Higher-level routing (full vs reduced vs suggest-skip vs auto-skip) is governed by the Decision Engine — see Contextual Detection below.

Contextual Detection

The hook never blocks a commit and rarely asks questions when it shouldn't. Before any prompt, Lore evaluates a chain of rules — the first match wins:

flowchart TD
    A["Post-commit hook fires"] --> A1["Reconnect stdin (< /dev/tty)"]
    A1 --> B{"doc-skip in message?"}
    B -->|Yes| C["Skip silently"]
    B -->|No| D{"/dev/tty available?<br/>TERM != dumb?"}
    D -->|"No (CI, pipe, dumb term)"| E["Defer to pending"]
    D -->|Yes| F{"Rebase in progress?"}
    F -->|Yes| E
    F -->|No| G{"Merge commit?"}
    G -->|Yes| H["Skip — 1-line message"]
    G -->|No| I1{"Cherry-pick?"}
    I1 -->|Yes| I2{"Doc exists for<br/>source commit?"}
    I2 -->|Yes| C
    I2 -->|No| J1{"Amend?"}
    I1 -->|No| J1
    J1 -->|Yes| J2{"Doc exists for<br/>pre-amend commit?"}
    J2 -->|No| R["Proceed — create new doc"]
    J2 -->|Yes| K0{"Question 0:<br/>Document this? Y/n"}
    K0 -->|No| C
    K0 -->|Yes| K["[U]pdate / [C]reate / [S]kip"]
    J1 -->|No| L["Decision Engine scoring"]
    L --> M{"Score?"}
    M -->|">=60"| N["Ask full questions"]
    M -->|"35-59"| O["Ask reduced questions"]
    M -->|"15-34"| P["Suggest skip — confirm"]
    M -->|"<15"| Q["Auto-skip silently"]
    E --> E2["VS Code IPC<br/>(if GIT_ASKPASS)"]
    E2 -.->|fallback| E3["OS dialog<br/>(osascript / zenity / PowerShell)"]
    E3 -.->|fallback| E4["Lock file<br/>(~/.lore/notify.lock)"]

Loading

Detection rules (priority order):

#	Rule	Action	Reason
1	[doc-skip] in commit message	Skip silently	Explicit developer intent
2	Non-TTY or TERM=dumb	Defer to pending	CI/pipes must never block
3	Rebase in progress	Defer to pending	Avoid prompts during replay
4	Merge commit (2+ parents)	Skip silently	Infrastructure commits
5a	Cherry-pick + source doc exists	Skip silently	Already documented
5b	Cherry-pick + no source doc	Continue evaluation	Source not in corpus — let the next rule decide
6a	Amend + existing doc	Question 0 → [U]pdate / [C]reate / [S]kip	Editing prior work (configurable: hooks.amend_prompt)
6b	Amend + no existing doc	Proceed — create a new doc	First-time documentation of an amended commit
7	Decision Engine score	Score-based action (full / reduced / suggest skip / auto-skip)	Multi-signal analysis on every other commit

Decision Engine tiers (configurable via decision.threshold_* in .lorerc):

Score	Action
≥ 60	Full questions (Type, What, Why, Alternatives, Impact)
35–59	Reduced questions (Type, What, Why)
15–34	Suggest skip — confirm
< 15	Auto-skip silently

Other safety nets: Non-TTY contexts (IDE, CI, Docker, cron) defer to pending and trigger an OS dialog when an IDE is detected. Ctrl+C at any prompt saves partial answers to .lore/pending/ for resume via lore pending resolve.

Full reference: docs/guides/contextual-detection.md (FR).

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-6", "claude-haiku-4-5-20251001", "gpt-4o", "llama3.2"
  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
• Documentation site — full guides, EN + FR
• FAQ — common questions (FR)
• 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 stands on the open-source foundations laid by others — Git, Linux, Go, SQLite, Cobra, Viper, Bubble Tea. That's why Lore is free and open source in turn.

What you see today is an MVP — a foundation, not a finished product. If adoption follows, the next steps are clear: more personas live, dynamic templates, knowledge-graph hints from the existing corpus.

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

Selected direct dependencies (full graph in go.mod / go.sum):

Dependency	License	Used for
cobra	Apache-2.0	Command tree, flag parsing
viper	MIT	Config cascade (.lorerc → env → flags)
bubbletea	MIT	Interactive type selector, persona picker
lipgloss	MIT	Terminal styling
modernc.org/sqlite	BSD-3-Clause	SQLite driver (CGO-free, pure Go)
yaml.v3	MIT + Apache-2.0	YAML front-matter parsing
mapstructure	MIT	Config decoding
x/term	BSD-3-Clause	Terminal detection
x/text	BSD-3-Clause	Unicode normalization (i18n)
pflag	BSD-3-Clause	Cobra flag backend
fsnotify	BSD-3-Clause	Config file watching

License

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