Skip to content

docs: document video-digest + verify, sync stale video-digest render#81

Merged
VGonPa merged 3 commits into
developfrom
docs/digest-verify-sync
Jul 6, 2026
Merged

docs: document video-digest + verify, sync stale video-digest render#81
VGonPa merged 3 commits into
developfrom
docs/digest-verify-sync

Conversation

@VGonPa

@VGonPa VGonPa commented Jul 6, 2026

Copy link
Copy Markdown
Owner

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 check stays green.

What shipped that the docs missed

Changes

P0 — new commands documented

  • README.md §Commands: video-digest + verify rows.
  • README.md §Execution modes: added both to the LLM-stage list; noted they reuse [enrich].executor, worksheet tracks only (no api).
  • docs/tutorial.md §5 + docs/digest-video.md §Run it: inserted the video-digest step before generate (+ optional verify).
  • CLAUDE.md + ARCHITECTURE.md: video-digest and verify architecture bullets / stage sections; video-digest added to the items.json writers list + a verify-report.{json,md} artifact row.

P0 — corrected the stale ## Video digest render 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

  • Documented the additive digest field (ARCHITECTURE.md §x_video, CLAUDE.md).
  • Fixed the "both enrich tracks truncate" claim → full transcript + frame descriptions on the worksheet track (ARCHITECTURE.md §enrich, CLAUDE.md); noted frame descriptions feed enrich/topics (README.md §Layer 1).

P2

  • config.toml.example: [enrich].executor comment notes video-digest/verify also 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

VGonPa and others added 3 commits July 6, 2026 15:22
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 VGonPa merged commit 3b83bdc into develop Jul 6, 2026
1 check passed
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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant