# Editorial Media Authority

Load this reference for AI News, GitHub repository, technology explainer,
article-to-video or reference-video/remake work that selects public evidence,
plans editorial visuals or prepares publishable media.

This document owns source-backed editorial and media-role decisions. Run state,
template approval, channel voice overrides and universal release QA remain in
their existing authority files.

## Source Record Before Script

Before scripting a factual video, create `capture/source-record.json` and
`capture/visual-evidence-plan.md` inside the project directory.

- Establish original or official first-party sources for facts about the
  subject: original repositories, official sites, original publisher
  articles, official documentation, official release posts and
  publisher-owned assets. Record URL, retrieval date, intended claim and
  visual treatment.
- Every URL supplied by the user is source intake and must be attempted with
  Crawl4AI before ad hoc browser, metadata or manual fetch, including
  social/share URLs such as Facebook, X/Twitter, LinkedIn, Reddit, YouTube
  descriptions, article shares and short URLs.
- Save each Crawl4AI attempt to `capture/crawl4ai/<slug>.md` when it returns
  useful Markdown. Record `url`, `normalized_url`, `crawl_status`,
  `markdown_path`, `failure_reason`, `fallback_used` and any extracted hook in
  `capture/source-record.json` and `run-state.json`.
- If a social/share URL resolves only to a login wall, metadata, redirect shell
  or partial snippet, mark it as `supplementary_hook_only`; do not treat it as
  factual proof. Use the original/official first-party source for facts.
- When a third-party Facebook, TikTok, X repost or other social video is
  supplied only to extract transcript or content angle for an official/source
  video remake, treat it as internal research only. Do not mention the
  third-party platform, publisher, link, "no Facebook frames", "third-party",
  "reference video" or similar provenance wording in public narration,
  captions, source labels, storyboard-visible copy, publish caption or
  hashtags. Public source language should point only to the official/source
  asset actually used as proof.
- Only after the Crawl4AI attempt/fallback record may browser, API or manual
  metadata be used for the specific missing hook or claim.
- For repository videos, build a repo evidence digest before scripting:
  README title/hero text, short description, license, star/fork counts,
  recent activity, badges, feature headings, install/use sections, security
  caveats and adoption signals such as star history when they support a scene.
- For GitHub repositories, use GitHub APIs for repo metadata, README and file
  inventory first. If the repo metadata, README, topics or user prompt include
  a non-GitHub homepage, docs site, blog, changelog, release note or demo page,
  crawl that URL with Crawl4AI when available, save the Markdown to
  `capture/crawl4ai/<slug>.md`, and summarize only the useful claims into
  `capture/repo-evidence-digest.json`. Do not paste full crawled pages into
  the prompt when a digest can carry the needed facts.
- Before the first Crawl4AI crawl in a run, check Crawl4AI dependency readiness:
  verify whether the Python package
  imports and whether `crawl4ai-setup` or browser setup has been completed.
  If Crawl4AI is missing, install it with `python -m pip install -U crawl4ai`
  and run `crawl4ai-setup` or the package's current browser setup command
  before crawling. Record install/setup results in `run-state.json`.
- If Crawl4AI is unavailable or fails for a non-GitHub URL, record the failed
  crawl and fallback in `run-state.json` plus the source record, then use a
  browser/API fallback only for the specific missing claim.
- When the user supplies a repo/site/document plus related links, treat those
  links as source intake, not title/hashtag metadata. Read every supplied link
  for audience hook, promised benefit, pain point and points worth checking. If
  the video is about the original subject, do not display, cite, quote or name
  a supplementary publisher in public output.
- A supplementary hook may shape the opening question or benefit statement
  without mentioning the publisher, for example: "Xem va tai video VIP ma
  khong tra phi hang thang?" The next beat must ground that hook in what the
  original source actually describes, including mechanisms and caveats.
- The source record retains a research note identifying which link supplied
  the angle and which original/official source was used to verify or qualify
  it.
- For technical functionality, metrics, legal/safety guidance or claims that
  affect viewer action, verify against original/official material where
  available. A supplementary-only statement must stay attributed and must not
  be presented as confirmed product behavior.
- If supplementary material conflicts with the original/official source,
  prefer the original source; disclose a relevant difference when it matters
  to the story or omit the unsupported point.
- Before capturing a website, inspect the official README, repository asset
  folders and first-party demo/homepage for authored diagrams, UI screenshots
  or charts already chosen by the publisher. For GitHub repositories, inventory
  candidate image paths with the repository tree/contents APIs or README image
  references, then download only the necessary selected images for the planned
  scene claims. Do not bulk-download every image into a production project
  unless doing a separate audit/test outside the publishable project. Prefer
  the clearest official asset over a weaker new screenshot, and record its raw
  or embedded source URL.
- A source statement remains an attributed claim unless independently
  established; do not inflate marketing or README wording into a guarantee.
- If no defensible proof exists for a factual angle, stop or reframe the angle.
- For a reference video, identify the underlying official source or proceed
  only with a clearly original concept; never use its screen recording or
  extracted frames as public media.

## Media Truth Roles

Assign each evidence-bearing scene one visible role in the storyboard and
composition:

| Role | Meaning | Allowed examples |
| --- | --- | --- |
| `SOURCE PROOF` | Direct, attributable evidence from an official source | focused README excerpt, official UI/demo crop, official release note |
| `EXPLAINER` | Rebuilt visual that clarifies mechanism or impact | animated graph path, highlighted flow, query card, diff ripple |
| `ILLUSTRATION` | Mood or relatable setting, not evidence | abstract code overload, human-moment background motion |

