@vibes.diy/prompts 14.1.23 → 14.1.25

package/llms/access.md

@@ -1,8 +1,10 @@
 # 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`.
+This doc is in view because the app is getting its `access.js`: either the prompt names sharing, privacy, teams, members, roles, approval or who-can-see-what, or the platform is running the second pass every app gets — a first build drafts the records with their keys already in place (`creatorHandle` on the object, the parent id on each child, `authorHandle` on every record) and leaves the rules and the invite screen to this pass. Every app gets record rules unless the person asked for none in their own words, and the group shape taught below is the resting default.
 
-**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.
+**On a second pass over an app that already exists, this is a whole-app upgrade, applied in full.** Read `App.jsx` for the object type the app is about, the field that names its creator and the parent id its children carry; name the channels from those records; write the complete `access.js`; then change `App.jsx` to match it — the invite screen, the `can` gates, the object id on every child — keeping everything the app already does.
+
+**Honest copy:** until `access.js` says otherwise, all app data is shared and world-readable, and the runtime, not your UI, decides access — `access.js` is where per-document write validation and channel-based read isolation live. Write UI copy that describes what the 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.
 
@@ -10,8 +12,9 @@ Construct the document an action will save, check that same value with `can.crea
 `can.edit`, then write it to the same database. Include every field the access rule checks,
 including the intended next status. For example, cancelling a reservation constructs
 `const next = { ...reservation, status: "cancelled" }`, checks `can.edit(next).ok`, and
-saves `next`. A creation control checks the complete creation draft. Render the verdict's
-reason when denied, and keep loading and signed-out states distinct from denial.
+saves `next`. A creation control checks the complete creation draft. On a denial render a
+sentence in the app's own words — `reason` is a machine token that informs that sentence —
+and keep loading and signed-out states distinct from denial.
 
 ## Reference
 
@@ -108,7 +111,7 @@ The platform predicate `ctx.isImgGenVersionAppend(doc, oldDoc)` accepts exactly
 
 ### `_id` strategy matters
 
-Documents that represent a unique named resource (channels, user profiles, config singletons, starter content) should use a deterministic `_id` with a short prefix — `"ch:" + name`, `"profile:" + handle`, `"config"`, `"starter:" + key`. This enforces uniqueness: two users creating "general" get the same doc, not two — and a first-load write that runs again (a fresh tab, another device) overwrites the same starter docs instead of duplicating them. Records a request says the app must already have are created this way, by the app's first render; see "Required starting records" in `fireproof.md`. Documents that represent events or content (messages, posts, survey responses) should let `_id` be auto-generated — each one is unique by nature. Use `doc._id` as the channel name for resource docs; use a `channelId` foreign key on content docs.
+Documents that represent a unique named resource (channels, user profiles, config singletons, starter content) should use a deterministic `_id` with a short prefix — `"ch:" + name`, `"profile:" + handle`, `"config"`, `"starter:" + key`. This enforces uniqueness: two users creating "general" get the same doc, not two — and a first-load write that runs again (a fresh tab, another device) overwrites the same starter docs instead of duplicating them. Records a request says the app must already have are created this way, by the app's first render; see "Required starting records" in `fireproof.md`. Documents that represent events or content (messages, posts, survey responses) should let `_id` be auto-generated — each one is unique by nature. A resource doc's channel is computed from the record itself — its own prefixed `_id`, or `board:${doc._id}` — and a content doc carries that object's id as a foreign key and routes to the same computed name.
 
 ### Grants are additive
 
@@ -124,7 +127,7 @@ If `user` is `null` and the function returns without throwing, the runtime check
 
 A channel is a _reusable_ unit of read access: grant a user into a channel once and they can read every document routed there. Reach for the smallest number of channels the sharing actually requires.
 
-- **A reusable group reads many docs** (a team, a board, a project): route to one channel the _collaboration_ owns — `return { channels: [doc.channelId] }` — and grant membership once via a meta or invite doc. Many documents share the one channel.
+- **A reusable group reads many docs** (a team, a board, a project): route to one channel the _collaboration_ owns — `return { channels: [doc.channelId] }` — and grant membership once via a meta or invite doc. Many documents share the one channel. That channel's name is computed from the record the collaboration lives on — `board:${doc._id}` on the object itself and `board:${doc.boardId}` on its children — and the branch that creates the object grants its creator that channel in the same `return`, so the person who makes a thing is already inside it and their very first write lands. An invite doc for that collaboration grants the picked handle that same computed channel, so being let into one object is being let into that one object, and the next group to open the app gets a room of its own.
 - **Only the author reads it** (private notes, a user's own uploads): route to one channel the _user_ owns. `const mine = \`user:${user.userHandle}\`; return { channels: [mine], grant: { users: { [user.userHandle]: [mine] } } };` — all of that user's private documents live in this single channel.
 - **A document goes to a one-off set with no reusable group:** route to several channels at once — `return { channels: [\`user:${aHandle}\`, \`user:${bHandle}\`] }`. Mint a per-document channel (`channels: [doc._id]`) only when each document genuinely has its own disjoint audience.
 - **Refusing a write:** `throw { forbidden: "reason" }`. Every document you store is routed to at least one channel so it can be read back.
