Kits

Everything beyond the dashboard is an optional kit. A new space has only HQ, its page and the AI chat; people add a kit only if they want it, and taking it out is one tap and can be undone. Kits are settings, never code: each one switches on engines and adds pages, blocks, collections and settings to the blueprint. Code: convex/lib/kits.ts. Overview of the idea: docs/KITS.md.

The full library with each kit's status: Catalog (generated).

What's ready #

Highlights by group (the Catalog has the full, current list and status):

Coming: card payments and tips (Stripe), a bookable service page, events and tickets, moderation, quests, docs and wiki, automations, bots, invites and referrals, public links and auto-post. Ready-made starting points that combine kits are on Templates.

Adding and removing #

Adding a kit is one version. If a kit's collection id already exists in the space (the Journal kit and the Personal starter both use journal), the space keeps it and its records, gets only the missing fields, and keeps it when the kit is taken out. The space remembers what it added in blueprint.kits.<id> (its pages, collections, streams, roles, games, ledger units and levels, audience), so removing takes out exactly that, plus any dashboard pane showing its pages, and any block on the pages that stay that shows one of its feeds, collections or streams (removeKitOps), so a page never points at something that's gone. Records stay, so adding the kit back brings the data back. A kit can't be added twice, and one that waits for an engine can't be added yet.

After adding, everything a kit made is ordinary blueprint: rename it, restyle it, move its blocks, hide it from some roles. A kit never hard-codes a use case: "Support desk" is a space with a queue and assignment; "VIP" is a rank.

Feed recipes #

Ready settings for the kinds of feed people ask for, in convex/kits/social/recipes.ts: threads, photos, stories, clips (short videos), updates (owner-only news), board (members post, managers approve), moments (private family photos), questions (Q&A), forum, links (upvotes and discussion), reviews, guestbook and portfolio. The AI uses one when someone names the kind ("add a clips feed") and changes what they ask. feedRecipeOps(bp, recipe, { name?, id?, page?, tab? }) returns the changes that add the feed and a page for it, with ids that never clash.

Writing a kit #

A kit is one entry in KITS in convex/lib/kits.ts, or in a kit list of its own spread into it (ROUNDS_KITS, LEDGER_KITS, LIVE_KITS, the social kits). Besides collections and pages, a kit can add streams, feeds, roles, games, ledger settings, apps (mini-apps) and connections. The simplest shape:

{
  id: "signups",
  name: "Sign-ups",
  about: "People sign up for something; you see the list.",  // one line people read
  group: "Grow",                                             // a KIT_GROUPS entry
  engines: ["collections"],
  collections: [{ id: "signups-people", name: "People", fields: [
    { id: "name", label: "Name", type: "text", required: true },
    { id: "email", label: "Email", type: "email", required: true },
  ] }],
  pages: [{ id: "signups", title: "Sign-ups", blocks: [
    { id: "signups-form", kind: "records.form", props: { collection: "signups-people", submit: "Sign up" } },
    { id: "signups-list", kind: "records.list", props: { collection: "signups-people", empty: "Be the first." } },
  ] }],
}

Rules:

1. Ids start with the kit's id (signups-…) for pages, blocks, collections, streams and games, so kits never clash with each other or with what people made. The one exception is a piece several kits mean to share: the talk kits all use one chats page with the inbox, and Channels and Teamspace share general and announcements, so a space with both has one of each. A shared piece is added with the first kit that lists it and stays while any of them is in the space.
2. Only blocks, collections and settings. If the kit needs the server to run rules, that's an engine; use one that exists, or add a new engine only when none can express it.
3. Words in props, looks from the style. No colours or fonts. If the kit needs its own colour, name one (gold, felt) and let styles set it.
4. A kit is ready when every engine it uses is ready and it adds something: a page, collection, stream, role, game, feed or ledger settings (kitReady). Until then the Library shows it as coming.
5. Check it: the result must pass checkBlueprint on a fresh space, and removing it must leave the space as it was.
6. Regenerate the catalog: npm run docs.

Planned: kit settings that people change later (a currency name for Coins, quiet hours for Notifications) live in blueprint.kits.<id> next to what it added, checked like any other setting.

Kits people and their AI make #

A kit is data, so the same shape can be saved from a space: "save my party page as a kit" turns those pages and everything they point at into a kit, kept private until a person taps Publish and an admin accepts it. Others then add it next to what they have, and can take it out again (Templates and kits people make). The AI can also put together kits nobody has thought of from the same engines.