c131 plan: Native App V1 (draft, before kick-off)

Gate: c130 G1 (D1–D10 ruled 2026-11-09; shape.md to accept) plus the repo (created 2026-11-09 at ../qnative, provisional directory name) and the name (c0 there). Phase 0 may run now beside the primer (Mark, 2026-11-09). Reader: the executor who builds the app, then the engineers who receive it. Read c130's research/ and shape.md first once they exist; this plan assumes them. Outcome assumed: B (we build V1; c130 D3). If G2 rules A, this plan is rewritten as "attach at the UI layer" and Phases 1–3 become a patterns-and-fixtures hand-off only.

Why

The sensor can't carry the web dashboard (c130 Why). A native app on the endpoint shows what qcontrol found and how it is doing, without a browser or a bundled web stack. Tyler wants the first shippable release to be this app plus the tray. Mark wants our V1 built first: a simple port of the pages we already have, every page running on synthetic data and ready for real data, the patterns shown by implementing them.

What exists to port

• Pages in ../../../qcontrol/crates/qdash/ui/app/pages: inventory/ (agents, harnesses, mcp-servers, models, providers, skills, tools, workspaces), live.vue, activity/, overview/, organization/ (endpoints, teams, users), integrations/, policies/, findings.vue, settings.vue. The native app takes the one-machine slice of these.
• The data-interface bible (ui/docs/data-interface.md): Transport (http(), local()), R13 types written from the backend handler, R15 primitives know transport not resources, R23 every number served / derived / staged, R25 staged state swaps transports in one line, R31 honest states (c108). These become Rust traits and rules.
• The API (../../../qcontrol/crates/qdash/src/web.rs): 38 /api/* routes, among them inventory, harnesses, mcp-servers, skills, tools, sessions, workspaces, models, providers, stats, performance, events/stream. SQLite behind it (db.rs).
• The tray (../../../qcontrol/crates/qtray): tray.rs, menu.rs, model.rs, dashboard.rs; tray-icon + tao + AppKit; links qevents, qconfig, qtap. A passive viewer with click-to-tap. macOS only.
• Fixture worlds: the Meridian seed (scripts/qdash-seed/generate.py) and c113's baked demo worlds (R2 bucket qdash-demo-worlds). One of these becomes the synthetic store.
• Self-update: ../../../qcontrol/crates/qupdate.
• The framework: GPUI Kit 0.9.1 (gpui-kit = "0.9.1"): application(), init(cx), open_window → Root; gpui-component's tables, lists, dock panels, charts; semantic theme tokens; headless tests (gpui_kit::test); AccessKit. Facts in c130 plan.md §Facts.

The shape (from c130, to be confirmed by shape.md)

┌ tray ─────────────┐        ┌ app window ──────────────────────────────────────┐
│ ● qcontrol on      │        │ Status  Inventory  Events  Config  Connect        │
│   connected: HQ    │  open  │ ─────────────────────────────────────────────────│
│   3 harnesses      │ ─────▶ │ page                                              │
│   taps ▸           │        │                                                   │
│   Open app…        │        │ footer: data: synthetic · local file · v0.1.0     │
└───────────────────┘        └──────────────────────────────────────────────────┘

Two states: local (reads the file system and SQLite; Config is editable) and connected (reads the control plane; Config is read-only; the app says "You're connected to HQ. The configuration is managed there. Here is what was found on this machine.").

Rules

• R1. Every number is served, derived or synthetic; synthetic flows through the real pipes. No view fabricates a value. The footer states the source (c108's honesty, bible R23).
• R2. Views know nothing about the source. A page asks a repository for Harnesses; the repository asks the DataNozzle; the nozzle picks the transport among three sources, synthetic, local and plane (ruled 2026-11-09). One switch for the whole process, never a per-page flag. Amended 2026-11-11 (c138 ruling 3): on the app's Sensor page the switch has two positions, synthetic or the sensor (this machine or an address); the plane is a connection, not a data choice, and the plane transport stays in the code. In developer mode the switch can be changed while the app runs.
• R3. One type per served shape, written from the backend handler, in a types crate the app, the tray and (later) the control-plane client share. The TypeScript types/api/* are the existing contract; a check compares the two until one generates the other.
• R4. Read-only when connected. Edits exist only in the local state, behind one guard.
• R5. Honest states. Loading, empty, error and "not on this machine" are drawn, never a blank. Carried from c108.
• R6. The demo is the test. Every page has a story per state (empty, minimal, typical, overflow, error) and a headless test that renders it. The stories crate is the app's design site.
• R7. The budget is measured. RSS idle, CPU idle, startup and binary size recorded per release against the numbers Tyler sets (c130 Q8), with strobe (anomalyco/strobe: an agent-native CLI and MCP server that measures any process on three OSes; Mark, 2026-11-09), so an agent can reproduce the figures.
• R8. Native before custom. A kit component before a drawn one; a drawn one only when the kit has nothing and the data would otherwise be shown wrong. Amended 2026-11-11 (D18): the kit for the shell; in the content area our layer is drawn on GPUI with our tokens, as c2's scorecard showed it had to be.

Decisions (defaults, for Mark at kick-off; Q-items for Tyler at G2)

Phases

0. Spike (may start during c130 Phase 1, on Mark's word)

A hello app that answers the platform questions before anything is promised.

• gpui-kit = "0.9.1", one window, a sidebar and a data table bound to a JSON inventory.
• A tray icon beside GPUI's event loop (macOS first), with a menu that opens the window.
• Measured with strobe: RSS idle, CPU idle, startup, binary size, on Mark's Mac; the numbers written into research/platform.md and the repo's README.
• A plane transport stub against a fixture plane (a tiny local server over the same JSON world), so all three sources exist from the first commit.
• Windows and Linux builds attempted in CI (GitHub Actions), results recorded even when they fail.
• Written back to c130 research/platform.md.

1. Skeleton

• The workspace (D1); the types crate written from web.rs handlers (R3) with the TS comparison check.
• nozzle: the DataNozzle trait, Synthetic (bundled world, D4), Local (qdash socket, D5) and Plane (base URL plus credential, D5, D13) transports, the switch (D3), repositories per resource with the same return protocol (bible R25).
• messages: c137's bones (the schema in types), the inbox store, the OS notification plumbing and the per-type controls (D8).
• The shell: sidebar, title, status footer (source, state, version), theme tokens (c132's bridge when it exists; the kit's defaults until then).
• stories: the harness that renders a page in a state, as a headless test (R6).

2. Pages, one at a time (review stop after each)

3. The tray

Port qtray's model, menu and click-to-tap into the app (D7), on three OSes; the tray reads the same nozzle.

4. Packaging

Bundles for macOS (signed, notarized), Windows (signed) and Linux (formats per Tyler, c130 Q7); qupdate wired; CI builds and uploads artifacts; the budget recorded (R7).

5. Hand-off (G3)

PATTERNS.md, the fixture world, the stories, CI, a recorded walk, and the pitch deck's demo. Presented to the engineers as option B.

Clarifying questions

1. Name and repo (c130 Q1, Q2). Repo: ../qnative (2026-11-09). Name: c0 there, with Tyler.
2. What the app reads locally: socket API, SQLite, or both (c130 Q3)?
3. Does the tray move into the app, or stay as qtray (D7, c130 Q4)?
4. Budget numbers (c130 Q8) and platform order (c130 Q9).
5. Fonts? Answered 2026-11-09: the brand type for now, Inter, bundled on three OSes (Geist Mono for code, per the brand's typography). Mark wants the decision noted because of all the degrees of expression the brand type gives us. Inter is under the SIL Open Font License, so bundling is allowed; how the kit loads a bundled font is a Phase 0 check.
6. Is Connect in V1 even without the control plane side, as a mocked flow on the synthetic transport?
7. The six endpoint-only shapes (SensorState, Resources, EffectiveConfig, LogLine, ConfigFile, PlaneConnection): new qdash routes typed in TypeScript and generated like the other 38, or hand-written in types for V1? Answered 2026-11-11: qdash routes (D17); synthetic-data.md §The six endpoint-only shapes.

Patterns to consider

• Generate the types from the Rust handlers, then generate the TypeScript from the Rust, so the control plane, the web app and the native app share one contract (bible R13 extended).
• Tray-only mode as the default launch (login item), the window on demand; the budget then applies to the tray.
• Stories as the design site: a stories binary that lists every page state, screenshotted by capture.mts (c132 decides the medium).
• The kit's wasm build for reviewing pages in the lab without a Rust toolchain on the reviewer's machine (verify in c130).
• Deep links (qpoint://connect?…) for the connect flow from the web app.