feat(desktop): open Phoebus Updates through sys
Some checks are pending
ci / test (push) Waiting to run

This commit is contained in:
Phoebus 2026-10-02 04:20:34 -07:00
parent 42cba06b61
commit be6910c62d
10 changed files with 168 additions and 13 deletions

View file

@ -5,6 +5,15 @@ this file is the curated, human-readable summary.
## Unreleased — Fast defaults with user-controlled source builds
- **Phoebus Updates entry point (2026-10-02).** The launcher and Super+U now
open the Assistant's update view directly, including without an AI model.
Its Apply action opens the existing interactive `sys` update flow in Kitty,
where the exact Portage/Flatpak/Snap plan is reviewed and command progress
remains visible. DMS stays an ordinary Gentoo package updated by Portage;
no DMS updater fork or patch is maintained. Existing Mango profiles gain
the shortcut once without replacing a user binding. The live image now
includes both Assistant and Updates desktop entries.
- **Frame and OS launcher logo defaults (2026-10-02).** New DMS profiles
start with the Frame layout and the OS logo on the bar and dock launcher
buttons. Existing profiles keep their layout and logo choices; DMS stores

View file

@ -3,6 +3,16 @@
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.
- **Phoebus Updates entry point (2026-10-02):** The Updates view now has a
dedicated launcher and Super+U shortcut, works without a connected model,
and opens the existing interactive `sys` apply flow in Kitty so review and
package progress stay visible. DMS itself is unchanged and updates through
Portage. A one-time Mango config migration adds the shortcut to existing
profiles unless Super+U is already bound. The live image now installs the
Assistant and Updates desktop entries. Host checks pass; the new graphical
flow still needs a fresh VM check when `make doctor`'s 20 GiB disk-space
gate is met (currently 10 GiB free).
- **Frame and OS launcher logo defaults (2026-10-02):** DMS 1.6.2's layout
picker sets `frameEnabled=true`; its launcher button logo uses
`launcherLogoMode=os` (and the dock uses `dockLauncherLogoMode=os`). The

View file

@ -48,6 +48,18 @@ disposable VM; `serial-driver.py recovery` now automates the same check.
## Matrix
Phoebus Updates entry point (2026-10-02): the installed and live desktops
provide a dedicated launcher and Super+U shortcut that open the Assistant's
Updates view without needing a connected model. Review & Apply launches
`sudo sys apply updates --legacy` in Kitty, retaining the existing typed
approval, snapshots and visible package output. DMS remains the Portage
package supplied by GURU and is included in normal Gentoo updates. The DMS
updater widget is absent from the default bar; custom user bar layouts are
preserved. The installed desktop entry has a provisioning test, and the
launcher script, desktop entry and Rust suite have host checks. A fresh
graphical ISO/install is not VM verified because `make doctor` reports 10 GiB
free versus the 20 GiB VM gate.
Frame and launcher defaults (2026-10-02): the session now seeds DMS 1.6.2's
`frameEnabled=true`, `launcherLogoMode=os`, and `dockLauncherLogoMode=os` only
when `settings.json` does not yet exist. DMS's sparse settings format makes

View file

