`majordomus ui` is the primary surface, and the Cockpit is the technical layer beneath it

135. majordomus ui is the primary surface, and the Cockpit is the technical layer beneath it

Context

Two kinds of reader use the browser surfaces of this repository.

• One asks how delivery stands. What is in the pull-request queue and why, which milestones are blocked, which release is live, which workers are on the mesh, what evidence holds and what the documentation says. This is the high-level question, asked in the project's own vocabulary by people who are not reading the registry.
• The other asks what the registry is. Which capabilities, objects, graphs, routes and schemas exist, and how each is projected. The Cockpit answers that today, as the registry rendered (ADR 0012): it is the low-level, technical surface.

The owner's briefs are kept verbatim under campaigns/ (the unified real-data pack campaigns/majordomus-ui-unified-real-data-v2-20261011/ and its successor campaigns/majordomus-ui-complete-opus-fable-v3-20261011/). The earlier owner packs (ui-implementation v1.1, ui-ux-dx) named the first surface majordomus ui, the primary human-facing control plane. The prompt of I2231 said that the choice between "the Cockpit adapted" and "a separate surface" must be recorded rather than made in a launcher. The owner's unified real-data pack of 2026-10-11 brings eleven screen concepts for it (dashboard, PR drain, issues and pull requests, roadmap overview and detail, mesh, CI/CD, capabilities, evidence, documentation). On the same day the owner settled the choice in plain words: "it is majordomus ui primary, not cockpit (low level)".

Decision

• majordomus ui is a surface of its own, and the primary one. It has its own mount on the shared server, its own shell and its own navigation, written in delivery vocabulary (Dashboard, Issues & PRs, PR Drain, Roadmap, Mesh, CI/CD, Capabilities, Evidence, Documentation). It is where majordomus ui and the server's home page send a person first.

• The Cockpit stays the technical layer. It keeps its areas and routes and is not restyled into the high-level screens. A panel of the UI links down into it as the diagnostic view of its source (the capability, object or graph it read), and the Cockpit links up to the UI. Neither copies the other's pages.

• One server, one model, no second application. The UI is served by the same shared server and composes the same capabilities through the same executor (ADR 0004, ADR 0012). It has no datastore, no status vocabulary of its own and no JavaScript that decides a domain fact. ADR 0088's rule holds for every panel:

  • It names the capability, input and pointer it read.
  • A source that cannot answer makes the panel unknown, never empty or green.
  • A fact without a producer reads "Not measured" and names the issue that would produce it.

• Shared mechanics, separate surfaces. The UI reuses the mechanics the Cockpit already proved:

  • the server-side element builder and the generated design tokens;
  • the hash-pinned CSP and the immutable fingerprinted assets;
  • the vendored libraries, loaded lazily per screen (Cytoscape for relations, ECharts for measured series once vendored, Alpine for small interactions, p5 only for a justified decorative motif and never as status evidence);
  • the route-derived probe and the UI audit (ADR 0022), which discover the UI's pages the way they discover the Cockpit's.

  Shared code moves to a module both surfaces import. It is not duplicated.

• First paint is bounded. A screen renders its shell and its cheap panels at once. A panel whose source is slow arrives as a server-rendered fragment of its own route, so with JavaScript off the page still links to every panel. Sources are asked concurrently (I2460 is the first instance).

• majordomus ui the command ensures the shared server and opens the UI's dashboard (I2231). It adds no server and no mode.

Consequences

• I2231 (planned in PR #863, chore/the-owner-packs-are-planned) says majordomus ui "opens this checkout's Cockpit". Its title, objective, desired state and acceptance change to "opens the UI's dashboard". ui status and ui stop stay serve status and serve stop under another name, and there is still no second server.
• The high-level screens are new routes and a new navigation under the UI's mount. The Cockpit's area list, pages and their tests are not reshaped to host them.
• The UI's shell must work from the first screen at every declared width. The mobile navigation work of #858 is reused where its mechanics are generic, not by making the UI a Cockpit section.
• docs/COCKPIT.md describes the technical layer. A new docs/UI.md section, or its own document, describes the primary surface. The site and the server's home page present the UI first.

Status

Proposed by session d3 on 2026-10-11 on the owner's words. Accepted by the owner on 2026-10-12, asked in session p12 after the UI had landed with v0.21.0 (#940, #948, #952, #955, #957-#963): "Yes, accept both" — this decision and the ui feature as stable.

I2231 lived only on the closed PR #863 and never reached master. The majordomus ui command that the first consequence describes is planned as I2484 instead.