P1Start documentation index¶

For a full matrix of subsystems, source paths, legacy HTML, and Sphinx gaps, open Reference → Coverage matrix in the sidebar (source file reference/coverage-matrix.md).

Use this file to find Sphinx-side deep dives for each subsystem.
Platform-wide canonical contracts now live in newdocs/; update both surfaces when behavior changes (see foundation-debt.md §8).

Doc	Purpose
`foundation-debt.md`	Foundation ledger: IPC mailboxes (§2), WM + syscall 50 present teardown + `PML4[192]` rule (§3), RegCube (§4), cross-cutting MM (§5), §5.3 client RGBA `mmap` vs `brk`, serial regression signature §5.2, maintenance rule (§8).
`wm-v1-platform-roadmap.md`	WM v1 product + Rex brief: wire format, bugs-fixed table (§6), Track A/B compositor state, file touch list.
`system-architecture.md`	Whole-stack map: boot → tasks → IPC → deskgui; §3.1–§3.2 present remap + close/kill hygiene (links to foundation-debt).
`terminal-stack.md`	gterm ↔ PTY ↔ dps byte spine; display fold vs VT emulation; §4b — multi-window “close order” was not PTY coupling; pointer to foundation-debt + §5.2.
`keyboard-input-and-layout.md`	Keyboard / UTF‑8 contract: PS/2 path, US QWERTY via `p1keyboard-layout`, Ctrl+Shift+Q close policy, kernel `keyboard_layout.rs` stub vs userland; locale / RegCube deferred.
`pty-v1-design.md`	PTY v1 contract: refcount/teardown, blocking read + wait queues, `sys_read` `r10` non-block PTY flag, Phase D userspace status, §9 gterm display path (CSI/OSC/fold), testing criteria.
`launch-paths.md`	Dock `.lnk`, `PATH_`, ramdisk staging — not* WM lifecycle.
`dynamic-linking.md`	`ld.elf` / `p1dl`: phase-1 experimental dynamic linking, relocation subset, `DL_E_*`.
Shared library workflow (repo)	`SDK/shared-library-development.md` — Clang `.so` fixtures, ramdisk `E` lines, QEMU smoke.

Multi-window close / compositor — read first¶

If QEMU dies when closing any terminal (especially front / higher z_order first), do not assume PTY or “first spawned” magic. In Apr 2026 the dominant kernel bug was cleanup_user_page_tables freeing the shared PML4[192] subtree while other apps still used syscall-50 present mappings there.

Read foundation-debt.md §3.5.6 (edge-case table) and §5.2 (serial log signature).
Run the manual checklist §5.1 before merging MM or spawn changes.
See also wm-v1-platform-roadmap.md §6 (bugs-fixed table).

Last updated: Apr 26, 2026 — gterm client RGBA on p1_alloc_framebuffer / sys_mmap_anon (foundation-debt §5.3); prior Apr 2026: PTY Phase D + WM present stride + compositor HUD / task manager drag.