dreamcontext 0.6.0 → 0.7.1

package/dist/templates/init/data-structures/default.md

@@ -3,33 +3,35 @@ name: {{PRODUCT_NAME}}
 description: Data structures for {{PRODUCT_NAME}}
 type: data-structures
 product: {{PRODUCT_NAME}}
+tags:
+  - data-structures
+  - database
+  - schema
 updated: {{DATE}}
 ---
-
-# Data Structures — {{PRODUCT_NAME}}
-
-Document this product's database schema, key models, and API contracts here. This file is the source of truth for data shapes.
-
-## Conventions
-
-- One `data-structures/<product>.md` file per product in a monorepo. `default.md` is the single-product fallback.
-- Sleep-state applies the **single-observation gate** to this file: a single session that adds, removes, or changes a schema MUST be reflected here in the same sleep cycle. No pattern repetition required.
-- Tasks MAY include `product: <name>` in frontmatter to route data-structure observations to the matching product file.
-
-## Schema
-
-<!-- Example:
-
 ```sql
+-- Data Structures — {{PRODUCT_NAME}}
+-- Updated: {{DATE}}
+--
+-- Document all tables, models, and key JSON shapes here.
+-- One observation gate: a schema change in a session MUST be reflected here
+-- in the same sleep cycle. No pattern repetition required.
+--
+-- Convention:
+--   - Single-product projects use default.md.
+--   - Multi-product monorepos use <product>.md per product.
+--   - The body should always be a ```sql fenced block for dashboard highlighting.
+--   - Use SQL comments (-- ...) for documentation and guidance.
+
+-- ============================================================
+-- EXAMPLE — replace or extend with your actual schema
+-- ============================================================
+
 CREATE TABLE users (
-  id UUID PRIMARY KEY,
-  email VARCHAR(255) NOT NULL UNIQUE,
-  created_at TIMESTAMP DEFAULT NOW()
+  id          UUID         PRIMARY KEY,
+  email       VARCHAR(255) NOT NULL UNIQUE,
+  created_at  TIMESTAMP    NOT NULL DEFAULT NOW()
 );
-```
 
-Or document models in any format that matches the stack — TypeScript interfaces, Prisma schema, Pydantic models, GraphQL SDL. -->
-
-## API Contracts
-
-<!-- Document request/response shapes, route handlers, and external API integrations relevant to this product. -->
+-- Add additional tables, indexes, and JSON model shapes below.
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dreamcontext",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "description": "dreamcontext — the persistent brain for your AI agents. Remembers what you built, knows how your project works.",
   "type": "module",
   "bin": {

package/skill/SKILL.md

@@ -87,7 +87,7 @@ All three are auto-loaded every session via the SessionStart hook.
 Every session start injects these automatically (zero tool calls needed):
 
 - **Soul, User, Memory** -- full content
-- **Extended core files index** -- names/types of style guide, tech stack, data structures
+- **Extended core files index** -- names/types of style guide, tech stack, system flow
 - **Active tasks** -- status, priority, last updated (answer "which tasks are active?" directly from this, zero tool calls needed)
 - **Bookmarks** -- tagged important moments from previous sessions, ordered by salience
 - **Contextual reminders** -- matching triggers for active tasks (prospective memory)
@@ -115,7 +115,7 @@ Decide dynamically. Match the task to what you need. Choose the right operation
 | `core/features/<name>.md` | READ | Feature scoping, sprint work, planning, "what's next" questions |
 | `core/3.style_guide_and_branding.md` | READ | UI/UX work, frontend, branding, copy, design tasks |
 | `core/4.tech_stack.md` | READ | Architecture decisions, integrations, dependency questions, infra |
-| `core/data-structures/<product>.md` (or `default.md`) | READ or SEARCH | Database work, API design, schema changes, data modeling |
+| `knowledge/data-structures/<product>.md` (or `default.md`) | READ or SEARCH | Database work, API design, schema changes, data modeling (recall-indexed like all knowledge) |
 | `core/CHANGELOG.json` | SEARCH | Bug investigations, "what changed recently?" |
 | `core/RELEASES.json` | SEARCH | "Which release shipped this?", rollback decisions |
 | `state/<task>.md` | READ | Continuing previous work. Changelog section = where you left off |
@@ -134,17 +134,17 @@ When debugging (e.g., "notifications are broken"):
 
 Some projects are monorepos with multiple products. Init asks "Is this a monorepo with multiple products?" and records the product list in `_dream_context/state/.config.json` under `multiProduct: string[] | false`. When products are configured:
 
-- **Per-product data structures** live at `_dream_context/core/data-structures/<product>.md` (single-product projects use `default.md`).
+- **Per-product data structures** live at `_dream_context/knowledge/data-structures/<product>.md` (single-product projects use `default.md`). They're knowledge files — recall-indexed, staleness-tracked, owned by `sleep-product`. **Body format: a single \`\`\`sql fenced block** with SQL comments (`-- ...`) for documentation — this is what the dashboard highlights. `migrateDataStructures` auto-wraps unfenced bodies; `dreamcontext init` scaffolds the fenced template.
 - **Per-product knowledge** lives at `_dream_context/knowledge/products/<product>.md`. Cross-cutting knowledge still lives at the top-level `knowledge/`.
 - **Tasks** MAY include `product: <name>` in frontmatter. The dashboard / CLI surfaces a product filter when `.config.json` lists products.
 - **Auto-injection — handled by the SessionStart hook.** The hook (`npx dreamcontext hook session-start` → `generateSnapshot()`) resolves the active task (override file `_dream_context/state/.active-task`, or fallback: most recently modified task with status `in_progress`). If that task's frontmatter has `product: <name>` and `<name>` is listed under `multiProduct`, the hook injects the body of `_dream_context/knowledge/products/<name>.md` into the snapshot under an `## Active Product Knowledge: <name>` section (capped at 200 lines, with a "read full" pointer if truncated). You don't need to remember to load it — it's already in your context. Cross-cutting knowledge still lives at the top-level `knowledge/`.
 - **Feature PRDs** MAY include `product: <name>` in frontmatter for product scoping; they still live in the flat `core/features/` directory.
 