@@ -370,7 +373,7 @@ export function habits(doc, oldDoc, user, ctx) {
 
 The leaderboard is just the access model: read the public `track:` channels and sum them; each viewer additionally sees their own streaks and any buddy who granted them in. A habit tracker whose owner **asked to keep it to themselves** is instead the per-visitor shape shown above: every visitor's habits and check-ins on their single `user:${user.userHandle}` channel, self-granted and private to them.
 
-**Per-object collaboration is the resting shape of almost every app** (the second worked example above), and certainly of anything that says "invite", "join", "people can join", "collaborate", "share with", "together", "with my partner/team", or names a board/canvas/room/whiteboard a group co-edits — each shared thing is ONE object its members reach directly; it needs no owner. Use the per-object recipe: a channel per object (`board:<id>`/`list:<id>`); the creator self-grants at creation (`grant: { users: { [user.userHandle]: [ch] } }`); child docs gate on `ctx.requireAccess(ch)` so any member edits any child in it (not just their own); a member-authored `share` doc grants a peer the same channel; a `request` doc — which takes **no** `requireAccess` — lets a not-yet-member ask to join. Keep the _object's own_ creator field write-once (`if (oldDoc && doc.author !== oldDoc.author) throw`) and a child's object-id immutable. **Two traps to avoid:** don't build it as an open public feed where each person only owns their own items (that abandons the shared membership), and don't gate it behind a single writer (members self-serve via share/request). The app owner is not special in the data model: any signed-in person creates their own object and invites a friend into it, and the rule keys on `user.userHandle` or the object's creator, never on `user.isOwner`.
+**Per-object collaboration is the resting shape of almost every app** (the second worked example above), and certainly of anything that says "invite", "join", "people can join", "collaborate", "share with", "together", "with my partner/team", or names a board/canvas/room/whiteboard a group co-edits — each shared thing is ONE object its members reach directly; it needs no owner. Use the per-object recipe: a channel per object, named from the record (`board:${doc._id}` on the object, `board:${doc.boardId}` on its children); the creator self-grants at creation (`grant: { users: { [user.userHandle]: [ch] } }`); child docs gate on `ctx.requireAccess(ch)` so any member edits any child in it (not just their own); a member-authored `share` doc grants a peer the same channel; a `request` doc — which takes **no** `requireAccess` — lets a not-yet-member ask to join. Keep the _object's own_ creator field write-once (`if (oldDoc && doc.author !== oldDoc.author) throw`) and a child's object-id immutable. **Two traps to avoid:** don't build it as an open public feed where each person only owns their own items (that abandons the shared membership), and don't gate it behind a single writer (members self-serve via share/request). The app owner is not special in the data model: any signed-in person creates their own object and invites a friend into it, and the rule keys on `user.userHandle` or the object's creator, never on `user.isOwner`.
 
 **Ownership is just the object graph** — whoever authored or created a doc owns it (`doc.authorHandle === user.userHandle`, checked against `oldDoc` on updates). There's no broadcaster shape to reach for by default, and **owner-only publishing is a dead end** — never gate the content itself on `requireRole("owner")`. **A blog, magazine, or publication is public read + author-owned posts, with the owner controlling the _author roster_:** the owner approves authors with a grant doc (`if (doc.type === "author") { ctx.requireRole("owner"); return { channels: ["blog:authors"], grant: { users: { [doc.authorHandle]: ["blog:authors"] }, roles: { owner: ["blog:authors"] } } }; }` — the **one** place `requireRole("owner")` belongs, gating who may author, never the posts); a post then gates on `ctx.requireAccess("blog:authors")` (membership) and is author-owned (`doc.authorHandle === user.userHandle` + the `oldDoc` check), so once approved each author's post is _their own_ object — only they edit it, and they moderate the comments on it (a comment is allowed if it's your comment **or** you own the post: `doc.authorHandle === user.userHandle || doc.postAuthorHandle === user.userHandle`). A personal blog is just this with a roster of one. Always gate write UI on `useVibe(dbName).can`.
 

package/llms/callai.initial.md

@@ -1,6 +1,6 @@
 # CallAI Helper Function
 
-The `callAI` function asks an AI model and returns a string. With a `schema` the string is structured JSON you `JSON.parse()`; without one it is ordinary text — a chat reply, a caption, a paragraph — used as is. Reach for a schema when the app needs fields, and leave it out when it needs prose.
+The `callAI` function asks an AI model and returns a string. Every call carries a `schema`, and the string that comes back is JSON you `JSON.parse()`. When the app needs prose — a chat reply, a caption, a paragraph — the schema is a single string field and that field holds the prose: `schema: { properties: { reply: { type: "string" } } }`, read back as `JSON.parse(response).reply`.
 
 ## Basic Usage
 

package/llms/callai.md

@@ -1,6 +1,6 @@
 # CallAI Helper Function
 
-The `callAI` function returns structured JSON from an AI model. It always requires a schema and returns a string that you `JSON.parse()`.
+The `callAI` function asks an AI model and returns a string. Every call carries a `schema`, and the string that comes back is JSON you `JSON.parse()`. When the app needs prose — a chat reply, a caption, a paragraph — the schema is a single string field and that field holds the prose: `schema: { properties: { reply: { type: "string" } } }`, read back as `JSON.parse(response).reply`.
 
 ## Basic Usage
 

package/llms/use-viewer.initial.md

@@ -90,8 +90,10 @@ App.jsx
             <button type="submit">Post</button>
           </form>
         ) : (
-          // Your own words, informed by v.reason — never the token itself.
-          <p>Sign in to add a comment.</p>
+          // Your own words, informed by v.reason. A signed-in viewer who is denied is
+          // outside this thread's membership, so the sentence says that; the sign-in
+          // ask is for the anonymous viewer.
+          <p>{me?.userHandle ? "Comments here are for members of this thread." : "Sign in to add a comment."}</p>
         );
       })()}
 >>>>>>> REPLACE
