diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index 4742241..6974d9d 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -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 diff --git a/docs/HANDOFF.md b/docs/HANDOFF.md index 4426152..e4b4ca0 100644 --- a/docs/HANDOFF.md +++ b/docs/HANDOFF.md @@ -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 diff --git a/docs/STATUS.md b/docs/STATUS.md index 9a2801a..5cdb754 100644 --- a/docs/STATUS.md +++ b/docs/STATUS.md @@ -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 diff --git a/installer-rs/crates/phoebus-core/src/system.rs b/installer-rs/crates/phoebus-core/src/system.rs index f2a20b6..eb5adb5 100644 --- a/installer-rs/crates/phoebus-core/src/system.rs +++ b/installer-rs/crates/phoebus-core/src/system.rs @@ -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#" Option { 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(), diff --git a/installer-rs/crates/phoebus-executor/src/desktop.rs b/installer-rs/crates/phoebus-executor/src/desktop.rs index aa2a1ea..2353687 100644 --- a/installer-rs/crates/phoebus-executor/src/desktop.rs +++ b/installer-rs/crates/phoebus-executor/src/desktop.rs @@ -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}"); + } } } diff --git a/installer-rs/crates/phoebus-installer/tests/live_iso.rs b/installer-rs/crates/phoebus-installer/tests/live_iso.rs index 01e85a2..e856aad 100644 --- a/installer-rs/crates/phoebus-installer/tests/live_iso.rs +++ b/installer-rs/crates/phoebus-installer/tests/live_iso.rs @@ -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" diff --git a/installer/live/build.sh b/installer/live/build.sh index f51cb25..f0acb4f 100755 --- a/installer/live/build.sh +++ b/installer/live/build.sh @@ -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 \ diff --git a/installer/live/desktop/phoebus-assistant/shell.qml b/installer/live/desktop/phoebus-assistant/shell.qml index da93f71..a8e82fb 100644 --- a/installer/live/desktop/phoebus-assistant/shell.qml +++ b/installer/live/desktop/phoebus-assistant/shell.qml @@ -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,17 +315,18 @@ 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. - Flickable { - Layout.preferredWidth: Math.min(420, parent.width * 0.55) - Layout.preferredHeight: 40 - contentWidth: tabRow.width - contentHeight: 40 - clip: true - flickableDirection: Flickable.HorizontalFlick - boundsBehavior: Flickable.StopAtBounds + // Keep tabs on their own row so the header never pushes them + // outside a compact scratchpad window. + Flickable { + Layout.fillWidth: true + Layout.preferredHeight: 40 + contentWidth: tabRow.width + contentHeight: 40 + clip: true + flickableDirection: Flickable.HorizontalFlick + boundsBehavior: Flickable.StopAtBounds RowLayout { id: tabRow @@ -327,7 +371,6 @@ ShellRoot { } } } - } } // Truthful connection bar: when no model is connected, show a @@ -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 diff --git a/installer/live/desktop/phoebus-help/index.html b/installer/live/desktop/phoebus-help/index.html new file mode 100644 index 0000000..6c84199 --- /dev/null +++ b/installer/live/desktop/phoebus-help/index.html @@ -0,0 +1,32 @@ + + + + +Phoebus OS Help + + +

Phoebus OS Help

A practical, offline guide to the desktop, packages, recovery, and shortcuts.

+
+

Getting started

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 sys is the shared interface for package management and system administration.

Open Phoebus Welcome from the app launcher or press Super+Shift+W. Open the original DMS Welcome from the launcher or press Super+Alt+W. Press Super+F1 to reopen this guide.

“Super” is usually the Windows or Command key. Settings and Welcome are regular windows; the Assistant is a floating scratchpad.

+

Desktop controls

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.

Open the app launcher with Super+Space or Super+P. Type an app or command and press Enter. Press Escape to dismiss a panel. Open DMS Settings from the launcher or Super+Ctrl+,.

+

Keybinding cheat sheet

+ + +
KeysAction
Super+Shift+EnterTerminal
Super+Space or Super+PApp launcher
Super+AShow or hide Phoebus Assistant
Super+F1Phoebus Help
Super+Shift+W / Super+Alt+WPhoebus Welcome / DMS Welcome
Super+Ctrl+,DMS Settings
Super+V / Super+NClipboard history / notifications
Super+Ctrl+MProcess list
Super+Alt+LLock screen
Super+1…9Switch workspace
Super+Shift+1…9Move focused window to workspace
Super+TabPrevious workspace
Super+J/K or arrow keysFocus another window
Super+Shift+J/K or arrow keysSwap focused window
Super+H/LShrink / grow master area
Super+I/DAdd / remove a master window
Super+EnterSwap focused window with master
Super+T/MTile / monocle layout
Super+FToggle fullscreen
Super+Shift+SpaceToggle floating
Super+Shift+CClose focused window
Super+RReload Mango configuration
Super+drag left/right mouse buttonMove / resize a floating window
Super+Shift+F9…F12Switch display resolution (1024×768, 1280×768, 1440×900, 1920×1080)

Advanced bindings also include Super+Ctrl+number to add a workspace to the view, Super+Ctrl+Shift+number to toggle a window tag, Super+comma/period to focus another monitor, and Super+Shift+comma/period to move a window there. Super+Shift+E exits the desktop session.

+

Apps and packages

Run sys --help for the full command reference. Plain sys commands use the connected model; --legacy 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.

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

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.

+

Assistant and models

Press Super+A 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 sys --legacy and the Legacy tab.

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.

+

Updates and recovery

Use sys updates --legacy to inspect available updates and sudo sys apply updates --legacy to review and apply them. sys history --legacy lists recorded actions. sys undo status --legacy shows recovery state; sudo sys undo --legacy 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.

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.

+

Settings and displays

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 ~/Pictures/Wallpapers; DMS can choose one from its Wallpaper page.

Changes to your personal Mango config live under ~/.config/mango/. The packaged defaults are copied only for a new account, so updates preserve your custom bindings.

+

Troubleshooting

If the bar or a panel does not appear, run dms ipc call settings focusOrToggle from a terminal to check whether DMS responds. Reopen the Assistant with Super+A. To inspect the compositor, run mmsg get all-clients in a Wayland terminal. For package errors, run the same sys command in a terminal to read its status and backend output. sys --help and dms ipc --help list current commands.

This guide is stored on the local system at /usr/share/phoebus/help/index.html and remains available without network access.

+
diff --git a/installer/live/desktop/phoebus-welcome/shell.qml b/installer/live/desktop/phoebus-welcome/shell.qml index 1d2f42f..a5f4a4c 100644 --- a/installer/live/desktop/phoebus-welcome/shell.qml +++ b/installer/live/desktop/phoebus-welcome/shell.qml @@ -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 { diff --git a/installer/live/live-packages.list b/installer/live/live-packages.list index 98ad319..9e6d6ef 100644 --- a/installer/live/live-packages.list +++ b/installer/live/live-packages.list @@ -74,6 +74,8 @@ qml6-module-qtquick-controls qml6-module-qtquick-layouts kitty foot +firefox-esr +xdg-utils wayland-utils wlr-randr wtype