# 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](https://fetchcatch.com/docs)
3. Fetch the doc manifest: `https://fetchcatch.com/docs/manifest.json`
3. Use the **latest** doc base URL from the manifest (currently `https://fetchcatch.com/docs/v0.1/`).
4. Prefer pulling docs as raw markdown: `{baseUrl}/ai-agent-guide.md`

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

## Your scope

| In scope | Out of scope |
|----------|--------------|
| `.fetchcatch/flows/*.json` | `~/.fetchcatch/` credentials |
| `.fetchcatch/response-types/*.json` | Server-side C# / infra in product repo |
| `.fetchcatch/project.json` (rarely) | Inventing API source GUIDs |
| Running `fcc status`, `fcc apply --dry-run` | Publishing without user approval (`fcc publish`) |
| `fcc run <runId> --json` to inspect evaluate traces | — |

### Inspect an evaluate run

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

```bash
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](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](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](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](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

```bash
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

| Page | URL path |
|------|----------|
| Getting started | getting-started.md |
| CLI | cli-reference.md |
| Workspace layout | workspace-layout.md |
| Flow schema | flow-graph-schema.md |
| Node types | flow-nodes.md |
| JSONata | expressions-jsonata.md |
| Response types | response-types.md |
| Evaluate API | evaluate-api.md |
| Sync / CI | sync-and-ci.md |

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