History

Document synfiles — it has been the default file manager and was in neither the wiki nor the README The gap the Antiquity credit left behind, again: synfiles replaced Dolphin as what a folder opens in, ships on the ISO and is in syn-update's components — and appeared on **no page a user reads**. The only mention of a file manager anywhere in this wiki was a Dolphin context-menu action and a Dolphin Troubleshooting entry. New **Files** page: the window (tabs, split view, the three view modes, thumbnails, tree, drag-and-drop), the keyboard, the trash and undo rules, properties including the new resolution row, service menus, places, volumes, archives, search, settings with their real defaults, `--rec` for scripts, and how to get Dolphin back. - _Sidebar and Home: Files listed under "Using it", beside Software. - Commands: a `synfiles` row; `synui-wine-run` is a right-click action in both file managers, not "a Dolphin context-menu action". - The Desktop: a short section pointing at the page, and what a desktop drop does. - Troubleshooting: which application opens a folder is decided by mimeapps.list and how to change it (including a folder opening in a terminal, which is the same mechanism with no entry set); the Dolphin "Open With" entry now says Files does not use that index; and no resolution for .mkv/.webm/.avi means ffmpeg is not installed. - Development Notes, two entries, both generalisable: - two renderings of one row are two places to forget — drag-and-drop and then rename were each wired into the list delegate only, and a control whose state is set but not drawn reads as a dead button; plus the reverse-paint-order rule for a row-wide MouseArea, and how to drive a quickshell app with no display (and why the probe must be run against the shipped file too). - a bounds check turns a wrong answer into no answer, which is how you find it — validate the parsed value, expect short reads, and decide a format by magic rather than by its extension. Both link checkers pass.

velle999 committed Aug 12, 2026

Software: document synpkg; retire shelly synpkg landed as the package manager and appeared on NO wiki page — the same gap the Antiquity shell had, where a shipped thing existed only in a PKGBUILD. New Software page: the five sources and what actually installs from each, the two that are off until you enable them, the everyday commands, and why a full upgrade and any AUR build open a terminal. shelly-bin is gone from the system, so it is gone from Updating's list of components syn-update cannot rebuild. Updating and Commands now name `synpkg upgrade` as the Arch-side half; plain pacman still works and the page says so.

velle999 committed Aug 9, 2026

Add a DaVinci Resolve page `syn resolve` had one row in Commands and a mention in Troubleshooting, both about `transcode`. The half that actually breaks installs was undocumented anywhere a user reads. The page covers what the AUR package already fixes (so nobody re-applies the guides by hand and fights it), the manual download and the AUR version-lag trap that fails deep in makepkg on a checksum naming neither cause, the OpenCL virtual-provider dependency — the usual reason Resolve installs cleanly and then refuses to start — the desktop-entry shadowing, and the codec limits with the transcode options in full. Two claims were checked against the running system rather than inferred, and both were wrong on the first pass: - the launch environment is not set by env lines in the desktop entry. The override rewrites `Exec=` to `syn resolve launch`, and that subcommand exports QT_QPA_PLATFORM=xcb and unsets QT_QPA_PLATFORMTHEME and QT_STYLE_OVERRIDE. Worth stating, because it means running that command by hand reproduces a menu launch exactly. - the AUR entry ships no `TryExec` at all. The rewrite being anchored to `^Exec=` is what protects one where it exists; the page now says that instead of implying the file has one. Linked from the sidebar, Home, Commands and the recording entries in Troubleshooting. Links and anchors check clean; the version numbers in the mismatch example are invented rather than a real download.

velle999 committed Aug 8, 2026

Screen recording, syn resolve, and credit for the Antiquity shell The Antiquity bar has shipped since 0.2.7 and was documented in neither the README nor here, which also meant diinki was uncredited in anything a user reads. The Desktop now covers both shells, `bar_shell`, and the fact that Antiquity is her work under MIT, with the Indian Type Foundry credit clause the bundled faces carry. Recording gained a constant frame rate and a `--edit` mezzanine mode, and `syn resolve` was never listed at all: - Commands: `syn resolve`, and what synui-record now does. - Troubleshooting: three symptom-first entries. The important one is that a recording refusing to open in DaVinci Resolve is not a broken file and not a missing codec — the free edition on Linux decodes neither H.264 nor AAC, so no package fixes it and `syn resolve transcode` is the answer. - Development Notes: two lessons. A container's "frame rate" may be its timebase, which is one field causing three unrelated-looking symptoms; and a validated argument is not a dispatched one, where a build script accepted a component name, built nothing and exited 0. - Building and Packaging: that is a fifth instance of the two-collectors drift, recorded next to the other four. Page links and cross-page anchors checked; nothing here names a machine.

