@vibes.diy/prompts 8.1.1 → 8.2.0

package/llms/access.md

@@ -0,0 +1,788 @@
+# Access Control (`access.js`) — permission design
+
+You are seeing this doc because the app's prompt is **permission-shaped** — it asks about privacy, sharing, teams, members, roles, DMs, approval, or who-can-see-what. Use it to design the app's `access.js`.
+
+**Honest default first:** all app data is shared and world-readable by default; the runtime, not your code, decides access. Add an `access.js` only when the app genuinely needs per-document write validation or channel-based read isolation. Never write UI copy that promises privacy the access model doesn't enforce — describe what the access rules actually do.
+
+`access.js` is a separate file alongside `App.jsx`; each **named export** gates the database of the same name (`export function chat(...)` gates `useFireproof("chat")`), and an `export default` acts as a catch-all. The `App.jsx` you write gates its write surfaces on `useVibe(dbName).can` — the same function this access.js enforces server-side. See the fireproof docs for the `access.js` function signature, `AccessDescriptor` return type, and channel/grant reference.
+
+## When to emit access.js, and where it goes
+
+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.
+
+**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.
+
+**Scaffold or follow-up turns (incremental `SEARCH`/`REPLACE` edits):** emit `access.js` **early** — for a fresh scaffold, right after the shell and before any feature edits; on a follow-up turn, **before** any `App.jsx` edit that writes a doc type it gates. Ordering matters here because the app runs live while edits stream in: a `db.put` of a doc type the in-force access.js still rejects fails immediately with `unknown document type`, so the access branch must land before the write. Emitting it first also commits the permission design so every subsequent edit can gate its write surfaces on `useVibe(dbName).can`.
+
+Worked example — members-only chat writes
+
+access.js
+
+```js
+export function chat(doc, oldDoc, user, ctx) {
+  if (!user) throw { forbidden: "authentication required" };
+
+  if (doc.type === "message") {
+    // Author fixed at create; ownership immutable. On update a non-author may
+    // only append one legitimate ImgGen version — the platform predicate
+    // ctx.isImgGenVersionAppend decides that (oldDoc is null on create).
+    if (oldDoc === null) {
+      if (doc.userHandle !== user.userHandle) throw { forbidden: "not author" };
+    } else if (doc.userHandle !== oldDoc.userHandle) {
+      throw { forbidden: "cannot change author" };
+    } else if (ctx.isImgGenVersionAppend(doc, oldDoc) === false && oldDoc.userHandle !== user.userHandle) {
+      throw { forbidden: "not author" };
+    }
+    ctx.requireAccess(doc.channelId);
+    return { channels: [doc.channelId] };
+  }
+
+  throw { forbidden: "unknown document type" };
+}
+```
+
+`ctx.requireAccess(channel)` gates on channel **membership** (a `grant.users`/`grant.roles` grant), NOT on `grant.public`, which is read-only — so a channel anyone signed-in should post to must **not** gate writes on `requireAccess` (it would block every non-owner); just check the author and route the doc. Reserve `requireAccess` for members-only channels whose writers you granted membership. For writes that need no sign-in at all ("anyone can sign/submit"), return `allowAnonymous: true` instead of throwing on `!user`. A grant/member/role doc must also return `channels` (route it to an owner-readable admin channel like `["admin:grants"]`) — a channel-less result is rejected as "unreadable write". On updates of shared-visible docs, keep ownership immutable (`if (oldDoc && doc.<authorField> !== oldDoc.<authorField>) throw`, where `<authorField>` is your doc's author field — `authorHandle`/`userHandle`/`senderHandle`) rather than requiring the updater to BE the author — image version appends run as the VIEWING user, and an author-only update gate turns every other viewer's generation into a billed deny-retry. Reserve author-only updates for genuinely private per-user docs; on shared docs, let a non-author through only when `ctx.isImgGenVersionAppend(doc, oldDoc)` accepts the write (as `chat.message` above shows) — it permits exactly one legitimate ImgGen version append and requires every other field unchanged.
+
+**A follow-up edit that adds a NEW doc type updates `access.js` FIRST.** The app runs live while your edits stream in, and writes are enforced against the access.js that was in force before this turn until the whole turn completes — so a `db.put` of a doc type the old function rejects fails immediately (`unknown document type`), even though your access.js update lands later in the same reply. Emit the access.js edit adding the new type's branch before the App.jsx edits that write it. And never fire-and-forget background writes of a newly added type: gate seed/auto-write effects on `useVibe(dbName)` — `if (!ready || !can.create(sampleDoc).ok) return;` with `ready`/`can` in the effect deps, checking a representative sample of **each** doc type the effect writes — so a not-yet-allowed write is skipped quietly instead of surfacing rejection errors the user didn't cause.
+
+## Worked examples — permission design
+
+### Worked example — open channel wall (author-owned writes)
+
+access.js
+
+```js
+export function wall(doc, oldDoc, user, ctx) {
+  if (!user) throw { forbidden: "sign in" };
+
+  if (doc.type === "channel") {
+    ctx.requireRole("owner");
+    return { channels: [doc._id], grant: { public: [doc._id] } };
+  }
+
+  if (doc.type === "post") {
+    // Author fixed at create; ownership immutable. On update a non-author may
+    // only append one legitimate ImgGen version — the platform predicate
+    // ctx.isImgGenVersionAppend decides that (oldDoc is null on create).
+    if (oldDoc === null) {
+      if (doc.authorHandle !== user.userHandle) throw { forbidden: "not author" };
+    } else if (doc.authorHandle !== oldDoc.authorHandle) {
+      throw { forbidden: "cannot change author" };
+    } else if (ctx.isImgGenVersionAppend(doc, oldDoc) === false && oldDoc.authorHandle !== user.userHandle) {
+      throw { forbidden: "not author" };
+    }
+    return { channels: [doc.channelId] };
+  }
+
+  throw { forbidden: "unknown document type" };
+}
+```
+
+### Worked example — per-object collaboration with join request
+
+access.js
+
+```js
+export function board(doc, oldDoc, user, ctx) {
+  if (!user) throw { forbidden: "sign in" };
+  const channel = `board:${doc.boardId}`;
+
+  if (doc.type === "board") {
+    if (oldDoc && doc.author !== oldDoc.author) throw { forbidden: "creator is fixed" };
+    return { channels: [channel], grant: { users: { [user.userHandle]: [channel] } } };
+  }
+
+  if (doc.type === "share") {
+    ctx.requireAccess(channel);
+    return { channels: [channel], grant: { users: { [doc.invitee]: [channel] } } };
+  }
+
+  if (doc.type === "request") return { channels: [channel] };
+
+  ctx.requireAccess(channel);
+  if (oldDoc && oldDoc.boardId !== doc.boardId) throw { forbidden: "item stays on its board" };
+  return { channels: [channel] };
+}
+```
+
+`ctx.requireAccess(channel)` gates on **membership** (a `grant.users`/`grant.roles` grant), not `grant.public` (read-only) — so an open feed anyone signed-in may post to must not gate writes on it; check the author and route the doc. For writes needing no sign-in ("anyone can sign/submit"), return `allowAnonymous: true` instead of throwing on `!user`. A grant/share/request doc must also return `channels` — a channel-less result is rejected. On updates of shared-visible docs, keep ownership immutable (`doc.authorHandle !== oldDoc.authorHandle` → throw) rather than requiring the updater to BE the author — image version appends run as the viewing user, and an author-only update gate turns every other viewer's generation into a billed deny-retry. Reserve author-only updates for genuinely private per-user docs; on shared docs, let a non-author through only when `ctx.isImgGenVersionAppend(doc, oldDoc)` accepts the write (as `wall.post` above shows) — it permits exactly one legitimate ImgGen version append and requires every other field unchanged.
+
+**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:
+
+access.js
+
+```js
+export function notes(doc, oldDoc, user, ctx) {
+  if (!user) throw { forbidden: "sign in" };
+  const ch = `user:${user.userHandle}`; // this visitor's own private space
+
+  if (doc.type === "note") {
+    if (!oldDoc) {
+      if (doc.authorHandle !== user.userHandle) throw { forbidden: "not author" };
+    } else {
+      if (doc.authorHandle !== oldDoc.authorHandle) throw { forbidden: "cannot change author" };
+      if (oldDoc.authorHandle !== user.userHandle) throw { forbidden: "not author" };
+    }
+    return { channels: [ch], grant: { users: { [user.userHandle]: [ch] } } };
+  }
+
+  throw { forbidden: "unknown document type" };
+}
+```
+
+Every item a visitor creates lands on their own `user:<handle>` channel, private to them from the first load. Pair it with a small "Only you can see this" cue near their content. This is the shape whenever the app is one person's own collection kept for themselves — the whole space is one private channel, no membership step in the way. The word "personal" routes on what the data is FOR: a personal tracker/journal/notes app is this private per-user shape, while a personal blog or portfolio exists to be READ — that one is the publication shape below (public read + author-owned posts, a roster of one), not a private channel.
+
+**When the prompt asks to share, invite, or collaborate — bring in a partner, a buddy, a friend, a team, or a group that co-edits — each shared thing becomes its own object others can be invited into.** A shopping list you invite your partner to, a board a group co-edits, a document you open to a collaborator: route that shared thing to its **own object channel** (`list:<id>`/`board:<id>`) and self-grant it at creation (`grant: { users: { [user.userHandle]: [ch] } }`), with the `authorHandle` create + `oldDoc` author checks so each item stays on its object. Then let the creator invite a chosen friend in: a `share` doc the creator authors grants that friend the same channel (`grant: { users: { [doc.invitee]: [ch] } }`), so they collaborate on that one list — sharing a single list or a whole space is the same grant at a different node of the object graph. A wall, guestbook, or map where each visitor adds their _own_ items is author-owned writes + public read: any signed-in visitor authors their own and everyone reads.
+
+**When a user's work is private by default, show it — and offer a way to publish.** If everything a user does routes to a channel only they can read (a per-user `user:<handle>`, a private journal/notes/tracker with no `grant.public`), the UI must say so: a small, persistent "Only you can see this" / "Private to you" cue near their content, so no one wonders who's watching their unfinished work. Then, where sharing fits the app, give them a publish control — but publish at the granularity of a **channel**, not a doc: channels are the unit of read isolation, so adding `grant.public` to the shared `user:<handle>` channel would expose _every_ private item on it, not just the one they meant to share. To publish a single item, route it to its **own** channel and flip only that channel's read-grant from a `visibility` field the access fn reads — exactly the per-item-channel shape the worked example below uses (`const ch = \`entry:${doc._id}\`; const grant = { users: { [user.userHandle]: [ch] } }; if (doc.visibility === "public") grant.public = [ch];`) — for anonymous visitors, or grant a shared app channel for all granted members. Gate the control on `useVibe(dbName).can`, and reflect the result back in the affordance ("Published — anyone can see this", with an unpublish to flip it back). Making the user's _whole_ space public is fine when that's the intent; silently leaking their other private items by publishing one is the trap to avoid. **If the app brief is private-only/confidential — a journal, private notes, a health tracker — do not add publish/share controls.** Keep publish opt-in: for private-only apps, omit the publish UI entirely; for share-capable apps, make publish one tap for user-selected items.
+
+**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
+export function habits(doc, oldDoc, user, ctx) {
+  if (!user) throw { forbidden: "sign in" };
+
+  // A habit: a public object anyone proposes; everyone can read and adopt it.
+  if (doc.type === "habit") {
+    if (doc.authorHandle !== user.userHandle) throw { forbidden: "not author" };
+    if (oldDoc && doc.authorHandle !== oldDoc.authorHandle) throw { forbidden: "creator is fixed" };
+    return { channels: [`habit:${doc._id}`], grant: { public: [`habit:${doc._id}`] } };
+  }
+
+  // A tracking record: your enrollment in a habit + ONE visibility choice. It sets the
+  // read-grant on your per-habit channel, so the check-ins routed there inherit it.
+  if (doc.type === "tracking") {
+    if (doc.authorHandle !== user.userHandle) throw { forbidden: "your own enrollment" };
+    if (oldDoc && oldDoc.authorHandle !== user.userHandle) throw { forbidden: "your own enrollment" };
+    const ch = `track:${doc.habitId}:${user.userHandle}`;
+    const grant = { users: { [user.userHandle]: [ch] } }; // always yourself
+    if (doc.visibility === "public") grant.public = [ch]; // public -> counts on the leaderboard
+    else if (doc.buddyHandle) grant.users[doc.buddyHandle] = [ch]; // buddy-only -> you + your buddy
+    return { channels: [ch], grant };
+  }
+
+  // A check-in: author-owned, routed to your per-habit channel — it inherits that habit's visibility.
+  if (doc.type === "checkin") {
+    if (doc.authorHandle !== user.userHandle) throw { forbidden: "not your check-in" };
+    if (oldDoc && oldDoc.authorHandle !== user.userHandle) throw { forbidden: "not your check-in" };
+    return { channels: [`track:${doc.habitId}:${user.userHandle}`] };
+  }
+
+  throw { forbidden: "unknown document type" };
+}
+```
+
+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.
+
+**"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).
+
+**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`.
+
+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
+if (doc.type === "post") {
+  if (!oldDoc) {
+    if (doc.authorHandle !== user.userHandle) throw { forbidden: "not author" };
+  } else if (doc.authorHandle !== oldDoc.authorHandle) throw { forbidden: "author is fixed" };
+  return { channels: ["posts"], grant: { public: ["posts"] } };
+}
+```
+
+When the prompt also asks for drafts, keep the same public resting state for posts and give drafts their own author-only channel (`draft:<handle>`, granted just to the author) — publishing moves the doc to the public `posts` channel.
+
+**Sharing objects: channels carry objects, roles carry types.** A channel is one shareable thing (`list:<id>`) — membership in it means "can reach this object." A role is a _kind_ of participant (`author`, `editor`), a small reusable vocabulary. To let people collaborate on _their own_ objects with no admin in the loop: the creator routes the object to its channel and grants themselves access; any member shares it by granting a peer into the same channel; child docs gate on `ctx.requireAccess("list:<id>")`. The reserved `owner` role is the only one auto-seeded — every _other_ role is populated by the app's own grant docs (a member writes a doc whose access-fn output adds another user to a role or channel). So to put someone in a role, write a grant; don't expect a role to be pre-filled. Give newcomers a way in too: a `request` doc a not-yet-member authors (taking **no** `requireRole`) lets them ask for a role, and an owner or member welcomes them by writing the grant — so a role-based workspace invites people in the same way a shared object does.
+
+## Reading Resolved Grants (`access`)
+
+`useFireproof()` returns an `access` property — the viewer's resolved roles and channels for that database, computed server-side from the access function's `members` and `grant` declarations. Use `access.roles` (ReadonlySet), `access.channels` (ReadonlySet), `access.hasRole(name)`, and `access.hasChannel(name)`. Use these to reflect roles/channels in the UI; gate writes with `useVibe(dbName).can`.
+
+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
+
+```jsx
+<<<<<<< SEARCH
+import { useFireproof } from "use-fireproof";
+=======
+import { useFireproof } from "use-fireproof";
+import { useVibe } from "use-vibes";
+>>>>>>> REPLACE
+```
+
+App.jsx
+
+```jsx
+<<<<<<< SEARCH
+  const { useLiveQuery, database } = useFireproof("announcements", {
+    acl: { write: ["members"], delete: ["editors"] },
+  });
+=======
+  const { database, useLiveQuery, access } = useFireproof("comments");
+  const { can, me } = useVibe("comments");
+>>>>>>> REPLACE
+```
+
+App.jsx
+
+```jsx
+<<<<<<< SEARCH
+      <h3>Recent Documents</h3>
+      <ul>
+        {docs.map((doc) => (
+          <li key={doc._id}>
+            {doc.text}
+            <button onClick={() => database.put({ ...doc, favorite: !doc.favorite })}>
+              {doc.favorite ? "★" : "☆"}
+            </button>
+          </li>
+        ))}
+      </ul>
+=======
+      {/* gate writes with useVibe().can, not access.* — and gate the SAME db you write to */}
+      {can.create({ type: "comment", authorHandle: me?.userHandle }).ok && <CommentForm database={database} />}
+      {access.hasRole("moderator") && <ModToolsBadge />}
+      {access.hasChannel("announcements") && <Announcements />}
+>>>>>>> REPLACE
+```
+
+The AI agent writes the access function (so it knows the role names) and writes the UI (so it knows which roles gate which components). The `access` object is the bridge — it lets the UI reflect server-enforced permissions without duplicating the logic.
+
+The access function is the single source of truth for permissions. Gate write surfaces with `useVibe(dbName).can`, which runs this same access function. The `access` object (`access.hasRole(name)`, `access.hasChannel(name)`) reflects the viewer's resolved roles/channels for DISPLAY — role badges, showing/hiding read-only sections — not as the write gate.
+
+`access.hasChannel()` covers every grant path — public channels, restricted channels, role-expanded channels. The access function decides who gets access and how; the UI uses `access.hasChannel(name)` to reflect membership for display.
+
+### Complete example: Team announcements with channels
+
+This example shows the full round-trip — access.js declares channels and grants; App.jsx reads them back via `access`. Key details:
+
+- **Owner bootstrap:** the vibe owner is auto-seeded into the reserved `owner` role, so gate management operations (channel setup, role grants, moderation) on `ctx.requireRole("owner")` — **never on a display flag** (the UI gates on `can.*`). No bootstrap problem — the seed means the owner can manage without a prior grant. Default content, though, should be author-owned (anyone signed-in creates and edits their own); reserve owner-gating for shared admin surfaces.
+- **Channel identity:** Channel docs use `_id: "ch:" + name` so names are unique. The `_id` is the channel identifier everywhere — in `channels`, `grant`, and `ctx.requireAccess()`.
+- **Channel grant:** A channel document grants the creator (`grant.users`), adds `grant.public` so all members can read, and `grant.roles` so posters can write.
+- **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 and sign-in button are 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).
+
+access.js
+
+```js
+export function announcements(doc, oldDoc, user, ctx) {
+  if (!user) throw { forbidden: "sign in" };
+
+  if (doc.type === "channel") {
+    ctx.requireRole("owner");
+    return {
+      channels: [doc._id],
+      grant: {
+        users: { [user.userHandle]: [doc._id] },
+        public: [doc._id],
+        roles: { poster: [doc._id] },
+      },
+    };
+  }
+
+  if (doc.type === "roleGrant") {
+    ctx.requireRole("owner");
+    // A grant doc must ALSO route to a channel — a result with no `channels`
+    // (only `members`/`grant`) is rejected as an "unreadable write". Route it to
+    // an owner-readable admin channel (not a public one) so the grant persists
+    // and the owner can read the roster back; the membership then applies.
+    return {
+      channels: ["admin:grants"],
+      members: { [doc.role]: [doc.userHandle] },
+      grant: { users: { [user.userHandle]: ["admin:grants"] } },
+    };
+  }
+
+  if (doc.type === "post") {
+    // Author fixed at create; ownership immutable. On update a non-author may
+    // only append one legitimate ImgGen version — the platform predicate
+    // ctx.isImgGenVersionAppend decides that (oldDoc is null on create).
+    if (oldDoc === null) {
+      if (doc.authorHandle !== user.userHandle) throw { forbidden: "not author" };
+    } else if (doc.authorHandle !== oldDoc.authorHandle) {
+      throw { forbidden: "cannot change author" };
+    } else if (ctx.isImgGenVersionAppend(doc, oldDoc) === false && oldDoc.authorHandle !== user.userHandle) {
+      throw { forbidden: "not author" };
+    }
+    ctx.requireAccess(doc.channel);
+    return { channels: [doc.channel] };
+  }
+
+  throw { forbidden: "unknown document type" };
+}
+```
+
+App.jsx — `useVibe().can` gates every write surface (posts AND owner-only management); `access.hasChannel()` reflects display-only membership:
+
+```jsx
+import React from "react";
+import { useFireproof } from "use-fireproof";
+import { useViewer, useVibe } from "use-vibes";
+
+export default function App() {
+  const { viewer, isViewerPending, ViewerTag } = useViewer();
+  const { database, useLiveQuery, access } = useFireproof("announcements");
+  const { can } = useVibe("announcements");
+
+  const { docs: posts } = useLiveQuery("type", { key: "post" });
+  const [draft, setDraft] = React.useState("");
+  const [channel, setChannel] = React.useState("general");
+  // Build each candidate from the doc you'll actually write — the access function
+  // checks authorHandle/channel (and owner-only for roleGrant), so a bare partial
+  // would be denied and hide the control even from users who can act.
+  const canPost = can.create({ type: "post", channel, authorHandle: viewer?.userHandle });
+  // Owner-only management gates on can.* too — the access fn calls
+  // ctx.requireRole("owner"), so this verdict is false for everyone but the owner.
+  const canGrant = can.create({ type: "roleGrant", role: "poster", userHandle: "newUser" });
+
+  if (isViewerPending) return null;
+
+  async function submitPost() {
+    if (!draft.trim() || !viewer) return;
+    await database.put({
+      type: "post",
+      channel,
+      body: draft.trim(),
+      authorHandle: viewer.userHandle,
+      createdAt: Date.now(),
+    });
+    setDraft("");
+  }
+
+  return (
+    <div>
+      {/* No current-user pill / sign-in button here — that's system chrome in the
+          Vibes Switch (the panel the logo opens). ViewerTag below renders post authors. */}
+
+      {/* gate the write surface on useVibe().can — it runs the access function */}
+      {canPost.ok ? (
+        <form
+          onSubmit={(e) => {
+            e.preventDefault();
+            submitPost();
+          }}
+        >
+          <textarea value={draft} onChange={(e) => setDraft(e.target.value)} />
+          <button type="submit">Post</button>
+        </form>
+      ) : (
+        viewer && <p style={{ color: "var(--muted, #888)" }}>{canPost.reason}</p>
+      )}
+
+      {/* owner-only management — gated on can.* */}
+      {canGrant.ok && (
+        <button onClick={() => database.put({ type: "roleGrant", role: "poster", userHandle: "newUser" })}>
+          Grant poster role
+        </button>
+      )}
+
+      {posts.map((p) => (
+        <div key={p._id}>
+          <ViewerTag userHandle={p.authorHandle} />
+          <p>{p.body}</p>
+          {can.delete(p).ok && <button onClick={() => database.del(p._id)}>Delete</button>}
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+The pattern: `useVibe().can` gates every write surface — including owner-only management, which the access function enforces via `ctx.requireRole("owner")` so `can.create({ type: "roleGrant", … })` is false for non-owners. `access.hasChannel()` reflects display-only membership; the write gate is always `can.*`. The access function is the server-side authority — `useVibe().can` is how the UI reflects its decisions for writes.
+
+**Owner-management panels (appoint/revoke moderators, grant/revoke roles) gate on `can.*`.** Gate each mutating control — and the panel's visibility — on the `can.*` verdict from the doc you'll actually write: appoint on `can.create({ type: "modGrant", role: "moderator", userHandle }).ok`, revoke on `can.delete(grantDoc).ok` — and render `.reason` when denied. `can.*` runs the app's own `access.js` to produce the verdict, so the control's enabled state and message track what the access function decides and stay correct as the rule grows beyond owner-only (a delegated admin role, say).
+
+```jsx
+// Gate visibility AND each write on the can.* verdict, and supply the denial reason
+const canAppoint = can.create({ type: "modGrant", role: "moderator", userHandle });
+const canRevoke = can.delete(grantDoc);
+{(canAppoint.ok || canRevoke.ok) && (
+  <ModeratorPanel>
+    {canAppoint.ok && (
+      <button onClick={() => database.put({ type: "modGrant", role: "moderator", userHandle })}>Appoint</button>
+    )}
+    {canRevoke.ok ? (
+      <button onClick={() => database.del(grantDoc._id)}>Revoke</button>
+    ) : (
+      <p>{canRevoke.reason}</p>
+    )}
+  </ModeratorPanel>
+)}
+```
+
+### Example: Channel board with open channels (any member posts)
+
+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
+export function chat(doc, oldDoc, user, ctx) {
+  if (!user) throw { forbidden: "sign in" };
+
+  if (doc.type === "channel") {
+    ctx.requireRole("owner");
+    // Open channel: public READ for everyone. No write-membership grant is
+    // needed — any signed-in user may post (see the post rule below).
+    return { channels: [doc._id], grant: { public: [doc._id] } };
+  }
+
+  if (doc.type === "post") {
+    // Author fixed at create; ownership immutable. On update a non-author may
+    // only append one legitimate ImgGen version — the platform predicate
+    // ctx.isImgGenVersionAppend decides that (oldDoc is null on create).
+    if (oldDoc === null) {
+      if (doc.authorHandle !== user.userHandle) throw { forbidden: "not author" };
+    } else if (doc.authorHandle !== oldDoc.authorHandle) {
+      throw { forbidden: "cannot change author" };
+    } else if (ctx.isImgGenVersionAppend(doc, oldDoc) === false && oldDoc.authorHandle !== user.userHandle) {
+      throw { forbidden: "not author" };
+    }
+    // Any signed-in author may post to this open channel. Do NOT call
+    // ctx.requireAccess(doc.channel) here: the channel is grant.public
+    // (read-only), which never satisfies requireAccess, so gating on it would
+    // block every non-owner from posting. requireAccess is for members-only
+    // channels whose writers were granted membership (see announcements above).
+    return { channels: [doc.channel] };
+  }
+
+  throw { forbidden: "unknown document type" };
+}
+```
+
+App.jsx — `access.hasChannel()` filters which channels are visible (display); `useVibe().can` gates the write surface:
+
+```jsx
+<<<<<<< SEARCH
+  const { database, useLiveQuery, access } = useFireproof("announcements");
+=======
+  const { database, useLiveQuery, access } = useFireproof("chat");
+  const { docs: channels } = useLiveQuery("type", { key: "channel" });
+  // Build the candidate from the doc you'll write — the access fn checks
+  // authorHandle, so a bare { type: "post" } would be denied and hide the form.
+  const canPost = useVibe("chat").can.create({ type: "post", channel, authorHandle: viewer?.userHandle });
+>>>>>>> REPLACE
+```
+
+```jsx
+<<<<<<< SEARCH
+      {viewer && access.hasChannel(channel) && (
+=======
+      {/* filter to channels the viewer can see — use _id as channel identifier (display only) */}
+      {channels.filter((ch) => access.hasChannel(ch._id)).map((ch) => (
+        <button key={ch._id} onClick={() => setChannel(ch._id)}>{ch.name}</button>
+      ))}
+
+      {/* gate the write surface on useVibe().can */}
+      {canPost.ok ? (
+>>>>>>> REPLACE
+```
+
+Channel `_id` is the channel identifier everywhere. The access function uses `doc._id` for routing and grants. A deterministic `_id` like `"ch:" + name` enforces uniqueness — two users can't create duplicate channels.
+
+### 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.
+
+access.js
+
+```js
+export default function (doc, oldDoc, user, ctx) {
+  if (!user) throw { forbidden: "sign in" };
+  const ch = (id) => `list:${id}`;
+
+  if (doc.type === "list") {
+    // Creator owns the list doc; route it to its own channel and grant self.
+    const author = oldDoc ? oldDoc.author : doc.author;
+    if (author !== user.userHandle) throw { forbidden: "not your list" };
+    // author is write-once: an update must not re-author the list (which would
+    // change who can edit it and hand control to someone never granted).
+    if (oldDoc && doc.author !== oldDoc.author) throw { forbidden: "cannot change author" };
+    return { channels: [ch(doc._id)], grant: { users: { [user.userHandle]: [ch(doc._id)] } } };
+  }
+
+  if (doc.type === "item") {
+    // Any member of the list may add/edit items in it. listId is immutable —
+    // without this, a member of list X could re-point an existing item from a
+    // list they don't belong to into X (it would still pass requireAccess(X)).
+    if (oldDoc && oldDoc.listId !== doc.listId) throw { forbidden: "cannot move item" };
+    ctx.requireAccess(ch(doc.listId));
+    return { channels: [ch(doc.listId)] };
+  }
+
+  if (doc.type === "share") {
+    // Any current member invites a peer by handle — grants them the list channel.
+    // Route the share doc to the list channel itself (every member already holds
+    // it), so members see who was added without a second channel to grant.
+    ctx.requireAccess(ch(doc.listId));
+    return { channels: [ch(doc.listId)], grant: { users: { [doc.invitee]: [ch(doc.listId)] } } };
+  }
+
+  throw { forbidden: "unknown document type" };
+}
+```
+
+To invite someone who isn't a member yet without knowing their handle in advance, invert the flow with a request doc: a `request` type takes **no** `ctx.requireAccess` (any signed-in user may create one — their handle is `user.userHandle`, unforgeable) and routes to the list channel `ch(doc.listId)`, where current members read it (the requester can't read their own request back — they aren't a member yet — which is fine; they just wait to be granted). A member then writes the `share` above to approve.
+
+App.jsx — `access.hasChannel()` shows only the lists the viewer belongs to; `useVibe("lists").can` gates each write surface (create list, add item, invite peer):
+
+```jsx
+<<<<<<< SEARCH
+  const { database, useLiveQuery, access } = useFireproof("notes");
+=======
+  const { database, useLiveQuery, access } = useFireproof("lists");
+  const { me, can } = useVibe("lists");
+  const { docs: lists } = useLiveQuery("type", { key: "list" });
+  const visible = lists.filter((l) => access.hasChannel(`list:${l._id}`));
+  // Each member edits any item — items gate on requireAccess(list:<id>), not authorHandle.
+  const canAddItem = (list) => can.create({ type: "item", listId: list._id, authorHandle: me?.userHandle }).ok;
+  const canShare = (list) => can.create({ type: "share", listId: list._id, invitee: "x" }).ok;
+>>>>>>> REPLACE
+```
+
+```jsx
+<<<<<<< SEARCH
+      {viewer && <button onClick={addNote}>+ note</button>}
+=======
+      {/* create list — any signed-in visitor can start their own */}
+      {can.create({ type: "list", author: me?.userHandle }).ok && (
+        <button onClick={() => database.put({ type: "list", author: me.userHandle, name: "new list" })}>
+          + new list
+        </button>
+      )}
+
+      {visible.map((list) => (
+        <section key={list._id}>
+          <h3>{list.name}</h3>
+          {/* add-item form is shown only when the access fn would accept the write */}
+          {canAddItem(list) && <AddItemForm listId={list._id} />}
+          {/* invite peer — only shown to members of this list */}
+          {canShare(list) && <ShareForm listId={list._id} />}
+        </section>
+      ))}
+>>>>>>> REPLACE
+```
+
+## More worked round-trip examples
+
+### Example: Workspace chat with channels
+
+access.js
+
+```js
+export function chat(doc, oldDoc, user, ctx) {
+  if (!user) throw { forbidden: "authentication required" };
+
+  if (doc.type === "channel-meta") {
+    if (doc.ownerHandle !== user.userHandle) throw { forbidden: "not owner" };
+    if (oldDoc && oldDoc.ownerHandle !== user.userHandle) throw { forbidden: "not owner" };
+    return {
+      channels: [doc._id],
+      grant: {
+        users: Object.fromEntries([[doc.ownerHandle, [doc._id]], ...doc.memberHandles.map((h) => [h, [doc._id]])]),
+      },
+    };
+  }
+
+  if (doc.type === "message") {
+    // Author fixed at create; ownership immutable. On update a non-author may
+    // only append one legitimate ImgGen version — the platform predicate
+    // ctx.isImgGenVersionAppend decides that (oldDoc is null on create).
+    if (oldDoc === null) {
+      if (doc.userHandle !== user.userHandle) throw { forbidden: "not author" };
+    } else if (doc.userHandle !== oldDoc.userHandle) {
+      throw { forbidden: "cannot change author" };
+    } else if (ctx.isImgGenVersionAppend(doc, oldDoc) === false && oldDoc.userHandle !== user.userHandle) {
+      throw { forbidden: "not author" };
+    }
+    ctx.requireAccess(doc.channelId);
+    return { channels: [doc.channelId] };
+  }
+
+  if (doc.type === "channel-invite") {
+    if (doc.senderHandle !== user.userHandle) throw { forbidden: "not sender" };
+    if (oldDoc && oldDoc.senderHandle !== user.userHandle) throw { forbidden: "not sender" };
+    ctx.requireAccess(doc.channelId);
+    return {
+      channels: [doc.channelId],
+      grant: { users: { [doc.inviteeHandle]: [doc.channelId] } },
+    };
+  }
+
+  throw { forbidden: "unknown document type" };
+}
+```
+
+This single access function handles three document types: **channel-meta** — owner creates a channel and grants access to listed members, **message** — only the author can post, must already have channel access, **channel-invite** — any channel member can invite others; deleting the invite revokes the grant.
+
+App.jsx — show only channels the viewer is in (`access.hasChannel`), gate the compose box and invite form on `useVibe().can`:
+
+```jsx
+<<<<<<< SEARCH
+  const { database, useLiveQuery, access } = useFireproof("notes");
+=======
+  const { database, useLiveQuery, access } = useFireproof("chat");
+  const { me, can } = useVibe("chat");
+  const { docs: channels } = useLiveQuery("type", { key: "channel-meta" });
+  // Filter to channels the viewer has been granted into — non-members never see them in the list.
+  const myChannels = channels.filter((ch) => access.hasChannel(ch._id));
+  const [channelId, setChannelId] = React.useState(null);
+  const canPost = can.create({ type: "message", channelId, userHandle: me?.userHandle });
+  const canInvite = can.create({ type: "channel-invite", channelId, senderHandle: me?.userHandle, inviteeHandle: "x" });
+>>>>>>> REPLACE
+```
+
+```jsx
+<<<<<<< SEARCH
+      {viewer && <Compose onSend={send} />}
+=======
+      {/* sidebar lists only the channels the viewer is in */}
+      <nav>{myChannels.map((ch) => <button key={ch._id} onClick={() => setChannelId(ch._id)}>{ch.name}</button>)}</nav>
+
+      {/* compose is shown only when the viewer is a member of the selected channel */}
+      {channelId && canPost.ok ? (
+        <Compose onSend={(text) => database.put({ type: "message", channelId, userHandle: me.userHandle, text })} />
+      ) : (
+        <p>{canPost.reason || "Pick a channel"}</p>
+      )}
+
+      {/* any member of this channel may invite a peer */}
+      {channelId && canInvite.ok && <InviteForm channelId={channelId} senderHandle={me.userHandle} />}
+>>>>>>> REPLACE
+```
+
+### Example: Anonymous survey with role-gated results
+
+access.js
+
+```js
+export function survey(doc, oldDoc, user, ctx) {
+  if (doc.type === "survey-response") {
+    if (oldDoc) throw { forbidden: "responses are write-once" };
+    return { channels: ["inbound-responses"], allowAnonymous: true };
+  }
+
+  if (doc.type === "survey-config") {
+    ctx.requireRole("owner");
+    // Route this grant/config doc to an owner-readable admin channel — a
+    // grant-only result (no `channels`) is rejected as an "unreadable write".
+    return {
+      channels: ["admin:grants"],
+      grant: {
+        users: { [user.userHandle]: ["admin:grants"] },
+        roles: { "feedback-team": ["inbound-responses"] },
+      },
+    };
+  }
+
+  if (doc.type === "final-results") {
+    ctx.requireRole("feedback-team");
+    return { channels: [doc._id], grant: { public: [doc._id] } };
+  }
+
+  throw { forbidden: "unknown document type" };
+}
+```
+
+Key patterns: `allowAnonymous: true` on survey-response lets unauthenticated visitors submit, `grant.public` on final-results makes them readable by any member without a specific channel grant, and the **singleton grant doc** pattern (survey-config) wires role-to-channel access in one place.
+
+App.jsx — anonymous-friendly submit form, owner-only config panel, role-gated results view:
+
+```jsx
+<<<<<<< SEARCH
+  const { database } = useFireproof("notes");
+=======
+  const { database, useLiveQuery, access } = useFireproof("survey");
+  const { me, can } = useVibe("survey");
+  // Submit form is shown for anyone — allowAnonymous makes this can.create return ok for null user.
+  const canSubmit = can.create({ type: "survey-response", question: "q1", answer: "" });
+  // Owner-only — survey-config rule calls ctx.requireRole("owner").
+  const canConfigure = can.create({ type: "survey-config" });
+  const { docs: results } = useLiveQuery("type", { key: "final-results" });
+>>>>>>> REPLACE
+```
+
+```jsx
+<<<<<<< SEARCH
+      <input value={answer} onChange={(e) => setAnswer(e.target.value)} />
+=======
+      {/* anyone (signed in OR anonymous) can submit — only stamp authorHandle when present */}
+      {canSubmit.ok ? (
+        <form onSubmit={(e) => {
+          e.preventDefault();
+          database.put({ type: "survey-response", question: "q1", answer, ...(me && { authorHandle: me.userHandle }) });
+        }}>
+          <input value={answer} onChange={(e) => setAnswer(e.target.value)} />
+          <button type="submit">Submit</button>
+        </form>
+      ) : <p>{canSubmit.reason}</p>}
+
+      {/* owner-only admin to wire up the feedback-team role */}
+      {canConfigure.ok && <ConfigPanel />}
+
+      {/* results render only for users with the feedback-team role — access.hasChannel filters them in */}
+      {results.filter((r) => access.hasChannel(r._id)).map((r) => <ResultCard key={r._id} doc={r} />)}
+>>>>>>> REPLACE
+```
+
+### Example: Public guestbook / contact form (anonymous writes)
+
+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
+export function guestbook(doc, oldDoc, user, ctx) {
+  if (doc.type === "entry") {
+    if (oldDoc) throw { forbidden: "entries are write-once" };
+    // No `if (!user) throw` — anyone may sign. allowAnonymous opts the write in.
+    return { channels: ["public"], grant: { public: ["public"] }, allowAnonymous: true };
+  }
+  throw { forbidden: "unknown document type" };
+}
+```
+
+In `App.jsx`, gate the form on `useVibe("guestbook").can.create({ type: "entry" }).ok` (true for anon here) and stamp `authorHandle: me?.userHandle` only when signed in. Without `allowAnonymous: true` the runtime rejects the null-user write even though the function didn't throw — so the guestbook would silently require login, the exact miss to avoid.
+
+App.jsx — gate the form on `can.create({ type: "entry" }).ok`, which is true even when nobody is signed in:
+
+```jsx
+<<<<<<< SEARCH
+  const { database } = useFireproof("notes");
+=======
+  const { database, useLiveQuery } = useFireproof("guestbook");
+  const { me, can } = useVibe("guestbook");
+  const { docs: entries } = useLiveQuery("type", { key: "entry" });
+  // allowAnonymous: true on the access fn → this returns ok for an anon viewer.
+  // The form is visible from first load, no sign-in wall.
+  const canSign = can.create({ type: "entry", message: "" });
+>>>>>>> REPLACE
+```
+
+```jsx
+<<<<<<< SEARCH
+      <SignInGate>
+        <input value={message} onChange={(e) => setMessage(e.target.value)} />
+      </SignInGate>
+=======
+      {canSign.ok ? (
+        <form onSubmit={(e) => {
+          e.preventDefault();
+          // Stamp authorHandle only when signed in — anon entries simply omit it.
+          database.put({ type: "entry", message, createdAt: Date.now(), ...(me && { authorHandle: me.userHandle }) });
+          setMessage("");
+        }}>
+          <input value={message} onChange={(e) => setMessage(e.target.value)} placeholder="Leave a note" />
+          <button type="submit">Sign</button>
+        </form>
+      ) : <p>{canSign.reason}</p>}
+
+      {entries.map((e) => <li key={e._id}>{e.message} — {e.authorHandle || "anonymous"}</li>)}
+>>>>>>> REPLACE
+```