@vibes.diy/prompts 4.0.11 → 4.0.13

package/README.md

@@ -32,7 +32,7 @@ The whole platform is open source under Apache 2.0. Read the code, open an issue
 ## Quick Start
 
 1. [Try the demo](https://vibes.diy/) — no setup required.
-2. Or hack on the code: clone the repo, `pnpm install`, and `pnpm build` — the build, lint, and test suite work from a fresh clone with no secrets. Running the full web app locally currently requires extra setup; the [Contributing Guide](CONTRIBUTING.md#getting-started) covers exactly what works out of the box and what doesn't yet.
+2. Or hack on the code: clone the repo, `pnpm install`, and `pnpm build` — the build, lint, and test suite work from a fresh clone with no secrets. The full web app runs locally too: `pnpm dev:setup` generates the needed dev environment (no team secrets required); the [Contributing Guide](CONTRIBUTING.md#running-the-web-app-locally) walks the whole path.
 
 ## Community
 

package/llms/backend.md

@@ -32,7 +32,7 @@ the exact gate user writes pass through — acting as the **trigger's identity**
 | ----------- | ----------------------------------------------------------------- |
 | `onChange`  | the user whose write triggered the event                          |
 | `fetch`     | the signed-in caller when verifiable — treat as possibly anonymous |
-| `scheduled` | the app owner                                                     |
+| `scheduled` | the app owner, **in admin mode**                                  |
 
 So the permission model stays in `access.js`, and `backend.js` writes must be
 allowed by it for the acting identity. If a `fetch` handler writes, make sure
@@ -46,6 +46,20 @@ for **derivation and convenience**, never privilege escalation. For documents
 only the server should control, use `scheduled` — it acts as the **owner**, an
 identity `access.js` can genuinely restrict a database to.
 
+`scheduled` always runs in **admin mode**, the same override the owner gets
+from the client's admin toggle: `ctx.requireAccess(...)`/`ctx.requireRole(...)`
+no-op, and its `ctx.db.query` reads are unfiltered. The access function still
+**runs** on every write — its returned channels and grants still route the doc,
+so members keep seeing what the cron writes. `user.isOwner` is `true`, so
+owner-conditional rules apply as the owner. Two consequences worth designing
+around: a scheduled sweep can read and rewrite **every user's** documents in
+the app (access functions protect users from *each other*, not from the app
+owner — the owner's automation touches all users' data); and because admin mode
+skips `requireAccess`, a bug in a scheduled write fails *silently-wrong* rather
+than `forbidden` — keep scheduled writes small and well-guarded. `fetch` and
+`onChange` never get admin mode: they're user-triggerable, and a handler any
+visitor can invoke must not run owner-privileged.
+
 ## ctx — what a handler gets
 
 ```js
@@ -64,19 +78,31 @@ const docs = await ctx.db.query({ db: "notes" }); // latest non-deleted docs (ea
   when the access function denies it).
 - `ctx.db.query({ db })` returns the whole database's latest docs (capped at
   2000) — filter and sort in the handler. It is read-ACL-gated as the acting
-  identity, anonymous `fetch` callers are denied, and databases bound to an
-  access function cannot be queried from the backend (keep backend-read
-  databases on plain ACLs). Made for `scheduled` sweeps: read, decide, then
-  `put`/`delete`.
+  identity and anonymous `fetch` callers are denied. In `scheduled` (admin
+  mode) the read is **unfiltered** — access-fn-bound databases return every
+  doc, across all users and channels. In `fetch`/`onChange`, databases bound
+  to an access function cannot be queried (keep those lanes' read databases on
+  plain ACLs). Made for `scheduled` sweeps: read, decide, then `put`/`delete`.
 - `ctx.secrets` carries the owner's per-vibe secrets, set in the vibe's settings
   page or with `vibes-diy secrets set KEY`. Use it to verify inbound credentials —
-  a webhook's shared secret or token — and never write a value anywhere users can
-  read it (a doc, a response body). Only the owner can set or rotate secrets;
-  handlers see the current values on every invocation.
-- **No outside network access**: `fetch()` to external URLs is refused inside
-  `backend.js`, so secrets cannot be sent anywhere — they can only be compared
-  against or used to verify what arrives. Don't call third-party APIs from the
-  backend; AI calls stay in `App.jsx` via `callAI`.
+  a webhook's shared secret or token — or to authenticate outbound calls
+  (`Authorization: Bearer ${ctx.secrets.KEY}` to an admitted API). Never write a
+  value anywhere users can read it (a doc, a response body). Only the owner can
+  set or rotate secrets; handlers see the current values on every invocation.
+- **Outbound `fetch()` is policy-gated**: `backend.js` can call external https
+  APIs that either (a) are CORS-open — the platform forwards the request exactly
+  as a browser on the app's own page could (same preflight rules, same
+  `Access-Control-Allow-Origin` check, browser-forbidden headers like `Cookie`
+  are stripped) — or (b) are on the platform's curated list (`api.github.com` is
+  seeded; additions are a PR to the platform repo). A denied call returns
+  `403 {"vibesEgressDenied":true,"gate":"floor"|"owner-blocked"|"cors"|"rate-limit","host":...}` —
+  check for it and surface a useful error. Remedies: use a CORS-open endpoint,
+  request a curated-list addition, or ask about owner blessing. Limits: https
+  on port 443 only, 15s per request, 10MB responses, per-vibe rate caps
+  (30/10s, 300/min). Make all outbound calls **before returning** the Response —
+  a `fetch()` fired while a streamed body is still being pulled after the
+  handler returned is unsupported and gets denied. Frontend AI calls stay in
+  `App.jsx` via `callAI`.
 
 ## fetch — the app's HTTP endpoint
 
@@ -142,8 +168,12 @@ export async function scheduled(event, ctx) {
 }
 ```
 
-Runs as the app owner. Use it for cleanup, digests, and time-based state — not
-for anything that needs a user in the loop.
+Runs as the app owner in admin mode (see "Writes go through the access
+function" above): it can read every doc in the app and its writes pass
+`requireAccess`/`requireRole` automatically, while the access function's
+channels and grants still route what it writes. Use it for cleanup, digests,
+rotations, and time-based state — not for anything that needs a user in the
+loop.
 
 ## A complete example — activity feed + owner-only digest
 

package/llms/use-viewer.md

@@ -38,6 +38,7 @@ export default function App() {
 - `isViewerPending` — `true` while the platform is still resolving the viewer identity (e.g. on first render before the parent shell has pushed the identity update). **Gate any auth-dependent UI on `!isViewerPending`** to avoid flashing the wrong state. Once it becomes `false`, `viewer` is either populated or definitively `null`.
 - `can(action)` — membership boolean for `"read"`/`"write"`/`"delete"`: is the viewer through the door? Access functions enforce per-document and per-database rules server-side. Prefer `useVibe(dbName).can.create/edit/delete` for write gating; it runs the app's access function and returns a `reason`.
 - `ViewerTag` — ready-made user pill; see the ViewerTag section below.
+- `HandleInput` — ready-made handle-lookup text input; see the HandleInput section below.
 
 ## Gating UI
 
@@ -209,3 +210,33 @@ Key points:
 **Theming.** `ViewerTag` reads `--accent`, `--accent-text`, `--card-bg`, `--border`, `--text`, and `--muted` from the app's CSS variables with sensible fallbacks. If your app defines these on `:root` (which most generated themes do), `ViewerTag` inherits the theme automatically with no extra props.
 
 Pass `<ViewerTag userHandle={...} />` to render other people. The no-prop `<ViewerTag />` (current user) covers identity and sign-in too, but the logo's Vibes Switch already does that — reach for it only when you specifically want inline avatar self-edit for any signed-in member.
+
+## HandleInput
+
+`HandleInput` is a ready-made **find-a-person input**, returned from `useViewer()` alongside `ViewerTag`. Use it whenever your app needs the viewer to pick another user — assigning a task, adding someone to a roster, sharing with a friend. Never build your own handle autocomplete or ask users to type handles into a bare `<input>`.
+
+```jsx
+const { HandleInput } = useViewer();
+
+// Controlled: store just the handle string on your doc.
+const [assignee, setAssignee] = React.useState(null);
+<HandleInput value={assignee} onChange={setAssignee} placeholder="Assign to…" />;
+```
+
+How it behaves:
+
+- **Typing opens a dropdown of prefix matches.** People the viewer has already interacted with — members of vibes they own or belong to, DM partners — rank at the top; below them come matching handles from the wider user base, GitHub-mention style.
+- **Picking one collapses the input into a ViewerTag** for that handle (avatar + name, resolved automatically), with an × to clear and pick again.
+- **Raw entry always works.** Pressing Enter commits the sanitized typed text even when nothing matched, so users can reference someone brand-new.
+- `onChange` fires with the picked handle string (or `null` on clear). **Persist only the handle** on your docs — render it later with `<ViewerTag userHandle={...} />`, exactly like `authorHandle`.
+- Works uncontrolled too (omit `value`) when you only need the `onChange` events.
+- Theming matches `ViewerTag` — it reads the same CSS variables (`--accent`, `--card-bg`, `--border`, `--text`, `--muted`).
+
+```jsx
+// Typical write pattern: stash the picked handle on a doc.
+async function assign(handle) {
+  if (!handle) return;
+  await database.put({ type: "assignment", taskId: task._id, assigneeHandle: handle, assignedBy: me?.userHandle });
+}
+<HandleInput onChange={assign} placeholder="Add a teammate…" />;
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibes.diy/prompts",
-  "version": "4.0.11",
+  "version": "4.0.13",
   "type": "module",
   "main": "./index.js",
   "description": "",
@@ -24,9 +24,9 @@
   "license": "Apache-2.0",
   "dependencies": {
     "@adviser/cement": "~0.5.34",
-    "@vibes.diy/call-ai-v2": "^4.0.11",
-    "@vibes.diy/identity": "^4.0.11",
-    "@vibes.diy/use-vibes-types": "^4.0.11",
+    "@vibes.diy/call-ai-v2": "^4.0.13",
+    "@vibes.diy/identity": "^4.0.13",
+    "@vibes.diy/use-vibes-types": "^4.0.13",
     "arktype": "~2.2.1",
     "json-schema-faker": "~0.6.2"
   },

package/system-prompt-initial.md

@@ -156,6 +156,8 @@ The leaderboard is just the access model: read the public `track:` channels and
 
 **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.
 
+**The owner must never be locked out of their own app.** On first load there are zero grant docs, so no one — the owner included — holds any membership channel yet; the reserved `owner` role is ALL the owner has, and a members-only gate (`ctx.requireAccess(ch)`) denies the owner exactly like a stranger. Two rules keep the owner in. In `access.js`: when a grant branch is itself owner-gated (`ctx.requireRole("owner")` — the roster/member pattern), it also grants the reserved owner role into the same content channel (`grant: { users: { [doc.memberHandle]: [ch] }, roles: { owner: [ch] } }` — the author-roster example above does this), so approving others never leaves the owner behind. This applies ONLY to owner-managed roster channels: a per-object channel members self-grant and share (`list:<id>`, a private journal, a shared board) needs no owner and must NOT auto-grant one — the app owner gets no special access to users' own spaces. In the UI: route the denied state by capability, not one-size-fits-all — when the core write gate denies (`can.create({ type: "post", ... }).ok` false), also check the app's own grant-doc type — `member` here, but use whatever this access.js names it (`author`, `share`, `approve`): `can.create({ type: "member", userHandle: me?.userHandle }).ok`: a viewer who can grant runs the roster, so show them the manage surface — pending requests with one-tap approve, plus a way to add themselves — never a "request to join" CTA aimed at their own gate. And ship that approve surface in the same build as the request path: a join flow without its approve half strands everyone outside, owner included.
+
 **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.
 
 **Never put access function code inside an `App.jsx` block** — it will overwrite the React component. The filename line (`access.js` vs `App.jsx`) is how the system knows which file to write.
@@ -176,17 +178,15 @@ Use these import statements verbatim at the top of the scaffold's `create` block
 
 ## End every turn with one improvement question
 
-After your code edits, end your response with exactly ONE short improvement question and 2–4 multiple-choice options. (One exception: when the user's previous message was exactly `I'm done for now`, skip the question — see the escape-hatch paragraph below.)
+After your code edits, end your response with exactly ONE short improvement question and 2–4 multiple-choice options.
 
 Each option goes on its own line, prefixed with `▸ ` (the `▸` character — U+25B8 BLACK RIGHT-POINTING SMALL TRIANGLE — followed by a space). The chat UI parses these into clickable buttons. Don't number them. Don't use bullets, dashes, or other list markers.
 
-NEVER put a `▸` option on the same line as the question, the answer narration, or another option. The question ends with its `?` and a newline; the first option begins on the next line. Each subsequent option also starts on a new line. The escape hatch `▸ I'm done for now` is the FINAL option — never first, never inline with the question.
-
-The last option is always the escape hatch: `▸ I'm done for now`.
+NEVER put a `▸` option on the same line as the question, the answer narration, or another option. The question ends with its `?` and a newline; the first option begins on the next line. Each subsequent option also starts on a new line.
 
-When the user's next message is exactly `I'm done for now`, your next turn must skip both the edits and the question — just one or two short acknowledgment lines (e.g., "Sounds good. Ping me when you want to keep iterating."). The loop pauses until the user types something else.
+Every option must be a concrete improvement — do NOT include a dismissive option like "I'm done for now"; the user can simply stop replying or type their own message instead.
 
-When the user picks any other option (or types a custom answer), your next turn:
+When the user picks an option (or types a custom answer), your next turn:
 
 1. Make the change implied by their answer.
 2. End with another improvement question.

package/system-prompt.md

@@ -362,6 +362,8 @@ When the app is a publication — a blog, a magazine, an announcements feed —
 
 **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.
 
+**The owner must never be locked out of their own app.** On first load there are zero grant docs, so no one — the owner included — holds any membership channel yet; the reserved `owner` role is ALL the owner has, and a members-only gate (`ctx.requireAccess(ch)`) denies the owner exactly like a stranger. Two rules keep the owner in. In `access.js`: when a grant branch is itself owner-gated (`ctx.requireRole("owner")` — the roster/member pattern), it also grants the reserved owner role into the same content channel (`grant: { users: { [doc.memberHandle]: [ch] }, roles: { owner: [ch] } }` — the author-roster example above does this), so approving others never leaves the owner behind. This applies ONLY to owner-managed roster channels: a per-object channel members self-grant and share (`list:<id>`, a private journal, a shared board) needs no owner and must NOT auto-grant one — the app owner gets no special access to users' own spaces. In the UI: route the denied state by capability, not one-size-fits-all — when the core write gate denies (`can.create({ type: "post", ... }).ok` false), also check the app's own grant-doc type — `member` here, but use whatever this access.js names it (`author`, `share`, `approve`): `can.create({ type: "member", userHandle: me?.userHandle }).ok`: a viewer who can grant runs the roster, so show them the manage surface — pending requests with one-tap approve, plus a way to add themselves — never a "request to join" CTA aimed at their own gate. And ship that approve surface in the same build as the request path: a join flow without its approve half strands everyone outside, owner included.
+
 **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:
@@ -490,17 +492,15 @@ Example streamed output for a team board app:
 
 ## End every turn with one improvement question
 
-After your code edits, end your response with exactly ONE short improvement question and 2–4 multiple-choice options. (One exception: when the user's previous message was exactly `I'm done for now`, skip the question — see the escape-hatch paragraph below.)
+After your code edits, end your response with exactly ONE short improvement question and 2–4 multiple-choice options.
 
 Each option goes on its own line, prefixed with `▸ ` (the `▸` character — U+25B8 BLACK RIGHT-POINTING SMALL TRIANGLE — followed by a space). The chat UI parses these into clickable buttons. Don't number them. Don't use bullets, dashes, or other list markers.
 
-NEVER put a `▸` option on the same line as the question, the answer narration, or another option. The question ends with its `?` and a newline; the first option begins on the next line. Each subsequent option also starts on a new line. The escape hatch `▸ I'm done for now` is the FINAL option — never first, never inline with the question.
-
-The last option is always the escape hatch: `▸ I'm done for now`.
+NEVER put a `▸` option on the same line as the question, the answer narration, or another option. The question ends with its `?` and a newline; the first option begins on the next line. Each subsequent option also starts on a new line.
 
-When the user's next message is exactly `I'm done for now`, your next turn must skip both the edits and the question — just one or two short acknowledgment lines (e.g., "Sounds good. Ping me when you want to keep iterating."). The loop pauses until the user types something else.
+Every option must be a concrete improvement — do NOT include a dismissive option like "I'm done for now"; the user can simply stop replying or type their own message instead.
 
-When the user picks any other option (or types a custom answer), your next turn:
+When the user picks an option (or types a custom answer), your next turn:
 
 1. Make the change implied by their answer.
 2. End with another improvement question.