diff --git a/01-RESEARCH/026-the-graphical-session-as-modules/00-overview.md b/01-RESEARCH/026-the-graphical-session-as-modules/00-overview.md index 68d3f43..5e44247 100644 --- a/01-RESEARCH/026-the-graphical-session-as-modules/00-overview.md +++ b/01-RESEARCH/026-the-graphical-session-as-modules/00-overview.md @@ -46,6 +46,15 @@ desktops. Measured in [01](01-what-the-workstations-run.md): - The session's environment is a hand-kept second copy of the account's, beside the one the mesh now writes. +## How it is approached + +**Adopting is also improving** (the operator, 2026-10-04). A module is not a copy of what a machine +does today. Making it is the moment to fix what is broken, drop what is dead, choose the better tool +and remove the leftovers. Every module's design lists its improvements over today. **Every module +also serves tools,** many of them, for reading, acting and diagnosing; a module that only places a +package and a file is unfinished. The tools are catalogued in +[026/05](../026-the-graphical-session-as-modules/05-the-tools-each-module-serves.md). + ## What it touches - **The seat table:** up to ten node seats. @@ -61,4 +70,5 @@ desktops. Measured in [01](01-what-the-workstations-run.md): - [01 — What the workstations run](01-what-the-workstations-run.md): evidence. - [02 — The questions and the options](02-the-questions-and-the-options.md) - [04 — Screensaver, displays and menus](04-screensaver-displays-and-menus.md): the lock and idle module, monitor layouts by the monitors' identity, rofi and dmenu behind one launcher seat, the clipboard, fonts +- [05 — The tools each module serves](05-the-tools-each-module-serves.md): a first catalogue for the modules of 026 and 027 - [03 — What the predecessor taught](03-what-the-predecessor-taught.md): its 128 modules and 3,395 commits, as patterns to keep and failures not to repeat; shared with research 027. diff --git a/01-RESEARCH/026-the-graphical-session-as-modules/04-screensaver-displays-and-menus.md b/01-RESEARCH/026-the-graphical-session-as-modules/04-screensaver-displays-and-menus.md index e52dce3..44530c9 100644 --- a/01-RESEARCH/026-the-graphical-session-as-modules/04-screensaver-displays-and-menus.md +++ b/01-RESEARCH/026-the-graphical-session-as-modules/04-screensaver-displays-and-menus.md @@ -107,10 +107,22 @@ Three areas the operator named on 2026-10-04, as their own modules. Each sharpen - The DPI is fixed in an X resource. - **Every Nerd font in use is in the official repositories** (Hack, Meslo, Iosevka, JetBrains Mono). +**Decided** (the operator left the choice open, except that it must not be today's Hack): + +| role | face | why | +|---|---|---| +| monospace: terminal, window manager, bar, launcher, prompt | **JetBrains Mono Nerd Font** | built for long reading in a terminal, unambiguous `0O1lI`, optional ligatures; a version-3 Nerd font, so every icon the prompt and bar use is present | +| interface: GTK, Qt, notifications | **Inter** | designed for screens, clear at small sizes | +| icons missing from any face | Nerd Fonts Symbols | a fallback, so a font without icons still shows them | +| emoji | Noto Color Emoji | | +| serif and every other script | Noto | | + +All five are official packages. + **Starting position:** -- **A `fonts` module:** the official packages, and a fontconfig file it owns that maps `monospace` (and - the emoji and symbol fallbacks) to the chosen faces, so every program agrees. +- **A `fonts` module:** those packages, and a fontconfig file it owns that maps `monospace`, `sans-serif`, + `serif` and the emoji and symbol fallbacks to the chosen faces, so every program agrees. - The terminal, bar, launcher and prompt modules name the family, not a file. - The DPI becomes the display server's setting (issue 168). - The copied files are removed by the operator once the packages are in (ADR 0182). diff --git a/01-RESEARCH/026-the-graphical-session-as-modules/05-the-tools-each-module-serves.md b/01-RESEARCH/026-the-graphical-session-as-modules/05-the-tools-each-module-serves.md new file mode 100644 index 0000000..efa669e --- /dev/null +++ b/01-RESEARCH/026-the-graphical-session-as-modules/05-the-tools-each-module-serves.md @@ -0,0 +1,77 @@ +# 05 — The tools each module serves + +A first catalogue for the modules of research 026 and 027, as the operator asked: "all kinds of useful +tools for all these modules". Each tool is served by the node's runtime (ADR 0175), on the machine the +module runs on. Through discovery (ADR 0195) it is reachable from any machine as +`/.`, or as `/.` where a seat defines it. + +**Conventions:** + +- **(r)** reads. +- **(a)** acts on the machine, escalating where it must, as the packet filter does (to-be 38 WP4). +- **(d)** is a desktop act that needs the operator's session. +- A tool that changes something a module declares says so in its answer: the next push restores the + declaration. +- Every tool answers structured data, not prose (issue 229). +- **Seat verbs** (marked *seat*) are the protocol every holder of that seat serves. The rest are the + module's own. + +## The graphical session (026) + +| module | tools | +|---|---| +| `xorg` (*node-display-server*) | *seat* `displays` (r: outputs, modes, rates, connected monitors with their identity) · *seat* `layout` (r/a: list, save, apply an autorandr profile) · `set-mode` (a: one output's resolution, rate, rotation, scale) · `primary` (a) · `dpi` (r/a) · `input-devices` (r) · `input-set` (a: touchpad tap, natural scroll, pointer speed) · `keyboard` (r/a: layout and options) · `screenshot` (d: one screen or all, as a file) · `x-log` (r: the server's errors since start) | +| `i3` (*node-display-session*) | *seat* `reload` (a) · *seat* `workspaces` (r) · *seat* `windows` (r: tree with classes, titles, workspaces) · `focus` (d: window or workspace) · `move` (d: window to workspace or output) · `layout-save` / `layout-restore` (d: a workspace's arrangement) · `exec` (d: start a program in the session) · `kill` (d) · `bindings` (r: every key binding and what it runs) · `config-check` (r: validate the composed configuration before a reload) · `marks` (r) · `scratchpad` (d) | +| `sway` (*node-display-server*, *node-display-session*) | the same seat verbs over Wayland, plus `outputs` (r) and `idle-inhibitors` (r) | +| `lemurs` (*node-login-manager*) | *seat* `sessions` (r: what the login screen offers) · *seat* `default-session` (r/a) · `logins` (r: who logged in when, from the journal) | +| `xterm` (*node-terminal-emulator*) | *seat* `open` (d: a terminal, optionally running a command, in a directory) · `font` (r/a: face and size) · `colours` (r) | +| `i3status-rust` (*node-bar*) | *seat* `reload` (a) · `blocks` (r: what the bar shows and each block's current value) · `block-run` (r: run one block once and answer its output) · `themes` (r) | +| `picom` (*node-compositor*) | *seat* `restart` (a) · `rules` (r: opacity, shadow and blur rules in force) · `window-opacity` (d) · `toggle` (d: compositing off and on, for a game or a test) | +| `rofi` (*node-launcher*) | *seat* `menu` (d: show a list, answer the chosen line: the dmenu-compatible command as a tool) · `applications` (r: the desktop entries it would offer) · `themes` (r) · `run` (d) | +| `dmenu` (*node-launcher*) | *seat* `menu` (d) | +| `dunst` (*node-notifier*) | *seat* `send` (d: title, body, urgency, actions) · *seat* `history` (r) · `pause` / `resume` (d: do not disturb) · `close-all` (d) · `rules` (r) · `count` (r: shown, waiting, history) | +| lock module (*node-lock-screen*) | *seat* `lock` (d) · `idle` (r/a: screensaver and display power timeouts) · `inhibit` (d: keep the screen on for a while) · `locked` (r: is the session locked now, and since when) | +| clipboard manager (*node-clipboard*) | *seat* `history` (r: entries, newest first, length-limited) · *seat* `copy` (d: put text on the clipboard) · `paste` (r: what the clipboard holds now) · `clear` (d) · `delete` (d: one entry) | +| `xclip` | `copy` (d) · `paste` (r): the plain clipboard without a manager | +| `feh` (wallpaper) | `set` (d: an image, per output) · `current` (r) | +| `fonts` | `families` (r: installed faces) · `match` (r: what `monospace`, `sans-serif` and `emoji` resolve to) · `glyph` (r: which installed font has a given character) · `cache-rebuild` (a) | +| theme module | `appearance` (r/a: dark or light, for GTK, Qt and the portal at once) · `cursor` (r/a) · `icons` (r) · `portal-check` (r: which portal backend answers which interface) | +| `gnome-keyring` (*node-secret-service*) | *seat* `unlocked` (r) · `lock` (d) · `collections` (r: names and item counts, never secrets) · `ssh-keys` (r: what the agent holds, by fingerprint) | +| desktop hardware module (laptop) | `brightness` (r/a: panel and keyboard) · `battery` (r: charge, health, cycles, limit) · `charge-limit` (r/a) · `gpu-mode` (r/a: integrated, hybrid, discrete) · *seat* `profile` (r/a: quiet, balanced, performance) · `thermals` (r: temperatures and fan speeds) · `power-draw` (r) | + +## The system and the account (027) + +| module | tools | +|---|---| +| `docker` (*node-container-runtime*, ADR 0166) | *seat* `list`, `inspect`, `logs`, `stats`, `start`, `stop`, `restart` (r/a) · `images` (r: with size and which container uses each) · `prune` (a: dangling images, stopped containers not held by the mesh, build cache, with a dry run first) · `disk-usage` (r) · `networks` (r) · `volumes` (r: with what mounts each and whether the mesh holds it) · `events` (r: the last hour) · `daemon-config` (r) | +| `docker-compose` | `projects` (r: compose projects running and where their files are) · `up` / `down` / `restart` (a: one project, by directory) · `logs` (r) · `ps` (r) | +| `sudo` | `rules` (r: what the account may run, without a prompt and with one) · `check` (r: does the escalation the mesh relies on work here) | +| `pacman` | `search` (r) · `installed` (r: with version and explicitly or as a dependency) · `info` (r) · `owns` (r: which package owns a path) · `files` (r) · `updates` (r: what an upgrade would change) · `upgrade` (a: with the news first) · `orphans` (r) · `remove-orphans` (a) · `cache` (r/a: size, clean to the last N versions) · `history` (r: installs and upgrades from the log) · `mirrors` (r/a: rank and refresh) · `news` (r: distribution news since the last upgrade) | +| AUR (package repository, 027 question 1) | `search` (r) · `build` (a: on the build machine, into the mesh's repository) · `outdated` (r) · `published` (r) | +| `snapd`, `flatpak` | `list` (r) · `install` / `remove` (a) · `update` (a) · `runtimes` (r) · `disk-usage` (r) | +| `time-sync` | `status` (r: synchronised, offset, server) · `servers` (r) · `sync-now` (a) | +| `localization` | `get` (r: locale, time zone, keymap) · `time-zone` (r/a) · `locales` (r) | +| `kernel` | `running` (r: version, command line, uptime) · `installed` (r) · `modules` (r: loaded, with what uses them) · `reboot-needed` (r: a newer kernel or library than the one running) · `microcode` (r) · `boot-entries` (r) · `initramfs-rebuild` (a) · `dmesg` (r: errors since boot) | +| `logrotate` | `status` (r: last rotation per log) · `force` (a: one configuration) · `big-logs` (r: the largest logs on the machine) | +| `avahi` | `browse` (r: services on the local network) · `resolve` (r) | +| `cups` | `printers` (r) · `queue` (r) · `cancel` (a) · `print` (a: a file to a printer) · `default` (r/a) | +| `bluetooth` | `devices` (r: paired, connected, battery where reported) · `connect` / `disconnect` (a) · `scan` (r) · `power` (r/a) | +| `ssh-client` (owns `~/.ssh`) | `hosts` (r: every `Host` and where it came from: the mesh, a module, the operator) · `check` (r: modes, keys without a passphrase, keys unused for a year, stale `known_hosts` entries) · `authorized` (r: who may log in, by fingerprint and comment) · `revoke` (a: one authorized key, into the operator's region) · `known-host` (r/a: verify, refresh one host's key) · `test` (r: can this machine reach a host and authenticate, batch mode) | +| `sshd` | `sessions` (r: who is logged in, from where) · `config-effective` (r: `sshd -T`) · `failed-logins` (r: since a time, with fail2ban's verdicts) | +| scripts modules | `list` (r: each script with its one-line description) · `run` (a: one script by name with arguments, as the account, bounded like `execute`) · `which` (r: which module ships a command) | +| `node-env` (*node-environment*) | `show` (r: every variable and `PATH` entry with the module that contributed it) · `diff` (r: what a shell actually has versus what the mesh composed) | +| `zsh` (*node-login-shell*) | *seat* `execute` · `zsh_config` (r) · `history-search` (r: the account's history, by pattern) · `functions` (r: aliases and functions in force, with where each came from) · `startup-time` (r: how long an interactive shell takes to start, per slot) | +| `memory-pressure` | `status` (r: memory, swap, compressed swap ratio, pressure stall) · `top` (r: the largest processes) · `oom-history` (r: what was killed, when) | +| `zfs` | `pools` (r: health, capacity, fragmentation) · `datasets` (r) · `snapshots` (r/a: list, create, destroy by name) · `scrub` (r/a: status, start) · `errors` (r) · `arc` (r: cache statistics) | +| `nfs-server`, `samba` | `exports` / `shares` (r) · `clients` (r: who has it mounted now) · `reload` (a) | +| `nfs-client`, `smb-client` | `mounts` (r: each share, mounted or not, and since when) · `mount` / `unmount` (a) · `test` (r: is the server reachable, is the export offered) | +| hosts-file holder (*node-hosts-file*, ADR 0199) | *seat* `entries`, `add`, `remove` | +| `vnstat`, `lm_sensors` | `traffic` (r: per interface, day, month) · `sensors` (r) | +| mail consumer (future effort) | `accounts` (r) · `search` (r) · `unread` (r) · `read` (r: one message) · `mark` (a) · `send` (a) | + +## What this catalogue is for + +It is a starting list, not a contract. A tool becomes a contract only when it is a seat's verb, and +each seat's verbs are decided in that seat's record (ADR 0132). A module's own tools can grow freely. +Every row above is a tool the operator would otherwise run by hand over ssh. That is the measure of +whether one is worth writing. diff --git a/01-RESEARCH/027-the-system-layer-as-modules/00-overview.md b/01-RESEARCH/027-the-system-layer-as-modules/00-overview.md index e3a4a94..a95b1d4 100644 --- a/01-RESEARCH/027-the-system-layer-as-modules/00-overview.md +++ b/01-RESEARCH/027-the-system-layer-as-modules/00-overview.md @@ -37,6 +37,15 @@ Measured in [01](01-what-the-machines-run.md): on four machines, almost nothing owned by a module. The pieces differ by machine for no recorded reason. Three findings are security matters on their own. +## How it is approached + +**Adopting is also improving** (the operator, 2026-10-04). A module is not a copy of what a machine +does today. Making it is the moment to fix what is broken, drop what is dead, choose the better tool +and remove the leftovers. Every module's design lists its improvements over today. **Every module +also serves tools,** many of them, for reading, acting and diagnosing; a module that only places a +package and a file is unfinished. The tools are catalogued in +[026/05](../026-the-graphical-session-as-modules/05-the-tools-each-module-serves.md). + ## What it touches - **The container runtime seat** (ADRs 0165 and 0166, both proposed).