@vibes.diy/prompts 14.3.6 → 14.3.7

package/llms/backend.js.map

@@ -1 +1 @@
-{"version":3,"file":"backend.js","sourceRoot":"","sources":["../../jsr/llms/backend.ts"],"names":[],"mappings":"AAUA,MAAM,CAAC,MAAM,aAAa,GAAc;IACtC,IAAI,EAAE,SAAS;IACf,KAAK,EAAE,YAAY;IACnB,WAAW,EACT,uXAAuX;IAMzX,IAAI,EAAE,CAAC,QAAQ,EAAE,YAAY,CAAC;CAC/B,CAAC"}
+{"version":3,"file":"backend.js","sourceRoot":"","sources":["../../jsr/llms/backend.ts"],"names":[],"mappings":"AAUA,MAAM,CAAC,MAAM,aAAa,GAAc;IACtC,IAAI,EAAE,SAAS;IACf,KAAK,EAAE,YAAY;IACnB,WAAW,EACT,uXAAuX;IAOzX,IAAI,EAAE,CAAC,QAAQ,EAAE,YAAY,CAAC;CAC/B,CAAC"}

package/llms/backend.md

@@ -141,6 +141,7 @@ ctx.appInfo; // { ownerHandle, appSlug } — this app's identity
 ctx.userInfo; // { userHandle } or null — who the handler is acting as
 ctx.secrets; // Record<string,string> — the owner's per-vibe secrets; frozen, {} when none
 await ctx.db.put(doc, { db: "notes", id: "optional-id" }); // resolves to the doc id AFTER commit
+await ctx.db.put(doc, { db: "jobs", id: doc._id, ifRev: doc._rev }); // commits only if nobody wrote the doc since you read it
 await ctx.db.delete(docId, { db: "notes" });
 const docs = await ctx.db.query({ db: "notes", field: "type", key: "note", limit: 100 }); // a filtered page
 const doc = await ctx.db.get("state:cursor", { db: "notes" }); // one doc by _id, or null
