Skip to content

MASTER_CONTEXT.template.md

Latest commit

 

History

History
205 lines (140 loc) · 10.3 KB

MASTER_CONTEXT.template.md

File metadata and controls

205 lines (140 loc) · 10.3 KB
Raw

Master context (project + agents)

Purpose: One place for humans and AI agents to capture decisions, brand voice, API quirks, and what we learned while using this repo.

How agents should use this file

  • At the start of substantive work: Read this file for project-specific context that is not in the skill.
  • After meaningful changes: Append a new dated entry under Changelog (Decision / What changed / Why).
  • If fields are empty: Offer to populate them — ask the user once and write the values back.

Brand (optional)

Edit or replace with your real brand blocks. A starter template lives at skills/<this-repo's-api>-external-api/prompting/brand-voice-starter.md (e.g. skills/arcads-external-api/... in the Arcads repo, skills/kie-external-api/... in the KIE repo).

  • Tone:
  • Audience:
  • Words to use / avoid:

Reference images

Drop reference images into the references/ folder at the repo root:

  • references/influencers/ — face/body photos to recreate as AI people
  • references/products/ — product photos for showcase workflows
  • references/aesthetics/ — mood boards, lighting references, style inspiration

The agent checks this folder when composing prompts. (If the API in this repo requires hosted URLs rather than local file uploads, also fill in your hosting strategy in the API-specific section below.)

Universal prompting principles

These apply across all generative-image and generative-video APIs.

UGC realism

  • Imperfection block (camera): Every UGC image/video prompt must include camera imperfections: motion blur, overexposure, grain, lens distortion, off-center framing, soft focus. Without this, output looks too polished.
  • Skin realism block (mandatory): Include 3–4 subtle skin cues inline with character description: "visible pores, slight unevenness in skin tone, minor undereye shadows, hint of shine from natural oils." Do NOT use: acne, pimples, breakouts, blemishes, redness. Goal is "real person, not retouched" — not "person with skin problems."
  • Reference image order: character hero first (strongest identity signal), then product, then style refs.

Influencer / character recreation

  • Two-step flow: (1) generate a still image with the reference image as input, (2) show user for approval, (3) only then generate video using the approved still as the start frame / reference.
  • Never skip the approval step — video is expensive, stills are cheap to iterate.

Image QA

  • Visually review still images after generation (hands, fingers, limbs, face, merged objects, artifacts).
  • If defective, regenerate with refined prompt — up to 2 retries (3 attempts total).
  • QA retries skip a second credit confirmation but still bill credits.

Video prompting

  • No subtitles, no captions, no text overlays — append this clause to every prompt; many video models burn captions in by default.
  • Human motion cues are mandatory for person-on-screen videos: 3–4 cues per prompt (breaking eye contact, head tilts, weight shifts, grip adjustments). Without these, subjects look like frozen mannequins.

Meta ad deployment

Used by the meta-ad-builder shared skill (shared/skills/meta-ad-builder/) — publishes finished creatives as Meta (Facebook/Instagram) ads. Fill in your account IDs once; the skill reads them so you don't paste them every run. These are account identifiers, not secrets, but the file is gitignored either way.

  • Default ad account (META_AD_ACCOUNT_ID):
  • Facebook Page ID (META_PAGE_ID):
  • Instagram user ID (META_IG_USER_ID):
  • Meta Pixel ID (META_PIXEL_ID):
  • Default destination URL / offer link:
  • Default ad set(s) to deploy into (name → ID):
  • Default CTA type (e.g. SIGN_UP, LEARN_MORE):

The access token itself (META_ACCESS_TOKEN) lives in .env, never here. Campaigns, ad sets, and ads created by the skill are PAUSED. Activation is always a separate operator-reviewed action; follow the repository's documented activation flow.

End-to-end ad agent

Used by the ad-agent-orchestrator skill when running the full research → creative → deploy → measure loop. Fill these once so the agent does not re-ask every run. The access token stays in .env; thresholds and account IDs are preferences, not secrets.

  • Default competitor Page names or IDs (comma-separated):
  • Default conversion action type (exact Meta action type string for ROAS/CPA):
  • Winner threshold (e.g. minimum ROAS or max CPA to call a test a winner):
  • Loser threshold (e.g. spend cap with zero conversions before pausing review):
  • Default primary test variable (creative / copy / audience / offer):
  • Preferred deploy mode (existing_ad_set or new_campaign):

Runs are tracked in outputs/ad-agent/lineage.jsonl. Real deploys must pass --run-id so meta-performance-loop can join automatically. Activation is a separate human step with --execute and exact --confirm ACTIVATE; orchestrated activation also requires a verified approved G9 receipt. Activation is never automatic.

