photofresco 0.0.0-stage → 0.1.2

package/CLI.md

@@ -0,0 +1,192 @@
+# PhotoFresco command line (pf-agent-platform-nkwn.16)
+
+`photofresco <command>` drives a PhotoFresco window you approve from scripts and agents: open an
+image from a folder you granted, run a saved workflow on it, export the result, inspect status and
+stop. It is a thin layer over the local connector ([CONNECTOR.md](CONNECTOR.md)), the same one the
+MCP server (`photofresco mcp`, [MCP.md](MCP.md)) uses: the editor in the window does all the
+editing, and the connector enforces pairing, permissions and folder grants. What it runs, sends and
+fetches: [DISCLOSURE.md](DISCLOSURE.md).
+
+Status: implemented and verified (unit and process tests, the real editor session layer, and a
+headless real-browser run). **Not published**: the npm package is a later release step (`.39`,
+owner approval pending), so run it from a checkout until then (nothing to install):
+
+```sh
+alias photofresco="node $PWD/agent/src/bin/photofresco.js"
+```
+
+A Chromium-based browser (Chrome, Edge or Chromium 120+) must be installed, or pass `--browser`
+(or set `PHOTOFRESCO_BROWSER`) to a Chrome for Testing binary.
+
+## Example
+
+```sh
+photofresco connect --read ~/Pictures --write ~/Pictures/PhotoFresco
+photofresco run warm.json --open ~/Pictures/beach.png --input amount=0.6 \
+  --export ~/Pictures/PhotoFresco/beach-warm.png
+photofresco stop
+```
+
+1. `connect` opens PhotoFresco in its own browser window and prints a **connection code**. Check
+   that the window shows the same code and click **Allow**, then choose the permissions in the
+   Permissions dialog (the CLI asks for Read, Edit and Export by default). `connect` returns once
+   you decided; it exits 75 if you have not decided within `--wait` seconds (run it again to keep
+   waiting).
+2. Later commands reuse that window and session. `run` opens the image (a new tab), runs the
+   workflow through the editor's workflow engine (`workflow.run`, the Actions panel's engine) and
+   writes the export only after its SHA-256 matched.
+3. `stop` ends the session, closes the window and stops the connector. `disconnect` ends only the
+   session; the window stays open for you.
+
+Verified output of the same flow (`docs/e2e-runs/pf-agent-platform-nkwn.16-20261009/human-run.txt`):
+
+```text
+$ photofresco run invert.json --input opacity=0.5 --export out/sunset-half.png
+Workflow "Invert" succeeded: 2/2 steps, 2 edits (run run_…, document doc_…)
+Exported …/out/sunset-half.png (png, 2008 bytes, sha256 2129b3c3741e784c…)
+```
+
+A workflow file is the portable document `workflow.export` or the Actions panel produces
+(`photofresco.workflow` version 1, see docs/agent-interface.md "Workflows"). `--action <id>` runs
+an action saved in the editor instead.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `connect` | Start the connector if needed, open PhotoFresco and pair (you click Allow) |
+| `status` | Connector, window, session, permissions and granted folders (`running: false` when stopped) |
+| `request-access <list>` | Ask for more permissions (`read,edit,export,external-write,spend`) |
+| `documents` | Open documents with IDs and revisions |
+| `attach <document-id>` | Target another open document |
+| `open <file>` | Open an image (PNG, JPEG, WebP, GIF, BMP, AVIF, PSD/PSB, `.pfd`, ≤ 32 MiB) from a granted folder in a new tab |
+| `run <workflow.json>` | Run a workflow (or `--action <id>`) on the session document; `--open`, `--export` around it |
+| `export <file>` | Export the document (PNG, PSD or `.pfd`, from the extension or `--format`) into a granted folder |
+| `exec <op> [params-json]` | Run one editor operation (`layer.add` or its tool name `layer_add`) |
+| `outcome <request-id>` | The retained result of an earlier request, after a lost connection |
+| `ops [prefix]` | Operations this session may run; the public catalog before connecting (`--catalog` forces it) |
+| `describe <op>` | An operation's description, permissions, effects and parameter schema |
+| `disconnect` | End the session; window and connector stay |
+| `stop` | End the session, close the window and stop the connector |
+| `mcp` | The MCP server ([MCP.md](MCP.md)) |
+
+`photofresco <command> --help` lists each command's options. The main ones:
+
+| Option | Command | Meaning |
+|---|---|---|
+| `--read <folder>`, `--write <folder>` | connect | Folders this session may open from / export into (repeatable; grants add up while the connector runs) |
+| `--overwrite` | connect, run, export | On connect: exports may replace files in `--write` folders. On run/export: replace this file |
+| `--grant <list>` | connect | Permissions to ask for (default `read,edit,export`; `none` asks for nothing) |
+| `--client <name>` | connect | Shown in the window as "<name> via CLI" (default `Terminal`) |
+| `--wait <seconds>` | connect, request-access | How long to wait for your decision (default 170, at most 180) |
+| `--profile <folder>`, `--browser <path>` | connect | Browser profile (`ephemeral` for a throwaway one) and browser; only when the connector starts |
+| `--input name=value`, `--inputs <file>` | run | Workflow inputs; values parse as JSON when they can (`0.6`, `true`, `"text"`), else as text |
+| `--consent <step-id>` | run | Allow an irreversible barrier step (export, upload, paid AI, tab lifecycle) |
+| `--on-failure stop\|rollback` | run | Keep the partial result (default) or roll the run's edits back |
+| `--request-id <id>` | run, exec | Your ID for `outcome` |
+| `--json` | all | One JSON object on stdout, also on failure ([result.schema.json](src/cli/result.schema.json)) |
+| `--include-data` | all | Keep image data (base64, data URLs) in results; omitted by default |
+| `--data-dir <folder>` | all | Connector data folder (default `PHOTOFRESCO_DATA_DIR`, else the per-OS folder in DISCLOSURE.md) |
+
+Development only: `connect --editor-url http://127.0.0.1:<port>/app/ --allow-loopback-editor`.
+
+## Exit codes and JSON
+
+| Code | Meaning |
+|---|---|
+| 0 | Success |
+| 1 | Unexpected internal error |
+| 2 | Usage: bad arguments, unreadable or unsupported workflow file, unknown operation. Nothing ran |
+| 3 | No connector or session, pairing denied/expired, browser or editor unavailable |
+| 4 | A path was refused (not granted, escapes its folder, exists, too large, unreadable). Nothing ran |
+| 5 | The editor refused or failed the operation or workflow (permission, revision, failed step). Nothing was written |
+| 6 | Reading the export back failed or did not match its SHA-256. Nothing was written |
+| 7 | Writing the file failed. The target was not replaced |
+| 8 | Canceled (Ctrl-C, or Stop in the window). The document keeps the partial result |
+| 75 | Still waiting for you in the window; run `connect` again |
+
+With `--json` every command prints `{ "ok", "command", "exit_code", … }`; failures add
+`error { code, message, hint, stage? }` plus whatever already happened (for `run`: the opened
+file, the run record with each step's status, the run ID). Human output goes to stdout, errors and
+the connection code to stderr. Results never contain keys, and image payloads are replaced by
+`[omitted: N bytes …]` unless `--include-data`, so the JSON is a reproducible log of what ran
+(workflow SHA-256, inputs, steps, document revision, exported file SHA-256).
+
+## Cancellation and lost connections
+
+- **Ctrl-C** during `run`, `exec`, `open` or `export` ends the session (the connector's `close`,
+  same as Stop): the editor stops before the next workflow step, keeps what was done as an
+  inspectable checkpoint and the CLI exits 8. Reconnect (`connect`, a new Allow), then inspect
+  (`exec workflow.runs`) or roll back (`exec workflow.rollback '{"run_id":"…"}'`). The session
+  protocol has no per-request cancel yet, which is why the whole session ends. A second Ctrl-C
+  exits immediately. Ctrl-C while `connect` waits only stops waiting (exit 130); the request stays
+  in the window until you answer it or it expires.
+- **A lost connection** (the CLI killed, the terminal closed) cancels nothing: the editor finishes
+  the request. `outcome <request-id>` returns its result; the document stays open in the window.
+- **Stop** in the window, closing it or reloading ends the session; running requests fail as
+  canceled or `session_ended` (exit 8 or 3).
+
+## How invocations share one session (attach protocol)
+
+`connect` starts a background **connector process** (`photofresco __daemon`, detached, no
+console) for the data folder when none runs. It owns the connector (surface `cli`), its browser
+window and the paired session. Every command connects to it, makes its calls and disconnects. It
+exits on `stop`, when you close its browser window, on SIGINT/SIGTERM/SIGHUP, or after one minute
+with no browser and no client (for example after a failed browser start).
+
+Security model (same as `.14`; adapters add no authorization of their own):
+
+- **No network listener.** A Unix domain socket `<data dir>/cli/connector.sock` (a named pipe
+  `\\.\pipe\photofresco-cli-<hash>` on Windows, not verified). No TCP, WebSocket or HTTP server.
+- **Local user only.** `<data dir>/cli` must be a real directory owned by you with mode 0700; both
+  sides check it and refuse otherwise (`ipc_insecure`). The socket is 0600.
+- **Attach key.** Each start writes 32 random bytes (hex) to `<data dir>/cli/attach.key` (0600);
+  a connection must present it in its first message, compared in constant time. Defence in depth
+  against a mis-permissioned folder, not a boundary against code running as you (out of scope,
+  as in CONNECTOR.md).
+- **Explicit pairing.** Attaching to the process grants nothing in the editor: the session exists
+  only after your Allow, and the editor enforces the permissions you granted on every operation.
+  Folder grants come from `connect --read/--write` and accumulate while the process runs.
+  An agent that can run any shell command as you is not contained by folder grants.
+- One connector process per data folder (a lock file; `already_running`); a stale socket left by a
+  crash is replaced. Use `--data-dir` (or `PHOTOFRESCO_DATA_DIR`) for parallel instances.
+
+Wire format (attach protocol 1, for `.47` SDKs and other local clients): newline-delimited
+JSON-RPC 2.0 over that socket, one message per line, requests ≤ 16 MiB.
+
+1. First request: `hello { protocol: 1, key, client: { name, version } }` → `{ protocol,
+   connector: { name, version }, channel_protocol, pid }`. A wrong or missing key is error
+   `-32001` and the connection closes; another protocol version is `-32002` with
+   `data.supported`.
+2. Methods mirror the connector API (CONNECTOR.md), params and results unchanged: `status`,
+   `connect`, `close`, `sessionStatus`, `documents`, `attach`, `release`, `operations`,
+   `requestAccess`, `execute`, `outcome`, `importFile`, `exportFile`, `roots`, `addRoot`,
+   `fetchArtifact` (returns `data_base64`, at most 32 MiB). `subscribe` starts `event`
+   notifications carrying connector events (`state`, `pairing`, `session`, `session_ended`).
+   `shutdown` ends the session, closes the browser and stops the process.
+3. Errors: connector and editor failures are `-32000` with `data` = `{ code, message, stage?,
+   details? }` (the connector's error codes); `-32601` unknown method, `-32700` invalid JSON.
+
+Implementation: `src/cli/attach.js` (socket, key, framing, client), `src/cli/daemon.js`
+(connector process), `src/cli/main.js` (commands), `src/cli/exit.js` (exit codes, hints),
+`src/cli/workflow.js` (workflow files).
+
+## Tests
+
+- `npm test` in `agent/` includes `test/cli.test.js`: argument parsing, exit codes, the JSON
+  schema, workflow file checks, socket permissions, attach key/protocol refusals, one process per
+  folder, idle exit, and the real bin spawning, reporting and stopping its connector process.
+- Editor repository: `test/agent-cli.test.mjs` (every command over the real session layer: pairing,
+  workflow run with inputs, export, path and permission refusals, failed step checkpoint, Ctrl-C,
+  lost connection, user Stop, pending pairing, stop) and `scripts/agent-cli-e2e.mjs` (the real bin
+  against a real editor in a headless browser; see the evidence folder above).
+
+## Not included
+
+- Publication (npm, Homebrew tap, GitHub Release binaries): `.39`/`.43`, owner approval.
+- A terminal recording (GIF) for the README and Terminal Trove: after publication.
+- Per-request cancel without ending the session; Windows/Linux runs (implemented, not verified).
+
+## Uninstall
+
+`photofresco stop`, remove the package, then follow DISCLOSURE.md "Uninstall".

package/CONNECTOR.md

@@ -0,0 +1,111 @@
+# PhotoFresco local connector (pf-agent-platform-nkwn.14)
+
+One in-process API (`createConnector`) shared by the MCP server (`.15`, `photofresco mcp`, see
+[MCP.md](MCP.md)), the CLI (`.16`, `photofresco <command>`, see [CLI.md](CLI.md)) and the JSON-RPC
+stdio endpoint (`.47`). Pairing, origin/protocol pinning, revocation and file grants are enforced
+here; adapters add no authorization logic. What it runs, sends and fetches:
+[DISCLOSURE.md](DISCLOSURE.md).
+
+Separate processes reach one running connector through the CLI's **attach path**: a background
+connector process serves this API over a local-user-only Unix socket (0700 folder, 0600 socket,
+per-start attach key; no TCP listener) as newline-delimited JSON-RPC 2.0 whose methods mirror the
+API below. Protocol and security model: CLI.md "How invocations share one session"; `.47` SDKs can
+attach to it or spawn their own process.
+
+## API
+
+```js
+import { createConnector } from 'photofresco' // package name pending .33
+const connector = createConnector({
+  surface: 'mcp',                 // mcp | cli | sdk | vscode (shown to the user, acquisition token)
+  client: 'Claude Code',          // agent name shown as "Claude Code via MCP"
+  roots: [{ path: '/Users/me/Pictures', read: true }, { path: '/Users/me/Exports', write: true, overwrite: false }],
+  // editorUrl, allowLoopbackEditor, browserPath, dataDir, profileDir ('ephemeral'), cwd, env, log, launch
+})
+connector.status()                // sync, no browser: { protocol, connector, surface, state, editor, browser, pairing, session, last_end, roots }
+connector.subscribe((event) => {}) // state | pairing { code, expires_at } | session { status } | session_ended { code, message }
+await connector.connect({ access: { capabilities: ['read', 'edit', 'export'], reason: '…' }, document: 'active', timeout_ms })
+await connector.operations()      // granted ops only
+await connector.execute({ op: 'image.desaturate', params: {}, request_id, expected_revision }) // SessionResponse; refusals are responses
+await connector.importFile({ path: 'photo.png' })                   // doc.open (Edit grant)
+await connector.exportFile({ path: 'out/photo.psd', format: 'psd', overwrite: false }) // Read + Export grants
+await connector.fetchArtifact({ artifact_id, max_bytes })            // verified bytes for MCP resources
+// also: sessionStatus, documents, attach({ document }), release, requestAccess, outcome({ request_id }), roots, addRoot (trusted config only), close, shutdown
+```
+
+- `state`: `idle` (no browser) → `starting` → `ready` (editor open, no session) → `pairing` →
+  `connected`. `connect()` resolves after the user's Allow; concurrent calls share one attempt;
+  when connected it returns the current status. The `pairing` event carries the code to show the
+  user. The editor withdraws an unanswered request after 3 minutes (`timeout_ms` ≤ that).
+- `close()` ends the session from the agent side (same as Stop) and leaves the window open;
+  `shutdown()` also closes the browser.
+- Never expose `addRoot`, `editorUrl`, `browserPath` or `launch` to the model.
+
+## Errors
+
+`ConnectorError { code, message, stage?, details? }` (`toJSON()` for adapters). Editor-side
+refusals keep the editor's codes (`capability_denied`, `stale_revision`, `artifact_expired`, …).
+Connector codes: `invalid_options`, `invalid_request`, `not_connected`, `busy`,
+`browser_not_found`, `browser_unsupported`, `browser_launch_failed`, `profile_in_use`,
+`browser_closed`, `page_closed`, `page_reloaded`, `origin_changed`, `editor_unavailable`,
+`editor_unsupported`, `channel_rejected`, `pairing_denied`, `pairing_expired`,
+`pairing_canceled`, `pairing_in_progress`, `session_active`, `session_ended`,
+`path_not_granted`, `path_escape`, `path_invalid`, `file_exists`, `not_a_file`, `file_too_large`,
+`read_failed`, `write_failed`, `artifact_incomplete`, `artifact_hash_mismatch`,
+`artifact_too_large`, `operation_failed`. File workflows set `stage`: `path` (refused before
+anything ran), `operation`, `retrieval`, `write` — the CLI maps these to separate exit codes
+(4–7, CLI.md). The attach path adds `connector_not_running`, `connector_disconnected`,
+`connector_unsupported`, `ipc_unauthorized`, `ipc_insecure`, `ipc_failed` and `already_running`.
+
+## Security model
+
+- **Transport**: a connector-owned browser process with a dedicated profile and the DevTools
+  protocol on `--remote-debugging-pipe`: no TCP/WebSocket listener, so no Host/Origin, DNS
+  rebinding or local-network surface, and other local processes or web pages cannot reach it.
+  Works under the editor's production HTTPS/COOP/COEP; TLS and isolation are untouched.
+- **Page channel** (`src/ops/connectorChannel.ts` in the editor): installed only when the
+  connector's binding exists; the editor takes the binding off the global scope at boot and
+  exposes a frozen `photofrescoConnector.receive`. Every message needs the page's random
+  channel key (sent only through the binding) and a strictly increasing ID: forged and replayed
+  envelopes are refused synchronously and never answered. Session calls also need the
+  per-pairing session key, which ends with Stop, close, consent revocation or reload.
+- **Pinning**: binding calls count only from the tab's main frame, default world, at the pinned
+  editor origin; navigation away ends the session and unsubscribes the binding; protocol
+  version mismatches are refused (`editor_unsupported`). Other tabs have no binding.
+- **Authorization**: the user allows each connection (pairing dialog with a matching code, which
+  also records the page's External agents consent) and grants capabilities in the Permissions
+  dialog; the editor enforces them on every operation (`.11`). The connector cannot answer
+  either dialog and no adapter may expose `session.*` operations.
+- **Files**: canonical (`realpath`) folder grants; traversal and symbolic-link escapes refused;
+  no writes through links; overwrite needs the root grant and the request flag; reads open the
+  checked file without following links; writes publish atomically only after the full artifact
+  was read and its SHA-256 matched.
+- **Threats out of scope**: code already running as the same OS user (it can read the profile or
+  control any browser), and script running inside the editor origin (it can already drive the UI).
+
+## Packaging decision
+
+- Runtime: Node.js ≥ 22. The connector modules import no dependencies; the MCP server
+  (`src/mcp`) uses the official MCP TypeScript SDK (`@modelcontextprotocol/server` 2.2.0, which
+  brings `@modelcontextprotocol/core` and `zod`), bundled readable in `vendor/` so the package and
+  the plugin installs need no `npm install` (pf-agent-platform-nkwn.37; `vendor/README.md`). Browser: an installed Chromium-based browser
+  ≥ 120 (Google Chrome, Microsoft Edge, Chromium), or any Chromium/Chrome for Testing binary in
+  `PHOTOFRESCO_BROWSER`. The connector downloads nothing; machines without one need a browser
+  install first (for example `npx @puppeteer/browsers install chrome@stable`, then point
+  `PHOTOFRESCO_BROWSER` at it).
+- OS: macOS arm64 verified (Chrome for Testing 145). Windows and Linux discovery paths are
+  implemented but not verified. The pipe transport is the same one Playwright uses on all three.
+- Clean uninstall: remove the npm package and the data dir listed in DISCLOSURE.md.
+- One connector per profile at a time (`profile_in_use`); use `profileDir: 'ephemeral'` for parallel
+  instances.
+
+## Tests
+
+`npm test` (node:test: path grants, staged writes, CDP framing, tab pinning, launch with a fake
+browser, API guards, `test/mcp.test.js`: the MCP server as a clean stdio process driven by the
+official MCP client, and `test/cli.test.js`: the CLI and its attach socket); `npm run typecheck`.
+The editor repository adds `test/agent-connector.test.mjs` (real page channel + connector),
+`test/agent-mcp.test.mjs` (MCP over the real session layer), `test/agent-mcp-catalog.test.mjs`
+(the bundled op catalog), `test/agent-cli.test.mjs` (CLI over the real session layer),
+`scripts/agent-connector-browser-tests.mjs`, `scripts/agent-mcp-e2e.mjs` and
+`scripts/agent-cli-e2e.mjs` (real browser).

package/DISCLOSURE.md

@@ -0,0 +1,162 @@
+# What the PhotoFresco connector runs, sends and fetches
+
+Record for pf-agent-platform-nkwn.14, the MCP server (pf-agent-platform-nkwn.15) and the CLI
+(pf-agent-platform-nkwn.16) (source for the `.34` public README section). Observed on macOS arm64
+with Chrome for Testing 145 against a local editor build on 2026-10-09
+(`docs/e2e-runs/pf-agent-platform-nkwn.14-20261009/log.json`,
+`docs/e2e-runs/pf-agent-platform-nkwn.15-20261009/log.json`,
+`docs/e2e-runs/pf-agent-platform-nkwn.16-20261009/log.json` and the `.34` request log
+`docs/e2e-runs/pf-agent-platform-nkwn.34-20261009/demo/user-side.json` in the editor repository).
+Anything not observed in those runs is marked "not verified".
+
+## Runs
+
+- **A Node.js process**: whatever adapter loaded the connector (MCP server, CLI, SDK endpoint).
+  Constructing the connector starts nothing.
+- **One browser process tree, only on `connect()`**: an installed Chromium-based browser
+  (`browserPath` option, else `PHOTOFRESCO_BROWSER`, else Google Chrome, Microsoft Edge or
+  Chromium from their standard install locations). Nothing is downloaded. Exact arguments:
+  `--user-data-dir=<profile> --remote-debugging-pipe --no-first-run --no-default-browser-check --disable-extensions about:blank`.
+  Observed: 7 processes (browser plus its renderer/GPU/utility children), all ending when the
+  connector shuts down or its process exits (the browser exits when its pipe closes).
+- **No other programs**, no shell commands, no installers.
+
+## Browser profile and local files
+
+- **Dedicated profile**: `<data dir>/browser-profile`, where the data dir is
+  `~/Library/Application Support/PhotoFresco Connector` (macOS), `%LOCALAPPDATA%\PhotoFresco Connector`
+  (Windows) or `$XDG_DATA_HOME/photofresco-connector` / `~/.local/share/photofresco-connector`
+  (Linux). It holds what any browser profile holds for photofresco.com (cookies and sign-in if
+  you sign in there, cache, local storage including the editor's acquisition first-touch,
+  editor autosave). Your normal browser profiles are never opened, read or attached to.
+  `profileDir: 'ephemeral'` uses a temporary profile deleted when the browser exits.
+- **Lock file**: `<profile>/PhotoFrescoConnector.lock` (process ID and a random nonce) while the
+  connector owns the profile.
+- **Reads**: only files inside folders granted for reading, only on `importFile`, at most 32 MiB.
+- **Writes**: only inside folders granted for writing, only on `exportFile`: missing subfolders,
+  a hidden temporary `.<name>.<random>.pf-partial` next to the target during the transfer, then
+  the target (atomic rename, or hard link when not overwriting). Existing files are replaced
+  only with the folder's overwrite grant and `overwrite: true`. A transfer whose SHA-256 does not
+  match leaves no file.
+- The connector itself writes no log files (the CLI's connector process does; see below). Its
+  optional `log` callback receives events such as `file_written { path, bytes, sha256 }`; it never
+  receives keys, file contents or pixels.
+
+## Local ports and channels
+
+- **No listening port.** The DevTools protocol runs over the browser's private pipe (file
+  descriptors 3/4 of the browser process). Observed: no TCP listener in any browser process,
+  and no `DevToolsActivePort` file. No HTTP/WebSocket server is started.
+- The connector attaches only to the tab it opened, registers one binding there
+  (`__photofrescoConnector`) and calls one fixed function (`photofrescoConnector.receive`) with
+  data arguments. It evaluates no other page code and never attaches to other tabs.
+- Messages carry a random channel key and, per approved connection, a session key. Neither
+  is put in a URL, a log or an event.
+
+## Fetches and sends
+
+- **The connector process itself makes no network requests.**
+- The browser opens `https://photofresco.com/app/?pf_ref=<surface>` (the editor URL is pinned
+  per connector; a loopback `http://127.0.0.1` editor is allowed only for development). The
+  `pf_ref` value is the non-secret surface name (`mcp`, `cli`, `sdk`, `vscode`) used for
+  acquisition attribution. From there the page loads its assets like a normal visit to the editor.
+- **The connector's window starts with session recording & diagnostics off** (owner decision,
+  2026-10-09). The editor knows the connector opened it (the DevTools binding the connector
+  registers on its own tab; no link or website can set it) and starts that page with nothing
+  allowed in Data & privacy; the menu button reads "Data: local-only" until you click Allow,
+  which adds only External agents. So the page sends PhotoFresco **no session recording, no
+  diagnostics, no copies of the files the agent imports and no acquisition events**, and keeps
+  `pf_ref` unprocessed in the address bar. Observed in the `.39` runs (local build with
+  `?replay=1`, which records the way production does for a normal visit): no `/replay/` or
+  `/telemetry` request from pairing to the end of the session, through import, edits and exports.
+- **Unless you turn Session recording & diagnostics on in Data & privacy** (`/app/privacy/`) in that window: from then
+  on the page sends the session recording (input events, editor commands, document names, typed
+  text except password and email fields) **with a copy of each file opened afterwards in the
+  window, including files the agent imports through the connector** (at most 16 MiB each, 6 per
+  page load), diagnostics (errors, feature events, performance vitals, a device profile) and
+  privacy-safe acquisition events (`referral`, `open`, `edit`, `export`, each `{ channel: 'mcp',
+  source: 'mcp', surface: 'mcp', actor: 'automated' }`, no file names or pixels); the editor then
+  removes `pf_ref` from the address bar. Observed after turning it on: `POST /telemetry`,
+  `/telemetry/acquisition` and `/replay/sessions/<id>/chunks`, all to the editor's own origin.
+  A normal visit to the editor (not opened by the connector) keeps recording on by default.
+- In the observed runs (local build) the tab requested only the editor's own origin. Production
+  third-party requests were not verified.
+- The connector's browser reports `navigator.webdriver = true` (a consequence of the DevTools
+  pipe), so the editor shows no third-party ads there and counts any acquisition events as
+  `automated`.
+- The browser's own background traffic (component updates, safe browsing and similar) follows
+  the installed browser's defaults; not measured.
+- **To the agent** (through the adapter): only what the user's grants allow — session status,
+  document state, previews (pixels), operation results and exported artifacts. Previews and
+  other results returned to an agent go to that agent's model provider under its policy.
+- Paid AI runs only with the Spend grant and the budget the user sets (pf-agent-platform-nkwn.11).
+
+## The MCP server (`photofresco mcp`)
+
+- **Runs** as a Node.js process your MCP client starts and talks to over stdin/stdout. With
+  `npx photofresco …`, npm downloads the package from the npm registry first (npm's fetch, before
+  the server runs); as a Claude Code, Codex, Cursor or Gemini CLI plugin, the client copies this
+  repository and runs `node <plugin folder>/src/bin/photofresco.js mcp`, downloading nothing at start.
+  Runtime dependencies: none to install. The official MCP SDK (`@modelcontextprotocol/server` and
+  `@modelcontextprotocol/core` 2.2.0, `zod` 4.6.5) is bundled readable in `vendor/` (versions,
+  tarball SHA-256 and licenses in `vendor/README.md`); the server uses only its stdio transport. It
+  starts no browser until the agent calls `photofresco_connect`.
+- **No network, no listening port** of its own. Observed: no socket in the server process during a
+  session (`lsof -i`).
+- **Files**: reads its own package files; reads and writes your files only through the folders you
+  pass with `--read`/`--write` (the connector rules above). No log files; it writes to stderr only
+  for startup errors.
+- **To the editor**: the MCP client's own name from its `initialize` message, shown to you as
+  "<name> via MCP", and the surface token `mcp`.
+- **To the agent**: the tool list (before a session, the public operation catalog bundled in the
+  package), connection state and code, session status (target document, revision, grants, the
+  pending request, budget), the folders you granted (paths), the browser's product name, operation
+  results, previews as images, exports as resources (at most 6 MiB each) and the paths and SHA-256
+  of files it wrote. All of it goes to the agent's model provider under that provider's policy.
+- **Ends** when the client closes stdin: the server ends the session, closes its browser and exits.
+  Observed: the browser process was gone after the client closed.
+
+## The CLI (`photofresco <command>`)
+
+- **Runs** two kinds of Node.js process: each command you type (it exits when done), and one
+  background **connector process** per data folder, started by `photofresco connect` (`photofresco
+  __daemon`, detached from the terminal). The connector process owns the browser described above.
+  It ends on `photofresco stop`, when you close its browser window, on SIGINT/SIGTERM/SIGHUP, or
+  after a minute with no browser and no command attached. Runtime dependencies: none beyond Node.js
+  (it reads the bundled op catalog for `ops`/`describe` before a session).
+- **Local channel, no network listener**: `<data dir>/cli/connector.sock`, a Unix domain socket
+  (mode 0600) in a folder that must be owned by you with mode 0700; a named pipe on Windows (not
+  verified). Every connection must present `<data dir>/cli/attach.key` (32 random bytes, 0600,
+  new each start, deleted on stop). Observed: no network socket in the connector process during a
+  session (`lsof -i`), socket 0600 in a 0700 folder.
+- **Files**: `<data dir>/cli/` holds the socket, the key, a lock file (`PhotoFrescoConnector.lock`,
+  process ID and nonce) and `connector.log`: the connector's secret-free events as JSON lines
+  (paths of granted folders and of files read or written, byte counts, SHA-256 of exports, session
+  and browser start/stop), overwritten at each start and capped at 4 MiB. Observed: no key, file
+  content or pixel data in it. It reads workflow and inputs files you name on the command line (at
+  most 1 MiB, JSON only; anything else is refused before it is sent) and your images only through
+  the folders you pass to `connect --read/--write` (the connector rules above).
+- **To the editor**: the name from `--client` (default `Terminal`), shown to you as "<name> via
+  CLI", the surface token `cli` (`pf_ref=cli`; the window starts with recording off, so no
+  acquisition events are sent unless you turn recording on there, then `referral`, `open`, `edit`
+  and `export`, each `{ channel: 'cli', source: 'cli', surface: 'cli', actor: 'automated' }`, no
+  file names or pixels) and the workflow documents and inputs you run.
+- **To the terminal**: results on stdout (with `--json`, one object per command), the connection
+  code and errors on stderr. Image data in results is omitted unless `--include-data`. Whatever
+  runs the CLI (for example an agent) receives that output.
+- **Ends**: `photofresco stop` closes the browser and the connector process. Observed: browser and
+  connector processes gone and the socket removed after `stop`.
+
+## User control
+
+- Each connection needs the user's **Allow** in the editor window (the window shows the same
+  connection code the agent reports); the session starts with no permissions; the Permissions
+  dialog grants them. Stop, closing the window, reloading or leaving the editor origin ends the
+  session; a new connection needs a new Allow.
+- Closing the connector (or its process exiting) closes its browser window.
+
+## Uninstall
+
+Run `photofresco stop` if the CLI is running, remove the package (for example `npm uninstall -g
+<package>`) and delete the data dir above. Nothing else is installed: no services, no login items,
+no browser extensions.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PhotoFresco / Josh Wardini
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/MCP.md

