New user on-boarding/OOBE needs attention...

[signaldirective]

Originally I was going to write this as a PR but the contributing guide recommends discussions->suggestions, so I decided to post here instead: I propose adding two of my plugins into Omarchy - they would likely be a really good fit with the version of Omarchy shell that will add the dock for users not used to tiling window management. The on-boarding experience for new users is .... not great. Let me be clear, I love Omarchy. I'm a full-on Omarchy Evangelist. I adore this distro. But I've been seeing some really regrettable things in regards to the new user experience for people coming from other OSes that do not have experience with Linux and people who do not have any experience with AI prompts beyond the ones that run in their browser. I really want us to retain those users, but in the current state of the on-boarding process we're not going to. I've had to personally talk 7 different people out of giving up on Omarchy because they didn't know what to do once the distro was installed, or how to get help when something goes wrong. If they had a very simple new user experience like what my plugins provide, it would solve two of the biggest problems with the current on-boarding process.

---

What a new user gets today

I traced the actual first-login path. It is one script, and it is short:

omarchy-provision-first-run runs once per user from default/hypr/autostart.lua.
After user provisioning, it installs three post-update hooks (Voxtype,
fingerprint, agent setup), enables user units, sets the GNOME and GTK details,
tunes the speakers, waits for the notification service, and then sends exactly
one piece of onboarding to the screen — install/user/first-run/welcome.sh:

# install/user/first-run/welcome.sh
omarchy-notification-send -u critical -g <icon> "Learn Keybindings" \
  $'Super + K for cheatsheet.\nSuper + Space for Omarchy Menu.' \
  --exec omarchy-menu-keybindings

install/user/first-run/setup-agent.hook adds a second invitation, but it is
installed as a post-update hook, and it assumes the vocabulary already:

# install/user/first-run/setup-agent.hook
omarchy-notification-send -u critical -g <icon> "Set your default agent" \
  "Let your favorite agent help with Omarchy." \
  --exec omarchy menu summon setup.default.agent

So the complete new-user experience is: a critical toast telling you which two
keys open the menu and the cheatsheet, and a toast asking you to pick a default
agent. Both are useful. Neither answers the two questions someone arriving from
macOS or Windows actually has on day one:

1. What do I do with this computer now? The toast explains where the menu is,
   not that the machine will help you change itself.
2. What is an agent, and how would I talk to one? The invitation presumes
   the answer. There is no icon, no window, and no link on screen that shows a
   newcomer what an agent is or how to get help right there.

Nothing on the first-run path links to the manual, the Discord, the community
themes, or the plugin marketplace — the four places every new user eventually
needs, and the four that would have answered their first question without them
having to ask a human.

The observation that started this

In #omarchy I counted the last ten people who asked for help and were told to
ask their agent. Eight of them replied "what agent?", "okay", or said nothing.
I DM'd all eight; none of them knew what an agent was or how to reach one on
their machine.

That is ten conversations in one channel, not a survey, and I am not claiming
more than it is. But the failure mode is specific and it is not a documentation
problem: these are people who were already in the place where the community
gathers, and the answer "ask your agent" arrived in a vocabulary they had never
been given. The system tells them where the menu is. It never tells them that
asking the computer a question in plain English is the intended way to use it.

Your own doctrine says it better than I can:

Welcome the agents. The age of agents is the most important paradigm shift
in computing since the microprocessor... Agents are welcome everywhere.

You're somebody now. Omarchy is for everyone willing to learn and
participate.

Everyone willing to learn needs to be told what they are learning. Right now
that happens in Discord, by hand, one newcomer at a time — and it lands eight
times out of ten.

The proposal

Two plugins, both already written, both MIT, both installable right now:

Plugin	What it is	The gap it closes
Make It Real	A first-run welcome window: three moves (open a terminal, run opencode, ask a clear question), a safe starter prompt you can copy, a reusable request pattern, buttons that open the real Omarchy menu and theme picker, and links to the manual, Discord, themes, and plugins.	"What do I do with this computer now?"
Mocchi	One quiet bar icon. Click it, type a question, press Enter — an agent opens with the question already sent. Ships a merged Omarchy + triage skill so the agent knows how to help with Omarchy and how to turn "my computer is doing X" into a report someone can act on.	"What is an agent, and how would I talk to one?"

Together they cover the two questions the current first-run does not: one window
that teaches the shape of the workflow, and one icon that turns "I wonder
if..." into an answered question without a terminal in the way.

How it would land in-tree

Concretely, so this is reviewable rather than aspirational:

1. Vendor both as first-party plugins beside the existing ones, under
   shell/plugins/mocchi/ and shell/plugins/make-it-real/, with ids
   omarchy.mocchi and omarchy.make-it-real (author Omarchy, MIT, matching
   shell/plugins/agents/manifest.json). Both are plain plugin directories that
   pass omarchy plugin validate . today, with no installer script, no
   background service, and no build step.
2. Add one step to the first-run sequence in omarchy-provision-first-run,
   next to the existing notification steps, opening the welcome window after the
   keybindings toast. The plugin's own self-trigger would be removed in favour of
   this, so the first-run script stays the single place that decides what a new
   user sees, and omarchy-done keeps the once-only guarantee.
