docs + ci: changesets, READMEs, backend contract spec, CI workflow (RUN-384)

- changesets: minor bumps for @runflow-io/sdk (assets.upload, pin
  helpers), @runflow-io/proxy (allowedPaths), @runflow-io/studio
  (shell props, headless mask controller)
- READMEs: SDK upload + pin-editing sections and API surface; proxy
  path-contract table + allowedPaths guide with security note; studio
  "Customizing the shell" + headless mask example; root README links
  the real-estate-studio-sdk reference repo as the worked fork example
  and documents the live proof gate
- docs/plans/run-384-sdk-gaps/backend-contract.md: companion spec for
  backend gaps 2+6 — resolve runflow:// refs at model dispatch (read
  path already does), acceptance criteria, suggested ticket text
- .github/workflows/ci.yml: bun install/build/typecheck/test/lint on
  PRs and main (first CI for this repo; live proof stays manual)

Author: miguelrisero

.changeset/proxy-allowed-paths.md

@@ -0,0 +1,5 @@
+---
+"@runflow-io/proxy": minor
+---
+
+Add `allowedPaths` — an extensible, strictly-matched route allow-list on top of the built-ins (dispatch, run polling, health). Defaults now include the asset-upload pair `rf.assets.upload` needs (`POST /v1/asset-uploads`, `POST /v1/asset-uploads/:id/confirmations`); customer rules are additive, support method arrays and `:param` segments, and reject traversal. Org-data reads (run listing, billing) remain strictly opt-in. The handler now also exposes `PUT`/`PATCH`/`DELETE` for framework route exports. `RateLimitResult`'s `void` member is now `undefined` (type-level only).

.changeset/sdk-assets-pin.md

@@ -0,0 +1,7 @@
+---
+"@runflow-io/sdk": minor
+---
+
+Add `rf.assets.upload(file)` — the browser-safe presigned upload flow (create session → PUT to storage → confirm), returning a model-ready signed HTTPS `url` plus the stable `runflow://assets/{id}` `ref`. Fixes the most common external-fork failure: browser file uploads ending up as `data:` URIs that models reject with a 422.
+
+Export `composePinPrompt`, `composeRegionPrompt`, `pinRegion`, and `PinPoint` — the pin→region prompt convention (3×3 grid baked into the edit prompt) that previously existed only as private copies inside the studio bundle.

.changeset/studio-props-mask.md

@@ -0,0 +1,7 @@
+---
+"@runflow-io/studio": minor
+---
+
+`<StudioShell>` accepts four optional customization props — `tools` (workflow catalogue), `source` (initial asset URL or sample list), `sentinel` (`{ enabled, taskDescription }`), and `copy` (brand/labels) — making vertical forks possible without rebuilding on `./headless`. Zero props renders exactly as before. `mount()` forwards them via the new `props` option.
+
+`./headless` now exports `createMaskController` — the framework-free dual-canvas brush engine (stroke interpolation, coverage, full-resolution thresholded mask blob) the shell itself uses, so headless consumers get working mask creation for inpaint workflows without rebuilding it.

.github/workflows/ci.yml

@@ -0,0 +1,41 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  checks:
+    name: build · typecheck · test · lint
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: 1.3.10
+
+      - name: Install
+        run: bun install --frozen-lockfile
+
+      - name: Build
+        run: bun run build
+
+      - name: Typecheck
+        run: bun run typecheck
+
+      - name: Test
+        run: bun run test
+
+      - name: Lint
+        run: bun run lint
+
+      # The live e2e proof (examples/e2e-proof) needs RUNFLOW_API_KEY and
+      # spends real credits, so it stays a local/manual gate — see
+      # `bun run proof`.

README.md