@ -316,6 +316,13 @@ Every result distinguishes three honest states per lane: **unavailable**
Deterministic forms:
On the desktop, launch **Phoebus Updates** or press Super+U. The update view
checks sources without a model, and **Review & Apply** opens the same
interactive `sudo sys apply updates --legacy` flow in Kitty. Portage compiles
and other package progress stay visible through completion. DankMaterialShell
is updated as a normal Portage package; the default DMS bar does not use its
separate updater widget.
```sh
sys search firefox --legacy # every source
sys search firefox --legacy --flatpak # one source

View file

@ -1460,6 +1460,16 @@ if [ ! -e "$cursor_include_marker" ] && [ -w "$mango_conf" ]; then
: > "$cursor_include_marker"
fi
fi
# Older user configs do not receive new packaged shortcuts. Add this one
# once, while respecting a user's existing Super+U binding or later removal.
updates_binding_marker="$HOME/.config/mango/dms/.phoebus-updates-binding-v1"
if [ ! -e "$updates_binding_marker" ] && [ -w "$mango_conf" ]; then
if grep -Eiq '^[[:space:]]*bind=SUPER,u,' "$mango_conf"; then
: > "$updates_binding_marker"
elif printf '\n# Open Phoebus Updates.\nbind=SUPER,u,spawn,phoebus-assistant --updates\n' >> "$mango_conf"; then
: > "$updates_binding_marker"
fi
fi
# DMS manages these fragments; they must exist before Mango sources them.
for f in colors layout outputs cursor; do
[ -e "$HOME/.config/mango/dms/$f.conf" ] || : > "$HOME/.config/mango/dms/$f.conf"
@ -1882,6 +1892,7 @@ 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,u,spawn,phoebus-assistant --updates
bind=SUPER,F1,spawn,phoebus-help
bind=SUPER+SHIFT,w,spawn,phoebus-welcome --reopen
bind=SUPER+ALT,w,spawn,dms ipc call welcome open
@ -1915,10 +1926,37 @@ After=graphical-session.target
pub const PHOEBUS_ASSISTANT_SCRIPT: &str = r#"#!/bin/bash
# Open the Phoebus assistant. If graphical environment and quickshell are available,
# launch the desktop assistant GUI. Otherwise fall back to a terminal with `sys ask`.
# Variables in single-quoted bash -c arguments expand inside the Kitty child.
# shellcheck disable=SC2016
set -u
updates=false
case "${1:-}" in
"") ;;
--updates) updates=true ;;
--apply-updates)
if ! command -v kitty >/dev/null 2>&1; then
echo "phoebus-assistant: Kitty is required to show update progress" >&2
exit 1
fi
exec kitty --title "Phoebus Updates" -e bash -c '
sudo /usr/local/bin/sys apply updates --legacy
result=$?
printf "\nUpdate session finished (exit %s). Press Enter to close.\n" "$result"
read -r
exit "$result"
'
;;
*) echo "Usage: phoebus-assistant [--updates|--apply-updates]" >&2; exit 2 ;;
esac
if [ -n "${WAYLAND_DISPLAY:-}" ] || [ -n "${DISPLAY:-}" ]; then
if command -v quickshell >/dev/null 2>&1 \
&& [ -f /etc/xdg/quickshell/phoebus-assistant/shell.qml ]; then
if "$updates"; then
if quickshell ipc -c phoebus-assistant call panel updates >/dev/null 2>&1; then
exit 0
fi
PHOEBUS_ASSISTANT_START_TAB=updates exec quickshell --no-duplicate -c phoebus-assistant
fi
# 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
@ -1927,6 +1965,15 @@ if [ -n "${WAYLAND_DISPLAY:-}" ] || [ -n "${DISPLAY:-}" ]; then
fi
fi
if command -v kitty >/dev/null 2>&1; then
if "$updates"; then
exec kitty --title "Phoebus Updates" -e bash -c '
/usr/local/bin/sys updates --legacy
result=$?
printf "\nUpdate check finished (exit %s). Press Enter to close.\n" "$result"
read -r
exit "$result"
'
fi
exec kitty --title "Phoebus Assistant" -e bash -lc \
'read -rp "Phoebus assistant request: " r; sudo sys ask "$r"; \
echo; read -rp "Press Enter to close"'
@ -1946,6 +1993,17 @@ Categories=System;Settings;
Keywords=system;admin;assistant;ai;sys;install;update;
"#;
pub const PHOEBUS_UPDATES_DESKTOP_ENTRY: &str = r#"[Desktop Entry]
Name=Phoebus Updates
Comment=Review and apply system and application updates
Exec=/usr/local/bin/phoebus-assistant --updates
Icon=software-update-available
Terminal=false
Type=Application
Categories=System;
Keywords=updates;portage;flatpak;snap;sys;
"#;
pub const PHOEBUS_HELP_SCRIPT: &str = r#"#!/bin/bash
set -u
page=/usr/share/phoebus/help/index.html
@ -2610,6 +2668,8 @@ 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(),
"assistant-desktop" => PHOEBUS_ASSISTANT_DESKTOP_ENTRY.to_string(),
"updates-desktop" => PHOEBUS_UPDATES_DESKTOP_ENTRY.to_string(),
"help" => PHOEBUS_HELP_SCRIPT.to_string(),
"help-html" => {
include_str!("../../../../installer/live/desktop/phoebus-help/index.html").to_string()

View file

@ -97,6 +97,11 @@ pub fn write_session_script(exec: &Exec, config: &InstallConfig) -> Result<()> {
"usr/share/applications/phoebus-assistant.desktop",
sysgen::PHOEBUS_ASSISTANT_DESKTOP_ENTRY,
)?;
write_public(
&target,
"usr/share/applications/phoebus-updates.desktop",
sysgen::PHOEBUS_UPDATES_DESKTOP_ENTRY,
)?;
write_script(
&target,
@ -1101,6 +1106,10 @@ mod tests {
.root
.join("usr/share/applications/phoebus-assistant.desktop")
.is_file());
assert!(exec
.root
.join("usr/share/applications/phoebus-updates.desktop")
.is_file());
assert!(exec
.root
.join("etc/xdg/quickshell/phoebus-assistant/shell.qml")

View file

@ -150,6 +150,27 @@ fn failure_to_create_the_socket_is_reported() {
assert!(fixture.read("helpers.log").is_empty());
}
#[test]
fn existing_mango_profiles_gain_updates_shortcut_once_and_keep_custom_bindings() {
let fixture = Fixture::new(MANGO_FAIL);
let config = fixture.dir.path().join(".config/mango/config.conf");
std::fs::create_dir_all(config.parent().unwrap()).unwrap();
std::fs::write(&config, "bind=SUPER,a,spawn,phoebus-assistant\n").unwrap();
let _ = fixture.run();
let _ = fixture.run();
let content = std::fs::read_to_string(&config).unwrap();
assert_eq!(content.matches("bind=SUPER,u,").count(), 1);
let custom = Fixture::new(MANGO_FAIL);
let custom_config = custom.dir.path().join(".config/mango/config.conf");
std::fs::create_dir_all(custom_config.parent().unwrap()).unwrap();
std::fs::write(&custom_config, "bind=SUPER,u,spawn,my-updater\n").unwrap();
let _ = custom.run();
let custom_content = std::fs::read_to_string(&custom_config).unwrap();
assert!(custom_content.contains("bind=SUPER,u,spawn,my-updater"));
assert!(!custom_content.contains("bind=SUPER,u,spawn,phoebus-assistant"));
}
#[test]
fn first_login_seeds_wallpaper_folder_and_letter_avatar_without_replacing_choices() {
let fixture = Fixture::new(MANGO_OK);

View file

@ -99,7 +99,7 @@ echo "releases OK"
# ---------------------------------------------------------------------------
say "emit shared desktop assets"
assets=(
session-mango assistant help help-html help-desktop dms-welcome-desktop install welcome
session-mango assistant assistant-desktop updates-desktop 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,8 @@ 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 assistant-desktop /usr/share/applications/phoebus-assistant.desktop
install_asset updates-desktop /usr/share/applications/phoebus-updates.desktop
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

View file

@ -11,12 +11,13 @@ ShellRoot {
// 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 string currentTab: Quickshell.env("PHOEBUS_ASSISTANT_START_TAB") === "updates" ? "updates" : "assistant"
property var conversation: []
property bool busy: false
property string statusText: "Ready"
property var activeAlerts: []
property var updateOverview: null
property string updateError: ""
property var preferences: null
// Truthful model connection: never "Connected" solely because the bridge
// process started. `aiConfigured` follows the handshake's ai_configured.
@ -46,6 +47,8 @@ ShellRoot {
shell.aiConfigured = !!result.ai_configured;
shell.aiBackend = result.ai_backend || "direct";
shell.aiError = "";
if (shell.currentTab === "updates")
shell.checkUpdates();
AssistantBridge.getProactiveAlerts(reply => {
if (reply.ok && reply.result)
shell.activeAlerts = reply.result.alerts || [];
@ -86,6 +89,8 @@ ShellRoot {
}
function checkUpdates() {
if (!AssistantBridge.ready)
return;
shell.busy = true;
shell.statusText = "Checking for updates across package sources...";
AssistantBridge.getUpdates(reply => {
@ -93,6 +98,9 @@ ShellRoot {
shell.statusText = "Ready";
if (reply.ok && reply.result) {
shell.updateOverview = reply.result;
shell.updateError = "";
} else {
shell.updateError = reply.error || "Could not check for updates.";
}
});
}
@ -230,6 +238,14 @@ ShellRoot {
shell.showPanel();
return "shown";
}
function updates(): string {
shell.currentTab = "updates";
shell.showPanel();
if (!shell.updateOverview && !shell.busy && AssistantBridge.ready)
shell.checkUpdates();
return "shown";
}
}
Timer {
@ -245,7 +261,7 @@ ShellRoot {
FloatingWindow {
id: window
title: "Phoebus Assistant"
title: shell.currentTab === "updates" ? "Phoebus Updates" : "Phoebus Assistant"
color: "transparent"
visible: shell.panelOpen
// Default fits 1024x768 and 1280x720. Content areas scroll at
@ -290,7 +306,7 @@ ShellRoot {
spacing: 12
Label {
text: "Phoebus Assistant"
text: shell.currentTab === "updates" ? "Phoebus Updates" : "Phoebus Assistant"
color: Theme.text
font.pixelSize: 18
font.bold: true
@ -300,11 +316,11 @@ ShellRoot {
Layout.preferredWidth: 8
Layout.preferredHeight: 8
radius: 4
color: shell.assistantConnected ? Theme.primary : Theme.warning
color: (shell.currentTab === "updates" ? AssistantBridge.ready : shell.assistantConnected) ? Theme.primary : Theme.warning
}
Label {
text: shell.assistantConnected ? "Connected (" + shell.aiBackend + ")" : (shell.bridgeConnecting ? "Connecting…" : (AssistantBridge.ready ? "Setup required" : "Offline"))
text: shell.currentTab === "updates" ? (AssistantBridge.ready ? "System broker ready" : "Connecting…") : (shell.assistantConnected ? "Connected (" + shell.aiBackend + ")" : (shell.bridgeConnecting ? "Connecting…" : (AssistantBridge.ready ? "Setup required" : "Offline")))
color: Theme.muted
font.pixelSize: 12
}
@ -378,7 +394,7 @@ ShellRoot {
// and never approval controls for an error.
Rectangle {
Layout.fillWidth: true
visible: !shell.assistantConnected
visible: !shell.assistantConnected && shell.currentTab === "assistant"
radius: 8
color: Theme.card
border.color: Theme.warning
@ -686,12 +702,19 @@ ShellRoot {
spacing: 12
Label {
text: "Unified Multi-Source Updates"
text: "System Updates"
color: Theme.text
font.pixelSize: 16
font.bold: true
}
Label {
Layout.fillWidth: true
text: shell.updateError || "Portage, Flatpak and Snap updates appear below using your current repository metadata. Review the exact plan in the terminal before approving it."
wrapMode: Text.WordWrap
color: shell.updateError ? Theme.warning : Theme.muted
}
ListView {
Layout.fillWidth: true
Layout.fillHeight: true
@ -751,12 +774,14 @@ ShellRoot {
Layout.fillWidth: true
PhoebusButton {
label: "Refresh Updates"
onClicked: refreshStatus()
actionEnabled: !shell.busy
onClicked: shell.checkUpdates()
}
PhoebusButton {
label: "Apply All Updates"
label: "Review & Apply"
primary: true
onClicked: shell.submitPrompt("update system")
actionEnabled: !shell.busy
onClicked: Quickshell.execDetached(["/usr/local/bin/phoebus-assistant", "--apply-updates"])
}
}
}

View file

@ -13,7 +13,7 @@ body{margin:0}header{background:#20242c;border-bottom:1px solid #3b414d;padding:
<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>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>U</kbd></td><td>Phoebus Updates</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
@ -26,7 +26,7 @@ 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="updates"><h2>Updates and recovery</h2><p>Open <strong>Phoebus Updates</strong> from the launcher or press <kbd>Super</kbd>+<kbd>U</kbd>. It checks Portage, Flatpak and Snap without a model. Portage checks use your last synced repository metadata; run <code>sudo emerge --sync</code> to discover newly published Gentoo and GURU packages. Choose <strong>Review &amp; Apply</strong> to open an interactive <code>sys</code> update in a terminal, review the exact plan and approve it. Package progress stays visible until you close the terminal. This keeps DankMaterialShell updated through Portage along with other Gentoo packages. Use Phoebus Updates for system updates; the separate updater page in DMS Settings does not manage Portage. Nix, managed AppImages and custom ebuilds have separate update paths. You can also use <code>sys updates --legacy</code> to inspect and <code>sudo sys apply updates --legacy</code> to review and apply. <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>