refactor (untested)

INDEX.md

@@ -0,0 +1,84 @@
+# meetus — repo index
+
+A standalone, local-first **command-line tool**: turn screen-share meeting/training
+recordings into a rich, AI-summarizable transcript. The extraction pipeline is
+deterministic and offline; the summarization step is the only LLM-facing part.
+
+meetus stands on its own. The separate **`cht`** project does the same thing in
+realtime; meetus may or may not feed it, so the two are kept formally apart (the
+cht-facing bits here live under `ctrl/cht/`).
+
+> This file maps the whole repo. [`README.md`](README.md) is the detailed manual for
+> the main `process_meeting.py` CLI.
+
+## Data flow
+
+```
+video / audio
+   │  process_meeting.py                       (deterministic, offline)
+   ▼
+output/<run>/                                  run folder: YYYYMMDD-NNN-<stem>/
+   ├── <stem>.json                             Whisper/WhisperX transcript (base)
+   ├── <stem>.srt / .vtt / ...                 extra transcript formats (optional)
+   ├── frames/                                 extracted scene/interval frames
+   ├── <stem>_enhanced.txt                     transcript + frame refs   ◀── the product
+   └── manifest.json
+   │  ctrl/summarize/*.py                       (local LLM — WIP, on hold)
+   ▼
+<stem>_summary_simple.md / _reference.md
+```
+
+`make batch` (→ `ctrl/batch.sh`) runs the pipeline over a whole directory tree,
+mirroring the input folder structure into the output.
+
+## Status legend
+
+✅ active · 🚧 WIP, on hold · 🗄️ deprecated (kept for reference) · 🧰 one-off / niche · 📄 docs
+
+## Layout
+
+```
+process_meeting.py        ✅ the CLI tool — entry point (stays at root)
+Makefile                  ✅ batch convenience wrapper
+meetus/                   ✅ core package
+  ├─ workflow.py             orchestrator (whisper → frames → merge)
+  ├─ frame_extractor.py      FFmpeg scene-detection / interval frames
+  ├─ transcript_merger.py    interleave transcript + frame refs → enhanced.txt
+  ├─ output_manager.py       run-folder naming + manifest.json
+  ├─ cache_manager.py        per-step caching (skip done work on rerun)
+  └─ deprecated/          🗄️ old screen-text idea (OCR/vision/hybrid) — unwired, reference only
+       ├─ ocr_processor.py       (was --ocr-engine)
+       ├─ vision_processor.py    (was --use-vision)
+       ├─ hybrid_processor.py    (was --use-hybrid)
+       └─ prompts/               vision context prompts
+ctrl/                     control plane / operational scripts
+  ├─ batch.sh             ✅ recursive batch runner (mirrors tree, continues past failures)
+  ├─ transcribe_oneoff.sh 🧰 high-quality re-transcription over an existing run
+  ├─ summarize/           🚧 last step — local-LLM summarization (WIP, on hold)
+  │    ├─ summarize_simple.py    minimal map-and-append; reads every referenced frame
+  │    ├─ compile_meeting.py     REFINE-pattern technical reference; on-demand frames
+  │    └─ summarize_meeting.py   map→extract(validated facts)→reduce
+  └─ cht/                 🧰 bridge to the separate realtime `cht` project
+       └─ interleave_cht_frames.py   whisperx JSON + cht frames/index.json → enhanced.txt
+def/                      📄 design/decision notes, in order (the feature history)
+README.md                 📄 manual for process_meeting.py
+INDEX.md                  📄 this file
+MARIAN.md                 📄 genesis brainstorm (explains why the deprecated OCR path exists)
+local-run.sh              📄 personal scratch invocations (gitignored)
+```
+
+## Notes
+
+- **Default flow** uses `--embed-images` (frames referenced for the LLM to read) +
+  `--scene-detection --scene-threshold 10 --diarize`. `make batch` adds
+  `--transcript-formats srt` and writes outputs next to the sources. See `README.md`.
+- **`meetus/deprecated/`** is no longer imported or reachable from the CLI (its flags
+  were removed and `workflow.py` no longer imports it). Kept for reference only; the
+  realtime continuation of the idea is the separate `cht` project.
+- **`ctrl/summarize/`** scripts are standalone; run them under an env with the `openai`
+  client (e.g. `~/wdir/llm/.venv`) against a local OpenAI-compatible server.
+
+## Loose ends
+
+- `README.md`'s "Output Files" example still shows the old run-folder format
+  `YYYYMMDD_HHMMSS-video` (actual: `YYYYMMDD-NNN-<stem>`). Minor; worth a tidy.