@lore-ai/cli 0.1.6

package/README.md

@@ -0,0 +1,178 @@
+# Lore
+
+**Automated project knowledge that writes itself.**
+
+Lore is a CLI that runs periodic agentic scans over your development activity -- git history, AI coding conversations (Cursor, Claude Code) -- and distills them into living, always-current project documentation.
+
+## Installation
+
+### CLI
+
+```bash
+# Global install
+npm install -g @lore-ai/cli
+
+# Or run directly
+npx @lore-ai/cli
+```
+
+### Editor Extension
+
+Search **"Lore"** in the VS Code or Cursor extension marketplace, or install manually from a [GitHub Release](https://github.com/matan1542/lore/releases):
+
+```bash
+# VS Code
+code --install-extension lore-cursor-extension-<version>.vsix
+
+# Cursor
+cursor --install-extension lore-cursor-extension-<version>.vsix
+```
+
+### Prerequisites
+
+- **Node.js 18+**
+- **Git** -- for scanning commit history
+- **Claude Code CLI** (`claude`) -- for AI-powered distillation ([install](https://docs.anthropic.com/en/docs/claude-code/overview))
+- **GitHub CLI** (`gh`) -- optional, for PR metadata scanning ([install](https://cli.github.com/))
+
+## Quick Start
+
+```bash
+# Initialize Lore in your project
+lore init
+
+# Run your first scan
+lore sync
+
+# Check what was captured
+lore status
+
+# Review proposed documentation updates
+lore review
+
+# Ask questions about your project
+lore recall "why did we choose TypeScript?"
+
+# Start automatic periodic scanning
+lore watch
+```
+
+## How It Works
+
+```
+Developer writes code
+        |
+        v
+Git commits + AI conversations accumulate
+        |
+        v
+   [ lore sync ]  <-- manual or cron trigger
+        |
+        +---> Scans git log (commits, diffs)
+        +---> Scans GitHub PRs (titles, reviews, comments)
+        +---> Scans Claude Code sessions (JSONL transcripts)
+        +---> Scans Cursor conversations (workspace storage)
+        +---> Reads current documentation state
+        |
+        v
+   [ Alignment Engine ]
+        |
+        +---> Matches commits to conversations (by file overlap, branch, timing)
+        +---> Produces: matched pairs, unmatched commits, unmatched conversations
+        |
+        v
+   [ Agentic Distillation ] (via Claude Code CLI + Octocode MCP)
+        |
+        +---> Extracts what changed and WHY
+        +---> Identifies architectural decisions
+        +---> Detects emerging patterns
+        +---> Finds stale documentation
+        |
+        v
+   [ Documentation Output ]
+        |
+        +---> Updates CHANGELOG.md
+        +---> Creates Architecture Decision Records (ADRs)
+        +---> Updates architecture docs
+        +---> Queues items for human review
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `lore init` | Set up Lore for a repository. Auto-detects available sources. |
+| `lore sync` | Run a one-off scan, distill, and write cycle. |
+| `lore watch` | Start periodic scanning on a cron schedule. |
+| `lore status` | Show scan history, pending reviews, and source status. |
+| `lore recall <topic>` | Query accumulated knowledge about a topic. |
+| `lore review` | Interactively review and approve proposed doc updates. |
+| `lore config [get\|set] <key> [value]` | View or edit configuration. |
+
+## Configuration
+
+After `lore init`, configuration lives in `.lore/config.json`:
+
+```json
+{
+  "sources": {
+    "git": { "enabled": true },
+    "github": { "enabled": true, "repo": "owner/repo" },
+    "cursor": { "enabled": true },
+    "claudeCode": { "enabled": true }
+  },
+  "outputs": {
+    "changelog": "CHANGELOG.md",
+    "adr": "docs/decisions/",
+    "architecture": "docs/architecture.md"
+  },
+  "schedule": "0 */4 * * *",
+  "reviewMode": "propose"
+}
+```
+
+### Review Modes
+
+- **`propose`** (default): All doc updates go to `.lore/pending/` for human review via `lore review`.
+- **`auto`**: Changes are applied directly to documentation files.
+
+## Data Sources
+
+### Git History
+Scans commits, diffs, and changed files since the last sync.
+
+### GitHub PRs
+Uses `gh` CLI to fetch merged PRs, review comments, and discussions.
+
+### Claude Code Sessions
+Reads JSONL transcripts from `~/.claude/projects/`. Extracts conversation turns, tool usage, and files modified.
+
+### Cursor Conversations
+Reads conversation metadata from Cursor's workspace SQLite storage.
+
+## Alignment Engine
+
+The key insight: **conversations explain the "why" behind commits**. Lore aligns them using:
+
+1. **File overlap** (strongest): files edited in conversation match files in commit diff
+2. **Branch + time window**: same branch, commit within session timeframe
+3. **Commit message match**: session contains a git commit command with matching message
+
+Unmatched conversations (planning, research, debugging sessions) are also captured -- they contain decisions and knowledge even when no code was committed.
+
+## Architecture
+
+Built with:
+- **TypeScript** with strict mode
+- **Commander** for CLI framework
+- **Clack** for beautiful interactive prompts
+- **Zod** for runtime validation
+- **Simple-git** for git operations
+- **Execa** for subprocess management
+- **Claude Code CLI** for AI-powered distillation
+- **Octocode MCP** for code research during distillation
+
+## License
+
+MIT
+# lore