Do not label a rebuilt UI, generated image or generic footage as
`SOURCE PROOF`. Illustration must never be presented as actual product
behavior.

Do not use a public `SOCIAL CONTEXT` scene for a video about an original
repo/site/article merely because a supplementary link was provided. Such a
scene is allowed only when the user explicitly asks the video to discuss the
post or public reaction itself.

Popularity indicators such as star counts, download counts or trend charts
may be shown only as `SOURCE PROOF / ADOPTION SIGNAL`, with retrieval date and
source visible or recorded. They demonstrate attention, not product quality,
correctness or fitness for a viewer's repository.

## Readable Evidence And Footage

- Use a focused crop or redesigned evidence callout containing only the important
  source detail. Never capture the full screen or full-desktop screenshot, as it
  makes the text/content unreadable in a 9:16 vertical layout. Crop screenshots
  tightly and sufficiently to show only the essential content clearly (e.g. specific
  code blocks, files, or repository stats).
- If a source screenshot becomes too small in the final frame, recapture or crop
  the important area and review it in a phone-like 9:16 frame or targeted
  HyperFrames check frame before using it as public proof.
- For public 9:16 proof, prefer one of these treatments: a tight source crop,
  a source-backed metric/code/release callout, or a rebuilt explainer labelled
  `EXPLAINER`. Do not use a full-page or full-desktop capture as the visible
  proof layer when the exact claim can be shown more clearly.
- A visible proof image must explain the scene claim. If viewers would not know
  why the screenshot is on screen, replace it with a more meaningful official
  image, release/changelog/history source, product screenshot, or labelled
  source-backed callout.
- Selected images must have a stated role and claim in the visual evidence
  plan. Keep only the small set needed for the storyboard; reject decorative,
  duplicate, low-information or unrelated repo images even when they are
  official files.
- Do not render QA/debug labels such as "focus crop", crop guides, red review
  boxes or internal inspection notes in public frames. Keep those only in QA
  artifacts outside the final composition.
- A crop retains an on-frame source label and a source record entry.
- When an official source already provides a legible explanatory banner or
  product screenshot, try it in the evidence plan before rebuilding the same
  idea or using a lower-information homepage capture.
- Use motion footage only when attributable official interaction materially
  demonstrates the subject better than a still crop.
- When embedding official/source video inside a 9:16 composition, make it large
  enough to be the primary readable proof. As a default, the visible video
  media area should occupy at least 78% of the usable content width or at least
  58% of the proof-panel height when the source aspect ratio allows it, while
  keeping at least 36px internal padding from panel borders and the template's
  outer safe zones. If that still looks small in a contact sheet, crop or scale
  the official video region rather than leaving a miniature full-frame view.
- For source video or image inserts inside a proof frame, decide the frame
  contract before animation: either the media is flush to the visible proof
  border and attribution/source text sits in a separate bottom/top strip, or
  the media has a deliberate even inset that is large enough to read as design.
  Do not combine a large proof panel with a smaller offset media rectangle
  unless the empty space carries a clear label/callout. Never let inserted
  media float upward/downward over headings, captions or badges because of
  Studio drag/resize offsets; production placement must be deterministic CSS,
  not `data-hf-studio-*`, `--hf-studio-*`, inline `translate`, inline
  `transform` or ad hoc `style` positioning.
- Do not fill scenes with generic motion to meet a quota; clarity outranks
  motion density.
- Never publish frames or screen recordings captured from a third-party
  reference video.

## Editorial Spine

For evidence-led technology shorts, prefer:

1. a specific audience-facing problem or promised-benefit hook, including one
   discovered from a supplied supplementary source;
2. the source-backed explanation of what the product actually does;
3. readable proof and an honest explainer of mechanism;
4. a practical impact beat;
5. one brief grounded human moment when it improves memorability;
6. a caveat or verification boundary;
7. the channel CTA and visible attribution.

For repo/tool/product explainers, include a practical audience/use-case beat:
who should use it, what problem it solves and one concrete workflow example
such as crawling a website, summarizing the result and turning it into source
material for a video script.

The human moment can be lightly playful, but it cannot replace proof or imply
a capability the source does not establish.

## QA And Handoff Evidence

Before describing a render as publish-ready, preserve:

- `SCRIPT.md`, `PUBLISH.md` with publish title, caption and exactly 5 hashtags,
  `STORYBOARD.md`, `voiceover.txt` and generated narration;
- `capture/source-record.json` and `capture/visual-evidence-plan.md`;
- selected approved template and rationale in `run-state.json`;
- measured narration timing used by `index.html`;
- rendered MP4 plus contact sheet or targeted proof frames;
- a QA report checking traceability, mobile crop readability, role labels,
  Vietnamese rendering, safe zones, synchronization, fallback disclosure and
  reference-video non-reuse;
- targeted 9:16 proof frames when any source screenshot, profile card, caption
  or callout could be too small, off-center or visually confused with a button;
- a final handoff note that reports retries or quality-changing fallbacks and
  repeats the post-ready title and exactly 5 hashtags after render completes.

If voice provider, factual confidence, evidence role or visual readability
must be weakened, block and obtain explicit approval before continuing.