docs: document video-digest + verify, sync stale video-digest render#81
Merged
Conversation
Cover the two enrichment features shipped on develop that the docs did not mention and correct sections the shipped code made stale. New commands (were undocumented — #78, #79/#80): - README §Commands: add `video-digest` (long-form per-video digest, worksheet flow, auto-snapshots on --apply) and `verify` (LLM-as-judge over enrichment outputs, --target, multi-worksheet --apply, report-only) rows. - README §Execution modes: add both to the LLM-stage list; note they reuse `[enrich].executor` and run worksheet tracks only (no `api`). - ARCHITECTURE: new `### video-digest` and `### verify` stage sections; add `video-digest` to the items.json writers + a `verify-report.{json,md}` row. - CLAUDE.md: add `video-digest` and `verify` architecture bullets. - docs/tutorial.md §5 + docs/digest-video.md: insert the `video-digest` step (worksheet → --apply) before `generate`; optional `verify` step. - config.toml.example: note `[enrich].executor` is also read by both. - docs/troubleshooting.md: "no pending / worksheet" FAQ entry. Corrected stale docs (matched to shipped code): - Video digest render (#77): digest is now the section HEADLINE with the raw transcript + frames demoted into a collapsible <details> ("Frames + transcript" / "Frames y transcripción"); empty digest falls back to the old inline layout. Fixed docs/digest-video.md §What you get, README §Layer 1, ARCHITECTURE. - enrich video inputs (#75): worksheet track sends the FULL transcript + a video_frame_descriptions field; only the `api` track truncates. Corrected the "both tracks truncate" claim in ARCHITECTURE §enrich + CLAUDE.md. - Documented the additive `digest: str = ""` field on ContentSourceSuccess (ARCHITECTURE §x_video, CLAUDE.md). Docs only — no source/test changes. `poe check` stays green. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
CLAUDE.md §Git workflow said "This repo has only `main`", but the repo uses `develop` as the integration branch (origin/develop exists; recent PRs target it). Document the real convention: feature branch → PR to `develop`; `develop → main` only via PR, never a direct merge/push. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Review panel on #81 flagged additional lists that predate the shipped video-digest/verify stages. Reconcile every one with the code on develop. - ARCHITECTURE invariant #8 (destructive ops): add `video-digest --apply` (snapshots on apply, not on export); note `verify` is non-destructive. - ARCHITECTURE §Rubrics: complete the LLM-driven-stages list and add the `rubric-video-digest.md` + `rubric-verify.md` rows (7 rubrics ship, both exist on develop). - CONTRIBUTING §Safety: add `video-digest --apply` to the destructive-ops list; note verify is not destructive. - docs/troubleshooting "Do I need an API key?": reconcile with the new FAQ — video-digest/verify also run the keyless claude-code track and have NO api track. - docs/digest-video §What you get: make the <details> example byte-accurate — the transcript renders RAW (no `>`); only frame captions are blockquotes (generate.py:_video_digest_lines / _slide_embed_lines). - SKILL enriching-x-knowledge: description + body now drive the two new claude-code worksheet flows (video-digest, verify) end to end. Docs only. `poe check` stays green. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
VGonPa
added a commit
that referenced
this pull request
Jul 7, 2026
Integration merge bringing the verification-layer epic up to date with develop (docs-sync PR #81). Resolved README verify-row conflict by combining #81's phrasing (named worksheet file, executor-default note) with the umbrella's --write-verdicts/staleness-badge and --audit content. ARCHITECTURE.md and CLAUDE.md auto-merged as clean unions (verified: no duplicated verification sections, no content loss). Full gate green. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
VGonPa
added a commit
that referenced
this pull request
Jul 7, 2026
The #81/develop verify docs were written before --write-verdicts existed; unioned against the umbrella's badge docs they left two semantic clashes git could not flag. - ARCHITECTURE.md `### verify`: scope 'never mutates/snapshots' to the default report-only mode; add the opt-in --write-verdicts (mutate+snapshot) and --audit (verifier-audit) clauses the prose omitted; add `verify --write-verdicts` to the items.json 'Mutated by' column. - CLAUDE.md verify bullet: same scoping + --write-verdicts/--audit clause. Docs-only; full `poe check` green (1226 tests, 95% cov, all A/B). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Docs-only PR syncing the manual/reference docs to the enrichment features shipped on
develop. No source or test changes;uv run --extra dev poe checkstays green.What shipped that the docs missed
video-digest(PR feat(video-digest): xbrain video-digest step (long-form digest per video) #78, issue Long-form media digest: transcribe + summarize bookmarked videos (and podcasts) into the vault #44) — generates the long-form readabledigestper video from its transcript + frame descriptions; worksheet flow (--executor manual|claude-code,--apply), writesdata/video-digest-worksheet.json, auto-snapshots on apply.verify(PR feat(verify): xbrain verify — LLM-as-judge machinery for enrichment (PR-1 of #79) #80, issue Enrichment verification layer (LLM-as-judge evals for summary/digest/topics) #79) — LLM-as-judge over enrichment outputs (--target summary|digest|topics|all),--applyaccepts multiple worksheets (one per judge), writesdata/verify-report.{json,md}, report-only (never mutates the store).<details>("Frames + transcript" / "Frames y transcripción"); empty digest falls back to the old inline layout.video_frame_descriptionsfield; only theapitrack truncates toTRANSCRIPT_CHAR_LIMIT.digest: str = ""field onContentSourceSuccess.Changes
P0 — new commands documented
README.md§Commands:video-digest+verifyrows.README.md§Execution modes: added both to the LLM-stage list; noted they reuse[enrich].executor, worksheet tracks only (noapi).docs/tutorial.md§5 +docs/digest-video.md§Run it: inserted thevideo-digeststep beforegenerate(+ optionalverify).CLAUDE.md+ARCHITECTURE.md:video-digestandverifyarchitecture bullets / stage sections;video-digestadded to the items.json writers list + averify-report.{json,md}artifact row.P0 — corrected the stale
## Video digestrender docs (digest headline +<details>demotion + empty-digest fallback):docs/digest-video.md§What you get,README.md§Layer 1,ARCHITECTURE.md§Video digest section.P1
digestfield (ARCHITECTURE.md§x_video,CLAUDE.md).ARCHITECTURE.md§enrich,CLAUDE.md); noted frame descriptions feed enrich/topics (README.md§Layer 1).P2
config.toml.example:[enrich].executorcomment notesvideo-digest/verifyalso read it ([frames]untouched).docs/troubleshooting.md:video-digest/verify"no pending / worksheet" FAQ entry.Every claim was verified against the code on
develop(command flags, field names, file paths, i18n strings, snapshot labels).🤖 Generated with Claude Code