AI agent guide

This page is written for Cursor, Copilot, Claude Code, and other agents editing FetchCatch workspaces.

Before you edit

1. Read .fetchcatch/AGENTS.md in the consumer repo (bootstrap pointers).
2. Prefer the website docs for human context: https://fetchcatch.com/docs
3. Fetch the doc manifest: https://fetchcatch.com/docs/manifest.json
4. Use the latest doc base URL from the manifest (currently https://fetchcatch.com/docs/v0.1/).
5. Prefer pulling docs as raw markdown: {baseUrl}/ai-agent-guide.md

Discovery file: https://fetchcatch.com/llms.txt

Your scope

Inspect an evaluate run

When a flow run fails, pauses, or returns unexpected output:

fcc run <runId> --json

Review status, step trace, errors, and output. For waiting runs, note waitingForEvent and resume with POST /v1/runs/{runId}/resume.

Task patterns

Add a branch to a flow

1. Read the flow JSON and flow-nodes.md.
2. Add nodes with valid ids (^[A-Za-z_][A-Za-z0-9_]*$).
3. Wire edges; set "when" on condition branches.
4. Add description on new nodes explaining intent.
5. Suggest user run fcc status.

Change a JSONata expression

1. Read expressions-jsonata.md.
2. Edit only the expression or inputs / responseValues fields.
3. Preserve unrelated nodes and positions.

Add a response field

1. Edit response type JSON (response-types.md).
2. Update all decision.responseValues in dependent flows in the same change.
3. Apply response type before flows if applying separately.

Set up CI sync

Copy and adapt sync-and-ci.md and docs/examples/fetchcatch-sync.workflow.yml.

Hard rules

1. Never change resource id GUIDs after they exist on the server.
2. Never fabricate apiSourceId — ask the user to configure API sources in the console or pull existing flows.
3. Leave "publish": false (or omit the field) in flow JSON. Do not set "publish": true — it is legacy; ship with fcc publish or the console instead.
4. Do not delete sync-state.json.
5. Deleting flows: console trash icon, or remove flows/{slug}.json locally and fcc apply. After a console delete, recommend fcc pull.
6. Validate graph structure: one start, reachable nodes, condition edges have when.
7. After edits, recommend: fcc status → review → fcc apply → fcc publish (when the user wants runtime evaluate).

Schema version

All resources use schemaVersion: 1. If you encounter a different version, fetch the matching doc version from manifest.json instead of guessing.

CLI quick reference

fcc pull          # download latest from server
fcc status        # diff local vs remote
fcc plan          # preview push / pull / conflicts
fcc apply --dry-run
fcc apply         # push drafts
fcc publish       # ship callable versions for /v1/evaluate
fcc run <runId> --json   # fetch evaluate run + step trace

Full documentation index

Base: https://fetchcatch.com/docs/v0.1/