@@ -143,8 +145,10 @@ import { useViewer, useVibe } from "use-vibes";
             <button type="submit">Post</button>
           </form>
         ) : (
-          // Your own words, informed by v.reason — never the token itself.
-          <p>Sign in to add a comment.</p>
+          // Your own words, informed by v.reason. A signed-in viewer who is denied is
+          // outside this thread's membership, so the sentence says that; the sign-in
+          // ask is for the anonymous viewer.
+          <p>{me?.userHandle ? "Comments here are for members of this thread." : "Sign in to add a comment."}</p>
         );
       })()}
 =======
@@ -167,8 +171,10 @@ import { useViewer, useVibe } from "use-vibes";
             <button type="submit">Post</button>
           </form>
         ) : (
-          // Your own words, informed by v.reason — never the token itself.
-          <p>Sign in to add a comment.</p>
+          // Your own words, informed by v.reason. A signed-in viewer who is denied is
+          // outside this thread's membership, so the sentence says that; the sign-in
+          // ask is for the anonymous viewer.
+          <p>{me?.userHandle ? "Comments here are for members of this thread." : "Sign in to add a comment."}</p>
         );
       })()}
 >>>>>>> REPLACE

package/llms/use-viewer.md

@@ -49,7 +49,7 @@ export default function App() {
 
 ## Gating UI
 
-Gate the comment form on `useVibe("comments").can` — not on `viewer`. The current viewer never needs a pill here (that's in the Vibes Switch); just render the gated form and its `reason` when denied:
+Gate the comment form on `useVibe("comments").can` — not on `viewer`. The current viewer never needs a pill here (that's in the Vibes Switch); just render the gated form, and on a denial a sentence in your app's own words — `reason` is a machine token that informs that sentence and is never printed:
 
 App.jsx
 
@@ -91,7 +91,10 @@ App.jsx
             <button type="submit">Post</button>
           </form>
         ) : (
-          <p>{v.reason}</p>
+          // Your own words, informed by v.reason. A signed-in viewer who is denied is
+          // outside this thread's membership, so the sentence says that; the sign-in
+          // ask is for the anonymous viewer.
+          <p>{me?.userHandle ? "Comments here are for members of this thread." : "Sign in to add a comment."}</p>
         );
       })()}
 >>>>>>> REPLACE
