repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by bugabinga

Add Linux console skill

f6ba8b8e67c043cb934d960c2fe3357aa9dfa2b5

Oliver Jan Krylow <oliver@bugabinga.net> ·

unsigned

Browse filesCompare with HEAD

Changed files (4)

skills/linux-console/SKILL.md

Added
new file mode 100644
1 +---
2 +name: linux-console
3 +description: "Use for real Linux kernel virtual console work: tty1/tty2, /dev/ttyN, Ctrl+Alt+F1 VTs, TERM=linux, getty, vconsole.conf, setfont, loadkeys, setterm, console_codes, fbcon. Not for terminal emulators, /dev/pts ptys, tmux, X11, or Wayland."
4 +---
6 +# Linux Console
8 +## Scope
10 +Use for kernel virtual consoles only:
12 +- `/dev/ttyN`
13 +- `TERM=linux`
14 +- `tty1`, `tty2`, ...
15 +- `Ctrl+Alt+F1` / VT switching
16 +- `getty`, `vconsole.conf`, `setfont`, `loadkeys`, `setterm`, `fbcon`
18 +Do not use for:
20 +- graphical terminal emulators
21 +- `/dev/pts/*` pseudo-terminals
22 +- tmux internals
23 +- X11 / Wayland / XKB config
25 +## First Probe
27 +Run before advice/changes:
29 +```sh
30 +tty
31 +echo "$TERM"
32 +infocmp -1 "${TERM:-linux}"
33 +```
35 +Interpret:
37 +- `/dev/ttyN` + `TERM=linux` → real VT likely.
38 +- `/dev/pts/N` → terminal emulator/pty; stop unless user asks docs only.
39 +- Missing local man page → fetch current upstream man page.
41 +## Learn Locally First
43 +Prefer local truth over memory:
45 +```sh
46 +man console_codes | col -b
47 +man setterm | col -b
48 +man vconsole.conf | col -b
49 +man loadkeys | col -b
50 +man keymaps | col -b
51 +man setfont | col -b
52 +man reset | col -b
53 +infocmp -1 linux
54 +```
56 +For deeper lookup: `references/research.md`.
58 +## Durable Rules
60 +- `TERM=linux` describes Linux-console capabilities via terminfo.
61 +- `clear` and `reset` differ; inspect `infocmp -1 linux`.
62 +- Linux console interprets control/escape sequences; verify in
63 + `console_codes(4)`.
64 +- Existing screen cells may need redraw after display/attribute changes.
65 +- Keymap, font, palette, and persistence scopes differ; classify first.
67 +## Change Hygiene
69 +For every proposed change, state:
71 +- target: current VT | all VTs | boot/persistent
72 +- mechanism: escape seq | terminfo | kbd tool | system config | ioctl
73 +- privilege needs: none | user permissions | root/admin | unknown until probed
74 +- rollback/reset path
76 +## Safety
78 +- Never apply X11/Wayland/XKB/niri fixes to Linux console.
79 +- Never confuse `/dev/ttyN` with `/dev/pts/N`.
80 +- Do not change keymaps/fonts/persistent config without explicit user intent.
81 +- Prefer `setterm`, `loadkeys`, `setfont`, `vconsole.conf` docs over guesses.
83 +## References
85 +Read when needed:
87 +- `references/research.md` — fresh docs, command probes, web fallbacks.
88 +- `references/model.md` — VT model, terminfo, reset/clear, screen memory.
89 +- `references/tools.md` — setterm/loadkeys/setfont/vconsole scope notes.

skills/linux-console/references/model.md

Added
new file mode 100644
1 +# Model
3 +## Terms
5 +- Linux console: kernel console implementation.
6 +- Virtual console / VT: numbered console, usually `/dev/ttyN`.
7 +- pty: pseudo-terminal, usually `/dev/pts/N`; not a real VT.
8 +- `TERM=linux`: terminfo name commonly used by Linux VTs.
9 +- framebuffer console / `fbcon`: kernel console display path on many systems.
11 +## Detection
13 +Strong signal:
15 +```text
16 +/dev/ttyN + TERM=linux
17 +```
19 +Weak/negative signal:
21 +```text
22 +/dev/pts/N
23 +```
25 +Use exact user wording too: `tty1`, `tty2`, `virtual console`, `linux console`,
26 +`Ctrl+Alt+F1`, `getty`, `fbcon`.
28 +## Terminfo
30 +`infocmp -1 linux` shows what `clear`, `reset`, curses apps, and terminfo-aware
31 +programs will emit.
33 +Inspect, do not assume:
35 +```sh
36 +infocmp -1 linux | grep -E 'clear|rs1|rs2|rs3|oc|op|initc|sgr0'
37 +```
39 +## Clear vs Reset
41 +`clear` normally clears/redraws screen state.
43 +`reset` reinitializes terminal state via terminfo reset strings. It may undo
44 +palette/display state. Confirm through `infocmp -1 linux` and `man reset`.
46 +## Escape Controls
48 +`console_codes(4)` is source of truth for Linux-console control sequences.
49 +Stable topics there:
51 +- control chars
52 +- ESC / CSI / OSC sequences
53 +- SGR attributes
54 +- palette controls
55 +- private Linux console sequences
57 +Avoid hard-wiring controls unless the task explicitly needs raw escapes.
58 +Prefer terminfo-aware tools when possible.
60 +## Screen Memory
62 +`vcs(4)` documents `/dev/vcsN` and `/dev/vcsaN` screen-memory devices.
63 +They can help inspect or dump VTs. Access depends on device permissions.
64 +Prefer `setterm --dump` for simple snapshots when available.
66 +## Low-level ioctls
68 +`ioctl_console(2)` describes Linux-specific console/VT ioctls and warns they are
69 +internal-ish. Prefer user tools unless low-level work is requested.

