content-generator

What this skill does

# FSAI Content Generator

This skill generates valid JSON import files for the FSAI applicant portal, custom forms, and email sequences. The output is consumed by the FSAI backend's content import endpoints.

---

## Guided Workflow

Content generation follows a **three-phase process**. Each phase builds on the previous one because later phases reference content created in earlier phases.

### Phase 1: Custom Forms (`output/forms.json`)

**Why first:** Custom forms must be imported into the platform before the portal can reference them. The portal's `formName` fields must match forms that actually exist.

1. **Setup** — If `metadata/` and `output/` directories don't exist in the current workspace, create them.

2. **Metadata check** — Look for a `metadata/*.json` file. If none found, tell the user:
   > "No metadata file found. Export one from the FSAI admin panel and place it in `metadata/`. The file contains brand info, available forms, and uploaded assets needed to generate valid content."

3. **Read metadata** — Examine `metadata.availableForms` to understand what default forms already exist (fields with `dataLocation` are defaults, those without are custom). Identify gaps — what additional questions does this brand need that aren't covered by defaults?

4. **Generate `output/forms.json`** — Create custom forms following the Forms JSON Schema below. Use `useExistingFields` to pull default fields into custom form pages where it makes sense. Never set `dataLocation` on new fields. Skip this phase if the brand only needs the default forms.

5. **Validate** — Copy the validator and run it:
   ```bash
   cp "${CLAUDE_PLUGIN_ROOT}/skills/content-generator/references/validate.ts" ./validate.ts
   npx tsx validate.ts
   ```

6. **Hand off to user** — Present the forms.json and tell them:
   > "Import this forms.json via the super admin panel, then **re-export the metadata** so the next phase can reference the newly created forms by name."

**Wait for the user to provide updated metadata before proceeding to Phase 2.**

### Phase 2: Portal (`output/portal.json`)

**Why second:** The portal references forms by name. With the updated metadata (which now includes custom forms from Phase 1), all `formName` references will validate correctly.

1. **Read updated metadata** — The user should have placed a fresh metadata export in `metadata/`. Read it to see all available forms (defaults + newly imported custom forms), assets, and brand context.

2. **Generate `output/portal.json`** — Build the portal sections and steps following the Portal JSON Schema below. Reference both default and custom form names. Use real asset IDs from metadata for video/slide steps.

3. **Validate** — Run `npx tsx validate.ts` and fix any errors.

4. **Present to user** — Show the portal structure. They can import it via the super admin panel.

### Phase 3: Email Sequences (`output/sequences.json`)

**Why last:** Sequences are independent of forms/portal but are typically generated in the same session.

1. **Generate `output/sequences.json`** — Create email sequences following the Sequences JSON Schema below. Use tracking link placeholders and merge tags.

2. **Validate** — Run `npx tsx validate.ts` and fix any errors.

3. **Present to user** — Show the sequences. They can import them via the super admin panel.

### Shortcut: Single-phase generation

If the user only needs one file type (e.g., "just generate the portal"), skip the other phases. If they ask for everything at once and custom forms aren't needed, generate portal and sequences together. The phased workflow only matters when custom forms are involved, because forms must exist in the platform before the portal can reference them.

---

## Portal JSON Schema (`output/portal.json`)

```typescript
interface ImportPortalJson {
  /** Main title displayed at the top of the applicant portal */
  title: string;
  /** Subtitle displayed below the title */
  subtitle: string;
  /** Ordered list of portal sections */
  sections: ImportPortalSectionJson[];
}

interface ImportPortalSectionJson {
  /** Section heading */
  title: string;
  /** Optional section description */
  subtitle?: string;
  /** Optional emoji shown next to the section title */
  emoji?: string;
  /** Ordered list of steps within this section */
  steps: ImportPortalStepJson[];
}

interface ImportPortalStepJson {
  /** Step heading shown to the applicant */
  title: string;
  /** Step description / instructions */
  subtitle: string;
  /** The type of interaction this step presents */
  action:
    | 'video'          // Embedded video player (requires assetId referencing a video asset)
    | 'form'           // Dynamic form (requires formName matching an available form)
    | 'slides'         // PDF/image slides viewer
    | 'studio_slides'  // Interactive slide deck from the studio (requires assetId referencing a slide asset)
    | 'call'           // Schedule a call (Calendly or similar)
    | 'sign'           // E-signature document
    | 'document'       // Downloadable document
    | 'visit_link'     // External link (requires url)
    | 'upload'         // File upload prompt
    | 'invite_team';   // Invite team members step

  /** Form name to bind to (required for action: 'form'). Must match a name from metadata availableForms. */
  formName?: string | null;

  /** Asset UUID to bind to (required for action: 'video' and 'studio_slides'). Must match an assetId from metadata assets. */
  assetId?: string;

  /** Whether completing this step creates a deal in the pipeline */
  createsDeal?: boolean;

  /** Whether this step is the FDD (Franchise Disclosure Document) step */
  isFdd?: boolean;

  /** Whether this step is hidden from the applicant by default */
  hidden?: boolean;

  /** URL for visit_link steps or fallback video URL */
  url?: string | null;

  /** Arbitrary JSON data attached to the step (rarely used) */
  json?: unknown | null;
}
```

---

## Forms JSON Schema (`output/forms.json`)

```typescript
interface ImportFormsJson {
  /** List of custom forms to create */
  forms: ImportFormJson[];
}

interface ImportFormJson {
  /** Display name of the form */
  name: string;
  /** Optional description */
  description?: string;
  /** Which entity type this form collects data for */
  appliesTo: 'user' | 'franchisee-org' | 'location';
  /** Optional group name — creates or matches an existing form group */
  groupName?: string;
  /** Ordered list of pages in this form */
  pages: ImportFormPageJson[];
}

interface ImportFormPageJson {
  /** Page heading */
  title: string;
  /** Optional page description */
  subtitle?: string;
  /** New custom fields to create on this page */
  fields: ImportFormFieldJson[];
  /** Field names from default forms to move into this page */
  useExistingFields?: string[];
}

interface ImportFormFieldJson {
  /** Internal field name */
  name: string;
  /** Display text shown to the user */
  question: string;
  /** Additional help text */
  description?: string;
  /** Input placeholder text */
  placeholder?: string;
  /** Field input type */
  type: 'short-text' | 'long-text' | 'currency' | 'number' | 'date' | 'url'
    | 'email' | 'phone' | 'multiselect' | 'singleselect' | 'boolean' | 'dropdown';
  /** Whether the field is required (default false) */
  required?: boolean;
  /** Options for multiselect, singleselect, and dropdown types */
  options?: string[];
}
```

### Form Generation Rules

1. **Never set `dataLocation`** — imported fields are always custom. Only default fields have dataLocation.
2. **Use `useExistingFields`** to reference default fields from metadata by name rather than recreating them. This moves the field from its default form into your custom form.
3. **Check metadata first** — read `metadata.availableForms[].pages[].fields[]` to see what questions are already collected. Don't duplicate them.
4. **Fields with `dataLocation`** in metadata are default fields that map to database columns. Referenc