@@ -62,6 +62,20 @@ Add a changeset for every user-visible change:
 bun changeset
 ```
 
+## End-to-end proof
+
+`bun run proof` exercises the real customer chain — browser SDK →
+`@runflow-io/proxy` → api.runflow.io — across every modality, including
+file upload via `rf.assets.upload` and the proxy allow-list. It needs
+`RUNFLOW_API_KEY` and spends real credits, so it's a local/manual gate
+(not CI). Results land in `.proof/`.
+
+For a worked example of a vertical fork (customize `<StudioShell>` via
+its `tools` / `source` / `sentinel` / `copy` props, or build a custom UI
+on `./headless`), see the
+[real-estate-studio-sdk](https://github.com/runflow-io/real-estate-studio-sdk)
+reference repo.
+
 ## License
 
 MIT

docs/plans/run-384-sdk-gaps/backend-contract.md

@@ -0,0 +1,75 @@
+# Backend contract: resolve `runflow://` asset refs at dispatch (RUN-384 gaps 2 + 6)
+
+**Target repo:** `runflow-monorepo` (api.runflow.io). **Not** implemented in `runflow-js` —
+this document is the companion spec for the backend ticket.
+
+## Current behavior (verified in code)
+
+- **Writes** (`POST /v1/models/{owner}/{slug}/runs`, `POST /v1/comfyui-workflows/.../runs`,
+  batches, admin retries): inline `data:` URIs in `body.input`/`body.metadata` are
+  auto-materialized to R2 and stored as `runflow://assets/{uuid}` refs. This is correct
+  and should stay.
+- **Reads** (`GET /v1/runs`, `GET /v1/runs/{id}`, batch/canonical listings): asset-backed
+  URLs are re-signed and `runflow://assets/{uuid}` refs are resolved to short-TTL signed
+  HTTPS URLs. Also correct.
+- **The gap:** at **model dispatch**, the materialized `runflow://` ref is forwarded to the
+  model worker **as-is**. Worker media validators accept only HTTP(S)/`data:` URIs —
+  `google/nano-banana-pro/edit` (and most non-ComfyUI models) reject with
+  `422: media URL must use HTTP(S) or data URI, got 'runflow'`. ComfyUI workflow file
+  inputs already accept the refs; singleton model dispatch does not.
+
+So the `data:`-materialization *convenience* currently breaks the exact requests it
+rewrites. (The original ticket framed this as "make materialization opt-in"; the better
+fix below removes the need for any flag.)
+
+## Requested change
+
+At the dispatch layer — after materialization, before the input reaches the model
+worker / provider transport — apply the **same resolution the read path already does**:
+
+1. Walk `body.input` (and `metadata` where it feeds workers) for strings of scheme
+   `runflow://assets/{uuid}`.
+2. Resolve each ref org-scoped (existing read-side resolver semantics: load asset, check
+   `access_expires_at`, sign `r2_key`) into a signed HTTPS URL whose TTL comfortably
+   covers worker pull + retries (suggest ≥ the worker's max queue+run window).
+3. Forward the signed HTTPS URL to the worker. Persist the **ref** (not the signed URL)
+   on the run record, as today.
+4. Unknown/foreign-org/expired refs → 422 with a precise message
+   (`asset not found or expired: runflow://assets/{uuid}`) — fail at dispatch, not in
+   the worker.
+
+### Acceptance criteria
+
+- `POST /v1/models/google/nano-banana-pro/edit/runs` with `input.image_urls:
+  ["runflow://assets/{uuid}"]` succeeds end to end (no 422), for both an explicit ref
+  and one produced by `data:` auto-materialization.
+- Read-side responses are unchanged (refs still resolve on read).
+- ComfyUI dispatch behavior unchanged.
+- A run whose ref points at a foreign org's asset 404s/422s without leaking existence
+  details beyond the standard non-leaky pattern.
+
+### Why dispatch-side resolution (not validator changes, not an opt-in flag)
+
+- One implementation point instead of N model-validator changes across providers.
+- Asset refs become first-class on the write path, matching the read path — the SDK can
+  then hand `UploadedAsset.ref` (stable, no TTL) to any model instead of the signed `url`.
+- The `data:` materialization default stays a pure convenience with no footgun, so no
+  config flag is needed.
+
+## Interim state (already shipped in runflow-js)
+
+`rf.assets.upload(file)` returns the **signed HTTPS** url from the confirmation response
+(`routers/asset_uploads.py` signs it server-side), so external forks are unblocked today
+without this change. Once dispatch-side resolution lands, the SDK will document `ref` as
+the preferred long-lived input.
+
+## Suggested ticket
+
+> **Title:** Resolve `runflow://assets/{uuid}` refs to signed HTTPS at model dispatch
+> **Parent:** RUN-384
+> **Why:** Auto-materialized `data:` inputs currently 422 on most singleton models
+> (worker media validators only accept HTTP(S)/data:). Read path already resolves refs;
+> dispatch must do the same so asset refs are first-class across the stack.
+> **Scope:** dispatch layer for `POST /v1/models/.../runs` (+ batches, retries);
+> resolver reuse from the read path; 422 on unknown/expired refs; tests per acceptance
+> criteria above. ComfyUI unchanged.

packages/proxy/README.md

@@ -95,16 +95,43 @@ runflowProxy({
 
 ## Path contract
 
-The proxy accepts only these paths (configurable via `allowedModels`):
+The proxy accepts these paths out of the box:
 
-| Method | Path                              | Purpose          |
-|--------|-----------------------------------|------------------|
-| POST   | `/v1/models/{owner}/{slug…}/runs` | Dispatch a run.  |
-| GET    | `/v1/runs/{uuid}`                 | Poll a run.      |
-| GET    | `/v1/health`                      | Public health.   |
+| Method | Path                                    | Purpose                          |
+|--------|-----------------------------------------|----------------------------------|
+| POST   | `/v1/models/{owner}/{slug…}/runs`       | Dispatch a run.                  |
+| GET    | `/v1/runs/{uuid}`                       | Poll a run.                      |
+| GET    | `/v1/health`                            | Public health.                   |
+| POST   | `/v1/asset-uploads`                     | Create a presigned upload.       |
+| POST   | `/v1/asset-uploads/{id}/confirmations`  | Confirm it (`rf.assets.upload`). |
 
 Everything else returns `403 Not allowed`. Run IDs are validated as
-UUIDv4-shape to block path traversal.
+UUIDv4-shape to block path traversal. Dispatch is additionally gated by
+`allowedModels`.
+
+### Extending the allow-list: `allowedPaths`
+
+```ts
+runflowProxy({
+  apiKey: process.env.RUNFLOW_API_KEY!,
+  allowedPaths: [
+    { method: "GET", path: "/v1/runs" }, // run listing
+    { method: "GET", path: "/v1/billing/balance" }, // billing read
+  ],
+});
+```
+
+Rules are additive over the defaults and matched strictly — full path,
+segment by segment, no prefixes or wildcards. A `:param` segment matches
+exactly one non-empty segment and rejects traversal (`.`, `..`,
+percent-encoded forms). `method` takes a string or an array
+(`["GET", "DELETE"]`); the handler also exports `PUT`/`PATCH`/`DELETE`
+for framework route files.
+
+> **Security:** every matched request is forwarded with **your** API
+> key, so an allowed `GET /v1/runs` exposes org-wide run data to any
+> same-origin browser session. Opt into reads deliberately and pair
+> them with `authenticate` + `rateLimit` in production.
 
 ## License
 

packages/sdk/README.md

@@ -34,6 +34,42 @@ const rf = new Runflow({ baseUrl: "/api/runflow" });
 The browser SDK never sees your API key — it's injected by
 `@runflow-io/proxy` on your server.
 
+### Uploading files
+
+```ts
+const asset = await rf.assets.upload(fileInput.files[0]);
+await rf.models.run("google/nano-banana-pro/edit", {
+  input: { prompt: "remove the price tag", image_urls: [asset.url] },
+});
+```
+
+`upload()` runs the platform's presigned flow (create session → PUT the
+bytes to storage → confirm) and returns `{ id, url, ref, ... }`. `url`
+is a short-TTL **signed HTTPS URL** — pass it straight to any model's
+media inputs. `ref` is the stable `runflow://assets/{id}` reference.
+Works in the browser through `@runflow-io/proxy` (the upload endpoints
+are on its default allow-list). Raw `Blob`s need `{ filename }`; the
+cap is 50 MB.
+
+### Pin-based editing
+
+Edit models like `google/nano-banana-pro/edit` have no `pin_x`/`pin_y`
+inputs — the convention is a region phrase baked into the prompt.
+`composePinPrompt` is that convention, shared with the Studio shell:
+
+```ts
+import { composePinPrompt } from "@runflow-io/sdk";
+
+await rf.models.run("google/nano-banana-pro/edit", {
+  input: {
+    // {x,y} are normalized 0..1; thirds map to upper|middle|lower ×
+    // left|center|right ("upper-left" … "lower-right").
+    prompt: composePinPrompt({ x: 0.25, y: 0.2 }, "remove the price tag"),
+    image_urls: [sourceUrl],
+  },
+});
+```
+
 ## Tools
 
 Declarative model bindings with typed inputs, presets, and outputs:
@@ -109,8 +145,12 @@ information for `buildRequest` and the run helpers.
 - `runflow.models.run(model, body)` — dispatch a run. Model id segments
   are URL-encoded; `..`/empty segments are rejected.
 - `runflow.runs.get(id)` / `runflow.runs.poll(id)` / `runflow.runs.wait(id)`
+- `runflow.assets.upload(file, opts?)` — presigned upload; returns a
+  signed https `url` + stable `runflow://` `ref`.
 - `runflow.tools.run(tool, args)` / `runflow.tools.dispatch(tool, args)`
 - `runflow.health.check()`
+- `pinRegion(pin)` / `composePinPrompt(pin, instruction)` — the shared
+  pin→region prompt contract.
 
 All return well-typed promises; errors are `RunflowError`,
 `RunFailedError`, or `RunTimeoutError`.

packages/studio/README.md

@@ -66,12 +66,31 @@ mount(target: string | HTMLElement, options?: {
   theme?: ThemeMode | ThemeOverrides;
   /** Inject the default <style> into <head>. Default: true. */
   injectStyles?: boolean;
+  /** Shell customization — see "Customizing the shell" below. */
+  props?: StudioShellProps;
 }): { unmount(): void };
 ```
 
-That is the entire option surface today. If you need event callbacks,
-custom tool catalogues, the source picker hidden, or `update()` to
-reconfigure at runtime, those are tracked as follow-ups.
+## Customizing the shell
+
+`<StudioShell>` (and `mount()`'s `props` option) takes four optional
+props; zero props renders the stock studio.
+
+```tsx
+<StudioShell
+  // The workflow catalogue: cards, chat-agent tools, package steps.
+  tools={WORKFLOWS.filter((w) => w.group === "cleanup")}
+  // A starting image URL, or SampleAsset[] to replace the samples.
+  source="https://cdn.example/listing.jpg"
+  // Disable quality evals, or re-template their task description.
+  sentinel={{ enabled: false }}
+  // Brand + labels, shallow-merged over the defaults.
+  copy={{ brandName: "Estates Studio", brandTag: "", assetsTitle: "Listings" }}
+/>
+```
+
+If you need event callbacks or `update()` to reconfigure at runtime,
+those are tracked as follow-ups.
 
 ## Companion endpoints
 
@@ -150,9 +169,24 @@ const { output } = await rf.tools.run(tool, { image: "https://cdn/x.png" });
 ```
 
 The headless entry also exports `WORKFLOWS`, `SAMPLES`, the prototype's
-`runWorkflow` dispatcher, the `sentinelEvaluate` client, and
-`setStudioUrls`. A React state reducer for building a custom shell is
-tracked as a follow-up.
+`runWorkflow` dispatcher, the `sentinelEvaluate` client, `setStudioUrls`,
+and `createMaskController` — the framework-free dual-canvas brush engine
+the shell uses for its mask workflows:
+
+```ts
+import { createMaskController } from "@runflow-io/studio/headless";
+
+const mask = createMaskController({ brushSize: 45 });
+mask.attach(overlayCanvas); // rendered over your image
+mask.syncToDisplay(rect.width, rect.height, devicePixelRatio);
+// pointer events → beginStroke / strokeTo / endStroke; then:
+const blob = await mask.toMaskBlob(img.naturalWidth, img.naturalHeight);
+const asset = await rf.assets.upload(blob, { filename: "mask.png" });
+// → feed asset.url as mask_url to runflow/reference-inpaint etc.
+```
+
+A React state reducer for building a custom shell is tracked as a
+follow-up.
 
 ## License