# 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 | 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.