Registering in the Version Registry¶

The version registry is the canonical record of every workflow, product, and account in the pipeline. When you add a new product or account, add it to the registry so tooling can find it.

What the registry is¶

A single JSON file: reference/version-registry.json. Tracks:

Workflows — current version, status, fan-out state per workflow
Products — file path, status, photo URL per product
Accounts — file path, archetype, R2 URL per account

The Manager and every sync script reads the registry as the source of truth.

Registry shape (high-level)¶

{
  "brands": {
    "xyz-wellness": {
      "file": "reference/brands/xyz-wellness.md",
      "status": "active",
      "products": ["magnesium-glycinate", "rhodiola-extract"]
    }
  },
  "products": {
    "magnesium-glycinate": {
      "brand": "xyz-wellness",
      "file": "reference/products/magnesium-glycinate.md",
      "status": "active",
      "photo_r2": "https://pub-xxx.r2.dev/products/magnesium-glycinate.jpg",
      "added": "2026-05-12"
    }
  },
  "accounts": {
    "F": {
      "code": "F",
      "file": "reference/accounts/account-f.md",
      "archetype": "confessional",
      "avatar_r2": "https://pub-xxx.r2.dev/avatar-sheets/account-f.jpg",
      "platforms": ["tiktok"],
      "sales_channels": ["tiktok-shop", "amazon-keyword"],
      "status": "active",
      "added": "2026-05-12"
    }
  },
  "workflows": {
    "xyz-wellness": {
      "XYZG1": {
        "current_version": "V1",
        "status": "approved",
        "fanned_out_to_accounts": ["A", "B", "C", "D"],
        "test_account": "A",
        "last_updated": "2026-05-10",
        "type": "growth",
        "month": "may",
        "history": [
          {"version": "V0-1", "date": "...", "notes": "initial build"},
          {"version": "V0-2", "date": "...", "notes": "..."},
          {"version": "V1", "date": "2026-05-10", "notes": "approved, fanned out to A-D"}
        ]
      }
    }
  }
}

Your team's exact shape may differ slightly — the registry evolves. The principles are the same.

When to register¶

Event	Add registry entry
New brand onboarded	Yes — under `brands.{brand-slug}`
New product added	Yes — under `products.{product-slug}`
New account created	Yes — under `accounts.{account-code}`
New workflow started	Yes — under `workflows.{brand-slug}.{workflow-code}`
Avatar reference URL updated	Yes — update the existing entry
Sales channel mechanics changed	Yes — update the existing entry
Surgical edit to an existing file	No — surgical edits don't bump versions

How to register a new product¶

You: register the new magnesium-glycinate product in the version registry.
     It's under brand XYZ Wellness, status active, photo at [R2 URL].

Claude:
  Reading reference/version-registry.json...

  Adding:
    products.magnesium-glycinate:
      brand: "xyz-wellness"
      file: "reference/products/magnesium-glycinate.md"
      status: "active"
      photo_r2: "https://pub-xxx.r2.dev/products/magnesium-glycinate.jpg"
      added: "2026-05-12"

  Also adding "magnesium-glycinate" to brands.xyz-wellness.products
  so the brand's product list stays consistent.

  Saved.

The Manager edits the JSON directly. You don't typically edit this file by hand — let Claude do it to avoid syntax errors.

How to register a new account¶

You: register account F in the registry. Archetype is confessional,
     avatar ref at [R2 URL], platforms TikTok only, sales channels
     TikTok Shop and Amazon-keyword.

Claude:
  Adding:
    accounts.F:
      code: "F"
      file: "reference/accounts/account-f.md"
      archetype: "confessional"
      avatar_r2: "https://pub-xxx.r2.dev/avatar-sheets/account-f.jpg"
      platforms: ["tiktok"]
      sales_channels: ["tiktok-shop", "amazon-keyword"]
      status: "active"
      added: "2026-05-12"

  Saved.

How to register a new workflow¶

This happens automatically the first time you build a workflow (the PatchWork Importer adds the workflow entry as part of saving V0-1.nbflow). You don't usually register workflows manually.

Subsequent version bumps (V0-1 → V0-2, V0-N → V1, etc.) get appended to the workflow's history array automatically by whatever script makes the change. As long as those scripts run, the registry stays current.

Manual updates to existing entries¶

When you update an existing avatar reference URL, change a sales channel, or rename a file:

You: I just re-uploaded account F's avatar to a v2 URL. Update the
     registry to point at the new URL.

Claude:
  Updating accounts.F:
    avatar_r2: "https://pub-xxx.r2.dev/avatar-sheets/account-f-v2.jpg"
    last_updated: "2026-05-13"

  Note: any workflow currently pointing at the old URL still works
  (the old URL is still live). To migrate workflows to the new URL,
  do a surgical edit on each affected workflow.

Sanity-checking the registry¶

Periodically (monthly or after big changes), verify the registry matches reality:

You: audit the version registry against actual files. Report any mismatches.

Claude: [walks every entry, checks each referenced file exists and R2 URL
         resolves]

  Mismatches found:
  - Product "old-product" entry exists but file doesn't (deleted?)
  - Account E's avatar_r2 returns 404 (URL stale?)
  - Workflow XYZS5's V0-3 file is missing (where did it go?)

  Want me to fix these one at a time?

This isn't a frequent task but it's worth doing every once in a while — silent registry drift is hard to notice.

Why the registry matters¶

The tracker-sync skill reads it to know what's where. The Manager reads it to know what products / accounts exist when briefing a new workflow. Workflow scripts read it to know current versions for variant work.

A stale registry means stale tooling. Keep it current.

When you're ready¶

You've finished Chapter 8. You've added a new product, a new account, wired the R2 references, set up the platform-side sales mechanics, and registered everything in the version registry. The pipeline now knows about it; future workflows can use it.

→ Next: Chapter 9 — Content Research. Before building workflows for the new product or account, research what's working in the niche right now.