feat(desktop): make shell controls, help, and welcome flows reliable
Some checks are pending
ci / test (push) Waiting to run

This commit is contained in:
Phoebus 2026-10-01 18:56:40 -07:00
parent c5b1c34cbc
commit 842dfe787f
11 changed files with 408 additions and 68 deletions

View file

@ -5,6 +5,26 @@ this file is the curated, human-readable summary.
## Unreleased — Fast defaults with user-controlled source builds
- **Desktop controls, welcome and offline help (2026-10-01).** Audited the
running disposable QEMU desktop across the top bar, control center, DMS
Settings, DMS onboarding and both Phoebus welcome variants. The Assistant
now opens as a 900×650 floating scratchpad; Super+A and Escape hide it, and
Super+A restores the same Quickshell process and conversation. A tab row
layout fix keeps controls visible. Phoebus Welcome closes its Quickshell
process so it can reopen, floats at 720×600, and places its Help, DMS tour
and finish actions above optional builds. DMS Welcome is reachable from
that window, a desktop entry and Super+Alt+W. A new local HTML Phoebus Help
guide covers daily use, `sys`, recovery and keybindings; it opens from the
launcher, Welcome and Super+F1. The live image manifest includes Firefox ESR and
`xdg-utils` so this local page opens there. The live Welcome now routes Network,
display and text controls to their exact DMS Settings pages, exposes the
offline guide, installation help and DMS Welcome, and explains an absent
installer log. First login seeds
Kitty as the terminal and Firefox/Thunderbird for HTML/mail links only when
the user has not chosen defaults. The existing installed QEMU playground
verified the UI paths and offline Help; a fresh ISO/install remains pending
the host space gate.
- **Settings size and VM pointer alignment (2026-10-01).** DMS Settings now
opens at 900×700 on new Mango profiles. The interactive QEMU launcher uses
unscaled 2D VirtIO output and an absolute USB tablet by default after both

View file

@ -3,6 +3,26 @@
Rolling note between work sessions. **Update this file before you finish**, then
commit it. It should be short and current; use `git log` for detail.
- **Shell control and help pass (2026-10-01):** Added an offline Phoebus Help
page, launcher and Super+F1 shortcut; DMS Welcome now has a separate launcher,
Super+Alt+W shortcut and button in Phoebus Welcome. The live medium manifest
now includes Firefox ESR and `xdg-utils` for the Help page. The installed Welcome
is a styled 720×600 floating window with Help and finish controls visible on
first view, and its close path quits Quickshell so `--reopen` works. The
Assistant is a 900×650 floating scratchpad; Super+A toggles the same process
and Escape hides it. The live Welcome routes Network, display and text
buttons to exact DMS tabs, retains its installation help, and shows a useful
message before an installer log exists. First login fills missing terminal,
HTML and mail defaults with
Kitty, Firefox and Thunderbird. The existing visible disposable QEMU VM was
updated and the bar panels, DMS Settings pages, both welcome paths, Help and
assistant toggles were visually exercised. Both launcher shortcuts worked;
the launcher showed the new Help and DMS entries. Rust formatting, Clippy,
workspace tests, release and static builds, ShellCheck and desktop entry
validation passed. The live-only install action and restart/shutdown actions
were inspected but not activated. A fresh ISO or
install is still gated by roughly 10 GiB free versus the 20 GiB requirement.
- **Settings and pointer (2026-10-01):** The DMS Settings window was only
about 500×400 because Mango floated it at its minimum size. A specific
900×700 Settings rule was added to the packaged Mango config and checked in

View file

@ -48,6 +48,33 @@ disposable VM; `serial-driver.py recovery` now automates the same check.
## Matrix
Desktop control audit (2026-10-01): in the existing disposable QEMU desktop,
the top-bar launcher, Super+Space and Super+P launcher shortcuts, clipboard,
process/CPU/memory panels, notifications, power profile, control center and
clock opened. DMS Welcome advanced through
its system check, plugins and final page; its new shortcut and Phoebus
Welcome button reopened it. DMS Settings rendered wallpaper, theme, text,
time, sounds, Mango layout, bar setup/widgets/workspaces, notifications,
dock/launcher, keybinds, display/gamma, network, default apps, audio, locale,
clipboard, users, lock/power, plugins and About. The bar Widgets page took
several seconds to populate but did finish. The Assistant's floating window,
all five tabs, Super+A show/hide, and Escape hide were exercised. Phoebus
Welcome opened Help, DMS Welcome and Assistant, closed and reopened; Help
loaded from its local HTML file with Super+F1. The live Welcome QML was also
loaded in the installed VM for safe control testing: Network, display chooser
and DMS display settings, text settings, Power/Cancel, advanced terminal,
system/installer logs and disk information opened. Restart, shut down and
the live-only installer launch were inspected in code but not activated on
this installed VM. Individual DMS setting mutations and every plugin were not
exhaustively exercised. A fresh ISO/install with these assets remains
unverified because the host has under 20 GiB free. The live package manifest
now includes Firefox ESR and `xdg-utils` so the new Help button has a browser;
that live-specific path still awaits a fresh ISO boot. The Rust formatting,
Clippy, workspace test, release build and static live installer build gates
passed; the live build script and generated desktop scripts passed ShellCheck (with
the intentional nested-shell quoting diagnostic excluded). Desktop entry
validation passed.
Desktop wallpapers: four generated JPEG choices are bundled into the installer
and seeded into the installation user's `Pictures/Wallpapers` folder and
`/etc/skel` without replacing existing images. The live ISO build copies the

