Zvessa docs

Templates and kits people make

Any space can be saved as a template (the whole space: pages, tabs, look, words, and everything they use) and any pages as a kit (those pages plus the collections, conversations, feeds, books, games, mini-apps, styles, connections, roles and ledger entries they point at). Both are a piece: plain blueprint data, so whatever is added becomes the owner's to change by hand, by chat or over MCP.

Code: convex/kits/sharing/ (piece.ts pure logic, library.ts server, tools.ts + run.ts AI/MCP tools, kits.ts blocks and kit, model.ts names and blueprint.fromLibrary check), src/kits/sharing/ (blocks), tests/sharing.test.ts.

Flow #

  1. Save (a person in the app, or the AI with save_template): makes the piece, takes private things out, checks it would make a valid space, and keeps it private to its author. The author can add a private one to any space they manage.
  2. Publish (only a person's tap, publish): the version waits for a Zvessa admin.
  3. Admin review (share.review block): accept, reject with a reason, take down, restore, reports.
  4. Add (share.library block, or add_template as a proposal a person approves):
    • mode: "add" puts its pages and parts next to what is there. Ids that clash get new ones (shop → shop-2) and every reference in the piece follows (collection, #page, level:vip, records.add:orders…). Identical parts and the space's own roles, units, levels and badges are reused. Built-in kits it uses are added first. Pages that were tabs become tabs.
    • mode: "switch" (templates): also its tabs, look, words, chat settings and org kinds; nothing is removed; a kids template makes the space a private kids space.
    • One saved version either way, so it can be undone from History.
  5. Take out (share.mine block, remove_template): removes what an "add" added (records stay), using blueprint.fromLibrary.

What is taken out before saving #

Keys and tokens (sk-, ghp_, xox, AKIA, JWTs, private keys, long random strings), emails and phone numbers (replaced with you@example.com / 555-0100), links with a sign-in or a key/signature in the query, links to this deployment's uploads (Convex storage, R2) and private networks, outside-feed accounts (feeds[].sources), photos in books, connection headers. Connections keep their auth (just a vault key name: whoever adds it saves their own key). A block that can't work without what was removed (a picture whose link was private) is left out. The person sees the full list before saving, and admins see it while reviewing. Mini-apps from the mini-app library travel as a reference and are added from that library again (if still listed). Identity, access and members never travel.

Ratings and kids #

A piece can't be rated younger than its mini-apps. Kids spaces only see and add pieces rated for everyone, and anything saved from a kids space is rated for everyone.

AI and MCP tools #

search_templates (with mine), view_template (with source), add_template, remove_template, save_template (with preview). No tool publishes. The open server POST /mcp/library also offers search_templates and view_template with no account.