@@ -137,7 +140,10 @@ import { useViewer, useVibe } from "use-vibes";
             <button type="submit">Post</button>
           </form>
         ) : (
-          <p>{v.reason}</p>
+          // Your own words, informed by v.reason. A signed-in viewer who is denied is
+          // outside this thread's membership, so the sentence says that; the sign-in
+          // ask is for the anonymous viewer.
+          <p>{me?.userHandle ? "Comments here are for members of this thread." : "Sign in to add a comment."}</p>
         );
       })()}
 =======
@@ -160,7 +166,10 @@ import { useViewer, useVibe } from "use-vibes";
             <button type="submit">Post</button>
           </form>
         ) : (
-          <p>{v.reason}</p>
+          // Your own words, informed by v.reason. A signed-in viewer who is denied is
+          // outside this thread's membership, so the sentence says that; the sign-in
+          // ask is for the anonymous viewer.
+          <p>{me?.userHandle ? "Comments here are for members of this thread." : "Sign in to add a comment."}</p>
         );
       })()}
 >>>>>>> REPLACE

package/package.json

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

package/system-prompt.md

@@ -91,7 +91,7 @@ The sandbox serves raw ES modules, so `App.jsx` can import local `.js`/`.jsx` fi
 - **Load Google Fonts with `&display=swap` (or `&display=optional`), never `&display=block`.** Append it to the Fonts URL so text paints immediately in a fallback instead of staying invisible for seconds on slow connections (flash of invisible text) — e.g. `https://fonts.googleapis.com/css2?family=Inter:wght@400;700&display=swap`.
 - **The bottom-right corner belongs to the platform — never pin your own control there.** The Vibes Switch (the logo) floats over every app in that corner, so a `fixed` element anchored to both `bottom` and `right` lands underneath it: no floating add/compose button, no chat bubble, no scroll-to-top disc in that spot. Anchor a floating action bottom-left or bottom-center instead, or fold it into the layout — a header button, or a full-width sticky bar (the platform already reserves scroll clearance below your app for one).
 
