Adding a New Product

When the brand expands its lineup — or you're onboarding a new brand from scratch — you'll need to add a product to the reference library so the pipeline can use it. This page walks through what files to create and what fields to fill.

Overview

flowchart LR
    A[New product to add] --> B[Create product file<br/>reference/products/]
    B --> C[Fill required fields<br/>ingredients / claims / mechanism]
    C --> D[Add product photo<br/>upload to R2]
    D --> E[Verify with the<br/>Script Writer test]
    E --> F[Product ready for workflows]

Step 1: Gather the source material

Before opening a file, collect:

• Product label (high-quality photo of the front of the product)
• Ingredient list (text — full list with dosages)
• Manufacturer claims — what the brand legally allows you to say
• Competitor comparisons — at least 2-3 similar products and how this one differs
• Mechanism notes — how the product works (the science)
• Production / origin facts — who makes it, where, any certifications

If you don't have all of this, ask the brand for it before proceeding. The product file is the compliance ground truth — incomplete information means later scripts will improvise, which is exactly what we don't want.

Step 2: Create the product file

Path: reference/products/{product-slug}.md

Slug convention: lowercase kebab-case. Examples:

• magnesium-glycinate.md
• rhodiola-extract.md
• vitamin-d3-k2.md

The file template:

# {Product Name}

## Brand

{Brand name} (link to brand file)

## Product type

{Supplement / cosmetic / device / etc.}

## Ingredients

- {Ingredient 1}: {dosage}
- {Ingredient 2}: {dosage}
- {Other actives, fillers, capsule material}

## Mechanism

{How the product works. 1-2 paragraphs explaining the science in approachable
terms — not too clinical, not oversimplified.}

## Approved claims

{Bulleted list of what scripts can say about this product. Each claim should
be specific and backed by either a study, the manufacturer's documentation,
or regulatory approval.}

- {Claim 1}
- {Claim 2}
- {Claim 3}

## Banned claims for this product

{Specifically banned claims for THIS product, beyond what's banned at the brand
level. Often related to specific ingredients or known concerns.}

- {Banned claim 1}
- {Banned claim 2}

## Competitor comparison

| Product | Our differentiator |
|---|---|
| {Competitor 1} | {What makes ours different / better} |
| {Competitor 2} | {Differentiator} |

## Production notes

- Made by: {manufacturer}
- Origin: {country}
- Certifications: {organic, NSF, GMP, etc.}
- Format: {capsule / tincture / powder / spray}

## Sales channel availability

- TikTok Shop: {link or "not listed"}
- Amazon: {link or "not listed"}
- Meta Shop: {link or "not listed"}

## Notes for the pipeline

{Any operational notes — known compliance gotchas, specific phrases the
brand wants emphasized or avoided, etc.}

Step 3: Upload the product photo

The Image Prompter wires the product photo into image gen nodes as a secondary reference. The photo needs to be available at an R2 URL.

You: upload reference/products/photos/magnesium-glycinate.jpg to R2.
     Use the product-images bucket.

Claude: [uploads via the R2 Worker, returns the public URL]

  Uploaded. URL:
  https://pub-xxxxx.r2.dev/products/magnesium-glycinate.jpg

  Adding to the product file's metadata.

The URL gets recorded in the product file (typically as a metadata header) so future workflows can find it.

Step 4: Verify with a test workflow

Don't trust that the product file is complete until you've test-driven it:

You: write a test script for the new magnesium-glycinate product, targeted
     at women 35-55 with sleep issues. Keep it under 60 seconds. We're
     just sanity-checking the product file is complete.

Claude:
  Loading reference/products/magnesium-glycinate.md...

  Compliance check: approved claims include "supports sleep onset" and
  "supports muscle relaxation". Brand-level banned words include
  "cure" and "guarantees" — Script Writer will avoid these.

  [test script follows]

  Check: does this script accurately reflect the product? If yes, the
  product file is complete. If no, what's wrong?

If the test script gets a claim wrong, your product file is incomplete or has incorrect information. Fix it before using it in production workflows.

Step 5: Register in the version registry (optional but recommended)

If your brand uses the version registry to track product status (active / discontinued / coming-soon), add the new product there:

{
  "xyz-wellness": {
    "products": {
      "magnesium-glycinate": {
        "status": "active",
        "added": "2026-05-12",
        "file": "reference/products/magnesium-glycinate.md",
        "photo_r2": "https://pub-xxxxx.r2.dev/products/magnesium-glycinate.jpg"
      }
    }
  }
}

Not all teams use the registry this way. Optional based on your team's conventions.

Common mistakes

Skipping the approved-claims list

Without it, the Script Writer either improvises (risky) or refuses to write specific claims (unhelpful). The list is the single most important field.

Padding the approved-claims list

The opposite mistake — including claims that aren't actually documented because "we say this in marketing." If it's not in the product file, Marketing doesn't get to use it either. Be honest about what's substantiated.

Forgetting competitor comparisons

Sales workflows often pivot on "this is different from [competitor]." Without this section, those pivots can't be written cleanly.

Not uploading the product photo

The Image Prompter expects the product photo to be R2-hosted. Local file paths don't work in .nbflow references — they fail at generation time.

When the product has multiple variants (size, flavor, etc.)

If the product has multiple SKUs with meaningfully different properties (different dosages, different formats):

• Same product file, with a "Variants" section listing each SKU
• Same photo unless variants look different (each variant may need its own photo)
• Variant-specific claims if dosing changes the approved claims

If the variants are cosmetically different but functionally identical (e.g., different bottle colors), use one file with one photo.

When you're ready

→ Next: Adding a New Account — set up a new avatar account that can produce content for any product in the brand.