Client shell redesign — canonical vocabulary, additive telemetry, unchanged contract

The Gnostikon client shipped a redesigned shell in gnostikon-client#24. The visible change is structural — a persistent Rail, a contextual TopBar, an on-demand Inspector, and a default Today briefing replacing the old module launcher. The docs-side role here is narrow: publish the canonical vocabulary so future copy stays uniform, confirm the public API contract is unchanged, and flag the one cross-repo follow-up the redesign uncovered.

What visibly changed​

The navigation grammar shifted from a hidden drawer with a module launcher on the home route to a persistent, surface-divided shell:

• The Rail is the persistent left-side navigation (desktop and tablet variants). Replaces the legacy drawer / hamburger menu.
• The TopBar is the contextual top surface (scope, title, surface-specific actions).
• The Inspector is the right-side detail pane that opens on-demand for the active selection.
• The Today briefing is the new default home (/), composed of decisions, continue list, and pulse strip. The legacy module launcher remains reachable as a one-release fallback via /?legacy=1.
• The Knowledge workspace wraps Index / Graph / Missing / Builder in a single horizontal tab strip under /knowledge/*. The bare /knowledge URL resolves to the Index tab.
• The Command Palette (⌘K / Ctrl-K) and the Profile Drawer are the principal overlays.

The full vocabulary — definitions, legacy synonyms to avoid, and a back-pointer to the client source for every surface — lives at the Client shell vocabulary page. That page is the citable source going forward; copy in this post that mentions a surface name is a link, not a redefinition.

What stayed the same​

• The public API contract. No /api/* endpoint was added, renamed, or reshaped by this redesign. See the API reference. Integrators have nothing to migrate.
• The product-events taxonomy is preserved. The client introduces a new chrome.* family of seven events — emitted from chrome-events.ts — and the family is intended as additive — no existing event from x-005 is renamed and no existing payload is reshaped. See the registry note for the seven names.

Where the canonical vocabulary lives​

The Client shell vocabulary page is the citable source for every chrome surface — definition, legacy synonyms to avoid, and a GitHub back-pointer to the client source. A docs-side glossary exists because copy decay is real: without one citable source, prose drifts back to the old vocabulary the next time anyone writes a use-case page or a release note. PR reviewers should cite the page during review whenever copy mentions a client surface.

Open follow-ups​

• Backend chrome.* allow-list. As of this post, none of the seven chrome.* event names appear in the backend allow_list.py. The events are emitted by the client but rejected at ingest with rejected_unknown_event, so they do not currently land in the canonical store. A backend PR is needed to add the seven names before analytics consumers can observe the family. The registry note tracks this gap.
• Client cleanup (Spine fe-006). Residual chrome-migration cleanup (token discipline, gesture wiring, telemetry guard) ships under a separate Spine task and a separate client PR; out of scope for this docs review.
• Shell screenshots in docs. The docs site does not host product screenshots today (static/img/ is brand and OG assets only). Producing 3-viewport captures of the new shell and finding the right editorial home for them is deferred to a separate visual-refresh task; the audit posture chosen here is "name the surfaces, link the source, defer the visuals."
• Future renames trigger a follow-up dx-. If a future client release renames or restructures any canonical surface above, a follow-up dx- task is required to keep the glossary truthful. Any divergence between the glossary's back-pointers and the actual client source should be reported.

Related​

• PR: gnostikon-client#24 (shell redesign, merged 2026-05-15).
• Docs: Client shell vocabulary · In-app diagnostics surface · Canonical event registry — chrome.* note.