docs: architecture describes what is built now

kernel (threads, demand paging, TLB shootdowns, dynamic linking, RAM direct map), syscalls, filesystem (/proc, /sys,
/dev), terminals (12, VT handshake, ptys), networking (r8169 through LDLS), LDLS (module sets; Linux code may ship),
devices (what stays in the kernel; hybrid.md's lasting content), boot (the loader's placement of the kernel),
graphics (fbdev, GMMOS, QR 1-40), audio (ALSA over OSS), debugging, usb. New: packages.md (the apk root) and
desktop.md (Xorg on the framebuffer).

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EVRhxi9zpdW2uDUN4FVcao

docs/architecture/terminals.md

@@ -95,7 +95,9 @@ nothing to choose between. It records `proc->ctty` now, which is what
 |---|---|---|
 | `/dev/console` | 1 | the **active** terminal, so kernel messages follow a switch |
 | `/dev/tty` | 10 | the caller's **controlling** terminal, via `proc->ctty` |
-| `/dev/tty1`..`tty6` | 11-16 | that terminal, whether or not it is on screen |
+| `/dev/tty0` | | the active terminal, which is what Xorg and `openvt` ask for |
+| `/dev/tty1`..`tty12` | 11-22 | that terminal, whether or not it is on screen |
+| `/dev/ptmx`, `/dev/pts/N` | | pseudo-terminals, below |
 
 `/dev/tty` was an alias for `/dev/console` with the same major and minor. They
 are different questions and now have different answers.
@@ -190,13 +192,13 @@ every candidate.
 |---|---|
 | **The host takes it, and the guest never sees it** | |
 | `Alt+F4`, `Alt+F2` | window manager |
-| `Ctrl+Alt+F1..F6` | display manager — and it matches **loosely**, so adding Shift does not get past it |
+| `Ctrl+Alt+F1..F12` | display manager — and it matches **loosely**, so adding Shift does not get past it |
 | `Ctrl+Alt+`digit | QEMU's own console tabs |
 | **Applications want it, and lose it permanently if the kernel eats it** | |
 | `Alt+`anything | Meta. zsh binds Meta-digit as `digit-argument`; so does every readline editor |
 | `Ctrl+`letter | control characters |
 | `Ctrl+Shift+`digit | types a character — `Ctrl+Shift+2` is `^@` |
-| `F1..F6` alone | help, and whatever a full-screen program wants |
+| `F1..F12` alone | help, and whatever a full-screen program wants |
 | **The keyboard layout wants it** | |
 | `AltGr+`letter | Polish diacritics — ą ć ę ł ń ó ś ź ż — and on some setups AltGr arrives as Ctrl+Alt |
 
@@ -207,7 +209,7 @@ chvt                        # report the active terminal and the current chord
 chvt -c ctrl+alt+F          # Ctrl+Alt+F1..F12    (the default)
 chvt -c altgr+F             # AltGr+F1..F12       (the default until 2026-10)
 chvt -c ctrl+shift+F        # Ctrl+Shift+F1..F12
-chvt -c alt+1               # Alt+1..6
+chvt -c alt+1               # Alt+1..9
 chvt -c off                 # no chord; chvt N is then the only way
 ```
 
@@ -368,34 +370,56 @@ and erase characters — were added at the same time, because `TERM=linux`
 declares them and a terminal that drops them silently is the same class of bug
 waiting for a different editor.
 
+## Handing a terminal to a program
+
+A display server takes a terminal with `VT_SETMODE(VT_PROCESS)` and `KDSETMODE(KD_GRAPHICS)`,
+and from then on switching away from it is a **request**: the kernel sends the owner
+`relsig` and waits for `VT_RELDISP`, so the server stops drawing and only then says
+yes; switching back sends `acqsig` and the server redraws. A terminal in graphics mode
+is not repainted by the kernel. If the owner dies, the terminal goes back to the kernel
+whole. This is how Xorg runs on a terminal of its own, with Ctrl+Alt+F-key switching
+between it and the text consoles and Ctrl+Alt+Backspace ending the session.
+
+## Pseudo-terminals
+
+`/dev/ptmx` makes a pair on every open and hands back the master; the slave is
+`/dev/pts/N`, which the program on the other side gets as its stdin, stdout and
+controlling terminal. Between them is a line discipline, the console's in miniature:
+what the master writes is the slave's input (canonical editing, echo, `^C` as `SIGINT`
+to the foreground group) and what the slave writes is read back by the master with NL
+turned into CR NL. xterm, tmux, `script` and `sshd` all need exactly this. The pairs
+share one lock; `kernel/dev/pty.c`.
+
+## The text cursor
+
+A steady inverted block — the cell with its colours swapped relative to what it would
+show, so a cursor on reverse-video text is the plain text and every cursor on screen
+is visible against its cell. `ESC[?25l` hides it, `ESC[?25h` shows it. It is drawn into
+the grid's repaint and does not blink.
+
 ## What it does not do
 
 - **No scrollback.** The grid is exactly the visible screen. Shift+PageUp does
   nothing because there is nothing above the top row to show.
-- **No reflow on resize.** The geometry is read once at `vt_init()`. Nothing
-  resizes a framebuffer console today; a compositor will, and that is when this
-  has to grow.
-- **No `VT_RELDISP` handshake.** `VT_PROCESS` stops the kernel switching, but
-  the kernel does not signal the owning process and wait for an answer. A
-  display server that needs to release the GPU *before* the screen changes
-  hands will need that, and `struct vt_mode` already has the fields.
-- **No terminal past 6.** Linux allows 63. Six is what the chords reach and
-  what the grids are sized for.
+- **No reflow on resize.** The geometry is read once at `vt_init()`; the console's
+  font is sized to the screen at that point, and a resolution change from `schmode`
+  repaints it, but text is not re-wrapped.
+- **No terminal past 12.** Linux allows 63. Twelve is one per function key.
 - **Only 240x75 of any screen.** Larger framebuffers work; the grid is clamped
   and the remainder stays background. Raising `VT_MAXCOLS`/`VT_MAXROWS` is the
   fix, and costs BSS.
 - **No UTF-8 the font lacks.** The console draws through the TrueType
-  rasteriser now, so the limit is the font's `cmap` rather than a 256-entry
-  table — Latin, Latin Extended, Greek, Cyrillic and the common punctuation and
-  maths symbols all render. Anything genuinely absent still draws as `?`, which
-  is deliberate: drawing a *different* character would be worse.
+  rasteriser, so the limit is the font's `cmap` — Latin, Latin Extended, Greek,
+  Cyrillic and the common punctuation and maths symbols all render. Anything
+  genuinely absent still draws as `?`, which is deliberate: drawing a
+  *different* character would be worse.
 - **No shaping, and no wide characters.** One codepoint is one cell of one
   advance. Combining marks land on top of their own cell rather than the
   preceding one, and CJK draws at half the width it wants. Both need a
   width table and a cell that can span two columns.
 - **No dead keys**, so French and Spanish layouts are absent rather than
-  broken. See above.
+  broken.
 - **No per-terminal layout.** One keyboard, one layout. Switching to tty3 does
   not move anybody's fingers.
-- **Only three layouts.** Adding one is a table in `keymap.c` and a line in the
+- **Only three layouts** (US, Polish programmers', German). Adding one is a table in `keymap.c` and a line in the
   catalogue; the mechanism is not the limit, the typing is.