@vibes.diy/prompts 14.3.77 → 14.3.78

package/llms/fireproof.initial.md

@@ -1,869 +0,0 @@
-# Fireproof Database API Guide
-
-Fireproof is a document database with live sync, designed to make browser apps easy. On vibes.diy it runs against Firefly: each app holds a local replica (IndexedDB) that IS the database, so writes succeed locally and instantly and then sync in the background. The Firefly server validates every synced write on ingest and can still reject it (a conflict, or a write the platform does not admit); accepted writes stream live to every viewer. Use it in any JavaScript environment with a unified API that works both in React (with hooks) and as a standalone core API.
-
-## Key Features
-
-- **Apps run anywhere:** Bundle UI, data, and logic together.
-- **Real-Time, local-first:** Writes land in the local replica instantly and sync in the background; the server validates each on ingest and streams the accepted ones live to every viewer. `useLiveQuery` keeps the UI in sync as data arrives, so you render empty states rather than loading spinners — but a synced write can still be rejected on ingest (a refusal, a conflict): the local optimistic revision converges **server-wins**, and the platform surfaces a reason only when it has one; a reason-less rejection converges silently. Keep the UI reactive to the store rather than depending on a toast; don't assume every write lands, but don't hand-roll denial errors either.
-- **Unified API:** TypeScript works with Deno, Bun, Node.js, and the browser.
-- **React Hooks:** Leverage `useLiveQuery` and `useDocument` for live collaboration. Note: these are NOT top-level exports — they are returned by the `useFireproof()` hook. Always destructure from `const { useLiveQuery, useDocument, database } = useFireproof("dbName")`. A child component that was handed `database` may call `useFireproof(database)` instead of repeating the name; it is the same database.
-
-**File structure:** A vibe's source is one or more files. `/App.jsx` is the entry point (React component).
-
-Fireproof enforces cryptographic causal consistency and ledger integrity using hash history, providing git-like versioning with lightweight blockchain-style verification. On vibes.diy, a write commits to the local replica immediately and syncs to the Firefly server in the background; the server is the authority on acceptance: it stores each document in a per-document append-only sequence, validates and routes it on ingest, and then syncs it to viewers. Because every synced write is validated server-side on ingest, it can be rejected.
-
-## Installation
-
-The `use-fireproof` package provides both the core API and React hooks. React hooks are the recommended way to use Fireproof in LLM code generation contexts. Fireproof databases persist data through the Firefly server and sync it live to every viewer. Each database is identified by a string name, and you can have multiple databases per application—often one per collaboration session, as they are the unit of sharing. Database names are the app's own to choose — pick a plain camelCase name for every database the app creates; prefix-namespaced names like `media:*` are platform-reserved for the databases platform components bring with them.
-
-Each document has an `_id`, which can be auto-generated or set explicitly. Auto-generation is recommended to ensure uniqueness and avoid conflicts. The server keeps a per-document sequence, so two clients writing the same `_id` at the same time can collide and one write will be rejected — see the note on continuous updates below. Prefer one document per event over many rapid writes to a single hot document.
-
-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 whenever it has one: the app's own `forbidden("…")` text, or the platform's message when a signed-in visitor has no write access to the app (both also reach the app as `writeRejection`, below); 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.
-
-When the server later refuses a write the visitor can act on — a signed-in visitor saving to a private app, say — the platform shows a notice and `useFireproof` hands the app the same reason as `writeRejection` (`{ docId, message }`, or `null` until a save is refused). Render `writeRejection.message` beside the form it came from and call `clearWriteRejection()` when the visitor dismisses it:
-
-```jsx
-function NoteForm({ text }) {
-  const { database, writeRejection, clearWriteRejection } = useFireproof("notes");
-  return (
-    <div>
-      <button onClick={() => database.put({ type: "note", text })}>Save</button>
-      {writeRejection && (
-        <p role="status">
-          {writeRejection.message} <button onClick={clearWriteRejection}>Dismiss</button>
-        </p>
-      )}
-    </div>
-  );
-}
-```
-
-### Basic Example
-
-Wire these visible actions in the first working app, using its own record names. One composer has Add and Ask actions. Add extracts and normalizes facts, saves each record immediately, and shows saved records with edit actions; one item and a pasted batch share this action. Each saved row has Change by sentence: selecting it changes Add to Apply correction, which saves onto that same record id. Ask sends the typed question with the relevant saved records and displays a read-only answer beside the composer. Edit opens the selected row’s populated fields. One parent-owned Undo restores the latest successful creation batch or the previous document from either a sentence correction or a field edit.
-
-With the callai skill available, submitting words extracts and normalizes every task they name, then immediately saves one document per task. The saved task is the confirmation and remains editable, with Undo beside the intake after each save. The parent keeps the ids from the last creation or the previous version from an edit, so intake and saved-detail editors share one Undo action. `useLiveQuery` keeps saved tasks visible; `useDocument` supplies the detail editor only after a record exists. For a plain message whose text is already the whole record, save that text directly.
-
-### `App.jsx`
-```jsx
-import React, { useState } from "react";
-import { callAI } from "call-ai";
-import { useFireproof } from "use-fireproof";
-import { useVibe } from "use-vibes";
-
-const taskSchema = {
-  type: "object",
-  properties: {
-    title: { type: "string", description: "The task in the person's words" },
-    details: { type: "string", description: "Supporting details in the person’s words" },
-  },
-  required: ["title", "details"],
-};
-
-function normalizeTask(raw) {
-  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return undefined;
-  const title = typeof raw.title === "string" ? raw.title.trim() : "";
-  const details = typeof raw.details === "string" ? raw.details.trim() : "";
-  return title.length > 0 ? { title, details } : undefined;
-}
-
-// Single-record extraction and edit-by-sentence share a schema and normalizer.
-async function readTask(sentence, current) {
-  const facts = current === undefined ? {} : { title: current.title, details: current.details };
-  const response = await callAI(
-    `Extract one task’s title and supporting details from the person's words. Update only what the correction mentions when a current task is supplied. Today: ${new Date().toISOString().slice(0, 10)}. Current: ${JSON.stringify(facts)}. Person: ${sentence}`,
-    { schema: taskSchema }
-  );
-  const task = normalizeTask(JSON.parse(response));
-  if (task === undefined) throw new Error("Add a task in your own words and try again.");
-  return task;
-}
-
-// A pasted list uses an array of the same flat document fields.
-async function readTasks(sentence) {
-  const response = await callAI(
-    `Extract every task from these words as a separate item, including when the person names just one task. Keep their title and supporting details. Today: ${new Date().toISOString().slice(0, 10)}. List: ${sentence}`,
-    { schema: { properties: { items: { type: "array", items: taskSchema } }, required: ["items"] } }
-  );
-  const raw = JSON.parse(response);
-  const items = Array.isArray(raw?.items) ? raw.items.map(normalizeTask) : [];
-  if (items.length === 0 || items.some((item) => item === undefined)) {
-    throw new Error("Describe the tasks you want to add and try again.");
-  }
-  return items;
-}
-
-function TaskCard({ task, database, can, onCorrect, onSaved, disabled }) {
-  const { useDocument } = useFireproof(database);
-  const { doc, merge, save } = useDocument(task);
-  const [editing, setEditing] = useState(false);
-  return <article>
-    <h2>{task.title}</h2><p>{task.details}</p><p>{task.dueDate}</p>
-    {can.edit(task).ok && <>
-      <button type="button" disabled={disabled} onClick={() => onCorrect(task)}>Change by sentence</button>
-      <button type="button" disabled={disabled} onClick={() => setEditing(true)}>Edit details</button>
-      {editing && <form onSubmit={async (event) => { event.preventDefault(); if (disabled) return; await save(); onSaved(task); setEditing(false); }}>
-        <input disabled={disabled} aria-label="Task" value={doc.title} onChange={(event) => merge({ title: event.target.value })} />
-        <textarea disabled={disabled} aria-label="Details" value={doc.details} onChange={(event) => merge({ details: event.target.value })} />
-        <input disabled={disabled} aria-label="Due date" type="date" value={doc.dueDate} onChange={(event) => merge({ dueDate: event.target.value })} />
-        <button type="submit" disabled={disabled}>Save details</button>
-      </form>}
-    </>}
-  </article>;
-}
-
-export default function App() {
-  const { database, useLiveQuery, writeRejection, clearWriteRejection } = useFireproof("tasks");
-  const { me, can, ready } = useVibe("tasks");
-  const { docs } = useLiveQuery("type", { key: "task" });
-  const [sentence, setSentence] = useState("");
-  const [current, setCurrent] = useState(undefined);
-  const [pending, setPending] = useState(undefined);
-  const [answer, setAnswer] = useState("");
-  const [busy, setBusy] = useState(false);
-  const [message, setMessage] = useState("");
-  // Creation, sentence correction and detail editing replace this one Undo receipt after a successful write.
-  const [lastWrite, setLastWrite] = useState(undefined);
-  async function submitSentence(event) {
-    event.preventDefault();
-    if (busy || !ready) return;
-    setBusy(true); setMessage("");
-    try {
-      // A failed local batch resumes its unsaved tail without extracting or duplicating earlier records.
-      let operation = pending;
-      if (operation === undefined) {
-        const target = current === undefined ? undefined : docs.find((doc) => doc._id === current._id);
-        if (current !== undefined && target === undefined) throw new Error("Choose a saved task to correct.");
-        const items = target === undefined ? await readTasks(sentence) : [await readTask(sentence, target)];
-        const remaining = items.map((item) => target === undefined
-          ? { _id: crypto.randomUUID(), type: "task", title: item.title, details: item.details, dueDate: "", authorHandle: me?.userHandle }
-          : { ...target, title: item.title, details: item.details });
-        operation = { remaining, created: [], replaced: target };
-      }
-      if (operation.remaining.some((doc) => operation.replaced === undefined ? can.create(doc).ok === false : can.edit(doc).ok === false)) {
-        throw new Error("This task is not editable right now.");
-      }
-      setPending(operation);
-      while (operation.remaining.length > 0) {
-        const doc = operation.remaining[0];
-        await database.put(doc);
-        operation = { ...operation, remaining: operation.remaining.slice(1), created: operation.replaced === undefined ? [...operation.created, doc._id] : [] };
-        setPending(operation);
-        setLastWrite({ created: operation.created, replaced: operation.replaced });
-      }
-      setPending(undefined);
-      setSentence(""); setCurrent(undefined);
-    } catch (error) {
-      // Preserve the words and any unsaved tail on local errors. Synced refusals converge through useLiveQuery.
-      setMessage(error.reason === "refusal" ? "Try describing the task another way." : error.message);
-    } finally { setBusy(false); }
-  }
-  async function askRecords() {
-    if (busy || !ready || pending !== undefined || sentence.trim().length === 0) return;
-    setBusy(true); setMessage("");
-    try {
-      const response = await callAI(
-        `Answer from these records. Today: ${new Date().toISOString().slice(0, 10)}. Records: ${JSON.stringify(docs.map(({ title, details, dueDate }) => ({ title, details, dueDate })))}. Question: ${sentence}`,
-        { schema: { properties: { answer: { type: "string" } }, required: ["answer"] } }
-      );
-      const raw = JSON.parse(response);
-      if (typeof raw?.answer !== "string") throw new Error("Ask your question again.");
-      setAnswer(raw.answer); setSentence("");
-    } catch (error) {
-      setMessage(error.message);
-    } finally { setBusy(false); }
-  }
-  // A new record is one del away; a corrected one is one put of its previous version away.
-  async function undoLast() {
-    if (busy || lastWrite === undefined) return;
-    setBusy(true); setMessage("");
-    try {
-      for (const id of lastWrite.created) await database.del(id);
-      if (lastWrite.replaced !== undefined) await database.put(lastWrite.replaced);
-      setLastWrite(undefined); setPending(undefined); setCurrent(undefined);
-    } catch (error) {
-      setMessage(error.message);
-    } finally { setBusy(false); }
-  }
-  return <main>
-    <h1>Tasks in your own words</h1>
-    <form onSubmit={submitSentence}>
-      <textarea aria-label="Describe tasks, a correction, or ask a question" value={sentence} disabled={busy || pending !== undefined} onChange={(event) => setSentence(event.target.value)} />
-      {current !== undefined && <p>Changing: {current.title} <button type="button" disabled={busy || pending !== undefined} onClick={() => { setCurrent(undefined); setSentence(""); }}>Add a new task</button></p>}
-      <button type="submit" disabled={!ready || busy || sentence.trim().length === 0}>{busy ? "Adding your changes…" : pending !== undefined ? "Retry remaining tasks" : current === undefined ? "Add tasks" : "Apply correction"}</button>
-      <button type="button" disabled={!ready || busy || pending !== undefined || sentence.trim().length === 0} onClick={askRecords}>Ask about tasks</button>
-    </form>
-    <p>{answer}</p>
-    <p role="status">{message}</p>
-    {writeRejection && <p role="status">{writeRejection.message} <button type="button" onClick={clearWriteRejection}>Dismiss</button></p>}
-    {lastWrite !== undefined && <button type="button" disabled={busy} onClick={undoLast}>Undo</button>}
-    {pending !== undefined && !busy && <button type="button" onClick={() => { setPending(undefined); setSentence(""); setCurrent(undefined); }}>Discard unsaved tasks</button>}
-    {docs.map((task) => <TaskCard key={task._id} task={task} database={database} can={can} disabled={busy || pending !== undefined} onSaved={(previous) => setLastWrite({ created: [], replaced: previous })} onCorrect={(doc) => { if (busy || pending !== undefined) return; setCurrent(doc); setSentence(""); }} />)}
-  </main>;
-}
-```
-
-### Editing Documents
-
-Address an existing record by its `_id`. `useDocument(task)` above holds the selected record's editable fields: `merge(updates)` changes the draft, `save()` writes it, and `reset()` restores its initial state. `submit(event)` combines prevent-default, save and reset. Choose the operation that matches the editor's lifecycle. For correction by sentence, pass the current editable fields and the person's correction to the same extraction schema, normalize the result and immediately update the existing document in that submit action with its trusted `_id` and identity fields intact. The callai skill's Text to records example includes that path and pasted lists.
-
-## Required starting records
-
-When a request names records the app must already have — the three projects in a
-studio, a template's starter rows, the rooms in a planner — those records are
-created by the app's own first render through the ordinary write path. That is
-the mechanism, and it is the same one described below for starter content.
-`seed.json` is a separate thing: an optional import a person runs by hand from
-the Data tab. Its sample records also populate the temporary, view-only preview
-while saving is being prepared; they become real saved records only through an
-explicit import. In that file, give each item a stable `key`; its derived identity
-is `seed:<key>`. References to another item use that derived identity. An `_id`
-that repeats the item's own derived identity is equivalent to leaving it out.
-Explicit singleton identities such as `config:board` remain available.
-
-Four rules make it hold:
-
-- **Each required record gets a fixed `_id` you choose** (`"project:atlas"`), so
-  a second write of it lands on the same document instead of minting another.
-- **Create them after `ready` and after `can.create` says yes**, so a write the
-  platform does not admit yet is skipped quietly and retried on a later run.
-- **Write the object before the records that belong to it**, so a dependent
-  document never lands against a container that does not exist yet.
-
-Fixed ids are also what makes two tabs safe. Two browsers opening the app for the
-first time at the same moment both see an empty query and both write; with fixed
-ids those are two writes of the same document, and last-writer-wins converges on
-one copy. Reading the query first and then deciding whether to write is the shape
-that races — the read is empty in both tabs before either write lands.
-
-### How records are shaped
-
-Every record a person writes carries two things beyond its own content: **the id of the object it belongs to**, and **`authorHandle`, the handle of whoever wrote it**. The object itself carries **`creatorHandle`**. Write them at create and leave them alone afterwards — a later editor's handle then always finds the ids already on the doc rather than supplying one.
-
-Each signed-in person also gets **an object of their own with no doc to create**: its id is derived from their handle, `` `default-${me.userHandle}` ``. So someone who has just arrived types once and their first record lands, with nothing for them to set up first — and an app one person keeps for themselves is just this, with one object in it.
-
-```jsx
-import { useFireproof } from "use-fireproof";
-import { useVibe } from "use-vibes";
-
-function Board({ pickedBoardId }) {
-  const { useLiveQuery, database } = useFireproof("boards");
-  const { me, can } = useVibe("boards");
-  // No board doc needed to start: every person has one derived from their handle.
-  const boardId = pickedBoardId ?? `default-${me?.userHandle}`;
-  const { docs: cards } = useLiveQuery("boardId", { key: boardId });
-
-  // A card names its board and its author, both at create.
-  const addCard = (text) => database.put({ type: "card", boardId, authorHandle: me?.userHandle, text });
-  // A board someone explicitly makes names the person who made it.
-  const addBoard = (title) => database.put({ type: "board", creatorHandle: me.userHandle, title });
-
-  return (
-    <div>
-      {cards.map((card) => (
-        <p key={card._id}>{card.text}</p>
-      ))}
-      {can.create({ type: "card", boardId, authorHandle: me?.userHandle }).ok && <AddCardForm onAdd={addCard} />}
-    </div>
-  );
-}
-```
-
-Queries read off those same ids — `useLiveQuery("boardId", { key: boardId })` above — so the fields earn their place immediately rather than being bookkeeping for later.
-
-### Match sample records to the maker's opening query
-
-The initial build's preview-maker context supplies the actual maker handle.
-Use it to evaluate the opening query's group ID when writing `seed.json`.
-For a maker named `mira`, the runtime expression below selects `default-mira`,
-so every sample card in this opening board carries that exact `boardId`:
-
-```jsx
-const boardId = pickedBoardId ?? `default-${me?.userHandle}`;
-const { docs: cards } = useLiveQuery("boardId", { key: boardId });
-```
-
-```json
-{
-  "boards": [
-    { "key": "tent", "type": "card", "boardId": "default-mira", "text": "Blue tent, sleeps four" },
-    { "key": "stove", "type": "card", "boardId": "default-mira", "text": "Two-burner camp stove" },
-    { "key": "lantern", "type": "card", "boardId": "default-mira", "text": "Two rechargeable lanterns" },
-    { "key": "cooler", "type": "card", "boardId": "default-mira", "text": "Wheeled cooler" }
-  ]
-}
-```
-
-Substitute the supplied maker handle in the sample values; keep the app's query
-and real writes driven by the current viewer and selected object. The database
-name, record type, parent references and query filters agree across the sample
-file and opening view. Later edits preserve those parent references.
-The platform labels the temporary preview as sample data; those records reach
-persistent storage only through the person's explicit import.
-
-### Seeding starter data — give each seed a deterministic `_id`
-
-When an app ships with default content — starter slides, template rows, example cards — and writes it into the database on first load, give **each seed document a deterministic `_id`** (`"seed:intro"`, `"seed:" + key`). This makes the seeding write **idempotent**: if it ever runs again, it overwrites the same documents instead of creating fresh copies.
-
-The trap is the live-query empty state. `useLiveQuery` renders empty before data arrives, so `docs.length === 0` is briefly true on **every** fresh load — and a `useRef`/`useState` "already seeded" flag only guards the current session, never the next reload, a second device, or another collaborator. With **auto-generated** `_id`s, each of those re-seeds the full set and duplicate copies pile up without bound. Deterministic `_id`s collapse every re-seed back onto the same N documents.
-
-```jsx
-import React from "react";
-import { useFireproof } from "use-fireproof";
-import { useVibe } from "use-vibes";
-
-// Stable _id per seed, and no Date.now()/random fields — keep the payload
-// constant so a redundant seed is a true no-op, not a churning rewrite.
-const SEED = [
-  { _id: "seed:intro", type: "slide", title: "Welcome", position: 1000 },
-  { _id: "seed:problem", type: "slide", title: "The problem", position: 2000 },
-  { _id: "seed:ask", type: "slide", title: "The ask", position: 3000 },
-];
-
-export default function App() {
-  const { useLiveQuery, database } = useFireproof("deck");
-  const { ready, can } = useVibe("deck");
-  const { docs: slides } = useLiveQuery("position");
-
-  React.useEffect(() => {
-    if (slides.length > 0) return; // already has content — don't seed
-    // Ask `can.create` before writing. A doc type the platform doesn't admit
-    // yet (e.g. one this very edit just introduced — the update binds only
-    // after the whole turn lands) would be rejected: skip quietly now and seed
-    // on a later run instead of spamming errors.
-    if (!ready || !can.create(SEED[0]).ok) return;
-    // Deterministic _id → idempotent. Even if this runs again (another load or
-    // device before the query resolves), it overwrites the same docs instead of
-    // minting new ones, so seed slides never duplicate.
-    SEED.forEach((s) => database.put(s).catch((e) => console.error(e)));
-  }, [slides.length, ready, can, database]);
-
-  return <Deck slides={slides} />;
-}
-```
-
-Don't stamp `Date.now()` or other changing values into seed documents — that makes each re-seed rewrite the doc with new content, churning revisions even though the `_id` is stable. Resource-like docs — categories, profiles, **seeds** — get deterministic `_id`s; event/content docs let `_id` auto-generate.
-
-### Updating Documents in Event Handlers
-
-To update an existing document from a click handler or callback, use `database.put()` directly. Never call `useDocument` inside an event handler — that violates React's Rules of Hooks. Adding a toggle to list items:
-
-### `App.jsx`
-```jsx
-<<<<<<< SEARCH
-  const { useDocument, useLiveQuery } = useFireproof("myLedger");
-=======
-  const { useDocument, useLiveQuery, database } = useFireproof("myLedger");
->>>>>>> REPLACE
-```
-
-### `App.jsx`
-```jsx
-<<<<<<< SEARCH
-          <li key={doc._id}>{doc.text}</li>
-=======
-          <li key={doc._id}>
-            {doc.text}
-            <button onClick={() => database.put({ ...doc, favorite: !doc.favorite })}>
-              {doc.favorite ? "★" : "☆"}
-            </button>
-          </li>
->>>>>>> REPLACE
-```
-
-Never call hooks inside handlers — `const { doc, save } = useDocument({ _id: id })` inside an onClick BREAKS the Rules of Hooks.
-
-### Continuous Controls — `merge()` on every event, `save()` once on commit
-
-A continuous control (slider, drag, color picker, live-typed text bound to one doc) fires many events in quick succession. **Never call `database.put()` or `save()` on every `onChange`** — that floods the server with rapid concurrent writes to the same `_id`, which collide on the per-document sequence and get rejected (`Failed to put document …`). Instead, `merge()` locally on each event to keep the UI live, and `save()` once when the interaction commits (`onPointerUp`, `onBlur`, `onChange` for a range input's final value, or a debounced trailing call). Editing a single doc with a slider:
-
-### `App.jsx`
-```jsx
-<<<<<<< SEARCH
-  const { useDocument, useLiveQuery, database } = useFireproof("myLedger");
-=======
-  const { useDocument, useLiveQuery, database } = useFireproof("myLedger");
-
-  // One shared mix doc; slider updates the UI on every event, persists on commit
-  const { doc: mix, merge: mergeMix, save: saveMix } = useDocument({ _id: "mix:current", level: 50 });
->>>>>>> REPLACE
-```
-
-### `App.jsx`
-```jsx
-<<<<<<< SEARCH
-      <h3>Recent Documents</h3>
-=======
-      <input
-        type="range"
-        min="0"
-        max="100"
-        value={mix.level}
-        onChange={(e) => mergeMix({ level: Number(e.target.value) })} // live, no write
-        onPointerUp={() => saveMix().catch((err) => console.error("save failed", err))} // one write on commit
-      />
-
-      <h3>Recent Documents</h3>
->>>>>>> REPLACE
-```
-
-If you genuinely need to persist mid-drag, debounce the `save()` so at most one write is in flight, and still `.catch()` the rejection. Better yet, prefer one document per event (see the Counter Pattern) over hammering a single hot document.
-
-### Query Data
-
-Data is queried by sorted indexes defined by the application. Sort by strings, numbers, or booleans, as well as arrays for grouping. Use numbers when possible for sorting continuous data. You can use the `_id` field for temporal sorting so you don't have to write code to get simple recent document lists, as in the basic example above.
-
-#### Query by Key Range
-
-Passing a string to `useLiveQuery` will index by that field. Use the key argument to filter by a specific value, or range for bounded queries. Switching from temporal to filtered query:
-
-### `App.jsx`
-```jsx
-<<<<<<< SEARCH
-  const { docs } = useLiveQuery("_id", { descending: true, limit: 100 });
-=======
-  // all docs where doc.agentName === "agent-1", sorted by _id
-  const { docs } = useLiveQuery("agentName", { key: "agent-1" });
->>>>>>> REPLACE
-```
-
-Or query a numeric range:
-
-### `App.jsx`
-```jsx
-<<<<<<< SEARCH
-  const { docs } = useLiveQuery("agentName", { key: "agent-1" });
-=======
-  // docs with agentRating between 3 and 5
-  const { docs } = useLiveQuery("agentRating", { range: [3, 5] });
->>>>>>> REPLACE
-```
-
-#### Counter Pattern
-
-Documents can be updated by multiple clients, and synced later. To create an event counter, don't increment a number on a single doc, instead write a small document per counted event, and query them with an index:
-
-### `App.jsx`
-```jsx
-<<<<<<< SEARCH
-  const { docs } = useLiveQuery("agentRating", { range: [3, 5] });
-=======
-  // The counter's scope: the board being viewed and who is counting (useVibe from "use-vibes", as above).
-  const { me } = useVibe("boards");
-  const boardId = `default-${me?.userHandle}`;
-  // Keyed on the board AND the event name, so one board's count never includes another board's events.
-  const { docs } = useLiveQuery((doc) => [doc.boardId, doc.counter], { key: [boardId, "my-event-name"] });
-  const counterValue = docs.length;
-
-  // Each counted event is its own record, and it names the board it belongs to and who wrote it.
-  function countEvent() {
-    database.put({ type: "count", counter: "my-event-name", boardId, authorHandle: me?.userHandle });
-  }
->>>>>>> REPLACE
-```
-
-This pattern ensures the count is accurate even during sync — each event is its own document, so concurrent writes never conflict.
-
-### Custom Indexes
-
-Use a custom index function to normalize and transform document data, for instance if you have both new and old document versions in your app:
-
-### `App.jsx`
-```jsx
-<<<<<<< SEARCH
-  // The counter's scope: the board being viewed and who is counting (useVibe from "use-vibes", as above).
-  const { me } = useVibe("boards");
-  const boardId = `default-${me?.userHandle}`;
-  // Keyed on the board AND the event name, so one board's count never includes another board's events.
-  const { docs } = useLiveQuery((doc) => [doc.boardId, doc.counter], { key: [boardId, "my-event-name"] });
-  const counterValue = docs.length;
-
-  // Each counted event is its own record, and it names the board it belongs to and who wrote it.
-  function countEvent() {
-    database.put({ type: "count", counter: "my-event-name", boardId, authorHandle: me?.userHandle });
-  }
-=======
-  const { docs } = useLiveQuery(
-    (doc) => {
-      if (doc.type == "listing_v1") return doc.sellerId;
-      else if (doc.type == "listing") return doc.userId;
-    },
-    { key: routeParams.sellerId }
-  );
->>>>>>> REPLACE
-```
-
-#### Array Indexes and Prefix Queries
-
-When you want to group rows easily, you can use an array index key. This is great for grouping records by year/month/day or other paths. The prefix query is a shorthand for a key range:
-
-### `App.jsx`
-```jsx
-<<<<<<< SEARCH
-  const { docs } = useLiveQuery(
-    (doc) => {
-      if (doc.type == "listing_v1") return doc.sellerId;
-      else if (doc.type == "listing") return doc.userId;
-    },
-    { key: routeParams.sellerId }
-  );
-=======
-  const { docs } = useLiveQuery(
-    (doc) => {
-      const date = new Date(doc.date);
-      if (Number.isNaN(date.getTime())) return; // return nothing to skip docs without a valid date
-      return [date.getFullYear(), date.getMonth(), date.getDate()];
-    },
-    { prefix: [2024, 11] } // everything from November 2024
-  );
->>>>>>> REPLACE
-```
-
-#### Sortable Lists
-
-Sortable lists are a common pattern. Use evenly spaced positions and insert between items using midpoint calculation:
-
-### `App.jsx`
-```jsx
-<<<<<<< SEARCH
-  const { docs } = useLiveQuery(
-    (doc) => {
-      const date = new Date(doc.date);
-      if (Number.isNaN(date.getTime())) return;
-      return [date.getFullYear(), date.getMonth(), date.getDate()];
-    },
-    { prefix: [2024, 11] }
-  );
-=======
-  // Query items on list xyz, sorted by position
-  // Note: useLiveQuery('listId', { key:'xyz' }) would be the same docs, sorted chronologically by _id
-  const { docs } = useLiveQuery((doc) => [doc.listId, doc.position], { prefix: ["xyz"] });
-
-  // Each item names the list it belongs to and who wrote it, both at create.
-  async function initializeList() {
-    await database.put({ type: "item", listId: "xyz", authorHandle: me?.userHandle, position: 1000 });
-    await database.put({ type: "item", listId: "xyz", authorHandle: me?.userHandle, position: 2000 });
-    await database.put({ type: "item", listId: "xyz", authorHandle: me?.userHandle, position: 3000 });
-  }
-
-  async function insertBetween(beforeDoc, afterDoc) {
-    const newPosition = (beforeDoc.position + afterDoc.position) / 2;
-    await database.put({ type: "item", listId: "xyz", authorHandle: me?.userHandle, position: newPosition });
-  }
->>>>>>> REPLACE
-```
-
-#### Emit a Row Value
-
-An index function can call `emit(key, value)` with a second argument to store a value beside the key. `rows[].value` is the value you emitted when you pass one, and the whole document when you call `emit(key)` alone. Emit a small summary when a long list renders only a field or two, and read `docs` when you want the documents themselves — `docs` holds the indexed documents whatever the rows carry.
-
-### `App.jsx`
-```jsx
-<<<<<<< SEARCH
-  const { docs } = useLiveQuery((doc) => [doc.listId, doc.position], { prefix: ["xyz"] });
-=======
-  // Rows carry just what this list renders; docs still holds the whole documents
-  const { rows } = useLiveQuery((doc, emit) => emit([doc.listId, doc.position], { label: doc.label }), {
-    prefix: ["xyz"],
-  });
-  const labels = rows.map((row) => row.value.label);
->>>>>>> REPLACE
-```
-
-## Offline writes are on by default (`offlineQueue`)
-
-For signed-in users, writes are **local-first by default**: a `put`/`del` that fails on the network is durably queued on the device (it resolves, stays visible, and syncs to the cloud when you're back online) instead of rolling back. You don't opt in — every signed-in vibe gets this. A refusal or validation rejection is **not** queued: it converges **server-wins** (the local optimistic revision is overwritten by the server's version); the platform surfaces the reason only when it has one, and a reason-less rejection converges silently — so keep the UI reactive to the store rather than depending on a toast. Only transport failures queue and retry.
-
-Pass `{ offlineQueue: false }` for **server-first, fail-fast** writes: a `put` resolves only when the server accepts it, and a network failure rejects immediately with nothing queued. Choose this for **collaborative multi-writer apps** where two people may edit the same doc — sync is blind last-arrival-wins (Firefly has no `_rev`), so a stale write replayed on reconnect can silently overwrite a newer one. When a lost write is safer than a surprise overwrite, opt out.
-
-```js
-// Default (single-user apps): durable offline writes, no config needed.
-const { useLiveQuery } = useFireproof("todos");
-
-// Collaborative app: fail fast instead of queueing a stale write.
-const { useLiveQuery } = useFireproof("shared-board", { offlineQueue: false });
-```
-
-## Anonymous writes (local-first by default)
-
-Letting a logged-out visitor try the app and build a little state before signing in needs **no opt-in** — it is the universal default on every vibe. While logged out, `put`/`del`/`useLiveQuery`/`useDocument` run against the local replica with the identical API — no auth branching in your code — so favorites, a draft, or a scratch list just work. On first sign-in that local state drains automatically into the user's cloud database and then syncs live; nothing is lost if a drain is interrupted. The sign-in and drain-confirmation toast ("saved to your account") is platform-provided chrome — do not build your own "saved"/"synced" notice for it.
-
-The old `{ anonymousLocal: true }` option (and its `migrate` hook) is **deprecated and ignored** — its behavior is now the default, so the runtime warns once and drains any legacy data on its own. Do not emit the flag in new code.
-
----
-
-## Architecture: Where's My Data?
-
-Data lives in a local replica (IndexedDB) that the app reads and writes instantly; that replica syncs to the Firefly server in the background. The server is the authority on acceptance — each synced write is validated on ingest, persisted, and then synced to every viewer who may read it. A write that fails validation or hits a conflict is rejected on ingest: the local optimistic revision converges **server-wins**, and the platform surfaces the reason only when it has one — a reason-less rejection converges silently, so keep the UI reactive to the store rather than depending on a toast. Don't assume the write always lands, but don't hand-roll your own denial error UI — let it converge.
-
-## Using Fireproof in JavaScript
-
-You can use the core API outside a React component — in a plain script or a helper module. Instead of hooks, import the core API directly:
-
-### `App.jsx`
-```jsx
-<<<<<<< SEARCH
-import React from "react";
-import { useFireproof } from "use-fireproof";
-
-export default function App() {
-  const { useDocument, useLiveQuery, database } = useFireproof("myLedger");
-=======
-import { fireproof } from "use-fireproof";
-
-const database = fireproof("myLedger");
-
-// The document API is async — reads and writes both await the server.
-// Writes can fail (refused, conflict, network), so wrap them.
-async function main() {
-  try {
-    const ok = await database.put({ text: "Sample Data" });
-    const doc = await database.get(ok.id);
-    const latest = await database.query("_id", { limit: 10, descending: true });
-    console.log("Latest documents:", latest.docs);
-  } catch (err) {
-    console.error("write failed (refused, conflict, or network):", err);
-  }
-}
->>>>>>> REPLACE
-```
-
-### Working with Files
-
-Fireproof documents carry attachments under `_files`. Save a `File` (or `Blob`) by assigning it to a key on `_files`, and Fireproof handles upload, durable storage, and URL minting for you. After a doc round-trips through the database, each `_files.<key>` entry carries a stable `url` you can drop straight into `<img>`, `<video>`, `<audio>`, CSS `background-image`, etc.
-
-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`
-```jsx
-import React from "react";
-import { useFireproof } from "use-fireproof";
-import { Button, Card, CardContent, Input, Label } from "@vibes.diy/look";
-
-export default function App() {
-  const { useDocument, useLiveQuery } = useFireproof("imageUploads");
-
-  const { doc, merge, save, reset } = useDocument({
-    _files: {},
-    caption: "",
-    type: "upload",
-    createdAt: Date.now(),
-  });
-
-  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 = async (e) => {
-    e.preventDefault();
-    if (!doc._files?.photo) return;
-    setSaveError("");
-    try {
-      // The save uploads the photo first, so it can reject; show why.
-      await save();
-      reset();
-    } catch (err) {
-      setSaveError(err.message);
-    }
-  };
-
-  const c = {
-    page: "bg-background text-foreground font-sans",
-    meta: "text-muted-foreground",
-  };
-
-  return (
-    <div className={`min-h-screen p-6 max-w-lg mx-auto ${c.page}`}>
-      <h2 className="text-2xl font-bold mb-4">Image Uploader</h2>
-      <form onSubmit={onSubmit} className="space-y-3">
-        <Label htmlFor="photo">Photo</Label>
-        <Input id="photo" type="file" accept="image/*" onChange={onPickFile} className="w-full" />
-        <Input
-          type="text"
-          placeholder="Caption"
-          value={doc.caption}
-          onChange={(e) => merge({ caption: e.target.value })}
-          className="w-full"
-        />
-        <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>
-      <div className="grid grid-cols-2 gap-4 mt-2">
-        {docs.map((d) => (
-          <Card key={d._id}>
-            <CardContent>
-              {d._files?.photo?.url && <img src={d._files.photo.url} alt={d.caption || "upload"} className="w-full h-auto rounded-md" />}
-              <p className={`${c.meta} mt-2`}>{d.caption || "No caption"}</p>
-            </CardContent>
-          </Card>
-        ))}
-      </div>
-    </div>
-  );
-}
-```
-
-For multi-file uploads (e.g. `<input multiple>`), build the `_files` map keyed by filename and iterate with `Object.entries(doc._files)` to render each entry.
-
-Adding multi-file support:
-
-### `App.jsx`
-```jsx
-<<<<<<< SEARCH
-  const onPickFile = (e) => {
-    const f = e.target.files?.[0];
-    if (f) merge({ _files: { photo: f } });
-  };
-
-  const onSubmit = async (e) => {
-    e.preventDefault();
-    if (!doc._files?.photo) return;
-=======
-  const onPickFile = (e) => {
-    const next = {};
-    for (const f of e.target.files) next[f.name] = f;
-    merge({ _files: next });
-  };
-
-  const onSubmit = async (e) => {
-    e.preventDefault();
-    if (!Object.keys(doc._files || {}).length) return;
->>>>>>> REPLACE
-```
-
-### Form Validation
-
-You can use React's `useState` to manage validation states and error messages. Validate inputs at the UI level before allowing submission. Adding validation to the uploader:
-
-### `App.jsx`
-```jsx
-<<<<<<< SEARCH
-  const onSubmit = async (e) => {
-    e.preventDefault();
-    if (!Object.keys(doc._files || {}).length) return;
-=======
-  const [errors, setErrors] = React.useState({});
-
-  function validateForm() {
-    const newErrors = {};
-    if (!doc.caption.trim()) newErrors.caption = "Caption is required.";
-    if (!Object.keys(doc._files || {}).length) newErrors.file = "Pick a file.";
-    setErrors(newErrors);
-    return Object.keys(newErrors).length === 0;
-  }
-
-  const onSubmit = async (e) => {
-    e.preventDefault();
-    if (!validateForm()) return;
->>>>>>> REPLACE
-```
-
-## Example React Application
-
-Code listing for todo tracker App.jsx. Note the code ordering: hooks, then handlers, then classNames right before JSX.
-
-```js
-import React from "react";
-import { useFireproof } from "use-fireproof";
-import { useVibe } from "use-vibes";
-import { Button, Card, CardContent, Input, Label } from "@vibes.diy/look";
-
-export default function App() {
-  // 1. Hooks and document shapes
-  const { useLiveQuery, useDocument, database } = useFireproof("todoList");
-  const { me } = useVibe("todoList");
-
-  // Every person has a list of their own without creating one first.
-  const listId = `default-${me?.userHandle}`;
-
-  const {
-    doc: newTodo,
-    merge: mergeNewTodo,
-    submit: submitNewTodo,
-  } = useDocument({
-    todo: "",
-    type: "todo",
-    listId, // the list this todo belongs to, on the todo itself
-    authorHandle: me?.userHandle,
-    completed: false,
-    createdAt: Date.now(),
-  });
-
-  const { docs: todos } = useLiveQuery("listId", {
-    key: listId,
-    descending: true,
-  });
-
-  // 2. Event handlers
-  const handleInputChange = (e) => {
-    mergeNewTodo({ todo: e.target.value });
-  };
-
-  const handleSubmit = (e) => {
-    e.preventDefault();
-    submitNewTodo();
-  };
-
-  // 3. ClassNames — right before JSX, for the plain elements only; the look's
-  // components carry their own surface, ink and shape.
-  const c = {
-    page: "bg-background text-foreground font-sans",
-    meta: "text-muted-foreground",
-  };
-
-  // 4. JSX return
-  return (
-    <div className={`min-h-screen max-w-md mx-auto p-6 ${c.page}`}>
-      <h2 className="text-2xl font-bold mb-4">Todo List</h2>
-      <form onSubmit={handleSubmit} className="mb-4">
-        <Label htmlFor="todo" className="mb-2 block">
-          Todo
-        </Label>
-        <Input className="w-full" id="todo" type="text" onChange={handleInputChange} value={newTodo.todo} />
-      </form>
-      <ul className="space-y-3">
-        {todos.map((doc) => (
-          <li key={doc._id}>
-            <Card>
-              <CardContent className="flex flex-col items-start">
-                <div className="flex items-center justify-between w-full">
-                  <div className="flex items-center">
-                    <input
-                      className="mr-2"
-                      type="checkbox"
-                      checked={doc.completed}
-                      onChange={() => database.put({ ...doc, completed: !doc.completed })}
-                    />
-                    <span className="font-medium">{doc.todo}</span>
-                  </div>
-                  <Button variant="destructive" size="sm" onClick={() => database.del(doc._id)}>
-                    Delete
-                  </Button>
-                </div>
-                <div className={`${c.meta} mt-1`}>{new Date(doc.createdAt).toISOString()}</div>
-              </CardContent>
-            </Card>
-          </li>
-        ))}
-      </ul>
-    </div>
-  );
-}
-```
-
-IMPORTANT: Don't use `useState()` on form data, instead use `merge()` and `submit()` from `useDocument`. Only use `useState` for ephemeral UI state (active tabs, open/closed panels, cursor positions). Keep your data model in Fireproof.