Quick start

Get started #

Open the app and sign up. Then build by chat, in HQ, or from your own AI over MCP (Connect).

Sign up and answer a few questions: your name, what the space is for (just me, a business, a team, family, kids, a creator, a community, games, something else), its name, a look (Classic or Futuristic) and the starter kits that purpose suggests, which you can untick. You land on the dashboard: HQ, your Home page and the AI chat. The purposes and their kits are in convex/lib/onboarding.ts; kits that aren't ready yet are skipped. Ready-made starting points are on Templates.

Your first change, three ways #

All three write the same blueprint and all three can be undone in HQ → History.

1. Ask the AI. Type "Make this page a link-in-bio with my Instagram and YouTube". The AI proposes a change; you see its summary and tap Approve. Nothing changes before that.

2. Tap in HQ. HQ → Library → add Boards and tasks. HQ → Style → switch to Futuristic, dark. Each tap is saved as its own version.

3. Call the API. Any signed-in client with the manage permission can send a change:

await convex.mutation(api.blueprint.change, {
  summary: "Add a welcome line",
  ops: [{ op: "add", path: "/pages/1/blocks/0",
          value: { id: "welcome", kind: "text", props: { text: "Welcome!" } } }],
});

The server applies it to a copy, runs every check, and refuses it with a readable message if anything is wrong, so a bad change never reaches the space. See Blueprint.

Which piece do I need? #

Rule of thumb: filled in and placed → block. Needs the server to run rules (data, games, payments) → engine and kit. Custom logic someone writes → mini-app. Outside service → capability.

Recipes #

Each recipe is what you'd ask the AI. The blueprint it ends up with is shown so a developer can write it by hand too.

Link-in-bio #

"Make my Home page a link-in-bio: my name, a short line, buttons for Instagram, YouTube and my shop."

{ "id": "home", "title": "Home", "blocks": [
  { "id": "me", "kind": "heading", "props": { "text": "Ada Park" } },
  { "id": "line", "kind": "text", "props": { "text": "Ceramics and slow mornings." } },
  { "id": "links", "kind": "stack", "props": { "gap": 10 }, "children": [
    { "id": "ig", "kind": "button", "props": { "label": "Instagram", "href": "https://instagram.com/ada" } },
    { "id": "yt", "kind": "button", "props": { "label": "YouTube", "href": "https://youtube.com/@ada" } },
    { "id": "shop", "kind": "button", "props": { "label": "Shop", "href": "#catalog" } }
  ] }
] }

#catalog opens another page of the space (here the Catalog kit's page).

Habit tracker #

"Build a habit tracker: I log a habit and a date, and see how many I've done."

A collection and three blocks:

"collections": [{ "id": "habits", "name": "Habits", "fields": [
  { "id": "habit", "label": "Habit", "type": "choice", "options": ["Run", "Read", "Water"], "required": true },
  { "id": "day", "label": "Day", "type": "date", "required": true },
  { "id": "note", "label": "Note", "type": "text" }
] }]

{ "id": "habits", "title": "Habits", "blocks": [
  { "id": "habits-count", "kind": "records.count", "props": { "collection": "habits", "label": "Done so far" } },
  { "id": "habits-form", "kind": "records.form", "props": { "collection": "habits", "submit": "Log it" } },
  { "id": "habits-board", "kind": "records.list", "props": { "collection": "habits", "groupBy": "habit" } }
] }

Team space with a chat #

"Make this a team space: roles Coach and Player, a team chat only coaches can post in, and an invite link for players."

Roles in /roles, a stream in /streams with mode: "broadcast" and postRoles: ["coach"], a stream block, an invite block with role: "player". Add Teams and hierarchy for squads, each with its own room. See People.

A small game #

"Make a tiny snake game that matches my style."

The AI adds a mini-app to /apps (one HTML document) and a miniapp block that shows it. The game reads colours from CSS variables, so it matches any style. See Mini-apps.

A party game #

"Make a trivia night about 90s music, three rounds, teams, and show it on the TV."

The Trivia night kit adds a game to blueprint.games; the AI writes the questions. People join with a code on their phones; Show on TV puts game.screen on the big screen.

Make a games page #

"Make a games page like a real game app, with trivia, a quiz board and a survey game."

The full detail is in docs/LOBBY.md. The page is built only from lobby blocks: a lobby.header, a showcase of featured games, game.live, a posters shelf of house games, small "Quick play" posters with links, game.winners, game.record, and an optional ledger.leaderboard. In code, gamesLobbyPage({ games, featured?, quick?, leaderboard? }) in convex/lib/lobby/page.ts builds exactly that page from a list of game ids.

{ "id": "lobby-p-trivia", "kind": "poster", "props": { "game": "trivia-night", "art": "trophy", "palette": "sunset", "badge": "HOT" } }

• Every new game gets a poster. When the AI makes a game, it adds a poster for it on the games page.
• The look is props. art is one of 20 scenes (trophy, board, survey, mask, sketch, dice, wheel, bingo…), an emoji or an https picture. palette is one of 12 (sunset, ocean, grape…), or colors takes 2 or 3 of your own colours. Leave both out and the poster picks from what the game does, the same way every time. Words are words["lobby.<key>"].
• A poster for a removed game isn't an error. Members don't see it, and managers see it greyed out.
• lobby.row puts the games page in a chat list as a row with a mosaic of its posters.

A shop #

"Add a catalog of my candles with prices."

The Catalog kit. People can buy levels (memberships, VIP) with the space's own coins today (Coins, Memberships); card payments with Stripe come later.

When something is refused #

Every change is checked. The message says exactly what to fix, for example block "ig": "label" is required or dashboard: no page "shop". The AI reads the same messages and fixes its own proposal, up to four tries.