learnchain 0.2.2 → 0.4.1

package/README.md

@@ -2,64 +2,195 @@
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-**LearnChain** is a terminal-based learning tool that helps you learn to code while using generative AI to build projects. It analyzes your Codex or Claude session logs and surfaces interactive quizzes in a beautiful terminal UI, reinforcing concepts as you work.
+**LearnChain** is a terminal-based learning tool that turns your AI-assisted coding sessions into quizzes and deep-dive writeups you can review inside a Ratatui interface. It reads session history from Codex CLI or Claude Code, summarizes the work, generates structured lessons and saved markdown deep dives with Rig-backed LLM workflows, and tracks what you have learned over time.
 
 ![Example Movie](readme_resources/example_mov.gif)
 
 ## Features
 
-- **Session Log Analysis**: Parse and learn from your AI-assisted coding sessions
-- **Quiz Generation**: AI-powered quiz creation based on your actual coding patterns
-- **Configuration Management**: Persistent settings stored in `config/app_config.toml`
-- **Multi-platform Support**: Distributed via npm for easy installation across platforms
-- **Interactive TUI**: Built with [Ratatui](https://ratatui.rs) for a polished terminal experience
+- Parse coding sessions from both Codex CLI and Claude Code
+- Generate structured quizzes from your recent or selected historical sessions
+- Generate saved session deep dives with reviewed source links and teaching narratives
+- Support multiple LLM providers: OpenAI, Anthropic, and OpenRouter
+- Use [Rig](https://github.com/0xPlaygrounds/rig) for provider integration and structured output generation
+- Review lessons in an interactive terminal UI with quiz navigation and summaries
+- Browse previously generated deep dives from inside the TUI
+- Track learning history and first-attempt accuracy in a local SQLite database
+- Browse an analytics dashboard for recent learning activity
+- Persist configuration in `config/app_config.toml`
+- Enable per-run debug logging with `--debug`
 
 ## Quick Start
+
+### Install from npm
+
 ```bash
 npm install -g learnchain
 ```
-#### Two options to set API Key:
-Option 1: 
-Start learnchain with 
+
+### Run from source
+
 ```bash
-learnchain
+git clone https://github.com/normand1/learnchain
+cd learnchain
+cargo build
+cargo run
 ```
-Then, 
+
+## Configure an LLM provider
+
+LearnChain can generate quizzes with OpenAI, Anthropic, or OpenRouter. Provider selection, model selection, and API keys are managed in the in-app Config view.
+
+### Option 1: configure inside the TUI
+
+1. Start LearnChain.
+2. Open `Configure details`.
+3. Choose the provider you want to use.
+4. Set the provider-specific model or API key fields.
+5. Save and return to the menu.
+
+### Option 2: configure keys from the CLI
+
 ```bash
-"Configure details" -> "OpenAI API key:" -> (set your api key here) -> Enter -> m (menu)
+learnchain config set openai-key <key>
+learnchain config set anthropic-key <key>
+learnchain config set openrouter-key <key>
 ```
 
-Option 2:
+You can also clear them:
+
 ```bash
-learnchain --set-openai-key <key>
+learnchain config clear openai-key
+learnchain config clear anthropic-key
+learnchain config clear openrouter-key
 ```
 
-## Installation From Source
+You can also configure a generic deep-dive export destination for future document repository integrations:
 
 ```bash
-git clone https://github.com/normand1/learnchain
-cd learnchain
-cargo build
-cargo run
+learnchain config set repository notion
+learnchain config set repository-target database/abcd1234
+learnchain config clear repository
+learnchain config clear repository-target
+learnchain config set notion-token <token>
+learnchain config clear notion-token
+```
+
+## Codex Integration
+
+LearnChain can generate a deep dive for the active Codex session without opening the TUI.
+
+Prerequisites:
+
+- Install LearnChain and configure an LLM provider. This can be an API-backed provider or a local CLI provider such as Codex CLI or Claude Code CLI.
+- Run the command from a Codex session if you want LearnChain to resolve `CODEX_THREAD_ID` automatically.
+
+Generate a deep dive for the active Codex session:
+
+```bash
+learnchain deep-dive generate codex
+```
+
+Target a specific Codex session id explicitly:
+
+```bash
+learnchain deep-dive generate codex --thread-id <thread-id>
+```
+
+The command writes the markdown artifact to `output/deep-dives/` and prints the saved path, title, goal, and accomplishment bullets to stdout for the active coding agent to relay back in chat. The command still resolves Codex sessions, but generation uses whichever provider is selected in LearnChain config, including `Claude Code CLI`.
+
+To generate and immediately export the deep dive to the configured document repository:
+
+```bash
+learnchain deep-dive generate codex --export
 ```
 
+That uses the same repository settings as the Library export flow and prints the repository label plus remote URL when the export succeeds.
+
+To install the real Codex skill into your local Codex skills directory:
+
+```bash
+learnchain skill install codex
+```
+
+This writes the bundled `learnchain-deep-dive` skill into `$CODEX_HOME/skills` when `CODEX_HOME` is set, or `~/.codex/skills` otherwise. Restart Codex after installation so it reloads available skills.
+
+If you want the copy/paste custom-command template as well, print it with:
+
+```bash
+learnchain action print codex
+```
+
+That template tells Codex to run LearnChain with `--thread-id "$CODEX_THREAD_ID"` and return the saved path plus a short summary.
+
+## Usage
+
+The main menu currently supports these core flows:
+
+- Select a historical session, grouped by project, and generate a quiz from it
+- Select a historical session, grouped by project, and generate a session deep dive from it
+- Open the Library view to browse previously saved deep dives and quiz artifacts
+- From the Library view, press `e` to send the selected artifact to the configured document repository
+- Open saved deep-dive history and reload previous markdown artifacts
+- Open the analytics dashboard
+- Configure provider, model, and app defaults
+
+Quiz JSON artifacts can be written to `output/` when `Write quiz artifacts to output` is enabled in the Config view. Session deep dives are always saved to `output/deep-dives/`. The Config view now includes a `Document repository` selector. When `Notion` is selected, LearnChain shows separate fields for `Notion destination` and `Notion API token`. The Notion destination should be the target database/page ID or the full Notion URL, and the UI explains how to create an internal integration and connect it to the database. Library exports create a new page under that configured Notion destination and send the selected deep dive or quiz content into it. Learning history is stored in `output/learning_history.sqlite`.
+
+## Debug Logging
+
+To troubleshoot runtime issues, start the app with the debug flag:
+
+```bash
+cargo run -- --debug
+```
+
+If you are running the installed binary directly:
+
+```bash
+learnchain --debug
+```
+
+This forces the app to write debug logs to:
+
+```text
+output/learnchain-debug.log
+```
+
+The log file is truncated at the start of each debug run so each session starts with a clean log.
+
 ## Development
 
 ### Prerequisites
 
 - Rust
-- Node.js >= 16 (for npm distribution)
+- Node.js >= 16 for npm distribution tasks
 - Cargo
 
-### Build Commands
+### Common commands
 
 ```bash
-# Compile the TUI
+# Build the TUI
 cargo build
 
 # Run the application
 cargo run
 
+# Run with runtime debug logging
+cargo run -- --debug
+
+# Generate a deep dive for the active Codex session
+cargo run -- deep-dive generate codex
+
+# Generate and export a deep dive for the active Codex session
+cargo run -- deep-dive generate codex --export
+
+# Install the bundled Codex skill
+cargo run -- skill install codex
+
+# Print the Codex custom command template
+cargo run -- action print codex
+
 # Run tests with output
 cargo test -- --nocapture
 
@@ -67,55 +198,69 @@ cargo test -- --nocapture
 cargo fmt
 cargo clippy --all-targets --all-features
 
-# Build release binary for npm distribution
+# Build the npm distribution
 npm run build
 ```
 
-### Project Structure
+## Project Structure
 
-```
+```text
 learnchain/
 ├── src/
-│   ├── main.rs              # Entry point and app state
-│   ├── ai_manager.rs        # AI/LLM integration
-│   ├── config.rs            # Configuration management
-│   ├── session_manager.rs   # AI coding tool (Claude/Codex) log processing
+│   ├── main.rs              # Entry point, app state, CLI handling
+│   ├── config.rs            # Configuration and provider/model resolution
+│   ├── llm/                 # Rig-backed learning and deep-dive generation
+│   │   ├── mod.rs           # App-facing orchestration and background task handling
+│   │   ├── backend.rs       # Shared Rig provider clients and typed extraction
+│   │   ├── deep_dive.rs     # Session deep-dive workflow and markdown assembly
+│   │   ├── deep_dive_types.rs # Structured deep-dive payloads and artifact metadata
+│   │   └── types.rs         # Structured quiz payloads and usage types
+│   ├── knowledge_store.rs   # SQLite-backed learning history and analytics
+│   ├── session_manager.rs   # Session orchestration and loading
+│   ├── session_sources/     # Session source implementations
+│   │   ├── mod.rs           # Shared session traits and types
+│   │   ├── codex.rs         # Codex CLI parsing
+│   │   └── claude.rs        # Claude Code parsing
 │   ├── ui_renderer.rs       # Terminal UI rendering
-│   └── view_managers/       # View-specific logic
+│   ├── log_util.rs          # Debug logging support
+│   └── view_managers/       # View-specific interaction logic
 ├── config/                  # Runtime configuration
+├── output/                  # Optional generated artifacts, logs, and SQLite data
 ├── test_fixtures/           # Test fixtures
 ├── scripts/                 # Build and install helpers
 └── dist/                    # npm distribution files
 ```
 
-See [AGENTS.md](AGENTS.md) for detailed development guidelines.
+See [AGENTS.md](AGENTS.md) for repository-specific development guidelines.
 
 ## Configuration
 
-LearnChain stores configuration in `config/app_config.toml`. Key settings include:
+LearnChain stores settings in `config/app_config.toml`. Relevant settings include:
 
-- OpenAI API key (required for quiz generation)
-- Default session log paths
-- UI preferences
+- session source selection
+- default event sampling and quiz sizing
+- active LLM provider
+- provider-specific model and API key fields
+- selected document repository and its repository-specific target
+- Notion API token for Notion-backed document targets
+- whether quiz JSON artifacts should be persisted to disk
 
 ## Contributing
 
-Contributions are welcome! Please:
+Contributions are welcome. Before opening a PR:
 
-1. Fork the repository
-2. Create a feature branch (`git checkout -b feature/amazing-feature`)
-3. Commit your changes (`git commit -m 'Add amazing feature'`)
-4. Push to the branch (`git push origin feature/amazing-feature`)
-5. Open a Pull Request
+1. Run `cargo fmt`
+2. Run `cargo clippy --all-targets --all-features`
+3. Run `cargo test -- --nocapture`
+4. Note any UI changes, config changes, or risky behavior changes in the PR description
 
 See [AGENTS.md](AGENTS.md) for coding standards and testing guidelines.
 
 ## License
 
-Copyright (c) Dave Norman <david.norman.w@gmail.com>
-
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+This project is licensed under the MIT License. See [LICENSE](LICENSE) for details.
 
 ## Acknowledgments
 
-- Built with [Ratatui](https://ratatui.rs) - Rust TUI framework
+- Built with [Ratatui](https://ratatui.rs)
+- LLM integration powered by [Rig](https://github.com/0xPlaygrounds/rig)

package/package.json

@@ -1,21 +1,17 @@
 {
   "name": "learnchain",
-  "version": "0.2.2",
-  "description": "Terminal-based learning tool that analyzes AI coding sessions and generates interactive quizzes",
-  "license": "MIT",
+  "version": "0.4.1",
   "author": "Dave Norman <david.norman.w@gmail.com>",
-  "bin": {
-    "learnchain": "dist/learnchain.js"
-  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/normand1/learnchain"
   },
-  "scripts": {
-    "build": "cargo build --release",
-    "build:all": "echo 'Use GitHub Actions workflow to build all platform binaries'",
-    "postinstall": "node scripts/install.js",
-    "prepublishOnly": "node scripts/generate-launcher.js"
+  "bin": {
+    "learnchain": "dist/learnchain.js"
+  },
+  "description": "Terminal-based learning tool that analyzes AI coding sessions and generates interactive quizzes",
+  "engines": {
+    "node": ">=16"
   },
   "files": [
     "dist/",
@@ -36,7 +32,11 @@
     "education",
     "rust"
   ],
-  "engines": {
-    "node": ">=16"
+  "license": "MIT",
+  "scripts": {
+    "build": "cargo build --release",
+    "build:all": "echo 'Use GitHub Actions workflow to build all platform binaries'",
+    "postinstall": "node scripts/install.js",
+    "prepublishOnly": "node scripts/generate-launcher.js"
   }
 }

package/scripts/install.js

@@ -58,4 +58,6 @@ if (platform !== 'win32') {
 
 console.log(`✓ learnchain installed successfully for ${platform}-${arch}`);
 console.log('\nRun: npx learnchain --help');
-console.log('Tip: Run `npx learnchain --set-openai-key <your-key>` to configure your OpenAI API key.');
+console.log('Tip: Run `npx learnchain config set openai-key <your-key>` to configure your OpenAI API key.');
+console.log('Codex tip: Run `npx learnchain skill install codex` to install the LearnChain Codex skill.');
+console.log('Codex tip: Run `npx learnchain action print codex` to print the Codex custom command template.');