# Kling documentation principles

Status: active working rule
Captured: 2026-03-29

## Purpose
Record the documentation principles that must govern future Kling API work so the project does not regress into:
- vague summaries without field detail
- hidden assumptions
- doc/live confusion
- paying to rediscover information already present in source material

---

# 1. Source before guess
If the Qingque-derived source-of-truth shows a field explicitly, document it by exact name before inventing or normalizing alternatives.

Meaning:
- prefer `image_url` if the source says `image_url`
- do not rewrite it mentally into `image` unless the source actually says that

---

# 2. Nested structures matter as much as endpoints
An endpoint-level summary is never enough if nested request fields decide whether the call works.

Meaning:
- `image_list[]`
- `multi_prompt[]`
- `video_list[]`
- `element_list[]`
- future `voice_list[]`
must be documented explicitly when present

---

# 3. Distinguish four kinds of truth
Every important field or pattern should be tracked as one of:
- doc-derived
- live-confirmed
- live-rejected
- hypothesis-only

Meaning:
- never collapse them into one fuzzy “I think this is right” state

---

# 4. Do not let successful create calls masquerade as semantic proof
A task can succeed while still failing the intended conditioning semantics.

Meaning:
- accepted payload != correct reference behavior
- create success != proven continuity support
- create success != proven voice binding support

Documentation must record that distinction.

---

# 5. Policies belong in writing, not in memory
If the pipeline decides:
- one scene = one clip
- single-scene ceiling = 15s
- no free probes
then those rules must live in policy docs, not just conversation history.

---

# 6. Blog notes are workflow hints, not contracts
Vendor blog material is useful for:
- direction
- workflow ideas
- quality hypotheses
- product positioning

But not sufficient for:
- exact payload naming
- exact request-body structure
- exact runtime guarantees

---

# 7. Extraction gaps must stay visible
Unknowns should be logged explicitly instead of being silently improvised away.

Meaning:
- if a field is missing from current extraction, add it to the gap log
- do not hide the gap by guessing and moving on

---

# 8. Documentation comes before live spend
If the source material likely already contains the answer, extract it first.
Only use live spend when documentation no longer reduces uncertainty enough.

---

# 9. The document set must stay navigable
As the document count grows, role clarity matters.
Every new document should fit one of these roles clearly:
- SOT/reference
- field-level detail
- implementation guidance
- policy/guardrail
- work planning
- external blog notes
- quick summary / navigation

---

# 10. The goal is not more docs — it is fewer mistakes
The project should not create documents for their own sake.
The purpose of documentation is to:
- reduce repeated mistakes
- reduce billable rediscovery
- tighten code alignment
- make future implementation decisions faster and safer