View file

@ -1455,6 +1455,25 @@ for f in colors layout outputs; do
[ -e "$HOME/.config/mango/dms/$f.conf" ] || : > "$HOME/.config/mango/dms/$f.conf"
done
# DMS uses xdg-terminals.list for the launcher's terminal action. Seed Kitty
# once; a user's later Default Apps choice takes precedence.
terminal_list="${XDG_CONFIG_HOME:-$HOME/.config}/xdg-terminals.list"
if [ ! -e "$terminal_list" ] && [ -f /usr/share/applications/kitty.desktop ]; then
mkdir -p "$(dirname "$terminal_list")"
printf '%s\n' 'kitty.desktop' > "$terminal_list"
fi
# Without a user choice, Gentoo's system MIME default can pick Emacs for
# mailto links even when Thunderbird is installed as the graphical mail app.
mimeapps="${XDG_CONFIG_HOME:-$HOME/.config}/mimeapps.list"
if [ -f /usr/share/applications/thunderbird-bin.desktop ] \
&& ! grep -q '^x-scheme-handler/mailto=' "$mimeapps" 2>/dev/null; then
xdg-mime default thunderbird-bin.desktop x-scheme-handler/mailto 2>/dev/null || true
fi
if [ -f /usr/share/applications/firefox-bin.desktop ] \
&& ! grep -q '^text/html=' "$mimeapps" 2>/dev/null; then
xdg-mime default firefox-bin.desktop text/html 2>/dev/null || true
fi
HELPERS=""
start_helper() {
@ -1638,6 +1657,8 @@ tagrule=id:9,layout_name:tile
layerrule=noanim:1,layer_name:^dms
windowrule=isfloating:1,appid:^com.danklinux.dms$
windowrule=width:900,height:700,appid:^com.danklinux.dms$,title:^Settings$
windowrule=isfloating:1,width:900,height:650,title:^Phoebus Assistant$
windowrule=isfloating:1,width:720,height:600,title:^Welcome to Phoebus OS$
windowrule=isfullscreen:1,title:^Install Phoebus OS$
# ===========================================================================
@ -1760,6 +1781,9 @@ bind=SUPER+CTRL,m,spawn,dms ipc call processlist focusOrToggle
bind=SUPER+CTRL,comma,spawn,dms ipc call settings focusOrToggle
bind=SUPER,n,spawn,dms ipc call notifications toggle
bind=SUPER,a,spawn,phoebus-assistant
bind=SUPER,F1,spawn,phoebus-help
bind=SUPER+SHIFT,w,spawn,phoebus-welcome --reopen
bind=SUPER+ALT,w,spawn,dms ipc call welcome open
# Security & Session
bind=SUPER+ALT,l,spawn,dms ipc call lock lock
@ -1794,6 +1818,10 @@ set -u
if [ -n "${WAYLAND_DISPLAY:-}" ] || [ -n "${DISPLAY:-}" ]; then
if command -v quickshell >/dev/null 2>&1 \
&& [ -f /etc/xdg/quickshell/phoebus-assistant/shell.qml ]; then
# Keep the active conversation when the shortcut is pressed again.
if quickshell ipc -c phoebus-assistant call panel toggle >/dev/null 2>&1; then
exit 0
fi
exec quickshell --no-duplicate -c phoebus-assistant
fi
fi
@ -1817,6 +1845,65 @@ Categories=System;Settings;
Keywords=system;admin;assistant;ai;sys;install;update;
"#;
pub const PHOEBUS_HELP_SCRIPT: &str = r#"#!/bin/bash
set -u
page=/usr/share/phoebus/help/index.html
if [ ! -f "$page" ]; then
echo "Phoebus Help is not installed at $page" >&2
exit 1
fi
if [ -e /etc/phoebus/live ] && command -v firefox-esr >/dev/null 2>&1; then
exec firefox-esr "$page"
fi
if command -v xdg-open >/dev/null 2>&1; then
exec xdg-open "$page"
fi
if command -v gio >/dev/null 2>&1; then
exec gio open "$page"
fi
echo "Open $page in a browser to read Phoebus Help." >&2
exit 1
"#;
pub const PHOEBUS_HELP_DESKTOP_ENTRY: &str = r#"[Desktop Entry]
Name=Phoebus Help
Comment=Offline guide and keyboard shortcut cheat sheet
Exec=/usr/local/bin/phoebus-help
Icon=help-browser
Terminal=false
Type=Application
Categories=System;Documentation;
Keywords=help;guide;shortcuts;keybindings;sys;
"#;
pub const DMS_WELCOME_DESKTOP_ENTRY: &str = r#"[Desktop Entry]
Name=DMS Welcome
Comment=Explore the DankMaterialShell desktop and onboarding guide
Exec=dms ipc call welcome open
Icon=preferences-desktop
Terminal=false
Type=Application
Categories=Settings;
Keywords=dms;welcome;guide;desktop;
"#;
pub fn desktop_help_assets() -> Vec<(&'static str, &'static str)> {
vec![
(
"usr/share/phoebus/help/index.html",
include_str!("../../../../installer/live/desktop/phoebus-help/index.html"),
),
(
"usr/share/applications/phoebus-help.desktop",
PHOEBUS_HELP_DESKTOP_ENTRY,
),
(
"usr/share/applications/dms-welcome.desktop",
DMS_WELCOME_DESKTOP_ENTRY,
),
]
}
pub const PHOEBUS_POLKIT_POLICY: &str = r#"<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE policyconfig PUBLIC
"-//freedesktop//DTD PolicyKit Policy Configuration 1.0//EN"
@ -1942,8 +2029,32 @@ ApplicationWindow {
root.close()
}
// Never modal: closing or leaving finishes nothing and blocks nothing.
onClosing: markSeen()
// Quickshell keeps ShellRoot alive after ApplicationWindow closes. Quit
// this one-window config so --reopen can launch it again.
onClosing: {
markSeen()
Qt.quit()
}
component WelcomeButton: Button {
id: control
implicitWidth: Math.max(implicitContentWidth + 24, 100)
implicitHeight: 36
padding: 8
contentItem: Text {
text: control.text
font.pixelSize: 14
color: control.highlighted ? "#14161c" : "#e5e7eb"
horizontalAlignment: Text.AlignHCenter
verticalAlignment: Text.AlignVCenter
}
background: Rectangle {
radius: 6
color: control.highlighted ? "#f5b942" : (control.down ? "#414957" : "#303744")
border.color: control.activeFocus ? "#f5b942" : "#596273"
border.width: 1
}
}
Flickable {
anchors.fill: parent
@ -1981,6 +2092,72 @@ ApplicationWindow {
color: "#9aa0ab"
}
Rectangle {
Layout.fillWidth: true
implicitHeight: guideContent.implicitHeight + 28
color: "#20242c"
radius: 10
Column {
id: guideContent
x: 14
y: 14
width: parent.width - 28
spacing: 10
Text {
width: parent.width
text: "Explore your desktop"
font.bold: true
color: "#f5b942"
}
Text {
width: parent.width
text: "Read the offline Phoebus guide and keyboard shortcuts, or explore the original DMS onboarding tour. Both remain available from the launcher."
wrapMode: Text.WordWrap
color: "#d7dae0"
}
Row {
spacing: 8
WelcomeButton {
text: "Phoebus Help"
onClicked: Quickshell.execDetached(["/usr/local/bin/phoebus-help"])
}
WelcomeButton {
text: "DMS Welcome"
onClicked: Quickshell.execDetached(["dms", "ipc", "call", "welcome", "open"])
}
}
}
}
Rectangle {
Layout.fillWidth: true
implicitHeight: finishContent.implicitHeight + 28
color: "#20242c"
radius: 10
Column {
id: finishContent
x: 14
y: 14
width: parent.width - 28
spacing: 10
Text {
width: parent.width
text: "Keep the fast defaults and finish"
font.bold: true
color: "#f5b942"
}
Row {
spacing: 8
WelcomeButton {
id: keepButton
text: "Keep working system and finish (default)"
highlighted: true
onClicked: root.close()
KeyNavigation.tab: srcButton
}
WelcomeButton { text: "Close"; onClicked: root.close() }
}
}
}
Rectangle {
Layout.fillWidth: true
implicitHeight: sourceContent.implicitHeight + 28
@ -1994,7 +2171,7 @@ ApplicationWindow {
spacing: 10
Text {
width: parent.width
text: "1. Review and selectively build applications from source"
text: "Optional: rebuild applications from source"
font.bold: true
color: "#f5b942"
}
@ -2004,7 +2181,7 @@ ApplicationWindow {
wrapMode: Text.WordWrap
color: "#d7dae0"
}
Button {
WelcomeButton {
id: srcButton
text: "Open assistant to review source builds"
onClicked: root.openAssistant()
@ -2025,7 +2202,7 @@ ApplicationWindow {
spacing: 10
Text {
width: parent.width
text: "2. Build a kernel tuned for this machine"
text: "Optional: build a kernel tuned for this machine"
font.bold: true
color: "#f5b942"
}
@ -2035,7 +2212,7 @@ ApplicationWindow {
wrapMode: Text.WordWrap
color: "#d7dae0"
}
Button {
WelcomeButton {
id: kernelButton
text: "Open assistant to review tuned kernel"
onClicked: root.openAssistant()
@ -2043,38 +2220,8 @@ ApplicationWindow {
}
}
}
Rectangle {
Layout.fillWidth: true
implicitHeight: finishContent.implicitHeight + 28
color: "#20242c"
radius: 10
Column {
id: finishContent
x: 14
y: 14
width: parent.width - 28
spacing: 10
Text {
width: parent.width
text: "3. Keep the fast defaults and finish"
font.bold: true
color: "#f5b942"
}
Row {
spacing: 8
Button {
id: keepButton
text: "Keep working system and finish (default)"
highlighted: true
onClicked: root.close()
KeyNavigation.tab: srcButton
}
Button { text: "Close"; onClicked: root.close() }
}
}
}
Label {
text: "Keys: Tab moves, Enter activates, Esc closes. Reopen anytime from the launcher (Phoebus Welcome) or settings."
text: "Keys: Tab moves, Enter activates, Esc closes. Reopen anytime from the launcher or Super+Shift+W."
wrapMode: Text.WordWrap
Layout.fillWidth: true
color: "#9aa0ab"
@ -2362,6 +2509,12 @@ pub fn desktop_asset(name: &str) -> Option<String> {
Some(match name {
"session-mango" => PHOEBUS_MANGO_SESSION_SCRIPT.to_string(),
"assistant" => PHOEBUS_ASSISTANT_SCRIPT.to_string(),
"help" => PHOEBUS_HELP_SCRIPT.to_string(),
"help-html" => {
include_str!("../../../../installer/live/desktop/phoebus-help/index.html").to_string()
}
"help-desktop" => PHOEBUS_HELP_DESKTOP_ENTRY.to_string(),
"dms-welcome-desktop" => DMS_WELCOME_DESKTOP_ENTRY.to_string(),
"install" => PHOEBUS_INSTALL_SCRIPT.to_string(),
"welcome" => PHOEBUS_WELCOME_SCRIPT.to_string(),
"mango-config" => MANGO_CONFIG_DEFAULT.to_string(),

View file

@ -98,6 +98,15 @@ pub fn write_session_script(exec: &Exec, config: &InstallConfig) -> Result<()> {
sysgen::PHOEBUS_ASSISTANT_DESKTOP_ENTRY,
)?;
write_script(
&target,
"usr/local/bin/phoebus-help",
sysgen::PHOEBUS_HELP_SCRIPT,
)?;
for (rel_path, content) in sysgen::desktop_help_assets() {
write_public(&target, rel_path, content)?;
}
// Provision all assistant QML assets and Polkit policy into the target.
for (rel_path, content) in sysgen::assistant_desktop_assets() {
write_public(&target, rel_path, content)?;
@ -1060,5 +1069,13 @@ mod tests {
.root
.join("usr/share/polkit-1/actions/club.phoebus.sys.policy")
.is_file());
for path in [
"usr/local/bin/phoebus-help",
"usr/share/phoebus/help/index.html",
"usr/share/applications/phoebus-help.desktop",
"usr/share/applications/dms-welcome.desktop",
] {
assert!(exec.root.join(path).is_file(), "missing {path}");
}
}
}

View file

@ -85,6 +85,8 @@ fn live_package_list_carries_the_desktop_stack() {
.collect();
for required in [
"quickshell",
"firefox-esr",
"xdg-utils",
"greetd",
"tuigreet",
// Mango is built from source, so its build dependencies must be present.
@ -213,15 +215,21 @@ fn live_build_installs_the_branded_launcher_and_marker() {
"phoebus-welcome",
"usr/share/phoebus/branding",
"etc/phoebus/live",
"usr/share/phoebus/help/index.html",
"usr/share/applications/phoebus-help.desktop",
"usr/share/applications/dms-welcome.desktop",
"brand-wallpaper",
"splash.png",
] {
assert!(build.contains(needle), "build.sh is missing {needle}");
}
// The live help text is shipped and read by the welcome window.
// The installer-specific help text remains in the live payload.
let help = read("installer/live/install-help.txt");
assert!(help.contains("ERASE"));
assert!(help.contains("LUKS2"));
let guide = system::desktop_asset("help-html").expect("offline desktop guide");
assert!(guide.contains("Keybinding cheat sheet"));
assert!(guide.contains("sys apply updates --legacy"));
}
#[test]
@ -348,10 +356,10 @@ fn assistant_layout_fits_small_vm_windows() {
let shell = read("installer/live/desktop/phoebus-assistant/shell.qml");
// Quickshell FloatingWindow accepts implicit sizing, not minimumWidth or
// minimumHeight. The content and tab row scroll at smaller sizes.
assert!(shell.contains("implicitWidth: 820"));
assert!(shell.contains("implicitHeight: 640"));
assert!(!shell.contains("minimumWidth:"));
assert!(!shell.contains("minimumHeight:"));
assert!(shell.contains("implicitWidth: 900"));
assert!(shell.contains("implicitHeight: 650"));
assert!(!shell.contains("\n minimumWidth:"));
assert!(!shell.contains("\n minimumHeight:"));
assert!(
shell.contains("Flickable") || shell.contains("Flow") || shell.contains("ScrollView"),
"tab row never wraps or scrolls"

View file

@ -99,7 +99,7 @@ echo "releases OK"
# ---------------------------------------------------------------------------
say "emit shared desktop assets"
assets=(
session-mango assistant install welcome
session-mango assistant help help-html help-desktop dms-welcome-desktop install welcome
mango-config mango-session-target install-desktop
wayland-session-mango greetd-live live-sudoers
brand-emblem brand-wordmark brand-wallpaper brand-tokens
@ -240,6 +240,10 @@ install_asset() {
install_asset session-mango /usr/local/bin/phoebus-session-mango 0755
ln -sf phoebus-session-mango "$rootfs/usr/local/bin/phoebus-session"
install_asset assistant /usr/local/bin/phoebus-assistant 0755
install_asset help /usr/local/bin/phoebus-help 0755
install_asset help-html /usr/share/phoebus/help/index.html
install_asset help-desktop /usr/share/applications/phoebus-help.desktop
install_asset dms-welcome-desktop /usr/share/applications/dms-welcome.desktop
install_asset install /usr/local/bin/phoebus-install 0755
install_asset welcome /usr/local/bin/phoebus-welcome 0755
install_asset mango-config /etc/xdg/mango/config.conf
@ -417,6 +421,10 @@ grep -q "initial_session" "$rootfs/etc/greetd/config.toml" || {
echo "live rootfs has no Install Phoebus launcher" >&2; exit 1; }
for check in \
usr/local/bin/phoebus-welcome \
usr/local/bin/phoebus-help \
usr/share/phoebus/help/index.html \
usr/share/applications/phoebus-help.desktop \
usr/share/applications/dms-welcome.desktop \
etc/xdg/quickshell/phoebus-welcome/shell.qml \
etc/xdg/quickshell/phoebus-install/shell.qml \
usr/share/phoebus/branding/emblem.svg \

View file

@ -8,6 +8,9 @@ import "Common"
ShellRoot {
id: shell
// Keep the broker and conversation alive while the scratchpad is hidden.
property bool panelOpen: true
property string currentTab: "assistant" // "assistant", "updates", "legacy", "alerts", "preferences"
property var conversation: []
property bool busy: false
@ -207,14 +210,54 @@ ShellRoot {
});
}
function showPanel() {
shell.panelOpen = true;
focusTimer.start();
}
IpcHandler {
target: "panel"
function toggle(): string {
if (shell.panelOpen)
shell.panelOpen = false;
else
shell.showPanel();
return shell.panelOpen ? "shown" : "hidden";
}
function open(): string {
shell.showPanel();
return "shown";
}
}
Timer {
id: focusTimer
interval: 120
onTriggered: {
if (shell.panelOpen) {
window.requestActivate();
promptField.forceActiveFocus();
}
}
}
FloatingWindow {
id: window
title: "Phoebus Assistant"
color: "transparent"
visible: shell.panelOpen
// Default fits 1024x768 and 1280x720. Content areas scroll at
// smaller window sizes and increased UI scale.
implicitWidth: 820
implicitHeight: 640
implicitWidth: 900
implicitHeight: 650
Component.onCompleted: focusTimer.start()
Shortcut {
sequence: "Escape"
context: Qt.WindowShortcut
onActivated: shell.panelOpen = false
}
// FloatingWindow has no palette property. A Control provides an
// inherited palette for the Qt Quick Controls inside this window.
Control {
@ -272,11 +315,12 @@ ShellRoot {
label: shell.themeMode === "dark" ? "Light mode" : "Dark mode"
onClicked: shell.toggleTheme()
}
}
// Tab buttons scroll horizontally instead of overflowing
// at 1024x768, 1280x720 or increased UI scale.
// Keep tabs on their own row so the header never pushes them
// outside a compact scratchpad window.
Flickable {
Layout.preferredWidth: Math.min(420, parent.width * 0.55)
Layout.fillWidth: true
Layout.preferredHeight: 40
contentWidth: tabRow.width
contentHeight: 40
@ -328,7 +372,6 @@ ShellRoot {
}
}
}
}
// Truthful connection bar: when no model is connected, show a
// setup action and the real error — never a false "Connected",
@ -352,6 +395,7 @@ ShellRoot {
Label {
Layout.fillWidth: true
Layout.minimumWidth: 0
wrapMode: Text.Wrap
text: shell.bridgeConnecting ? "Connecting to the assistant broker…" : (AssistantBridge.ready ? ("No AI model is connected" + (shell.aiError ? ": " + shell.aiError : ". Connect a provider or use Legacy Admin.")) : "The assistant broker is not running.")
color: Theme.text
@ -598,6 +642,7 @@ ShellRoot {
TextField {
id: promptField
Layout.fillWidth: true
Layout.minimumWidth: 0
placeholderText: "Ask Phoebus... (e.g. Install Firefox, Show updates, Check audio)"
color: Theme.text
placeholderTextColor: Theme.muted

View file

@ -0,0 +1,32 @@
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
<title>Phoebus OS Help</title>
<style>
:root{color-scheme:dark;font:16px/1.6 system-ui,sans-serif;background:#14161c;color:#e5e7eb}
body{margin:0}header{background:#20242c;border-bottom:1px solid #3b414d;padding:2rem max(1.5rem,calc((100vw - 1100px)/2))}h1{margin:0;color:#f5b942;font-size:2.25rem}header p{margin:.4rem 0 0;color:#b7bdc8}main{max-width:1100px;margin:auto;padding:1.5rem;display:grid;grid-template-columns:220px 1fr;gap:2rem}nav{position:sticky;top:1rem;align-self:start}nav a{display:block;padding:.3rem 0}article{min-width:0}section{padding-bottom:1.5rem;border-bottom:1px solid #3b414d}h2{color:#f5b942;margin-top:1.5rem}h3{color:#eecb80}a{color:#a9d7f8}code,kbd{background:#292f3a;border-radius:4px;padding:.1rem .35rem;color:#f8dfa1}pre{background:#20242c;border-radius:8px;padding:1rem;overflow:auto}pre code{background:none;padding:0}table{border-collapse:collapse;width:100%}th,td{text-align:left;vertical-align:top;border-bottom:1px solid #3b414d;padding:.5rem}th{color:#f5b942}.note{background:#272e37;border-left:3px solid #f5b942;padding:.7rem 1rem;border-radius:4px}@media(max-width:700px){main{display:block}nav{position:static;columns:2;border-bottom:1px solid #3b414d;padding-bottom:1rem}}
</style>
</head>
<body><header><h1>Phoebus OS Help</h1><p>A practical, offline guide to the desktop, packages, recovery, and shortcuts.</p></header>
<main><nav aria-label="Contents"><a href="#start">Getting started</a><a href="#desktop">Desktop controls</a><a href="#keys">Keybinding cheat sheet</a><a href="#packages">Apps and packages</a><a href="#assistant">Assistant and models</a><a href="#updates">Updates and recovery</a><a href="#settings">Settings and displays</a><a href="#troubleshooting">Troubleshooting</a></nav><article>
<section id="start"><h2>Getting started</h2><p>Phoebus is a Gentoo workstation with the Mango Wayland compositor, DankMaterialShell (DMS), Portage, Flatpak, and Nix. The system remains usable offline after installation. The terminal tool <code>sys</code> is the shared interface for package management and system administration.</p><p>Open <strong>Phoebus Welcome</strong> from the app launcher or press <kbd>Super</kbd>+<kbd>Shift</kbd>+<kbd>W</kbd>. Open the original <strong>DMS Welcome</strong> from the launcher or press <kbd>Super</kbd>+<kbd>Alt</kbd>+<kbd>W</kbd>. Press <kbd>Super</kbd>+<kbd>F1</kbd> to reopen this guide.</p><p class="note">“Super” is usually the Windows or Command key. Settings and Welcome are regular windows; the Assistant is a floating scratchpad.</p></section>
<section id="desktop"><h2>Desktop controls</h2><p>The top bar holds the app launcher and workspaces on the left, clock and optional weather in the center, and system controls on the right. Click the right side for clipboard, process list, notifications, volume, connectivity, and quick settings. Click the clock for the calendar. Some controls appear only when the corresponding device or service exists.</p><p>Open the app launcher with <kbd>Super</kbd>+<kbd>Space</kbd> or <kbd>Super</kbd>+<kbd>P</kbd>. Type an app or command and press Enter. Press Escape to dismiss a panel. Open DMS Settings from the launcher or <kbd>Super</kbd>+<kbd>Ctrl</kbd>+<kbd>,</kbd>.</p></section>
<section id="keys"><h2>Keybinding cheat sheet</h2><table><thead><tr><th>Keys</th><th>Action</th></tr></thead><tbody>
<tr><td><kbd>Super</kbd>+<kbd>Shift</kbd>+<kbd>Enter</kbd></td><td>Terminal</td></tr><tr><td><kbd>Super</kbd>+<kbd>Space</kbd> or <kbd>Super</kbd>+<kbd>P</kbd></td><td>App launcher</td></tr><tr><td><kbd>Super</kbd>+<kbd>A</kbd></td><td>Show or hide Phoebus Assistant</td></tr><tr><td><kbd>Super</kbd>+<kbd>F1</kbd></td><td>Phoebus Help</td></tr><tr><td><kbd>Super</kbd>+<kbd>Shift</kbd>+<kbd>W</kbd> / <kbd>Super</kbd>+<kbd>Alt</kbd>+<kbd>W</kbd></td><td>Phoebus Welcome / DMS Welcome</td></tr><tr><td><kbd>Super</kbd>+<kbd>Ctrl</kbd>+<kbd>,</kbd></td><td>DMS Settings</td></tr><tr><td><kbd>Super</kbd>+<kbd>V</kbd> / <kbd>Super</kbd>+<kbd>N</kbd></td><td>Clipboard history / notifications</td></tr><tr><td><kbd>Super</kbd>+<kbd>Ctrl</kbd>+<kbd>M</kbd></td><td>Process list</td></tr><tr><td><kbd>Super</kbd>+<kbd>Alt</kbd>+<kbd>L</kbd></td><td>Lock screen</td></tr>
<tr><td><kbd>Super</kbd>+<kbd>1</kbd>…<kbd>9</kbd></td><td>Switch workspace</td></tr><tr><td><kbd>Super</kbd>+<kbd>Shift</kbd>+<kbd>1</kbd>…<kbd>9</kbd></td><td>Move focused window to workspace</td></tr><tr><td><kbd>Super</kbd>+<kbd>Tab</kbd></td><td>Previous workspace</td></tr><tr><td><kbd>Super</kbd>+<kbd>J</kbd>/<kbd>K</kbd> or arrow keys</td><td>Focus another window</td></tr><tr><td><kbd>Super</kbd>+<kbd>Shift</kbd>+<kbd>J</kbd>/<kbd>K</kbd> or arrow keys</td><td>Swap focused window</td></tr><tr><td><kbd>Super</kbd>+<kbd>H</kbd>/<kbd>L</kbd></td><td>Shrink / grow master area</td></tr><tr><td><kbd>Super</kbd>+<kbd>I</kbd>/<kbd>D</kbd></td><td>Add / remove a master window</td></tr><tr><td><kbd>Super</kbd>+<kbd>Enter</kbd></td><td>Swap focused window with master</td></tr><tr><td><kbd>Super</kbd>+<kbd>T</kbd>/<kbd>M</kbd></td><td>Tile / monocle layout</td></tr><tr><td><kbd>Super</kbd>+<kbd>F</kbd></td><td>Toggle fullscreen</td></tr><tr><td><kbd>Super</kbd>+<kbd>Shift</kbd>+<kbd>Space</kbd></td><td>Toggle floating</td></tr><tr><td><kbd>Super</kbd>+<kbd>Shift</kbd>+<kbd>C</kbd></td><td>Close focused window</td></tr><tr><td><kbd>Super</kbd>+<kbd>R</kbd></td><td>Reload Mango configuration</td></tr><tr><td><kbd>Super</kbd>+drag left/right mouse button</td><td>Move / resize a floating window</td></tr><tr><td><kbd>Super</kbd>+<kbd>Shift</kbd>+<kbd>F9</kbd>…<kbd>F12</kbd></td><td>Switch display resolution (1024×768, 1280×768, 1440×900, 1920×1080)</td></tr>
</tbody></table><p>Advanced bindings also include <kbd>Super</kbd>+<kbd>Ctrl</kbd>+number to add a workspace to the view, <kbd>Super</kbd>+<kbd>Ctrl</kbd>+<kbd>Shift</kbd>+number to toggle a window tag, <kbd>Super</kbd>+comma/period to focus another monitor, and <kbd>Super</kbd>+<kbd>Shift</kbd>+comma/period to move a window there. <kbd>Super</kbd>+<kbd>Shift</kbd>+<kbd>E</kbd> exits the desktop session.</p></section>
<section id="packages"><h2>Apps and packages</h2><p>Run <code>sys --help</code> for the full command reference. Plain <code>sys</code> commands use the connected model; <code>--legacy</code> uses deterministic actions and works without a model. A package source flag selects exactly one lane. Operations show a review before mutation and may require administrator authentication.</p><pre><code>sys search firefox --legacy
sys search firefox --legacy --flatpak
sys install firefox --legacy --flatpak
sys install cmatrix --legacy --nix
sys install app-editors/vim --legacy --portage
sys remove firefox --legacy --flatpak
sys updates --legacy
sudo sys apply updates --legacy
sys history --legacy</code></pre><p>Available sources include Portage, Flatpak, Nix, Snap when snapd is installed, managed AppImages, and custom ebuilds. Search a lane first when the name is uncertain. A lane that is unavailable reports why; package management never silently switches sources. Portage, Flatpak, and other backend progress stays visible while work runs.</p></section>
<section id="assistant"><h2>Assistant and models</h2><p>Press <kbd>Super</kbd>+<kbd>A</kbd> to show or hide the Assistant without losing its conversation. The Assistant proposes typed system actions. Review and authenticate any change yourself; the model does not receive a root shell. Its Updates, Legacy, Alerts, and Preferences tabs give direct access to the same system capabilities. If no model is connected, use <code>sys --legacy</code> and the Legacy tab.</p><p>Model connection is configured through Phoebus setup or assistant preferences. Keep provider tokens in the supported secret storage; never paste them into a package request or terminal history.</p></section>
<section id="updates"><h2>Updates and recovery</h2><p>Use <code>sys updates --legacy</code> to inspect available updates and <code>sudo sys apply updates --legacy</code> to review and apply them. <code>sys history --legacy</code> lists recorded actions. <code>sys undo status --legacy</code> shows recovery state; <code>sudo sys undo --legacy</code> begins a reviewed undo where available. Snapshots protect high risk operations, but complete Btrfs rollback is still under development. Keep regular backups of personal files.</p><p>For boot trouble, select the known good kernel from the boot menu. Phoebus uses UEFI, LUKS2 encryption, Btrfs, and systemd; do not erase or reformat disks while diagnosing a boot issue.</p></section>
<section id="settings"><h2>Settings and displays</h2><p>DMS Settings controls appearance, bar, widgets, display, input, audio, notifications, network, and session options. On a virtual machine, resize the viewer first; use the display page if the guest resolution does not follow. The resolution shortcuts above offer an immediate fallback. Wallpaper files live in <code>~/Pictures/Wallpapers</code>; DMS can choose one from its Wallpaper page.</p><p>Changes to your personal Mango config live under <code>~/.config/mango/</code>. The packaged defaults are copied only for a new account, so updates preserve your custom bindings.</p></section>
<section id="troubleshooting"><h2>Troubleshooting</h2><p>If the bar or a panel does not appear, run <code>dms ipc call settings focusOrToggle</code> from a terminal to check whether DMS responds. Reopen the Assistant with <kbd>Super</kbd>+<kbd>A</kbd>. To inspect the compositor, run <code>mmsg get all-clients</code> in a Wayland terminal. For package errors, run the same <code>sys</code> command in a terminal to read its status and backend output. <code>sys --help</code> and <code>dms ipc --help</code> list current commands.</p><p>This guide is stored on the local system at <code>/usr/share/phoebus/help/index.html</code> and remains available without network access.</p></section>
</article></main></body></html>

View file

@ -297,8 +297,7 @@ ShellRoot {
PhoebusButton {
label: "Network"
compact: page.compactView
onClicked: shell.run(["sh", "-c",
"command -v dms >/dev/null && exec dms ipc call settings focusOrToggle || exec kitty -e sh -c 'nmcli device status; read -r _'"])
onClicked: shell.run(["dms", "ipc", "call", "settings", "openWith", "network_status"])
}
PhoebusButton {
label: "Display resolution"
@ -309,16 +308,25 @@ ShellRoot {
}
}
PhoebusButton {
label: "Accessibility"
label: "Text & motion"
compact: page.compactView
onClicked: shell.run(["sh", "-c",
"command -v dms >/dev/null && dms ipc call settings focusOrToggle || true"])
onClicked: shell.run(["dms", "ipc", "call", "settings", "openWith", "typography"])
}
PhoebusButton {
label: "Phoebus Help"
compact: page.compactView
onClicked: shell.run(["/usr/local/bin/phoebus-help"])
}
PhoebusButton {
label: "Installation help"
compact: page.compactView
onClicked: shell.run(["sh", "-c",
"kitty -e sh -c 'cat /usr/share/phoebus/install-help.txt 2>/dev/null || echo Help is not installed; read -r || true'"])
onClicked: shell.run(["kitty", "-e", "sh", "-c",
"cat /usr/share/phoebus/install-help.txt; printf '\\nPress Enter to close'; read -r _"])
}
PhoebusButton {
label: "DMS Welcome"
compact: page.compactView
onClicked: shell.run(["dms", "ipc", "call", "welcome", "open"])
}
PhoebusButton {
label: "Power"
@ -366,22 +374,22 @@ ShellRoot {
PhoebusButton {
label: "System log"
compact: true
onClicked: shell.run(["kitty", "-e", "sh", "-c", "journalctl -b --no-pager | less; read -r _"])
onClicked: shell.run(["kitty", "-e", "sh", "-c", "journalctl -b --no-pager | less; printf '\\nPress Enter to close'; read -r _"])
}
PhoebusButton {
label: "Installer log"
compact: true
onClicked: shell.run(["kitty", "-e", "sh", "-c", "tail -n 200 /var/log/phoebus-installer/install.log 2>/dev/null | less; read -r _"])
onClicked: shell.run(["kitty", "-e", "sh", "-c", "if [ -s /var/log/phoebus-installer/install.log ]; then less /var/log/phoebus-installer/install.log; else printf 'No installer log yet. Start the installer to create it.\\n'; fi; printf '\\nPress Enter to close'; read -r _"])
}
PhoebusButton {
label: "Disk information"
compact: true
onClicked: shell.run(["kitty", "-e", "sh", "-c", "lsblk -o NAME,SIZE,MODEL,TYPE,MOUNTPOINTS; read -r _"])
onClicked: shell.run(["kitty", "-e", "sh", "-c", "lsblk -o NAME,SIZE,MODEL,TYPE,MOUNTPOINTS; printf '\\nPress Enter to close'; read -r _"])
}
PhoebusButton {
label: "Network settings"
compact: true
onClicked: shell.run(["sh", "-c", "command -v dms >/dev/null && exec dms ipc call settings focusOrToggle || exec kitty -e sh -c 'nmcli device status; read -r _'"])
onClicked: shell.run(["dms", "ipc", "call", "settings", "openWith", "network_status"])
}
}
}
@ -469,7 +477,7 @@ ShellRoot {
compact: true
onClicked: {
shell.showDisplay = false;
shell.run(["sh", "-c", "command -v dms >/dev/null && dms ipc call settings focusOrToggle"]);
shell.run(["dms", "ipc", "call", "settings", "openWith", "display_config"]);
}
}
PhoebusButton {

View file

@ -74,6 +74,8 @@ qml6-module-qtquick-controls
qml6-module-qtquick-layouts
kitty
foot
firefox-esr
xdg-utils
wayland-utils
wlr-randr
wtype