From df1261ae7a5beadcf1f8d8f5ada5b60e1609fc7e Mon Sep 17 00:00:00 2001 From: Codex Date: Wed, 6 May 2026 13:31:26 +0000 Subject: [PATCH] docs: refresh public README --- README.md | 169 ++++++++++++++++++++++-------------------------------- 1 file changed, 69 insertions(+), 100 deletions(-) diff --git a/README.md b/README.md index 8a6f356..b4b8c03 100644 --- a/README.md +++ b/README.md @@ -1,133 +1,102 @@ -# learning-lab +# Learning Lab -A skill-based learning pipeline for Claude Code. Feed it any source — YouTube video, web page, PDF, or local file — and it produces a structured learning package. Final knowledge gets exported to an Obsidian vault. +Learning Lab is a skill-based learning pipeline for Claude Code that turns a source such as a YouTube video, web page, PDF, or local file into a structured learning package and an Obsidian-ready research note. -**NotebookLM is the primary analysis engine.** Heavy AI analysis runs on Google at zero token cost. Claude Code orchestrates the pipeline and formats the output. +## Current Status ---- +The repository contains the Python orchestration code, state-machine helpers, vault export scripts, tests, and documentation for a local learning workflow. NotebookLM is the preferred heavy-analysis engine, while Claude Code orchestrates ingestion, structuring, gap-filling, optional project rebuilds, and final vault export. -## How It Works +Workspace drafts are intentionally treated as working material; polished vault exports are the long-term output. -``` -Source (YouTube / web / PDF / text) - │ - ▼ - [learn-source] - │ 1. Detect & ingest (yt-dlp / defuddle / Read) - │ 2. Send to NotebookLM (create → add source → generate) - │ 3. Structure output into 8-file learning package - │ 4. Run adversarial logic check - ▼ - workspace/{slug}/ ← German, working drafts - │ - ├── [fill-gaps] → Research answers for open questions - ├── [rebuild-project] → projects/{slug}/ (optional, tutorials only) - │ - └── [save-to-vault] → The Vault/research/{Note}.md (English, final) -``` - ---- - -## Skills +## Key Capabilities -| Skill | Trigger | What it does | -|-------|---------|--------------| -| `lab-master` | "lab run", `/lab --auto ` | Master skill that chains all skills. `--auto` = zero interaction. | -| `learn-source` | URL or file path | Ingest → NLM analysis → 8-file learning package | -| `fill-gaps` | "fill gaps", "fülle Lücken" | Web search for open questions → integrate answers | -| `rebuild-project` | "rebuild", "baue nach" | Build a minimal MVP from a tutorial source | -| `save-to-vault` | "save to vault", "speichere im Vault" | Export to Obsidian vault with full asset bundle | +- Source ingestion for YouTube, web pages, PDFs, and local Markdown/text files. +- NotebookLM handoff for study guides and long-form analysis. +- Eight-file learning package generation for structured study. +- Optional gap-filling and tutorial rebuild flow. +- Vault export with asset bundles, daily-note entries, and stable source fingerprints. +- Run-state validation and tests for the state machine and vault sync code. ---- +## Workflow -## Learning Package (8 files, German) - -Each source produces a `workspace/{slug}/` folder: +```text +Source URL or file + -> ingest + -> NotebookLM analysis + -> workspace/{slug}/ learning package + -> optional fill-gaps or rebuild-project + -> vault export +``` -| File | Contents | -|------|----------| -| `00_zusammenfassung.md` | Executive summary + core thesis | -| `01_kernkonzepte.md` | Key concepts with definitions | -| `02_schritt_fuer_schritt.md` | Step-by-step walkthrough | -| `03_uebungen.md` | Flashcards and exercises | -| `04_projekt_rebuild.md` | Rebuild blueprint (tutorial sources only) | -| `05_offene_fragen.md` | Open questions and gaps | -| `06_notebooklm_artefakte.md` | NLM deliverable paths and notebook info | -| `07_logik_check.md` | Bias analysis, missing counter-arguments | +Default package files: ---- +- `00_zusammenfassung.md` +- `01_kernkonzepte.md` +- `02_schritt_fuer_schritt.md` +- `03_uebungen.md` +- `04_projekt_rebuild.md` +- `05_offene_fragen.md` +- `06_notebooklm_artefakte.md` +- `07_logik_check.md` -## Source Types +Useful docs: -| Type | Tool | -|------|------| -| YouTube URL | `yt-dlp` → transcript → NLM | -| Web page URL | `defuddle` → clean markdown → NLM | -| PDF file | Claude Code Read → NLM | -| Local `.md` / `.txt` | Claude Code Read → NLM | +- [Workflow Spec](docs/workflow-spec.md) +- [Workflow Plan](docs/workflow-plan.md) +- [Vault Format Reference](docs/vault-format-reference.md) ---- +## Quick Start -## Prerequisites +Install the external tools used by the pipeline: ```bash pip install yt-dlp notebooklm npm install -g defuddle -notebooklm login # browser OAuth — run once in a separate terminal +notebooklm login +``` -# Token-efficiency tools: -cargo install --git https://github.com/rtk-ai/rtk # or download rtk binary -winget install Buzz # offline whisper transcription +Run local tests: + +```bash +python3 -m pytest tests -q ``` ---- +The main implementation modules live in [`app/`](app/), while utility scripts live in [`scripts/`](scripts/). ## Repository Layout -``` -learning-lab/ -├── .claude/ -│ ├── settings.json # vault_path + tool permissions -│ └── skills/ -│ ├── lab-master/ -│ ├── learn-source/ -│ ├── fill-gaps/ -│ ├── rebuild-project/ -│ └── save-to-vault/ -├── docs/ -│ ├── vault-format-reference.md -│ └── workflow-spec.md -├── scripts/ -│ ├── run_state.py # run.json state machine -│ └── vault_sync.py # Vault asset export + migration -├── tests/ # pytest suite for scripts -├── sources/ # gitignored — raw transcripts and NLM output -├── workspace/ # gitignored — 8-file learning packages -├── projects/ # gitignored — MVP project rebuilds -├── CLAUDE.md -└── README.md +```text +app/ pipeline orchestration, config, ingestion, preflight, NotebookLM helpers +scripts/ run-state and vault-sync helpers +tests/ unit tests for state and vault behavior +docs/ workflow and vault format documentation +sources/ gitignored source artifacts +workspace/ gitignored learning packages +projects/ gitignored rebuild projects ``` ---- +## Verification -## Vault Integration +Recommended checks: -Polished notes are exported to a separate Obsidian vault. Each export produces: - -- `research/{Note-Title}.md` — English research note with full YAML frontmatter and wiki-links -- `research/assets/{source_type}/{slug}/Source Bundle.md` — index of all source artifacts -- `research/assets/{source_type}/{slug}/transcript.txt` — raw source transcript -- `research/assets/{source_type}/{slug}/study-guide.md` — NLM study guide -- `daily-notes/{YYYY-MM-DD}.md` — daily note entry (marker-based, deduped) +```bash +git diff --check +python3 -m pytest tests -q +python3 -m unittest tests.test_run_state tests.test_vault_sync +``` -The vault path is configured in `.claude/settings.json` → `vault_path`. +Preflight expectations are encoded in [`app/preflight.py`](app/preflight.py): required tools include Python, `yt-dlp` for YouTube ingestion, `defuddle` for web ingestion, `notebooklm` for NotebookLM stages, and `claude` for Claude Code-driven stages. -Assets are organized by source type (`youtube/`, `web/`, `pdf/`) to avoid a flat graveyard in `research/assets/`. +## Privacy And Safety ---- +- Keep raw sources, generated workspace drafts, rebuilt projects, and vault outputs out of Git unless intentionally publishing examples. +- Treat NotebookLM as a cloud analysis surface and avoid sending private or sensitive source material unless that is intended. +- Preserve the distinction between German working drafts and English final vault notes when using the existing convention. +- Do not store OAuth or provider credentials in tracked files. -## Language Convention +## Roadmap -- **Workspace files** — German (working drafts) -- **Vault research notes** — English (final, analytical) -- **Config and docs** — English +- Harden preflight and setup guidance for repeatable local runs. +- Keep state validation strict so interrupted runs can resume safely. +- Improve vault export quality and source-bundle traceability. +- Add more fixture-driven tests for ingestion and package generation.