bug2context 0.1.0__tar.gz

bug2context-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,50 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        # ubuntu proves the tesseract/no-Vision path; macos is the dev platform.
+        os: [ubuntu-latest, macos-latest]
+        python: ["3.12", "3.13"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install ffmpeg (Linux)
+        if: runner.os == 'Linux'
+        run: sudo apt-get update && sudo apt-get install -y ffmpeg
+
+      - name: Install ffmpeg (macOS)
+        if: runner.os == 'macOS'
+        run: brew install ffmpeg
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - run: uv sync --python ${{ matrix.python }} --extra ocr
+
+      - run: uv run pytest -q
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv build
+      - name: Install the wheel on its own and run it
+        run: |
+          uv venv /tmp/clean
+          uv pip install --python /tmp/clean/bin/python dist/*.whl
+          /tmp/clean/bin/bug2context --help
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/

bug2context-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,27 @@
+name: Release
+
+# Publishing is deliberately manual: push a tag when you actually mean to ship.
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write # PyPI trusted publishing — no API token to leak
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+
+      - name: Fail if the tag and pyproject version disagree
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          version=$(grep -m1 '^version' pyproject.toml | cut -d'"' -f2)
+          test "$tag" = "$version" || {
+            echo "tag $tag != pyproject $version"; exit 1;
+          }
+
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1

bug2context-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+bundle/

bug2context-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Emanuel Duran
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

bug2context-0.1.0/PKG-INFO

@@ -0,0 +1,232 @@
+Metadata-Version: 2.5
+Name: bug2context
+Version: 0.1.0
+Summary: Turns bug screen recordings into structured, chronological context for AI agents.
+Project-URL: Homepage, https://github.com/emanueld92/bug2context
+Project-URL: Issues, https://github.com/emanueld92/bug2context/issues
+Author: Emanuel Duran
+License-Expression: MIT
+License-File: LICENSE
+Keywords: bug-report,claude,debugging,llm,mcp,ocr,screen-recording
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Video
+Classifier: Topic :: Software Development :: Bug Tracking
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: imagehash>=4.3
+Requires-Dist: mcp>=1.2
+Requires-Dist: pillow>=11.0
+Requires-Dist: typer>=0.15
+Provides-Extra: audio
+Requires-Dist: faster-whisper>=1.1; extra == 'audio'
+Provides-Extra: ocr
+Requires-Dist: pyobjc-framework-vision>=10.3; (sys_platform == 'darwin') and extra == 'ocr'
+Requires-Dist: pytesseract>=0.3.13; extra == 'ocr'
+Description-Content-Type: text/markdown
+
+# bug2context
+
+Turns a screen recording of a bug into structured, chronological context an AI
+agent can actually read.
+
+Screenshots lose the story: bugs happen fast, a still frame has no timeline, and
+the logs and the narration live somewhere else entirely. LLMs don't take video.
+This distills a recording into one markdown chronology — key frames, the text on
+screen, device logs and spoken narration, all on the same clock.
+
+- **No SDK.** Works on any video, including one someone sent you over WhatsApp.
+- **Local-first.** Nothing leaves your machine. No account, no API key, no cloud.
+- **MCP-native.** Claude Code calls it as a tool; you just point at the file.
+
+```bash
+uv run bug2context            # guided menu
+uv run bug2context process bug.mp4 --out bundle/
+```
+
+Running it with no arguments opens a menu — record an Android device, process a
+video you already have, or list previous bundles — and writes to
+`~/.bug2context/`, which is where the MCP server looks. Everything it does is
+reachable through the flags below; it just stops you having to remember them.
+
+## What comes out
+
+```
+- `[00:00]` 🖼 `frames/frame_001_00-00.png` — start of recording
+      OCR: Cart 2 items
+- `[00:04]` 🖼 `frames/frame_002_00-04.png` — screen changed
+      OCR: Applying discount..
+- `[00:04]` 📋 W/DiscountEngine: rate field missing
+- `[00:06]` 🖼 `frames/frame_003_00-06.png` — screen changed
+      OCR: TypeError: cannot read 'rate'
+- `[00:06]` 📋 E/RideService: NullPointerException at RideRequest.kt:142
+- `[00:06]` 📋 F/AndroidRuntime: FATAL EXCEPTION: main
+- `[00:06]` 🎙 "ahí está, explota al aplicar el descuento"
+```
+
+A full run is in [examples/report.md](examples/report.md).
+
+```
+bundle/
+├── report.md    the chronology above
+├── frames/      the key frames, named by timestamp
+└── meta.json    the same data, structured, for programmatic use
+```
+
+## Install
+
+Requires [`ffmpeg`](https://ffmpeg.org) on PATH (`brew install ffmpeg`).
+
+```bash
+git clone https://github.com/emanueld92/bug2context
+cd bug2context
+uv sync --extra ocr        # OCR: Apple Vision on macOS, tesseract elsewhere
+uv sync --extra audio      # optional: spoken narration
+```
+
+Every stage is optional and degrades quietly: no OCR backend still gives you
+frames, no audio track still gives you the visual timeline.
+
+## Use it from Claude Code
+
+```bash
+claude mcp add bug2context -- uvx --from /path/to/bug2context bug2context-mcp
+```
+
+Then just ask: *"analiza este video del bug: ~/Desktop/crash.mp4"*.
+
+| Tool | Purpose |
+|---|---|
+| `analyze_bug_video` | Video → chronological report (returns the text itself) |
+| `get_frame` | Fetch one frame as an image so the agent can look at it |
+| `list_bundles` | Previously processed bundles, newest first |
+
+Bundles default to `~/.bug2context/<video>-<timestamp>/`.
+
+## Android: screen + logcat in one command
+
+```bash
+uv run bug2context record --seconds 60 --package com.example.app --out bundle/
+```
+
+Reproduce the bug while it records. Both streams start from a single host
+timestamp — that anchor is what makes a stack trace land next to the frame
+showing the crash.
+
+**Pass `--package`.** Level filtering alone is not enough on a real phone: a
+2 min capture held 7,634 W/E/F lines and *none* came from the app under test —
+they were all `AppOpsControllerImpl`, `GNSSMGT` and friends. Scoping to the
+app's process left 35. Crash tags (`AndroidRuntime`, `DEBUG`) are kept
+regardless of process, since a crash report is the whole point.
+
+Logs are captured unfiltered and scoped afterwards, so an app that crashes and
+restarts still has its death recorded. Consecutive identical entries fold into
+one with a `(×N)` count — framework chatter arrives in bursts of fifteen.
+
+Already have a log file? Merge it into any video:
+
+```bash
+uv run bug2context process bug.mp4 --logcat logcat.txt --log-tag RideService
+```
+
+Reads both `-v time` and `-v threadtime`. `--log-levels` defaults to `WEF` and
+`--log-max-lines` to 80, ranked by severity so a cap never trades the crash for
+boot chatter. `--log-pid` scopes to a process when you already know it. If the device clock and the
+recorder disagree, `--log-offset` shifts everything by N seconds; with no
+`--video-started-at`, the first log entry becomes the anchor.
+
+`screenrecord` caps at 3 minutes, so `record` refuses longer rather than handing
+back a silently truncated video. Ctrl-C cuts a recording short safely — the file
+is finalised on the device first, because killing the local adb leaves one
+`ffprobe` cannot open.
+
+Videos over 10 minutes are refused with the `ffmpeg` command to trim them
+(`--max-duration 0` overrides). Nothing scales badly with length except time,
+but it scales linearly: decoding alone runs at about a third of real time.
+
+## Narration
+
+```bash
+uv run bug2context process bug.mp4 --transcribe --language es
+```
+
+Off by default: it downloads a model on first use and is the slowest stage,
+while most recordings have no voice-over. Skipped automatically when there is no
+audio track, or the track is quieter than −50 dB — whisper invents confident
+sentences out of silence, so that guard is about output quality, not just speed.
+
+## How frames get picked
+
+ffmpeg over-produces candidates (scene cuts **and** a fixed interval, so slowly
+changing screens are not skipped), then perceptual hashing collapses the
+near-duplicates. `--max-frames` caps the result, always keeping the opening frame
+and then whichever changed most.
+
+| Flag | Default | Notes |
+|---|---|---|
+| `--scene-threshold` | `0.08` | ffmpeg scene score for a cut |
+| `--interval-seconds` | `1.0` | forced sample when no cut fires |
+| `--max-frames` | auto | one frame per 2 s, between 20 and 40 |
+| `--phash-distance` | `4` | below this, frames count as duplicates |
+| `--ocr-upscale` | `2` | enlarge before OCR; skipped above 1600 px wide |
+
+Measured end to end, OCR on:
+
+| Source | Result | Time |
+|---|---|---|
+| synthetic 3 min, 1080×1920 | 19 frames | 8.5 s |
+| Android capture, 2 min, 720×1612 @ ~12 fps | 118 candidates → 20 frames | 16 s |
+| macOS capture, 90 s, 2880×1864 @ 60 fps | 97 candidates → 18 frames | 86 s |
+
+Recognised text is cached by frame content in `~/.cache/bug2context/`, so
+re-running a video with different settings only pays for what actually changed —
+measured 9.0 s cold against 3.3 s warm on a 44 s clip, identical output.
+Extracting the same video twice yields byte-identical frames, which is what
+makes the cache safe. Delete the directory to reset it.
+
+Retina desktop recordings are the slow case and there is no trick to remove:
+the cost is decoding 60 fps at 5.4 megapixels (26 s) plus OCR, which Vision
+charges at ~1.6 s per frame regardless of size. Budget roughly real time for
+those; phone captures stay far under it.
+
+On `--ocr-upscale`: a stack trace on a recompressed 1080×1920 frame read as
+`Null PointerSxception Ride Requestkt14` at 1× and correctly as
+`NullPointerException Ride Request kt 142` at 3×. Raise it for badly
+recompressed sources — ask for the video as a file, not as a WhatsApp video.
+It is skipped on frames already 1600 px or wider, where it changed nothing
+measurable while building a 5760×3728 image per frame.
+
+OCR also drops lines that are debris rather than text — `»`, `.lll (100 4`,
+a misread status-bar clock. On a real capture that removed 41 of 210 report
+lines and no real text. A line that looks like a failure is never dropped.
+
+## Known limitation
+
+Perceptual hashing compares visual *structure*. It sees navigation, dialogs and
+error banners, but it cannot detect a small **text-only** change on an otherwise
+identical layout — measured on 1080×1920 those differences fall inside the noise
+floor at every hash size, so no `--phash-distance` value separates them.
+
+OCR does not rescue this: it runs on frames that survive deduplication, so a
+screen already collapsed is never read. Reading every candidate instead measured
+48–59 s for a 3 min video, over the entire time budget. If your bug *is* a small
+text change on an identical screen, record cropped or at lower resolution so the
+text occupies more of the frame.
+
+## Development
+
+```bash
+uv sync --extra ocr
+uv run pytest -q
+```
+
+183 tests. Device recording is mocked on purpose — a test suite should not record
+anyone's phone. Whisper is opt-in via `BUG2CONTEXT_TEST_WHISPER=1` so the suite
+stays offline.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

bug2context-0.1.0/PLAN-bug2context.md

@@ -0,0 +1,200 @@
+# PLAN — bug2context
+
+> Herramienta local-first que transforma grabaciones de video de bugs (especialmente de apps móviles) en contexto estructurado y cronológico listo para consumir por motores de IA, entregada como CLI + servidor MCP.
+
+---
+
+## 1. Visión y problema
+
+**Problema:** al reportar o depurar bugs, las capturas de pantalla son ineficientes — los errores suceden muy rápido, no reflejan cronología, y el contexto (logs, narración, causa→efecto) se pierde. Los LLMs (Claude incluido) no aceptan video directamente.
+
+**Solución:** un pipeline que destila un video en un "paquete de contexto": frames clave con timestamps + texto extraído por OCR + logs del dispositivo sincronizados + transcripción de narración, ensamblados en un reporte markdown cronológico que un agente de IA puede leer directamente.
+
+**Diferenciadores vs. mercado existente (Bugsee, Shake, Instabug):**
+- Sin SDK: funciona con cualquier video, incluso uno recibido por WhatsApp.
+- Local-first: sin cloud, sin suscripción, privacidad total.
+- MCP-first: Claude Code lo consume como una tool nativa.
+- Open source (licencia MIT o Apache 2.0).
+
+## 2. Principios de diseño
+
+1. **Local-first:** todo el procesamiento corre en la máquina del usuario. Ningún dato sale sin acción explícita.
+2. **MCP como interfaz principal:** el CLI existe, pero el caso de uso estrella es `Claude Code → tool MCP → contexto`.
+3. **Degradación elegante:** cada etapa del pipeline es opcional. Sin audio → sin transcripción. Sin logcat → solo video. Sin OCR disponible → solo frames.
+4. **Salida en texto plano primero:** el reporte es markdown legible por humanos y por IA; los frames son adjuntos referenciados.
+5. **Costo cero por defecto:** ninguna etapa del núcleo requiere API keys. El análisis con vision-LLM es una capa opcional posterior.
+
+## 3. Arquitectura del pipeline
+
+```
+video.mp4 ──► [1] Extracción de frames (ffmpeg, detección de escena + intervalo fijo)
+             ──► [2] Deduplicación (hash perceptual)
+             ──► [3] OCR por frame (macOS Vision / tesseract fallback)
+audio      ──► [4] Transcripción (faster-whisper, opcional)
+logcat.txt ──► [5] Parser de logs con timestamps (opcional)
+             ──► [6] Ensamblador: fusiona las 3 líneas de tiempo (frames, narración, logs)
+             ──► [7] Salida: bundle/
+                        ├── report.md        (cronología unificada)
+                        ├── frames/          (PNGs clave, numerados con timestamp)
+                        └── meta.json        (datos estructurados para consumo programático)
+```
+
+### Detalles por etapa
+
+**[1] Extracción de frames**
+- `ffmpeg -i video.mp4 -vf "select='gt(scene,0.08)',showinfo" -vsync vfr` para cambios de escena.
+- Parsear stderr de `showinfo` para obtener `pts_time` (timestamp exacto) de cada frame.
+- Muestreo de respaldo: 1 frame cada N segundos (configurable, default 3 s) para transiciones lentas.
+- Umbral de escena configurable (`--scene-threshold`).
+
+**[2] Deduplicación**
+- `imagehash.phash` con distancia Hamming configurable (default ≤ 6 = duplicado).
+- Meta: de un video de 2 min quedar con 8–25 frames.
+- Límite duro configurable (`--max-frames`, default 20) priorizando frames con mayor cambio de escena.
+
+**[3] OCR**
+- macOS: framework Vision vía `pyobjc` (calidad superior para texto de pantalla, gratis, offline).
+- Fallback multiplataforma: `pytesseract`.
+- Guardar texto por frame en `meta.json`; incluir en el reporte solo líneas relevantes (heurística: contiene "error", "exception", "fatal", "warning", stack traces, o difiere del frame anterior).
+
+**[4] Transcripción (opcional)**
+- `faster-whisper` modelo `small` por defecto (balance velocidad/calidad), con timestamps por segmento.
+- Detectar si el video tiene pista de audio con contenido antes de transcribir (skip si es silencio).
+
+**[5] Parser de logs (opcional)**
+- Entrada: archivo logcat (`adb logcat -v time`) o log genérico con timestamps.
+- Normalizar timestamps al reloj del video (offset configurable o auto-alineado por hora de inicio de grabación).
+- Filtro por nivel (default: W/E/F) y por tag/paquete de la app.
+
+**[6] Ensamblador**
+- Fusiona los tres streams en una sola cronología ordenada por timestamp.
+- Formato de entrada del reporte:
+  ```
+  [00:06] 🖼 frame_003.png — cambio de escena
+          OCR: "TypeError: cannot read property 'rate'"
+  [00:06] 📋 LOG E/RideService: NullPointerException at RideRequest.kt:142
+  [00:08] 🎙 "ahí está, explota al aplicar el descuento"
+  ```
+
+## 4. Stack técnico
+
+| Componente | Elección | Notas |
+|---|---|---|
+| Lenguaje | Python 3.12+ | ecosistema ffmpeg/whisper/MCP maduro |
+| CLI | `typer` | subcomandos, help autogenerado |
+| Video | `ffmpeg` (subprocess) | dependencia de sistema, verificar en arranque |
+| Dedup | `Pillow` + `imagehash` | |
+| OCR | `pyobjc` (Vision) / `pytesseract` | detección de plataforma en runtime |
+| Audio | `faster-whisper` | extra opcional: `pip install bug2context[audio]` |
+| MCP | SDK oficial de Python MCP (`fastmcp`) | servidor stdio |
+| Empaquetado | `uv` + `pyproject.toml` | instalable vía `uvx bug2context` |
+| Tests | `pytest` | fixtures con videos cortos sintéticos generados con ffmpeg |
+
+## 5. Estructura del repo
+
+```
+bug2context/
+├── pyproject.toml
+├── README.md
+├── LICENSE
+├── src/bug2context/
+│   ├── __init__.py
+│   ├── cli.py              # typer app
+│   ├── pipeline/
+│   │   ├── frames.py       # etapas 1-2
+│   │   ├── ocr.py          # etapa 3
+│   │   ├── audio.py        # etapa 4
+│   │   ├── logs.py         # etapa 5
+│   │   └── assemble.py     # etapas 6-7
+│   ├── mcp_server.py       # servidor MCP
+│   └── config.py           # dataclass de opciones + defaults
+└── tests/
+```
+
+## 6. Fases (metodología GSD)
+
+### Fase 1 — Núcleo de video (MVP)
+**Objetivo:** `bug2context process video.mp4` produce `bundle/` con `report.md` + frames.
+- [ ] 1.1 Scaffold del repo (`pyproject.toml`, typer, estructura src/)
+- [ ] 1.2 `frames.py`: extracción por escena + intervalo, parseo de timestamps de showinfo
+- [ ] 1.3 Deduplicación por phash con límite de frames
+- [ ] 1.4 `assemble.py`: report.md cronológico solo con frames + meta.json
+- [ ] 1.5 Tests con video sintético (ffmpeg genera pantallas de color con texto que cambian)
+
+**Criterio de aceptación:** un screen recording real de 1–3 min produce ≤ 20 frames relevantes con timestamps correctos, en < 30 s de procesamiento.
+
+### Fase 2 — OCR
+- [ ] 2.1 Backend Vision (macOS) vía pyobjc
+- [ ] 2.2 Backend tesseract como fallback
+- [ ] 2.3 Heurística de relevancia (errores, diffs entre frames)
+- [ ] 2.4 Integración al reporte
+
+**Criterio de aceptación:** un video con un stack trace visible en pantalla produce ese texto legible en report.md.
+
+### Fase 3 — Servidor MCP
+- [ ] 3.1 `mcp_server.py` con fastmcp, transporte stdio
+- [ ] 3.2 Tool `analyze_bug_video(path, options)` → devuelve report.md + rutas de frames
+- [ ] 3.3 Tool `get_frame(bundle, index)` → devuelve imagen para que el agente la vea
+- [ ] 3.4 Documentar instalación en Claude Code (`claude mcp add`)
+
+**Criterio de aceptación:** desde Claude Code, pedir "analiza este video del bug" ejecuta la tool y el agente razona sobre la cronología sin pasos manuales.
+
+### Fase 4 — Audio (narración)
+- [ ] 4.1 Extracción de pista de audio + detección de silencio
+- [ ] 4.2 faster-whisper con timestamps por segmento
+- [ ] 4.3 Fusión en la cronología
+
+### Fase 5 — Orquestador móvil (Android primero)
+- [ ] 5.1 `bug2context record --android`: lanza `adb shell screenrecord` + `adb logcat -v time` en paralelo
+- [ ] 5.2 Alineación de relojes video↔logcat
+- [ ] 5.3 Parser de logcat con filtros por nivel y paquete
+- [ ] 5.4 Fusión de logs en la cronología
+- [ ] 5.5 (Posterior) iOS: simctl + log stream
+
+**Criterio de aceptación:** reproducir un crash en un dispositivo Android conectado produce un reporte donde el stack trace del logcat aparece en el instante del frame del crash.
+
+### Fase 6 — Publicación
+- [ ] 6.1 README con demo GIF, ejemplos de uso con Claude Code
+- [ ] 6.2 Publicar en PyPI + anuncio (X, Reddit r/ClaudeAI, HN)
+- [ ] 6.3 Recoger feedback y definir capa de monetización (cloud, GitHub Issues, equipo)
+
+## 7. Diseño del servidor MCP (contrato)
+
+```python
+@mcp.tool()
+def analyze_bug_video(
+    video_path: str,
+    logcat_path: str | None = None,
+    transcribe_audio: bool = False,
+    max_frames: int = 20,
+) -> str:
+    """Procesa un video de un bug y devuelve un reporte cronológico
+    en markdown con referencias a frames clave."""
+
+@mcp.tool()
+def get_frame(bundle_path: str, frame_index: int) -> Image:
+    """Devuelve un frame específico del bundle para inspección visual."""
+
+@mcp.tool()
+def list_bundles(workdir: str = "~/.bug2context") -> list[dict]:
+    """Lista los bundles procesados con fecha y video de origen."""
+```
+
+## 8. Riesgos y mitigaciones
+
+| Riesgo | Mitigación |
+|---|---|
+| OCR pobre en videos comprimidos (WhatsApp recomprime mucho) | upscaling 2x con ffmpeg antes de OCR; documentar "pide el video como archivo, no como video de WhatsApp" |
+| Detección de escena falla en apps con animaciones constantes | combinar escena + intervalo fijo; umbral configurable |
+| Ventana competitiva (otros ya construyen en el nicho) | priorizar Fases 1–3 para tener el MVP con MCP publicado rápido; el orquestador adb (Fase 5) es el foso |
+| Desalineación de relojes video↔logcat | registrar timestamp de inicio de screenrecord; offset manual como escape |
+| pyobjc/Vision frágil entre versiones de macOS | tesseract siempre disponible como fallback |
+
+## 9. Instrucciones de trabajo para Claude Code
+
+- Ejecutar comando por comando, confirmando entre pasos.
+- Trabajar en un worktree de git dedicado.
+- Cada fase = una rama; merge al completar criterio de aceptación.
+- Escribir tests antes de cerrar cada tarea numerada.
+- No agregar dependencias fuera de las listadas sin consultar.
+- Máquina de desarrollo: macOS (Homebrew disponible para ffmpeg/tesseract).