bananarchy/AGENTS.md

# Bananarchy Linux — Agent Guide (`AGENTS.md`)

## 1. Project Overview
**Bananarchy** is a keypad-first Linux distribution (`armv7` / Alpine `edge` / postmarketOS `v26.06` hardfork) for **Qualcomm MSM8905 (Snapdragon 205)** and **MSM8909 (Snapdragon 210)** smart feature phones with **240x320 QVGA non-touch SPI displays** and **12-key T9 keypads** (`nokia-argon`, `nokia-beatles`, `nokia-tough`, `nokia-sparkler`, `nokia-leo`).

It uses a pure **X11 (`Xlibre` + `sxmo-de-dwm`)** stack (no Wayland) optimized for `< 2 ms` UI wakeup latency and `< 95 MB` idle RAM on 512 MB devices.

## 2. Repository Layout
- `src/sxmo-dwm/`: Patched `dwm` window manager (`240x320` vertical `bstack` layout, 24px Pango status bar, desktop `"Menu"`/`"Names"` softkey bar, C-level `SW_LID` slider and locked-key wake handling, live `.Xresources` reload, and `.so` plugin loader via `dwm_plugin.h`).
- `src/sxmo-dmenu/`: Zero-lag resident DWM menu plugin (`dmenu.so`) and `/tmp/dwm_plugin_dmenu.sock` client (`dmenu` / `xdmenu`), featuring built-in Sxmo menus (`sys`, `applications`, `scripts`, `modem`, `config`, `power`, `audio`, `notifications`, `wm`, `timezone`, `games`, `st`, `nano`, `sthotkeys`) and `fcitx5-t9` XIM input.
- `src/dwm-plugins/`: Preloaded C++20 `240x320` DWM plugins and shared headers:
  - `theme.h`: Unified `.Xresources` / `~/.xthemes/*.xth` parser, proportional font sizing (`theme.baseFontSize`), automatic shade derivation, and live Xft/Pango theme reloading (`PluginTheme`).
  - `phone_data.h`: Shared X11 geometry (`240x296` below the 24px bar), FIFO IPC (`/tmp/dwm_plugin_<name>.fifo`), softkey chord detection, Sxmo TSV contact/call/SMS parsers, and `libjpeg`/`libpng` helpers.
  - `dialer_plugin.cpp` (`dialer.so` / `xdialer`), `calllog_plugin.cpp` (`calllog.so` / `xcalllog`), `callscreen_plugin.cpp` (`callscreen.so` / `xcallscreen`), `contacts_plugin.cpp` (`contacts.so` / `xcontacts`), `sms_plugin.cpp` (`sms.so` / `xsms`), `files_plugin.cpp` (`files.so` / `xfiles`), `camera_plugin.cpp` (`camera.so` / `xcamera`), `themes_plugin.cpp` (`themes.so` / `xthemes`), `modem_plugin.cpp` (`modem.so` / `xmodem`), `networks_plugin.cpp` (`networks.so` / `xnetworks` / `xbluetooth`), `ringtones_plugin.cpp` (`ringtones.so` / `xringtones`), `wallpapers_plugin.cpp` (`wallpapers.so` / `xwallpapers` / `xbackground`), `music_plugin.cpp` (`music.so` / `xmusic` / `xplayer`).
  - `dwm_plugin_runner.c`: Lightweight `/usr/bin/dwm-plugin` launcher symlinked by `xdrawer`, `xdialer`, `xcalllog`, `xcallscreen`, `xcontacts`, `xsms`, `xfiles`, `xcamera`, `xthemes`, `xmodem`, `xnetworks`, `xbluetooth`, `xringtones`, `xwallpapers`, `xbackground`, `xmusic`, `xplayer`, `dmenu`, and `xdmenu`.
