Make Troubleshooting a user's page; move the engineering history out
Troubleshooting had become a development changelog — bugs *we* hit, told as
history, with commit hashes and the internal test rigs used to find them. That
is not what someone reaches for when their machine is misbehaving, and a lot of
it described one particular machine rather than the system.
Troubleshooting is now symptom-first and about the reader's computer: no sound
from event sounds, an installed cursor theme that won't appear, a giant pointer
in one app, the bar gone, a widget eating clicks, games on the wrong monitor,
black screen after suspend, being locked out with no VT, pacman 404s, a module
that won't load after a kernel upgrade, the AI not answering, Secure Boot
enrollment, a LUKS header you didn't back up. Each entry says what to run.
The engineering material moves to a new Development-Notes page, which keeps the
generalisable rules — a commit is not an install, dkms status is not a health
check, /etc units shadow /usr/lib ones, signal dispositions survive exec,
tightening a check must handle the values already sitting on the wrong side —
without the narrative or the machine it happened on.
Also removed personal and machine-specific detail from the pages added in
ae733c0: a named USB volume knob, downloaded archive names, which apps had which
shadow, screen widths, monitor names, and the private-desktop state that
prompted the sound-theme fix. The rules they illustrate all still stand on their
own, stated generally. The one home path in Building-and-Packaging is now $HOME.
Fixed two dead anchors that predate this batch (synui#game-mode and
synui#task-manager pointed at bold text, not headings) and verified every
internal link and cross-page anchor resolves.
synapd: document AMD/Intel Vulkan GPU backend
Add the per-backend package table (synapse-llama / -cuda / -vulkan), note
Vulkan as the portable AMD/Intel choice (one build, all cards, ROCm opt-in),
and extend the 'verify it' grep to cover the Vulkan libraries.
Document SynapseOS commands + the sudo -n privileged desktop actions
New Commands page: the syn* CLI surface plus the scoped NOPASSWD sudoers
rules (power-menu, synapd-gamemode, synapd-backend) that let synui, running
as the session user with no polkit agent, do the few things needing root.
Add the synapd-backend / AI-backend row to synapd.md and link from the sidebar.
wiki: initial operator's manual
Ten pages: installation, keybindings, architecture, per-component pages
(synapd, synui, synguard+kmod, synsh), Secure Boot, building/packaging,
cutting an ISO release, and a troubleshooting catalogue.
The wiki deliberately carries what the README cannot: the failure modes.
Nearly every hard bug in this project has been SILENT — a build that exits 0
on stale code, a dkms module that reports installed while being unloadable, a
security rule that reports clean because it was reading garbage. Those are
written down here with the generalisable lesson attached.