From cbac6743bc5b99a982b5ded0f458dc7d0f72844b Mon Sep 17 00:00:00 2001 From: Luxferre Date: Thu, 22 Oct 2026 09:27:26 +0300 Subject: [PATCH] Add AGENTS.md project outline and conventions guide --- AGENTS.md | 41 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 41 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..adeaa0f --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,41 @@ +# 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`, `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_.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`), `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`). + - `dwm_plugin_runner.c`: Lightweight `/usr/bin/dwm-plugin` launcher symlinked by `xdrawer`, `xdialer`, `xcalllog`, `xcontacts`, `xsms`, `xfiles`, `xcamera`, `xthemes`, `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/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`). +- `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`, and all C++ `.so` plugins (`xdrawer`, `dialer`, `calllog`, `contacts`, `sms`, `files`, `camera`, `themes`). +- `./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`. +- `./chroot-shell.sh` — Opens an `armv7` container shell to manage packages in `rootfs/` (`pkg-add`, `pkg-del`, `pkg-search`). +- `./rebuild-image.sh [--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_.lock`, sleeping at 0% CPU on `poll()` over `ConnectionNumber(dpy)` and `/tmp/dwm_plugin_.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/`.