skills/linux-console/references/research.md

Added
new file mode 100644
1 +# Research Pattern
3 +Local first:
5 +```sh
6 +tty
7 +echo "$TERM"
8 +infocmp -1 "${TERM:-linux}"
9 +```
11 +Man pages:
13 +```sh
14 +man console_codes | col -b
15 +man setterm | col -b
16 +man vconsole.conf | col -b
17 +man loadkeys | col -b
18 +man keymaps | col -b
19 +man dumpkeys | col -b
20 +man showkey | col -b
21 +man setfont | col -b
22 +man reset | col -b
23 +man terminfo | col -b
24 +man vcs | col -b
25 +man ioctl_console | col -b
26 +```
28 +Useful probes:
30 +```sh
31 +infocmp -1 linux | grep -E '^(\s*(clear|rs[123]|is[123]|oc|op|initc|sgr0)=)'
32 +dumpkeys | head
33 +kbd_mode
34 +fgconsole 2>/dev/null
35 +ls -l /dev/tty[0-9]* /dev/vcs* /dev/vcsa* 2>/dev/null
36 +```
38 +If local docs are missing/stale, fetch current upstream docs:
40 +- <https://man7.org/linux/man-pages/man4/console_codes.4.html>
41 +- <https://man7.org/linux/man-pages/man1/setterm.1.html>
42 +- <https://man7.org/linux/man-pages/man5/vconsole.conf.5.html>
43 +- <https://man7.org/linux/man-pages/man1/loadkeys.1.html>
44 +- <https://man7.org/linux/man-pages/man5/keymaps.5.html>
45 +- <https://man7.org/linux/man-pages/man8/setfont.8.html>
46 +- <https://man7.org/linux/man-pages/man1/clear.1.html>
47 +- <https://man7.org/linux/man-pages/man1/reset.1.html>
48 +- <https://man7.org/linux/man-pages/man5/terminfo.5.html>
49 +- <https://man7.org/linux/man-pages/man4/vcs.4.html>
50 +- <https://man7.org/linux/man-pages/man2/ioctl_console.2.html>
52 +Distro docs can explain policy/integration. Prefer upstream man pages for
53 +interfaces, distro wiki for packaging/persistence quirks.

skills/linux-console/references/tools.md

Added
new file mode 100644
1 +# Tools
3 +## setterm
5 +Use for terminal attributes and VT-specific controls.
7 +Research:
9 +```sh
10 +man setterm | col -b
11 +setterm --help
12 +```
14 +Common scopes:
16 +- foreground/background/rendering attrs: current terminal stream
17 +- `--store`: stored defaults for reset-to-default on virtual consoles
18 +- blanking, bell, repeat, kernel messages: virtual-console-specific controls
20 +State exact scope before changing.
22 +## loadkeys / dumpkeys / showkey / keymaps
24 +Use for kernel console keyboard maps, not XKB/X11/Wayland.
26 +Research:
28 +```sh
29 +man loadkeys | col -b
30 +man keymaps | col -b
31 +man dumpkeys | col -b
32 +man showkey | col -b
33 +dumpkeys | head
34 +```
36 +Critical scope: `loadkeys` changes the kernel keymap used by virtual consoles;
37 +check local docs for exact reach and permissions.
39 +Rollback idea:
41 +```sh
42 +loadkeys --default
43 +```
45 +Verify with local docs before presenting as final rollback.
47 +## setfont
49 +Use for Linux console fonts and Unicode maps.
51 +Research:
53 +```sh
54 +man setfont | col -b
55 +ls /usr/share/kbd/consolefonts 2>/dev/null | head
56 +```
58 +Important:
60 +- PSF fonts are common.
61 +- Font/glyph choices can affect color availability.
62 +- `-O` can save previous font/map.
63 +- `-C` can target a console device; permissions vary.
65 +## vconsole.conf / localectl / systemd-vconsole-setup
67 +Use for boot/persistent virtual-console keyboard/font config on systemd systems.
69 +Research:
71 +```sh
72 +man vconsole.conf | col -b
73 +man localectl | col -b
74 +man systemd-vconsole-setup.service | col -b
75 +```
77 +State persistence and privilege needs before editing.
79 +## Palette / colors
81 +Research:
83 +```sh
84 +man console_codes | col -b
85 +man setterm | col -b
86 +infocmp -1 linux | grep -E 'initc|oc|op|setaf|setab'
87 +```
89 +Linux console color behavior is not the same as graphical terminal emulators.
90 +Verify palette, SGR, and reset behavior locally.