learning-agent 0.1.0 → 0.2.1

package/CHANGELOG.md

@@ -7,8 +7,48 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.1] - 2026-02-01
+
+### Added
+
+- **CLI Commands**
+  - `lna` short alias for `learning-agent` CLI
+  - `show <id>` - Display lesson details
+  - `update <id>` - Modify lesson fields (insight, severity, tags, confirmed)
+  - `delete <id>` - Create tombstone for lesson removal
+  - `download-model` - Download embedding model (~278MB)
+  - `--severity` flag for `learn` command to set lesson severity
+
+- **Documentation**
+  - Complete lesson schema documentation in README
+  - Required vs optional fields explained
+  - Session-start loading requirements (type=full + severity=high + confirmed=true)
+  - "Never Edit JSONL Directly" warning in AGENTS.md template
+
+### Changed
+
+- `setup claude` now defaults to project-local (was global)
+- `setup claude --global` required for global installation
+- `init` now includes `setup claude` step by default
+- Auto-sync SQLite after every CLI mutation (learn, update, delete, import)
+
+### Fixed
+
+- Pre-commit hook now inserted before exit statements (not appended after)
+- JSONL edits properly sync to SQLite index
+- High-severity lessons load correctly at session start
+
+## [0.2.0] - 2026-01-31
+
 ### Added
 
+- **Claude Code Integration**
+  - `learning-agent setup claude` - Install SessionStart hooks into Claude Code settings
+  - `--project` flag for project-level hooks (vs global)
+  - `--uninstall` to remove hooks
+  - `--dry-run` to preview changes
+  - Automatic lesson injection at session start, resume, and compact events
+
 - **Storage Enhancements**
   - Compaction system for archiving old lessons and removing tombstones
   - Smart sync: rebuild index only when JSONL changes
@@ -27,14 +67,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Simplified model download using node-llama-cpp resolveModelFile
 
 - **Testing**
-  - 100% statement/function/line coverage (435 tests)
-  - Property-based tests with fast-check
+  - 501 tests with property-based testing (fast-check)
   - Integration tests for capture workflows
 
 ### Changed
 
 - Unified QuickLesson and FullLesson into single Lesson type
 - Removed deprecated type exports
+- `check-plan` now hard-fails on embedding errors (exit non-zero with actionable message)
+- `capture` and `detect --save` now require `--yes` flag for saves
+- `learn` command always saves with `confirmed: true`
+- Hook installation is non-destructive (appends to existing hooks)
+- Hook installation respects `core.hooksPath` git configuration
+
+### Fixed
+
+- Embedding errors no longer masked as "no relevant lessons" in check-plan
+- Git hooks no longer overwrite existing pre-commit hooks
+- AGENTS.md template now includes explicit plan-time instructions
 
 ## [0.1.0] - 2025-01-30
 
@@ -91,5 +141,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Vitest test suite
   - tsup build configuration
 
-[Unreleased]: https://github.com/nathanbraun/learning_agent/compare/v0.1.0...HEAD
-[0.1.0]: https://github.com/nathanbraun/learning_agent/releases/tag/v0.1.0
+[Unreleased]: https://github.com/Nathandela/learning_agent/compare/v0.2.1...HEAD
+[0.2.1]: https://github.com/Nathandela/learning_agent/compare/v0.2.0...v0.2.1
+[0.2.0]: https://github.com/Nathandela/learning_agent/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/Nathandela/learning_agent/releases/tag/v0.1.0

package/README.md

@@ -111,13 +111,42 @@ learning-agent compact
 
 ## Claude Code Integration
 
-Add to your `.claude/settings.json` to automatically load lessons:
+### Automatic Setup (Recommended)
+
+```bash
+# Install hooks into Claude Code settings (global)
+npx learning-agent setup claude
+
+# Install to project only
+npx learning-agent setup claude --project
+
+# Preview what would change
+npx learning-agent setup claude --dry-run
+
+# Remove hooks
+npx learning-agent setup claude --uninstall
+```
+
+This installs a SessionStart hook that automatically loads lessons when Claude starts, resumes, or compacts context.
+
+### Manual Setup
+
+Add to your `~/.claude/settings.json`:
 
 ```json
 {
   "hooks": {
-    "session_start": "npx learning-agent load-session",
-    "pre_plan": "npx learning-agent check-plan"
+    "SessionStart": [
+      {
+        "matcher": "startup|resume|compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx learning-agent load-session 2>/dev/null || true"
+          }
+        ]
+      }
+    ]
   }
 }
 ```
@@ -127,7 +156,7 @@ Add to your `.claude/settings.json` to automatically load lessons:
 | Command | Purpose |
 |---------|---------|
 | `load-session` | Load high-severity lessons at session start |
-| `check-plan` | Retrieve relevant lessons when planning |
+| `check-plan --plan "..."` | Retrieve relevant lessons when planning |
 
 ## API Reference
 