velle999 committed Aug 8, 2026

Split synui into the user page and the contributor notes; niri in the layouts synui.md was three audiences stacked on one page: a feature list, ~85 lines of compositor internals, and a config section that mixed "how you configure this" with "change one, change all three". 217 lines down to 160, and the split is by reader rather than by topic. - Header said "Tiling + monocle layouts". There are five. It now names them and points at The-Desktop for what each does. - Features regrouped under Shell / Look / Hardware / AI and security so it can be skimmed, with a what-you-want table at the top. - Every pkgrel reference dropped (154, 163, 183, 192, 197). "Replaced waybar in pkgrel 154" is release history; a reader wants to know the bar is quickshell. - "Hard-won rules for working on synui" moved to Development Notes as "Compositor traps", which is where the cross-cutting ones already lived and where that page already pointed for them. - "Reset signal dispositions" was NOT moved: Development Notes already has "Inherited signal dispositions", same three burns, better written. It was a duplicate, so the page now cross-references instead. - "Session env vars live in three places" went with it — a contributor trap sitting in a user-facing config section. - The state-file rule got the practical form it was missing: if editing synuirc appears to do nothing, a panel has already written that setting. The-Desktop's layout TABLE still had four rows — the prose above it was fixed last time and the table was not, which is the half that gets read. niri now has a row and a section of its own: the strip, the two column moves, and why a column that does not fit is not drawn at all rather than cut off at the edge. Also corrects the geometry note. It said tiling and AI ignore remembered per-app geometry; layout_restore_geometry() gates on tiling, niri AND ai, so three layouts ignore it, not two. Page and anchor links checked.

velle999 committed Aug 7, 2026