-If `multiProduct` is `false` or missing, treat the project as single-product and use `data-structures/default.md` exclusively. The SessionStart hook no-ops the product-knowledge injection in that case.
+If `multiProduct` is `false` or missing, treat the project as single-product and use `knowledge/data-structures/default.md` exclusively. The SessionStart hook no-ops the product-knowledge injection in that case.
 
 ### Extended Core Files (3+)
 
-Beyond the auto-loaded soul/user/memory, projects define additional core files (style guide, tech stack, data structures, and potentially more).
+Beyond the auto-loaded soul/user/memory, projects define additional core files (style guide, tech stack, and potentially more). (Data structures are no longer a core file — they live under `knowledge/data-structures/` as recall-indexed knowledge.)
 
 **Discovery protocol**:
 1. The extended core files index is auto-loaded each session (names and types visible).
@@ -366,6 +366,18 @@ Tasks are your **working documents**. All context, decisions, user stories, acce
 dreamcontext tasks list                                                 # List non-completed tasks (or --all for everything)
 Read _dream_context/state/<task>.md                                     # Load full context (Why + Changelog = where you left off)
 
+# Slice the list — filters compose (AND), and stack with --status / --all
+dreamcontext tasks list --version S5                                    # All tasks in version/milestone S5 (no more frontmatter scraping)
+dreamcontext tasks list --tag memoryos --tag backend --status todo      # --tag is repeatable, AND semantics (must have ALL)
+dreamcontext tasks list --any-tag lina --any-tag studio                 # --any-tag is repeatable, OR semantics (at least one)
+dreamcontext tasks list --priority critical                             # critical | high | medium | low
+dreamcontext tasks list --feature recall-engine                         # match related_feature
+dreamcontext tasks list --long                                          # also show version + tags inline
+dreamcontext tasks list --group-by version --all                        # sectioned output with per-group counts (tag|version|priority|status)
+dreamcontext tasks list --tag lina --json                              # scriptable: emit the filtered set as JSON (use this, not awk/grep)
+dreamcontext tasks tags                                                  # distinct tags with counts (--all to include completed)
+#   Filters are case-insensitive; version/priority/feature match exactly; multiple --tag = AND, --any-tag = OR.
+
 # Create (rich task with Why, User Stories, Acceptance Criteria, Constraints, Technical Details, Notes, Changelog)
 dreamcontext tasks create <name> --description "..." --priority medium --why "What this task accomplishes"
 
@@ -451,9 +463,6 @@ dreamcontext memory status
 _dream_context/
 +-- core/
 |   +-- features/<feature>.md         <- Feature PRDs (may include product: <name>)
-|   +-- data-structures/              <- Per-product schemas
-|   |   +-- default.md                <-   single-product fallback
-|   |   +-- <product>.md              <-   one per product if monorepo
 |   +-- 0.soul.md                     <- Identity, principles, rules
 |   +-- 1.user.md                     <- Preferences, project details
 |   +-- 2.memory.md                   <- Decisions + Known Issues (ship narrative moved to CHANGELOG 2026-05-23)
