@vibes.diy/prompts 14.3.20 → 14.3.22

package/llms/access.md

@@ -66,7 +66,8 @@ Keep the two visually distinct (a checkbox with its own explanatory line; a sepa
 
 App.jsx — the checkbox is the consent call; the picker is a doc write:
 
-```jsx file=App.jsx
+### `App.jsx`
+```jsx
 const { can } = useVibe("logs"); // the write gate is always the server's own verdict
 
 // checking is the consent preflight; unchecking is the off switch. Never one verb for both edges.
@@ -93,7 +94,8 @@ const { can } = useVibe("logs"); // the write gate is always the server's own ve
 
 access.js — the buddy grant and the followers audience arm are independent:
 
-```js file=access.js
+### `access.js`
+```js
 const ch = `log:${user.userHandle}`;
 
 if (doc.type === "share") {
@@ -265,7 +267,8 @@ Use `oldDoc` (the previous version of the document) to enforce invariants across
 
 Some documents belong to the machinery rather than to a person: a scheduled run's state doc, a counter a `scheduled` sweep advances, a notification the backend generates. Gate those on the **origin** with `ctx.requireBackend(...)` — one line, no conditional:
 
-```js file=access.js partial
+### `access.js`
+```js partial
 if (doc.type === "runState") {
   ctx.requireBackend("scheduled");
   return { channels: ["show"] };
@@ -284,7 +287,7 @@ One trap: applying a release's `seed.json` is the **platform** writing, not the
 
 The **placement** of `access.js` depends on which turn shape you are in — one-shot whole-app generation vs. incremental scaffold/follow-up edits. Follow the subsection that matches your turn; the other one's ordering is wrong for you and will strand writes.
 
-**Variant-neutral rules (always):** write `access.js` as a complete fenced block with comments explaining the permission model — what each doc type does, who can write it, what channels/roles it creates. **Never put access function code inside an `App.jsx` block** — it will overwrite the React component; the filename line (e.g. `access.js` vs `App.jsx`) is how the system knows which file to write. Whatever the turn shape, `App.jsx` gates its write surfaces on `useVibe(dbName).can` — the same rules this access function enforces.
+**Variant-neutral rules (always):** write `access.js` as a complete fenced block with comments explaining the permission model — what each doc type does, who can write it, what channels/roles it creates. **Never put access function code inside an `App.jsx` block** — it will overwrite the React component; the path heading (e.g. `access.js` vs `App.jsx`) is how the system knows which file to write. Whatever the turn shape, `App.jsx` gates its write surfaces on `useVibe(dbName).can` — the same rules this access function enforces.
 
 **One-shot generation (the whole app in one full-file block):** emit `access.js` as the **last file of the turn** — after the complete `App.jsx` and any companion feature files. You are NOT emitting incremental `SEARCH`/`REPLACE` edits here — write the finished files in full. The worked examples below show the access-function shapes; ignore any edit-by-edit cadence in them and emit the access function as one complete block.
 
@@ -292,9 +295,8 @@ The **placement** of `access.js` depends on which turn shape you are in — one-
 
 Worked example — members-only chat writes
 
-access.js
-
-```js file=access.js partial
+### `access.js`
+```js partial
 export function chat(doc, oldDoc, user, ctx) {
   if (!user) throw { forbidden: "authentication required" };
 
@@ -349,9 +351,8 @@ _Each example below closes its type dispatch with the default terminal `throw {
 
 ### Worked example — open channel wall (author-owned writes)
 
-access.js
-
-```js file=access.js partial
+### `access.js`
+```js partial
 export function wall(doc, oldDoc, user, ctx) {
   if (!user) throw { forbidden: "sign in" };
 
@@ -380,9 +381,8 @@ export function wall(doc, oldDoc, user, ctx) {
 
 ### Worked example — per-object collaboration with join request
 
-access.js
-
-```js file=access.js partial
+### `access.js`
+```js partial
 export function board(doc, oldDoc, user, ctx) {
   if (!user) throw { forbidden: "sign in" };
   const channel = `board:${doc.boardId}`;
@@ -413,9 +413,8 @@ export function board(doc, oldDoc, user, ctx) {
 
 **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
-
-```js file=access.js partial
+### `access.js`
+```js partial
 export function notes(doc, oldDoc, user, ctx) {
   if (!user) throw { forbidden: "sign in" };
   const ch = `user:${user.userHandle}`; // this visitor's own private space
@@ -442,9 +441,8 @@ Every item a visitor creates lands on their own `user:<handle>` channel, private
 
 **Worked example — a shared catalog people track against, with per-thing visibility (a social habit app, a reading challenge, a fitness ladder).** The catalog items are public objects anyone proposes; each person's progress is their own; and each person chooses — _once per item, never per entry_ — whether their streak is public (on the leaderboard) or buddy-only. The visibility choice lives on a per-`(person, item)` **tracking** record that sets the read-grant the entries routed to it inherit.
 
-access.js
-
-```js file=access.js partial
+### `access.js`
+```js partial
 export function habits(doc, oldDoc, user, ctx) {
   if (!user) throw { forbidden: "sign in" };
 
@@ -486,7 +484,8 @@ The leaderboard is just the access model: read the public `track:` channels and
 
 The personal blog's post branch is small — public read is the blog's resting state, declared inline on every post result (readers are the point of publishing):
 
-```js file=access.js partial
+### `access.js`
+```js partial
 if (doc.type === "post") {
   if (!oldDoc) {
     if (doc.authorHandle !== user.userHandle) throw { forbidden: "not author" };
@@ -505,8 +504,7 @@ When the prompt also asks for drafts, keep the same public resting state for pos
 
 For databases without an access function export, `access` has empty roles and channels. No separate pending flag — grants arrive alongside the viewer identity, so `useViewer().isViewerPending` covers both.
 
-App.jsx
-
+### `App.jsx`
 ```jsx
 <<<<<<< SEARCH
 import { useFireproof } from "use-fireproof";
@@ -516,8 +514,7 @@ import { useVibe } from "use-vibes";
 >>>>>>> REPLACE
 ```
 
-App.jsx
-
+### `App.jsx`
 ```jsx
 <<<<<<< SEARCH
   const { useLiveQuery, database } = useFireproof("comments");
@@ -527,8 +524,7 @@ App.jsx
 >>>>>>> REPLACE
 ```
 
-App.jsx
-
+### `App.jsx`
 ```jsx
 <<<<<<< SEARCH
       <h3>Recent Documents</h3>
@@ -566,9 +562,8 @@ This example shows the full round-trip — access.js declares channels and grant
 - **Write surfaces** are gated with `useVibe(dbName).can.create/edit/delete` — it runs this same access function, so the UI verdict matches the server. Render `.reason` when denied. (See use-vibe docs.)
 - **`ViewerTag`** takes `userHandle` to render another user (authors, rosters). The current viewer's own pill is system chrome in the Vibes Switch (the logo) — don't add one to the app's UI, except a guarded no-prop `{viewer && <ViewerTag />}` when you want inline avatar self-edit for any signed-in member (see use-viewer docs). The sign-in ASK is the app's, though: `useViewer().requestLogin()` from your own button, at the moment the visitor's work becomes worth keeping.
 
-access.js
-
-```js file=access.js
+### `access.js`
+```js
 export function announcements(doc, oldDoc, user, ctx) {
   if (!user) throw { forbidden: "sign in" };
 
@@ -618,7 +613,8 @@ export function announcements(doc, oldDoc, user, ctx) {
 
 App.jsx — `useVibe().can` gates every write surface (posts AND owner-only management); `access.hasChannel()` reflects display-only membership:
 
-```jsx file=App.jsx
+### `App.jsx`
+```jsx
 import React from "react";
 import { useFireproof } from "use-fireproof";
 import { useViewer, useVibe } from "use-vibes";
@@ -723,9 +719,8 @@ const canRevoke = can.delete(grantDoc);
 
 Channels everyone can read, and any signed-in user can post to. The channel doc is `grant.public` (read for everyone) and the post rule checks only the author — **no `ctx.requireAccess`**, because public is read-only and would block every non-owner. (For a members-only board where the owner appoints who can post, grant a poster role and `requireAccess` it, as in the announcements example above.) The UI uses `access.hasChannel()` to filter which channels to display, and `useVibe().can` to gate writes.
 
-access.js
-
-```js file=access.js partial
+### `access.js`
+```js partial
 export function chat(doc, oldDoc, user, ctx) {
   if (!user) throw { forbidden: "sign in" };
 
@@ -793,9 +788,8 @@ Channel `_id` is the channel identifier everywhere. The access function uses `do
 
 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
-
-```js file=access.js partial
+### `access.js`
+```js partial
 export default function (doc, oldDoc, user, ctx) {
   if (!user) throw { forbidden: "sign in" };
   const ch = (id) => `list:${id}`;
@@ -881,9 +875,8 @@ Reach for this variant whenever the app is built around a *thing* people come ba
 - **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`.
 - **Recipients can select every readable object.** The ordinary object query already applies the access rules, including grants from independent membership records. Its complete result supplies the picker. Prefer the person's own object as the initial selection while keeping invited objects selectable alongside it. Resolve the selected id against the current readable results on each render, so a revoked object leaves both the picker and the content view. Use the selected object's id for child queries, new content, and invitations; `can` continues to gate each write.
 
-access.js
-
-```js file=access.js partial
+### `access.js`
+```js partial
 export function boards(doc, oldDoc, user, ctx) {
   if (!user?.userHandle) throw { forbidden: "sign in" };
   const safeId = (id) => {
@@ -970,7 +963,8 @@ const addCard = async (text, boardId = `default-${me.userHandle}`) => {
 
 App.jsx — the same board list serves the creator and the invited recipient. `BoardContents` uses `board._id` for its content queries, calls `addCard(text, board._id)` and `addMember(board._id, handle)`, and gates its write controls with `can`. Pass the `ensureDefaultBoard` helper above into `BoardWorkspace`; its creation action stays reachable with an empty readable list and selects the person's new board after saving it.
 
-```jsx file=App.jsx partial
+### `App.jsx`
+```jsx partial
 function BoardWorkspace({ ensureDefaultBoard }) {
   const { useLiveQuery } = useFireproof("boards");
   const { me, can } = useVibe("boards");
@@ -1033,9 +1027,8 @@ That bounds what the build's own closing line says: the rules and the screen it
 
 ### Example: Workspace chat with channels
 
-access.js
-
-```js file=access.js partial
+### `access.js`
+```js partial
 export function chat(doc, oldDoc, user, ctx) {
   if (!user) throw { forbidden: "authentication required" };
 
@@ -1119,9 +1112,8 @@ App.jsx — show only channels the viewer is in (`access.hasChannel`), gate the
 
 ### Example: Anonymous survey with role-gated results
 
-access.js
-
-```js file=access.js partial
+### `access.js`
+```js partial
 export function survey(doc, oldDoc, user, ctx) {
   if (doc.type === "survey-response") {
     if (oldDoc) throw { forbidden: "responses are write-once" };
@@ -1195,9 +1187,8 @@ App.jsx — anonymous-friendly submit form, owner-only config panel, role-gated
 
 When the prompt says **anyone can sign / submit without logging in** (a guestbook, a contact form, an RSVP), do **not** throw on `!user` — return `allowAnonymous: true` so the write is accepted for anonymous visitors. `useVibe().can.create(...)` then returns `ok` for an anonymous viewer, and the form shows instead of a sign-in wall. Stamp `authorHandle` only when there is a user.
 
-access.js
-
-```js file=access.js partial
+### `access.js`
+```js partial
 export function guestbook(doc, oldDoc, user, ctx) {
   if (doc.type === "entry") {
     if (oldDoc) throw { forbidden: "entries are write-once" };

package/llms/backend.md

@@ -50,7 +50,7 @@ the declared fallback, with its freshness and failure visible in saved status.
 ## Output format
 
 `backend.js` is a separate file, exactly like `access.js`: one prose line, the
-filename `backend.js` on its own line, then one **complete** fenced block (the
+heading naming `backend.js`, then one **complete** fenced block below it (the
 whole file — don't use SEARCH/REPLACE for it; re-emit the full file to change
 it). **Never put backend code inside an `App.jsx` block**, and never import
 `backend.js` from `App.jsx` — the browser can't run it.
@@ -468,9 +468,8 @@ This complete example makes one curated GitHub API request every 15 minutes
 (well inside the documented caps), stores at most 20 normalized `release` docs
 in `nodeReleases`, and records refresh state in that same database.
 
-backend.js
-
-```js file=backend.js
+### `backend.js`
+```js
 export const config = { scheduled: { interval: "15m" } };
 
 const SNAPSHOT = [
@@ -565,9 +564,8 @@ export async function scheduled(event, ctx) {
 }
 ```
 
-App.jsx
-
-```jsx file=App.jsx
+### `App.jsx`
+```jsx
 import React from "react";
 import { useFireproof } from "use-fireproof";
 import { Badge, Card, CardContent } from "@vibes.diy/look";
@@ -644,7 +642,8 @@ Runs for requests to the app's `/_api` route. The request path is rooted after
 `/_api`: a call to `https://slug--owner.host/_api/webhooks/pay` arrives with
 pathname `/webhooks/pay`. Return a standard `Response`.
 
-```js file=backend.js
+### `backend.js`
+```js
 export async function fetch(request, ctx) {
   const url = new URL(request.url);
   if (url.pathname === "/rsvp" && request.method === "POST") {
@@ -660,7 +659,8 @@ export async function fetch(request, ctx) {
 
 From `App.jsx`, call it with a relative fetch — no host needed:
 
-```js file=App.jsx partial
+### `App.jsx`
+```js partial
 const res = await fetch("/_api/rsvp", { method: "POST", body: JSON.stringify({ name }) });
 ```
 
@@ -707,7 +707,8 @@ needs to know the visitor — their own records, their connection, their
 permissions — the page calls it with `apiFetch`.** The path is the route under
 `/_api`, and the answer reads like a `Response`:
 
-```jsx file=App.jsx partial
+### `App.jsx`
+```jsx partial
 import { apiFetch } from "use-vibes";
 
 const res = await apiFetch("/my-rsvp", {
@@ -735,7 +736,8 @@ owner, declare `config.fetch.unfilteredReads` for the collections it reads, page
 `ctx.db.query` returns, and keep progress in a state document read by id so a second run continues
 where the first stopped.
 
-```js file=backend.js
+### `backend.js`
+```js
 export const config = { fetch: { unfilteredReads: ["rsvps"] } };
 
 export async function fetch(request, ctx) {
@@ -774,9 +776,8 @@ browser, a consent wall, a host answering with an empty body — is a read that
 it answers `ok: false` with a reason. That is what makes `page.ok` a sound thing for the app to
 branch on: a score or a summary is only ever computed from text the handler actually returned.
 
-backend.js
-
-```js file=backend.js
+### `backend.js`
+```js
 export async function fetch(request, ctx) {
   const url = new URL(request.url);
   if (url.pathname === "/page") {
@@ -815,7 +816,8 @@ export async function fetch(request, ctx) {
 
 From `App.jsx`, the page asks the handler for the address it was given:
 
-```js file=App.jsx partial
+### `App.jsx`
+```js partial
 const res = await fetch(`/_api/page?url=${encodeURIComponent(url)}`);
 const page = await res.json();
 if (page.ok === false) {
@@ -842,7 +844,8 @@ server owes in response.
 Runs after any document write to the app's databases commits (user writes and
 backend writes alike). The event:
 
-```js file=backend.js
+### `backend.js`
+```js
 export async function onChange(event, ctx) {
   // event: { dbName, docId, doc, oldDoc, seq, deleted } — doc carries _id and _rev
   if (event.dbName !== "votes" || event.deleted) return;
@@ -894,7 +897,8 @@ sweep's `query` row), then `put` the next status with `ifRev: doc._rev`. A
 - Keep each run short; a run past 15 minutes is delivered again while it is
   still going, so chunk long work into `scheduled` ticks.
 
-```js file=backend.js
+### `backend.js`
+```js
 export const config = { scheduled: { interval: "30s" } };
 const DB = "jobs", LEASE_MS = 30_000, MAX_ATTEMPTS = 3;
 const rid = () => Math.random().toString(36).slice(2, 10);
@@ -941,7 +945,8 @@ production are at https://good.vibes.diy/docs/patterns/doc-state-machines.
 Requires a `config` export with a **static string-literal** interval between
 `"5s"` and `"1h"` (e.g. `"30s"`, `"5m"`, `"1h"` — computed values are rejected):
 
-```js file=backend.js
+### `backend.js`
+```js
 export const config = { scheduled: { interval: "15m" } };
 
 export async function scheduled(event, ctx) {
@@ -969,7 +974,8 @@ saving on its own, which a stored hour-offset does not.
 
 App.jsx — when the owner saves the schedule:
 
-```jsx file=App.jsx partial
+### `App.jsx`
+```jsx partial
 await merge({
   hour: 12, // the hour they picked, in their own day
   timeZone: Intl.DateTimeFormat().resolvedOptions().timeZone, // e.g. "America/Detroit"
@@ -978,7 +984,8 @@ await merge({
 
 backend.js — the tick compares in that zone:
 
-```js file=backend.js partial
+### `backend.js`
+```js partial
 const hourLocal = Number(
   new Intl.DateTimeFormat("en-US", {
     timeZone: settings.timeZone ?? "UTC",
@@ -1044,7 +1051,8 @@ repeats" above: the interval is only how often the handler wakes up.
 
 App.jsx — write the zone once, when they arrive:
 
-```jsx file=App.jsx
+### `App.jsx`
+```jsx
 useEffect(() => {
   if (!me?.userHandle) return;
   const timeZone = Intl.DateTimeFormat().resolvedOptions().timeZone;
@@ -1055,7 +1063,8 @@ useEffect(() => {
 
 backend.js — evaluate each person in their own zone:
 
-```js file=backend.js
+### `backend.js`
+```js
 export const config = { scheduled: { interval: "15m" } };
 const WEEKDAYS = new Set(["Mon", "Tue", "Wed", "Thu", "Fri"]);
 
@@ -1111,7 +1120,8 @@ is the only place an owner can tell. For a job that acts twice a month that mean
 weeks of silence that reads exactly like a dead alarm. So log once per tick,
 before any early return:
 
-```js file=backend.js partial
+### `backend.js`
+```js partial
 export async function scheduled(event, ctx) {
   const due = eventsDueNow(event.scheduledTime);
   ctx.log("debug", "tick", { due: due.length }); // proof of life; no reads, no spend
@@ -1195,7 +1205,8 @@ genuinely produced something is a real state change and belongs in that doc —
 unlike a per-tick `checkedAt`, which is the churn the zero-churn rule above is
 about.
 
-```js file=backend.js
+### `backend.js`
+```js
 export const config = { scheduled: { interval: "15m" } };
 
 const SHOW_DB = "show"; // the one database App.jsx live-queries
@@ -1291,7 +1302,8 @@ including the owner's own — while still no-opping under admin mode, so a hand
 repair runs the function and keeps the routing. `access.js` is where that is
 said:
 
-```js file=access.js
+### `access.js`
+```js
 // access.js
 export default function (doc, oldDoc, user, ctx) {
   if (doc.type === "runState" || doc.type === "runStatus") {
@@ -1308,7 +1320,8 @@ picked and, beside it, the zone their own browser reported — and reads the sam
 database back, rendering the status beside the drafts so a failed run and a good
 one never look alike:
 
-```jsx file=App.jsx
+### `App.jsx`
+```jsx
 const { useLiveQuery, database } = useFireproof("show");
 
 async function saveSchedule(hour) {
@@ -1340,7 +1353,8 @@ mirrors each note into a per-author `activity` entry (acting as that author —
 same privilege, just automated), and a `scheduled` sweep maintains one `digest`
 doc that `access.js` restricts to the **owner**, so no user can forge it.
 
-```js file=backend.js
+### `backend.js`
+```js
 export const config = { scheduled: { interval: "15m" } };
 
 export async function onChange(event, ctx) {

package/llms/bluesky.md

@@ -139,7 +139,8 @@ person can act on — "no data" is not.
 
 ## Complete backend.js
 
-```js file=backend.js app=bluesky-browser
+### `backend.js`
+```js app=bluesky-browser
 const XRPC = "https://public.api.bsky.app/xrpc";
 const DB = "bluesky";
 
@@ -260,7 +261,8 @@ export async function fetch(request, ctx) {
 A profile card, its follow graph, and the account's posts — one handle in, no
 account of the visitor's involved.
 
-```jsx file=App.jsx app=bluesky-browser
+### `App.jsx`
+```jsx app=bluesky-browser
 import React, { useState } from "react";
 
 export default function App() {

package/llms/calendar.md

@@ -110,7 +110,8 @@ button is simply there once the user has subscribable content.
 there means the Subscribe link never renders, even though the mint effect and
 the feed itself work.
 
-```jsx file=App.jsx app=calendar-feed
+### `App.jsx`
+```jsx app=calendar-feed
 // access.js needs a `caltoken` branch routing the doc to the owner's PRIVATE
 // channel (like notes) — the token is the secret.
 const { docs: calTokens } = useLiveQuery(byTypeUser, { key: ["caltoken", me.userHandle] });
@@ -153,7 +154,8 @@ the button tooltip.
 "2026-07-31", time: "18:00:00", endtime: "", title, venue, url } }` — adapt
 the doc shape, db name, and timezone to the app.
 
-```js file=backend.js app=calendar-feed
+### `backend.js`
+```js app=calendar-feed
 export const config = { scheduled: { interval: "1m" } };
 
 const TZ = "America/Los_Angeles"; // the app's local timezone

package/llms/callai.initial.md

@@ -20,7 +20,8 @@ After each successful creation, sentence correction or field edit, the parent ow
 
 This complete example covers **one sentence → one task**, **pasted list → many tasks**, **a selected task + correction → the same task**, **questions from the same box**, and **Undo after a save**. Every new submission uses the array schema, whether it names one task or several. The person sets a due date in the saved task’s date control. A malformed response leaves the typed sentence and saved records available; the waiting state ends when the request settles.
 
-```jsx file=App.jsx
+### `App.jsx`
+```jsx
 import React, { useState } from "react";
 import { callAI } from "call-ai";
 import { useFireproof } from "use-fireproof";

package/llms/callai.md

@@ -20,7 +20,8 @@ After each successful creation, sentence correction or field edit, the parent ow
 
 This complete example covers **one sentence → one task**, **pasted list → many tasks**, **a selected task + correction → the same task**, **questions from the same box**, and **Undo after a save**. Every new submission uses the array schema, whether it names one task or several. The person sets a due date in the saved task’s date control. A malformed response leaves the typed sentence and saved records available; the waiting state ends when the request settles.
 
-```jsx file=App.jsx
+### `App.jsx`
+```jsx
 import React, { useState } from "react";
 import { callAI } from "call-ai";
 import { useFireproof } from "use-fireproof";
@@ -201,7 +202,8 @@ Send an image by passing the prompt as an array of content parts: an `image_url`
 
 The prompt is the content of one user message, so a plain string means exactly one text part and the array is that same message's parts. Read the picture the user picked with a `FileReader` and hand over the data URL it produces, straight from the camera or photo library — `callAI` shrinks a large photo to a model-friendly size (1568px on its long edge) before sending it, so the app passes the whole picture and leaves the resizing to the platform:
 
-```javascript file=App.jsx
+### `App.jsx`
+```javascript
 import { callAI } from "call-ai";
 
 function readAsDataUrl(file) {

package/llms/connections.md

@@ -32,7 +32,8 @@ reaches the third with `apiFetch` (section 4), so it runs as the visitor.
 
 ### 1. Declare it — `backend.js`
 
-```js file=backend.js app=instagram-connection
+### `backend.js`
+```js app=instagram-connection
 export const config = {
   connections: [
     {
@@ -71,7 +72,8 @@ for the rest.
 
 ### 2. Ask for it — `App.jsx`
 
-```jsx file=App.jsx app=instagram-connection
+### `App.jsx`
+```jsx app=instagram-connection
 import { useConnection } from "use-vibes";
 
 function ConnectInstagram() {
@@ -113,7 +115,8 @@ the platform's Settings page, not in your app.
 
 ### 3. Read it — `backend.js`
 
-```js file=backend.js app=instagram-connection
+### `backend.js`
+```js app=instagram-connection
 import { instagram, connectionState } from "@vibes.diy/social";
 
 export async function fetch(request, ctx) {
@@ -188,7 +191,8 @@ connection. The path is the route under `/_api`, so `apiFetch("/top-posts")`
 reaches the `/top-posts` branch above. Wait for the connection before calling,
 so the first answer is the real one.
 
-```jsx file=App.jsx app=instagram-connection
+### `App.jsx`
+```jsx app=instagram-connection
 import React, { useEffect, useState } from "react";
 import { useConnection, apiFetch } from "use-vibes";
 

package/llms/create-vibe.md

@@ -24,7 +24,8 @@ never automatically from an effect, a timer, or straight out of an async `callAI
 resolution. Gate it behind an explicit "Create my ___" button the user presses
 when they're ready.
 
-```jsx file=App.jsx
+### `App.jsx`
+```jsx
 import React from "react";
 import { createVibe } from "use-vibes";
 import { Button } from "@vibes.diy/look";
@@ -63,7 +64,8 @@ Let the user edit each slide inline and present full-screen.`;
 
 ## Full pattern — interview, then hand off
 
-```jsx file=App.jsx
+### `App.jsx`
+```jsx
 import React from "react";
 import { callAI } from "call-ai";
 import { createVibe } from "use-vibes";

package/llms/d3.md

@@ -138,7 +138,8 @@ Structure your component in this order:
 
 ### 1. Simple Bar Chart
 
-```js file=App.jsx
+### `App.jsx`
+```js
 import * as d3 from "d3";
 
 // 1. Design tokens and dimensions

package/llms/fireproof.draft.md

@@ -0,0 +1,47 @@
+# Fireproof on vibes.diy — the short version
+
+Fireproof is the app's database: a local-first document store that syncs in the background. Records are plain JSON documents. Everything on screen comes from a live query, so the UI updates itself after every save.
+
+```jsx
+import { useFireproof } from "use-fireproof";
+
+export default function App() {
+  const { database, useLiveQuery, useDocument } = useFireproof("myApp"); // one plain camelCase name per app
+
+  // Read: every doc whose `type` is "note", newest first. `docs` re-renders on every change.
+  const { docs: notes } = useLiveQuery("type", { key: "note", descending: true });
+
+  // Create: one document per record. `type` names the record kind; stamp the author and the parent id.
+  const addNote = (text) => database.put({ type: "note", text, authorHandle: "me", createdAt: Date.now() });
+
+  // Update: spread the existing doc and change fields. Delete: by id.
+  const toggle = (note) => database.put({ ...note, done: !note.done });
+  const remove = (note) => database.del(note._id);
+
+  // A form bound to one document (edit view): `doc`, `merge` to change fields, `save` to persist.
+  const { doc, merge, save } = useDocument({ type: "note", text: "" });
+
+  return (
+    <main>
+      <input value={doc.text} onChange={(e) => merge({ text: e.target.value })} />
+      <button onClick={() => save()}>Save</button>
+      {notes.map((n) => (
+        <div key={n._id}>
+          <span onClick={() => toggle(n)}>{n.done ? "✓" : "○"} {n.text}</span>
+          <button onClick={() => remove(n)}>Delete</button>
+        </div>
+      ))}
+    </main>
+  );
+}
+```
+
+Rules of the road:
+
+- `useFireproof(name)` is called once at the top of a component; `useLiveQuery` and `useDocument` come from it and are also called at the top, outside handlers and loops.
+- `useLiveQuery(field, { key })` returns `{ docs }` matching `doc[field] === key`; `useLiveQuery(field)` returns every doc that has the field, sorted by it. `{ descending: true }` and `{ limit: n }` are available. Filter and sort further in plain JavaScript.
+- Documents get an auto `_id`; write one explicitly only for a well-known singleton (`"settings"`) or a one-per-person-per-thing record (`` `vote-${handle}-${postId}` ``), so re-saves replace rather than duplicate.
+- Writes land instantly and the store is the feedback: after `database.put`, the live query shows the new record. A saved card is the confirmation.
+- One document per event or record, and a `type` string on every document. Keep documents small; a list is many documents, each with the id of the list it belongs to (`listId`), rather than one document holding an array that grows.
+- Related records reference each other by `_id`. Seed items that other seed items point at carry an explicit `_id`, and the reference uses that exact string.
+- A list that renders one field per row can carry that field on the row: `useLiveQuery((doc, emit) => emit(doc.listId, { label: doc.label }), { key: listId })` puts the summary in `rows[].value` — exactly what was passed, including `0`, `""`, `false`, `null`, or an explicit `undefined` — while `docs` still holds the whole documents. Calling `emit(key)` alone leaves the whole document as the value.