Skip to content
SHC Docs

The settings surface: proposal 2026-08-16

Status: open design. The settings surfaces in this note are not built. Owner-reported: “isn’t there supposed to be an app called settings…?” and, the same day, “shouldn’t there be, like, a user profile that when pressed goes to the console”. Companions: 2026-08-14-console-architecture.md, 2026-08-14-portal-architecture.md, ../architecture/flows/launcher.md.

This is a design lane. Nothing here is implemented.

0. What is actually true today (measured, not recalled)

Section titled “0. What is actually true today (measured, not recalled)”
ClaimReality
A settings app existsNo. Not in apps/, not on either estate.
Settings does not exist at allFalse. apps/console/routes/settings.tsx → features/console/src/SettingsScreen.tsx, titled “Settings”, subtitled “Account, access, and this console”. It is a stub, but it is the named home.
The console is deployedNo. apps/console/ has no app.yaml and no compose.yaml (it is daemon-served by ruling, not a container), and docker service ls names no console or settings on bitspur or promanager.
The real launcher shell is builtNo. launchershell.SetBundle has no shc-side caller; every estate materialises ce’s placeholder, so the vanilla bootstrap panel is what renders.
The launcher payload has byte room314 bytes. Measured 24,186 served against menuPayloadByteCeiling = 24500.
The launcher knows name/email/avatarOnly a username. See §3.

Two of those correct the premises this lane was handed, and both change the answer, so they lead.

§12.8 of the launcher doc is stale. Its budget table reads 10,193 / 10,250. The constant has been raised twice since (→ 16250, → 24500 for iPad arrange + folders + per-user layout). The live number:

menu_test.go:1162: scanned 24186 served bytes (ceiling 24500) for comments,
prose, hostnames, dates and em dashes

No settings app. No new deployment. No new endpoint.

  1. The console’s existing /settings route is the settings surface. It is already named, already routed, already the place “Account, access, and this console” belongs. It needs filling in, not inventing.
  2. The launcher panel header gets a profile affordance (a monogram button between the title and the close button) that is a plain link, in a new tab, to the console. Not a menu.
  3. It renders only when the daemon says a console exists. Server-decided, never client-guessed.

This is the owner’s own proposal, and it is right. The reasoning below is mostly about why the alternatives are worse, and about the three details that decide whether it is 300 bytes or 3,000.

(a) “Settings IS the console, it just needs a tile.” Right destination, wrong affordance. A tile in the grid claims the console is an app, but the grid is the tenant-filtered, verdict-gated inventory of things you can open (§12), each tile a deployment the daemon resolved. The console is not a deployment; it is the estate’s own chrome. Putting it in the grid means teaching the dedupe, the environment precedence, the placement axis and the RBAC verdict about a thing none of them describe. The header is where chrome goes, and the header is free.

(c) A UI over shc config. Out of scope for “settings”, and dangerous to conflate with it. A 5-level config editor is its own proposal with its own blast radius; hanging it off a word the owner used to mean “where’s my account” is how the junk drawer starts.

(b) A distinct per-user surface: this is the one worth killing carefully, because it is the plausible one. Its candidate contents evaporate on inspection:

Proposed contentWhy it is not a setting
Launcher arrangementAlready shipped, by direct manipulation. launcher_layout.go persists per-user layout keyed on id.User; menu_arrange.go + launcher_drag.go are drag-to-reorder, drop-to-folder and a dock. The 8,250-byte ceiling raise bought exactly this. You arrange the launcher by dragging it. A screen that edits the same thing as a list is a worse second way to do a solved thing.
ThemeRefused by console ruling 5. Launcher/console parity is “100%”, achieved through shared design tokens and guarded by visual parity checks. A per-user theme axis in the launcher is a parity-breaking knob, not a preference.
My SSO sessionsKeycloak’s account console already exists and already owns session listing and revocation. Reimplementing it is work with a negative return.

With those three removed, surface (b) is empty. That is the argument: it is not that a per-user surface is a bad idea, it is that everything anyone would put in it is already somewhere better.

3. The identity correction: and what it forces

Section titled “3. The identity correction: and what it forces”

The premise handed to this lane was that “name/email/avatar are in hand”. One third of that is true:

  • auth.go stamps menuIdentity{User,Tenant,Stack,Verb} from the daemon verdict headers X-SHC-User / -Tenant / -Stack / -Verb.
  • X-SHC-User is a bare username; the tests pin "root" and "alice". There is no email header, no display-name header, no avatar URL anywhere in the forward-auth contract.
  • launcherAppsResponse carries Version, State, Apps, Glyphs, Arts and no user field at all. The browser does not learn who it is today.

Two consequences, and the second is the important one.

The avatar must be a monogram, and never a fetched image. An avatar URL would be a cross-origin image on a third party’s page, which is precisely the hot-linking §12.8 already rejected for app icons, on four grounds that all still hold (CSP img-src widened as a function of the inventory, airgapped estates render nothing, a 404 is a broken affordance no operator can fix, and outbound HTTP from the plugin is banned). Reopening it for a face is a bad trade.

It is also unnecessary: the monogram machinery is already in the payload. glyph() takes two characters and derives a hue by hashing the label: hsl(h,72%,74%). Pointing the same two lines at the username costs close to nothing and is visually consistent with every tile beside it, by construction.

The header exists and does not need inventing (menu.go, the build() panel): a flex row, gap:12, padding:18 18 14, border-bottom, holding

mark(24) → ttl "Applications" (flex:1 1 auto) → close (44×44, "×")

The profile button goes between ttl and close. The flex:1 1 auto on the title already pushes everything after it to the right, so this needs no layout change at all: one head.appendChild in the existing order.

  • 44×44, matching close; the tap-target constant is already chosen.
  • Circular (borderRadius:P(22)) against close’s P(12), so it reads as an identity, not as a second control.
  • Left of close, not right. Dismiss stays the rightmost thing, and the tab order reads title → profile → close, which is the order of increasing consequence.

The monogram: two characters of the username, uppercased, on the hashed hue. No name text, no email. The panel is full-viewport but it lands on other organisations’ pages; a header that spells out a person’s email on a customer’s site is a disclosure decision nobody asked for, and the accessible name carries the full username anyway (aria-label, title, the same pattern the tiles use).

<a target="_blank" rel="noopener"> to the console URL. Nothing intercepts the activation. Three reasons this is not a menu:

  1. Portal ruling §4: “Consoles are linked out in new tabs, never embedded.” A plain anchor is exactly compliant; anything that renders console content inside the panel is not.
  2. §15 already made this decision for tiles and gave the reasoning: W.open() from a handler needs a preventDefault that kills every modifier gesture, and is a blockable programmatic popup. Middle-click, cmd-click and copy-link keep working for free.
  3. 314 bytes. A menu needs a popup, outside-click dismissal, focus management and Escape handling. That does not fit, and the ceiling is a disclosure bound, not a performance one; raising it is a decision someone has to write down, and “so the profile could have a dropdown” is a weak thing to write.

Sign out must not be in it, even if a menu were free. The payload runs on pages the user did not get from us; “Sign out” there is ambiguous between the app they are standing in and SHC itself. Worse, auto.go already watches for logout transitions to latch the auto-redirect off; a launcher-initiated sign-out would either trip that latch or need a carve-out in it. Session management belongs to Keycloak’s account console, one link further in.

Whether it renders when there is no console

Section titled “Whether it renders when there is no console”

It must not, and the mechanism is the one this codebase already uses three times.

The daemon stamps a console URL onto the /apps response as an omitempty field (the wire uses terse keys: "c" beside the existing "n"/"h"/"i"/"a"). Absent field → no button. One field does both jobs: it decides visibility and supplies the destination, so there is no state where the button exists and the URL does not.

This is the shell manifest’s doctrine (“absent/unreadable manifest → NO SHELL … never an error a user sees”) and launcher_placed’s (“false is the only value ever written; placed rides as an absent field”). It also means the rollout needs no plugin repin: today the field is absent on every estate and the button renders nowhere, correctly, since nothing serves console bytes anywhere, and when console serving lands (console doc owed work #2) the affordance lights up on its own.

Console doc owed work #0 asks for the launcher→console entry with “role-gated visibility to match the console’s RBAC screens”. Recommend not role-gating this one. Console ruling 3 is that every realm user may sign in and operator screens gate inside; the profile affordance is the door to a user’s own account, so gating it on an operator role hides identity from exactly the users who have nothing else. Gate on console presence, not on role, and let the console keep gating its own screens, which it already does.

The free tier needs no new line either: it has no launcher menu at all, so this surface is Hobby+ by construction.

5. What does NOT belong: the junk-drawer fence

Section titled “5. What does NOT belong: the junk-drawer fence”

Stated as refusals, because the failure mode of “settings” is that everything lands in it.

Not in the profile affordanceWhere it lives
Sign out / session listKeycloak account console (§4)
ThemeNowhere; parity is a token, not a preference (console ruling 5)
Launcher arrangementThe launcher itself, by dragging (already shipped)
Anything with a submenuNowhere; it is a link
Not in the console’s /settingsWhere it lives
Per-app configurationThe app
Estate/cluster config (shc config)Its own proposal, if ever
User & role administrationThe console, but its own RBAC-gated screen
Cluster registration, billing, fleetThe Portal (console ruling 7: no cross-cluster anything)
A second clusterNowhere in the console, ever (ruling 7)
  1. Daemon stamps the console URL onto the /apps response (omitempty); absent until console serving exists. Blocked on console owed work #2.
  2. Payload: username on the response, monogram button in the header, anchor with target="_blank" rel="noopener". Must land under 24,500: measure, and if it does not fit, shrink the payload rather than raise the ceiling a fourth time in a month.
  3. Guards: button absent when the field is absent; monogram never fetches; modifier-click opens exactly one tab (the §15 guard, extended).
  4. Fill in features/console/src/SettingsScreen.tsx past the stub.
  5. Correct launcher.md §12.8’s budget table; it is two raises behind.
  1. Confirm the shape: no settings app; the console’s existing /settings is the surface; the launcher gets a monogram → console link. Ruled?
  2. Monogram, not avatar: accepted? It follows from the icon hot-linking ruling, but it does mean no faces, ever, unless the daemon later materialises avatar bytes the way it materialises app icons.
  3. Link, not menu: accepted? The cost is that there is no sign-out in the launcher at all, on any page.
  4. Gate on console presence, not on role; this contradicts the wording of console owed work #0. Which wins?
  5. Where does the link land: console / (the stacks list, ruling 4) or console /settings? “Profile” argues /settings; “console” argues /.
  6. 314 bytes. If the honest implementation measures over, is the answer to shrink the payload, or to raise the ceiling a fourth time?
  7. Does the destination change once the Portal exists? A profile might reasonably lead to the Portal account rather than the per-cluster console: but ruling 7 keeps cross-cluster navigation portal-only, so this affordance should probably stay pointed at the local console forever. Confirm.