# Template Library Contract Use this reference when selecting, validating or promoting a reusable nAvid template set. For dedicated template authoring and `/navid-template` requests, load `template-creation.md` first, then use this file as the library contract. The library is operational data, not a gallery of unverified concepts. ## Path Resolution All paths in this document are relative to `NAVID_SKILL_ROOT` — the directory containing `SKILL.md`. See the **Skill Root Anchor** section in `SKILL.md`. When the agent reads, writes, lists or validates any template path, it must resolve from `NAVID_SKILL_ROOT`, never from the user's project directory or a hardcoded development path. ## Repository Layout The single index is `NAVID_SKILL_ROOT/templates/registry.json`. Template material is grouped by content domain, then by trust tier: ```text NAVID_SKILL_ROOT/ templates/ registry.json domains//candidate//manifest.json domains//approved//manifest.json portable//short/index.html portable//standard/index.html portable//extended/index.html fixtures/ai-news-tech-sample.json ``` The `portable/` subtree holds self-contained renderable sequences for each approved set. These files are bundled inside the skill package so they travel with any install (`npx navid-workflow install` or manual copy). Supported starting domains are `ai-news`, `developer-tools`, `security`, `robotics` and `product-tour`. A visual style belongs to an individual set; it does not replace the content-domain grouping. ## Tiers And Visibility - `candidate/` holds imported concepts and built sets still under review. - `approved/` holds sets that passed structural and visual QA and received explicit user approval. - Imported legacy or preview concepts always begin as `candidate` with `readiness: "needs-expansion"` and `status: "concept-import"`. - Candidate material is never a normal default or one of the three normal recommendations. It may be mentioned separately as experimental material. - Promotion is never automatic. A passing QA record makes a candidate eligible; the user must explicitly approve promotion. - A failed candidate remains in `candidate/` with `status: "needs-revision"` and concrete QA failures. ## Promotable Set Contract A renderable candidate must describe: - At least 12 module records: eight core narrative roles and at least four domain-specific supporting modules. - Core roles: `hook-headline`, `source-proof`, `context-card`, `feature-list`, one of `process-diagram` or `timeline`, `impact-risk`, `takeaway-source` and `cta-outro`. - At least two layout variants for `hook-headline`, `source-proof`, `feature-list`, `impact-risk`, and the chosen `process-diagram` or `timeline` role. - Three sequences named `short`, `standard` and `extended`, using the same sample story. Normal targets are 25-35, 40-60 and 60-90 seconds respectively. Sequences shorter than 55 seconds are preview/QA assets only; a completed public production must use or extend a sequence to satisfy the `55-180` second public-duration boundary in `../SKILL.md`. - Source-proof and screenshot rules, typography, safe-zone guidance, content domain, tags and style identity. - For TikTok-oriented output, `cta-outro` uses a compact horizontal profile-card as a reusable lower element; the scene area above it remains available for story-specific conclusion, CTA or source attribution. Do not require a full profile panel or unverified social metrics in a template set. The card must be content-fitted and centered; empty right-side pill tails, over-wide black backgrounds or off-center alignment fail template QA. - TikTok `cta-outro` QA must include deterministic follow interaction: pointer approach, button click feedback and a final `Following` state. - TikTok `cta-outro` metadata must define a `follow-click` SFX slot. Production renders use `templates/assets/sfx/follow-click.wav` or a documented approved replacement at the button-press frame; portable QA templates must preserve the slot and may use the packaged default SFX. - Prefer one reusable TikTok profile-card component contract across templates: stable markup/classes, local avatar and cursor slots, deterministic Follow-to-Following timing and the `follow-click` SFX slot. A standalone HTML fragment is synchronized only when its CSS, motion adapter and asset dependencies are versioned and consumed with it. The canonical component lives at `NAVID_SKILL_ROOT/templates/components/tiktok-profile-card/`; each portable sequence vendors byte-identical CSS and JavaScript under `components/` so it remains independently renderable. The shared synthetic evaluation story is `NAVID_SKILL_ROOT/templates/fixtures/ai-news-tech-sample.json`. It may demonstrate the set without claiming a real product announcement. ## QA And Generated Evidence For each sequence, render or provide a playable preview plus a full contact sheet. Store generated preview evidence outside the skill runtime at: ```text videos/template-library-preview// ``` QA must evaluate Vietnamese readability, source proof readability in 9:16, targeted proof frames for small screenshots, caption/subtitle placement and non-button styling, compact centered TikTok profile-card layout, caption/CTA/logo/source safe zones, layout variety, honest distinction between proof and illustration, and consistent pacing. Before promotion, additionally test one real AI News or technology input with an audience/use-case beat. ## Save And Approval Workflow When the user says to save, keep, approve or add a completed video's template to the library, treat that as explicit template-library maintenance intent. Do not repeat the normal video intake gate or start npm publication work. For creating a new template from a design brief, import or reusable-template request, follow `template-creation.md` before this approval routine. All write operations below target `NAVID_SKILL_ROOT/templates/`. This ensures new templates are saved **inside the skill package** and will be included in the next publish or manual copy to another machine. Use this routine path: 1. Derive a reusable candidate from the accepted production layout, preserving proof roles, illustration boundaries, safe zones and channel attribution. 2. Write the candidate manifest to `NAVID_SKILL_ROOT/templates/domains//candidate//manifest.json`. 3. Expand it to the required `short`, `standard` and `extended` sequences using the shared story fixture or the already approved real production. 4. Write each portable sequence to `NAVID_SKILL_ROOT/templates/portable///` with its own `index.html`, referenced CSS, referenced JS and required local assets. Each sequence directory must render independently when opened alone. 5. Generate contact sheets and playable previews outside the skill runtime (in the project's `videos/template-library-preview//`), then run structural and visual QA for the three sequences. 6. Validate the layout against one real technology or AI News input. An already completed, user-reviewed production may serve as that evidence. 7. If QA passes and the user's save/approval instruction is explicit: a. Move the manifest to `NAVID_SKILL_ROOT/templates/domains//approved//manifest.json`. b. Update `NAVID_SKILL_ROOT/templates/registry.json` with the promoted entry. c. Record the approval signal in the manifest. 8. If QA fails, keep the set as `candidate`, record the failures and repair it before asking for promotion again. When the new set is a minor variation of an already approved design family, reuse the existing portable structure and QA harness. Do not repeat foundational packaging work unless the variation changes the portable contract or exposes a new render/install defect. ## Approval Versus Distribution Template approval is an internal library operation that writes files into `NAVID_SKILL_ROOT/templates/`. Because approved templates live inside the skill directory, they are **automatically bundled** when the skill package is published or copied to another machine. No separate distribution step is needed for the templates themselves. Approval does not require: - Building or publishing an npm release. - Installing or replacing runtime skills. - Running cross-runtime clean-install acceptance after every new template. Packaging, runtime sync and npm publication are separate release operations. Run them only when the user asks to publish/sync, or when preparing a grouped release. A release operation must still validate that every bundled portable sequence renders independently. After approving a new template on one machine, the user may: - Re-publish the npm package to distribute the updated skill with new templates. - Or manually copy `NAVID_SKILL_ROOT/templates/` to the target machine's installed skill directory. ## Recommendation And Run State After intake, recommend up to three approved sets, ranked by content/domain fit and source-proof fit before visual freshness. Warn when a set was used recently on the same channel, but do not silently forbid it. If fewer than three approved matches exist, report the shortage rather than filling the result with candidates. The selected set id and the selection rationale belong in the project's `run-state.json`. Changing selection invalidates composition and all dependent stages. The first approved set, `repo-update-fullframe`, carries one follow-up improvement recorded at approval time: allow an optional lower `support-zone` for richer proof crops, diagrams or supporting media while preserving caption and platform UI safe areas.