-**If the app needs an `access.js`** — privacy, sharing, teams, roles, or approval — the access skill doc (included on permission-shaped turns) carries the emit format, placement, and worked examples; emit `access.js` before any `App.jsx` edit that writes a doc type it gates. Gate every write surface on `useVibe(dbName).can` regardless of whether the app has an `access.js`.
+**Every app gets an `access.js`** unless the person asked for none in their own words, and the access skill doc carries the emit format, placement, and worked examples whenever a turn writes one. When the instruction is the platform's second pass over an app drafted without one, that is a whole-app upgrade applied in full: read `App.jsx` for the records it already writes, emit the complete `access.js` first, then the `App.jsx` edits it needs — the invite screen, the `can` gates, the object id on every child. On any turn, emit `access.js` before any `App.jsx` edit that writes a doc type it gates. Gate every write surface on `useVibe(dbName).can` regardless of whether the app has an `access.js` yet.
 
 **Keep `access.js` in step with the data model.** The app's current `access.js` and `seed.json` are always in view (the `APP_STATE` block). When an edit adds a new written doc `type` — or a field the rules key on — update `access.js` in the same reply so the new writes are allowed; an existing terminal branch that rejects unknown types will reject them at runtime.
 
@@ -302,9 +302,9 @@ Below is a tiny worked example showing the format end-to-end. Description → sc
 
 Note how each edit is preceded by exactly one prose line, the visible structure (input + button) lands before the data wiring (`useDocument` / state), and each SEARCH block is the smallest unique snippet that targets the change.
 
-### access.js output format (when needed)
+### access.js output format
 
-When the app needs channel-based read isolation or per-document write validation, the **access skill doc** (included on permission-shaped turns) carries the full teaching: emit format and placement (one prose line, `access.js`, then one complete fenced block — for a fresh app right after the shell, on a follow-up turn **before** any `App.jsx` edit that writes a doc type it gates), the new-doc-type-first ordering rule, and the worked examples. Never put access function code inside an `App.jsx` block — the filename line (`access.js` vs `App.jsx`) is how the system knows which file to write.
+When a turn writes `access.js`, the **access skill doc** carries the full teaching: emit format and placement (one prose line, `access.js`, then one complete fenced block — for a fresh app right after the shell, on a follow-up turn **before** any `App.jsx` edit that writes a doc type it gates), the new-doc-type-first ordering rule, and the worked examples. Never put access function code inside an `App.jsx` block — the filename line (`access.js` vs `App.jsx`) is how the system knows which file to write.
 
 ## Your starter scaffold
 
@@ -364,7 +364,7 @@ export default function App() {
 
 Don't put a current-user `<ViewerTag />` or login button in the header — the logo's Vibes Switch already shows who's signed in and offers sign-in. Reach for `useViewer` (`const { ViewerTag } = useViewer();`) only where you render **other** users (`<ViewerTag userHandle={...} />`) — either in that feature component, or hoisted to `App` and passed down as a prop. Add `useVibe(dbName)` in the components that gate writes — `can`/`ready` are read where the write surface lives, not hoisted to `App`.
 
-**If the app needs an `access.js`** — privacy, sharing, teams, roles, or approval — the access skill doc (included on permission-shaped turns) carries the permission-model design, worked examples, and the emit format. Emit it right after the scaffold, before any feature edits, and emit the follow-up `access.js` block with any new doc type's branch **before** the edits that write it. Gate every write surface on `useVibe(dbName).can` — the liveness gate is universal even when the app has no `access.js`.
+**When this turn writes `access.js`**, the access skill doc carries the permission-model design, worked examples, and the emit format. Emit it right after the scaffold, before any feature edits, and emit the follow-up `access.js` block with any new doc type's branch **before** the edits that write it. Gate every write surface on `useVibe(dbName).can` — the liveness gate is universal even when the app has no `access.js`.
 ## Social: followers see your stuff (platform graph)
 
 The follow graph lives in the PLATFORM (Settings → Social) — never store friend/follow