Add a Nix page; document the niri keys and the shortcut palette Nix.md covers both halves of the optional Nix layer, and says up front which is which because they share a language and nothing else: - Nix + Home Manager beside pacman, for a declarative USER environment. Leads with what it is NOT: this is not NixOS, pacman still owns the system, and "declare the whole machine and rebuild it" is a different product. - facts.nix as the bridge — what the machine actually is, probed rather than remembered, so one home.nix reacts to the box instead of being edited per box. - Install profiles: syn-install --config, in Nix or key=value. Semantic keys rather than menu numbers, unused keys reported by name, and the destructive confirmations spelled out one at a time. The two traps get their own headings because both fail silently: managing synuirc from home.nix makes the control panel revert instead of save (Home Manager's files are read-only store symlinks; synui writes that file live), and /etc/synapseos/nix must not be a git repo (flakes copy only tracked files, so a fresh facts.nix evaluates as missing). Keybindings was missing four real binds — Super+/ (and Super+?), the palette that lists everything else, and Super+, / Super+. , the two column moves that are the whole point of the niri layout. Found by running synui's new tests/readme_binds.sh against this page instead of the README; it now passes against both. The-Desktop said four layouts and named four: niri is the fifth in the Super+Tab cycle. It also said the layout "is not remembered across a restart", which layout_state_save() and tests/layout_persist.sh have both contradicted for a while — it is per desktop and it persists. Page and anchor links checked.

velle999 committed Aug 7, 2026

Keybindings: the Super+Space swap toggle, and rofi theming

velle999 committed Aug 6, 2026

Keybindings: rofi on Super+Space, command bar to Super+= Also fixes two errors that predate this change: - Super+Shift+T was listed as Calendar in the System table while the Windows table correctly had it as Retile. It has been retile since 2026-07-31. - The rebinding example had a comma (`super+shift+z, spawn ...`). The line is split on the first whitespace, so the comma became part of the key name and the bind was silently dropped. Documented the punctuation-keysym rule too, since Super+= has to be written super+equal.

velle999 committed Aug 6, 2026

The Layout row is in the control panel too Super+C - Desktop - Layout, added in synui 231: reads the current layout and its desktop, Enter cycles it the same as Super+Tab. Worth naming in the Layouts section because the key is the harder way in if you have not already memorised it, and the control panel is meant to be the front door.

velle999 committed Jul 31, 2026

Document the four layouts and what monocle does Super+Tab had one wiki row (Cycle layout) and nothing anywhere explained the four layouts it cycles, so the most-pressed layout key on the system was also the least documented one. The-Desktop gains a Layouts section: the cycle order, that layout is per-desktop and resets at login, a table of the four, the floating/ maximize/snap trap that leaves a tiling desktop with nothing to tile, and a Monocle subsection - one window per monitor, change it with the normal focus keys, floating windows exempt (so Super+F is how you get two things on screen), not fullscreen, remembers per-app geometry. Keybindings: the Super+Tab row now names the cycle and says plainly that it does not switch windows, which is what it reads as next to Alt+Tab two rows above; adds the missing Super+Shift+T retile row. Development-Notes: two pieces of state that must agree, updated from only one side - the monocle visibility bug, why a bug that any later action masks reads as imagined, and deriving at the choke point rather than in each caller.

velle999 committed Jul 31, 2026

0.2.5 is out — the installer pages describe a shipped release now Both pages carried a "this is on main, build the ISO yourself" marker written while 0.2.4 was the newest published one. 0.2.5 is now Latest and contains all of it, so the markers say what an installed system HAS rather than what is coming: - Installation: the filesystem and bootloader choices, snapshots, ADVANCED and swap/zram are in 0.2.5; 0.2.4 and earlier had ERASE and ALONGSIDE only, ext4 and GRUB, and no swap of any kind. - synsh: kitty is new in 0.2.5, and an upgraded machine still keeps foot — nothing rewrites a user's synuirc. The 0.2.1 and 0.2.3 references elsewhere are historical and still true.

velle999 committed Jul 30, 2026

synguard: how to actually set up the BPF-LSM gate The enforcement section said the gate exists and what it cannot do, but not how to turn it on. Adds the operator path, in the order someone has to do it. - Confirm the kernel offers it: 'bpf' must appear in /sys/kernel/security/lsm (stock Arch has it), and it is LAST in that list on purpose — additive only. - Nothing ships armed: 55 rules, zero deny or quarantine verdicts. As installed synguard detects and alerts, it does not kill. - Which rules can lower, as a table. There is no fnmatch in a BPF program, so a pattern is an exact string or a prefix and synguard refuses anything else rather than approximating. Plus the ordering constraint that will bite first: first-match-wins means a deny rule only lowers when synguard can PROVE no earlier rule matches the same input, and the stock base rules open with allows at priority 1. - The exec gotcha: 'comm' is the process CALLING execve, not the binary being run, because the kernel has not installed the new name at that hook. - Arming is a separate decision from loading — the drop-in for --bpf-enforce, and what a loaded-but-unarmed rule looks like. - The five distinct bpf-lsm log lines, so each outcome is greppable. - The way out: synapse.bpf_enforce=0 on the kernel command line, plus the 30s warmup and the fail-open-on-crash behaviour that make a bad rule survivable. - Points at /etc/synguard/rules.d/40-enforce.rules.example for the long-form version, which ships on the system and parses as nothing until it is copied to .rules. Every flag, hook name, kernel parameter and log string checked against the source; the rule count and the zero-deny claim recounted rather than copied.

velle999 committed Jul 30, 2026

Document the installer rebuild, synguard enforcement, and kitty The wiki stopped at 2026-07-28 and the whole synguard-to-now range was undocumented. Installation.md still described a single ext4-and-GRUB installer that no longer exists. Installation — install modes now include ADVANCED (partition it yourself, then name the partitions), plus the filesystem table, the bootloader table and what each implies for the ESP, snapshots, swap and zram. Marked with what is actually published: 0.2.4 has ERASE/ALONGSIDE only, everything else is on main and needs a self-built ISO. synguard — the enforcement model had no page anywhere. Adds the two paths (post-hoc SIGKILL vs the in-kernel BPF-LSM gate) and why they are not equivalent, the mode/flag split, the four things the gate cannot do, the two cases where a DENY stands down, how to read the stats line, and how to test a deny rule without killing your own session. synsh — kitty is the default terminal; foot is kept as the CPU-rendered rescue. Includes the dynamic_background_opacity trap, which cannot be fixed after the fact. Terminal references updated across Commands, synui, Window-Effects and Gaming. Development Notes — five new entries, all from silent failures: systemd dependency lists are additive-only so a drop-in cannot remove one; socket-activated services resurrect a daemon you stopped, over the network; an indented heredoc terminator swallows code while bash -n passes; a prompt after a long step answers itself from typeahead; grep -q in a pipeline under pipefail makes "must be absent" checks pass vacuously.

velle999 committed Jul 30, 2026

Add Updating page for syn-update; surface it on the front page Installed systems could never receive a SynapseOS component update: the [synapseos] repo syn-install writes points at /var/cache/synapseos, which is copied off the ISO at install time and never written to again. pacman -Syu upgraded all of Arch and silently never saw a newer synui/synapd/synguard. syn-update fixes that, and ships on 0.2.3 — so it needs documenting before anyone upgrades into it. New Updating page: the two-command split against pacman -Syu, check/apply/ status, the build-from-source requirement and its cost, what is deliberately NOT updated this way and why, and a symptom-first troubleshooting section. Home: Updating added to Start here, plus a callout for anyone coming from a pre-0.2.3 ISO, since the old failure was silent and they have no reason to suspect it. Also filled two gaps where the front page had fallen behind the sidebar — Commands, and the TEPRIS/Nexus P2P app rows. Sidebar and Commands link to it.

velle999 committed Jul 28, 2026

wiki: wpengine is on the ISO, Super+E controls, TEPRIS + Nexus P2P pages linux-wallpaperengine ships on the ISO as of 0.2.1, so three pages saying otherwise are now actively wrong — Wallpapers told people to build a package they already have. Commands and the Wallpapers intro said "optional / not on the ISO". Window-Effects documented the config keys and gave the Super+E panel one sentence, even though the panel is how most people will actually touch any of this. Adds the two pages, the shared keys, and the part that is genuinely surprising: Space means different things per page — master on/off on the CRT page, but "toggle the switch governing this row" on the window page, so it lights the shadow from a greyed-out Shadow size row. Also that `s` saves only the page you are on, into separate files. New Apps pages for TEPRIS and Nexus P2P, both previously undocumented. Nexus P2P's leads with the thing a user must know before sharing a code — the code IS the password — and records why the code is not the MQTT topic: encrypting the payload is not enough if the envelope carries the secret. Written against the current launchers, not from notes: tepris deliberately does NOT use --kiosk any more (kiosk had no way out of fullscreen and no way to quit), which older notes still claimed.

velle999 committed Jul 27, 2026

Document wallpapers end to end, plus the mixer New Wallpapers page: the Super+W picker and its keys, per-monitor scoping and scaling modes, the wallpaper.state-over-synuirc rule, and the whole Wallpaper Engine path — how to get the package, every synui-wpengine command, the files and env vars, what renders and what doesn't, and why synui has to restart the engine after a suspend. Also: the bar's new mixer, wallpaper symptoms in Troubleshooting, the two generalisable lessons in Development Notes (a running process is not a working one; an flock belongs to the open file description), and Home's stale 0.1.x status line.

velle999 committed Jul 27, 2026

Add a Gaming page — game mode had no documentation anywhere Game mode existed as one line in a keybind table, one row in the sudo -n table, and a paragraph in synapd about VRAM. Nothing said what triggers it, what it stops, how to stop it stopping things, or that there is a launcher wrapper at all — and synui-game-run, the half that has to be in place BEFORE a game starts, was named once in a command list and never explained. The page covers both halves and, more usefully, why they are separate: game mode acts on a game that is already running, while MangoHud and the governor have to be wrapped around the launch, because you cannot inject an overlay into a process that is already up. Documented from the source rather than from memory: the detection rule (a fullscreen XWayland client, which works because desktop apps are Wayland- native and never match), what it stops and why synapd has to be stopped outright (the wire protocol has no unload or sleep, only RELOAD and SHUTDOWN), the idle hold-off and why a gamepad makes it necessary, the five default exclusions and the fullscreen-video surprise they exist to prevent, and the six synuirc keys with their real defaults. Also the things people actually hit: MANGOHUD=1 only hooks Vulkan so an OpenGL game needs the wrapper; the overlay ships hidden behind Shift_R+F12; gamescope is on the ISO but mangohud and gamemode are optdepends; borderless windowed is not fullscreen; a blank window at the right size is usually the game's own resolution index. Linked from Home, the sidebar, Keybindings, Commands and synui, which all previously dead-ended on the subject.

velle999 committed Jul 26, 2026

Correct the build flag table — the default is CPU, not GPU auto-detect The table said `(none)` gives a "full build, GPU auto-detected". It does not: build.sh initialises WITH_GPU=cpu, and the autodetect branch only runs on an explicit --gpu=auto. Following the old table would not have produced what it promised, and the failure mode is nasty — a CUDA build links the shipped libggml against the build host's driver stack, so synapd exits 127 on any machine without it, VMs included. That is a shipped-and-broken ISO, discovered by whoever boots it. Replaced with the real options, and added the note that the CPU build is a deliberate release choice rather than a limitation — plus the part that was missing entirely: the build also packages synapse-llama-cuda and synapse-llama-vulkan into the repo when the host has nvcc / glslc, so an installed machine can switch onto its GPU afterwards.

velle999 committed Jul 26, 2026

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.

velle999 committed Jul 26, 2026

Document the desktop: sounds, cursors, widgets, the bar and window effects The wiki was last touched at 0.1.8; everything since — the quickshell bar replacing waybar, the cursor and sound managers, desktop widgets and icons, the wlroots 0.20 / scenefx 0.5 port and the glass work — was undocumented. Four new pages: Sound-Themes synui-sound end to end: the ten events and where each is hooked, installing themes from an archive or a plain folder of .oga files, per-event sample picking, and why several spec names resolve to something else. Carries the ghost theme (/usr/share/sounds/alsa silenced a desktop whose switches all said "on") and the `volume` key collision. Cursor-Themes synui-cursor end to end, built around the thing that actually costs people time: opendesktop ships ready-to-use themes and source trees that look identical from outside. Plus the untrusted-archive handling, and the five places a cursor theme has to be written or the desktop disagrees. The-Desktop the bar (and why waybar went), widgets, desktop icons, themes, per-app geometry. Window-Effects the full synuirc knob reference with defaults and ranges, how to tell whose shadow you are looking at, the 50% shadow ceiling shadow_spread lifts, and the seam rule that made the glass halo square on top. Both installers are documented as installers of untrusted archives, because that is what they are: paths re-resolved against the extraction root, and `build` kept CLI-only since it runs the archive's own makefile as you. Keybindings was materially wrong — Super+T has been the theme manager since the task manager lost its second bind, and Alt+Tab, Super+S, Super+Shift+A, Super+Shift+P, Super+V, Super+R, Super+I and the bare media keys were all missing. Regenerated against the bind table in config.c, with the note that a duplicate combo is not a conflict anyone sees, it is the older feature silently going dead. Troubleshooting gains eight entries, all the same shape as the rest of that page: a commit and a pkgrel bump that ship nothing, the ghost sound theme, a nested synui that re-themes the live desktop, quickshell's missing UseQApplication (whose error goes to tty1, not the journal), Nerd Font glyphs silently becoming the empty string, systemd's non-existent inline comments, and `pkill -f` killing the shell that ran it. Also corrected: wlroots 0.19 -> 0.20 and the scenefx fork in Architecture and Building; the collector drift that went four-for-four and is now deduped via <pkg>/mktarball.sh; LUKS2 and dual-boot in Installation, including why /boot stays outside the encrypted root; and the 0.1.5-0.1.9 release history, with the post-0.1.9 work marked unreleased.

velle999 committed Jul 26, 2026

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.

velle999 committed Jul 18, 2026

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.

velle999 committed Jul 18, 2026

Add Vibe and Chibi app pages; link them from Home + sidebar Vibe: local AI coding assistant (agentic tool loop) on synapd's model, the confirmation gate, and the text <tool_call> path over SYN_QF_RAW. Chibi: voice companion + security sentinel, the audio/venv gotchas. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

velle committed Jul 17, 2026

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.

velle999 committed Jul 12, 2026

Initial Home page

velle999 committed Jul 12, 2026