# Instrucțiuni pentru un agent care conduce PhotoCraft

Citește acest fișier înainte să editezi o imagine. PhotoCraft nu se conduce din pagina web. Se conduce prin serverul MCP al aplicației, pe calculatorul utilizatorului. Varianta din browser nu are canal de control.

Documentele complete, copiate local, sunt:

- Unelte MCP: /agent/docs/photocraft/mcp.md
- Protocolul de control (comenzi, dialoguri, pointer): /agent/docs/photocraft/control-protocol.md
- Ghidul de contribuție, dacă modifici codul: /agent/docs/photocraft/AGENTS.md

## Cum ești legat

Procesul `photocraft-cli mcp` vorbește pe stdin/stdout, protocol MCP. Două moduri:

1. Headless: editezi documentul fără fereastră. Pornește cu rădăcini de fișiere:
   `photocraft-cli mcp --automation-read-root <dosar> --automation-write-root <dosar>`
2. Punte către aplicația deschisă: `photocraft-cli mcp --bridge 127.0.0.1:<port>`. Uneltele de interfață (`ui_inspect`, `ui_screenshot`) cer aplicația desktop pornită cu `--control`. Canalul ascultă doar pe localhost și cere un token.

Fără `--automation-read-root` nu ai voie să citești fișiere. Fără `--automation-write-root` nu ai voie să scrii. Căile trebuie să rămână în dosarul acordat. Nu cere căi absolute în afara lui și nu folosi `..`.

## Unelte pe care le ai

- `command_list` — lista de comenzi, parametrii și dacă sunt active. Filtre: `filter`, `enabled_only`. Apeleaz-o înainte să inventezi un id.
- `command_run` — `id`, `params` opțional, `wait` opțional. Parametrii sunt cei ai motorului, nu ai tăi.
- `command_batch` — pași în ordine. La eroare se oprește. Pașii reușiți rămân aplicați; nu există rollback.
- `doc_inspect` — straturi, istoric, selecție. Fără document, rezultatul este `document: null`.
- `render_preview` — PNG, `max_side` implicit 1024, maxim 2048.
- Resurse: `photocraft://document` și `photocraft://commands`.

Argument necunoscut: eroare JSON-RPC `-32602`, înainte de execuție. Eșecul unei unelte vine cu `isError: true`.

## Reguli de lucru

1. Dacă nu există document, creează unul sau deschide unul din rădăcina de citire. `needsDocument: true` înseamnă că primul pas este un document nou sau deschis, nu că comanda e stricată.
2. Înainte de un experiment, duplică: `command_run` cu `image.duplicate` și `params` `{}`, sau `history.newDocument`. Editează copia.
3. Deschide și salvează prin metodele cu rădăcină (`app.open`, `app.save` pe canalul de control). `file.open`, `file.save`, `file.saveAs` și `file.saveACopy` sunt refuzate: folosesc sistemul de fișiere din afara rădăcinii.
4. Nu salva peste un fișier existent la exportul video. Anularea nu șterge fișiere din afara jobului.
5. Undo este `edit.undo`, o dată pentru fiecare intrare din istoric. Nu anulează fișiere deja scrise pe disc. După un batch eșuat, inspectează documentul înainte să reîncerci.
6. Nu inventa id-uri de comenzi. Ia-le din `command_list`. Exemple reale: `file.new` cu `width`, `height`, `mode`, `depth`, `background`; `layer.new.layer`; `layer.newAdjustmentLayer.hueSaturation`; `paint.stroke`; `select.rect`; `document.inspect`.
7. Un filtru lung poate fi un job. Pe canalul de control, `wait: false` întoarce `{job, pending: true}`; starea se citește cu `jobs.list`, oprirea cu `jobs.cancel`.
8. Imaginile utilizatorului rămân în dosarul lui. Nu le copia în altă parte și nu le trimite la un serviciu.

## Celelalte aplicații

Același tip de legătură există pentru VectorCraft, LightCraft, EffectCraft, DesignCraft, PdfCraft, FigCraft, WordCraft, DeckCraft, GridCraft, SoundCraft și CADCraft. Înlocuiește numele binarului (`vectorcraft-cli`, `lightcraft-cli`, …) și citește `/agent/docs/<aplicație>/mcp.md` înainte de prima comandă.