@@ -462,6 +471,9 @@ _dream_context/
 |   +-- 6.system_flow.md
 |   +-- CHANGELOG.json, RELEASES.json
 +-- knowledge/<topic>.md              <- Deep research, resources (global)
+|   +-- data-structures/              <- Per-product schemas (recall-indexed knowledge)
+|   |   +-- default.md                <-   single-product fallback
+|   |   +-- <product>.md              <-   one per product if monorepo
 |   +-- products/<product>.md         <- Per-product knowledge (multi-product)
 +-- state/
 |   +-- <task>.md                     <- Active tasks (frontmatter may include product:)
@@ -470,20 +482,42 @@ _dream_context/
 
 ---
 
+## Improving dreamcontext (Agent Feedback)
+
+You are not just a *user* of dreamcontext — you are its field reporter. When dreamcontext gets in your way, the system can only improve if that friction reaches its maintainers. Take responsibility: file it.
+
+**Trigger — the moment you notice any of these, consider filing feedback:**
+- You expected a fact to be in memory but `memory recall` didn't surface it (a recall gap, not a missing fact).
+- You wished a CLI command existed and there was no path (e.g. "I want to reopen a completed task" and no `tasks reopen`).
+- A command, hook, or doc behaved wrong, was confusing, or crashed.
+- The structure forced an awkward workaround to do something the system should support directly.
+
+Do **not** silently work around it. A workaround fixes today; feedback fixes the system.
+
+**The loop (this is the only sanctioned way to file — never run `gh issue create` by hand):**
+1. **Draft.** Run `dreamcontext feedback --dry-run` with the category and a complete scenario. Fill `-s` (what you were doing), `-e` (what you expected), `-g` (what was missing/broken), `-r` (exact commands), `-p` (your proposed improvement). A maintainer who has never seen your session must understand it from the issue alone — include the whole scenario.
+2. **Confirm with the user.** Show them the rendered draft and ask permission. This writes to a public repo on their behalf — never file without an explicit yes.
+3. **File.** Re-run the same command without `--dry-run` and with `--yes`. It checks for near-duplicate open issues, applies the `agent-feedback` label, and files to the dreamcontext project (`meanllbrl/dreamcontext`) — **not** the user's own repo.
+
+**No GitHub access?** If the command reports `gh` is missing or unauthenticated, relay its guidance to the user: install `gh` + run `gh auth login`, and if they have no GitHub account, ask them to create a free one at github.com/signup. They need an account to file. Once they're signed in, re-run the loop.
+
+**Quality bar:** one issue per distinct gap, concrete title, full scenario, a concrete proposal. Vague feedback ("recall is bad") is noise; a reproducible scenario with a proposed command is signal.
+
 ## Command Reference
 
 All commands prefixed with `dreamcontext`. For reading/searching, use native tools directly.
 
 | Command | Description |
 |---------|-------------|
