docs: refresh public README

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 <url>` | 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.