cleonos/docs/stage20.md

# CLeonOS Stage20

## Stage Goal
- Keep system in kernel-shell mode while ELF user shell remains deferred.
- Stabilize terminal interaction path: PS/2 input queue + line editing shell loop.
- Enable external PSF font loading for framebuffer TTY.
- Keep scheduler/service/syscall/interrupt pipeline stable.

## What Was Implemented
- Boot pipeline keeps kernel shell as the active interactive interface.
- TTY supports loading external PSF font from `/system/tty.psf`.
- Keyboard module provides:
  - PS/2 scan code handling
  - input queue buffering
  - `Alt+F1..F4` virtual TTY switch hotkeys
- Kernel shell interactive loop is online:
  - command dispatch (`help/ls/cat/exec/clear/kbdstat` baseline)
  - line editing and history
- TTY cursor path is timer-driven and supports blink updates via `clks_tty_tick()`.

## Acceptance Criteria
- Kernel boots and prints `CLEONOS Stage20 START`.
- Boot logs include:
  - `[INFO][TTY] EXTERNAL PSF LOADED /SYSTEM/TTY.PSF` (or fallback warning)
  - `[INFO][KBD] ALT+F1..F4 TTY HOTKEY ONLINE`
  - `[INFO][KBD] PS2 INPUT QUEUE ONLINE`
  - `[INFO][SHELL] INTERACTIVE LOOP ONLINE`
- Typing in kernel shell produces immediate echo and command execution.
- `Alt+F1..F4` switches active TTY without panic.

## Build Targets
- `make setup`
- `make userapps`
- `make iso`
- `make run`
- `make debug`

## QEMU Command
- `qemu-system-x86_64 -M q35 -m 1024M -cdrom build/CLeonOS-x86_64.iso -serial stdio`

## Common Bugs and Debugging
- Cannot type in shell:
  - Ensure QEMU window has keyboard focus.
  - Check logs for keyboard queue online messages.
- External PSF not applied:
  - Verify `/system/tty.psf` exists in ramdisk package.
  - If load fails, system will fall back to built-in font.
- Hotkey switching does not work:
  - Confirm `Alt` is held while pressing `F1..F4`.
  - Check `[INFO][TTY] HOTKEY SWITCH` logs.
- Input lag feels high:
  - Increase shell input budget or scheduler frequency in later stage.