# Current Docs Map

This folder is the **current working documentation hub** for the Kling-based YouTube automation project.

## Maintenance rule
If you add, rename, remove, split, merge, or materially change any document in this folder, update this `README.md` in the same edit.

## Reading order
1. `kling-api-reference.md` — main integrated Kling API reference
2. `kling-api-series-3-spec.md` — Series 3.0 deep-dive from Qingque-linked spec
3. `youtube-automation-v1-kling-spec.md` — current v1 implementation-facing spec
4. `kling-current-state-summary.md` — shortest honest statement of what is completed, what Phase 3 means, and where approval is required
5. `kling-priority-todo.md` — priority-ordered closeout + Phase 3 entry checklist
6. `kling-docs-to-implementation-workboard.md` — operational bridge from closeout to the next approved verification slice
7. `kling-billable-create-guardrails.md` — mandatory spend/approval rules before any billable create
8. `youtube-automation-v1-implementation-tasks.md` — execution task breakdown
9. `youtube-automation-v1-build-decisions.md` — current build decisions
10. `youtube-automation-next-steps.md` — immediate next steps / remaining work
11. `kling-3-refresh-plan.md` — refresh planning document for 3.0 alignment

## Roles
### Canonical
- `kling-api-reference.md`
- `youtube-automation-v1-kling-spec.md`

### Current production-facing route scope
- `text2video` with `kling-v3`
- `image2video` with `kling-v3`
- `omni` with `kling-v3-omni`
- legacy/non-current families should be kept out of the main current-production layer even if they still exist in the wider docs corpus

### Current status / closeout
- `kling-current-state-summary.md`
- `kling-priority-todo.md`
- `kling-api-status.md`
- `kling-documentation-progress-board.md`

### Approval / operating rules
- `kling-billable-create-guardrails.md`
- `kling-api-field-status-register.md`
- `kling-pipeline-approved-payload-patterns.md`

### Operational planning
- `kling-docs-to-implementation-workboard.md`
- `youtube-automation-next-steps.md`
- `youtube-automation-v1-implementation-tasks.md`
- `youtube-automation-v1-build-decisions.md`

### Supporting deep-dive
- `kling-api-series-3-spec.md`
- `kling-qingque-full-api-reference.md`
- tier docs / blog notes / continuity notes

## Notes for LLM agents
- Prefer the **Canonical** docs first.
- Before any possible live create, read the **Current status / closeout** docs and the **Approval / operating rules** docs.
- Treat historical non-Omni evidence as reference context, not automatic permission for default routing.
- If this map becomes stale, it is a documentation bug.

## Latest verified update
- 2026-03-29 live smoke test confirmed JWT auth + Omni Video create-task success.
- `mode` enum corrected from `standard` to `std` (and `pro`).
- 2026-03-30 production policy docs refined:
  - production model pair is `kling-v3` + `kling-v3-omni`
  - `kling-video-o1` is no longer treated as the current 3.0 base production model
  - production image inputs should keep source-of-truth assets on our side and send actual raw-base64 image attachments by default
  - endpoint-specific image field shapes remain distinct: `image2video` uses top-level `image` / `image_tail`, Omni uses `image_list[].image_url`
  - important Omni SOT limits now called out explicitly for production use: without reference video, `reference images + reference elements <= 7`; with reference video, `<= 4`; `end_frame` is not supported when there are more than 2 images
  - current live interpretation of Omni `mode`: `pro` is modestly better than `std` overall, and currently has a practical edge for higher-resolution output
  - current operating policy: keep `std` as the default mode and escalate to `pro` only when quality/resolution or observed `std` weakness justifies it
  - verified outcomes now recorded explicitly: `text2video` with `kling-v3` = verified, `image2video` with `kling-v3` = verified, `omni` with `kling-v3-omni` = verified
  - verified production-facing image input methods now recorded explicitly: `image2video` uses top-level `image=<raw base64>` and Omni uses `image_list[].image_url=<raw base64>` with `type='first_frame'`
  - current docs are now being narrowed to production-relevant routes only; legacy/non-current families such as `reference2video` are no longer supposed to remain in the main production-facing layer
  - 7-second generation is also supported in the current scaffold because duration is validated as a configurable `3..15` second range, not a fixed 5-second contract

