Update to Frigade Engage

{
  "description": "Build and manage Frigade Engage flows (announcements, tours, checklists, nudges, forms, banners, cards, NPS surveys) and collections directly from your coding agent, including end-to-end wiring into React/Next.js codebases. Use when the user mentions Frigade, onboarding flows, product tours, checklists, announcements, in-product guides, or flow collections (promoting, creating, or adding flows to a collection).",
  "included_files": [
    {
      "relative_path": "examples/banner-permanent.yaml",
      "size_in_bytes": 786
    },
    {
      "relative_path": "examples/card-feature-highlight.yaml",
      "size_in_bytes": 764
    },
    {
      "relative_path": "examples/form-multistep.yaml",
      "size_in_bytes": 4309
    },
    {
      "relative_path": "examples/nps-survey.yaml",
      "size_in_bytes": 1063
    },
    {
      "relative_path": "examples/onboarding-checklist.yaml",
      "size_in_bytes": 2237
    },
    {
      "relative_path": "examples/product-tour.yaml",
      "size_in_bytes": 1275
    },
    {
      "relative_path": "examples/welcome-announcement.yaml",
      "size_in_bytes": 1023
    },
    {
      "relative_path": "recipes/add-flows-to-collection.md",
      "size_in_bytes": 7689
    },
    {
      "relative_path": "recipes/create-announcement.md",
      "size_in_bytes": 35405
    },
    {
      "relative_path": "recipes/create-banner.md",
      "size_in_bytes": 4545
    },
    {
      "relative_path": "recipes/create-card.md",
      "size_in_bytes": 4770
    },
    {
      "relative_path": "recipes/create-checklist.md",
      "size_in_bytes": 5052
    },
    {
      "relative_path": "recipes/create-collection.md",
      "size_in_bytes": 34025
    },
    {
      "relative_path": "recipes/create-form.md",
      "size_in_bytes": 4456
    },
    {
      "relative_path": "recipes/create-nps-survey.md",
      "size_in_bytes": 4939
    },
    {
      "relative_path": "recipes/create-survey.md",
      "size_in_bytes": 4725
    },
    {
      "relative_path": "recipes/create-tour.md",
      "size_in_bytes": 44303
    },
    {
      "relative_path": "recipes/delete-flow.md",
      "size_in_bytes": 4425
    },
    {
      "relative_path": "recipes/duplicate-flow.md",
      "size_in_bytes": 5575
    },
    {
      "relative_path": "recipes/first-run-setup.md",
      "size_in_bytes": 23301
    },
    {
      "relative_path": "recipes/get-flow.md",
      "size_in_bytes": 3778
    },
    {
      "relative_path": "recipes/link-flows.md",
      "size_in_bytes": 30371
    },
    {
      "relative_path": "recipes/list-flows.md",
      "size_in_bytes": 3398
    },
    {
      "relative_path": "recipes/promote-collection-to-prod.md",
      "size_in_bytes": 6228
    },
    {
      "relative_path": "recipes/promote-to-prod.md",
      "size_in_bytes": 44119
    },
    {
      "relative_path": "recipes/publish-flow.md",
      "size_in_bytes": 5917
    },
    {
      "relative_path": "recipes/reset-user.md",
      "size_in_bytes": 19969
    },
    {
      "relative_path": "recipes/update-targeting.md",
      "size_in_bytes": 5335
    },
    {
      "relative_path": "recipes/update-yaml.md",
      "size_in_bytes": 5064
    },
    {
      "relative_path": "recipes/version-management.md",
      "size_in_bytes": 5591
    },
    {
      "relative_path": "reference/agent-harness.md",
      "size_in_bytes": 3592
    },
    {
      "relative_path": "reference/errors.md",
      "size_in_bytes": 24836
    },
    {
      "relative_path": "reference/graphql-schema.md",
      "size_in_bytes": 32255
    },
    {
      "relative_path": "reference/next-app-router.md",
      "size_in_bytes": 13709
    },
    {
      "relative_path": "reference/next-pages-router.md",
      "size_in_bytes": 14705
    },
    {
      "relative_path": "reference/operations.md",
      "size_in_bytes": 24316
    },
    {
      "relative_path": "reference/rest-endpoints.md",
      "size_in_bytes": 42050
    },
    {
      "relative_path": "reference/sdk-react.md",
      "size_in_bytes": 31321
    },
    {
      "relative_path": "reference/targeting-and-rules.md",
      "size_in_bytes": 26570
    },
    {
      "relative_path": "reference/yaml-spec.md",
      "size_in_bytes": 44737
    }
  ],
  "name": "frigade-engage",
  "skill_md_contents": "---\nname: frigade-engage\ndescription: Build and manage Frigade Engage flows (announcements, tours, checklists, nudges, forms, banners, cards, NPS surveys) and collections directly from your coding agent, including end-to-end wiring into React/Next.js codebases. Use when the user mentions Frigade, onboarding flows, product tours, checklists, announcements, in-product guides, or flow collections (promoting, creating, or adding flows to a collection).\nmetadata:\n  upstream-version: \"0.0.1\"\n  upstream-commit: \"aeba3dfc792b1ed9dcccfe576efabb039a2b9514\"\n  authored-against:\n    backend-app: \"d245b4fd\"\n    frigade-web: \"17326986\"\n    docs: \"fc1fe0c3\"\n    demo-v2: \"82b68403\"\n    frigade-react: \"2.9.4\"\n---\n\n# frigade-engage\n\n> **ChatGPT/Codex compatibility.** Load this skill through the plugin and read `reference/agent-harness.md` before executing. It maps recipe tool labels to the tools actually available in the host. Resolve recipe, reference, and example paths relative to this skill directory; resolve application paths against the user’s selected project.\n\n## What this skill does\n\n`frigade-engage` lets you build onboarding flows for your product — announcements, tours, checklists, forms, surveys, banners, and cards — directly from ChatGPT or Codex with the required project and execution tools. It manipulates your Frigade workspace via the Frigade API (GraphQL + REST) and wires the `@frigade/react` SDK into your Next.js or React codebase end-to-end. Once your keys are set up, you never need to open the Frigade dashboard: the agent reads and writes flow definitions, targeting rules, YAML payloads, and the component calls that render flows in your app — all from one conversation.\n\n## Critical pre-flight: always run first-run-setup\n\n**Every skill invocation runs `recipes/first-run-setup.md` first.** This ensures the project has Frigade API keys configured, the repo is bound to a Frigade workspace, and the `.env.local` / `.gitignore` / `.frigade/project.json` are set up correctly before any API call is made. Never skip this step. If keys or the workspace binding are missing, the setup recipe walks the user through initialization (public key + private secret for dev, optionally prod) and writes `.frigade/project.json` so subsequent invocations skip straight to work.\n\nIf the user's request looks entirely read-only (\"what flows do I have?\"), setup still runs — it's what proves we have credentials to read in the first place.\n\n## Two environments — the mental model\n\nEvery Frigade workspace has two sibling environments, each with its own key pair: **dev** (`FRIGADE_API_KEY_SECRET` / `NEXT_PUBLIC_FRIGADE_API_KEY`) and **prod** (`..._SECRET_PROD` / `..._PROD`). They are separate Organization records — a flow in dev and its prod counterpart are distinct rows linked by a shared slug. **You build and iterate in dev; you ship to prod by promoting from dev.** The skill defaults to dev for everything and only ever touches prod when the user is explicitly promoting or has explicitly asked to operate in prod (see `recipes/first-run-setup.md` Section 5 for how the target env is resolved per call).\n\n## Safety model summary\n\n- **Dev environment (default):** All operations run immediately. Fast iteration, low friction, no confirmation prompts.\n- **Prod is promote-only for flow & collection content.** The **only** sanctioned way to change a prod flow or collection is to make the change in dev and promote it (`recipes/promote-to-prod.md`, `recipes/promote-collection-to-prod.md`). Direct authoring in prod — creating, updating, publishing, or deactivating a flow or collection straight against the prod key — is **discouraged**. When a user asks for it, the skill **steers them to the dev→promote path** and proceeds only on an explicit typed override (`edit prod directly`). See `reference/operations.md` §\"Prod is promote-only\" for the exact steer template and the list of ops it covers.\n- **Prod environment (other writes):** Any operation tagged `dangerous` in `reference/operations.md` requires explicit confirmation (`\"About to <verb> <target> in prod. Confirm? (y/n)\"`) before executing.\n- **Destructive operations** (`delete-flow`, `reset-user`, `delete-user-group`, `delete-rule`, and others flagged in `reference/operations.md`) are tagged `dangerous` in **both** environments — confirmation is always required regardless of env.\n- **Batch confirmations:** One confirmation per operation batch, not per sub-item. Example: promoting 3 flows dev → prod = one confirmation covering all three, not three separate prompts.\n- **Confirmation canonical format:** `\"About to <verb> <target> in <environment>. Confirm? (y/n)\"`. Anything other than `y`/`yes` aborts cleanly — no partial state is left behind.\n\nThe authoritative list of operation names, their verbs, their targets, their `dangerous` flag, and whether they trigger the prod steer is `reference/operations.md`. Always consult that file before emitting a confirmation or steer prompt.\n\n## Dispatch table — recipes\n\n| If the user wants to… | Read |\n|---|---|\n| First use, set up, plug in keys | `recipes/first-run-setup.md` |\n| Create an announcement | `recipes/create-announcement.md` |\n| Create a tour (with DOM anchors) | `recipes/create-tour.md` |\n| Link flows (e.g., announcement CTA starts a tour) | `recipes/link-flows.md` |\n| Promote dev → prod | `recipes/promote-to-prod.md` |\n| Reset a user so they see flows again | `recipes/reset-user.md` |\n| Create a checklist | `recipes/create-checklist.md` |\n| Create a form | `recipes/create-form.md` |\n| Create a survey | `recipes/create-survey.md` |\n| Create an NPS survey | `recipes/create-nps-survey.md` |\n| Create a banner | `recipes/create-banner.md` |\n| Create a card | `recipes/create-card.md` |\n| Create a collection (and embed it in your app) | `recipes/create-collection.md` |\n| Add one or more flows to a collection | `recipes/add-flows-to-collection.md` |\n| Promote a collection dev → prod | `recipes/promote-collection-to-prod.md` |\n| Duplicate a flow | `recipes/duplicate-flow.md` |\n| Delete a flow | `recipes/delete-flow.md` |\n| Update a flow's YAML | `recipes/update-yaml.md` |\n| Update targeting on a flow | `recipes/update-targeting.md` |\n| Publish a flow | `recipes/publish-flow.md` |\n| List flows in the workspace | `recipes/list-flows.md` |\n| Get a single flow's details | `recipes/get-flow.md` |\n| Manage flow versions (revert, diff, history) | `recipes/version-management.md` |\n| Anything not above | Consult `reference/operations.md` + `reference/rest-endpoints.md` and extend the closest fully-authored recipe pattern |\n\n## Dispatch table — references\n\n| For questions about… | Read |\n|---|---|\n| Running this skill on Codex / another harness (tool mapping, terminology) | `reference/agent-harness.md` |\n| Which ops exist, their verb/target, their safety tag | `reference/operations.md` |\n| GraphQL queries and mutations (shapes, arguments, responses) | `reference/graphql-schema.md` |\n| REST endpoints (URLs, headers, bodies, auth) | `reference/rest-endpoints.md` |\n| `@frigade/react` SDK surface (provider, components, hooks, env vars) | `reference/sdk-react.md` |\n| How to wire Frigade into a Next.js App Router project (≥13) | `reference/next-app-router.md` |\n| How to wire Frigade into a Next.js Pages Router project | `reference/next-pages-router.md` |\n| Flow YAML structure (the `data` field of a flow) | `reference/yaml-spec.md` |\n| Targeting rules and audience DSL | `reference/targeting-and-rules.md` |\n| Error classes, status codes, and recovery strategy | `reference/errors.md` |\n\n## Hard rules (non-negotiable)\n\n1. **Private keys never enter web-app code.** `FRIGADE_API_KEY_SECRET` and `FRIGADE_API_KEY_SECRET_PROD` only appear in `.env.local` (gitignored) and in `Authorization: Bearer ...` headers in `curl` / server-side fetch calls issued from the skill itself. Never inside JSX/TSX, never as a React prop, never in a client-side `fetch`, never in any file under `src/`, `app/`, `pages/`, or `components/`. **Grep guard:** after any code emission, confirm `grep -r FRIGADE_API_KEY_SECRET src/ app/ pages/ components/` returns zero hits. If it returns anything, revert the emission and report the violation.\n\n2. **Multi-file code edits are atomic.** If any edit in a batch fails (syntax error, type error, failed write, failed API call mid-batch), revert all prior edits in that same batch. Keep pre-edit snapshots of every file touched. Never leave the repo half-wired.\n\n3. **Upstream Frigade state is preserved on partial failure.** Never auto-delete a server-side flow to \"recover\" from a downstream failure. If flow creation succeeded but code wiring failed, report what succeeded and what failed, and offer an explicit retry path or user-initiated cleanup (`recipes/delete-flow.md`). The skill does not silently unwind server state.\n\n4. **Consistency between server and code.** Deleting a flow also removes in-code `<Flow flowId=\"...\" />` / `<Tour flowId=\"...\" />` / hook references. Renaming a flow ID updates both the server-side flow **and** every code site that references it. If code cannot be safely updated (e.g., the flow ID is constructed dynamically, is referenced from a file the skill can't parse, or lives in an unsupported framework), refuse the rename and explain why.\n\n5. **Every write op logs to `.frigade/skill.log`** in the host repo. Log entries: ISO timestamp, operation name, request (with `Authorization` REDACTED), response body, and any recovery taken on failure. `.frigade/skill.log` is gitignored by the setup recipe. Reads are not logged — only writes (create, update, delete, publish, promote, reset).\n\n6. **Confirmation prompts use the canonical format.** Exact wording: `\"About to <verb> <target> in <environment>. Confirm? (y/n)\"`. The verb and target come from the matching row in `reference/operations.md`. Anything other than `y`/`yes` aborts — no partial state, no \"well I already did step 1\".\n\n7. **Recipe-based execution.** For every user intent, consult the dispatch table, read the matched recipe end to end, then follow it. Do not improvise multi-step operations. If the matched recipe is a stub (short file, no concrete steps) and the user's request needs depth the stub doesn't cover, extend the pattern from the closest fully-authored recipe (`create-announcement.md`, `create-tour.md`, `link-flows.md`, `promote-to-prod.md`, `reset-user.md`, `first-run-setup.md`) and surface that you're extrapolating so the user can sanity-check.\n\n8. **Prod is promote-only; steer away from direct prod authoring.** Never create, update, publish, or deactivate a flow or collection *directly* against the prod key as a first move. When the resolved target env is `prod` and the op is authoring a flow or collection (not a read, not a promotion, not a destructive delete/reset — see the covered-ops list in `reference/operations.md` §\"Prod is promote-only\"), emit the **prod steer** first: explain that the change belongs in dev and should reach prod via promotion, offer to do exactly that, and require the explicit typed override `edit prod directly` before proceeding. `y`/`yes` alone does **not** satisfy this gate — the override phrase must be typed verbatim. The promotion recipes themselves (`promote-to-prod.md`, `promote-collection-to-prod.md`) are the sanctioned prod-write path and are **not** subject to the steer; they use the normal dev→prod confirmation.\n\n9. **Flow slugs are always backend-generated — never invent one on create.** When creating a flow (`POST /v1/flows`), **omit the `slug` field entirely**. Frigade assigns every new flow a unique slug of the form `flow_<nanoid8>`; the human label lives in `name`, not the slug. Do not derive a slug from the title, do not kebab-case anything into a slug, and do not run a \"slug collision\" pre-check — there is nothing to collide with. After the create call, read the server-assigned `slug` from the response and use **that** value for every code-wiring reference (`<Frigade.* flowId=\"flow_...\" />`), dashboard URL, and log entry. The **only** ops that legitimately send a slug are cross-environment promotion (`promote-to-prod.md`) and duplication (`duplicate-flow.md`), which replicate an existing, already-valid `flow_...` slug — never a freshly-invented one. (The backend enforces this too: a create body whose slug does not already start with `flow_` is ignored and a fresh `flow_...` slug is generated.)\n\n## Framework support\n\n- **React (plain):** supported via the vanilla `<FrigadeProvider>` + component pattern. See the relevant recipe's \"wire into React\" section and `reference/sdk-react.md`.\n- **Next.js App Router (≥13):** supported. See `reference/next-app-router.md` for provider placement, server/client boundaries, and env var wiring.\n- **Next.js Pages Router:** supported. See `reference/next-pages-router.md` for `_app.tsx` wiring and API route patterns.\n- **Other frameworks (Vue, Remix, SvelteKit, React Native, Angular, Astro, etc.):** not yet. The skill will happily create flows server-side, but code-emission stops at the framework check. It reports:\n\n  > Flow is live in Frigade but I can't automatically wire it into this framework — manual setup: https://docs.frigade.com/quickstart\n\n  Flow creation, update, delete, and promotion still work end-to-end — only codebase wiring is affected.\n\nThe framework detection happens in `recipes/first-run-setup.md` and is re-checked by every wiring-capable recipe before it emits code.\n\n## When a request doesn't map cleanly\n\nIf a user's request does not map cleanly to a row in the dispatch table, do not silently improvise. Tell the user which recipe you think is closest, propose an extension of that pattern, and wait for confirmation before executing.\n"
}