# Community module pack authoring (v1)

This document is designed to be **uploaded to any external AI assistant** (Claude/Gemini/ChatGPT, etc.) so it can generate a community Studio module pack that fits **WindSeeker** constraints and validation rules.

## What you are making

You are producing a **Community Studio Module Pack**: a JSON manifest that can be submitted for moderation. After approval and publish, the module appears in **WingUnity Studio** with a **Community** badge and **creator credit**.

The pack is validated by the app and server using the shared validator:

- `packages/shared/src/studio/community-module-manifest.ts`

## Hard constraints (must follow)

- **Language**: All user-facing text is **English**.
- **Do not modify protected systems**: Pilates flow algorithm, anatomy visualization pipeline, and music notation rendering must remain unchanged.
- **Media URLs**:
  - Must be **HTTPS**.
  - Must use **allowed hosts** (Supabase domains by default; optionally extended by server env).
  - If unsure about media, **omit** media fields.
- **Schema must validate** (see below).

## Required manifest fields

Your JSON must be an object with these required fields:

- `title` (string, required, max 200)
- `description` (string, required)
- `module_type` (string, required, must be one of existing Studio module types)
- `safety_notes` (string, required, non-empty)
- `steps` (array, required, 1–200 items)

Optional fields:

- `wingunity_context` (string, optional; coaching hints for WingUnity assistant; keep short)
- `theme_preset` (string, optional; UX label only)

### Allowed `module_type` values (current)

Use one of:

- `pilates_basics`
- `advanced`
- `breathing`
- `wellness`
- `reference`
- `language`
- `music`

If your module is “completely independent” from movement/language/music, choose a **generic bucket**:

- Prefer `wellness` or `reference`
- Use `theme_preset` to express the “style” label (does not change runtime logic)

## Step fields (per item)

Each step must be an object with:

- `title` (string, required)

Optional step fields:

- `description` (string)
- `duration_seconds` (number; if omitted, the system may treat as 30s default; keep typical steps ~30–300)
- `movement_name` (string)
- `movement_difficulty` (number 1–10)
- `reps_or_sets` (string)
- `target_muscle_groups` (string[])
- `spine_alignment_notes` (string)
- `breathing_pattern` (string)
- `image_url` (string HTTPS on allowed host)
- `video_url` (string HTTPS on allowed host)

Notes:

- `image_url` and `video_url` are validated for HTTPS + allowed host.
- Audio URLs are **not** part of v1 schema (keep audio instructions as text for now).

## Minimal “good citizen” rules (recommended)

Even if schema allows 1 step, aim for:

- **3–12 steps**
- Clear titles and short instructions
- Safety note that is general and non-medical
- Avoid extreme claims (“cures”, “guaranteed”, medical advice)

## AI generation options (cost control)

The app supports generating a draft manifest via server route:

- `POST /api/wingunity/studio/community-module/ai-pack`

Two modes:

- **BYOK**: provide header `X-OpenAI-Key: <your OpenAI key>` (not stored)
- **Platform-funded**: server uses `OPENAI_API_KEY` with daily cap:
  - `COMMUNITY_MODULE_AI_DAILY_CAP_PER_USER` (default 3; set `0` to force BYOK)

Media allowlist can be extended by server env:

- `COMMUNITY_MODULE_MEDIA_EXTRA_HOSTS` (comma-separated hostnames)

## Copy-paste starter JSON (template)

```json
{
  "title": "My community module",
  "description": "A short overview for the Studio catalog and Explore listing.",
  "module_type": "wellness",
  "safety_notes": "Consult a qualified professional before starting. Stop if you feel sharp pain, dizziness, or shortness of breath.",
  "wingunity_context": "Optional: coaching tone, reminders, and what to prioritize. Keep it brief.",
  "theme_preset": "custom",
  "steps": [
    {
      "title": "Warm-up",
      "duration_seconds": 60,
      "breathing_pattern": "Slow nasal inhale and exhale",
      "description": "Settle into a calm rhythm. No strain."
    },
    {
      "title": "Main practice",
      "duration_seconds": 180,
      "description": "Follow the instruction focus for this module. Keep it simple and consistent."
    },
    {
      "title": "Cool down",
      "duration_seconds": 60,
      "description": "Ease back to rest and notice how you feel."
    }
  ]
}
```

## Prompt template (upload this file + prompt below)

Use this prompt with Claude/Gemini/etc. (and include your desired theme/style):

> You are generating a WindSeeker “Community Studio Module Pack” JSON manifest.
> Output **ONLY valid JSON** (no markdown fences).
> Follow the required schema and constraints described in `docs/community-module-pack-authoring.md`.
> Use English text only.
> Choose `module_type` from the allowed list; if the topic is independent, use `wellness` or `reference`.
> Omit any media URLs unless they are HTTPS and on an allowed host.
>
> Requirements:
> - Title max 200 chars
> - 3–12 steps
> - Each step has a clear `title`, reasonable `duration_seconds`
> - Include `safety_notes` (non-medical)
> - Include a short `wingunity_context` (max ~800 chars)
>
> Theme preset (UX label): `<your_theme_preset_here>`
> Module idea: `<describe the module>`

## Submission + moderation lifecycle (high level)

- User submits JSON → moderation queue
- Staff may request changes and message submitter
- Staff can preview a draft session
- Staff publishes → module becomes catalog-visible with **Community** badge + creator name