Track existing modulair-rag brainstorm capture

Pre-promotion commit so the next 'git mv' to .archive/ shows as a rename.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

.brainstorm/modulair-rag.md

@@ -0,0 +1,178 @@
+# ModulAIr RAG — brainstorm capture
+
+> Captured 2026-05-05 in single-agent session inside `.meeting-room/`.
+> Source scenario: `scenarios/modulair.md` (4-agent meeting frontmatter, не запускалось — пользователь предпочёл одного собеседника).
+> Prior multi-agent transcript: `source/2026-05-03-modulair.md` — там пользователь с другим ассистентом прошёл первый круг и накопил пул tooling-кандидатов (Marker, Repomix, ArchiveBox, Memos, Hermes-agent, и др.).
+> Mature design: `~/projects/.wiki/concepts/modulair-rag-design.md` — этот файл фиксирует процесс, не финальное решение.
+
+---
+
+## Контекст ModulAIr
+
+ModulAIr — AI-управляемый секвенсор/контроллер для еврорэка на Pico 2 W. Декомпозирован на 6 sub-projects:
+
+- `modulair-hw` — KiCad PCB (Pico 2 W + DAC + Gate-drivers + ADC + MIDI TRS + audio preamp + eurorack-питание)
+- `modulair-fw` — прошивка Pico 2 W
+- `modulair-script` — Teletype-style DSL + интерпретатор
+- `modulair-mcp` — MCP-мост между LLM и Pico
+- **`modulair-rag`** — база знаний ◄ предмет этого брейнсторма
+- `modulair-agent` — Hermes-агент как top-level orchestrator
+
+**Сквозная архитектурная развилка решена: Variant A — Pico-autonomous, LLM-conductor.** Pico исполняет скрипты sample-accurate, LLM через MCP мутирует паттерны/скрипты, но не сидит в горячем audio-пути. Wi-Fi latency перестаёт быть проблемой.
+
+## RAG-решения и почему
+
+### Стратегия — c-tiered (а не плоский vector RAG)
+
+Чисто вектор-RAG плох на factual-лукапах в синт-домене:
+- Эмбеддинги "0–8V" / "±5V" / "0V to 10V" близки в семантическом пространстве, но это разные факты
+- Отрицание ("у X нет Reset-входа") не работает — ретривер тащит чанки где есть "Reset" и "X" рядом
+- Сравнения требуют JOIN, а не top-k retrieval
+- Чанкинг ломает таблицы datasheet'ов
+
+→ **Tier 1** vector (manuals / theory / VCV source / forum threads) — recall-heavy, fuzzy.
+→ **Tier 2** structured Postgres (module specs из ModularGrid + vendor parsers) — precision-heavy, точные ответы.
+→ **Tier 3** ручные аннотации (~50 модулей личного рэка, calibration quirks, undocumented behavior).
+
+### Storage
+
+- **Postgres (cloud, существующий)** для Tier 2/3. **Не MariaDB:** JSONB для переменной формы jack-списков, pgvector как открытая дверь, recursive CTE + lateral joins зрелее, array-типы родные, MCP/ORM-экосистема Postgres-first.
+- **LightRAG #2 (новый instance с `working_dir=modulair-rag`)** для Tier 1. Текущий LightRAG-корпус не трогаем — он для других задач.
+- **Не pgvector unified** — это потребовало бы миграцию текущего LightRAG.
+- **Не Neo4j** — overkill для тысяч модулей; relations моделируются плоскими таблицами.
+
+### Scope первой итерации — (II) MVP на full-scrape ModularGrid
+
+~15k модулей, ~1 месяц. Альтернативы: (I) Top-50 за 2 недели — учиться на знакомом; (III) всё сразу за 1.5–2 мес. Выбрано (II) — компромисс между амбицией и сроками.
+
+Что меняется при этом скоупе:
+- **Per-field provenance обязательна** — без неё не отличить достоверный ±5V от LLM-угадки
+- **LLM-extraction как этап pipeline** — jacks/polarity/range живут в свободном тексте описаний и manual PDF, нужен LLM-проход по 15k
+- **Validation gates first-class** — voltage standards становятся правилами (audio типично ±5V, anomaly → флаг)
+
+### Pipeline — immutable layered (L1-L4)
+
+```
+L1  raw HTML        → MinIO bucket, content-addressed (sha256)
+L2  DOM extracts    → JSONL/run, структурные поля (HP, manufacturer, current_ma)
+L3  LLM extracts    → JSONL/run, jacks/polarity/range из свободного текста
+L4  Postgres        → "current state", собран из L2+L3+Tier-3
+```
+
+Зачем слоями: на MVP схема меняется ~5×, LLM-промпт ~10×. Без immutable слоёв каждое изменение = повторный scrape (медленно, rate-limit) + LLM-проход (дорого). С immutable — пере-extract из L2/L3 за минуты.
+
+### Source стратегия — multi-source
+
+```
+1. Vendor-side parsers (top-10):
+   pichenettes/eurorack (canonical Mutable), Make Noise, Intellijel,
+   Doepfer, ALM, Noise Engineering, Befaco, 4ms, Erica, Tiptop
+2. ModularGrid scrape (HTML, ≤1 RPS, weekly cron)
+   robots.txt allow модули и .json; их официальный API паузнут из-за EU copyright reform
+3. Tier 3 — ручные аннотации (~50 модулей личного рэка)
+```
+
+Не зависимы от ModularGrid одного — фрагильно (DOM может смениться, anti-scrape, юр. неопределённость).
+
+### Extractor LLM — Ollama Cloud sample first, не Haiku
+
+Решение: первый прогон через Ollama Cloud (GLM-5.1 / qwen) на golden set, валидация против Haiku 4.5 как benchmark. Если разница <5pp на ключевых метриках — Ollama, бесплатно. Если ≥10pp — Haiku-tiered с Sonnet 4.6 на flagged записях.
+
+**Golden set protocol** (1–2 дня ручной работы):
+- ~40 модулей: 20 Mutable (pichenettes/eurorack), 10 Doepfer, 5 Make Noise/Intellijel, 5 edge-case
+- JSON-эталон per модуль: `{name, direction, signal_type, polarity, range_v_min, range_v_max}`
+- Метрики/пороги: F1 signal_type ≥0.85, Acc polarity ≥0.85, MAE range ≤0.5V, hallucination ≤5%, miss ≤15%
+- Артефакты в git: `golden/`, `runs/<model>/`, `metrics/`
+
+### Provenance — module_facts + materialized consensus view
+
+```sql
+module_facts (
+  module_id, field, value JSONB, confidence REAL,
+  source_layer  -- 'L2-dom' | 'L3-llm-haiku' | 'L3-llm-sonnet' | 'tier3-manual'
+  source_ref,   -- 'scrape-2026-05-05/mutable-rings.json#desc-jacks'
+  scraped_at
+)
+```
+
+Плоские `modules` / `jacks` — materialized view "consensus" поверх highest-confidence values. MCP читает плоский view, валидатор/админка — `module_facts` напрямую. Альтернатива (`<col>_confidence`/`<col>_source` рядом) отвергнута — на 30+ полях шум.
+
+### Tier 1 corpus — phased
+
+**Phase 1 (MVP):** ModularGrid descriptions всех 15k (из L1) + top-100 vendor manuals + VCV Rack Fundamental/Library source + 30–50 hand-curated theory статей.
+**Phase 2 post-MVP:** vendor manuals top-500, YouTube whisper-транскрипты топ-creator'ов, selected forum threads.
+**Phase 3:** long-tail manuals, full forum scrape с quality filter.
+
+### Deploy shape — Docker compose, своё железо
+
+Existing: Postgres, Traefik, Portainer, kicad-mcp (для других sub-projects).
+
+5 новых контейнеров для modulair-rag:
+1. `lightrag-modulair` — Tier 1 vector, working_dir отдельный
+2. `minio` — L1 raw HTML cache, content-addressed
+3. `modulair-pipeline` — scraper + extractor + loader, cron внутри
+4. `tier1-converter` — Marker + Repomix + Firecrawl batch jobs
+5. `modulair-mcp` — MCP-сервер для Hermes (`module_spec`, `concept_search`, `module_compare`, `module_pairs`, `module_text`, `rack_modules`, `provenance`)
+
+### Orchestration — Hermes, не n8n
+
+Hermes-agent живёт в отдельном sub-project и через MCP зовёт наш `modulair-mcp` + (будущий) `firmware-mcp` + собственные Python-skills для batch (`run_repomix`, `run_marker`). n8n из плана убран — дублирует Hermes.
+
+Phases:
+- Phase 1 — cron внутри контейнеров
+- Phase 2 — Changedetection.io webhooks → Hermes scheduled-automations
+- Phase 3 — расширение Hermes skills (multi-source priorisation, feedback-loop из Memos/Obsidian, vendor-парсеры как skills)
+
+## Что отвергнуто и почему
+
+| Отвергнуто | Причина |
+|---|---|
+| Pure vector RAG (c-flat) | Factual-лукапы галлюцинируют; embeddings не различают voltage ranges |
+| Postgres + pgvector unified (α) | Заставит мигрировать существующий LightRAG-корпус |
+| MariaDB | JSONB и pgvector будущего — типпинг-пойнт за Postgres |
+| Neo4j | Overkill для тысяч модулей; relations плоско моделируются |
+| n8n | Дублирует Hermes-agent |
+| markitdown как primary | Marker лучше PDF, Repomix лучше код, Firecrawl лучше JS-сайты |
+| tree-sitter primary chunking | Repomix даёт structure-aware MD из коробки |
+| DVC | pg_dump + content-addressed MinIO покрывают provenance |
+| kicad-mcp в modulair-rag | Out of scope; живёт в modulair-agent / modulair-hw |
+| ArchiveBox в MVP | Heavy (Docker+Chrome+Node), своя scraper-реализация дешевле для targeted-scrape |
+
+## Открытые вопросы (не блокируют MVP)
+
+- Финальный размер golden-set (40 принято; ужесточение MAE до 0.2V для CV-модулей — после первого прогона)
+- Music theory sources — конкретный список 30–50 статей не зафиксирован (упомянуты Allen Strange, Whitwell, SoS Synth Secrets, Eno strategies)
+- Phasing для feedback-loop (Memos / Obsidian #feedback) — Phase 2, конкретная реализация позже
+- Где физически живёт kicad-mcp (host stdio vs Docker) — релевантно для modulair-agent / modulair-hw, не для modulair-rag
+
+## Tooling из исходного транскрипта 2026-05-03
+
+Я провалил первый проход — не прочитал транскрипт перед тем как предлагать стэк. Память записана: `feedback_read_source_transcripts.md`. Финальный мерж stack'ов:
+
+| Категория | Что взято | Что отвергнуто |
+|---|---|---|
+| PDF→MD | **Marker** (primary), **LlamaParse** (fallback) | markitdown как primary, Docling (только если Marker не установится) |
+| Web→MD | **Firecrawl** (batch), **Jina Reader** (одноразовый) | Trafilatura |
+| Code→MD | **Repomix** | tree-sitter с нуля |
+| Web archive | **Wallabag** в Phase 2 | ArchiveBox в MVP, Linkwarden, Shiori |
+| Change detection | **Changedetection.io** в Phase 2 | (alone, без n8n) |
+| Orchestration | **Hermes-agent** | n8n, Huginn |
+| Data versioning | `pg_dump` + content-addressed MinIO | DVC |
+| Feedback loop | **Memos** или **Obsidian** в Phase 2 | (одно из двух) |
+| Container UI | **Portainer** (existing) | Dockge |
+| Vector store | **LightRAG** (existing для других, новый instance для modulair) | ChromaDB, Pinecone, GraphRAG |
+| Algo composition | **music21** — для modulair-agent, не RAG | — |
+| Embedded DSP | Pure Data + hvcc / Faust — для modulair-fw audio sub-project, не RAG | — |
+| EDA → MD | **kicad-mcp** существующий, для modulair-hw / modulair-agent | KiCad-CLI / KiBot — out of scope для modulair-rag |
+
+## Меморики, появившиеся за сессию
+
+- `feedback_meeting_room_workspace.md` — `.meeting-room` это brainstorm-зона, артефакты идут в `.brainstorm/` или global wiki, не через "transit-zone autopilot"
+- `project_extend_discipline_for_meeting_room.md` — открытый todo расширить project-discipline под brainstorm-workspaces
+- `feedback_read_source_transcripts.md` — `.meeting-room/source/<date>-<topic>.md` это pre-loaded user research, читать до предложения стэка
+
+## Следующие шаги
+
+1. Брейнсторм per остальным 5 sub-projects (`modulair-hw`, `modulair-fw`, `modulair-script`, `modulair-mcp`, `modulair-agent`)
+2. Когда RAG-implementation начнётся — поднять структуру репозитория `modulair-rag` где-то в `~/projects/`, скелет compose.yml, `.tasks/STATUS.md` под фактический проект
+3. Заведение golden-set (1–2 дня ручной работы — это первое что нужно сделать; в MVP это блокирующая зависимость для extractor-валидации)