HQ

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	members, invite, and a row to "Who can come in"
Settings	three short groups of rows; each row opens its own screen

Settings rows: Space (Look, Navigation, Pages, Starters), AI and connections (AI, Connections, Library), Safety and versions (Safety, History, Blueprint).

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 Connections.
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 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 that already has a tab bar, or was rebuilt by hand, is left alone.