- 2026-03-29 extended endpoint smoke sequence (historical broader-platform evidence; not current-production routing guidance):
- text2video: FAIL
- image2video: FAIL
- reference2video: FAIL
- query_lists: PASS
- extend_video: FAIL

- 2026-03-29 deep contract probe completed. See current reference/spec for live findings.
- Phase 2 interpretation for implementation: keep code sync Omni-first.
- Historical non-Omni probe/pass notes remain reference evidence only. They are **not** the same as a synchronized default routing/model policy for the current scaffold.

- 2026-03-29 final verification round (historical broader-platform evidence):
- text2video_5s: PASS
- image2video_5s: PASS
- reference2video_5s: PASS
- omni_multishot_15s: FAIL
- callback files observed: 0

- 2026-03-29 retry round after valid image + multishot validator fix (historical broader-platform evidence):
- image2video_valid_image: PASS
- reference2video_valid_image: PASS
- omni_multishot_15s_retry: FAIL
- callback externally reachable configured: NO

- 2026-03-29 contract refinements from deeper live probing (historical broader-platform evidence):
- image2video_img256_png: failed (Image pixel is invalid)
- image2video_img512_png: submitted ()
- image2video_img512_jpg: submitted ()
- reference2video_img256_png: processing ()
- reference2video_img512_png: processing ()
- reference2video_img512_jpg: processing ()
- omni_multishot_probe_3: create/query succeeded after adding index fields to multi_prompt
- omni_multishot_probe_3: create/query succeeded after adding index fields to multi_prompt

## Key current docs added/updated in this closeout
- `kling-current-state-summary.md` — now states the completed closeout boundary, the expanded Phase 3 meaning, and the approval boundary before live work.
- `kling-priority-todo.md` — now defines Phase 3 as an approval-gated expanded verification phase with Omni and non-Omni tracks.
- `kling-docs-to-implementation-workboard.md` — now bridges closeout -> explicit approval -> first billable verification slice.
- `kling-api-status.md` — now summarizes completed phases, next-phase meaning, and exact approval triggers.

- `kling-v3-vs-omni-selection-guide-notes.md` — structured notes from Kling blog positioning VIDEO 3.0 vs VIDEO 3.0 Omni; includes claim summary, use-case split, and comparison against our live findings.
- `kling-video-3-0-omni-guide-notes.md` — notes from an Omni-focused blog article covering multimodal workflow, Character Identity 3.0, audio, AI Director, and production positioning.
- `kling-video-3-0-overview-guide-notes.md` — notes from a general Kling VIDEO 3.0 article covering unified training, AI Director, native audio, 15s duration, and multi-character positioning.
- `kling-video-3-0-director-mode-notes.md` — notes from a Director Mode article focused on multi-shot/automatic-vs-custom storyboard control and best-practice prompting.
- `kling-educational-videos-guide-notes.md` — notes from an education-focused Kling guide covering image-to-video, Motion Brush, Element Library, extension workflows, and API usage ideas.

- `kling-pipeline-action-items-from-blog-and-live-findings.md` — execution note translating external blog positioning plus our live API/continuity findings into concrete pipeline decisions and next actions.
- `kling-continuity-test-matrix.md` — structured experiment matrix for continuity, reference-strength, subject-type, environment-complexity, and motion-vector testing.
- 2026-03-29 update: Omni image-reference structure refined — current best-known live contract is `image_list[].image_url + type='first_frame'`; older `image_list[].image` assumption was rejected live.