@@ -184,6 +185,31 @@ const gh = await ctx.github.fetch("/repos/acme/site/issues", { method: "POST", b
   database that triggered the event is the default.
 - Always `await` db calls; they resolve only after the write commits (or throw
   when the access function denies it).
+- **Every read carries the doc's revision as `_rev`.** `ctx.db.get`, each
+  `ctx.db.query` row and the `onChange` event's `doc` include `_rev` beside
+  `_id`. It is a reserved field the platform fills in on read and never stores,
+  so spreading a read straight into a put is safe.
+- **`ifRev` makes a write a compare-and-set.** `ctx.db.put(doc, { db, id, ifRev: doc._rev })`
+  commits only if the doc is still at the revision you read. Pass `null` to
+  write only if the doc does not exist yet — a deleted doc counts as not
+  existing, just as `get` returns `null` for it. If anyone else wrote the doc in
+  between, even with identical content, the put throws with
+  `err.code === "conflict"` and `err.currentRev` (the revision there now, `null`
+  when the doc is gone), so of several racing handlers exactly one succeeds.
+  The access function still runs on every put, so its `oldDoc.status` check
+  plus `ifRev` is an exclusive claim. A conflict is an answer, not a failure:
+  someone else has the doc, so return. Leave `ifRev` out and a put is
+  last-writer-wins, as always. This is `backend.js` only: `useFireproof`
+  writes in the browser are local-first and keep last-writer-wins.
+
+  ```js
+  try {
+    await ctx.db.put({ ...event.doc, status: "running" }, { db: "jobs", id: event.docId, ifRev: event.doc._rev });
+  } catch (err) {
+    if (err.code === "conflict") return; // another run claimed it first
+    throw err;
+  }
+  ```
 - `ctx.db.get(id, { db })` resolves the single document with that `_id`, or
   `null` when it is missing or deleted. It is the right read whenever you can
   name the document — a tick's state doc, a token lookup, a singleton. Never
@@ -638,6 +664,39 @@ From `App.jsx`, call it with a relative fetch — no host needed:
 const res = await fetch("/_api/rsvp", { method: "POST", body: JSON.stringify({ name }) });
 ```
 
+The platform's answers are worth recognising. `404 backend.js _api: not found`
+means the app has no `fetch` handler to run. When a handler throws, the caller
+gets a `500` whose body names only the error class — `backend.js threw:
+TypeError. Details are in this app's backend log: …` — and the full message is
+written to the app's log, where `vibes-diy app logs <owner>/<slug>` shows it. A
+`502 backend.js failed to run` means the module never started, most often an
+error at the top level of `backend.js`. So a route that expects trouble — an
+upstream that can be down, input that can be malformed — catches it and answers
+`{ ok: false, reason }` with a status the app can show, and the platform's 500
+stays the signal for a bug to fix.
+
+### Who is calling: `ctx.userInfo` comes from the request, never a cookie
+
+Cookies are not read. `ctx.userInfo` is filled in two ways:
+
+- **A caller outside the app** — a script, another agent, a server — sends the
+  person's vibes.diy token as `Authorization: Bearer <token>`. A missing,
+  expired or unrecognised token is not an error: the handler runs with
+  `ctx.userInfo === null`, so a route that needs a person answers `401` itself.
+- **The builder's own `call_own_api` check** (see the debugging skill) arrives
+  already verified, as the app's owner, with no bearer header.
+
+A plain `fetch("/_api/...")` from `App.jsx` sends neither, so for that call the
+handler sees `ctx.userInfo === null`. That is exactly right for the routes the
+app calls for server work — reading a page, calling a service with a secret —
+which should not depend on who is asking. For anything that depends on the
+signed-in person (their own records, their permissions), build the screen on
+the database hooks, which already know who is signed in; a button that "tests
+the API" from inside the app is testing the anonymous path.
+
+Writes a handler makes with `ctx.db.put` still pass through `access.js` as the
+caller, so the app's rules hold for API writes too.
+
 ### Bulk transformations run as a route
 
 A change that touches many stored records is written once, as a named `/_api` route, and run
@@ -755,7 +814,7 @@ backend writes alike). The event:
 
 ```js file=backend.js
 export async function onChange(event, ctx) {
-  // event: { dbName, docId, doc, oldDoc, seq, deleted }
+  // event: { dbName, docId, doc, oldDoc, seq, deleted } — doc carries _id and _rev
   if (event.dbName !== "votes" || event.deleted) return;
   // Maintain a server-authoritative tally the UI reads but users can't forge.
   await ctx.db.put({ _id: "tally-" + event.doc.pollId, kind: "tally", bump: event.seq }, { db: "tallies" });
@@ -772,6 +831,81 @@ Two rules keep change-reactions sane:
    same-database ping-pong is still wasted work. Different db + dbName guard
    makes loops structurally impossible.
 
+### Jobs that finish even when a run crashes
+
+**A job that survives a crash carries its status, its claim and its lease on the document.**
+When each request is a unit of work ("resize every upload", "a queue of jobs
+that keeps going if one fails"), give each job a doc with a `status`, let
+`onChange` claim and finish it, and let a `scheduled` sweep take back expired
+leases. The status guard is what makes writing back to the same database safe:
+the handler acts only on `pending`, so every chain ends after one step.
+
+Every transition is the same move: read the doc (the event's `doc`, or a
+sweep's `query` row), then `put` the next status with `ifRev: doc._rev`. A
+`conflict` means someone else moved the job first, so step aside.
+
+- `access.js` holds the transition table, keyed on `oldDoc.status`:
+  `ctx.requireBackend("onChange")` for `pending → running` and
+  `running → done`; `ctx.requireBackend("scheduled")` for
+  `running → pending` (only once `oldDoc.leaseUntil < Date.now()`) and
+  `→ failed`; anything else throws.
+- The claim puts `running` with `ifRev: event.doc._rev`, so exactly one run
+  claims each job. It also writes a fresh `claimId`, `leaseUntil` and
+  `attempts + 1`.
+- The finish carries the same `claimId`, and `access.js` refuses a `done`
+  whose `claimId` differs from `oldDoc.claimId`. A slow run's lease can be
+  taken back and the job claimed again while it works, and `onChange` cannot
+  read the job back, so the token is how the finish knows it still owns it.
+- The sweep releases an expired lease with `ifRev: job._rev` from its query,
+  so it never overwrites a job that finished between the read and the write.
+- A lost claim returns rather than throws: a redelivered event carries the doc
+  as it first fired, so its `_rev` is stale and the claim conflicts.
+- Key the work's own writes by `jobId:attempt`, since a job can run twice.
+- Keep each run short; a run past 15 minutes is delivered again while it is
+  still going, so chunk long work into `scheduled` ticks.
+
+```js file=backend.js
+export const config = { scheduled: { interval: "30s" } };
+const DB = "jobs", LEASE_MS = 30_000, MAX_ATTEMPTS = 3;
+const rid = () => Math.random().toString(36).slice(2, 10);
+
+// One transition: commit `doc` only if the job is still at revision `ifRev`.
+async function tryPut(ctx, doc, ifRev) {
+  try { await ctx.db.put(doc, { db: DB, id: doc._id, ifRev }); return true; }
+  catch (err) {
+    if (err.code === "conflict") return false; // someone else moved this job first
+    ctx.log("info", "transition refused", { id: doc._id, reason: String(err?.message || err) });
+    return false;
+  }
+}
+
+export async function onChange(event, ctx) {
+  if (event.dbName !== DB || event.deleted || event.doc?.status !== "pending") return;
+  const job = { ...event.doc, _id: event.docId };
+  const claimed = { ...job, status: "running", attempts: (job.attempts || 0) + 1,
+    claimId: rid(), leaseUntil: Date.now() + LEASE_MS };
+  if (!(await tryPut(ctx, claimed, job._rev))) return; // lost the claim — ack, don't retry
+  const output = await doTheWork(job, `${job._id}:${claimed.attempts}`); // idempotent per jobId:attempt
+  await tryPut(ctx, { ...claimed, status: "done", output }); // same claimId, or access.js refuses it
+}
+
+export async function scheduled(event, ctx) {
+  ctx.log("debug", "lease sweep", { at: event.scheduledTime });
+  let after;
+  do {
+    const page = await ctx.db.query({ db: DB, field: "status", key: "running", limit: 500, after });
+    for (const job of page) {
+      if (!(job.leaseUntil < Date.now())) continue;
+      await tryPut(ctx, { ...job, status: job.attempts >= MAX_ATTEMPTS ? "failed" : "pending" }, job._rev);
+    }
+    after = page.next;
+  } while (after);
+}
+```
+
+The full walkthrough, the matching `access.js`, and timings measured on
+production are at https://good.vibes.diy/docs/patterns/doc-state-machines.
+
 ## scheduled — periodic work
 
 Requires a `config` export with a **static string-literal** interval between
@@ -1014,9 +1148,11 @@ a description of the series, never a prediction of the next member of it.
 **Claim the unit of work before you spend on it, not after.** Write the key
 first, then do the expensive, externally visible part: an isolate that dies
 between a finished draft and an unwritten claim comes back and buys the same day
-again. Claiming first means a crashed run is skipped rather than retried, and for
-work like a daily digest that is the better side of the trade — a missing day the
-status doc names beats a double charge nobody notices.
+again. Claiming first means a crashed run is skipped rather than retried. That
+is the named exception to the lease-and-retry jobs under `onChange` above: when a
+duplicate costs more than a gap — a paid call, a post, a message to a person —
+skip rather than retry, because a missing day the status doc names beats a double
+charge nobody notices.
 
 Then say what happened. Write the run's outcome to a status doc the app reads,
 and put the failure detail in `ctx.log("error", …)` for whoever inspects the

package/llms/bluesky.md

@@ -64,7 +64,7 @@ This is the trap that turns a handled refusal into a dead app. The `403` from
 before any `if (body.error)` line can run, and — because an uncaught throw in a
 handler renders as an opaque `404` — the app tells its user it does not exist.
 A 400 from a real XRPC route (a bad `uri`, an unknown actor) *is* JSON, shaped
-`{ "error": "NotFound", "message": … }`, which is worth passing to the screen.
+`{ "error": "InvalidRequest", "message": "Profile not found" }` for an unknown actor, which is worth passing to the screen.
 
 So: status first, JSON second, and a stated reason either way.
 
@@ -80,7 +80,10 @@ async function bsky(ctx, method, params) {
   }
   const body = await res.json().catch(() => null);
   if (!res.ok || !body) {
-    return { ok: false, reason: body?.error ?? "http-error", message: body?.message ?? `HTTP ${res.status}` };
+    // A missing, renamed or deactivated actor is a 400 `InvalidRequest` whose
+    // message says "not found"; name it once here so the screen can say so.
+    const notFound = /not found/i.test(body?.message ?? "");
+    return { ok: false, reason: notFound ? "not-found" : (body?.error ?? "http-error"), message: body?.message ?? `HTTP ${res.status}` };
   }
   return { ok: true, body };
 }
@@ -121,16 +124,17 @@ implying it is complete.
 
 ## 5. Every `/_api` route keeps its reason
 
-An uncaught throw in a handler is folded into an opaque `404 backend.js _api: not found`, so every `/_api` route wraps its work in try/catch and answers with a stated reason.
+An uncaught throw in a handler reaches the app as a bare `500 backend.js threw: <ErrorClass>` — the full message goes to the app's log, never to the caller — so every `/_api` route wraps its work in try/catch and answers with a stated reason.
 
-That fold is why a transient upstream blip reads to the user as "this app does
-not exist". Wrap the body of each route, answer `{ ok: false, reason }`, and log
-the throw with `ctx.log` so an operator can tell "the request never arrived"
-from "the request arrived and died".
+A transient upstream blip is something the person can wait out, and the screen
+can say so only when the route says so. Wrap the body of each route, answer
+`{ ok: false, reason }`, and log the throw with `ctx.log` so an operator reading
+`vibes-diy app logs` sees the route's own account alongside the platform's.
 
 A `not-found` from Bluesky is worth its own reason too: an actor who does not
 exist, a renamed handle, and a deactivated account all come back as a 400 with
-`error: "NotFound"`, and "we could not find @name on Bluesky" is an answer the
+`error: "InvalidRequest"` and a message saying the profile was not found — the
+helpers below name that `reason: "not-found"` — and "we could not find @name on Bluesky" is an answer the
 person can act on — "no data" is not.
 
 ## Complete backend.js
@@ -150,7 +154,10 @@ async function bsky(ctx, method, params) {
   }
   const body = await res.json().catch(() => null);
   if (!res.ok || !body) {
-    return { ok: false, reason: body?.error ?? "http-error", message: body?.message ?? `HTTP ${res.status}` };
+    // A missing, renamed or deactivated actor is a 400 `InvalidRequest` whose
+    // message says "not found"; name it once here so the screen can say so.
+    const notFound = /not found/i.test(body?.message ?? "");
+    return { ok: false, reason: notFound ? "not-found" : (body?.error ?? "http-error"), message: body?.message ?? `HTTP ${res.status}` };
   }
   return { ok: true, body };
 }
@@ -241,7 +248,7 @@ export async function fetch(request, ctx) {
 
     return new Response("not found", { status: 404 });
   } catch (err) {
-    // Without this, the throw is folded into an opaque 404 and the app claims it does not exist.
+    // Without this, the app gets a bare platform 500 naming only the error class — no reason to show.
     ctx.log("error", "bluesky route failed", { path: url.pathname, message: String(err) });
     return json({ ok: false, reason: "handler-failed", message: "Bluesky could not be read just now." }, 500);
   }
@@ -277,7 +284,7 @@ export default function App() {
       fetch(`/_api/feed?actor=${actor}`).then((r) => r.json()),
     ]);
     if (!p.ok) {
-      setProblem(p.reason === "NotFound" ? `We could not find @${who} on Bluesky.` : p.message);
+      setProblem(p.reason === "not-found" ? `We could not find @${who} on Bluesky.` : p.message);
       return;
     }
     setProfile(p.profile);
@@ -288,7 +295,7 @@ export default function App() {
   return (
     <div>
       <input value={handle} onChange={(e) => setHandle(e.target.value)} placeholder="alice.bsky.social" />
-      <button onClick={load}>Look up</button>
+      <button onClick={() => load()}>Look up</button>
       {problem && <p role="alert">{problem}</p>}
 
       {profile && (

package/llms/callai.initial.md

@@ -198,7 +198,7 @@ async function askRecords(question) {
 
 Send an image by passing the prompt as an array of content parts: an `image_url` part carrying the picture beside a `text` part asking the question.
 
-The prompt is the content of one user message, so a plain string means exactly one text part and the array is that same message's parts. Read the picture the user picked with a `FileReader` and hand over the data URL it produces:
+The prompt is the content of one user message, so a plain string means exactly one text part and the array is that same message's parts. Read the picture the user picked with a `FileReader` and hand over the data URL it produces, straight from the camera or photo library — `callAI` shrinks a large photo to a model-friendly size (1568px on its long edge) before sending it, so the app passes the whole picture and leaves the resizing to the platform:
 
 ```javascript
 import { callAI } from "call-ai";
@@ -237,6 +237,8 @@ async function readFlyer(file) {
 
 A string prompt stays the common path for text-only work and behaves exactly as it always has. A model that reads text alone answers an image request with an error naming that model, so an app that asks about a picture hears when the picture went unread — surface that message the way you surface any other `callAI` error.
 
+An image that stays too large even after shrinking is answered at once with an error whose `reason` is `"image-too-large"`; show its message and ask the person to pick a smaller photo.
+
 ## Error Handling
 
 ```javascript

package/llms/callai.md

@@ -198,7 +198,7 @@ async function askRecords(question) {
 
 Send an image by passing the prompt as an array of content parts: an `image_url` part carrying the picture beside a `text` part asking the question.
 
-The prompt is the content of one user message, so a plain string means exactly one text part and the array is that same message's parts. Read the picture the user picked with a `FileReader` and hand over the data URL it produces:
+The prompt is the content of one user message, so a plain string means exactly one text part and the array is that same message's parts. Read the picture the user picked with a `FileReader` and hand over the data URL it produces, straight from the camera or photo library — `callAI` shrinks a large photo to a model-friendly size (1568px on its long edge) before sending it, so the app passes the whole picture and leaves the resizing to the platform:
 
 ```javascript file=App.jsx
 import { callAI } from "call-ai";
@@ -237,6 +237,8 @@ async function readFlyer(file) {
 
 A string prompt stays the common path for text-only work and behaves exactly as it always has. A model that reads text alone answers an image request with an error naming that model, so an app that asks about a picture hears when the picture went unread — surface that message the way you surface any other `callAI` error.
 
+An image that stays too large even after shrinking is answered at once with an error whose `reason` is `"image-too-large"`; show its message and ask the person to pick a smaller photo.
+
 Inside `backend.js`, `ctx.callAI` takes a string prompt.
 
 ## Error Handling

package/llms/fireproof.initial.md

@@ -21,7 +21,7 @@ Each document has an `_id`, which can be auto-generated or set explicitly. Auto-
 
 Use granular documents, e.g. one document per user action, so saving a form or clicking a button should typically create or update a single document, or just a few documents. Avoid patterns that require a single document to grow without bound.
 
-`useLiveQuery` populates and refreshes the UI reactively as data arrives, so you usually render empty states rather than loading spinners. Writes are optimistic and local: `put()`/`save()`/`del()` land in the local replica instantly, and transport or offline failures queue and retry automatically. If the server rejects a synced write, the local optimistic revision converges **server-wins** (it is overwritten by the server's version) — and the **platform** surfaces the reason in a write-fail toast only when it has one; a reason-less rejection converges silently. So do **not** wrap writes in `try/catch` to show denial errors to the user; keep the UI reactive to the store (`useLiveQuery`/`useDocument`) so the converged state is the feedback, and gate write surfaces up front with `useVibe(dbName).can.create/edit/delete` so a disallowed action never renders in the first place.
+`useLiveQuery` populates and refreshes the UI reactively as data arrives, so you usually render empty states rather than loading spinners. Writes are optimistic and local: `put()`/`save()`/`del()` land in the local replica instantly, and transport or offline failures queue and retry automatically. If the server rejects a synced write, the local optimistic revision converges **server-wins** (it is overwritten by the server's version) — and the **platform** surfaces the reason in a write-fail toast only when it has one; a reason-less rejection converges silently. So do **not** wrap plain writes in `try/catch` to show denial errors to the user (a save carrying `_files` is the one exception, covered with the image uploader below); keep the UI reactive to the store (`useLiveQuery`/`useDocument`) so the converged state is the feedback, and gate write surfaces up front with `useVibe(dbName).can.create/edit/delete` so a disallowed action never renders in the first place.
 
 ### Basic Example
 
@@ -611,6 +611,8 @@ Fireproof documents carry attachments under `_files`. Save a `File` (or `Blob`)
 
 Each `_files.<key>` entry shape after save + round-trip: `{ url: string, type: string, size: number, lastModified?: number, file: () => Promise<File> }`. The platform-minted `url` is stable for the lifetime of that file, so the browser cache works normally. For plain `<img>` rendering, prefer `meta.url` — it skips one fetch and lets the browser handle cache and decoding. Use `meta.file()` only when you need the bytes themselves (transcoding, hashing, ML features).
 
+A save that carries `_files` uploads the bytes before the doc lands, so unlike a plain write it rejects instead of converging. Await it inside `try`/`catch` and show `err.message` next to the upload button: the message says in plain words how to get the photo saved (for example, on a private app, sign in as the owner or ask them for write access). Gate the uploader with `useVibe(dbName).can.create` as you would any write surface.
+
 Building an image uploader with `_files`:
 
 App.jsx
@@ -623,7 +625,7 @@ import { Button, Card, CardContent, Input, Label } from "@vibes.diy/look";
 export default function App() {
   const { useDocument, useLiveQuery } = useFireproof("imageUploads");
 
-  const { doc, merge, submit } = useDocument({
+  const { doc, merge, save, reset } = useDocument({
     _files: {},
     caption: "",
     type: "upload",
@@ -631,16 +633,24 @@ export default function App() {
   });
 
   const { docs } = useLiveQuery("type", { key: "upload", descending: true, limit: 12 });
+  const [saveError, setSaveError] = React.useState("");
 
   const onPickFile = (e) => {
     const f = e.target.files?.[0];
     if (f) merge({ _files: { photo: f } });
   };
 
-  const onSubmit = (e) => {
+  const onSubmit = async (e) => {
     e.preventDefault();
     if (!doc._files?.photo) return;
-    submit();
+    setSaveError("");
+    try {
+      // The save uploads the photo first, so it can reject; show why.
+      await save();
+      reset();
+    } catch (err) {
+      setSaveError(err.message);
+    }
   };
 
   const c = {
@@ -664,6 +674,7 @@ export default function App() {
         <Button type="submit" size="lg">
           Upload
         </Button>
+        {saveError && <p role="alert" className="text-destructive">{saveError}</p>}
       </form>
 
       <h3 className="text-lg font-bold mt-8">Recent Uploads</h3>
@@ -695,11 +706,9 @@ App.jsx
     if (f) merge({ _files: { photo: f } });
   };
 
-  const onSubmit = (e) => {
+  const onSubmit = async (e) => {
     e.preventDefault();
     if (!doc._files?.photo) return;
-    submit();
-  };
 =======
   const onPickFile = (e) => {
     const next = {};
@@ -707,11 +716,9 @@ App.jsx
     merge({ _files: next });
   };
 
-  const onSubmit = (e) => {
+  const onSubmit = async (e) => {
     e.preventDefault();
     if (!Object.keys(doc._files || {}).length) return;
-    submit();
-  };
 >>>>>>> REPLACE
 ```
 
@@ -723,11 +730,9 @@ App.jsx
 
 ```jsx
 <<<<<<< SEARCH
-  const onSubmit = (e) => {
+  const onSubmit = async (e) => {
     e.preventDefault();
     if (!Object.keys(doc._files || {}).length) return;
-    submit();
-  };
 =======
   const [errors, setErrors] = React.useState({});
 
@@ -739,10 +744,9 @@ App.jsx
     return Object.keys(newErrors).length === 0;
   }
 
-  const onSubmit = (e) => {
+  const onSubmit = async (e) => {
     e.preventDefault();
-    if (validateForm()) submit();
-  };
+    if (!validateForm()) return;
 >>>>>>> REPLACE
 ```
 

package/llms/fireproof.md

@@ -21,7 +21,7 @@ Each document has an `_id`, which can be auto-generated or set explicitly. Auto-
 
 Use granular documents, e.g. one document per user action, so saving a form or clicking a button should typically create or update a single document, or just a few documents. Avoid patterns that require a single document to grow without bound.
 
-`useLiveQuery` populates and refreshes the UI reactively as data arrives, so you usually render empty states rather than loading spinners. Writes are optimistic and local: `put()`/`save()`/`del()` land in the local replica instantly, and transport or offline failures queue and retry automatically. If the server's access rules reject a synced write, the local optimistic revision converges **server-wins** (it is overwritten by the server's version) — and the **platform** surfaces the reason in a write-fail toast **only when the app's access rules provide one** (`forbidden("…")`); a reason-less rejection converges silently. So do **not** wrap writes in `try/catch` to show denial errors to the user; keep the UI reactive to the store (`useLiveQuery`/`useDocument`) so the converged state is the feedback, and gate write surfaces up front with `useVibe(dbName).can.create/edit/delete` so a disallowed action never renders in the first place.
+`useLiveQuery` populates and refreshes the UI reactively as data arrives, so you usually render empty states rather than loading spinners. Writes are optimistic and local: `put()`/`save()`/`del()` land in the local replica instantly, and transport or offline failures queue and retry automatically. If the server's access rules reject a synced write, the local optimistic revision converges **server-wins** (it is overwritten by the server's version) — and the **platform** surfaces the reason in a write-fail toast **only when the app's access rules provide one** (`forbidden("…")`); a reason-less rejection converges silently. So do **not** wrap plain writes in `try/catch` to show denial errors to the user (a save carrying `_files` is the one exception, covered with the image uploader below); keep the UI reactive to the store (`useLiveQuery`/`useDocument`) so the converged state is the feedback, and gate write surfaces up front with `useVibe(dbName).can.create/edit/delete` so a disallowed action never renders in the first place.
 
 ### Basic Example
 
@@ -585,6 +585,8 @@ Fireproof documents carry attachments under `_files`. Save a `File` (or `Blob`)
 
 Each `_files.<key>` entry shape after save + round-trip: `{ url: string, type: string, size: number, lastModified?: number, file: () => Promise<File> }`. The platform-minted `url` is stable for the lifetime of that file, so the browser cache works normally. For plain `<img>` rendering, prefer `meta.url` — it skips one fetch and lets the browser handle cache and decoding. Use `meta.file()` only when you need the bytes themselves (transcoding, hashing, ML features).
 
+A save that carries `_files` uploads the bytes before the doc lands, so unlike a plain write it rejects instead of converging. Await it inside `try`/`catch` and show `err.message` next to the upload button: the message says in plain words how to get the photo saved (for example, on a private app, sign in as the owner or ask them for write access). Gate the uploader with `useVibe(dbName).can.create` as you would any write surface.
+
 Building an image uploader with `_files`:
 
 App.jsx
@@ -597,7 +599,7 @@ import { Button, Card, CardContent, Input, Label } from "@vibes.diy/look";
 export default function App() {
   const { useDocument, useLiveQuery } = useFireproof("imageUploads");
 
-  const { doc, merge, submit } = useDocument({
+  const { doc, merge, save, reset } = useDocument({
     _files: {},
     caption: "",
     type: "upload",
@@ -605,16 +607,24 @@ export default function App() {
   });
 
   const { docs } = useLiveQuery("type", { key: "upload", descending: true, limit: 12 });
+  const [saveError, setSaveError] = React.useState("");
 
   const onPickFile = (e) => {
     const f = e.target.files?.[0];
     if (f) merge({ _files: { photo: f } });
   };
 
-  const onSubmit = (e) => {
+  const onSubmit = async (e) => {
     e.preventDefault();
     if (!doc._files?.photo) return;
-    submit();
+    setSaveError("");
+    try {
+      // The save uploads the photo first, so it can reject; show why.
+      await save();
+      reset();
+    } catch (err) {
+      setSaveError(err.message);
+    }
   };
 
   const c = {
@@ -638,6 +648,7 @@ export default function App() {
         <Button type="submit" size="lg">
           Upload
         </Button>
+        {saveError && <p role="alert" className="text-destructive">{saveError}</p>}
       </form>
 
       <h3 className="text-lg font-bold mt-8">Recent Uploads</h3>
@@ -669,11 +680,9 @@ App.jsx
     if (f) merge({ _files: { photo: f } });
   };
 
-  const onSubmit = (e) => {
+  const onSubmit = async (e) => {
     e.preventDefault();
     if (!doc._files?.photo) return;
-    submit();
-  };
 =======
   const onPickFile = (e) => {
     const next = {};
@@ -681,11 +690,9 @@ App.jsx
     merge({ _files: next });
   };
 
-  const onSubmit = (e) => {
+  const onSubmit = async (e) => {
     e.preventDefault();
     if (!Object.keys(doc._files || {}).length) return;
-    submit();
-  };
 >>>>>>> REPLACE
 ```
 
@@ -697,11 +704,9 @@ App.jsx
 
 ```jsx
 <<<<<<< SEARCH
-  const onSubmit = (e) => {
+  const onSubmit = async (e) => {
     e.preventDefault();
     if (!Object.keys(doc._files || {}).length) return;
-    submit();
-  };
 =======
   const [errors, setErrors] = React.useState({});
 
@@ -713,10 +718,9 @@ App.jsx
     return Object.keys(newErrors).length === 0;
   }
 
-  const onSubmit = (e) => {
+  const onSubmit = async (e) => {
     e.preventDefault();
-    if (validateForm()) submit();
-  };
+    if (!validateForm()) return;
 >>>>>>> REPLACE
 ```
 

package/llms/spotify.md

@@ -153,8 +153,9 @@ A failure keeps its reason all the way to the screen. "No data" tells the owner
 nothing they can act on, and the five cases above each have a different fix.
 
 Every `_api` route wraps its handler in `try`/`catch` and answers with a stated
-reason, because an uncaught throw leaves the route rendering as an opaque 404 and
-the app looks broken rather than misconfigured.
+reason, because an uncaught throw reaches the app as a bare `500 backend.js threw`
+naming only the error class, and the app can show the person what to fix only
+when the route names it.
 
 ## Complete backend.js
 
@@ -243,7 +244,7 @@ export async function fetch(request, ctx) {
     return new Response("method not allowed", { status: 405, headers: { allow: "GET" } });
   }
 
-  // An uncaught throw renders as an opaque 404, so every route answers with a reason.
+  // An uncaught throw reaches the app as a bare 500 naming only the error class, so every route answers with a reason.
   try {
     if (url.pathname === "/search") {
       const q = (url.searchParams.get("q") ?? "").trim();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibes.diy/prompts",
-  "version": "14.3.6",
+  "version": "14.3.7",
   "type": "module",
   "main": "./index.js",
   "exports": {
@@ -37,9 +37,9 @@
   "license": "Apache-2.0",
   "dependencies": {
     "@adviser/cement": "~0.5.34",
-    "@vibes.diy/call-ai-v2": "14.3.6",
-    "@vibes.diy/identity": "14.3.6",
-    "@vibes.diy/use-vibes-types": "14.3.6",
+    "@vibes.diy/call-ai-v2": "14.3.7",
+    "@vibes.diy/identity": "14.3.7",
+    "@vibes.diy/use-vibes-types": "14.3.7",
     "arktype": "~2.2.3",
     "json-schema-faker": "~0.6.3"
   },