onboard

name

onboard

description

First-run onboarding for the desktop-manager plugin. Auto-profiles the local Linux desktop (distro, kernel, desktop environment, session type, package managers, audio stack, GPU, hardware summary), then interviews the user for the small handful of things that can't be auto-detected (sudo policy, GUI-app packaging preference, hardware quirks, services of interest), and persists the result to `$CLAUDE_USER_DATA/desktop-manager/profile.json`. Run this before any other skill in this plugin, or whenever the machine changes (distro upgrade, new GPU, switched DE, etc.). Triggers on phrases like "set up desktop manager", "onboard desktop", "profile this machine".

desktop-manager: onboard

Establish the persistent machine profile for the local Linux desktop. Every other command in this plugin reads from profile.json and refuses to run without it. Keeping the profile out of the plugin tree (in $CLAUDE_USER_DATA) means it survives plugin upgrades and never gets committed to git.

The same plugin install can serve different machines — the profile is per-machine, not per-plugin.

Workspace resolution

PLUGIN_DATA_DIR="${CLAUDE_USER_DATA:-${XDG_DATA_HOME:-$HOME/.local/share}/claude-plugins}/desktop-manager"
mkdir -p "$PLUGIN_DATA_DIR"
PROFILE_FILE="$PLUGIN_DATA_DIR/profile.json"

Never write to ~/.claude/plugins/desktop-manager/ — that path is clobbered on plugin update. Canonical convention: see claude-rudder:plugin-data-storage.

When to use

• User says "set up desktop manager", "onboard desktop", "profile this machine", "configure desktop-manager".
• Any other desktop-manager command finds no profile.json at the resolved path — refuse to run and offer to onboard first.
• The user did a distro upgrade, swapped GPU, switched display server, or moved to a new machine.

For surgical edits to a single field, prefer /desktop-manager:update-profile <field> rather than re-running the full onboarding.

Procedure

1. Existing profile?

If $PROFILE_FILE exists, read it and show the current values back. Offer:

• Update — re-run auto-detection, diff against current values, ask about each diff.
• Replace — discard the old profile entirely and start fresh.
• Cancel — bail out.

If no existing profile, proceed to step 2.

2. Auto-detect (no questions)

Run the probes below and capture each value. Treat any failed probe as null and move on — don't error out.

Field	Probe
system.distro_id / version / codename	. /etc/os-release; echo "$ID $VERSION_ID $VERSION_CODENAME"
system.kernel	uname -r
system.arch	uname -m
system.init_system	Check /run/systemd/system exists → systemd; else inspect ps -p 1 -o comm=.
system.hostname	hostnamectl --static 2>/dev/null || hostname
desktop.environment	$XDG_CURRENT_DESKTOP (split on :, take last meaningful entry — e.g. KDE, GNOME, XFCE).
desktop.session_type	$XDG_SESSION_TYPE (x11 / wayland / tty).
desktop.audio_stack	pgrep -x pipewire >/dev/null && echo pipewire || (pgrep -x pulseaudio >/dev/null && echo pulseaudio || echo alsa)
packaging.native	First match: command -v apt → apt; dnf → dnf; pacman → pacman; zypper → zypper; else null.
packaging.supplementary	Build a list — command -v flatpak, command -v snap.
hardware.cpu_model / cpu_cores	lscpu (parse "Model name", "CPU(s)").
hardware.ram_gb	awk '/MemTotal/ {printf "%.0f", $2/1024/1024}' /proc/meminfo

Show the user the auto-detected values in a compact table before moving on. Flag any null fields explicitly.

3. Interview (only what can't be auto-detected)

Ask each question. Default sensibly when the user just hits enter:

Field	Prompt	Default	Notes
packaging.preferred_for_gui_apps	"When a GUI app is available from both your native package manager and Flatpak, which do you prefer?"	flatpak if installed, else native	Skip the question if flatpak and snap aren't present.
packaging.ask_when_ambiguous	"Should I always ask before picking a backend, or just default to your preferred one?"	true (ask)
policies.sudo_mode	"Sudo policy on this machine? (passwordless / timestamp / password)"	timestamp	Affects whether commands warn before invoking sudo.
policies.auto_reboot_after_update	"After a system update flags reboot-required, may I reboot without re-asking?"	false
policies.default_editor	"Default editor for config edits?"	$EDITOR if set, else nano
services_of_interest	"Any systemd services you'd like surfaced by default in review-logs? (comma-separated)"	["NetworkManager"]	Append-only list.
quirks	"Any hardware or distro quirks I should know about? (free text — leave blank if none)"	[]	Multi-line.

4. Confirm and write

Show the assembled profile back to the user, prompt for one final confirmation, then write $PROFILE_FILE:

chmod 600 "$PROFILE_FILE"

Set version: 1 and last_profiled to ISO-8601 UTC.

5. Tell the user what's ready

Print the resolved path and list the now-ready commands:

• /desktop-manager:check-system — broader snapshot built on top of the profile
• /desktop-manager:install-package, /desktop-manager:remove-package, /desktop-manager:update-system
• /desktop-manager:apply-config
• /desktop-manager:inspect-service, /desktop-manager:review-logs
• /desktop-manager:troubleshoot-hardware

Mention that update-profile exists for surgical edits.

Schema reference

See lib/PROFILE.md in this plugin for the full schema, field semantics, and migration notes.