3. Add the icon to the default bar layout in config/omarchy/shell.json,
   in the right section beside omarchy.agents — the icon people will look for
   when they are told to "ask your agent".
4. Keep the keybindings toast. It is not the problem; it is just not the
   whole onboarding.
5. A migration for existing installs that enables both plugins without
   re-running the welcome window for people who are years past their first boot.

Happy to write these commits, or to hand the code over for you to reshape. The
integration points above are a suggestion, not a constraint — you own the
placement.

Objections, answered

"There is already an omarchy.agents widget."
It shows usage: rate-limit meters for Claude Code, Codex, and Fireworks. Its
right-click runs omarchy-agent --pick, which launches the agent picker. It
never asks you a question or carries one anywhere. Mocchi is the ask box on the
other side of the same idea: the difference between "which agent would you like"
and "here is my question".

"We already invite people to set a default agent."
That invitation asks you to choose an agent and assume the vocabulary. It also
arrives through the post-update path. Neither it nor the keybindings toast says
what an agent can do for you, or gives you something to try.

"Please do not add more toasts."
I agree, so the new toast is deliberately modest: urgency low (not critical),
at most once per six hours, and it can be silenced in one right-click — "hide
until I log out" or "don't show the greeting again" — with the choice persisted
in the widget's own settings. The welcome window has a Do not show again
toggle and reopens from Learn → Make It Real afterwards. Both are one click from gone, which is the standard any nudge should have to meet.

"Why in-tree instead of a plugin people can install?"
Because the audience for onboarding is exactly the audience that does not yet
know plugins exist. The marketplace is a fine answer to "how do I add this
thing", and no answer at all to "what is a thing, and why would I want one".
Onboarding that requires the knowledge it is teaching cannot work.

"Vendoring third-party code adds trust and maintenance surface."
Both are deliberately small and boring: 467 lines (Mocchi, plus a 13-file
markdown skill) and 590 lines (Make It Real) of QML and bash. No sudo, no
pkexec, no network requests, no background service, no eval, and no execution
of user text as a command. They are built entirely from Omarchy's own
pieces: omarchy menu input, omarchy default agent, omarchy agent prompt,
omarchy launch browser, omarchy-launch-tui, omarchy-notification-send.

They do write a little, and here is all of it. Make It Real keeps one preference
file (~/.local/state/omarchy/make-it-real/welcome-mode) and starts a terminal
when asked. Mocchi keeps its greeting markers in
~/.local/state/omarchy/mocchi/, records greeting: off in your own bar
settings when you click "don't show the greeting again", and — unless you set
its skill option to off — links its bundled skill at
~/.agents/skills/mocchi (the same directory Omarchy links its own omarchy
and diagnose-crash skills into) and adds one instructions entry to
~/.config/opencode/opencode.json, backing the file up as .mocchi.bak first.

Mocchi's README documents the sharp edge honestly: omarchy agent prompt
launches every agent with its pre-approved flags, which is Omarchy's own
behaviour and not something these plugins change. The free fallback (with no
default agent set) runs opencode mini without auto-approval.

"This belongs in the manual, not on screen."
The manual is excellent and already says all of it. The moment of need is a
freshly installed machine, before the person knows the manual exists. Both
plugins link to it from the screen where the question is actually being asked.

What this deliberately does not do

• It does not pick an agent for anyone, and it does not send a prompt on the
  user's behalf. Make It Real copies an example question; the user starts
  OpenCode and sends it. Mocchi asks, then hands the text to whichever agent
  omarchy default agent reports — including a free OpenCode session when none
  is set, so a person with no agent and no account still gets a real answer.
• It does not touch the keybindings toast, the agent invitation, or anything
  else in the first-run sequence.
• It does not change any theme or any permission rule. The only configuration
  either plugin edits is Mocchi's own bar setting and, unless you turn its
  skill option off, one instructions line in your OpenCode config.

Try it in thirty seconds

omarchy plugin add https://github.com/signaldirective/first-boot-menu --enable
omarchy plugin add https://github.com/signaldirective/mocchi --enable --yes

Then reopen the welcome window any time with:

omarchy shell shell summon io.github.signaldirective.make-it-real '{}'

Both repositories ship preview images, and Mocchi's README documents every file
it touches outside its own plugin directory.

Maintenance

I will maintain both, either in-tree or as the upstream repos they are now. If
you would rather own the code outright, take it — the onboarding is the point,
not the authorship. If the shape you want is different (a single combined
plugin, no greeting toast at all, the links moved into the shell itself), say so
and I will build that version instead.

[klamer]

Written by Claude, reviewed by a human — it gets the point across.

Coming from 30 years of Windows, the RC's floating mode + dock is what made Omarchy click for me. But the first thing I went looking for was a settings app, and there's nothing in the dock or on the windows that points to one. The Omarchy menu (Super+Space) has everything, but nothing on screen says it exists. Even just a Settings icon pinned to the dock by default on floating workspaces, opening the menu (or something like #15428), would close that gap.