# AGENTS.md

This file is generated from the FunnelsGrove step contract. Start at [the agent documentation router](docs/funnelsgrove/START-HERE.md), then read the exact page for the step type you are changing.

## Route by task

| Task | Read first |
| --- | --- |
| Add a step | [Add a step](docs/funnelsgrove/recipes/add-step.md) |
| Edit a step | [Edit a step](docs/funnelsgrove/recipes/edit-step.md) |
| Change metadata or routing | [Step metadata](docs/funnelsgrove/contracts/step-metadata.md) and [flow routing](docs/funnelsgrove/contracts/flow-routing.md) |
| Add a locale or translate visitor copy | [Localization](docs/funnelsgrove/contracts/content-answers.md#localization) |
| Add or edit choices | [Content and answers](docs/funnelsgrove/contracts/content-answers.md) |
| Edit product strategy, plan, or copy | [Content and answers](docs/funnelsgrove/contracts/content-answers.md) |
| Add an experiment | [Add an experiment](docs/funnelsgrove/recipes/add-experiment.md) |
| Edit email capture or analytics | [Analytics events](docs/funnelsgrove/contracts/analytics-events.md) |
| Edit paywall, checkout, or subscription flow | [Payments](docs/funnelsgrove/contracts/payments.md) |
| Edit theme, CSS, layout, or images | [Start here](docs/funnelsgrove/START-HERE.md), [flow routing](docs/funnelsgrove/contracts/flow-routing.md), and [local QA](docs/funnelsgrove/qa/local.md) |
| QA or publish | [Local QA](docs/funnelsgrove/qa/local.md), [analytics QA](docs/funnelsgrove/qa/analytics.md), and [publish QA](docs/funnelsgrove/qa/publish.md) |

## Non-negotiable workflow

1. Read the matching [step-type page](docs/funnelsgrove/steps/INDEX.md).
2. Keep manifest metadata and component metadata identical.
3. Use shared helpers for answers, conversions, checkout, handoff, and routing.
4. Run `fgrove validate` and the relevant manual QA checklist.
5. Publish preview first. Publish production only after explicit approval.

## Sync safety

1. Before edits run `fgrove status`, `git status --short`, and `fgrove github status` when the funnel is GitHub-connected.
2. Never run `fgrove sync down` over changed synced source. Use `--force` only to intentionally discard those local changes.
3. Sync-up atomically patches changed paths through the base draft version, uploads changed `public/` images directly, and safely replays retries. Disjoint remote edits rebase automatically; on a same-path conflict, run `fgrove sync rebase`, review the merge, rerun checks, and retry.
4. GitHub-connected changes use git push, `fgrove github pull`, terminal status, then publish; never use `fgrove sync up` for the same diff. Non-GitHub funnels use `fgrove sync up`.
5. Use `fgrove env pull` when only the ignored `.env` must be refreshed. Environment files never belong in synced source.

Contract version: `3`

Contract hash: `d761e91d5ac6ff9e72c6d49c5bcd014270912473a66f99c49d726c65998085cf`

## Project-specific context

If an unmanaged `AGENTS.project.md` exists, read and apply `AGENTS.project.md` after this managed contract. It may add product-specific constraints, but if it conflicts with this bundle, the managed contract wins. The docs generator never creates, hashes, copies, overwrites, or deletes that file.