@@ -153,33 +182,120 @@ import {
 
 See [examples/](examples/) for usage examples.
 
-## Lesson Types
+## Lesson Schema
+
+Lessons are stored in JSONL format with Zod validation. Understanding the schema is critical for correct usage.
+
+### Required Fields
+
+Every lesson **must** have these fields:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | string | Unique identifier (e.g., "L1a2b3c4d") |
+| `type` | "quick" \| "full" | Lesson quality tier (see below) |
+| `trigger` | string | What caused this lesson to be learned |
+| `insight` | string | The actual lesson content |
+| `tags` | string[] | Categorization tags (can be empty) |
+| `source` | enum | How it was captured: "user_correction", "self_correction", "test_failure", "manual" |
+| `context` | object | `{ tool: string, intent: string }` - what was happening |
+| `created` | string | ISO8601 timestamp |
+| `confirmed` | boolean | Whether user confirmed this lesson |
+| `supersedes` | string[] | IDs of lessons this replaces (can be empty) |
+| `related` | string[] | IDs of related lessons (can be empty) |
+
+### Optional Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `evidence` | string | Supporting evidence (typically for "full" type) |
+| `severity` | "high" \| "medium" \| "low" | Importance level |
+| `pattern` | object | `{ bad: string, good: string }` - code pattern |
+| `deleted` | boolean | Tombstone marker for deletions |
+| `retrievalCount` | number | Times this lesson was retrieved |
+
+### Type vs Severity (Important!)
+
+**`type`** and **`severity`** are **separate** fields:
+
+- **`type`**: Quality tier of the lesson
+  - `"quick"` - Minimal capture, fast to create
+  - `"full"` - Detailed lesson with evidence/patterns
+
+- **`severity`**: Importance level (optional field)
+  - `"high"` - Critical, loaded at every session start
+  - `"medium"` - Important, retrieved when relevant
+  - `"low"` - Minor, lower retrieval priority
+
+**Common mistake**: Using `type: "high"` instead of `type: "full"` with `severity: "high"`.
+
+### Session-Start Loading
+
+High-severity lessons are automatically loaded at session start. For a lesson to load:
+
+1. `type` must be `"full"`
+2. `severity` must be `"high"`
+3. `confirmed` must be `true`
+
+### Complete Examples
+
+#### Quick Lesson (minimal)
 
-### Quick Lesson (fast capture)
 ```json
 {
-  "id": "L001",
+  "id": "L1a2b3c4d",
   "type": "quick",
   "trigger": "Used pandas for 500MB file",
-  "insight": "Polars 10x faster",
+  "insight": "Polars is 10x faster for large files",
   "tags": ["performance", "polars"],
-  "source": "user_correction"
+  "source": "user_correction",
+  "context": { "tool": "edit", "intent": "optimize CSV processing" },
+  "created": "2025-01-30T14:00:00Z",
+  "confirmed": true,
+  "supersedes": [],
+  "related": []
 }
 ```
 
-### Full Lesson (detailed, high-severity)
+#### Full Lesson with High Severity (loads at session start)
+
 ```json
 {
-  "id": "L002",
+  "id": "L5e6f7g8h",
   "type": "full",
   "trigger": "Auth API returned 401 despite valid token",
   "insight": "API requires X-Request-ID header",
-  "evidence": "Traced in network tab, header missing",
+  "evidence": "Traced in network tab, header was missing",
+  "tags": ["api", "auth"],
   "severity": "high",
-  "source": "test_failure"
+  "source": "test_failure",
+  "context": { "tool": "bash", "intent": "run auth integration tests" },
+  "created": "2025-01-30T15:30:00Z",
+  "confirmed": true,
+  "supersedes": [],
+  "related": ["L1a2b3c4d"],
+  "pattern": {
+    "bad": "requests.get(url, headers={'Authorization': token})",
+    "good": "requests.get(url, headers={'Authorization': token, 'X-Request-ID': uuid4()})"
+  }
 }
 ```
 
+### Creating Lessons via CLI
+
+Always use the CLI to create lessons (never edit JSONL directly):
+
+```bash
+# Quick lesson
+npx lna learn "Use Polars for large files"
+
+# Full lesson with high severity (loads at session start)
+npx lna learn "API requires X-Request-ID header" --severity high
+
+# With trigger context
+npx lna learn "Use uv not pip" --trigger "pip was slow" --severity medium
+```
+
 ## Technology Stack
 
 | Component | Technology |
@@ -208,7 +324,7 @@ pnpm lint
 
 ## Project Status
 
-Version 0.1.0 - Core infrastructure implemented. See [doc/SPEC.md](doc/SPEC.md) for the full specification and [doc/PLAN.md](doc/PLAN.md) for the implementation roadmap.
+Version 0.2.1 - Bug fixes and documentation improvements. See [doc/SPEC.md](doc/SPEC.md) for the full specification and [CHANGELOG.md](CHANGELOG.md) for recent changes.
 
 ## Documentation