Project snapshot — Arcads

  • API base: https://external-api.arcads.ai (see .env.example).
  • Auth: HTTP Basic via ARCADS_BASIC_AUTH (pre-encoded Basic ... header) or ARCADS_API_KEY as the Basic username with an empty password. Values in .env must be single-quoted (special chars: {, [, *).
  • Skill: .cursor/skills/arcads-external-api/ (sync from skills/arcads-external-api/ via scripts/sync-skill.sh).

My workspace

  • Default product ID: (auto-populated after first GET /v1/products call)
  • Default product name: (auto-populated)

Credit costs

Fill in your plan's credit costs below. The agent references this table before every generation. If left blank, the agent will ask you once and can fill them in.

Treat every value as an estimate: this repository has no billing endpoint, and model, duration, resolution, references, and plan can change the charge. Confirm current pricing and actual usage in the Arcads dashboard.

Model Estimated credits per generation Notes
Veo 3.1 (fill in) Confirm the selected resolution and current dashboard price
Sora 2 (fill in)
Sora 2 Pro (fill in) Auto-selected when using refImageAsBase64
Kling 3.0 (scene) (fill in)
Kling 3.0 (b-roll) (fill in)
Nano Banana 2 (image, nano-banana-2) (fill in) Typical generation time is not a price guarantee
Nano Banana Pro (image, nano-banana) (fill in)
Nano Banana (scene) (fill in)

API learnings — Arcads

These are confirmed behaviors of the Arcads external API.

Auth

  • HTTP Basic with ARCADS_BASIC_AUTH (pre-encoded header from dashboard) or ARCADS_API_KEY as Basic username.
  • Values in .env must be single-quoted due to special characters ({, [, *).

Nano Banana image endpoint

  • POST /V2/images/generate (note uppercase V2). model is required.
  • Valid models: nano-banana, nano-banana-2, gpt-image, soul, grok_image, seedream, seedream_5_lite.
  • Default to nano-banana-2 (Nano Banana 2). nano-banana = Nano Banana Pro (no nano-banana-pro in the API enum).
  • Output: .png at the url field on the asset response (no thumbnailUrl).
  • Generation time: ~35 seconds typical.
  • Auth: must use Authorization: Basic ... header.

Scene for image-like output

  • POST /v1/scene with only productId, prompt, aspectRatio produces a short video + .jpg thumbnail.
  • Best path when you need a still frame to feed into another model (before the Nano Banana image endpoint was confirmed).
  • No duration required (unlike b-roll which needs 5 or 10).

B-roll

  • Requires duration (5 or 10 seconds).
  • Slower to generate than scene (~5 min vs ~75s).

Veo 3.1

  • startFrame vs referenceImages are mutually exclusive. startFrame = video animates from this exact image. referenceImages = style/mood inspiration only.
  • Default: always use startFrame when user provides a single person photo.
  • No duration field — auto-determines length (~8s typical).
  • Default resolution: 720p — 4K and 1080p show no visible quality difference for UGC content but produce 3-8x larger files.

Sora 2

  • refImageAsBase64 is a style/mood reference only — it does NOT preserve face, pose, or scene from the input image. Do NOT use Sora 2 to animate a specific starting frame.
  • Best for: text-only video generation, or when you just have a product photo and want to generate a UGC video directly (no starting frame step).
  • Supports duration up to 20s (enum: 4, 8, 12, 16, 20).

File upload (for Veo start frames / reference images)

  • POST /v1/file-upload/get-presigned-url — field is fileType, not contentType.
  • Response: presignedUrl (for PUT upload) + filePath (pass into startFrame / referenceImages).

Kling / Nano Banana video routing

  • No dedicated POST endpoints for Kling. Asset type enums (kling_30, nano-banana) exist on responses.
  • Model selection may be server-side for b-roll/scene.

Polling

  • GET /v1/assets/{id} — status goes pending -> generated | failed.
  • Typical times: scene ~75s, b-roll ~5 min, Veo 3.1 ~4 min, Nano Banana image ~35s.

Product API

  • ProductCreationDto has text-only fields (name, description, targetAudience, mainFeatures, painPoint, perceived) — no image upload.
  • Product images are dashboard-only (pictureId field).
  • The Arcads script/actor pipeline (situations, voices) is a separate system from the Veo/Sora/Kling direct-model routes.

Folder / project organization

  • Every agent session that generates assets should create (or reuse) a folder named "Arcads API - YYYY-MM-DD" with a matching project inside it, then assign all generated assets to that project.
  • API calls: POST /v1/folders, POST /v1/projects, POST /v1/assets/add-to-project. Check GET /v1/products/{productId}/folders first to avoid duplicates.

Changelog

YYYY-MM-DD — Template entry

  • Decision:
  • Change:
  • Why: