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)”| Claim | Reality |
|---|---|
A settings app exists | No. Not in apps/, not on either estate. |
| Settings does not exist at all | False. 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 deployed | No. 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 built | No. 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 room | 314 bytes. Measured 24,186 served against menuPayloadByteCeiling = 24500. |
| The launcher knows name/email/avatar | Only 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 dashes1. Recommendation
Section titled “1. Recommendation”No settings app. No new deployment. No new endpoint.
- The console’s existing
/settingsroute 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. - 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.
- 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.
2. Why not the other candidates
Section titled “2. Why not the other candidates”(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 content | Why it is not a setting |
|---|---|
| Launcher arrangement | Already 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. |
| Theme | Refused 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 sessions | Keycloak’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.gostampsmenuIdentity{User,Tenant,Stack,Verb}from the daemon verdict headersX-SHC-User/-Tenant/-Stack/-Verb.X-SHC-Useris 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.launcherAppsResponsecarriesVersion, State, Apps, Glyphs, Artsand 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.
4. The design
Section titled “4. The design”Where it sits
Section titled “Where it sits”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)) againstclose’sP(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.
What it shows at rest
Section titled “What it shows at rest”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).
What pressing it does: a link, not a menu
Section titled “What pressing it does: a link, not a menu”<a target="_blank" rel="noopener"> to the console URL. Nothing intercepts
the activation. Three reasons this is not a menu:
- 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.
- §15 already made this decision for tiles and gave the reasoning:
W.open()from a handler needs apreventDefaultthat kills every modifier gesture, and is a blockable programmatic popup. Middle-click, cmd-click and copy-link keep working for free. - 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.
One refinement to owed work #0
Section titled “One refinement to owed work #0”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 affordance | Where it lives |
|---|---|
| Sign out / session list | Keycloak account console (§4) |
| Theme | Nowhere; parity is a token, not a preference (console ruling 5) |
| Launcher arrangement | The launcher itself, by dragging (already shipped) |
| Anything with a submenu | Nowhere; it is a link |
Not in the console’s /settings | Where it lives |
|---|---|
| Per-app configuration | The app |
Estate/cluster config (shc config) | Its own proposal, if ever |
| User & role administration | The console, but its own RBAC-gated screen |
| Cluster registration, billing, fleet | The Portal (console ruling 7: no cross-cluster anything) |
| A second cluster | Nowhere in the console, ever (ruling 7) |
6. Owed work, if ruled
Section titled “6. Owed work, if ruled”- Daemon stamps the console URL onto the
/appsresponse (omitempty); absent until console serving exists. Blocked on console owed work #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. - Guards: button absent when the field is absent; monogram never fetches; modifier-click opens exactly one tab (the §15 guard, extended).
- Fill in
features/console/src/SettingsScreen.tsxpast the stub. - Correct launcher.md §12.8’s budget table; it is two raises behind.
7. Owner questions
Section titled “7. Owner questions”- Confirm the shape: no settings app; the console’s existing
/settingsis the surface; the launcher gets a monogram → console link. Ruled? - 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.
- Link, not menu: accepted? The cost is that there is no sign-out in the launcher at all, on any page.
- Gate on console presence, not on role; this contradicts the wording of console owed work #0. Which wins?
- Where does the link land: console
/(the stacks list, ruling 4) or console/settings? “Profile” argues/settings; “console” argues/. - 314 bytes. If the honest implementation measures over, is the answer to shrink the payload, or to raise the ceiling a fourth time?
- 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.