@vibes.diy/prompts 14.1.20 → 14.1.22

package/llms/access.md

@@ -299,7 +299,9 @@ export function board(doc, oldDoc, user, ctx) {
 
 **Build the permission model around what a newcomer should be able to do.** When a stranger opens the app, they should immediately be able to do the thing it's _for_ — add their own todos, post a note, drop a pin, join a shared canvas. So the default is: every signed-in visitor is a first-class participant who creates their own objects and edits what they created (`doc.authorHandle === user.userHandle`, checking `oldDoc` on updates), from first load, with no one needing to let them in.
 
-**A personal list, tracker, journal, or notes app — one the prompt frames as the user's own, with no sharing asked for — gives every visitor their own private space on a single per-user channel.** A todo list, a daily habit tracker, a reading list, a diary, a notes app, a workout log, or a budget where the data is one person's own routes every doc that visitor creates to the one channel keyed on their handle — `user:${user.userHandle}` — self-granted so only they read it, with `authorHandle: user.userHandle` fixed at create and held immutable on update (`oldDoc.authorHandle === user.userHandle`). Their whole collection lives on that single private channel, reachable from first load, each visitor's space entirely their own:
+**When the person says "no sharing", "no access control" or "keep it single-user", that is the one case where `access.js` is left out altogether:** the app ships with no rules file, and the object id and `authorHandle` its records already carry are what let rules be added later without touching a doc.
+
+**When the person asks for private per-user permissions — "each person sees only their own", "private to every user" — every visitor gets their own private space on a single per-user channel.** A todo list, a daily habit tracker, a reading list, a diary, a notes app, a workout log, or a budget where the data is one person's own routes every doc that visitor creates to the one channel keyed on their handle — `user:${user.userHandle}` — self-granted so only they read it, with `authorHandle: user.userHandle` fixed at create and held immutable on update (`oldDoc.authorHandle === user.userHandle`). Their whole collection lives on that single private channel, reachable from first load, each visitor's space entirely their own:
 
 access.js
 
@@ -366,9 +368,9 @@ export function habits(doc, oldDoc, user, ctx) {
 }
 ```
 
-The leaderboard is just the access model: read the public `track:` channels and sum them; each viewer additionally sees their own streaks and any buddy who granted them in. A **plain daily habit tracker** — one framed as the user's own, with no catalog, leaderboard, or buddy asked for — is instead the per-visitor shape shown above: every visitor's habits and check-ins on their single `user:${user.userHandle}` channel, self-granted and private to them.
+The leaderboard is just the access model: read the public `track:` channels and sum them; each viewer additionally sees their own streaks and any buddy who granted them in. A habit tracker whose owner **asked to keep it to themselves** is instead the per-visitor shape shown above: every visitor's habits and check-ins on their single `user:${user.userHandle}` channel, self-granted and private to them.
 
-**"Invite", "join", "people can join", "collaborate", "share with", "together", "with my partner/team", or a board/canvas/room/whiteboard a group co-edits → per-object collaboration** (the second worked example above) — each shared thing is ONE object its members reach directly; it needs no owner. Use the per-object recipe: a channel per object (`board:<id>`/`list:<id>`); the creator self-grants at creation (`grant: { users: { [user.userHandle]: [ch] } }`); child docs gate on `ctx.requireAccess(ch)` so any member edits any child in it (not just their own); a member-authored `share` doc grants a peer the same channel; a `request` doc — which takes **no** `requireAccess` — lets a not-yet-member ask to join. Keep the _object's own_ creator field write-once (`if (oldDoc && doc.author !== oldDoc.author) throw`) and a child's object-id immutable. **Two traps to avoid:** don't build it as an open public feed where each person only owns their own items (that abandons the shared membership), and don't gate it behind a single writer (members self-serve via share/request).
+**Per-object collaboration is the resting shape of almost every app** (the second worked example above), and certainly of anything that says "invite", "join", "people can join", "collaborate", "share with", "together", "with my partner/team", or names a board/canvas/room/whiteboard a group co-edits — each shared thing is ONE object its members reach directly; it needs no owner. Use the per-object recipe: a channel per object (`board:<id>`/`list:<id>`); the creator self-grants at creation (`grant: { users: { [user.userHandle]: [ch] } }`); child docs gate on `ctx.requireAccess(ch)` so any member edits any child in it (not just their own); a member-authored `share` doc grants a peer the same channel; a `request` doc — which takes **no** `requireAccess` — lets a not-yet-member ask to join. Keep the _object's own_ creator field write-once (`if (oldDoc && doc.author !== oldDoc.author) throw`) and a child's object-id immutable. **Two traps to avoid:** don't build it as an open public feed where each person only owns their own items (that abandons the shared membership), and don't gate it behind a single writer (members self-serve via share/request). The app owner is not special in the data model: any signed-in person creates their own object and invites a friend into it, and the rule keys on `user.userHandle` or the object's creator, never on `user.isOwner`.
 
 **Ownership is just the object graph** — whoever authored or created a doc owns it (`doc.authorHandle === user.userHandle`, checked against `oldDoc` on updates). There's no broadcaster shape to reach for by default, and **owner-only publishing is a dead end** — never gate the content itself on `requireRole("owner")`. **A blog, magazine, or publication is public read + author-owned posts, with the owner controlling the _author roster_:** the owner approves authors with a grant doc (`if (doc.type === "author") { ctx.requireRole("owner"); return { channels: ["blog:authors"], grant: { users: { [doc.authorHandle]: ["blog:authors"] }, roles: { owner: ["blog:authors"] } } }; }` — the **one** place `requireRole("owner")` belongs, gating who may author, never the posts); a post then gates on `ctx.requireAccess("blog:authors")` (membership) and is author-owned (`doc.authorHandle === user.userHandle` + the `oldDoc` check), so once approved each author's post is _their own_ object — only they edit it, and they moderate the comments on it (a comment is allowed if it's your comment **or** you own the post: `doc.authorHandle === user.userHandle || doc.postAuthorHandle === user.userHandle`). A personal blog is just this with a roster of one. Always gate write UI on `useVibe(dbName).can`.
 
@@ -674,7 +676,7 @@ Channel `_id` is the channel identifier everywhere. The access function uses `do
 
 ### Example: Per-object sharing (collaborate on your own objects, no admin)
 
-Reach for this whenever the prompt says **invite, join, collaborate, share with, together, with my partner/team** — a shared shopping list you invite a partner to, a whiteboard people can join, a trip a group plans together. A list app where every signed-in user makes their own lists, sees only their own, and can invite anyone to collaborate on a specific list — peer to peer, with no app admin in the loop. The pattern: **a channel per object** (`list:<id>`); the creator grants themselves that channel at creation; child docs (items) gate on `ctx.requireAccess` of the list's channel, so **any member edits any item**; any current member shares the list by granting another user the same channel. Membership is direct `grant.users`, so each viewer's access scales with their own memberships.
+Reach for this by default, and certainly whenever the prompt says **invite, join, collaborate, share with, together, with my partner/team** — a shared shopping list you invite a partner to, a whiteboard people can join, a trip a group plans together, a tracker one person starts and later shares with a coach. A list app where every signed-in user makes their own lists, sees only their own, and can invite anyone to collaborate on a specific list — peer to peer, with no app admin in the loop. The pattern: **a channel per object** (`list:<id>`); the creator grants themselves that channel at creation; child docs (items) gate on `ctx.requireAccess` of the list's channel, so **any member edits any item**; any current member shares the list by granting another user the same channel. Membership is direct `grant.users`, so each viewer's access scales with their own memberships. Nothing a person writes reaches anyone else until they chose it: a per-object channel starts with its creator as the only reader, and every other reader arrives through a grant that creator wrote.
 
 access.js
 
@@ -755,6 +757,83 @@ App.jsx — `access.hasChannel()` shows only the lists the viewer belongs to; `u
 >>>>>>> REPLACE
 ```
 
+#### The same shape with a default object per person, and a member doc that names the friend
+
+Reach for this variant whenever the app is built around a *thing* people come back to — a board, a trip, a game night's scoreboard, a hiking group's trail list, a habit tracker one person keeps and a coach is invited into next month. Everything above still holds; three additions make it feel finished from the first load:
+
+- **Every signed-in person already has one object, with no doc to create.** Their default channel is derived from their own handle — `` `board:default-${user.userHandle}` `` — so a brand-new visitor opens the app, types, and their first item lands. Each write to it re-grants that person their own channel, because there is no object doc carrying the grant. **The child doc stores that board id rather than having each writer derive one**: the create writes `` boardId: pickedBoardId || `default-${me.userHandle}` `` and the rule holds it fixed from then on, so a card stays on the board its creator put it on however many people edit it later.
+- **Membership is a `member` doc, and picking the friend is `HandleInput`** (`useViewer()`, see use-viewer.md — the platform's people-picker, so the handle on the doc is one the platform resolved). The doc grants the named person the object's channel: `` grant: { users: { [doc.userHandle]: [chan] } } ``.
+- **The object's creator is its admin**, held on a second channel (`` `${chan}/admin` ``) that the creator self-grants at creation. Adding a member is gated on that admin channel, so members collaborate and the creator decides who joins. The app owner holds no place in any of this: every rule reads `user.userHandle` or the object's own `creatorHandle`.
+
+access.js
+
+```js
+export function boards(doc, oldDoc, user, ctx) {
+  if (!user?.userHandle) throw { forbidden: "sign in" };
+  const safeId = (id) => {
+    if (typeof id !== "string" || !/^[A-Za-z0-9_-]+$/.test(id)) throw { forbidden: "bad id" };
+    return id;
+  };
+  const myDefault = "default-" + user.userHandle;
+  const ch = (id) => "board:" + safeId(id);
+
+  if (doc.type === "board") {
+    // Anyone signed in makes their own board; the creator holds it and its admin channel.
+    if (oldDoc) {
+      if (doc.creatorHandle !== oldDoc.creatorHandle) throw { forbidden: "creator is fixed" };
+      ctx.requireAccess(ch(doc._id) + "/admin"); // renaming is an admin act — updates only
+    } else if (doc.creatorHandle !== user.userHandle) {
+      throw { forbidden: "you must be the creator" };
+    }
+    return { channels: [ch(doc._id)], grant: { users: { [doc.creatorHandle]: [ch(doc._id), ch(doc._id) + "/admin"] } } };
+  }
+
+  if (doc.type === "card") {
+    // The card STORES its board id from the moment it is created (the client writes the
+    // creator's own default when the person picked no board) and holds it fixed after —
+    // including the absent-to-present move, so a later editor's handle always finds the
+    // id already on the doc rather than supplying one.
+    if (!oldDoc && (typeof doc.boardId !== "string" || doc.boardId.length === 0)) {
+      throw { forbidden: "a card names its board" };
+    }
+    if (oldDoc && doc.boardId !== oldDoc.boardId) throw { forbidden: "card stays on its board" };
+    const chan = ch(doc.boardId);
+    if (doc.boardId !== myDefault) ctx.requireAccess(chan); // any member edits any card on it
+    // The implicit default board has no board doc, so each write re-grants its own person.
+    if (doc.boardId === myDefault) {
+      return { channels: [chan], grant: { users: { [user.userHandle]: [chan, chan + "/admin"] } } };
+    }
+    return { channels: [chan] };
+  }
+
+  if (doc.type === "member") {
+    // The board's admin invites a person the picker resolved; the doc IS the grant.
+    if (oldDoc) throw { forbidden: "membership grants are fixed" };
+    if (doc.addedBy !== user.userHandle) throw { forbidden: "addedBy must be you" };
+    if (doc.boardId !== myDefault) ctx.requireAccess(ch(doc.boardId) + "/admin");
+    return { channels: [ch(doc.boardId)], grant: { users: { [doc.userHandle]: [ch(doc.boardId)] } } };
+  }
+
+  throw { forbidden: "unknown document type" };
+}
+```
+
+App.jsx — the invite surface is `HandleInput` plus one `member` write, shown to whoever the access fn would accept:
+
+```jsx
+const { HandleInput } = useViewer();
+const { me, can } = useVibe("boards");
+const canInvite = (boardId) => can.create({ type: "member", boardId, userHandle: "x", addedBy: me?.userHandle }).ok;
+const addMember = (boardId, handle) =>
+  handle && database.put({ type: "member", boardId, userHandle: handle, addedBy: me.userHandle });
+// Every card names its board at creation — the person's own default board when they picked none.
+const addCard = (text) => database.put({ type: "card", boardId: pickedBoardId || `default-${me.userHandle}`, text });
+// …
+{canInvite(board._id) && <HandleInput onChange={(h) => addMember(board._id, h)} placeholder="Add a friend…" />}
+```
+
+Where the app's own maintainer needs to move records through the gate — a CLI migration re-homing cards — `!user.isOwner` reads as a bypass written beside a check (`if (!user.isOwner) ctx.requireAccess(chan)`), never as the arm that decides who may act.
+
 ## More worked round-trip examples
 
 ### Example: Workspace chat with channels

package/llms/backend.md

@@ -601,6 +601,33 @@ From `App.jsx`, call it with a relative fetch — no host needed:
 const res = await fetch("/_api/rsvp", { method: "POST", body: JSON.stringify({ name }) });
 ```
 
+### Bulk transformations run as a route
+
+A change that touches many stored records is written once, as a named `/_api` route, and run
+once — not looped from outside the app. Gate the route inside the handler on the caller being the
+owner, declare `config.fetch.unfilteredReads` for the collections it reads, page with the cursor
+`ctx.db.query` returns, and keep progress in a state document read by id so a second run continues
+where the first stopped.
+
+```js
+export const config = { fetch: { unfilteredReads: ["rsvps"] } };
+
+export async function fetch(request, ctx) {
+  const url = new URL(request.url);
+  if (url.pathname !== "/admin/normalize") return new Response("not found", { status: 404 });
+  if (ctx.user?.userHandle !== ctx.ownerHandle) return new Response("forbidden", { status: 403 });
+  const page = await ctx.db.query("kind", { key: "rsvp", limit: 100, db: "rsvps" });
+  for (const doc of page) {
+    if (typeof doc.name === "string" && doc.name !== doc.name.trim()) {
+      await ctx.db.put({ ...doc, name: doc.name.trim() }, { db: "rsvps" });
+    }
+  }
+  return new Response(JSON.stringify({ ok: true, more: page.next ?? null }), {
+    headers: { "content-type": "application/json" },
+  });
+}
+```
+
 ### Reading a page the person names — the `/_api` proxy
 
 A page the person names is read in `backend.js` and handed to the app through `/_api`. A browser

package/llms/callai.initial.md

@@ -0,0 +1,121 @@
+# CallAI Helper Function
+
+The `callAI` function asks an AI model and returns a string. With a `schema` the string is structured JSON you `JSON.parse()`; without one it is ordinary text — a chat reply, a caption, a paragraph — used as is. Reach for a schema when the app needs fields, and leave it out when it needs prose.
+
+## Basic Usage
+
+```javascript
+import { callAI } from "call-ai";
+
+const response = await callAI("Give me a todo list for learning React", {
+  schema: {
+    properties: {
+      todos: {
+        type: "array",
+        description: "List of actionable todo items",
+        items: { type: "string" },
+      },
+    },
+  },
+});
+const todoData = JSON.parse(response);
+console.log(todoData.todos);
+```
+
+## Items with properties
+
+```javascript
+const response = await callAI(
+  "Generate 4 items with label, status, priority (low, medium, high, critical), and notes. Return as structured JSON with these fields.",
+  {
+    schema: {
+      properties: {
+        items: {
+          type: "array",
+          items: {
+            type: "object",
+            properties: {
+              label: { type: "string", description: "Short name for the item" },
+              status: { type: "string", description: "Current status (active, done, blocked)" },
+              priority: { type: "string", description: "Priority level (low, medium, high, critical)" },
+              notes: { type: "string", description: "Additional context or details" },
+            },
+          },
+        },
+      },
+    },
+  }
+);
+const demoData = JSON.parse(response);
+console.log(demoData.items); // Array of item objects
+```
+
+### Schema Tips
+
+- Flat schemas perform better across all models. Avoid nesting deeper than 2 levels.
+- Use simple property names like `name`, `type`, `items`, `price`.
+- Keep array items simple (strings or flat objects).
+
+## Reading an Image
+
+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:
+
+```javascript
+import { callAI } from "call-ai";
+
+function readAsDataUrl(file) {
+  return new Promise((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onload = () => resolve(reader.result);
+    reader.onerror = () => reject(reader.error);
+    reader.readAsDataURL(file);
+  });
+}
+
+async function readFlyer(file) {
+  const dataUrl = await readAsDataUrl(file);
+  const response = await callAI(
+    [
+      { type: "text", text: "Read this event flyer and pull out the event details." },
+      { type: "image_url", image_url: { url: dataUrl } },
+    ],
+    {
+      schema: {
+        properties: {
+          title: { type: "string", description: "Name of the event" },
+          date: { type: "string", description: "Date as printed on the flyer" },
+          time: { type: "string" },
+          venue: { type: "string" },
+          description: { type: "string" },
+        },
+      },
+    }
+  );
+  return JSON.parse(response);
+}
+```
+
+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.
+
+## Error Handling
+
+```javascript
+import { callAI } from "call-ai";
+
+try {
+  const response = await callAI("Generate some content", {
+    schema: {
+      properties: {
+        result: { type: "string" },
+      },
+    },
+  });
+  console.log(JSON.parse(response));
+} catch (error) {
+  console.error("API error:", error.message);
+}
+```
+
+Let the request finish. Reading an image takes several seconds, so a slow answer is still an answer: show a waiting state ("reading your photo…") and keep awaiting the call. The `catch` above is what tells the app a request actually failed.

package/llms/callai.js

@@ -2,6 +2,7 @@ export const callaiConfig = {
     name: "callai",
     label: "callAI",
     description: "easy API for LLM requests with streaming support",
+    initialVariant: true,
     importModule: "call-ai",
     importName: "callAI",
 };

package/llms/callai.js.map

@@ -1 +1 @@
-{"version":3,"file":"callai.js","sourceRoot":"","sources":["../../jsr/llms/callai.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,YAAY,GAAc;IACrC,IAAI,EAAE,QAAQ;IACd,KAAK,EAAE,QAAQ;IACf,WAAW,EAAE,kDAAkD;IAC/D,YAAY,EAAE,SAAS;IACvB,UAAU,EAAE,QAAQ;CACrB,CAAC"}
+{"version":3,"file":"callai.js","sourceRoot":"","sources":["../../jsr/llms/callai.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,YAAY,GAAc;IACrC,IAAI,EAAE,QAAQ;IACd,KAAK,EAAE,QAAQ;IACf,WAAW,EAAE,kDAAkD;IAC/D,cAAc,EAAE,IAAI;IACpB,YAAY,EAAE,SAAS;IACvB,UAAU,EAAE,QAAQ;CACrB,CAAC"}

package/llms/debugging.md

@@ -0,0 +1,114 @@
+# debugging — working out what a deployed app is actually doing
+
+This guide is for you, the agent, when something in a live app does not match
+what the code says it should do. It is the method, not a feature the app author
+types.
+
+## The loop
+
+1. **Reproduce in words.** Say what the person did, what they expected and what
+   they saw. A reproduction you can state is a reproduction you can check.
+2. **Read the release state.** Which version is serving, whether newer work is
+   waiting behind it, whether the version that is live carries the record rules
+   and the server file you think it does. A change that was never released is
+   the most common explanation for "I fixed that already".
+3. **Read the logs.** What the deployed app has been recording about itself,
+   newest first. A line the app wrote beats an expectation about the code.
+4. **Read the records.** The data settles which of two stories is true. Read it
+   as the person whose app it is, so you see what their app shows them.
+5. **One hypothesis.** Name the single thing you now believe is wrong, in one
+   sentence.
+6. **The smallest change that tests it.** One record, one line, one handler.
+7. **Verify from a read.** Read the thing back after the change. A claim rests
+   on what a read returned, never on the fact that a call succeeded.
+
+## Instrumentation the platform already has
+
+`ctx.log` writes a line from server code, and `vibe.log` writes one from the
+page. Both land in the app's own log stream, stamped with the version that
+produced them, so a deploy boundary is visible in the stream.
+
+```js
+export async function scheduled(ctx) {
+  ctx.log("info", "tick start", { at: new Date().toISOString() });
+  const page = await ctx.db.query("kind", { key: "rsvp", limit: 100, db: "rsvps" });
+  ctx.log("info", "tick read", { count: page.length });
+}
+```
+
+A probe that only paints its result on screen is unreadable from outside the
+app, so a self-checking probe echoes each case on one line:
+
+```js
+console.log(`[RSVP] ${ok ? "PASS" : "FAIL"} duplicate-guard ${JSON.stringify({ id, count })}`);
+```
+
+Start the run with a marker — `console.log("===== START =====")` — so a later
+read knows which lines belong to this attempt.
+
+## Bulk work is a route, not a loop
+
+Changing a handful of records one at a time is fine. Past that, write the change
+once, as a named route in the app's own server file, and have the person run it.
+A route runs beside the data, keeps its own progress, and can be read and
+re-read before it is trusted.
+
+Gate the route inside the handler on the caller being the owner, declare
+`config.fetch.unfilteredReads` for the collections it reads, page with a cursor,
+and remember progress in a state document read by id so a second run continues
+rather than starting over. An empty page can still carry `next`, so loop on the
+cursor.
+
+```js
+export const config = { fetch: { unfilteredReads: ["rsvps"] } };
+
+export async function fetch(request, ctx) {
+  const url = new URL(request.url);
+  if (url.pathname !== "/admin/normalize") return new Response("not found", { status: 404 });
+  if (ctx.user?.userHandle !== ctx.ownerHandle) return new Response("forbidden", { status: 403 });
+
+  const state = (await ctx.db.get("0-normalize-state", { db: "rsvps" })) ?? { _id: "0-normalize-state", after: null };
+  let after = state.after;
+  let changed = 0;
+  for (let round = 0; round < 20; round++) {
+    const page = await ctx.db.query("kind", { key: "rsvp", limit: 100, ...(after ? { after } : {}), db: "rsvps" });
+    for (const doc of page) {
+      if (typeof doc.name === "string" && doc.name !== doc.name.trim()) {
+        await ctx.db.put({ ...doc, name: doc.name.trim() }, { db: "rsvps" });
+        changed++;
+      }
+    }
+    if (!page.next) { after = null; break; }
+    after = page.next;
+  }
+  await ctx.db.put({ ...state, after, at: Date.now() }, { db: "rsvps" });
+  ctx.log("info", "normalize round", { changed, after });
+  return new Response(JSON.stringify({ ok: true, changed, more: after !== null }), {
+    headers: { "content-type": "application/json" },
+  });
+}
+```
+
+Once the route is published, run it with `call_own_api`: it calls the app's own
+routes as the person whose app this is, so the handler sees the owner and the
+answer comes back in the conversation. Read the release state first when unsure
+which routes the live version carries, and read the records back afterwards to
+confirm what the run did.
+
+The person can run the same route from their own machine with their own
+credential:
+
+```sh
+curl -sS -X POST \
+  -H "Authorization: Bearer $VIBES_TOKEN" \
+  https://vibes.diy/vibe/<owner>/<slug>/_api/admin/normalize
+```
+
+## A route is live code
+
+`backend.js` and `access.js` always run the app's live release, so a route has
+to be published before anyone can call it, and publishing it puts it in front of
+everyone the app serves. Try a route whose effect you are unsure of under a
+second address first, confirm what it did by reading the records back, then ship
+it where the real data is. `call_own_api` reaches the live release too, so what
+it runs is what everyone else is being served.