@@ -0,0 +1,155 @@
+# PhotoFresco MCP server (pf-agent-platform-nkwn.15)
+
+`photofresco mcp` is a stdio [Model Context Protocol](https://modelcontextprotocol.io) server. It
+lets an AI agent edit images in a PhotoFresco window on your computer: you see every change, you
+allow the connection, you choose what the agent may do, and you can stop it at any time. It is a
+thin adapter over the local connector ([CONNECTOR.md](CONNECTOR.md)); what it runs, sends and
+fetches is in [DISCLOSURE.md](DISCLOSURE.md).
+
+Status: implemented and verified with the official MCP TypeScript client over stdio (both protocol
+eras) and against a real editor in a real browser. **Not published**: the npm package and the MCP
+Registry entry are a later release step, so the `npx photofresco` lines below work only after that
+release. Until then, run it from a checkout (see "From a checkout").
+
+## Configure your agent
+
+Choose the folders the agent may open files from (`--read`) and save exports into (`--write`).
+Without them the agent can still edit and preview, but cannot touch your files.
+
+> To run from a clone instead, use `node /path/to/photofresco-agent/src/bin/photofresco.js` in place of
+> the `npx -y photofresco@0.1.2` part. Agents such as Cline can follow [llms-install.md](llms-install.md).
+
+**Claude Desktop** — `claude_desktop_config.json` (Settings → Developer → Edit Config):
+
+```json
+{
+  "mcpServers": {
+    "photofresco": {
+      "command": "npx",
+      "args": ["-y", "photofresco@0.1.2", "mcp", "--read", "/Users/you/Pictures", "--write", "/Users/you/Pictures/PhotoFresco"]
+    }
+  }
+}
+```
+
+**Claude Code**:
+
+```sh
+claude mcp add photofresco -- npx -y photofresco@0.1.2 mcp --read ~/Pictures --write ~/Pictures/PhotoFresco
+```
+
+**Cursor** — `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one project): the same
+`mcpServers` JSON as Claude Desktop.
+
+**VS Code** — `.vscode/mcp.json` (one workspace) or **MCP: Open User Configuration** (all): the
+same arguments under `"servers"` with `"type": "stdio"`:
+
+```json
+{
+  "servers": {
+    "photofresco": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "photofresco@0.1.2", "mcp", "--read", "/Users/you/Pictures", "--write", "/Users/you/Pictures/PhotoFresco"]
+    }
+  }
+}
+```
+
+**From a checkout** (before publication; nothing to install, the MCP SDK is bundled in `vendor/`):
+use `"command": "node"` with `"args": ["/path/to/agent/src/bin/photofresco.js", "mcp", "--read", …]`.
+
+These configurations follow each client's documented `command`/`args` stdio format. The server
+itself was exercised with the official MCP client; it has not yet been run inside Claude Desktop,
+Claude Code, Cursor or VS Code (recorded as a release check).
+
+### Options
+
+| Option | Meaning |
+|---|---|
+| `--read <folder>` | The agent may open image files from this folder (repeatable) |
+| `--write <folder>` | The agent may save exports into this folder and new subfolders (repeatable) |
+| `--overwrite` | Exports may replace existing files in `--write` folders (the agent must also ask for it) |
+| `--tools <groups>` | Which operations are listed as tools: `essentials` (default, at most 40 tools with both folder options), `all`, or a comma list (below) |
+| `--profile <folder>` | Browser profile folder, or `ephemeral` for a throwaway one |
+| `--browser <path>` | Chromium-based browser to use (same as `PHOTOFRESCO_BROWSER`) |
+
+A Chromium-based browser (Chrome, Edge or Chromium 120+) must be installed; see CONNECTOR.md
+"Packaging decision".
+
+## How a session goes
+
+1. The agent calls `photofresco_connect`. PhotoFresco opens in its own window with a **connection
+   code**; the agent tells you the same code. Check it and click **Allow**.
+2. The session starts with **no permissions**. The agent asks (Read, Edit, Export; Send and Spend
+   only for cloud and paid AI) and you choose in the **Permissions** dialog. Editing tools appear
+   for the agent as you grant them.
+3. The agent edits with one tool per editor operation; every document edit is in History.
+   Editing yourself pauses the agent until you press **Resume**. **Stop** ends the session.
+
+Initialization and the tool list never start a browser: nothing opens until the agent calls
+`photofresco_connect`.
+
+## Tools
+
+- **Session**: `photofresco_connect`, `photofresco_status`, `photofresco_request_access`,
+  `photofresco_documents`, `photofresco_attach`, `photofresco_disconnect`.
+- **Files** (listed only for configured folders): `photofresco_import_file` (PNG, JPEG, WebP, GIF,
+  BMP, AVIF, PSD/PSB, `.pfd`, at most 32 MiB) and `photofresco_export_file` (PNG, PSD or `.pfd`,
+  written only after the bytes' SHA-256 matched).
+- **Tool groups**: `photofresco_list_tool_groups`, `photofresco_select_tool_groups`.
+- **Operations**: one tool per editor operation, named like `layer_add`, `adjust_add`,
+  `render_region`, `history_undo`, with the editor's exact input schema. Each has a title, a
+  description of its inputs, effect, undo behaviour and required permission, and MCP annotations
+  derived from the operation's metadata (read-only, destructive, open-world). There is no generic
+  "execute" tool, and the user-only controls (pairing, permissions, pause/resume/stop, privacy
+  policy) are never tools.
+
+Before a session the list shows the public catalog of operations; once connected it shows only
+what your grants allow, and changes (`notifications/tools/list_changed`) when you grant, revoke or
+stop. Listing a tool is documentation, not permission: the editor checks every call.
+
+| Group | Operations |
+|---|---|
+| `essentials` (default) | Orient, preview, layers, adjustments, masks, selections, resize/crop, fill, undo, export (30 operations) |
+| `document` | Documents, history, previews, image/canvas/crop, exports and artifacts |
+| `layers` | Layers, masks, layer styles, smart objects, frames, channels |
+| `selection` | Selections, quick mask, paths |
+| `adjustments` | Adjustment layers, filters, liquify, warps |
+| `painting` | Brushes, retouching, fills, gradients, colors, presets, edit commands |
+| `text` | Type, shapes, notes, counts, ruler, slices |
+| `automation` | Actions, workflows, autosave |
+| `workspace` | Panels, view, dialogs, account usage, diagnostics |
+| `cloud` | My Documents, feedback, paid AI (needs Send and Spend) |
+
+### Results
+
+- Previews (`render_preview`, `render_region`, `render_mask`) return the PNG as MCP **image
+  content** plus the coordinate metadata as JSON.
+- `export_artifact` returns a **resource link** `photofresco://artifact/<id>`; `resources/read`
+  returns the bytes (verified against their SHA-256, at most 6 MiB; larger exports go through
+  `photofresco_export_file`). Exports live 10 minutes in the editor.
+- Refusals and failures are tool errors with the editor's code, its message and the next step, for
+  example `capability_denied` → ask with `photofresco_request_access`, `lease_paused` → ask the user
+  to press Resume.
+
+## Agent skill
+
+The package also carries an [Agent Skill](https://agentskills.io/specification),
+`skills/photofresco/` (pf-agent-platform-nkwn.36): instructions that teach skills-capable agents
+(Claude Code, Codex, Cursor and others) when to use PhotoFresco, how to connect and ask for
+permissions, the orient → edit → preview → undo loop, workflows, exports, every error code and the
+`photofresco` command line. It
+does not install or configure the MCP server; set that up as above. Install it with the
+[`skills` CLI](https://github.com/vercel-labs/skills) into the current project (`-g` for your user):
+
+```sh
+npx skills add /path/to/photofresco-checkout/agent -a claude-code -a codex -a cursor
+```
+
+Once the public repository is published (planned as `photofresco/photofresco-agent`), the source
+becomes `npx skills add photofresco/photofresco-agent`. Remove it with `npx skills remove photofresco`.
+
+## Uninstall
+
+Remove the MCP entry from your client configuration, then follow DISCLOSURE.md "Uninstall".