- `src/xdrawer/`: Global phone controls overlay (`xdrawer.so` / `xdrawer`), toggled by pressing both softkeys simultaneously.
- `src/sxmo-st/`: Patched `st` terminal with HarfBuzz OpenType ligatures (`Fira Code`), `XIM` (`fcitx5-t9`), and live `SIGUSR1` `.Xresources` reload.
- `src/fcitx5-t9/`: 6-mode keypad input method (`abc`, `Abc`, `ABC`, `Sym`, `Ctl`, `123` + `*` long-press `Ctrl+` latch) with fixed bottom preedit bar (`Y=290, H=30`).
- `src/games/`: Standalone keypad-driven `240x320` X11 games (`snake.cpp` -> `/usr/bin/snake`, `tetris.cpp` -> `/usr/bin/tetris`) with built-in 5x7 bitmap fonts, `timerfd`-driven pacing, and offscreen `Pixmap` double buffering.
- `src/msm8905-cam/` & `src/leds-msm8905-torch/`: Out-of-tree Linux `6.12.1-msm8916` kernel modules for the rear `GC2395` camera (`/dev/video0`) and `SY7807` torch LED (`white:torch`) / WCD codec init / PM8909 `PON` shutdown.
- `overlay/rootfs/`: System configuration overlay applied over the target rootfs (kept in sync with `prebuilt/`).
- `prebuilt/`: Cross-compiled `armv7` binaries and kernel modules (`sxmo-x11`, `fcitx5-t9`, `xlibre`, `kernel-6.12.1-msm8916`, `bantam`, `games`).
- `devices/` & `patches/`: Device trees (`.dts`/`.dtb`), MIPI-DBI panel init sequences, and upstream patch sets.

## 3. Build & Image Generation Commands
All cross-compilation scripts run inside rootless Docker (`alpine:3.24` `armv7` sysroot) and automatically update both `prebuilt/` and `overlay/rootfs/`:
- `./scripts/build-sxmo-x11.sh` — Builds `st`, `dmenu.so`, `dwm`, `dwm-plugin`, `sxmo_vibrate`, and all C++ `.so` plugins (`xdrawer`, `dialer`, `calllog`, `callscreen`, `contacts`, `sms`, `files`, `camera`, `themes`, `modem`, `networks`, `ringtones`, `wallpapers`, `music`).
- `./scripts/build-dmenu.sh` — Rebuilds only `dmenu.so`, `stest`, `dmenu_path`, and `dmenu_run`.
- `./scripts/build-games.sh` — Builds standalone X11 games in `src/games/` (`snake`, `tetris`).
- `./scripts/build-fcitx5-t9.sh` — Builds `src/fcitx5-t9` (`libt9.so` / `t9.so`).
- `./scripts/build-kernel-audio.sh` — Builds `6.12.1-msm8916` QDSP6 audio, torch LED, camera `.ko` modules, and device `.dtb` files.
- `./scripts/build-xlibre.sh` — Builds Xlibre `Xorg` and `libinput`/`fbdev` DDX drivers.
- `./scripts/build-bantam.sh` — Fetches and cross-compiles the `bantam` AI agent.
- `./scripts/generate-artwork.py` — Regenerates wallpapers, splashes, and icons from `artwork/icon-large.png`.
- `./scripts/version.sh [--print | target_rootfs]` — Computes the date-based release version (`<year-letter><MM><DD>` with `2026 = a`) and substitutes `@BANANARCHY_VERSION@` in `etc/os-release`, `etc/issue`, and `etc/motd` (invoked automatically during overlay application and image builds).
- `./chroot-shell.sh` — Opens an `armv7` container shell to manage packages in `rootfs/` (`pkg-add`, `pkg-del`, `pkg-search`).
- `./rebuild-image.sh <device> [--mkinitfs]` — Applies `overlay/rootfs/` + `prebuilt/` into `rootfs/` and produces flashable images in `images/`.
- `sudo ./flash-edl.sh [device]` — Flashes `lk2nd` and the system image over Qualcomm USB EDL (`05c6:9008`).

## 4. Coding & Architecture Conventions
- **Indentation**: Always use 2-space indentation in C, C++, Python, and shell scripts (tabs only in Makefiles and TSV files).
- **No Emojis**: Never use emojis in source code, UI strings, logs, or commit messages (use Nerd Font PUA codepoints defined in `phone_data.h` / `dmenu.c` for UI icons).
- **Unified Theming**: Never hardcode UI colors or font sizes in `dwm`, `dmenu`, `st`, or any DWM plugin. Read colors and proportional font sizes from `PluginTheme` (`src/dwm-plugins/theme.h`) / `.Xresources` (`theme.*`), and handle `RELOAD_THEME` on the plugin FIFO.
- **Zero-Lag Plugin Model**: Phone UI apps must run as preloaded resident daemons (`--preload`) guarded by `/tmp/dwm_plugin_<name>.lock`, sleeping at 0% CPU on `poll()` over `ConnectionNumber(dpy)` and `/tmp/dwm_plugin_<name>.fifo`, and rendering into an offscreen `Pixmap` (`240x296` at `X=0, Y=24`) copied with `XCopyArea` to prevent flicker.
- **Documentation**: Keep `README.md` and `MANUAL.md` synchronized with any new user-facing features or keybindings, and do not leave third-party `.md` files inside `src/` or `edl/`.