Templates

A template is a ready-made starting point: a blueprint (pages, kits, roles, a look) that a new space starts from. Like everything else it is data, so after it's applied it's an ordinary space: rename, restyle, add or remove kits, and undo back to before it.

Purposes in onboarding (ready) #

After sign-up, the person picks what the space is for. Each purpose names the space and ticks the kits it suggests; the person can untick any of them, and kits that aren't ready yet are skipped, so new kits show up here as they ship. Code: PURPOSES in convex/lib/onboarding.ts; it's applied by blueprint.onboard as one version, so the first undo point is the finished setup.

Each purpose also sets the AI chat's first hint ("Try: make a services page with prices and a booking form").

Adding a purpose: one entry in PURPOSES with id, label, about, spaceName, kits (kit ids from the Catalog) and welcome. Keep it abstract: a purpose is a set of kits and words, never new code.

Business and Personal starters (ready) #

Full detail: docs/TEMPLATES.md. Onboarding now opens with "How do you want to start?": Business starter, Personal starter, or Build my own (the purposes above). A starter skips the purpose, look and kit steps.

House party games only: no slots or casino games. A kit that isn't ready is skipped.

Business also adds the Reviews kit. Its Services page gets a star line under the header (hidden until the first review) and "What customers say" (a reviews.summary and a reviews.list, 3 at a time) before Support (review boards).

Applying one

Editing in place. Every page has an Edit button for managers that turns the page into its own editor: rename it, move, duplicate or remove parts, tap a header, tile or service to change it, open a part's settings as a sheet (built from its block description, including who sees it), add parts, then Save as one version or Cancel.

The look, part by part. Glossy game tiles with a red LIVE pill on what's on now; quick-play and app tiles as soft icons with a status line ("6 to play", "Vote now"); a services header card with the logo, a small-capitals line and Message us / Book; "This week" banners you swipe sideways; section titles in small capitals over cards. All of it is block props, listed below.

Native on phones. System tab bar (expo-router native tabs) with SF Symbols and Material icons and an unread badge; pages, chats and the AI slide in on a native stack and swipe back; large titles; action sheets and page sheets; haptics from the style's motion.haptics; lists virtualised and kit renderers loaded lazily. The web on a phone gets the same tabs drawn in the style; wide screens get a sidebar.

What it adds to the system (for every space, not only starters):

• Blocks hero, tiles / tile, links / link, chats, calls.recent, hq.overview, hq.starters (Blocks).
• Page.icon: an icon name from src/icons/icons.json, used as the tab icon.
• blueprint.dashboard.panes is the app's pages in order, and blueprint.dashboard.nav picks how they show: "tabs" (default; on phones the first five panes are tabs, the rest top-bar buttons) or "list" (the chat app's way: no tab bar, home is the chat list, panes are rows in it). The owner switches it in HQ → Navigation (hq.navigation), or asks the AI.
• blueprint.talk.screen: a page id. That page is the full-screen chat for every conversation opened; put a conversation block on it (plus anything around it: rules, a pinned card, a poll) to design every chat screen at once.
• Block options: hero look (band or card) and eyebrow; tiles tone (solid, soft, glossy), frame: "card", heading: "label", a tile's note as a status line and badge: "Live" as a LIVE pill; links layout (list, cards, grid, icons, banners), heading, tone and a link tint; chats search (header, field, off), filters, compose, rowsTop and rowsUnder (page ids or ai shown as rows); conversation background (a colour role such as chatBg) and send (text or icon).
• Links (href) also take chat:<conversation key>, ai, mailto: and tel:. A link to a page that doesn't exist is dimmed for managers and hidden for others, so removing a kit never breaks a page.
• Functions kits.templates.templates.apply, .overview({ days }) (HQ numbers, manage) and .recentCalls().

Making another template. Add a TemplateDef in convex/lib/templates/ (shape in types.ts) and list it in TEMPLATES in index.ts. tests/templates.test.ts checks every template makes a valid space, its tabs have icons, its links resolve, every kit can still be removed, switching twice is stable, and it uses only cataloged blocks and props, so the AI can build the same starter, or a new one, from scratch.

Feeds starter (ready) #

A social app (Instagram, Threads, X), built only from general blocks the AI also uses, so anyone can ask the AI for the same thing or any part of it.

• Home: a stories row, a box to post, then For you (every feed, newest first) and Following (people you follow, with Who to follow) in a switcher.
• Explore: search with trending #tags, tiles to Photos, Gallery, From outside and Polls, and a grid of the week's top photos and videos.
• New: composers for Post, Photo and Story (gone in 24 hours) in a switcher, with your own posts as a grid below.
• Activity: Activity (likes, replies, mentions, follows) and Saved.
• Profile: photo, @handle, bio, followers, Edit profile, then Posts, Photos and People.
• Messages: the chat list. HQ: overview, quick actions (Ask the AI, New post, Pull in feeds, Gallery), analytics, people, invite, access, pages, starters, library, styles, history.
• Everything inside a post (replies and threads, reactions, reposts, quotes, edit, saves, full-screen media) comes with the feed blocks. Taking out a kit, say Stories, takes its blocks off these pages too.

Journal starter (ready) #

A private journal (id journal) in the Paper style: cream paper and ink, serif headings, sunrise accents and a night-blue dark mode, with tint1 to tint4 as the moods. Every journal page is visibleTo: ["owner"], so entries stay private on the server too. Code: convex/lib/templates/journal.ts; built from the Journal kit and the record views.

HQ and the AI are in the top bar. The Journal kit on its own (group Plan) adds the journal collection (day, mood, title, entry, tags, prompt) and two owner-only pages: Journal and Mood calendar.

Photo book starter (ready) #

Id photobook, in the Album style: warm paper and ink, serif titles, terracotta and sunflower, with charcoal and amber at night. The tabs are Book (the book that fills itself, then tiles for Add photos, Albums, Guestbook and New book), Photos (the Gallery grid), Albums (the shelf), Chats and Guestbook. HQ and the AI are in the top bar. Its kits are Photo book (with the Gallery), Guestbook, Direct chat, Group chat and Analytics. Code is in convex/lib/templates/photobook.ts, and the books themselves are covered in Blueprint.

Picker covers (showcase) #

A template can carry showcase: { tagline, gradient: [colour, colour], stickers: [emoji…], shots: [{ icon, title, note, tint }] }. The picker (onboarding and HQ → Starters) draws a bright gradient cover with floating emoji, the tagline and a tilted phone showing the shots. They're plain views, with no images to download. The emoji move only on the picked card, only while the app is in front, and only if the person allows motion. Without showcase the picker shows the plain card. checkShowcase keeps it in limits: a 60-character tagline, 6 stickers and 3 shots.

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 plain blueprint data, so whatever is added becomes the owner's to change. Kit templates-library ("Templates and kits", group Build). Code: convex/kits/sharing/. Full detail: docs/SHARING.md.

When ids clash they get new ones (shop becomes 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, and pages that were tabs become tabs. Nothing is removed by a switch; a kids template makes the space a private kids space.

What's taken out before saving:

• Keys and tokens.
• Emails and phone numbers, which are replaced with [email protected] and 555-0100.
• Links that carry a sign-in, key or signature.
• Links to this server's uploads or to private networks.
• Outside-feed accounts, photos in books, and connection headers.

Connections keep only their vault key name, so whoever adds one saves their own key. A block that can't work without what was removed 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. 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.

Not yet: onboarding doesn't offer library templates. Start from a starter, then switch to one.