Welcome Guide

The welcome guide

Super+Escape, and it comes up on your first login.

Seven pages on what this desktop is and which keys do it, with a rail down the left that doubles as a contents page and a line under every row saying what the thing actually is:

Page	What is on it
Welcome	The terminal, the command bar, the control panel — and how the guide is driven
The keys	The shortcut palette, the start menu, the application grid, the task manager, and the workspace and window keys
Layouts	The seven window layouts, in the order Super+Tab walks them, with the keys that jump straight to tiling and cascade and the control-panel row that names all seven
Make it yours	Appearance, wallpaper, display settings, desktop widgets, screen filters, screensaver
The AI	The command bar, the neural overlay, which model is loaded, and the backend — GPU, CPU or off
Everything else	Network, power, calculator, news, game mode, cat mode, lock screen
You're set	The shortcut palette, the control panel, About this system, and where the documentation lives

Arrows move, Left/Right turn the page, Enter opens the selected row, Space ticks the checkbox, Esc closes. Clicking outside it closes it too, and so does the × in the corner — the guide is the first thing somebody meets, and "press Escape and hope you knew that" is not a way out for them.

synui-welcome              # toggle it — the default verb
synui-welcome show         # …or on a named monitor: synui-welcome show DP-1
synui-welcome page 3       # straight to the layouts
synui-welcome hide

There is also a Welcome Guide entry in the applications menu. A panel reachable only by a chord is a panel nobody finds, and Super+Escape is not a discoverable key.

The key column is live

Every chord the guide shows is read out of the running compositor over synctl binds, which reports synui's own bind table with each combination already spelled the way the shortcut palette and the control panel spell it.

That is not a detail. The guide it replaces carried a hand-typed chord per row, and it had been wrong more than once — the command bar has been on Super+Space, on Super+=, and back again, and each move left the column naming the key before it. Anyone who rebinds something in the Super+/ palette was in the same position. Now nothing has to remember to update it.

Turning it off

The Don't show again checkbox sits in the footer of every page — not only the last one, since anybody who dismisses the guide early would otherwise never find the switch that stops it coming back.

It writes welcome_at_startup, which is also a synuirc key and a row in the control panel:

welcome_at_startup = off

The state file (~/.config/synui/welcome.state) overrides the synuirc line once you have used the checkbox; delete it to hand control back to the config. Note the sense — the checkbox is the opt-out and the config key is the opt-in, so the box is ticked when the setting is off.

Super+Escape opens the guide either way, so turning this off never strands it.

How it is built, and why that matters

The guide is a quickshell window in a process of its own rather than a panel the compositor draws. Three things follow from that, and the first is the reason:

• Two bars ship. bar_shell = synapse|antiquity picks one (see The Desktop), and a guide living inside one of them would simply not exist for anyone running the other. The panel it replaces was drawn by synui itself, so every configuration had it.
• It costs nothing while closed. Dismissing it ends the process. Nothing is resident, and it does not reappear every time something restarts the bar.
• It is themed without copying anything. It is a second entry point into the bar's own QML tree, so it gets the palette, the picked UI font and the glass namespace from the same files the bar reads.

It also gets out of the way on its own: open a window while the guide is up and it closes. It is a full-screen surface, and the window underneath is what you actually asked for.

---

See also: Keybindings · Commands · The Desktop · Configuration