@vibes.diy/prompts 2.5.17 → 2.5.19

package/llms/fireproof.md

@@ -394,7 +394,7 @@ The access function is the single source of truth for permissions. Gate write su
 
 This example shows the full round-trip — access.js declares channels and grants; App.jsx reads them back via `access`. Key details:
 
-- **Owner bootstrap:** `user.isOwner` gates management operations (channel setup, role grants, moderation). No bootstrap problem — the owner can always manage without needing a role granted first.
+- **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 `user.isOwner`** (`isOwner` is being retired from the access-fn `user`). 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.)
@@ -407,7 +407,7 @@ export function announcements(doc, oldDoc, user, ctx) {
   if (!user) throw { forbidden: "sign in" };
 
   if (doc.type === "channel") {
-    if (!user.isOwner) throw { forbidden: "owner only" };
+    ctx.requireRole("owner");
     return {
       channels: [doc._id],
       grant: {
@@ -419,7 +419,7 @@ export function announcements(doc, oldDoc, user, ctx) {
   }
 
   if (doc.type === "roleGrant") {
-    if (!user.isOwner) throw { forbidden: "owner only" };
+    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
@@ -463,8 +463,8 @@ export default function App() {
   // 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 throws "owner only"
-  // for non-owners, so this verdict is false for everyone but the owner.
+  // 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;
@@ -519,7 +519,7 @@ export default function App() {
 }
 ```
 
-The pattern: `useVibe().can` gates every write surface — including owner-only management, which the access function enforces via `if (!user.isOwner) throw` so `can.create({ type: "roleGrant", … })` is false for non-owners. `access.hasChannel()` reflects display-only membership, and `isOwner` is a display hint only, never the write gate. The access function is the server-side authority — `useVibe().can` is how the UI reflects its decisions for writes.
+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, and `isOwner` is a display hint only, never the write gate. 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.*`, not `isOwner`.** It's tempting to wrap an admin panel in `{isOwner && <ModeratorPanel />}` and have its buttons call `database.put`/`database.del` directly. Don't let `isOwner` be what decides a write — it's the same display hint as everywhere else. Gate each mutating control on the 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 it grows beyond owner-only (a delegated admin role, say). Gate the panel's *visibility* on those same verdicts too, not `isOwner` alone — otherwise a delegated admin the access function now allows never reaches the controls or their reason.
 
@@ -561,7 +561,7 @@ export function chat(doc, oldDoc, user, ctx) {
   if (!user) throw { forbidden: "sign in" };
 
   if (doc.type === "channel") {
-    if (!user.isOwner) throw { forbidden: "owner only" };
+    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] } };
@@ -612,6 +612,50 @@ App.jsx — `access.hasChannel()` filters which channels are visible (display);
 
 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)
+
+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; 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. The UI gates each surface with `useVibe("lists").can` and reflects which lists the viewer can see with `access.hasChannel(...)`.
+
 ---
 
 ## Access Function (`/access.js`)
@@ -732,7 +776,7 @@ export function survey(doc, oldDoc, user, ctx) {
   }
 
   if (doc.type === "survey-config") {
-    if (!user.isOwner) throw { forbidden: "owner only" };
+    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 {
@@ -853,7 +897,7 @@ export function chat(doc, oldDoc, user, ctx) {
   // Grant/meta docs must also route to a channel — a channel-less result is
   // rejected as "unreadable write". Route them to an owner-readable admin channel.
   if (doc.type === "team-meta") {
-    if (!user.isOwner) throw { forbidden: "owner only" };
+    ctx.requireRole("owner");
     return {
       channels: ["admin:grants"],
       members: { [doc.teamId]: doc.memberHandles },
@@ -862,7 +906,7 @@ export function chat(doc, oldDoc, user, ctx) {
   }
 
   if (doc.type === "membership") {
-    if (!user.isOwner) throw { forbidden: "owner only" };
+    ctx.requireRole("owner");
     return {
       channels: ["admin:grants"],
       members: { [doc.role]: [doc.userHandle] },
@@ -887,11 +931,11 @@ access.js
 ```js
 <<<<<<< SEARCH
   if (doc.type === "team-meta") {
-    if (!user.isOwner) throw { forbidden: "owner only" };
+    ctx.requireRole("owner");
     return {
 =======
   if (doc.type === "team-meta") {
-    if (!user.isOwner) throw { forbidden: "owner only" };
+    ctx.requireRole("owner");
     // Immutable-after-create fields
     if (oldDoc && doc.createdBy !== oldDoc.createdBy) {
       throw { forbidden: "createdBy is immutable" };

package/llms/use-vibe.md

@@ -39,7 +39,7 @@ function PromptBar({ database }) {
 
 ## Owner-only and role-gated surfaces
 
-Don't gate management UI on `isOwner` directly. Encode the rule in `access.js` (e.g. `if (!user.isOwner) throw { forbidden: "owner only" }`) and gate the UI on `can.*` for that database — the verdict reflects the same rule. Per-row edit/delete affordances: `{can.edit(doc).ok && <EditButton doc={doc} />}`.
+Don't gate management UI on `isOwner` directly. Encode the rule in `access.js` (e.g. `ctx.requireRole("owner")` — the owner is auto-seeded into the reserved `owner` role) and gate the UI on `can.*` for that database — the verdict reflects the same rule. Per-row edit/delete affordances: `{can.edit(doc).ok && <EditButton doc={doc} />}`. By default every signed-in visitor is a first-class participant who creates and edits their own data; reserve `requireRole("owner")` for genuinely owner-published apps and per-object channels for peer-to-peer sharing. Public-vs-private and the allowed-user list are the owner's runtime sharing settings, not `access.js`.
 
 ## The server is still the authority
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibes.diy/prompts",
-  "version": "2.5.17",
+  "version": "2.5.19",
   "type": "module",
   "main": "./index.js",
   "description": "",
@@ -30,9 +30,9 @@
     "@fireproof/core-types-base": "~0.24.19",
     "@fireproof/core-types-protocols-cloud": "~0.24.19",
     "@fireproof/use-fireproof": "~0.24.19",
-    "@vibes.diy/call-ai-v2": "^2.5.17",
-    "@vibes.diy/identity": "^2.5.17",
-    "@vibes.diy/use-vibes-types": "^2.5.17",
+    "@vibes.diy/call-ai-v2": "^2.5.19",
+    "@vibes.diy/identity": "^2.5.19",
+    "@vibes.diy/use-vibes-types": "^2.5.19",
     "arktype": "~2.2.1",
     "json-schema-faker": "~0.6.2"
   },

package/system-prompt-initial.md

@@ -63,7 +63,7 @@ Target ~40–60 lines. The shell should look like a real app with empty sections
 > export function chat(doc, oldDoc, user, ctx) {
 >   if (!user) throw { forbidden: "sign in" };
 >   if (doc.type === "channel") {
->     if (!user.isOwner) throw { forbidden: "owner only" };
+>     ctx.requireRole("owner"); // owner is auto-seeded into the reserved `owner` role
 >     return { channels: [doc._id], grant: { public: [doc._id] } };
 >   }
 >   if (doc.type === "message") {

package/system-prompt.md

@@ -347,6 +347,14 @@ Keep `useViewer` (for `ViewerTag`) on `App`'s first line, and add `useVibe(dbNam
 
 **If the app needs an `access.js`, emit it right after the scaffold — before any feature edits.** Write it 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. This commits to the permission design early so every subsequent App.jsx edit can gate its write surfaces on `useVibe(dbName).can` — the same rules the access function enforces. If later feature edits introduce new doc types, emit a follow-up `access.js` block with the additions.
 
+**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 to the board, drop a pin, read the blog. 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.
+
+When the app is genuinely one person's to publish — a personal blog, an announcements feed — the newcomer's job is to _read_: gate writes with `ctx.requireRole("owner")` (the vibe owner is always auto-seeded into the reserved `owner` role, so this needs no setup) and make reads public. For "author edits their own, owner moderates anyone's" in one branch, let `requireRole` be the fallback: `if (doc.authorHandle !== user.userHandle) ctx.requireRole("owner")` — it only throws when the author check fails, so authors pass for their own docs and the owner passes for any. Gate the UI on `useVibe(dbName).can`, never on `user.isOwner`.
+
+**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.
+
+**Public vs private is the owner's ACL envelope, not your code.** Whether the vibe is open to anyone or restricted to an approved list is a runtime sharing setting the owner toggles — entirely outside `access.js`. Keep `access.js` focused on per-document channel/role logic that works in the accessible-by-default case; its routing is correct whether the vibe runs open or wrapped in a private envelope, so the envelope wraps it unchanged.
+
 Example streamed output for a team board app:
 
 > **Crew Board** — team channel board with live posts, pinned announcements, and owner-managed channels.
@@ -404,7 +412,9 @@ Example streamed output for a team board app:
 > access.js
 >
 > ```js
-> // Each channel doc grants public READ to that channel; only the owner creates channels.
+> // Each channel doc grants public READ to that channel; only the owner creates
+> // channels. The vibe owner is auto-seeded into the reserved `owner` role, so
+> // gate owner-only docs on ctx.requireRole("owner") — never on user.isOwner.
 > // OPEN board: any signed-in user posts. Do NOT gate posts on ctx.requireAccess —
 > // grant.public is read-only and never satisfies it, so it would block every
 > // non-owner. (Members-only channel instead? grant a role + requireAccess it.)
@@ -412,7 +422,7 @@ Example streamed output for a team board app:
 >   if (!user) throw { forbidden: "sign in" };
 >
 >   if (doc.type === "channel") {
->     if (!user.isOwner) throw { forbidden: "owner only" };
+>     ctx.requireRole("owner");
 >     return { channels: [doc._id], grant: { public: [doc._id] } };
 >   }
 >