davinci-resolve-mcp 3.2.2 → 3.4.0

package/CHANGELOG.md

@@ -2,6 +2,83 @@
 
 Release history for the DaVinci Resolve MCP Server. The latest release is summarized in the root README; older entries live here to keep the README focused.
 
+## What's New in v3.4.0 — review a bin one frame at a time in the control panel
+
+Contributed by @tpellet (#230), their first contribution here.
+
+### Added
+
+- **Serial source review in the control panel.** Reviewing a bin meant opening
+  each clip separately. The review bin now has an **Enlarge / review** button
+  per card that opens a full-size frame with previous/next navigation, so a bin
+  is walked once rather than clicked through a card at a time.
+- **Include / Exclude / Unreviewed per clip, and an independent star rating.**
+  Keyboard-driven — `I`, `X`, `U` and the arrow keys — with Include and Exclude
+  advancing automatically. Selection and rating are separate fields: rating a
+  clip does not decide it, and excluding one does not discard its rating.
+- **A selection filter** — all / non-excluded / excluded — alongside the
+  existing bin filter, and a selection chip on every card, so the state of a
+  pass is visible without opening anything.
+- **Decisions survive a reload.** Both fields go through the existing
+  correction store, so they persist the way clip notes already did and are
+  visible to everything else that reads corrections. Notes are untouched.
+
+### Changed
+
+- **Review thumbnails are letterboxed rather than cropped** (`object-fit:
+  cover` → `contain`). A cropped thumbnail hides exactly what a source review
+  is for: framing, headroom, and what is at the edges of frame.
+
+### Gating
+
+- **Every save is verified, not assumed.** The panel re-reads the clip after
+  each write and refuses to advance if the value it reads back is not the one
+  it sent, so a failed save cannot be walked past. `apply_clip_correction`
+  validates server-side as well: `user.selection` must be one of the three
+  literals, and `user.rating` must be an `int` from 0 to 5 — `type(value) is
+  not int` deliberately, so a JSON `true` is rejected rather than silently
+  stored as a rating of 1.
+- **No source media is touched and no Resolve edit is made.** Previews are
+  analyzed frames that already exist on disk; there is no conversion step.
+
+## What's New in v3.3.0 — ask the server what the native Resolve API contains
+
+Contributed by @legionsound (#229), the second of the two branches queued in #207.
+
+### Added
+
+- **`resolve_control`: `search_api`, `describe_api`, `api_surface`**, plus
+  granular twins `search_resolve_api`, `describe_resolve_api` and
+  `get_resolve_api_surface`. `resolve_control api_truth` already answered *what
+  is broken*; nothing answered *what exists*. #205 shipped Blackmagic's typed
+  `DaVinciResolveScript.pyi` and `scripts/audit_typed_api.py` could inventory
+  it, but only from a shell — an agent talking to this server had no way to ask.
+  This is the equivalent of Blackmagic's own `search_scripting_api`. Tool count
+  37/384 → 37/387.
+- **All three are read-only and none needs a Resolve connection.** They parse
+  the stub that already ships in `docs/reference/`, so they answer with Resolve
+  closed, and they describe the stub checked into this repository — currently
+  21.1.0.14 — not whatever build happens to be installed. A missing stub is
+  reported as missing rather than guessed around.
+- **Every result carries `referenced_in_this_server` and the files that
+  reference the method**, so a lookup doubles as a parity check: does the native
+  API have it, and do we wrap it? The flag counts executable syntax only —
+  attribute access, calls, `getattr(obj, "Name")` — never docstrings or
+  comments, built the same way `audit_typed_api.py` builds its source
+  references. A method named in prose is not coverage.
+- **Ambiguity is reported, not guessed.** A bare `GetName` lists its candidates
+  instead of picking one. An invalid regex is refused rather than raised.
+  Results are capped with an explicit `truncated` flag rather than silently cut.
+
+### Guards
+
+- The parser independently reports **410 methods, 46 TypedDicts, 513 fields**,
+  and `tests/test_typed_api_search.py` asserts that equality against the
+  inventory recorded in `resolve-211-typed-api.md`. A future stub refresh that
+  changes the surface now fails the suite instead of drifting quietly. The same
+  file checks both interfaces agree on surface, search and describe, and that
+  neither needs a connection.
+
 ## What's New in v3.2.2 — an analysis root that is deleted is actually let go of
 
 Contributed by @Dev-next-gen (#228), generalised to the second site and to the

package/README.md

@@ -2,10 +2,10 @@
 
 English | [简体中文](README.zh-CN.md)
 
-[![Version](https://img.shields.io/badge/version-3.2.2-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-3.4.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
 [![npm](https://img.shields.io/npm/v/davinci-resolve-mcp.svg?label=npm&color=CB3837)](https://www.npmjs.com/package/davinci-resolve-mcp)
 [![API Coverage](https://img.shields.io/badge/API%20Coverage-100%25-brightgreen.svg)](docs/reference/api-coverage.md)
-[![Tools](https://img.shields.io/badge/MCP%20Tools-37%20(384%20full)-blue.svg)](#server-modes)
+[![Tools](https://img.shields.io/badge/MCP%20Tools-37%20(387%20full)-blue.svg)](#server-modes)
 [![Advanced](https://img.shields.io/badge/Advanced%20(offline)-18%20tools-blueviolet.svg)](#server-modes)
 [![Tested](https://img.shields.io/badge/Live%20Tested-93.6%25-green.svg)](docs/reference/api-coverage.md#test-results)
 [![DaVinci Resolve](https://img.shields.io/badge/DaVinci%20Resolve-18.5+-darkred.svg)](https://www.blackmagicdesign.com/products/davinciresolve)
@@ -133,7 +133,7 @@ The command starts a loopback-only server and opens the control panel in your br
 | Mode | Entry point | Tools | Best for |
 |------|-------------|-------|----------|
 | Compound | `src/server.py` | 37 | Default mode for most assistants. Related Resolve operations are grouped behind action parameters to keep context usage low. |
-| Full / granular | `src/server.py --full` or `src/resolve_mcp_server.py` | 384 | Power users who want one MCP tool per Resolve API method. |
+| Full / granular | `src/server.py --full` or `src/resolve_mcp_server.py` | 387 | Power users who want one MCP tool per Resolve API method. |
 
 The compound server is recommended unless you specifically need the granular one-tool-per-method surface.
 
@@ -365,7 +365,7 @@ The default server is a local stdio process launched by your MCP client; it does
 
 | Metric | Value |
 |--------|-------|
-| MCP Tools | **37** compound / **384** granular (live server) |
+| MCP Tools | **37** compound / **387** granular (live server) |
 | Advanced (offline) tools | **18** — .drp/.drt/.drx + DB authoring, no Resolve running |
 | Kernel Actions | **136** guarded workflow actions across 9 compound tools |
 | API Methods Covered | **361/361** (100%) |

package/README.zh-CN.md

@@ -2,17 +2,17 @@
 
 [English](README.md) | 简体中文
 
-[![Version](https://img.shields.io/badge/version-3.2.2-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
+[![Version](https://img.shields.io/badge/version-3.4.0-blue.svg)](https://github.com/samuelgursky/davinci-resolve-mcp/releases)
 [![npm](https://img.shields.io/npm/v/davinci-resolve-mcp.svg?label=npm&color=CB3837)](https://www.npmjs.com/package/davinci-resolve-mcp)
 [![API Coverage](https://img.shields.io/badge/API%20Coverage-100%25-brightgreen.svg)](docs/reference/api-coverage.md)
-[![Tools](https://img.shields.io/badge/MCP%20Tools-37%20(384%20full)-blue.svg)](#服务器模式)
+[![Tools](https://img.shields.io/badge/MCP%20Tools-37%20(387%20full)-blue.svg)](#服务器模式)
 [![Advanced](https://img.shields.io/badge/Advanced%20(offline)-18%20tools-blueviolet.svg)](#服务器模式)
 [![Tested](https://img.shields.io/badge/Live%20Tested-93.6%25-green.svg)](docs/reference/api-coverage.md#test-results)
 [![DaVinci Resolve](https://img.shields.io/badge/DaVinci%20Resolve-18.5+-darkred.svg)](https://www.blackmagicdesign.com/products/davinciresolve)
 [![Python](https://img.shields.io/badge/python-3.10+-green.svg)](https://www.python.org/downloads/)
 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
-> 本翻译对应 v3.2.2 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
+> 本翻译对应 v3.4.0 版 README。如与英文原版有出入，以 [英文原版](README.md) 为准。
 
 一个 Model Context Protocol (MCP) 服务器，让 AI 助手通过官方脚本 API 控制 DaVinci Resolve Studio（达芬奇）。它提供完整的 API 覆盖，外加带护栏的工作流助手，涵盖剪辑、媒体池整理、渲染设置、审阅标记、调色、Fusion、Fairlight、项目生命周期任务、扩展开发，以及不碰源媒体的媒体分析。
 
@@ -88,7 +88,7 @@ venv/bin/python -m src.control_panel
 | 模式 | 入口 | 工具数 | 适合谁 |
 |------|------|--------|--------|
 | Compound（复合） | `src/server.py` | 37 | 大多数助手的默认模式。相关的 Resolve 操作按 action 参数分组，压低上下文占用。 |
-| Full / granular（细粒度） | `src/server.py --full` 或 `src/resolve_mcp_server.py` | 384 | 想要"一个 Resolve API 方法 = 一个 MCP 工具"的重度用户。 |
+| Full / granular（细粒度） | `src/server.py --full` 或 `src/resolve_mcp_server.py` | 387 | 想要"一个 Resolve API 方法 = 一个 MCP 工具"的重度用户。 |
 
 除非你明确需要一方法一工具的细粒度界面，否则推荐复合模式。
 
@@ -226,7 +226,7 @@ DRX 调色写入**针对 Resolve Studio 做过实机校准**：调色参数默
 
 | 指标 | 数值 |
 |------|------|
-| MCP 工具 | **37** 复合 / **384** 细粒度（实时服务器） |
+| MCP 工具 | **37** 复合 / **387** 细粒度（实时服务器） |
 | Advanced（离线）工具 | **18**——.drp/.drt/.drx + 数据库创作，无需 Resolve 运行 |
 | 内核 action | 9 个复合工具下 **136** 个带护栏的工作流 action |
 | API 方法覆盖 | **361/361**（100%） |

package/docs/SKILL.md

@@ -353,7 +353,7 @@ to the user as verified.
 | Mode | Entry point | Tool count | Use when |
 |---|---|---|---|
 | Compound (default) | `src/server.py` | 37 tools | Most workflows — keeps context lean |
-| Granular (full) | `src/server.py --full` | 384 tools | Power users needing one tool per API method |
+| Granular (full) | `src/server.py --full` | 387 tools | Power users needing one tool per API method |
 
 Resolve 21.1 adds [twelve read-only discovery controls](reference/resolve211-read-controls.md)
 for edition, presets, audio formats/codecs, normalization modes, speed, fades

package/docs/guides/control-panel.md

@@ -101,6 +101,19 @@ detection has run (`detect_entities` + a one-frame-per-cluster confirmation
 in chat), a `Recurring across this bin` card lists the labeled people,
 places, and objects with their shot counts.
 
+Use **Enlarge / review** on a card to inspect its complete analyzed frame without
+cropping. Previous/Next (or arrow keys) follow the visible bin order. **Include**
+(`I`) and **Exclude** (`X`) save the selection and advance after readback;
+**Unreviewed** (`U`) clears the decision without advancing. Ratings save independently
+and do not clear exclusions. The selection filter can show all, non-excluded,
+or excluded clips; it applies to the bin browser, not search results.
+
+Selections are stored as `user.selection` corrections alongside existing notes
+and ratings. They express review preferences, not automatic timeline edits.
+Previews use existing analyzed frames, so their resolution depends on the analysis;
+this does not generate proxies or stream original media. Existing clip detail
+controls remain available for notes and metadata edits.
+
 ### Clip detail
 
 ![Clip detail with shot strip](../images/control-panel/03-clip-detail.png)

package/docs/install.md

@@ -144,7 +144,7 @@ The MCP server comes in two modes:
 | Mode | File | Tools | Best For |
 |------|------|-------|----------|
 | **Compound** (default) | `src/server.py` | 37 | Most users — fast, clean, low context usage |
-| **Full** | `src/resolve_mcp_server.py` | 384 | Power users who want one tool per API method |
+| **Full** | `src/resolve_mcp_server.py` | 387 | Power users who want one tool per API method |
 
 The compound server's `timeline_item` tool includes dedicated actions for common workflows:
 
@@ -159,7 +159,7 @@ The compound server's `timeline_item` tool includes dedicated actions for common
 
 The installer uses the compound server by default. To use the full server:
 ```bash
-python src/server.py --full    # Launch full 384-tool server
+python src/server.py --full    # Launch full 387-tool server
 # Or point your MCP config directly at src/resolve_mcp_server.py
 ```
 

package/docs/reference/api-coverage.md

@@ -25,7 +25,7 @@ Every non-deprecated method in the bundled legacy README is represented. This
 does not claim complete coverage of the newer Resolve 21.1 typed API. The
 default compound server exposes **37 tools** that group related operations by
 action parameter, keeping LLM context windows lean. The full granular server
-provides **384 individual tools** for power users. The legacy coverage spans
+provides **387 individual tools** for power users. The legacy coverage spans
 13 API object classes. MCP-level kernel actions are tracked separately in
 [Kernel Action Coverage](../kernels/README.md).
 
@@ -39,6 +39,11 @@ Parity with Blackmagic's own MCP surfaced one more gap: it exposes
 node but never list, install or remove LUT files. The `lut` tool and its
 granular twins close that. See [LUT file controls](lut-file-controls.md).
 
+The typed stub shipped in #205 is now queryable from the server itself, the
+way Blackmagic's MCP exposes `search_scripting_api` — and each result also says
+whether this server wraps the method, so a lookup doubles as a parity check.
+See [Querying the typed API](typed-api-search.md).
+
 The 34th compound tool is `timeline_versioning` (C6) — an MCP-level workflow
 tool, not a wrapper around a Resolve API method. It surfaces the
 version-on-mutate hook that auto-archives the working timeline before any

package/docs/reference/typed-api-search.md

@@ -0,0 +1,56 @@
+# Querying the typed API from inside the server
+
+`resolve_control api_truth` answers *what is broken*. Nothing answered *what
+exists*. PR #205 landed Blackmagic's `DaVinciResolveScript.pyi` in
+`docs/reference/`, and `scripts/audit_typed_api.py` can turn it into a full
+inventory — but only from a shell. An agent talking to this server had no way
+to ask what the native API contains.
+
+Blackmagic's own MCP exposes `search_scripting_api` for this. These are the
+equivalent, with one addition that matters more here.
+
+## The addition: coverage, not just existence
+
+Every result carries `referenced_in_this_server` and the source files that
+reference it. That turns a lookup into a parity check — *does the native API
+have it, and do we wrap it?* — which is the question the whole 21.1 audit was
+built to answer, and it was previously only answerable by grepping.
+
+The flag counts **executable syntax only**: attribute access, calls, and
+`getattr(obj, "Name")`. A method named in a docstring or a comment is not
+coverage. Treating prose as coverage is the specific mistake this repo's audits
+exist to avoid, so the flag is built the same way `scripts/audit_typed_api.py`
+builds its source references.
+
+## Actions and tools
+
+Compound `resolve_control`, none of which need a Resolve connection:
+
+- `search_api(pattern, kind?, limit?)` — case-insensitive regex over
+  class-qualified method names, signatures, TypedDict names, field names and
+  descriptions. `kind` is `all`, `methods` or `options`. Results are capped and
+  the response declares `truncated` rather than silently cutting.
+- `describe_api(symbol)` — one `Class.Method`, an unambiguous bare method name,
+  or a TypedDict name. An ambiguous bare name lists the candidates instead of
+  guessing.
+- `api_surface()` — counts and the object list.
+
+Granular twins: `search_resolve_api`, `describe_resolve_api`,
+`get_resolve_api_surface`. Tool count 384 → 387. The granular tools carry the read-only annotation, since
+for the granular server the MCP annotation is the signal a client reads.
+
+## Self-consistency
+
+The parser reports **410 methods, 46 TypedDicts, 513 fields**, independently
+matching the inventory published in `resolve-211-typed-api.md` and the
+disposition ledgers built during the 21.1 audit. That agreement is asserted in
+`tests/test_typed_api_search.py`, so a stub refresh that changes the surface
+will fail the suite rather than drift quietly.
+
+## Scope
+
+This reads the stub shipped in this repository; it does not query a running
+Resolve, and it will report a missing stub rather than guessing. It therefore
+describes the API of the Resolve version whose stub is checked in — 21.1.0.14 —
+not whatever build happens to be installed. Refreshing the stub is the existing
+documented process in `resolve-211-typed-api.md`.

package/install.py

@@ -37,7 +37,7 @@ from src.utils.update_check import (
 
 # ─── Version ──────────────────────────────────────────────────────────────────
 
-VERSION = "3.2.2"
+VERSION = "3.4.0"
 # Only hard floor: mcp[cli] requires Python 3.10+. There is no upper bound —
 # Resolve's scripting bridge loads into newer interpreters on recent builds
 # (Python 3.14 verified against Resolve Studio 20.3.2). Older Resolve builds
@@ -1543,7 +1543,7 @@ def verify_resolve_connection(python_path, api_path, lib_path):
 
 def print_banner():
     title = f"DaVinci Resolve MCP Server — Installer v{VERSION}"
-    subtitle = "37 compound · 384 full · 3 platforms"
+    subtitle = "37 compound · 387 full · 3 platforms"
     print()
     print(bold("  ╔══════════════════════════════════════════════════════╗"))
     print(bold(f"  ║{title:^54}║"))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "davinci-resolve-mcp",
-  "version": "3.2.2",
+  "version": "3.4.0",
   "description": "NPM bootstrapper for the DaVinci Resolve MCP Server.",
   "license": "MIT",
   "author": "Samuel Gursky <samgursky@gmail.com>",

package/src/analysis_dashboard.py

@@ -1658,7 +1658,7 @@ HTML = r"""<!doctype html>
       aspect-ratio: 16 / 9;
       background: var(--lab-workspace-letterbox);
       border-radius: var(--radius-sm);
-      object-fit: cover;
+      object-fit: contain;
       display: block;
     }
     .review-thumb.placeholder {
@@ -4265,6 +4265,11 @@ HTML = r"""<!doctype html>
           <select id="reviewBinFilter" aria-label="Filter by bin">
             <option value="">All bins</option>
           </select>
+          <select id="sourceSelectionFilter" aria-label="Filter by source selection">
+            <option value="all">All selections</option>
+            <option value="non-excluded">Non-excluded</option>
+            <option value="excluded">Excluded</option>
+          </select>
           <div class="review-view-toggle" role="tablist" aria-label="View mode">
             <button id="reviewViewGridBtn" class="active" data-view-mode="grid" type="button">Grid</button>
             <button id="reviewViewListBtn" data-view-mode="list" type="button">List</button>
@@ -8822,11 +8827,159 @@ HTML = r"""<!doctype html>
         sorted.map(b => `<option value="${escapeHtml(b)}" ${b === current ? 'selected' : ''}>${escapeHtml(b)}</option>`).join('');
     }
 
+    let sourceSelectionFilter = 'all';
+    function matchesSourceSelection(clip) {
+      const selection = clip.user_selection || 'Unreviewed';
+      return sourceSelectionFilter === 'all'
+        || (sourceSelectionFilter === 'excluded' ? selection === 'Exclude' : selection !== 'Exclude');
+    }
+
+    // Source preview reviews the current bin/filter order using persisted corrections.
+    const sourcePreview = document.createElement('dialog');
+    sourcePreview.setAttribute('aria-label', 'Source preview');
+    sourcePreview.style.cssText = 'max-width:96vw;max-height:96vh;background:var(--bg-elevated-1);color:var(--text-primary)';
+    sourcePreview.innerHTML = `<button type="button" data-preview-close>Close</button>
+      <h3 data-preview-title></h3><div data-preview-controls>
+      <button type="button" data-preview-step="-1">← Previous</button>
+      <button type="button" data-preview-selection="Include">Include & next (I)</button>
+      <button type="button" data-preview-selection="Exclude">Exclude & next (X)</button>
+      <button type="button" data-preview-selection="Unreviewed">Unreviewed (U)</button>
+      <button type="button" data-preview-step="1">Next →</button>
+      <span>Rating:</span>${[0,1,2,3,4,5].map(n => `<button type="button" data-preview-rating="${n}" aria-label="${n ? n + ' stars' : 'Clear stars'}">${n ? '★'.repeat(n) : 'Clear'}</button>`).join('')}
+      </div><p data-preview-status role="status"></p>
+      <img data-preview-image alt="" style="display:block;max-width:90vw;max-height:70vh;object-fit:contain">`;
+    document.body.append(sourcePreview);
+    const previewImage = sourcePreview.querySelector('[data-preview-image]');
+    const previewStatus = sourcePreview.querySelector('[data-preview-status]');
+    let previewQueue = [], previewIndex = -1, previewBusy = false, previewReady = false, previewGeneration = 0;
+
+    function lockSourcePreview(busy) {
+      previewBusy = busy;
+      sourcePreview.querySelectorAll('[data-preview-controls] button').forEach(button => {
+        button.disabled = busy || (!button.dataset.previewStep && !previewReady);
+      });
+    }
+
+    function displaySourceReview(data, clip) {
+      const selection = readCorrectionValue(data.corrections, 'clip', clip.clip_id, 'user.selection') || 'Unreviewed';
+      const rating = readCorrectionValue(data.corrections, 'clip', clip.clip_id, 'user.rating') || 0;
+      clip.user_selection = selection;
+      sourcePreview.querySelectorAll('[data-preview-rating]').forEach(button => {
+        button.setAttribute('aria-pressed', String(Number(button.dataset.previewRating) === rating));
+      });
+      sourcePreview.querySelectorAll('[data-preview-selection]').forEach(button => {
+        button.setAttribute('aria-pressed', String(button.dataset.previewSelection === selection));
+      });
+      previewStatus.textContent = `${selection} · ${rating} stars — saved. ←/→ navigate; I include; X exclude; U clear selection.`;
+    }
+
+    async function showSourcePreview(index) {
+      if (previewBusy || index < 0 || index >= previewQueue.length) return;
+      previewIndex = index;
+      previewReady = false;
+      const clip = previewQueue[index], generation = ++previewGeneration;
+      lockSourcePreview(true);
+      sourcePreview.querySelector('[data-preview-title]').textContent = `${index + 1} / ${previewQueue.length} — ${clip.clip_name || clip.clip_id}`;
+      previewStatus.textContent = 'Loading preview and saved review…';
+      previewImage.style.visibility = 'hidden';
+      previewImage.alt = clip.clip_name || clip.clip_id;
+      try {
+        if (!clip.representative_frame_index) throw new Error('No analyzed frame available. Use Previous/Next to continue.');
+        const loaded = new Promise((resolve, reject) => {
+          previewImage.onload = resolve;
+          previewImage.onerror = () => reject(new Error('Preview unavailable. Use Previous/Next to continue.'));
+        });
+        previewImage.src = `/api/clips/${encodeURIComponent(clip.clip_id)}/frames/${clip.representative_frame_index}`;
+        const [data] = await Promise.all([api(`/api/clips/${encodeURIComponent(clip.clip_id)}`, {cache:'no-store'}), loaded]);
+        if (generation !== previewGeneration) return;
+        if (!data.success) throw new Error(data.error || 'Could not load saved review');
+        displaySourceReview(data, clip);
+        previewImage.style.visibility = 'visible';
+        previewReady = true;
+      } catch (error) {
+        if (generation === previewGeneration) previewStatus.textContent = error.message;
+      } finally {
+        if (generation === previewGeneration) lockSourcePreview(false);
+      }
+    }
+
+    async function saveSourceReview(field, value) {
+      if (previewBusy || !previewReady || previewIndex < 0) return;
+      const clip = previewQueue[previewIndex], generation = previewGeneration;
+      lockSourcePreview(true);
+      previewStatus.textContent = 'Saving…';
+      try {
+        const result = await api(`/api/clips/${encodeURIComponent(clip.clip_id)}/corrections`, {
+          method:'POST', body:JSON.stringify({entity_type:'clip', entity_uuid:clip.clip_id,
+            field_path:field, new_value:value, author:'control_panel', reason:'source preview review'})});
+        if (!result.success) throw new Error(result.error || 'Save failed');
+        const data = await api(`/api/clips/${encodeURIComponent(clip.clip_id)}`, {cache:'no-store'});
+        if (!data.success || readCorrectionValue(data.corrections, 'clip', clip.clip_id, field) !== value) {
+          throw new Error('Saved review could not be verified; retry before continuing.');
+        }
+        clip.user_selection = readCorrectionValue(data.corrections, 'clip', clip.clip_id, 'user.selection') || 'Unreviewed';
+        const listedClip = state.review.clipList?.clips?.find(item => item.clip_id === clip.clip_id);
+        if (listedClip) listedClip.user_selection = clip.user_selection;
+        renderReviewBin();
+        if (generation !== previewGeneration) return;
+        displaySourceReview(data, clip);
+        lockSourcePreview(false);
+        if (field === 'user.selection') {
+          if (!matchesSourceSelection(clip)) {
+            previewQueue.splice(previewIndex, 1);
+            if (previewQueue.length) await showSourcePreview(Math.min(previewIndex, previewQueue.length - 1));
+            else sourcePreview.close();
+          } else if (value !== 'Unreviewed' && previewIndex + 1 < previewQueue.length) {
+            await showSourcePreview(previewIndex + 1);
+          }
+        }
+      } catch (error) {
+        if (generation === previewGeneration) previewStatus.textContent = 'Save failed: ' + error.message;
+      } finally {
+        if (generation === previewGeneration) lockSourcePreview(false);
+      }
+    }
+
+    sourcePreview.querySelector('[data-preview-close]').onclick = () => sourcePreview.close();
+    sourcePreview.addEventListener('close', () => {
+      ++previewGeneration;
+      previewReady = false;
+      lockSourcePreview(false);
+      renderReviewBin();
+    });
+    sourcePreview.addEventListener('click', event => {
+      const button = event.target.closest('button');
+      if (!button) return;
+      if (button.dataset.previewStep) showSourcePreview(previewIndex + Number(button.dataset.previewStep));
+      if (button.dataset.previewSelection) saveSourceReview('user.selection', button.dataset.previewSelection);
+      if (button.dataset.previewRating != null) saveSourceReview('user.rating', Number(button.dataset.previewRating));
+    });
+    sourcePreview.addEventListener('keydown', event => {
+      if (event.target.matches('input,textarea,select') || event.ctrlKey || event.metaKey || event.altKey) return;
+      const actions = {
+        ArrowLeft: () => showSourcePreview(previewIndex - 1),
+        ArrowRight: () => showSourcePreview(previewIndex + 1),
+        i: () => saveSourceReview('user.selection', 'Include'),
+        x: () => saveSourceReview('user.selection', 'Exclude'),
+        u: () => saveSourceReview('user.selection', 'Unreviewed'),
+      };
+      const action = actions[event.key] || actions[event.key.toLowerCase()];
+      if (action) { event.preventDefault(); event.stopPropagation(); if (!event.repeat) action(); }
+    });
+    $('reviewBinGrid').addEventListener('click', event => {
+      const button = event.target.closest('[data-source-preview]');
+      if (!button) return;
+      event.stopImmediatePropagation();
+      previewQueue = filteredClips().slice();
+      sourcePreview.showModal();
+      showSourcePreview(previewQueue.findIndex(clip => clip.clip_id === button.dataset.sourcePreview));
+    }, true);
+
     function filteredClips() {
       const data = state.review.clipList;
       if (!data || !data.clips) return [];
       const binFilter = state.review.binFilter || '';
-      return data.clips.filter(c => !binFilter || c.bin_path === binFilter);
+      return data.clips.filter(c => (!binFilter || c.bin_path === binFilter) && matchesSourceSelection(c));
     }
 
     function renderReviewBin() {
@@ -8850,8 +9003,8 @@ HTML = r"""<!doctype html>
       }
       const clips = filteredClips();
       if (!clips.length) {
-        if (state.review.binFilter) {
-          if (summary) summary.textContent = `No analyzed clips in bin "${state.review.binFilter}".`;
+        if (state.review.binFilter || sourceSelectionFilter !== 'all') {
+          if (summary) summary.textContent = 'No analyzed clips match these filters.';
           if (grid) grid.innerHTML = '';
         } else {
           if (summary) summary.textContent = 'Nothing analyzed yet.';
@@ -8868,8 +9021,8 @@ HTML = r"""<!doctype html>
       Array.from(selected).forEach(id => { if (!visibleIds.has(id)) selected.delete(id); });
       if (summary) {
         const total = data.clips.length;
-        const base = state.review.binFilter
-          ? `${clips.length} of ${total} analyzed clip${total === 1 ? '' : 's'} · bin: ${state.review.binFilter}`
+        const base = state.review.binFilter || sourceSelectionFilter !== 'all'
+          ? `${clips.length} of ${total} analyzed clip${total === 1 ? '' : 's'}${state.review.binFilter ? ' · bin: ' + state.review.binFilter : ''}`
           : `${total} analyzed clip${total === 1 ? '' : 's'} in this project\u2019s analysis root.`;
         if (selected.size > 0) {
           summary.innerHTML = `<span>${escapeHtml(base)}</span>
@@ -8901,8 +9054,9 @@ HTML = r"""<!doctype html>
               <span class="select-box">${isSelected ? '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="3" stroke-linecap="round" stroke-linejoin="round"><polyline points="20 6 9 17 4 12"></polyline></svg>' : ''}</span>
             </button>
             ${thumb}
+            <button type="button" class="secondary" data-source-preview="${escapeHtml(clip.clip_id || '')}">Enlarge / review</button>
             <div class="review-clip-card-name">${escapeHtml(clip.clip_name || '')}</div>
-            <div class="review-clip-card-meta"><span>${dur}</span><span>${shots}</span>${primaryUse}${chip}</div>
+            <div class="review-clip-card-meta"><span>${dur}</span><span>${shots}</span>${primaryUse}${chip}<span class="review-chip">${escapeHtml(clip.user_selection || 'Unreviewed')}</span></div>
             ${clip.clip_summary_oneliner ? `<div class="review-clip-card-oneliner">${escapeHtml(clip.clip_summary_oneliner)}</div>` : ''}
           </div>`;
         }).join('');
@@ -11481,6 +11635,7 @@ HTML = r"""<!doctype html>
       openClipDetail(card.dataset.clipId).catch(alertError);
     });
     $('reviewBinGrid').addEventListener('keydown', event => {
+      if (event.target.closest('[data-source-preview]')) return;
       if (event.key !== 'Enter' && event.key !== ' ') return;
       const card = event.target.closest('.review-clip-card');
       if (card && card.dataset.clipId) {
@@ -11886,6 +12041,10 @@ HTML = r"""<!doctype html>
       const q = $('reviewSearchInput').value.trim();
       if (q) runReviewSearch(q).catch(alertError);
     });
+    $('sourceSelectionFilter').addEventListener('change', event => {
+      sourceSelectionFilter = event.target.value;
+      renderReviewBin();
+    });
     // Bin dropdown.
     $('reviewBinFilter').addEventListener('change', event => {
       state.review.binFilter = event.target.value || '';
@@ -13433,7 +13592,10 @@ def _v2_clip_summary_card(clip_slug: str, clip_dir: str, report: Dict[str, Any])
     if not isinstance(oneliner, str) or not oneliner:
         oneliner = summary[:140] + ("…" if len(summary) > 140 else "")
     rep_index = _v2_pick_representative_frame_index(report)
+    corrections = _v2_read_corrections_for_dir(clip_dir).get("current", {})
+    selection = corrections.get(f"clip:{clip_block.get('clip_id')}:user.selection", {}).get("value", "Unreviewed")
     return {
+        "user_selection": selection,
         "clip_id": clip_block.get("clip_id"),
         "clip_slug": clip_slug,
         "clip_dir": clip_dir,
@@ -13938,6 +14100,12 @@ def apply_clip_correction(project_root: str, clip_id: str, body: Dict[str, Any])
     clip_dir = _v2_find_clip_dir(project_root, clip_id)
     if not clip_dir:
         return {"success": False, "error": f"No analyzed clip found for id={clip_id}"}
+    field_path = body.get("field_path") or body.get("fieldPath")
+    value = body.get("new_value") if "new_value" in body else body.get("newValue", body.get("value"))
+    if field_path == "user.selection" and value not in ("Include", "Exclude", "Unreviewed"):
+        return {"success": False, "error": "Selection must be Include, Exclude, or Unreviewed"}
+    if field_path == "user.rating" and (type(value) is not int or not 0 <= value <= 5):
+        return {"success": False, "error": "Rating must be an integer from 0 to 5"}
     from src.server import _v2_update_field
     entity_type = body.get("entity_type") or body.get("entityType") or "shot"
     params: Dict[str, Any] = dict(body)

package/src/granular/common.py

@@ -87,7 +87,7 @@ if not logging.getLogger().handlers:
         handlers=[logging.StreamHandler()],
     )
 
-VERSION = "3.2.2"
+VERSION = "3.4.0"
 logger = logging.getLogger("davinci-resolve-mcp")
 logger.info(f"Starting DaVinci Resolve MCP Server v{VERSION}")
 logger.info(f"Detected platform: {get_platform()}")

package/src/granular/resolve_control.py

@@ -1,6 +1,8 @@
 """Resolve control resources, inspection helpers, and app-level tools."""
 
 from src.granular.common import *  # noqa: F401,F403
+import os
+from src.utils import typed_api_search
 
 resolve = ResolveProxy()
 
@@ -719,3 +721,48 @@ def export_user_preferences_preset(preset_name: str, export_path: str) -> Dict[s
         return missing
     result = resolve.ExportUserPreferencesPreset(preset_name, export_path)
     return {"success": bool(result), "preset_name": preset_name, "export_path": export_path}
+
+
+_PROJECT_DIR = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+
+@mcp.tool(annotations=READ_ONLY_TOOL)
+def search_resolve_api(pattern: str, kind: str = "all", limit: int = 50) -> Dict[str, Any]:
+    """Search the shipped Resolve 21.1 typed API stub. Needs no connection.
+
+    `api_truth` answers what is broken; this answers what exists. Each hit also
+    reports whether THIS server references the method and in which files, so a
+    search doubles as a parity check.
+
+    Args:
+        pattern: Case-insensitive regular expression, e.g. "marker" or "(Get|Set)Setting".
+        kind: 'all' (default), 'methods', or 'options' for TypedDicts only.
+        limit: Maximum results per section (capped at 200).
+    """
+    try:
+        return typed_api_search.search(_PROJECT_DIR, pattern, kind=kind, limit=limit)
+    except typed_api_search.TypedApiError as exc:
+        return {"error": str(exc)}
+
+
+@mcp.tool(annotations=READ_ONLY_TOOL)
+def describe_resolve_api(symbol: str) -> Dict[str, Any]:
+    """Full typed detail for one Resolve API symbol. Needs no connection.
+
+    Args:
+        symbol: 'Class.Method' (e.g. "Project.GetName"), a bare method name when
+            it is unambiguous, or a TypedDict name (e.g. "RenderSettings").
+    """
+    try:
+        return typed_api_search.describe(_PROJECT_DIR, symbol)
+    except typed_api_search.TypedApiError as exc:
+        return {"error": str(exc)}
+
+
+@mcp.tool(annotations=READ_ONLY_TOOL)
+def get_resolve_api_surface() -> Dict[str, Any]:
+    """Counts and object list for the shipped typed stub. Needs no connection."""
+    try:
+        return typed_api_search.summary(_PROJECT_DIR)
+    except typed_api_search.TypedApiError as exc:
+        return {"error": str(exc)}

package/src/resolve_mcp_server.py

@@ -34,7 +34,7 @@ from src.utils.update_check import start_background_update_check
 if __name__ == "__main__":
     try:
         start_background_update_check(VERSION, project_dir, logger)
-        logger.info(f"Starting DaVinci Resolve MCP Server v{VERSION} (384 granular tools)")
+        logger.info(f"Starting DaVinci Resolve MCP Server v{VERSION} (387 granular tools)")
         run_fastmcp_stdio(mcp)
     except KeyboardInterrupt:
         logger.info("Server shutdown requested")

package/src/server.py

@@ -11,7 +11,7 @@ Usage:
     python src/server.py --full       # Start the 377-tool granular server instead
 """
 
-VERSION = "3.2.2"
+VERSION = "3.4.0"
 
 import base64
 import os
@@ -52,6 +52,7 @@ from src.utils.resolve211_edits import validate_edit_options, validate_transitio
 
 # Platform-specific Resolve paths
 from src.utils.cdl import normalize_cdl_payload
+from src.utils import typed_api_search
 from src.utils import lut_files
 from src.utils import resolve_writes as _resolve_writes
 from src.utils.mcp_stdio import run_fastmcp_stdio
@@ -16652,6 +16653,15 @@ def resolve_control(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
       set_keyframe_mode(mode) -> {success}
       quit() -> {success}
       get_fairlight_presets() -> {presets}
+      search_api(pattern, kind?, limit?) -> {methods, option_types, total_matches}
+        — regex over the shipped Resolve 21.1 typed stub. Each hit says whether
+          THIS server references the method, and where, so it doubles as a
+          parity check. kind: 'all' (default) | 'methods' | 'options'.
+          No connection needed.
+      describe_api(symbol) -> {signatures, stub_line, description, source_files}
+        — one 'Class.Method' or one TypedDict name. No connection needed.
+      api_surface() -> {methods, option_types, option_fields, objects}
+        — what the shipped stub contains. No connection needed.
       set_high_priority() -> {success}
       disable_background_tasks_for_current_session() -> {success}  — Resolve 21+
       list_user_preferences_presets() -> {presets}  — Resolve 21.0.4+
@@ -16706,7 +16716,24 @@ def resolve_control(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
     # that property is worth keeping: it is the one call that still answers when
     # Resolve is down or unreachable. So the live build is used only if one is
     # ALREADY connected, or if the caller names it. Never connect for this.
-    if action == "api_truth":
+    if action == "search_api":
+        try:
+            return typed_api_search.search(
+                project_dir, p.get("pattern"),
+                kind=p.get("kind", "all"), limit=p.get("limit", 50))
+        except typed_api_search.TypedApiError as exc:
+            return _err(str(exc), code="TYPED_API_QUERY", category="invalid_input")
+    elif action == "describe_api":
+        try:
+            return typed_api_search.describe(project_dir, p.get("symbol"))
+        except typed_api_search.TypedApiError as exc:
+            return _err(str(exc), code="TYPED_API_QUERY", category="invalid_input")
+    elif action == "api_surface":
+        try:
+            return typed_api_search.summary(project_dir)
+        except typed_api_search.TypedApiError as exc:
+            return _err(str(exc), code="TYPED_API_QUERY", category="invalid_input")
+    elif action == "api_truth":
         facts = lookup_api_truth(p.get("query"))
         live_version = p.get("resolve_version")
         if not live_version and resolve is not None:
@@ -17139,7 +17166,7 @@ def resolve_control(action: str, params: Optional[Dict[str, Any]] = None) -> Dic
         if err:
             return _err(err)
         return {"success": bool(r.ExportUserPreferencesPreset(clean["name"], clean["path"]))}
-    return _unknown(action, ["is_studio","get_keyboard_presets","get_current_keyboard_preset","launch","runtime_mode","get_version","api_truth","check_version_support","verification_stats","report_issue","job_status","list_jobs","get_execution_trace","get_execution","list_recent_executions","begin_execution","end_execution","export_execution_report","clear_executions","inspect_operation","list_lifecycle_hooks","mcp_update_status","set_mcp_update_policy","ignore_mcp_update","snooze_mcp_update","clear_mcp_update_preferences","get_page","open_page","get_keyframe_mode","set_keyframe_mode","quit","get_fairlight_presets","set_high_priority","disable_background_tasks_for_current_session","list_user_preferences_presets","save_user_preferences_preset","load_user_preferences_preset","delete_user_preferences_preset","import_user_preferences_preset","export_user_preferences_preset","open_control_panel","control_panel_status","close_control_panel","save_state","restore_state"])
+    return _unknown(action, ["is_studio","get_keyboard_presets","get_current_keyboard_preset","launch","runtime_mode","get_version","search_api","describe_api","api_surface","api_truth","check_version_support","verification_stats","report_issue","job_status","list_jobs","get_execution_trace","get_execution","list_recent_executions","begin_execution","end_execution","export_execution_report","clear_executions","inspect_operation","list_lifecycle_hooks","mcp_update_status","set_mcp_update_policy","ignore_mcp_update","snooze_mcp_update","clear_mcp_update_preferences","get_page","open_page","get_keyframe_mode","set_keyframe_mode","quit","get_fairlight_presets","set_high_priority","disable_background_tasks_for_current_session","list_user_preferences_presets","save_user_preferences_preset","load_user_preferences_preset","delete_user_preferences_preset","import_user_preferences_preset","export_user_preferences_preset","open_control_panel","control_panel_status","close_control_panel","save_state","restore_state"])
 
 
 # ─── V2 C4: Per-field corrections with provenance + changelog ────────────────

package/src/utils/typed_api_search.py

@@ -0,0 +1,260 @@
+"""Query the shipped Resolve 21.1 typed stub from inside the server.
+
+PR #205 landed Blackmagic's `DaVinciResolveScript.pyi` in `docs/reference/`, and
+`scripts/audit_typed_api.py` can turn it into a full inventory — but only from a
+shell. An agent talking to this server had no way to ask what the native API
+contains. `resolve_control api_truth` answers "what is broken"; nothing answered
+"what exists".
+
+The official Blackmagic MCP exposes `search_scripting_api` for this. This is the
+equivalent, with one addition that matters more here: each result says whether
+**this server** references the method, and where. That turns a lookup into a
+parity check — "does the native API have it, and do we wrap it?" — which is the
+question that drove the whole 21.1 audit.
+
+Parsing is `ast`-based and reuses the same shapes as the audit script. Source
+references are executable syntax only: a method named in a docstring or comment
+is not counted as coverage.
+"""
+
+import ast
+import os
+import re
+from functools import lru_cache
+from typing import Any, Dict, List, Optional
+
+STUB_RELATIVE = os.path.join("docs", "reference", "DaVinciResolveScript.pyi")
+MAX_RESULTS = 200
+
+
+class TypedApiError(ValueError):
+    """The stub is missing, unparseable, or the query was unusable."""
+
+
+def stub_path(project_dir: str) -> str:
+    return os.path.join(project_dir, STUB_RELATIVE)
+
+
+@lru_cache(maxsize=4)
+def _inventory(path: str, mtime: float) -> Dict[str, Any]:
+    """Parse the stub into methods and TypedDicts. Cached on path plus mtime."""
+    with open(path, "r", encoding="utf-8") as handle:
+        text = handle.read()
+    methods: Dict[str, Any] = {}
+    option_types: Dict[str, Any] = {}
+    for cls in ast.parse(text).body:
+        if not isinstance(cls, ast.ClassDef):
+            continue
+        for node in cls.body:
+            if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)) and not node.name.startswith("_"):
+                signature = f"{node.name}({ast.unparse(node.args)})"
+                if node.returns is not None:
+                    signature += f" -> {ast.unparse(node.returns)}"
+                row = methods.setdefault(f"{cls.name}.{node.name}", {
+                    "object": cls.name,
+                    "method": node.name,
+                    "signatures": [],
+                    "stub_line": node.lineno,
+                    "description": ast.get_docstring(node),
+                })
+                row["signatures"].append(signature)
+        if any(ast.unparse(base).endswith("TypedDict") for base in cls.bases):
+            fields: Dict[str, Any] = {}
+            for index, node in enumerate(cls.body):
+                if isinstance(node, ast.AnnAssign) and isinstance(node.target, ast.Name):
+                    doc = None
+                    if index + 1 < len(cls.body):
+                        following = cls.body[index + 1]
+                        if (isinstance(following, ast.Expr)
+                                and isinstance(following.value, ast.Constant)
+                                and isinstance(following.value.value, str)):
+                            doc = following.value.value
+                    fields[node.target.id] = {"type": ast.unparse(node.annotation),
+                                              "stub_line": node.lineno,
+                                              "description": doc}
+            option_types[cls.name] = fields
+    if not methods:
+        raise TypedApiError("The typed stub contains no public class methods; refusing an empty inventory")
+    return {"methods": methods, "option_types": option_types}
+
+
+def load(project_dir: str) -> Dict[str, Any]:
+    path = stub_path(project_dir)
+    if not os.path.isfile(path):
+        raise TypedApiError(
+            f"Typed API stub not found at {STUB_RELATIVE}. It ships with this "
+            "repository; a source checkout is required for API search."
+        )
+    return _inventory(path, os.path.getmtime(path))
+
+
+@lru_cache(maxsize=4)
+def _wrapped_names(project_dir: str, fingerprint: str) -> Dict[str, List[str]]:
+    """Map native method name -> source files that actually call or read it.
+
+    Executable syntax only. A name that appears solely in a docstring or comment
+    is not coverage, and counting it as such is exactly the mistake this whole
+    audit existed to avoid.
+    """
+    found: Dict[str, set] = {}
+    src_root = os.path.join(project_dir, "src")
+    for current, _dirs, files in os.walk(src_root):
+        for filename in files:
+            if not filename.endswith(".py"):
+                continue
+            absolute = os.path.join(current, filename)
+            try:
+                with open(absolute, "r", encoding="utf-8", errors="replace") as handle:
+                    tree = ast.parse(handle.read())
+            except (OSError, SyntaxError):
+                continue
+            relative = os.path.relpath(absolute, project_dir).replace(os.sep, "/")
+            for node in ast.walk(tree):
+                name = None
+                if isinstance(node, ast.Attribute):
+                    name = node.attr
+                elif (isinstance(node, ast.Call) and isinstance(node.func, ast.Name)
+                      and node.func.id == "getattr" and len(node.args) > 1
+                      and isinstance(node.args[1], ast.Constant)
+                      and isinstance(node.args[1].value, str)):
+                    name = node.args[1].value
+                if name:
+                    found.setdefault(name, set()).add(relative)
+    return {name: sorted(paths) for name, paths in found.items()}
+
+
+def _source_fingerprint(project_dir: str) -> str:
+    """Cheap change detector for the source tree: newest mtime plus file count."""
+    newest = 0.0
+    count = 0
+    for current, _dirs, files in os.walk(os.path.join(project_dir, "src")):
+        for filename in files:
+            if filename.endswith(".py"):
+                count += 1
+                try:
+                    newest = max(newest, os.path.getmtime(os.path.join(current, filename)))
+                except OSError:
+                    pass
+    return f"{count}:{newest}"
+
+
+def search(project_dir: str, pattern: str, *, kind: str = "all",
+           limit: int = 50) -> Dict[str, Any]:
+    """Case-insensitive regex over method names, signatures, types and docs."""
+    if not isinstance(pattern, str) or not pattern.strip():
+        raise TypedApiError("pattern is required")
+    if kind not in ("all", "methods", "options"):
+        raise TypedApiError(f"kind must be all, methods or options, not {kind!r}")
+    try:
+        expression = re.compile(pattern, re.IGNORECASE)
+    except re.error as exc:
+        raise TypedApiError(f"pattern is not a valid regular expression: {exc}")
+    try:
+        limit = max(1, min(int(limit), MAX_RESULTS))
+    except (TypeError, ValueError):
+        raise TypedApiError("limit must be an integer")
+
+    inventory = load(project_dir)
+    wrapped = _wrapped_names(project_dir, _source_fingerprint(project_dir))
+
+    methods: List[Dict[str, Any]] = []
+    if kind in ("all", "methods"):
+        for key, row in sorted(inventory["methods"].items()):
+            haystack = " ".join([key] + row["signatures"] + [row["description"] or ""])
+            if not expression.search(haystack):
+                continue
+            references = wrapped.get(row["method"], [])
+            methods.append({
+                "symbol": key,
+                "object": row["object"],
+                "signatures": row["signatures"],
+                "stub_line": row["stub_line"],
+                "description": row["description"],
+                "referenced_in_this_server": bool(references),
+                "source_files": references[:5],
+            })
+
+    options: List[Dict[str, Any]] = []
+    if kind in ("all", "options"):
+        for type_name, fields in sorted(inventory["option_types"].items()):
+            matched = {
+                field: detail for field, detail in fields.items()
+                if expression.search(" ".join([type_name, field, detail["type"],
+                                               detail["description"] or ""]))
+            }
+            if expression.search(type_name):
+                matched = dict(fields)
+            if matched:
+                options.append({
+                    "type": type_name,
+                    "field_count": len(fields),
+                    "matched_fields": matched,
+                })
+
+    total = len(methods) + len(options)
+    return {
+        "pattern": pattern,
+        "kind": kind,
+        "total_matches": total,
+        "truncated": total > limit,
+        "methods": methods[:limit],
+        "option_types": options[:limit],
+        "stub": STUB_RELATIVE,
+        "note": ("referenced_in_this_server is executable syntax only — a name that "
+                 "appears solely in a docstring or comment is not counted."),
+    }
+
+
+def describe(project_dir: str, symbol: str) -> Dict[str, Any]:
+    """Full detail for one `Class.Method` or one TypedDict name."""
+    if not isinstance(symbol, str) or not symbol.strip():
+        raise TypedApiError("symbol is required")
+    inventory = load(project_dir)
+    key = symbol.strip()
+
+    if key in inventory["option_types"]:
+        fields = inventory["option_types"][key]
+        return {"symbol": key, "kind": "option_type", "field_count": len(fields),
+                "fields": fields, "stub": STUB_RELATIVE}
+
+    row = inventory["methods"].get(key)
+    if row is None:
+        candidates = sorted(k for k in inventory["methods"] if k.split(".", 1)[1] == key)
+        if len(candidates) == 1:
+            key, row = candidates[0], inventory["methods"][candidates[0]]
+        elif candidates:
+            raise TypedApiError(
+                f"{symbol!r} exists on more than one object: {', '.join(candidates)}. "
+                "Qualify it, e.g. 'Project.GetName'."
+            )
+        else:
+            raise TypedApiError(
+                f"{symbol!r} is not in the Resolve 21.1 typed stub. Use search to "
+                "find the right name."
+            )
+
+    wrapped = _wrapped_names(project_dir, _source_fingerprint(project_dir))
+    references = wrapped.get(row["method"], [])
+    return {
+        "symbol": key,
+        "kind": "method",
+        "object": row["object"],
+        "signatures": row["signatures"],
+        "stub_line": row["stub_line"],
+        "description": row["description"],
+        "referenced_in_this_server": bool(references),
+        "source_files": references,
+        "stub": STUB_RELATIVE,
+    }
+
+
+def summary(project_dir: str) -> Dict[str, Any]:
+    inventory = load(project_dir)
+    field_total = sum(len(fields) for fields in inventory["option_types"].values())
+    return {
+        "stub": STUB_RELATIVE,
+        "methods": len(inventory["methods"]),
+        "option_types": len(inventory["option_types"]),
+        "option_fields": field_total,
+        "objects": sorted({row["object"] for row in inventory["methods"].values()}),
+    }