{
  "schemaVersion": "1",
  "revision": "22ce5d34dbcb5a78",
  "id": "codex-oracle-video-runbook",
  "slug": "oracle-video-runbook",
  "title": "Oracle video analysis runbook",
  "summary": "Published Gemini-through-Oracle video-analysis skill covering video discovery and filtering, short- and long-recording workflows, media receipts, reproducible prompts, browser upload commands, readiness probes, blocking execution and recovery, artifact…",
  "category": "Tools",
  "tags": [
    "oracle",
    "gemini",
    "video"
  ],
  "sources": [
    {
      "label": "Portable Codex workflow resources",
      "url": "https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle"
    }
  ],
  "sourceUnits": [
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/SKILL.md",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/SKILL.md#Oracle Video Pipeline",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/SKILL.md#Oracle Video Pipeline/Session-Learned Operating Contract",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/SKILL.md#Oracle Video Pipeline/Non-Negotiable Runtime Mode",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/SKILL.md#Oracle Video Pipeline/Model / Intelligence Boundary",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/SKILL.md#Oracle Video Pipeline/Model / Intelligence Boundary/Gemini readiness: UI sign-in is required, but cookie errors are not proof",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/SKILL.md#Oracle Video Pipeline/Model / Intelligence Boundary/Attached-video smoke test",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/SKILL.md#Oracle Video Pipeline/Two Paths",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/SKILL.md#Oracle Video Pipeline/Two Paths/Short path — quick clips, no pre-processing (DEFAULT for short screen captures)",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/SKILL.md#Oracle Video Pipeline/Two Paths/Long path — workshop recordings, multi-section talks",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/SKILL.md#Oracle Video Pipeline/Pipeline",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/SKILL.md#Oracle Video Pipeline/Pipeline/Step 1: Choose a slug",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/SKILL.md#Oracle Video Pipeline/Pipeline/Step 2: Prep the media + receipts",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/SKILL.md#Oracle Video Pipeline/Pipeline/Step 3: Write the analysis prompt",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/SKILL.md#Oracle Video Pipeline/Pipeline/Step 4: Analyze — upload the video to Gemini",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/SKILL.md#Oracle Video Pipeline/Pipeline/Step 5: Wait correctly",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/SKILL.md#Oracle Video Pipeline/Pipeline/Step 5.5: Clean up the Gemini tab",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/SKILL.md#Oracle Video Pipeline/Pipeline/Step 6 (long path): Omissions pass + reconcile + verify",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/SKILL.md#Oracle Video Pipeline/Pipeline/Step 7: Assemble + summarize",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/SKILL.md#Oracle Video Pipeline/Evidence Preservation (core rule)",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/SKILL.md#Oracle Video Pipeline/Gemini Video Failure Diagnosis Tree",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/SKILL.md#Oracle Video Pipeline/Troubleshooting",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/SKILL.md#Oracle Video Pipeline/Completion Checklist",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/skills/oracle-video/SKILL.md#Oracle Video Pipeline/References",
    "downloads/codex-power-user-workshop-2026-06-27.bundle"
  ],
  "collection": "codex",
  "categoryId": "tools",
  "wordCount": 4038,
  "url": "/topics/codex-oracle-video-runbook/",
  "markdownUrl": "/markdown/codex-oracle-video-runbook.md?raw=1&v=22ce5d34dbcb5a78",
  "jsonUrl": "/api/v1/documents/codex-oracle-video-runbook.json",
  "headings": [
    {
      "id": "video-research-operating-rules",
      "text": "Video Research Operating Rules",
      "level": 2
    },
    {
      "id": "non-negotiable-runtime-mode",
      "text": "Non-Negotiable Runtime Mode",
      "level": 2
    },
    {
      "id": "model-intelligence-boundary",
      "text": "Model / Intelligence Boundary",
      "level": 2
    },
    {
      "id": "gemini-readiness-ui-sign-in-is-required-but-cookie-errors-are-not-proof",
      "text": "Gemini readiness: UI sign-in is required, but cookie errors are not proof",
      "level": 3
    },
    {
      "id": "attached-video-smoke-test",
      "text": "Attached-video smoke test",
      "level": 3
    },
    {
      "id": "two-paths",
      "text": "Two Paths",
      "level": 2
    },
    {
      "id": "short-path-quick-clips-no-pre-processing-default-for-short-screen-captures",
      "text": "Short path — quick clips, no pre-processing (DEFAULT for short screen captures)",
      "level": 3
    },
    {
      "id": "long-path-workshop-recordings-multi-section-talks",
      "text": "Long path — workshop recordings, multi-section talks",
      "level": 3
    },
    {
      "id": "pipeline",
      "text": "Pipeline",
      "level": 2
    },
    {
      "id": "step-1-choose-a-slug",
      "text": "Step 1: Choose a slug",
      "level": 3
    },
    {
      "id": "step-2-prep-the-media-receipts",
      "text": "Step 2: Prep the media + receipts",
      "level": 3
    },
    {
      "id": "step-3-write-the-analysis-prompt",
      "text": "Step 3: Write the analysis prompt",
      "level": 3
    },
    {
      "id": "step-4-analyze-upload-the-video-to-gemini",
      "text": "Step 4: Analyze — upload the video to Gemini",
      "level": 3
    },
    {
      "id": "step-5-wait-correctly",
      "text": "Step 5: Wait correctly",
      "level": 3
    },
    {
      "id": "step-5-5-clean-up-the-gemini-tab",
      "text": "Step 5.5: Clean up the Gemini tab",
      "level": 3
    },
    {
      "id": "step-6-long-path-omissions-pass-reconcile-verify",
      "text": "Step 6 (long path): Omissions pass + reconcile + verify",
      "level": 3
    },
    {
      "id": "step-7-assemble-summarize",
      "text": "Step 7: Assemble + summarize",
      "level": 3
    },
    {
      "id": "evidence-preservation-core-rule",
      "text": "Evidence Preservation (core rule)",
      "level": 2
    },
    {
      "id": "gemini-video-failure-diagnosis-tree",
      "text": "Gemini Video Failure Diagnosis Tree",
      "level": 2
    },
    {
      "id": "troubleshooting",
      "text": "Troubleshooting",
      "level": 2
    },
    {
      "id": "completion-checklist",
      "text": "Completion Checklist",
      "level": 2
    },
    {
      "id": "references",
      "text": "References",
      "level": 2
    },
    {
      "id": "related-resources",
      "text": "Related resources",
      "level": 2
    }
  ],
  "markdown": "# Oracle video analysis runbook\n\nYou are a PIPELINE EXECUTOR. Your job is: prep media -> upload the video to Gemini via\n`mcp__oracle__consult` (browser engine) -> read the analysis -> verify it against\nevidence -> write local artifacts. Oracle/Gemini supplies the expensive multimodal\nanalysis; you own every local file, receipt, and verification.\n\nThis skill is the sibling of `oracle-packx`. Where `oracle-packx` bundles *code* and\nsends *text* to ChatGPT, `oracle-video` attaches a *video file* and sends it to\n*Gemini* (which can actually watch the footage). The full, validated process spec\nlives in [references/repeatable-video-followup-process.md](/topics/codex-video-evidence-process/);\nread it before a long run.\n\n## Video Research Operating Rules\n\nThis skill exists because video understanding must happen in Gemini. Do not route\nvideo analysis through Codex, ChatGPT, OpenAI API mode, or text-only summarization.\nThe local agent may search YouTube, download media, compress files, write prompts,\nbundle analyses, and produce final Markdown; the video-watching step is always Gemini\nthrough Oracle's browser engine.\n\nWhen the user asks for \"same pipeline\" or a repeatable YouTube research batch, apply these repeatable research rules:\n\n- Filter candidate videos by actual YouTube metadata (`upload_date`), not title text,\n  search ranking, or remembered publication dates.\n- If the user gives a cutoff such as \"after a chosen cutoff\", enforce\n  `upload_date >= CUTOFF_YYYYMMDD`. Reject older/stale videos even if they rank highly.\n- Exclude topic collisions explicitly. For example, \"Raycast\" should exclude\n  game-development raycasting; \"Codex\" should exclude unrelated OCR/library/tool names.\n- Exclude coupon, affiliate-code, auto-generated music/topic uploads, shorts-only junk,\n  and videos whose content is not actually about the requested product/workflow.\n- Download with current `yt-dlp`, Chrome cookies, and YouTube challenge support when\n  needed. A known-good command shape is `yt-dlp --cookies-from-browser chrome ...`.\n- Preserve source metadata in `queue.json` with `id`, `title`, `uploader`,\n  `upload_date`, `duration`, and `url`.\n- Space Gemini video starts by about five minutes for larger batches only after the\n  first attached-video probe passes and no unresolved run is pending, unless the user\n  explicitly asks for a different cadence.\n- Make prompts topic-specific. Never reuse Codex-specific prompt language for another\n  topic; parameterize the topic in batch runners and prompts.\n- After every Gemini run, save the analysis beside the chunk and verify the sentinel\n  before moving to consolidation.\n- After each successful Gemini run, close the Gemini tab that Oracle opened. Do not\n  leave the remote Mac mini with dozens of `gemini.google.com/app` tabs.\n\n## Non-Negotiable Runtime Mode\n\nVideo analysis MUST run through the browser engine using `~/.oracle/config.json`.\n\n- Every `mcp__oracle__consult` call MUST set `engine: \"browser\"`.\n- **Default model: `model: \"gemini-3-pro\"`** — Oracle drives Gemini's mode picker to\n  **3.5 Flash + Extended thinking**, the right balance of speed and reasoning for routine\n  video analysis. Any Gemini model with an attachment uses the DOM upload path (not\n  pasted text), so the video is attached either way.\n- **Heavy opt-in: `model: \"gemini-3-pro-deep-think\"`** — selects **3.1 Pro + Deep Think**\n  (\"Max parallel reasoning\"). Use this only when the user explicitly asks for the deepest\n  analysis; it is markedly slower. Do NOT use it as the default.\n- Deliver the video with `browserAttachments: \"always\"`. The file path in `files` must\n  be an absolute path on the invoking machine that Oracle can stream or hand to the\n  browser host. For direct remote-host execution, use a path valid on that host; for\n  remote Oracle service runs, preserve the client-side absolute path in receipts and\n  let Oracle stream the attachment to the remote service.\n- Never use `engine: \"api\"` for video. The API path cannot upload the browser video.\n  If a call reports `Missing OPENAI_API_KEY`, you accidentally used API mode — rebuild\n  in browser mode.\n- Do not pass ad hoc remote host/token/profile overrides. Let Oracle read\n  `~/.oracle/config.json`, which owns the remote browser endpoint (the host that has\n  Chrome + Google sign-in). CLI Oracle recovery path: `oracle --engine browser --model gemini-3-pro ...`\n  (add `--model gemini-3-pro-deep-think` only for the heavy Deep Think opt-in).\n- If the user mentions a remote Mac mini/TV/Gemini config, still do not hard-code a\n  host/token in prompts or calls. Use `~/.oracle/config.json`; it is the source of truth\n  for the remote browser and cookie-bearing Google session.\n- If an ownership/access dialog appears in Gemini (\"confirm that you own/can access\n  this content\"), treat it as a browser/UI blocker. Let the user click it if automation\n  cannot, then retry only the affected upload. Do not restart the whole batch.\n\n## Model / Intelligence Boundary\n\nThis skill analyzes video through Gemini in Oracle browser mode. Do not manage\nChatGPT's Intelligence pill here.\n\nCritical rules:\n\n- Do not set `browserThinkingTime: \"instant\"` for Gemini video analysis.\n- Do not use ChatGPT `Pro Extended` / `Instant` labels as Gemini readiness proof.\n- Use `model: \"gemini-3-pro\"` by default, or `model:\n  \"gemini-3-pro-deep-think\"` only for explicit heavy opt-in.\n- The Instant vs Pro Extended policy applies to ChatGPT only: Instant for\n  ChatGPT Create image / `imagine`; Pro Extended for ChatGPT non-image consults.\n\n### Gemini readiness: UI sign-in is required, but cookie errors are not proof\n\nGemini video upload requires the browser profile that Oracle drives to have a live\nsigned-in Gemini UI. However, a Gemini text-only probe is not authoritative for video\nreadiness. Text-only Gemini may use Oracle's HTTP/cookie path and fail because a\nGoogle cookie such as `__Secure-1PSIDTS` is missing, while the visible Gemini UI is\nsigned in and the attached-video DOM upload path still works.\n\nUse this readiness order:\n\n1. Confirm the run is routed to Gemini browser mode, not ChatGPT or API mode.\n2. Confirm the remote Gemini UI is visibly signed in.\n3. Run one tiny attached-video probe with `engine: \"browser\"`, `model:\n   \"gemini-3-pro\"`, `browserAttachments: \"always\"`, and an explicit sentinel.\n4. Treat the attached-video probe, not a text-only probe, as the video readiness proof.\n5. If the probe hits a UI blocker, classify it with the failure diagnosis tree below\n   before retrying or starting a batch.\n\nGemini may show a conditional **video upload consent** modal after a video is attached\nand send is attempted. The DOM may include `video-upload-consent-dialog` with text like\n\"A reminder about creating videos\" and actions `Cancel` / `Agree`. This is not a\nGoogle sign-out, quota limit, or upload failure. Automation may click only the visible\naction whose normalized label is exactly `Agree`. Never click `Cancel`, never click the\nfirst dialog button generically, and never treat this modal as permission to click\narbitrary dialog actions.\n\n### Attached-video smoke test\n\nBefore a large batch, prove the actual video path with a tiny local MP4/MOV probe.\n\nRequired proof:\n\n- request uses `engine: \"browser\"`;\n- request uses `model: \"gemini-3-pro\"` unless the user explicitly requested Deep Think;\n- request uses `browserAttachments: \"always\"`;\n- stored request/session metadata shows Gemini provider routing;\n- run log shows Gemini navigation and attachment upload completion;\n- final response contains the expected sentinel;\n- completed Gemini tab is closed after output is saved.\n\nA text-only Gemini success is not enough. A text-only Gemini failure is also not enough\nto declare the video path broken. The video path is proven only by an attached-video run\nor by inspected Gemini tab evidence showing the submitted video prompt and sentinel\nresponse.\n\n## Two Paths\n\nPick the path from the source length and structure (full decision rules in the\nreference doc).\n\n### Short path — quick clips, no pre-processing (DEFAULT for short screen captures)\n\nUse when the clip is short enough to upload and analyze in one pass (quick screen\nrecording, a couple-minute walkthrough, a bug repro, a design review clip).\n\n1. Copy/symlink the clip as the single chunk; keep the original immutable + record a\n   `sha256` receipt.\n2. Run ONE Gemini consult with the clip attached (see Step: Analyze).\n3. Verify the output (URLs/tools/claims supported by what's actually in the video).\n4. Write a compact deliverable: bug report, requirements note, design brief, or summary.\n\nDo NOT segment, chunk, or build a manifest for short clips. Skip straight to analysis.\n\n### Long path — workshop recordings, multi-section talks\n\nUse for long recordings (roughly 45+ min, real breaks, many sections). Segment with\nffmpeg, drop verified dead-space (never discard chat — carry it forward), analyze each\nchunk, run an omissions pass, extract keyframes, reconcile against evidence, then\nassemble a teammate/follow-up packet. Follow the reference doc step by step.\n\n## Pipeline\n\n### Step 1: Choose a slug\n\n3-5 hyphenated words (Oracle rejects anything outside that range), e.g.\n`workshop-chunk-02-analysis` or `bug-repro-video-followup`. Every prompt starts with\n`[{slug}]` on its own first line, then a blank line, then the prompt.\n\n### Step 2: Prep the media + receipts\n\n```bash\nRUN_DIR=runs/$(date +%Y-%m-%d)-{slug}        # one folder per video/video-set\nmkdir -p \"$RUN_DIR\"/{inputs,receipts,chunks}\ncp \"/abs/path/to/source.mp4\" \"$RUN_DIR/inputs/source.mp4\"\nshasum -a 256 \"$RUN_DIR/inputs/source.mp4\" > \"$RUN_DIR/inputs/source.sha256\"\nffprobe -hide_banner -show_format -show_streams -of json \\\n  \"$RUN_DIR/inputs/source.mp4\" > \"$RUN_DIR/receipts/ffprobe.source.json\"\n```\n\nFor the long path, segment/chunk per the reference doc and write `chunks/video-manifest.json`.\nFor the short path, the single clip is `chunks/01/chunk.mp4`.\n\n### Step 3: Write the analysis prompt\n\nSave the prompt to `chunks/NN/gemini-prompt.md` so the run is reproducible. Use the\n\"Gemini Chunk Analysis\" template from the reference doc. Always include the hard rules:\npreserve original timestamps, separate transcript/chat/visual/inference evidence, do\nnot invent tools/commands/URLs/files/speakers/labels, return both Markdown and fenced\nJSON, end with an `END_OF_VIDEO_ANALYSIS ...` sentinel. Write the exact expected\nsentinel beside the prompt, for example `chunks/NN/expected-sentinel.txt`, and verify\nagainst that file rather than guessing whether the run used slug-only or\n`run_key chunk_id` form.\n\n### Step 4: Analyze — upload the video to Gemini\n\nYou MUST execute this MCP tool call (one per chunk):\n\n```\nmcp__oracle__consult({\n  prompt: \"[{slug}]\\n\\n{contents of chunks/NN/gemini-prompt.md}\",\n  files: [\"/abs/path/RUN_DIR/chunks/NN/chunk.mp4\"],\n  engine: \"browser\",\n  model: \"gemini-3-pro\",          // default → Gemini 3.5 Flash + Extended thinking\n  browserAttachments: \"always\",\n  slug: \"{slug}\"\n})\n```\n\nFor the heavy Deep Think opt-in (only when explicitly requested), swap in\n`model: \"gemini-3-pro-deep-think\"` (→ 3.1 Pro + Deep Think).\n\nForbidden shapes: `engine: \"api\"`, omitted `engine`, no `browserAttachments`. If you\ndraft one of these, rebuild before invoking.\n\nFor batch CLI Oracle recovery, use the same browser mode explicitly:\n\n```bash\noracle \\\n  --engine browser \\\n  --model gemini-3-pro \\\n  --browser-attachments always \\\n  --browser-keep-browser \\\n  --prompt \"$(cat chunks/NN/gemini-prompt.md)\" \\\n  --file \"/abs/path/RUN_DIR/chunks/NN/chunk.mp4\" \\\n  --slug \"{topic}-batch-NN\" \\\n  --write-output \"chunks/NN/gemini-analysis.md\" \\\n  --verbose \\\n  --wait \\\n  --force\n```\n\nUse `--browser-keep-browser` only so the run can be inspected and recovered while it is\nactive. Once the run has saved output, close the Gemini tab (see Step 5.5).\n\nPersist the result yourself (the MCP return + output.log are truncated — the caller\nowns persistence):\n\n```text\nchunks/NN/gemini-run.log        # browser automation metadata / timing\nchunks/NN/gemini-result.json    # full response payload\nchunks/NN/gemini-analysis.md    # rendered analysis\n```\n\n### Step 5: Wait correctly\n\nGemini video runs are blocking. After a run starts, all local analysis, artifact writing\nbased on Gemini's answer, follow-up planning, and independent summarization MUST pause\nuntil Oracle/Gemini has fully completed and the local response has been read.\n\n- Never assume Oracle/Gemini timed out or failed based on elapsed time alone.\n- Never proceed independently while Oracle/Gemini is still processing, even if a wrapper\n  returns after 120s or any other local wait limit.\n- Reattach with `mcp__oracle__sessions({ id: \"{slug}\", detail: true })` or read\n  `~/.oracle/sessions/{slug}/output.log`; these checks are only for recovering the final\n  response, not for starting work while the run continues.\n- Keep waiting as long as Oracle/Gemini requires while the session is still processing.\n  There is no Codex-side timeout threshold that permits independent action.\n- Only call it failed on an explicit terminal error, a sign-in/quota/upload guard, or a\n  non-zero exit.\n\nHealthy wrapper completion looks like the run log ending with `Gemini browser response\nreceived (N chars)` and `Completed in Nms`. Recovered completion is also valid when the\nwrapper reports a send/ready error but tab inspection shows a submitted user turn and\nGemini response containing the exact expected sentinel. In that case, save the visible\nresponse, record the recovery in `gemini-run.log`, and do not rerun that chunk.\n\nFor newer Gemini DOM runs, successful submission may also be evident from the remote\nGemini tab even when an older Oracle wrapper reports a send/ready error. If a run says\n`Gemini send was not accepted` or `Gemini composer was not ready to send` after an\nattached-video attempt, inspect the Gemini tab before retrying: the submitted user turn\nand Gemini response may already exist. A valid sentinel in the visible Gemini response\nbeats the wrapper error; persist the response and fix/adjust the wrapper before\nbatching more chunks.\n\n### Step 5.5: Clean up the Gemini tab\n\nEvery successful Gemini video run should close the tab it opened on the remote browser.\nThis prevents the remote Mac mini/TV browser from accumulating dozens of Gemini tabs.\nCleanup happens only after extraction, not merely after the browser appears done.\n\nPreferred cleanup order:\n\n1. Record the Oracle session slug and, if available, its Chrome debug port/target in the\n   run log.\n2. Extract and persist every needed artifact from the Gemini response:\n   `gemini-result.json`, `gemini-analysis.md`, any machine JSON or\n   `gemini-analysis.extracted.json`, and the recovery note if the response came from\n   tab inspection rather than wrapper success.\n3. Verify `gemini-analysis.md` is non-empty and contains the exact\n   `expected-sentinel.txt` value.\n4. Close only the Gemini tab for that completed/extracted run.\n5. Leave the browser itself running if Oracle needs to reuse the signed-in profile.\n6. Do not close tabs for still-running uploads, still-generating responses, unresolved\n   wrapper errors, or tabs whose visible response has not yet been extracted.\n\nIf you write a batch script, make tab cleanup an explicit post-extraction step. The\nscript should not close the tab immediately after Oracle returns; it should first save\nthe full result, extract machine-readable content, verify the sentinel, then close the\nexact tab target for that run. If extraction fails, leave the tab open and record the\ntarget/port so the run can be recovered.\n\nWhen the run used `--browser-keep-browser`, use Oracle/browser tooling to close matching\ncompleted Gemini tabs rather than leaving them open. If you are in the Oracle repo, a\nworking inspection/cleanup shape is:\n\n```bash\npnpm tsx scripts/browser-tools.ts eval --port <port> '\n(() => {\n  const tabs = [...document.querySelectorAll(\"a\")];\n  return { href: location.href, title: document.title, text: document.body.innerText.slice(0, 500) };\n})()\n'\n```\n\nIf you need to operate on the configured remote Mac mini, run the same command through\nSSH using the repo-local Node path from that machine. Prefer closing the exact tab\ntarget via Chrome DevTools Protocol when possible; avoid killing Chrome or closing all\nGemini tabs blindly. If exact-target close is not available, list tabs first, identify\ncompleted `gemini.google.com/app` tabs by title/conversation state, and close only those.\n\n### Step 6 (long path): Omissions pass + reconcile + verify\n\nRe-attach the same chunk with the \"Omissions Pass\" prompt, then reconcile locally into\n`final-reconciled.md`/`.json`, and run the verification reports (coverage, hallucination,\ntimestamp, visual-claim). Keep every receipt next to the claim it supports. Details in\nthe reference doc.\n\n### Step 7: Assemble + summarize\n\nLong path: produce the `final/` packet (teammate guide, chapter index, resources, QA\nindex, exercises, keyframe manifest, instructor checklist). Short path: produce the one\ncompact deliverable. Summarize for the user, leading with the highest-value findings,\nand link the artifact paths.\n\n## Evidence Preservation (core rule)\n\n- Keep original media immutable; record a `sha256` receipt.\n- Preserve ORIGINAL recording timestamps when a source timeline exists.\n- Save every prompt, result, and run log next to the chunk.\n- Never claim a URL/tool/command/visual unless it is supported by transcript, chat,\n  carry-forward chat, a local path, or keyframe review.\n- Never discard chat from a removed/dead span — carry it forward.\n\n## Gemini Video Failure Diagnosis Tree\n\nStop new batch starts before using this tree. Diagnose the current run first.\n\n1. **Was a video attached?**\n   - No: this may be the text-only HTTP/cookie path. Do not use it as the only video\n     readiness result. Run a tiny attached-video probe.\n   - Yes: continue.\n2. **Was the run routed to Gemini browser mode?**\n   - If logs or metadata show ChatGPT navigation/upload, API mode, or missing\n     `browserConfig.provider: \"gemini\"`, stop. This is a routing bug. Do not treat the\n     result as valid video analysis.\n   - If Gemini browser routing is confirmed, continue.\n3. **Is there an explicit terminal guard?**\n   - `sign-in`: stop and have the remote browser signed into Gemini.\n   - `quota` or `rate-limit`: stop and wait/change account per user direction.\n   - `upload-warning`: stop and fix file size/type/count or chunk the media.\n   - No terminal guard: continue.\n4. **Did a text-only probe fail on missing Google cookies?**\n   - If the visible Gemini UI is signed in, do not diagnose sign-out from that alone.\n     Text-only probes can fail on HTTP/cookie requirements that attached-video DOM runs\n     do not need.\n   - Run or inspect an attached-video probe.\n5. **Did attached-video send fail with `Gemini send was not accepted`?**\n   - Inspect the Gemini tab before retrying.\n   - If `video-upload-consent-dialog` is visible, click only exact `Agree`, then wait\n     for the same prompt to submit.\n   - If the prompt and attachment still remain in the composer and no submitted user\n     turn exists, rerun only that chunk after fixing the blocker.\n   - If a submitted user turn or response exists, do not rerun until checking for the\n     sentinel.\n6. **Did the wrapper report `prompt-empty`?**\n   - Inspect the tab. `prompt-empty` can mean Gemini accepted the prompt and moved it\n     out of the composer.\n   - If the visible response contains the expected sentinel, persist it as success.\n   - If no submitted user turn and no response exist, treat it as a real send failure\n     and rerun only that chunk.\n7. **Are there stale Gemini tabs?**\n   - Do not close active uploads or generating responses.\n   - Generic empty Gemini tabs from failed diagnostics may be closed after inspection.\n   - Tabs with real conversation state must be checked for a saved response/sentinel\n     before closing.\n   - Close only the exact completed tab after output is saved.\n8. **Is the result valid?**\n   - Valid completion is either a successful wrapper log with response received, or\n     inspected Gemini tab evidence containing the expected sentinel and saved output.\n   - Anything else is unresolved; do not consolidate, summarize, or batch further.\n\n## Troubleshooting\n\n| Problem | Fix |\n|---------|-----|\n| Run log stops at `Sending prompt...`, no response; tab left with video attached | Stop batch starts. Inspect the Gemini tab before rerunning. Check for a visible video consent modal, explicit sign-in/quota/rate-limit/upload warning, submitted user turn, or sentinel response. Rerun only the affected chunk after the state is classified. |\n| `Gemini send was not accepted after 3 attempts` | Inspect the remote Gemini tab. If `video-upload-consent-dialog` is visible, click only the visible action whose normalized label is exactly `Agree`, then wait for the same prompt to submit. If the prompt remains in the composer with no submitted user turn, rerun only that chunk after fixing the blocker. If a response with the expected sentinel already exists, persist it as success. |\n| `Gemini composer was not ready to send` with `reason=prompt-empty` after an attached-video run | Inspect the tab before retrying. `prompt-empty` may be a wrapper false negative after Gemini accepted the prompt. If the prompt appears in a submitted user turn/page and the Gemini response contains the expected sentinel, save it as completed analysis and record recovery. If no user turn/response exists, rerun only that chunk after fixing send/modal handling. |\n| Text-only Gemini probe reports sign-in/cookie failure, but the visible Gemini app is signed in | Do not assume the video path is broken. Text-only probes can use Oracle's HTTP/cookie path and fail on missing `__Secure-1PSIDTS`; video attachments use the Gemini DOM upload path. Verify with a tiny real video attachment probe before deciding whether user sign-in is required. |\n| Text-only Gemini probe fails on missing `__Secure-1PSIDTS` | Do not diagnose video sign-out from this alone. Confirm visible Gemini UI state and run a tiny attached-video probe. |\n| Attached-video probe succeeds after text-only failure | Treat video DOM upload path as ready. Record both receipts so future agents do not revert to the false sign-out diagnosis. |\n| Wrapper failed but tab contains sentinel | Persist the visible Gemini response, save a recovery note in the run log, close the completed tab, and do not rerun that chunk. |\n| Log shows ChatGPT navigation or ChatGPT upload for a video | Stop. Treat this as a routing bug, not a valid analysis. Verify the stored request/metadata shows `browserConfig.provider: \"gemini\"` and rerun only after the provider guard tests pass. |\n| Many leftover `gemini.google.com/app` tabs with generic \"Google Gemini\" title | Those are usually runs that never produced a query/response (often diagnostic/sign-in attempts), or completed runs that were left open because `--browser-keep-browser` was used. Close completed/empty Gemini tabs after saving output. Tabs with a real auto-generated title + conversation id may have completed; verify output before closing. |\n| `Missing OPENAI_API_KEY` | The call used API mode. Retry with `engine: \"browser\"` + `model: \"gemini-3-pro\"` (default) or `gemini-3-pro-deep-think` (heavy). |\n| `sign-in` / `quota` / `rate-limit` / `upload-warning` guard | Stop. Sign the remote browser into Google (or wait out the limit), then resume. |\n| `video-upload-consent-dialog` / \"A reminder about creating videos\" appears | This is a video consent blocker, not sign-out. Click only exact `Agree`; never click `Cancel`, never click the first button generically, and never click `Confirm` for this dialog unless the DOM label is actually `Agree`. Continue the same run after acceptance. |\n| Ownership/access confirmation appears | Treat as a separate UI blocker. If automation cannot safely identify the explicit ownership/access confirmation action, ask the user to click it once, then continue or retry only the affected upload. Do not restart the whole batch. |\n| 120s timeout / no final answer yet | Reattach via `mcp__oracle__sessions` or `output.log`; do not proceed independently; keep waiting until Oracle/Gemini completes or reports a terminal failure. |\n| Large video upload | Oracle streams large attachments to the remote service before the run (`[remote] streaming large attachment before run`). Keep the file under the configured `maxFileSizeBytes` / remote limit, or chunk it. |\n| Truncated MCP return | Read `chunks/NN/gemini-result.json` that you persisted, not the MCP tail. |\n\n## Completion Checklist\n\n- [ ] Original media preserved + `sha256` receipt written.\n- [ ] Slug is 3-5 hyphenated words; prompt starts with `[{slug}]`.\n- [ ] Each Gemini call used `engine: \"browser\"`, `model: \"gemini-3-pro\"` (default 3.5 Flash + Extended; `gemini-3-pro-deep-think` only if explicitly requested), `browserAttachments: \"always\"`, absolute `files` path.\n- [ ] Remote browser confirmed signed into Gemini before batch runs.\n- [ ] A real attached-video probe has completed through Gemini before a large batch; do not rely only on a text-only Gemini probe.\n- [ ] Text-only Gemini probe results were not used as the sole video readiness proof.\n- [ ] First real attached-video probe result was saved before any batch fan-out.\n- [ ] Any `send not accepted`, `prompt-empty`, consent modal, sign-in, quota, rate-limit, or upload-warning state stopped new batch starts until classified.\n- [ ] Prompt, result JSON, and run log persisted per chunk.\n- [ ] Each run either reached `Gemini browser response received`, or a wrapper-error recovery was documented with submitted user turn + visible Gemini response + expected sentinel.\n- [ ] If `video-upload-consent-dialog` appeared, only the `Agree` action was clicked and the same submitted prompt was allowed to complete.\n- [ ] Stored session metadata/request shows `browserConfig.provider: \"gemini\"` for every video run.\n- [ ] Expected sentinel was written next to the prompt and checked exactly.\n- [ ] If the sentinel format used `run_key chunk_id`, verification did not look for slug-only form.\n- [ ] Run log contains `[gemini-web] Navigating to gemini.google.com...` and `Attachment upload complete in Gemini: <filename>`.\n- [ ] Run log does not show ChatGPT navigation/upload for the video attachment.\n- [ ] No local analysis, artifact synthesis, or final answer happened while Oracle/Gemini was still processing.\n- [ ] Completed Gemini tabs were closed after output was saved and verified; the remote\n      browser was not left with accumulated `gemini.google.com/app` tabs.\n- [ ] Scripted tab cleanup ran only after full extraction completed:\n      `gemini-result.json`, `gemini-analysis.md`, extracted JSON if expected, and exact\n      sentinel verification.\n- [ ] Outputs verified: no invented URLs/tools/commands; visual claims confirmed; original timestamps preserved.\n- [ ] Long path: omissions pass + reconciliation + verification reports done; `final/` packet assembled.\n- [ ] Short path: single compact deliverable written.\n- [ ] User summary leads with highest-value findings and links artifact paths.\n\n## References\n\n- [Repeatable video follow-up process](/topics/codex-video-evidence-process/) — full step-by-step spec, ffmpeg segmentation, prompt templates, verification, and final-packet layout.\n\n## Related resources\n\n- [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle)\n- [Resource directory and portable download](/topics/codex-resources/)"
}
