phoebus_os/installer/live/desktop/phoebus-help/index.html
Phoebus be6910c62d
Some checks are pending
ci / test (push) Waiting to run
feat(desktop): open Phoebus Updates through sys
2026-10-02 04:20:34 -07:00

32 lines
11 KiB
Bash
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!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>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
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>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>