learnchain 0.1.0 → 0.3.0

package/README.md

@@ -2,69 +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`
 
-## Installation
+## Quick Start
 
-### Via npm (Recommended)
+### Install from npm
 
 ```bash
 npm install -g learnchain
-npx learnchain --help
 ```
 
-### From Source
+### Run from source
 
 ```bash
-git clone https://github.com/yourusername/learnchain.git
+git clone https://github.com/normand1/learnchain
 cd learnchain
-cargo build --release
-./target/release/learnchain
+cargo build
+cargo run
 ```
 
-## Quick Start
+## 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
+learnchain --set-openai-key <key>
+learnchain --set-anthropic-key <key>
+learnchain --set-openrouter-key <key>
+```
+
+You can also clear them:
+
+```bash
+learnchain --clear-openai-key
+learnchain --clear-anthropic-key
+learnchain --clear-openrouter-key
+```
+
+You can also configure a generic deep-dive export destination for future document repository integrations:
+
+```bash
+learnchain --set-document-repository notion
+learnchain --set-document-repository-target database/abcd1234
+learnchain --clear-document-repository
+learnchain --clear-document-repository-target
+learnchain --set-notion-api-token <token>
+learnchain --clear-notion-api-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.
+- 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 --generate-codex-deep-dive
+```
+
+Target a specific Codex session id explicitly:
+
+```bash
+learnchain --generate-codex-deep-dive --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 Codex to relay back in chat.
+
+To generate and immediately export the deep dive to the configured document repository:
 
-1. **Configure your OpenAI API key** (required for quiz generation):
-   ```bash
-   npx learnchain --set-openai-key sk-...
-   ```
+```bash
+learnchain --generate-codex-deep-dive --export-to-document-repository
+```
+
+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 --install-codex-deep-dive-skill
+```
+
+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 --print-codex-deep-dive-action
+```
+
+That template tells Codex to run LearnChain with `--codex-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`.
 
-   Or configure it directly in the TUI: Config view → "OpenAI API key" → press Enter to edit
+## Debug Logging
 
-2. **Launch the terminal UI**:
-   ```bash
-   cargo run
-   # or if installed via npm:
-   npx learnchain
-   ```
+To troubleshoot runtime issues, start the app with the debug flag:
 
-3. Navigate the menu to load session logs, configure defaults, and start learning!
+```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 (edition 2024)
-- Node.js >= 16 (for npm distribution)
+- Rust
+- 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 -- --generate-codex-deep-dive
+
+# Generate and export a deep dive for the active Codex session
+cargo run -- --generate-codex-deep-dive --export-to-document-repository
+
+# Install the bundled Codex skill
+cargo run -- --install-codex-deep-dive-skill
+
+# Print the Codex custom command template
+cargo run -- --print-codex-deep-dive-action
+
 # Run tests with output
 cargo test -- --nocapture
 
@@ -72,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.1.0",
-  "description": "Terminal-based learning tool that analyzes AI coding sessions and generates interactive quizzes",
-  "license": "MIT",
+  "version": "0.3.0",
   "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

@@ -59,3 +59,5 @@ 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('Codex tip: Run `npx learnchain --install-codex-deep-dive-skill` to install the LearnChain Codex skill.');
+console.log('Codex tip: Run `npx learnchain --print-codex-deep-dive-action` to print the Codex custom command template.');