ZvessaHQ
HQ is where the people who run a space see and change everything. It is a normal page (id hq) made only of general blocks, so the AI can rearrange it like any other page. It looks and moves like chat-app's futuristic HQ: a frosted header with the space's mark, a bottom tab bar with a lit edge, "Needs you" cards, a big glass widget and an app grid.
Code: convex/lib/hqshell/ (descriptions, the Apps list, the HQ page), src/kits/hqshell/ (screens), tests/hqshell.test.ts.
The tabs #
| Tab | What it holds |
|---|---|
| Overview | Connect your AI (until a key is in), Needs you, changes waiting, reports, the 7-day overview, and anything a template adds (Business: quick actions, a chart, leaderboards) |
| Apps | apps: everything the space has, as a phone's home screen |
| People | rows for Members, Invite people and Who can come in; each opens its own screen |
| Settings | three short groups of rows; each row opens its own screen |
Settings rows: Space (Look, Navigation, Pages, Starters), AI and connections (AI key, MCP servers and APIs, Access tokens, Library), Safety and versions (Safety, History, Blueprint). hq.connections takes part (ai, servers, tokens) so each row shows one short screen.
The header has a back chevron on the left ("Back" spelled out on wide screens). The card on top of Apps shows what needs you and how many apps are on.
The blocks #
| Kind | What it is |
|---|---|
tabbar | A page's own bottom tab bar; children are tab blocks; only the open tab is drawn. Alone on a page it is the whole screen (header + bar). Inside another page, or where the app already has a tab bar, the tabs sit in a row on top. Up to 5. |
tab | One tab: label, icon, title (header title), count (a live number on the icon: needs, proposals, reports, requests, unread). |
apps | Everything the space has, built from the blueprint each time, in at most four sections: Apps, Chats, Connections, More. Props: title, groups, look (grid or list), add, widget. |
hq.status | Needs you: changes to approve, reports to review, people asking to join. |
hq.kit | One added kit: what it is, what it added, Remove. |
Rows that open their own screen are the Layout blocks' item (or section with open: true) holding child blocks; the page route shows them at /p/<page>?part=<block id>.
Nothing turned on is hidden #
appSections() in convex/lib/hqshell/apps.ts reads the blueprint, so a kit, a mini-app, a connection or a chat shows up in Apps the moment it is added:
- Apps: the space's pages, its mini-apps, then what each kit added, in the Library's order. A mini-app with no page runs in a sheet.
- Chats: the AI chat and every conversation stream.
- Connections (managers): every MCP server and API; a tap opens MCP servers and APIs.
- More (managers): kits that work in the background (a bot, a rule, a setting) with a card saying what they do, bots, and the space's own data.
Every entry has an icon: the page's or mini-app's own, else a house for home (as in the chat list), else its kit's (KIT_ICONS, a test checks every kit has one), else its Library group's. Section names are words: apps.apps, apps.chats, apps.connections, apps.more.
Members only see what their blueprint holds (blueprintFor), so never connections, bots or HQ.
Looks #
Everything reads the style. In glowing styles (Futuristic, Tech) HQ gets chat-app's touches: the style's mono face for numbers and small labels, a lit edge on the header and tab bar, glass cards that hide the grid, glossy dark app icons with an accent sheen, and a glowing pill over the open tab (src/kits/hqshell/look.ts). Classic stays clean with soft tinted icons. When the Tech style adds type.mono, surface.edge and surface.glow, HQ reads them first.
Old spaces #
upgradeHq() runs inside upgradeBlueprint: a space whose HQ is the old flat list of system blocks gets the new HQ, and any block it added itself (a chart, tiles) moves to the end of Overview. An HQ from the first tab-bar version gets People and "AI and connections" as rows (only HQ's own blocks are swapped; anything added there stays). Any other HQ with a tab bar, or one rebuilt by hand, is left alone.