-| `init [--multi-product=a,b,c]` | Initialize `_dream_context/`. Prompts interactively whether the project is a monorepo with multiple products; `--multi-product=a,b,c` skips the prompt and provides kebab-case product names directly. Creates `core/data-structures/<product>.md` per product (or `default.md` for single-product) and seeds `knowledge/products/`. |
+| `init [--multi-product=a,b,c]` | Initialize `_dream_context/`. Prompts interactively whether the project is a monorepo with multiple products; `--multi-product=a,b,c` skips the prompt and provides kebab-case product names directly. Creates `knowledge/data-structures/<product>.md` per product (or `default.md` for single-product) and seeds `knowledge/products/`. |
 | `core changelog add` | Add changelog entry (interactive) |
 | `core releases add [--ver v --summary s --yes] [--status planning]` | Create release (default: released with auto-discovery; --status planning: empty planning version, auto-becomes active) |
 | `core releases active [<version>] [--clear]` | Get/set/clear the active planning version (default for new tasks' `version` field) |
 | `core releases list [-n count]` | List recent releases |
 | `core releases show <version>` | Show release details |
-| `features create <name>` | Create feature PRD |
-| `features insert <name> <section> <content>` | Insert into feature section |
+| `features create <name> [-w why] [-t tags] [-s status] [--related-tasks a,b]` | Create feature PRD; frontmatter set without hand-editing (status: planning\|in_progress\|in_review\|active\|shipped\|deprecated) |
+| `features insert <name> <section> <content>` | Insert into feature section (replaces template placeholders on first write; `user_stories`/`acceptance_criteria` auto-formatted as `- [ ]` items) |
+| `features set <name> <tags\|status\|related_tasks> <value...>` | Set a feature frontmatter field (comma-separated for tags/related_tasks) without hand-editing |
 | `knowledge create <name>` | Create knowledge file |
 | `knowledge index [--tag <tag>]` | Show knowledge index |
 | `knowledge tags` | List standard tags |
@@ -494,7 +528,8 @@ All commands prefixed with `dreamcontext`. For reading/searching, use native too
 | `memory delete <slug> [--force]` | Remove a knowledge entry |
 | `memory list [--types ...]` | List indexable memory corpus by type |
 | `memory status` | Show corpus size broken down by type |
-| `tasks list [-s status] [--all]` | List tasks (default: excludes completed) |
+| `tasks list [-s status] [--all] [--tag t]… [--any-tag t]… [--version id] [--priority p] [--feature slug] [--group-by tag\|version\|priority\|status] [--long] [--json]` | List/filter/group tasks. Default excludes completed. `--tag` repeatable (AND), `--any-tag` repeatable (OR), filters compose; `--json` emits the filtered set; case-insensitive matching |
+| `tasks tags [--all] [--json]` | List distinct task tags with counts (discover before filtering) |
 | `tasks create <name> [-d desc] [-p priority] [-s status] [-t tags] [-w why] [--reach N --impact N --confidence N --effort N]` | Create task (defaults: priority=medium, status=todo). RICE flags optional and additive. |
 | `tasks rice <name> [--reach N] [--impact N] [--confidence N] [--effort N] [--clear]` | Print or update RICE values; no flags prints current values |
 | `tasks insert <name> <section> <content>` | Insert into task section |
@@ -529,6 +564,7 @@ All commands prefixed with `dreamcontext`. For reading/searching, use native too
 | `config show` | Print project config (platforms, packs, native-memory state) |
 | `config native-memory <enable\|disable>` | Toggle Claude's native auto-memory; disabled by default so dreamcontext owns project memory |
 | `upgrade [--check]` | Update the dreamcontext CLI itself to the latest npm release |
+| `feedback -c <category> -t <title> -s <scenario> [-e expected] [-g gap] [-r repro] [-p proposal] [--dry-run] [--yes]` | File a structured gap/bug as a GitHub issue to the **dreamcontext project** (upstream, not the user's repo). Use `--dry-run` to render a draft for the user; file with `--yes` only after they approve. Categories: `bug \| missing-cli \| unseen-memory \| feature \| docs \| other`. See "Improving dreamcontext" below. |
 
 Feature insert sections: `changelog`, `notes`, `technical_details`, `constraints`, `user_stories`, `acceptance_criteria`, `why`
 Task insert sections: `why`, `user_stories`, `acceptance_criteria`, `constraints`, `technical_details`, `notes`, `changelog`

package/skill-packs/excalidraw/SKILL.md

@@ -32,14 +32,90 @@ Write a spec JSON, then run it. The script prints `elements/images/texts` counts
 
 ### JS API (for pipelines that generate many boards)
 ```js
-const { buildExcalidraw, lane, grid } = require('.../scripts/build_excalidraw.js');
-buildExcalidraw({ out, elements: [ ...lane({ title, images, x, y, thumbW }) ] });
+const path = require('path');
+// skill lives at <project>/.claude/skills/excalidraw/ — adjust leading ../ count to match your script's depth from project root
+const { buildExcalidraw, lane, grid } = require(path.resolve(__dirname, '../.claude/skills/excalidraw/scripts/build_excalidraw.js'));
+buildExcalidraw({ out: path.resolve(__dirname, '../boards/Board.excalidraw.md'), elements: [ ...lane({ title, images, x, y, thumbW }) ] });
 ```
 
+## File layout
+
+### Single board (default)
+Keep the spec next to the generated board but clearly separated:
+```
+boards/
+├── MyBoard.excalidraw.md      ← generated deliverable; do not hand-edit
+└── _spec/
+    └── MyBoard.json           ← source of truth; edit this, then regenerate
+```
+The `.excalidraw.md` is **disposable** — it is fully derived from the spec. If the two ever
+disagree, the spec wins. Commit both (the board for Obsidian/GitHub preview, the spec for
+reproducibility), but only edit the spec.
+
+### Multi-board pipeline
+When a single generator produces several boards, isolate it in a `pipeline/` folder so the
+deliverable boards stay at the top of the project and are easy to open in Obsidian:
+```
+boards/
+├── Overview.excalidraw.md     ← generated
+├── Funnel.excalidraw.md       ← generated
+├── Pricing.excalidraw.md      ← generated
+└── pipeline/
+    ├── generate.js            ← single regen entrypoint: `node pipeline/generate.js`
+    ├── shared-style.js        ← shared palette / helpers
+    └── spec/
+        ├── Overview.json      ← source spec for Overview board
+        ├── Funnel.json        ← source spec for Funnel board
+        └── Pricing.json       ← source spec for Pricing board
+```
+- **Generated files** (`*.excalidraw.md`) live one level above `pipeline/` — open them in Obsidian without navigating into a sub-folder.
+- **Source specs** live in `pipeline/spec/` — one JSON per board.
+- **Single entrypoint**: `node pipeline/generate.js` rebuilds every board. No per-board manual commands.
+
+### Many boards from shared data (recipe)
+Use this pattern when multiple boards pull from the same data set (e.g. one board per product, per region, or per funnel step):
+
+```js
+// pipeline/generate.js  (lives at boards/pipeline/generate.js)
+const path = require('path');
+const ROOT  = path.resolve(__dirname, '..');          // boards/ directory
+// ../../ = project root (boards/ → project/); adjust if boards/ is nested deeper
+const { buildExcalidraw, lane } = require(path.resolve(__dirname, '../../.claude/skills/excalidraw/scripts/build_excalidraw.js'));
+const style  = require(path.resolve(__dirname, 'shared-style.js'));
+const items  = require(path.resolve(__dirname, 'spec/items.json'));  // shared data
+
+for (const item of items) {
+  const elements = style.buildItemBoard(item);        // per-item spec logic
+  buildExcalidraw({
+    out: path.resolve(ROOT, `${item.slug}.excalidraw.md`),
+    elements,
+  });
+  console.log('wrote', item.slug);
+}
+```
+
+```js
+// pipeline/shared-style.js  (lives at boards/pipeline/shared-style.js)
+const path = require('path');
+// ../../ = project root (boards/ → project/); adjust if boards/ is nested deeper
+const { card, connector, sectionTitle } = require(path.resolve(__dirname, '../../.claude/skills/excalidraw/scripts/lib/style.js'));
+
+exports.buildItemBoard = (item) => [
+  sectionTitle({ x: 0, y: 0, text: item.name, fontSize: 40 }),
+  // … common layout using item fields
+];
+```
+
+Key conventions:
+- `ROOT = path.resolve(__dirname, '..')` pins paths relative to the generator file, not the working directory. The generator works correctly wherever it is invoked from.
+- Each item produces exactly one board; the mapping is `items.json → <slug>.excalidraw.md`.
+- `shared-style.js` owns the layout logic — boards stay visually consistent; change the style once, regenerate all.
+- Add a `package.json` script or `Makefile` alias so the command is always `npm run boards` (or similar) and never has to be rediscovered.
+
 ## Spec schema
 ```jsonc
 {
-  "out": "/abs/path/Board.excalidraw.md",   // required (or pass --out)
+  "out": "./boards/Board.excalidraw.md",    // prefer __dirname-relative in JS generators; relative to cwd for CLI
   "vaultRoot": "/abs/vault",                  // optional; auto-detected by walking up to `.obsidian`
   "attachDir": "Attachments",                 // external images get copied here (relative to board dir)
   "wikilinkMode": "basename",                 // "basename" (default) or "path" (vault-relative)
@@ -48,6 +124,9 @@ buildExcalidraw({ out, elements: [ ...lane({ title, images, x, y, thumbW }) ] })
 }
 ```
 
+**Paths in generators**: always use `path.resolve(__dirname, ...)` for `out` and image `path` fields — never
+hardcode absolute paths. This keeps the generator portable: move the folder and it still runs.
+
 ### Element types
 - `text`     — `{ x, y, text, fontSize?, color?, width?, align?, fontFamily? }` (fontFamily 1=hand, 2=normal, 3=code). **Set `width` for any caption/label that must stay inside a column or card** → the text WRAPS to that width (autoResize off) and its height is computed from the wrapped line count. Omit `width` only for short single-line text you want sized to content (it renders on one line and will overlap neighbours if long).
 - `image`    — `{ x, y, path, width? , height? }` — give ONE of width/height; the other is derived from aspect. `path` is an absolute file path.

package/skill-packs/video-watching/SKILL.md

@@ -39,15 +39,36 @@ if it's installed.
 #   language auto-detects — no need to pass it. Override only if auto mislabels a
 #   short/ambiguous clip: ./transcribe.sh "/abs/path/clip.mp4" tr
 ```
+
+**Pick the mode for the kind of video — this matters most for app/UI recordings:**
+- **Talking-head / lecture / ad creative** → the default is right. Scene-detect + a
+  10s gap-fill catches the visuals.
+- **App screen-recording / onboarding funnel / UI walkthrough** → add `--mode ui`.
+  App screens linger 3–5s and change by **text only** (a questionnaire step, a
+  paywall) — they don't move enough to trip scene-detect, so the 10s default
+  silently drops most of them. `--mode ui` samples every ~2.5s so each screen lands.
+  If you only need the screens (no narration), add `--frames-only` to skip whisper:
+  ```bash
+  ./scripts/transcribe.sh "/abs/path/onboarding.mp4" --mode ui --frames-only --contact-sheet
+  ```
+
 This writes everything into `<video_dir>/<slug>.media/`:
-- `transcript.srt` / `.json` / `.txt` — timestamped transcript (large-v3-turbo)
+- `transcript.srt` / `.json` / `.txt` — timestamped transcript (large-v3-turbo) — *skipped with `--frames-only`*
 - `frames/anchor_first.jpg` / `anchor_last.jpg` — first + last frame, always captured
   (short cut-heavy creatives carry the hook and CTA here; scene-detect misses both)
-- `frames/scene_*.jpg` — frames at each scene change (slides/UI transitions)
-- `frames/gap_*.jpg` — fill frames so no stretch > 10s goes unsampled (catches
-  static-but-important sections scene-detect misses: app demos, slides, CTAs)
+- `frames/frame_*.jpg` — frames selected in **one time-based pass**: a scene change
+  fired (slide/UI transition) **or** `MAX_GAP` seconds elapsed since the last frame,
+  whichever comes first. The gap rule is wall-clock based (`prev_selected_t`), so it
+  works on variable-frame-rate screen recordings where frame-number sampling breaks,
+  and it guarantees every static stretch (app demos, slides, CTAs) gets a frame.
+- `frames/contact_sheet.jpg` — tiled montage of all frames, *only with `--contact-sheet`*
 - `frames.json` — **the index you read**: `[{file, t, at, type}]`, sorted by time,
-  near-duplicate timestamps collapsed (anchors always kept)
+  near-duplicate timestamps collapsed (anchors always kept). `type` is `scene` (a
+  picture change fired), `gap` (a periodic fill at the `MAX_GAP` cadence), or `anchor`.
+
+The engine prints a **coverage check** at the end: `longest unsampled gap = Xs`. If it
+warns the gap is >2× `MAX_GAP`, frames are likely missing — re-run denser (`--max-gap`
+lower, or `--mode ui`) **before** any expensive deep-analysis pass.
 
 `audio.wav` is auto-deleted after transcription (it's a ~1.9MB/min whisper-only
 intermediate). The whole `*.media/` dir is gitignored — it stays next to the video
@@ -69,7 +90,9 @@ nothing on screen need no frame.
 > Heuristic: the two `anchor` frames (first/last) almost always matter — the hook
 > and the CTA. Every `scene` frame is a candidate (the picture changed for a
 > reason). `gap` frames cover static stretches scene-detect skipped — often the
-> most informative part (an app demo or slide that doesn't "move"), so check them.
+> most informative part (an app demo or onboarding screen that doesn't "move"), so
+> check them. In `--mode ui` runs most frames are `gap` — that's expected and you
+> generally want to look at all of them, one per screen.
 
 **Need a frame the index doesn't have? Grab it on demand.** Scene-detect fires on
 motion, not on meaning — on fast-cut video the most informative moment often sits
@@ -116,6 +139,14 @@ relevant dreamcontext skill (per the skill-triage rule) and load it:
 - **Knowledge / training** → if it should persist for the project, hand the transcript to `dreamcontext knowledge` so it becomes durable context
 Don't guess the use-case — let the user direct it.
 
+> **UI teardown (no transcript needed).** When the goal is purely the app flow —
+> e.g. tearing down a competitor's onboarding funnel — run `--frames-only --mode ui`
+> and skip the `.transcript.md` entirely. The deliverable becomes a **curated screen
+> list** (one entry per onboarding step, in order, from `frames.json`), which feeds a
+> board (`excalidraw`) or an `onboarding-design` analysis directly. Use `--contact-sheet`
+> to eyeball coverage first, and trust the coverage warning — under-sampling here is
+> exactly what makes a teardown wrongly report "screen X wasn't shown".
+
 ## What this skill is NOT
 - Not a knowledge-base writer or ingestion pipeline. This skill produces the
   transcript artifact; persisting it (chunking, embedding, ingest into a project's
@@ -140,12 +171,22 @@ brew install whisper-cpp ffmpeg          # yt-dlp too, only for remote links
 ├── SKILL.md                    ← you are here
 └── scripts/
     ├── transcribe.sh           ← video → transcript + frames + frames.json (the engine)
-    ├── gap_fill.py             ← timestamps to fill scene-detect gaps (> MAX_GAP)
-    └── build_frame_index.py    ← frames/*.jpg → frames.json (pts_time index)
+    └── build_frame_index.py    ← frames/*.jpg → frames.json (pts_time index + coverage check)
 ```
 
-## Tuning
-- Too few frames on a slide-heavy video? `SCENE_THRESHOLD=0.1 ./transcribe.sh …`
-- Long static lecture over-sampled? Raise `MAX_GAP=20 ./transcribe.sh …` (default 10s).
-- Capturing too many near-identical frames? `DEDUPE_SEC=1.0 ./transcribe.sh …`
-- Force a model: `WHISPER_MODEL=/abs/ggml-large-v3.bin ./transcribe.sh …`
+## Flags & tuning
+Flags (each also settable as an env var, e.g. `MODE=ui`):
+- `--mode ui|lecture` — sampling preset. `ui` = `MAX_GAP` 2.5s (app screens); `lecture`
+  (default) = 10s (talking-head). Explicit `--max-gap`/`--scene-threshold` always win.
+- `--frames-only` — skip whisper; extract frames only (UI/UX teardowns).
+- `--max-gap N` — guarantee a frame at least every N seconds.
+- `--scene-threshold N` — scene-change sensitivity, lower = more frames.
+- `--contact-sheet` — also emit `frames/contact_sheet.jpg` (coverage at a glance).
+- `--lang CODE` — force the transcript language (default: auto-detect).
+
+Common adjustments:
+- Onboarding/UI recording under-sampled? `--mode ui` (or push further: `--max-gap 1.5`).
+- Too few frames on a slide-heavy talk? `--scene-threshold 0.1`.
+- Long static lecture over-sampled? `--max-gap 20`.
+- Capturing too many near-identical frames? `DEDUPE_SEC=1.0 ./transcribe.sh …`.
+- Force a model: `WHISPER_MODEL=/abs/ggml-large-v3.bin ./transcribe.sh …`.

package/skill-packs/video-watching/scripts/build_frame_index.py

@@ -1,14 +1,22 @@
 #!/usr/bin/env python3
 """Build frames.json: map each extracted frame to its pts_time on the video timeline.
 
-Reads the per-frame pts_time dumps (scene_times.txt from ffmpeg metadata, gap_times.txt
-written by transcribe.sh) alongside the frames, pairs each timestamp with its
-zero-padded frame file in selection order, adds the first/last anchor frames, drops
-near-duplicate timestamps, and emits frames.json sorted by time.
+transcribe.sh selects frames in ONE time-based pass (scene change OR every MAX_GAP),
+dumping each kept frame's pts_time to frame_times.txt. This pairs every timestamp with
+its zero-padded frame file in selection order, adds the first/last anchor frames, drops
+near-duplicate timestamps, labels each frame (scene vs gap vs anchor), and emits
+frames.json sorted by time. It also prints a COVERAGE check — the largest unsampled
+stretch — so a human can catch under-sampling before an expensive deep-analysis pass.
+
+Type labels are reconstructed from inter-frame spacing (no second decode): a frame that
+landed sooner than MAX_GAP after the previous one was triggered by a scene change
+('scene'); one that landed at the MAX_GAP cadence is a periodic fill ('gap'). They are
+hints for which frames to prioritize, not a hard contract.
 
 Stdlib only — no venv needed.
 Usage: build_frame_index.py <OUT_DIR> [DURATION_SEC]
 Env:   DEDUPE_SEC=0.4  collapse non-anchor frames closer than this to the kept one.
+       MAX_GAP=10      the gap target the engine sampled at (drives type + coverage warn).
 """
 import json
 import os
@@ -19,6 +27,7 @@ from pathlib import Path
 # metadata=print header line, e.g.: "frame:0    pts:321024  pts_time:12.852500"
 FRAME_RE = re.compile(r"frame:(\d+)\b.*?pts_time:([\d.]+)", re.DOTALL)
 DEDUPE_SEC = float(os.environ.get("DEDUPE_SEC", "0.4"))
+MAX_GAP = float(os.environ.get("MAX_GAP", "10"))
 
 
 def parse_times(meta_file: Path) -> dict[int, float]:
@@ -29,11 +38,11 @@ def parse_times(meta_file: Path) -> dict[int, float]:
     return {int(n): round(float(t), 2) for n, t in FRAME_RE.findall(text)}
 
 
-def collect(out_dir: Path, prefix: str, meta_name: str, kind: str) -> list[dict]:
+def collect(out_dir: Path, prefix: str, meta_name: str) -> list[dict]:
     times = parse_times(out_dir / "frames" / meta_name)
     frames = sorted((out_dir / "frames").glob(f"{prefix}_*.jpg"))
     # transcribe.sh names files 1-based (%04d starts at 0001); metadata frame: is 0-based.
-    return [{"file": f"frames/{f.name}", "t": times.get(i), "type": kind}
+    return [{"file": f"frames/{f.name}", "t": times.get(i), "type": "key"}
             for i, f in enumerate(frames)]
 
 
@@ -69,6 +78,40 @@ def dedupe(rows: list[dict]) -> list[dict]:
     return kept
 
 
+def label_types(rows: list[dict]) -> None:
+    """Reconstruct scene/gap from spacing. Frames spaced >= ~MAX_GAP are periodic
+    fills ('gap'); closer ones were pulled in early by a scene change ('scene')."""
+    near = MAX_GAP * 0.9
+    prev_t = 0.0
+    for r in rows:
+        if r["type"] == "anchor":
+            if r["t"] is not None:
+                prev_t = r["t"]
+            continue
+        if r["t"] is None:
+            r["type"] = "scene"
+            continue
+        r["type"] = "gap" if (r["t"] - prev_t) >= near else "scene"
+        prev_t = r["t"]
+
+
+def coverage(rows: list[dict], duration: float) -> tuple[float, float]:
+    """Largest unsampled stretch (s) and where it starts, over [0, duration]."""
+    ts = sorted(r["t"] for r in rows if r["t"] is not None)
+    if not ts:
+        return (duration, 0.0)
+    # Bound the right edge with the real duration; if ffprobe couldn't read it (0), fall
+    # back to the last sampled time so the tail gap (last frame -> end) still surfaces
+    # rather than being silently dropped.
+    right = round(duration, 2) if duration > 0 else ts[-1]
+    bounds = [0.0] + ts + [right]
+    worst, at = 0.0, 0.0
+    for a, b in zip(bounds, bounds[1:]):
+        if b - a > worst:
+            worst, at = b - a, a
+    return (worst, at)
+
+
 def main() -> int:
     if len(sys.argv) < 2:
         print("usage: build_frame_index.py <OUT_DIR> [DURATION_SEC]", file=sys.stderr)
@@ -76,18 +119,26 @@ def main() -> int:
     out_dir = Path(sys.argv[1])
     duration = float(sys.argv[2]) if len(sys.argv) > 2 else 0.0
 
-    rows = collect(out_dir, "scene", "scene_times.txt", "scene")
-    rows += collect(out_dir, "gap", "gap_times.txt", "gap")
+    rows = collect(out_dir, "frame", "frame_times.txt")
     rows += anchors(out_dir, duration)
-    # Sort by time; unknown timestamps sink to the end.
-    rows.sort(key=lambda r: (r["t"] is None, r["t"] or 0.0))
+    # Sort by time (unknown timestamps sink to the end); on a tie, anchors sort FIRST so
+    # the eq(n,0) seed frame at t=0 (and any selected frame coincident with anchor_last)
+    # dedupes away against the identical anchor instead of producing a duplicate entry.
+    rows.sort(key=lambda r: (r["t"] is None, r["t"] or 0.0, r["type"] != "anchor"))
     rows = dedupe(rows)
+    label_types(rows)
     for r in rows:
         r["at"] = fmt(r["t"])
 
     (out_dir / "frames.json").write_text(json.dumps(rows, ensure_ascii=False, indent=2))
+
     n_anchor = sum(r["type"] == "anchor" for r in rows)
+    worst, at = coverage(rows, duration)
     print(f"   frames.json: {len(rows)} frames indexed ({n_anchor} anchors, dedupe<{DEDUPE_SEC}s)")
+    print(f"   coverage: longest unsampled gap = {worst:.1f}s at {fmt(at)} (target MAX_GAP={MAX_GAP:g}s)")
+    if duration > 0 and worst > MAX_GAP * 2:
+        print(f"   ⚠ coverage gap is >2x MAX_GAP — frames may be missing around {fmt(at)}. "
+              f"Re-run denser: --max-gap {MAX_GAP / 2:g} (or --mode ui for app recordings).")
     return 0