@vibes.diy/prompts 14.1.21 → 14.1.23

package/llms/fireproof.js

@@ -2,6 +2,7 @@ export const fireproofConfig = {
     name: "fireproof",
     label: "useFireproof",
     description: "cloud-backed document database with live sync",
+    initialVariant: true,
     importModule: "use-fireproof",
     importName: "useFireproof",
 };

package/llms/fireproof.js.map

@@ -1 +1 @@
-{"version":3,"file":"fireproof.js","sourceRoot":"","sources":["../../jsr/llms/fireproof.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,eAAe,GAAc;IACxC,IAAI,EAAE,WAAW;IACjB,KAAK,EAAE,cAAc;IACrB,WAAW,EAAE,+CAA+C;IAC5D,YAAY,EAAE,eAAe;IAC7B,UAAU,EAAE,cAAc;CAC3B,CAAC"}
+{"version":3,"file":"fireproof.js","sourceRoot":"","sources":["../../jsr/llms/fireproof.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,eAAe,GAAc;IACxC,IAAI,EAAE,WAAW;IACjB,KAAK,EAAE,cAAc;IACrB,WAAW,EAAE,+CAA+C;IAC5D,cAAc,EAAE,IAAI;IACpB,YAAY,EAAE,eAAe;IAC7B,UAAU,EAAE,cAAc;CAC3B,CAAC"}

package/llms/image-gen.initial.md

@@ -0,0 +1,155 @@
+# ImgGen Component
+
+Generate and edit images from a text prompt. Each generated image lands as a file ref on the doc — display reads the platform-minted URL via `_files`.
+
+**When to use it:** reach for `<ImgGen>` when a picture adds real value — items whose identity includes an image (cards, creatures, products, covers), user-personalized art (avatars, portraits from a photo), or apps whose whole point is imagery. Most text/data apps (lists, trackers, notes, forms) need **no** images — leave the import unused rather than decorating with gratuitous pictures.
+
+## Basic Usage
+
+Start with a minimal image generation component:
+
+App.jsx
+
+```jsx
+import React from "react";
+import { useFireproof } from "use-fireproof";
+import { ImgGen } from "use-vibes";
+
+export default function App() {
+  return (
+    <div>
+      <h2>Image Generator</h2>
+      <ImgGen prompt="A sunset over mountains" />
+    </div>
+  );
+}
+```
+
+`<ImgGen>` stores generated versions in its component-owned media database, associated
+with the host database name and `_id`. Read a saved image through
+`useImgGen({ _id, database })` from `use-vibes`: its `document` composes current media
+versions and legacy host versions. From that composed document, select
+`document.versions?.[document.currentVersion ?? 0]`, then
+`document._files?.[version.id]`. The returned file ref supplies both `.url` for display
+and `.file()` for a transformation input, so a ref you have in hand is ready to pass
+straight to `images`. Ordinary host records hold the app's own data; the image hook
+supplies the associated generated output.
+
+For example, refining a saved pottery illustration keeps its original ID and uses its
+actual output as the input to a separate result ID:
+
+```jsx
+import { ImgGen, useImgGen } from "use-vibes";
+
+function GlazingPreview({ database }) {
+  const { document: original, pending, error } = useImgGen({ _id: "vessel-original", database });
+  const version = original?.versions?.[original.currentVersion ?? 0];
+  const source = version?.id ? original?._files?.[version.id] : undefined;
+  const sourceReady = source !== undefined;
+  return <section>
+    <ImgGen _id="vessel-original" database={database} showControls={false} />
+    {sourceReady ? <ImgGen _id="vessel-glazed" database={database}
+      prompt="Add a blue glaze while preserving this vessel's shape and composition"
+      images={[source]} /> : <p>{error ? error.message : pending ? "Loading saved source…" : "Source image unavailable"}</p>}
+  </section>;
+}
+```
+
+This is the same `_files`-shape contract documented in `fireproof.md`'s "Working with Files" section — read it first if you have not seen the platform's file/URL story.
+
+## Editing an Uploaded Image
+
+Pass a `File` object via `images` to run img2img. Adding a file picker that feeds into ImgGen:
+
+App.jsx
+
+```jsx
+<<<<<<< SEARCH
+export default function App() {
+  return (
+    <div>
+      <h2>Image Generator</h2>
+=======
+export default function App() {
+  const [file, setFile] = React.useState(null);
+
+  return (
+    <div>
+      <h2>Image Generator</h2>
+      <input type="file" accept="image/*" onChange={(e) => setFile(e.target.files[0])} />
+      {file && <ImgGen prompt="Make it look like a watercolor painting" images={[file]} />}
+>>>>>>> REPLACE
+```
+
+The input image is automatically resized (max 1024px) and compressed as JPEG before sending.
+
+`images` accepts **either** a raw `File` (fresh from an `<input type="file">`) **or** a stored Fireproof file ref — anything shaped like `{ file: () => Promise<File> }` passes straight through. So if the app has already saved the upload onto a doc, feed it back directly:
+
+```jsx
+// doc was saved earlier with: database.put({ ..., _files: { photo: file } })
+<ImgGen prompt="Turn this pet into a cute cartoon character" images={[doc._files.photo]} _id={doc._id} database={database} />
+```
+
+Do **not** invent wrappers like `images={x?.file ? something : undefined}` — pass the `_files` entry itself. If the stored ref might be absent, gate the whole `<ImgGen>` mount on it instead: `{doc._files?.photo && <ImgGen images={[doc._files.photo]} ... />}`.
+
+**Displaying an img2img result later** (gallery, detail view, reload): render by `_id` and do NOT re-pass `images` — `<ImgGen _id={doc._id} database={database} showControls={false} />` shows the stored version. ImgGen records which input produced each version, so re-passing that SAME input (the doc's own stored source, e.g. `images={[doc._files.photo]}` on every render) — or `_id` alone — just displays the saved result and will not force a fresh, billed generation. Passing a genuinely DIFFERENT input to the same `_id` DOES generate a new version — that's a requested img2img edit, not a reload: a new upload, a different stored ref, or a PRIOR OUTPUT fed back in to refine it. To force a new version from the CURRENT input, use the regenerate control (or set `generationId`). Generate once with `images`, display forever with `_id` alone.
+
+Do **not** set `model` for img2img: when an input image is present the platform automatically selects its image-**edit** default, which is tuned to produce edits faithful to the source. An explicit `model` override bypasses that routing — only use one when the app has a specific, stated reason.
+
+## Loading a Specific Doc
+
+Load a previously generated image by `_id` — if the doc has a `prompt` but no `_files` yet, the component generates one: `<ImgGen _id="my-image-id" database={database} />`
+
+## Illustrations That Are Part of an Item's Identity
+
+When an item's picture is intrinsic to what it is — a card in a deck, a creature in a bestiary, a product in a catalog, a character in a cast — render `<ImgGen>` **by default** for every such item that lacks an image, so the illustration appears as soon as the item does. Because ImgGen auto-generates when the target doc has a `prompt` but no `_files` yet, mounting it directly on the item is all it takes:
+
+```jsx
+<ImgGen
+  _id={card._id}
+  database={database}
+  prompt={`Illustration of ${card.title}. ${card.description ?? ""}`}
+/>
+```
+
+Do **not** hide first generation behind an "Illustrate" / "Generate image" button — a button leaves every item blank until tapped, which reads as "the app has no pictures." Reserve buttons and `showControls` for *regeneration* of an image that already exists. (For incidental or user-optional images — an avatar upload, a one-off hero graphic — an explicit action is still fine; this rule is about items whose identity includes a picture.)
+
+## Gallery Pattern
+
+Keep gallery entries as app-owned records with the saved image's host `_id`. Query those
+records with `useLiveQuery`, then let each `<ImgGen>` read its associated media. This also
+keeps the app's title, caption and other editable fields separate from image versions:
+
+```jsx
+function Gallery() {
+  const { database, useLiveQuery } = useFireproof("artwork");
+  const { docs } = useLiveQuery("type", { key: "artwork" });
+  return <div>{docs.map(doc => <figure key={doc._id}>
+    <ImgGen _id={doc._id} database={database} showControls={false} />
+    <figcaption>{doc.caption}</figcaption>
+  </figure>)}</div>;
+}
+```
+
+## Caching and Versions
+
+- Same prompt produces a deterministic `_id` (hash-based), so results are cached across reloads.
+- Each image has a regenerate button that appends a new version (writes a new `_files.v<N>` entry).
+- Prev / next controls navigate between stored versions.
+- Set `showControls={false}` to hide regenerate and version navigation.
+
+## Choosing a Model
+
+Override the model per component: `<ImgGen prompt="An astronaut riding a horse" model="openai/gpt-5-image-mini" />`
+
+Model ids follow the `provider/model-name` form from the platform's model catalog. Unknown ids surface as an error in the component's error UI.
+
+#### Props
+
+- `prompt`: text prompt (required unless `_id` is provided)
+- `images`: array of `File` objects **or stored `_files` refs** for img2img (uses first image; only pass while generating — display stored results via `_id`)
+- `_id`: load a specific doc instead of generating
+- `database`: Fireproof db name or instance (default `"ImgGen"`)
+- `className`, `alt`, `style`: standard image styling
+- `showControls`: toggle regenerate + version nav (default `true`)
+- `model`: override the image-gen model for this component

package/llms/image-gen.js

@@ -2,6 +2,7 @@ export const imageGenConfig = {
     name: "image-gen",
     label: "Image Generation",
     description: "Generate and edit images",
+    initialVariant: true,
     cues: [
         "image",
         "images",

package/llms/image-gen.js.map

@@ -1 +1 @@
-{"version":3,"file":"image-gen.js","sourceRoot":"","sources":["../../jsr/llms/image-gen.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,cAAc,GAAc;IACvC,IAAI,EAAE,WAAW;IACjB,KAAK,EAAE,kBAAkB;IACzB,WAAW,EAAE,0BAA0B;IACvC,IAAI,EAAE;QACJ,OAAO;QACP,QAAQ;QACR,KAAK;QACL,OAAO;QACP,QAAQ;QACR,SAAS;QACT,UAAU;QACV,QAAQ;QACR,cAAc;QACd,MAAM;QACN,cAAc;QACd,gBAAgB;KACjB;IACD,YAAY,EAAE,WAAW;IACzB,UAAU,EAAE,QAAQ;CACrB,CAAC"}
+{"version":3,"file":"image-gen.js","sourceRoot":"","sources":["../../jsr/llms/image-gen.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,cAAc,GAAc;IACvC,IAAI,EAAE,WAAW;IACjB,KAAK,EAAE,kBAAkB;IACzB,WAAW,EAAE,0BAA0B;IACvC,cAAc,EAAE,IAAI;IACpB,IAAI,EAAE;QACJ,OAAO;QACP,QAAQ;QACR,KAAK;QACL,OAAO;QACP,QAAQ;QACR,SAAS;QACT,UAAU;QACV,QAAQ;QACR,cAAc;QACd,MAAM;QACN,cAAc;QACd,gBAAgB;KACjB;IACD,YAAY,EAAE,WAAW;IACzB,UAAU,EAAE,QAAQ;CACrB,CAAC"}

package/llms/types.d.ts

@@ -3,6 +3,7 @@ export interface LlmConfig {
     label: string;
     description: string;
     cues?: string[];
+    initialVariant?: boolean;
     importModule?: string;
     importName?: string;
     importType?: "named" | "namespace" | "default";

package/llms/use-vibe.initial.md

@@ -0,0 +1,58 @@
+# useVibe Hook — write gating
+
+`useVibe(dbName)` is how you gate write surfaces. It asks the platform whether a candidate document would be accepted, so the UI's enabled/disabled state matches what the server will actually allow. You never re-implement the answer in the app; you ask, and you render the verdict.
+
+```jsx
+const { me, can, ready } = useVibe("comments");
+```
+
+Pass the Fireproof database name you are writing to. You get:
+
+- `can.create(draft)` / `can.edit(doc)` / `can.delete(doc)` → `{ ok: boolean, pending?: true, reason?: string }`. **The verdict has three states, not two** — allowed, still resolving, and denied — so branch on `pending` before `ok`.
+- `ready` — `false` until identity and the verdict have resolved. It is the same moment `pending` marks, so either one can hold the surface.
+- `me` — `{ userHandle, displayName? } | null` (null = anonymous). For display only.
+
+## The three-way branch
+
+While `pending` is set, show a quiet checking state — never a sign-in prompt, never the raw `reason` token, and never a blank space where the write surface was. A pending verdict means "we don't know yet", not "you may not"; it resolves on its own within a moment, so anything that reads as a refusal is wrong for that moment, and hiding the surface with nothing in its place makes the app look broken.
+
+On a real denial (`!ok` and no `pending`), explain it in your app's own words — `reason` is a machine token, not display copy. Let it *inform* the sentence you write ("Sign in to post here"), and never render it directly: a token like `pending` printed into the page is internal vocabulary leaking at a user.
+
+Never stamp author fields from `me` while the verdict is pending — `me` is null until identity resolves, and a write that skips the gate lands authorless.
+
+**Build the candidate from the doc you'll actually write.** `can.create(draft)` is evaluated against `draft`, so `draft` must carry the fields the write carries — `authorHandle`, the id of the object the record belongs to, and so on. A bare `can.create({ type: "post" })` can be denied (e.g. `"not author"`) and hide the form even from users who could post. Stamp the same fields you will `put`: `can.create({ type: "card", boardId, authorHandle: me?.userHandle })`. And gate the **same database** you write to — `useVibe(dbName)` answers per `dbName`, so a gate on a different db won't reflect what the server does.
+
+## The rule
+
+Gate every write affordance on `can.*`. Hold it while `pending`, and write your own copy when denied. Never branch write permission on `viewer` or on document fields — those drift from the platform's own answer. Rendering **other** users (authors, rosters) is `useViewer()`'s `<ViewerTag userHandle={...} />`, not `useVibe`. The current viewer's own pill and the "signed in as" label are system chrome in the Vibes Switch (the logo) — don't build them into the app. Asking an anonymous visitor to sign in is a different thing and it IS yours: `useViewer().requestLogin()`, at the moment their work becomes worth keeping (see use-viewer docs). A resolved denial is one such moment — write the sign-in copy in your app's own words and wire it to that callable, never to a sentence about the logo. (The one exception is inline avatar self-edit: a guarded no-prop `{viewer && <ViewerTag />}` lets any signed-in member change their own photo in place — see use-viewer docs.)
+
+```jsx
+import { useVibe } from "use-vibes";
+
+function PromptBar({ database, boardId }) {
+  const { can, me } = useVibe("aestheticBoard");
+  // The candidate carries the same keys the write will: the board it belongs
+  // to, and who is writing it.
+  const v = can.create({ type: "tile", boardId, authorHandle: me?.userHandle });
+  // 1. still resolving — a quiet placeholder, no refusal wording, no empty hole
+  if (v.pending) return <div className="skeleton" aria-busy="true">Checking…</div>;
+  // 2. resolved denial — your words, informed by v.reason, never v.reason itself
+  if (!v.ok) return <p className="muted">Sign in to add a tile.</p>;
+  // 3. allowed
+  return (
+    <form onSubmit={/* … */}>
+      {/* no current-user pill — identity + sign-in live in the Vibes Switch (the logo) */}
+      <input placeholder="Add a tile…" />
+      <button type="submit">Post</button>
+    </form>
+  );
+}
+```
+
+## Per-row affordances
+
+Per-row edit/delete affordances read the same way: `{can.edit(doc).ok && <EditButton doc={doc} />}`. By default every signed-in visitor is a first-class participant who creates and edits their own data, so on a fresh app these verdicts come back `ok` — which is the point. The gate is already in the right place when the app later grows a narrower answer, and nothing about the surface has to be rewritten to pick that answer up.
+
+## The server is still the authority
+
+`can.*` is a fast, faithful preview, not the final word. A write can still be rejected server-side (the source may be stale, async, or unevaluable — in which case `can.*` optimistically returns `ok` and defers to the server). Keep the optimistic-write + rollback pattern: apply the change immediately, revert and surface an error if the `put` rejects.

package/llms/use-vibe.js

@@ -2,6 +2,7 @@ export const useVibeConfig = {
     name: "use-vibe",
     label: "Vibe Write Gating",
     description: "Gate write surfaces on the app's own access.js via useVibe().can",
+    initialVariant: true,
     importModule: "use-vibes",
     importName: "useVibe",
 };

package/llms/use-vibe.js.map

@@ -1 +1 @@
-{"version":3,"file":"use-vibe.js","sourceRoot":"","sources":["../../jsr/llms/use-vibe.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,aAAa,GAAc;IACtC,IAAI,EAAE,UAAU;IAChB,KAAK,EAAE,mBAAmB;IAC1B,WAAW,EAAE,kEAAkE;IAC/E,YAAY,EAAE,WAAW;IACzB,UAAU,EAAE,SAAS;CACtB,CAAC"}
+{"version":3,"file":"use-vibe.js","sourceRoot":"","sources":["../../jsr/llms/use-vibe.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,aAAa,GAAc;IACtC,IAAI,EAAE,UAAU;IAChB,KAAK,EAAE,mBAAmB;IAC1B,WAAW,EAAE,kEAAkE;IAC/E,cAAc,EAAE,IAAI;IACpB,YAAY,EAAE,WAAW;IACzB,UAAU,EAAE,SAAS;CACtB,CAAC"}

package/llms/use-viewer.initial.md

@@ -0,0 +1,303 @@
+# useViewer Hook
+
+`useViewer()` is a **read-only window** into viewer identity. The platform owns who is signed in, and `useViewer()` lets your app see that and render it. Your app reflects the runtime's answer in its UI; it never invents one of its own.
+
+**The current viewer's pill is system chrome — you don't build it.** The platform shows the current user inside the **Vibes Switch**, the panel that opens when you click the logo. So your app does **not** need a header pill for whoever is looking — don't render a no-prop `<ViewerTag />` just to show "who's signed in".
+
+**The sign-in _ask_ is yours.** `requestLogin()` from `useViewer()` opens the platform sign-in UI from anywhere in your app, so you can word, place and time the ask yourself. Reach for it at the moment your app becomes worth keeping. The Switch is chrome outside your app's frame, and pointing at the logo is not a call to action — it is a scavenger hunt. See **Asking a visitor to sign in** below.
+
+Use `useViewer()` to render **other** people's identity — comment authors, rosters, "added by" labels — with `<ViewerTag userHandle={...} />`, and to read `viewer`/`can` when your UI needs to branch on who's looking. **Write surfaces are gated with `useVibe(dbName).can`** (see use-vibe docs), not with `viewer`.
+
+## Basic Usage
+
+Start with a minimal component that reads the viewer identity. You don't render a current-user pill — that lives in the Vibes Switch (click the logo). Branch on `viewer` for any welcome/empty copy. Note there is **no sign-in button here**: the ask belongs at the moment the visitor has made something worth keeping, not on arrival — see **Asking a visitor to sign in** below.
+
+App.jsx
+
+```jsx
+import React from "react";
+import { useFireproof } from "use-fireproof";
+import { useViewer } from "use-vibes";
+
+export default function App() {
+  const { viewer, isViewerPending } = useViewer();
+
+  if (isViewerPending) return null;
+
+  return (
+    <div>
+      {/* No current-user pill here — that's the Vibes Switch's job. */}
+      {viewer ? (
+        <p>Welcome back, {viewer.displayName ?? viewer.userHandle}!</p>
+      ) : (
+        <p>Everything you make here is saved on this device.</p>
+      )}
+    </div>
+  );
+}
+```
+
+## What you get
+
+- `viewer` — `{ userHandle, displayName? }` or `null` for anonymous visitors. Avatars are not on the payload — render them with `<ViewerTag userHandle={...} />`, which resolves the avatar from the handle. Don't build avatar URLs yourself.
+- `isViewerPending` — `true` while the platform is still resolving the viewer identity (e.g. on first render before the parent shell has pushed the identity update). **Gate any auth-dependent UI on `!isViewerPending`** to avoid flashing the wrong state. Once it becomes `false`, `viewer` is either populated or definitively `null`.
+- `can(action)` — membership boolean for `"read"`/`"write"`/`"delete"`: is the viewer through the door? It answers about the viewer, not about a particular document, so prefer `useVibe(dbName).can.create/edit/delete` for write gating — that one is asked about the doc you are writing and comes back with a `reason`.
+- `viewerLapsed` — `true` when `viewer` is the identity this device *remembers* and the platform's answer came back anonymous: the sign-in lapsed (an expired session, a cold boot before auth restores), rather than the person signing out. Keep rendering their stuff — the local data is still theirs, and writes queue locally and sync once they sign back in — and offer a quiet "Sign back in to sync" nudge wired to `requestLogin()`. Never fall back to the anonymous copy ("Sign in to get started") while `viewerLapsed` is true; that reads as if their work is gone. `can()` and every write gate stay closed while lapsed, so gate *writes* on `can`, not on this flag, and `isViewerPending` is `false` (lapsed is a settled state, not a loading one).
+- `requestLogin()` — opens the platform sign-in UI. Fire-and-forget: there is nothing to await and no result to branch on, because the new identity arrives on its own through `viewer`. This is how your app asks — see **Asking a visitor to sign in** below.
+- `ViewerTag` — ready-made user pill; see the ViewerTag section below.
+
+## Gating UI
+
+Gate the comment form on `useVibe("comments").can` — not on `viewer`. The current viewer never needs a pill here (that's in the Vibes Switch); just render the gated form, and on a denial a sentence in your app's own words — `reason` is a machine token that informs that sentence and is never printed:
+
+App.jsx
+
+```jsx
+<<<<<<< SEARCH
+import { useViewer } from "use-vibes";
+=======
+import { useViewer, useVibe } from "use-vibes";
+>>>>>>> REPLACE
+```
+
+App.jsx
+
+```jsx
+<<<<<<< SEARCH
+  const { viewer, isViewerPending } = useViewer();
+=======
+  const { viewer, isViewerPending } = useViewer();
+  const { can, ready, me } = useVibe("comments");
+>>>>>>> REPLACE
+```
+
+App.jsx
+
+```jsx
+<<<<<<< SEARCH
+      {viewer ? (
+        <p>Welcome back, {viewer.displayName ?? viewer.userHandle}!</p>
+      ) : (
+        <p>Everything you make here is saved on this device.</p>
+      )}
+=======
+      {/* write gate: useVibe().can, not viewer */}
+      {!ready ? null : (() => {
+        const v = can.create({ type: "comment", postId, authorHandle: me?.userHandle });
+        return v.ok ? (
+          <form>
+            <input placeholder="Add a comment..." />
+            <button type="submit">Post</button>
+          </form>
+        ) : (
+          // Your own words, informed by v.reason — never the token itself.
+          <p>Sign in to add a comment.</p>
+        );
+      })()}
+>>>>>>> REPLACE
+```
+
+## Tagging content with the viewer (write/render pattern)
+
+When one user writes content others will see (comments, posts, messages), **stamp `authorHandle` on the doc at write time**, and stamp the id of the thing it belongs to beside it (`postId`, `boardId`, `listId`). Render the author with `<ViewerTag userHandle={doc.authorHandle} />` which resolves display name and avatar automatically. Do not stamp `displayName` or `avatarUrl` on docs — ViewerTag handles that from the handle alone.
+
+Wire up a full comment thread with Fireproof and viewer attribution:
+
+App.jsx
+
+```jsx
+<<<<<<< SEARCH
+import { useViewer, useVibe } from "use-vibes";
+=======
+import { useViewer, useVibe } from "use-vibes";
+>>>>>>> REPLACE
+```
+
+```jsx
+<<<<<<< SEARCH
+  const { viewer, isViewerPending } = useViewer();
+  const { can, ready, me } = useVibe("comments");
+=======
+  const { viewer, isViewerPending, ViewerTag } = useViewer();
+  const { can, ready, me } = useVibe("comments");
+  const { useLiveQuery, database } = useFireproof("comments");
+  // Every comment names the post it belongs to. A thread shows one post, so
+  // its id is fixed here. An app where each person has a space of their own
+  // derives the id from the viewer's handle instead (`default-${me.userHandle}`)
+  // once `ready` says the handle is known, so the first write lands in a space
+  // that is theirs and stays theirs.
+  const postId = "post:welcome";
+  const { docs: comments } = useLiveQuery("postId", { key: postId });
+  const [body, setBody] = React.useState("");
+>>>>>>> REPLACE
+```
+
+```jsx
+<<<<<<< SEARCH
+      {/* write gate: useVibe().can, not viewer */}
+      {!ready ? null : (() => {
+        const v = can.create({ type: "comment", authorHandle: me?.userHandle });
+        return v.ok ? (
+          <form>
+            <input placeholder="Add a comment..." />
+            <button type="submit">Post</button>
+          </form>
+        ) : (
+          // Your own words, informed by v.reason — never the token itself.
+          <p>Sign in to add a comment.</p>
+        );
+      })()}
+=======
+      {/* render OTHER users with userHandle — that's what ViewerTag is for here */}
+      <ul>
+        {comments.map((c) => (
+          <li key={c._id}>
+            <ViewerTag userHandle={c.authorHandle} />
+            <p>{c.body}</p>
+          </li>
+        ))}
+      </ul>
+
+      {/* write gate: useVibe().can, not viewer */}
+      {!ready ? null : (() => {
+        const v = can.create({ type: "comment", postId, authorHandle: me?.userHandle });
+        return v.ok ? (
+          <form onSubmit={(e) => { e.preventDefault(); post(); }}>
+            <input value={body} onChange={(e) => setBody(e.target.value)} placeholder="Add a comment..." />
+            <button type="submit">Post</button>
+          </form>
+        ) : (
+          // Your own words, informed by v.reason — never the token itself.
+          <p>Sign in to add a comment.</p>
+        );
+      })()}
+>>>>>>> REPLACE
+```
+
+Also add the `post` handler before `if (isViewerPending)`:
+
+```jsx
+<<<<<<< SEARCH
+  if (isViewerPending) return null;
+=======
+  async function post() {
+    if (!body.trim()) return;
+    await database.put({
+      type: "comment",
+      postId, // the id of the thing this record belongs to, on the record itself
+      body: body.trim(),
+      createdAt: Date.now(),
+      authorHandle: me?.userHandle,
+    });
+    setBody("");
+  }
+
+  if (isViewerPending) return null;
+>>>>>>> REPLACE
+```
+
+Key points:
+
+- **Stamp `authorHandle` at write time** — persist the author's handle on the doc. Render with `<ViewerTag userHandle={authorHandle} />` which resolves display name and avatar automatically.
+- **Name the thing it belongs to** — every record carries the id of its parent object (`postId`, `boardId`, `listId`), written at create and left alone afterwards. Queries read off it, and so does everything the app grows later.
+- **Give each person a default object of their own** — `` `default-${me.userHandle}` `` — so someone who has just arrived types once and it lands, with no object for them to create first. An object someone does make carries `creatorHandle: me.userHandle`.
+- **Avatars are stable** — ViewerTag resolves the avatar from the handle; if the author changes their avatar, the URL stays the same and the bytes update. ViewerTag handles this for you.
+- **One source of identity** — persist `authorHandle` on the doc. ViewerTag does the rest.
+
+## Asking a visitor to sign in
+
+An anonymous visitor is having a legitimately good time. Under local-first their work is already saved on their device and your app should keep working for them — the account buys **sync, followers and durability**, not permission. So the ask is an **offer to keep what they already have — never a wall in front of it**. A visitor who never signs in should still get a working app; one who does should feel like they kept something.
+
+Three rules separate a CTA that converts from the two shapes that don't.
+
+**Ask at the moment of value.** The ask lands when the person has just made something they'd hate to lose — posted their first comment, starred their first pick, saved their first note. A prompt on arrival asks a stranger to commit before they know what the app does; a prompt after the first save offers to keep something they can already see.
+
+**Wire the ask to `requestLogin()`, never to a sentence about the logo.** Copy like "sign in via the logo" points at platform chrome outside your app's frame and sends the reader hunting for it. It is not a call to action and it does not convert. Render a real control: `<button onClick={requestLogin}>Keep these</button>`.
+
+**Only ask once identity has settled.** `isViewerPending` is `true` while the platform is still resolving who's looking, and a CTA rendered in that window shows signed-in people a SIGN IN button on every load. Compute the settled-signed-out state once and gate on it — `const settledSignedOut = !isViewerPending && !viewer;`.
+
+Layer it onto the comment app: the visitor can already read and post, and once they've posted, we offer to keep it.
+
+```jsx
+<<<<<<< SEARCH
+  const { viewer, isViewerPending, ViewerTag } = useViewer();
+=======
+  const { viewer, isViewerPending, ViewerTag, requestLogin } = useViewer();
+>>>>>>> REPLACE
+```
+
+```jsx
+<<<<<<< SEARCH
+  const [body, setBody] = React.useState("");
+=======
+  const [body, setBody] = React.useState("");
+
+  // Settled AND anonymous — never merely anonymous, or signed-in viewers flash
+  // this on every load while their identity is still resolving (#3639).
+  const settledSignedOut = !isViewerPending && !viewer;
+  // The moment of value: a comment THIS visitor wrote. An anonymous write
+  // stamps `authorHandle: me?.userHandle` with `me` still null, so an undefined
+  // author is our own unclaimed work — which is exactly what signing in keeps.
+  // Reading `comments.length` instead would nag people who only ever read.
+  const hasSomethingToKeep = comments.some((c) => c.authorHandle === undefined);
+>>>>>>> REPLACE
+```
+
+```jsx
+<<<<<<< SEARCH
+      {/* write gate: useVibe().can, not viewer */}
+=======
+      {settledSignedOut && hasSomethingToKeep && (
+        <div>
+          {/* Says what they GET. Never "you must sign in to continue" — they
+              can continue, and their comment above is already saved locally.
+              And never "post it under your name": signing in syncs the comment
+              they already wrote, it does not rewrite the author stamped on it.
+              Promise continuity, which is true — not attribution, which isn't. */}
+          <p>Your comment is saved on this device.</p>
+          <button onClick={requestLogin}>Sign in to keep it on all your devices</button>
+        </div>
+      )}
+
+      {/* write gate: useVibe().can, not viewer */}
+>>>>>>> REPLACE
+```
+
+Copy that works, and copy that doesn't:
+
+| Write this | Not this |
+| --- | --- |
+| "Sign in to sync your picks everywhere" | "Sign in to continue" |
+| "Keep these on all your devices" | "You must sign in to save" |
+| "Saved on this device — sign in to sync" | "Sign in via the Vibes DIY logo" |
+
+And never disable the app's real controls on `!viewer`. If favoriting works signed out, keep it working signed out — the platform refuses the *cloud* write on its own, calmly, while the local write still succeeds. Turning a working app into a signup wall is worse than never asking at all.
+
+## Notes
+
+- Never use Clerk user IDs. Only `userHandle` crosses into vibe code.
+- Avatar URLs are stable indirection URLs — when a user changes their avatar, the URL stays the same and the bytes update. Treat them as opaque strings.
+- To gate a write surface, use `useVibe(dbName).can` — asked about the document you are about to write. The server is the authority either way; `can` is the app's faithful preview of its answer.
+
+## ViewerTag
+
+`ViewerTag` is a ready-made inline user pill returned alongside `viewer` from `useViewer()`. It is not a separate import — you get it from the hook. **Use it to render _other_ people** — comment authors, roster rows, "added by" labels — by passing `userHandle`:
+
+```jsx
+{/* Show another user read-only: */}
+<ViewerTag userHandle={comment.authorHandle} />
+{/* Style override: */}
+<ViewerTag userHandle={member.userHandle} style={{ borderRadius: 8, fontSize: 12 }} />
+```
+
+**The current viewer's pill is system chrome, not app UI.** The platform already shows the current user inside the Vibes Switch that opens from the logo, so don't add a no-prop `<ViewerTag />` as a header pill just to show who's signed in; reach for `userHandle` to render someone else instead. To *ask* an anonymous visitor to sign in, use `requestLogin()` and your own copy (see **Asking a visitor to sign in**) — that ask belongs at the moment of value, which is a place only your app knows.
+
+**The one in-app reason to render a no-prop `<ViewerTag />` is inline avatar self-edit.** A no-prop tag shows the signed-in viewer a dashed edit ring that lets them change their _own_ avatar in place, and that works for **every** signed-in viewer — the Switch's avatar editing is owner-only. So if your app wants any member (not just the owner) to update their photo without leaving the app, render a guarded `{viewer && <ViewerTag />}` for that — otherwise leave the current-viewer pill to the Switch.
+
+**Undefined safety.** If `userHandle` is present in props but falsy (e.g. a missing field from a loop lookup), `ViewerTag` renders a dim italic placeholder instead of the edit ring. This prevents a broken data source from accidentally turning an arbitrary pill into a photo-edit control.
+
+**Anonymous & always-safe.** `ViewerTag` never throws regardless of login state. A no-prop `<ViewerTag />` renders a "Sign in" button for anonymous viewers — a fine fallback, but it is an identity chip in whatever spot you put it, not a CTA you can word or time. When the goal is conversion, write the prompt yourself and wire it to `requestLogin()`.
+
+**Theming.** `ViewerTag` reads the canonical palette variables — `--surface`, `--text-primary`, `--border`, and `--accent` (plus optional `--accent-text` to override the on-accent text color) — from the app's CSS with sensible fallbacks. If your app defines these on `:root` (which every generated theme does), `ViewerTag` inherits the theme automatically with no extra props. The one exception is the signed-out **Sign in** CTA, which deliberately stays the Vibes brand blue: it is a platform affordance matched to the Vibes Switch shown to the same visitor, so it is not theme-inherited.
+
+Pass `<ViewerTag userHandle={...} />` to render other people. Reach for the no-prop `<ViewerTag />` when you specifically want inline avatar self-edit for any signed-in member; for the current-user pill the Switch already covers it, and for a sign-in ask use `requestLogin()`.

package/llms/use-viewer.js

@@ -2,6 +2,7 @@ export const useViewerConfig = {
     name: "use-viewer",
     label: "Viewer Identity",
     description: "Get the current viewer's identity and capability gates",
+    initialVariant: true,
     importModule: "use-vibes",
     importName: "useViewer",
 };

package/llms/use-viewer.js.map

@@ -1 +1 @@
-{"version":3,"file":"use-viewer.js","sourceRoot":"","sources":["../../jsr/llms/use-viewer.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,eAAe,GAAc;IACxC,IAAI,EAAE,YAAY;IAClB,KAAK,EAAE,iBAAiB;IACxB,WAAW,EAAE,wDAAwD;IACrE,YAAY,EAAE,WAAW;IACzB,UAAU,EAAE,WAAW;CACxB,CAAC"}
+{"version":3,"file":"use-viewer.js","sourceRoot":"","sources":["../../jsr/llms/use-viewer.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,eAAe,GAAc;IACxC,IAAI,EAAE,YAAY;IAClB,KAAK,EAAE,iBAAiB;IACxB,WAAW,EAAE,wDAAwD;IACrE,cAAc,EAAE,IAAI;IACpB,YAAY,EAAE,WAAW;IACzB,UAAU,EAAE,WAAW;CACxB,CAAC"}

package/llms/use-viewer.md

@@ -322,7 +322,7 @@ async function assign(handle) {
 
 ### Adding a member to your own object — the canonical use
 
-Whenever the app is for a group — a shared list, a board, a trip, a club's page — each signed-in person has their own object and lets a friend into it by picking them here. The write is one small membership doc, and `access.js` turns that doc into the grant that gives the named person the object's channel (see access.md's per-object sharing examples). Keys on the picked handle and on the writer's own — the app owner has no special place in it.
+Almost every app works this way — a shared list, a board, a trip, a club's page, a tracker one person starts and later shares with a coach: each signed-in person has their own object and lets a friend into it by picking them here. The write is one small membership doc, and `access.js` turns that doc into the grant that gives the named person the object's channel (see access.md's per-object sharing examples). Keys on the picked handle and on the writer's own — the app owner has no special place in it.
 
 ```jsx
 const { HandleInput } = useViewer();
@@ -338,4 +338,4 @@ async function addMember(handle) {
 {canInvite && <HandleInput onChange={addMember} placeholder="Add a friend…" />}
 ```
 
-Members render with `<ViewerTag userHandle={m.userHandle} />`, the same way any other stored handle does. An app one person keeps for themselves needs none of this — the picker belongs where the prompt asks for other people.
+Members render with `<ViewerTag userHandle={m.userHandle} />`, the same way any other stored handle does. An app the person asked to keep to themselves — "just for me", "no sharing", "no access control" — needs none of this; everywhere else the picker belongs.

package/package.json

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