- `kling-billable-create-guardrails.md` — mandatory spend-control rules: every create is billable, first success stops probing, and multi-create requires explicit pre-approval.
- `kling-qingque-full-api-reference.md` — fuller Qingque-based Series 3 API reference layer, promoting the captured Qingque document into an explicit doc-derived SOT reference with live annotations.
- `kling-video-reference-probe-mismatch-note.md` — corrective note documenting why the attempted `video_url=<base64 video>` continuation probe was not SOT-grounded and should not be treated as validated video-reference support.
- `kling-video-3-0-omni-audio-notes.md` — notes from an Omni audio/lip-sync blog article covering Elements 3.0 voice binding, voice tags, voice_list, multilingual dialogue, ambient sound, and claimed audio pricing.
- `kling-pipeline-scene-length-policy.md` — active pipeline rule: one scene should fit within one clip (up to 15s); cross-scene continuity should now be read through `video_list(remote url)` rather than degraded generated-last-frame chaining.
- `kling-api-field-level-audit-plan.md` — active plan for fully transcribing the Qingque-derived Series 3 API into field-level reference documentation, with doc/live status tagging per field.
- `kling-api-field-level-tier1.md` — Tier 1 field-level reference for Omni-Video, Text-to-Video, and Image-to-Video surfaces, now including exact preserved create rows plus Text/Image query single/list path/query/response rows, combined with current live findings.
- `kling-api-field-level-tier1-addendum-audio-elements.md` — addendum focusing on `video_list`, `element_list`, General Element APIs, audio/voice workflow hints, and pro-quality implications.
- `kling-api-field-level-tier2-elements.md` — Tier 2 field-level reference for General / Element APIs, now covering exact create/query/list/delete top-level rows, invocation examples, and the remaining path-semantics/nested-detail residuals.
- `kling-api-field-level-tier3-images.md` — Tier 3 field-level reference for Omni-Image and Image Generation surfaces, now covering exact create/query/list top-level rows plus residual capability-map/runtime support limits.
- `kling-api-field-status-register.md` — compact cross-reference of important field clusters with status labels (`doc-derived`, `live-confirmed`, `live-rejected`, `hypothesis-only`) to guide safe implementation.
- `kling-pipeline-approved-payload-patterns.md` — practical implementation guide for approved, cautionary, and disallowed payload patterns based on current SOT + live findings.
- `kling-field-extraction-gap-log.md` — explicit log of remaining field-level gaps across Tier 1/Tier 2/Tier 3, audio, and quality so Qingque extraction can proceed systematically.
- `kling-doc-set-map.md` — navigation guide mapping the whole Kling doc set by role: SOT/reference, field-level detail, implementation guidance, policy, and external blog notes.
- `kling-documentation-progress-board.md` — progress board showing which parts of the Kling documentation effort are complete enough, partially complete, or still incomplete.
- `kling-series3-pipeline-interpretation.md` — synthesis note explaining the likely production logic of the Series 3 stack: one-scene clips, frame anchors, video continuation, element assets, and asset-centric quality/continuity workflows.
- 2026-03-30 usage-guide clarification: current docs now explicitly distinguish which tool is for which purpose — Omni `image_list` for one-scene reference-guided clips, Omni `multi_shot` for one-clip storyboarded beats, `element_list` for reusable recurring identity/assets, and `video_list` continuation for cross-scene continuity.
- 2026-03-30 continuity clarification: historical `video-extend` remains visible in the broader docs corpus but is treated as legacy/non-current because preserved support notes restrict it to older video generations.
- 2026-03-31 continuity implementation clarification: current doc-visible scene continuity should be read through Omni `video_list`, not Video Character Elements; `video_list` remains URL-shaped at the visible SOT layer, and the most realistic current implementation for split-scene continuity is short-window chaining using the freshly returned Kling result URL from the previous clip.
- 2026-03-31 documentation closeout clarification: current Kling API documentation is now considered complete for the current implementation scope; remaining items are refinement-only (audio parity details, nested child-row cleanup, capability-map range interpretation, and later live verification), not implementation blockers.
- `kling-documentation-principles.md` — documentation rules for future Kling work: source before guess, nested fields matter, truth states must stay distinct, and documentation should reduce billable rediscovery.
- `kling-implementation-handoff.md` — practical handoff note for the next phase, summarizing current strategy, safe reference paths, required reading order, and the next documentation/code steps.
- `kling-next-raw-extraction-order.md` — explicit sequence for the next Qingque raw extraction passes, prioritizing Tier 1 create rows, then element schemas, then audio, then image-generation details.