# KV-TrimUI Developer & AI Agent Knowledge Hub
> Official technical specifications, Rust core engine architecture, and autonomous coding guidelines for TrimUI Smart Pro & Brick Pro handheld gaming consoles.

## Overview
KV-TrimUI is an open-source software ecosystem and high-performance native application suite for the TrimUI handheld gaming console family (Allwinner A133plus Quad-Core ARM Cortex-A53 @ 1.8GHz, Linux Kernel 4.9, 1GB LPDDR4 RAM, 1280x720 16:9 60Hz IPS display).

This document serves as the canonical machine-readable index for LLMs, AI agents (Antigravity, Claude Code, Cursor, Copilot, ChatGPT), and human systems engineers building native software for TrimUI.

## Core Architectural Invariants (Critical Rules)
1. **NO X11 OR WAYLAND**: TrimUI Stock OS and CrossMix-OS do NOT provide any desktop window manager. Native apps MUST render directly to the Linux Framebuffer device `/dev/fb0` (1280x720, 32bpp, BGRA/RGBA) using memory mapping (`mmap`).
2. **MUSL STATIC LINKING MANDATORY**: Stock OS utilizes an outdated GLIBC (~2.28). Compiling with `aarch64-unknown-linux-gnu` WILL result in `GLIBC_2.34 not found` runtime crashes. All native binaries MUST be cross-compiled using the `aarch64-unknown-linux-musl` target with static linking.
3. **LINUX EVDEV INPUT**: Gamepad buttons, D-Pad, triggers, and analog sticks are read directly from Linux input event nodes (`/dev/input/event0`, `/dev/input/event1`, or `/dev/input/event2`) using the standard Linux input subsystem (`evdev`).
4. **MAINUI PROCESS MANAGEMENT**: In `launch.sh`, apps must kill or stop the background Stock OS launcher (`killall -STOP MainUI` or `killall MainUI`) before opening `/dev/fb0`, and resume/restart it upon exit (`killall -CONT MainUI`).
5. **ALSA BIT-PERFECT AUDIO**: Hardware audio output uses ALSA devices (`hw:0,0` or `default`), volume control via `amixer set 'Lineout'`.

## Essential Documentation & Machine Endpoints
- [Full Technical Handbook & Code Engine](https://trimui.vndns.net/llms-full.txt): Comprehensive deep-dive covering Framebuffer double-buffering, Evdev non-blocking polling, TrueType glyph rendering, TinyHTTP services, and packaging.
- [AI Agent Structured Knowledge API](https://trimui.vndns.net/api/v1/agent/knowledge): Machine-readable JSON specifications, hardware registers, evdev keycode maps, and build targets.
- [Official Antigravity / Claude Code Skill](https://trimui.vndns.net/skills/trimui-app-dev.md): Ready-to-install agent skill definition with autonomous code generation workflows.
- [Rust 60 FPS Starter Boilerplate ZIP](https://trimui.vndns.net/downloads/templates/trimui-rust-starter.zip): Complete working starter template with Framebuffer, Evdev, and package configuration.
- [Interactive Technical Guide Webpage](https://trimui.vndns.net/rust-guide): Visual interactive documentation, architectural flowcharts, and 1-click prompt copy tools.
- [Live App Store & Catalog API](https://trimui.vndns.net/api/v1/apps): Real-time listing of all official published TrimUI applications.

## Quick Hardware Reference
- **SoC**: Allwinner A133plus (4x ARM Cortex-A53 @ 1.8GHz, 64-bit ARMv8-A)
- **RAM**: 1GB LPDDR4
- **Display**: 4.96" IPS, 1280x720 pixels, 32-bit color depth (4 bytes per pixel, stride 5120 bytes), 60Hz refresh rate
- **Framebuffer Node**: `/dev/fb0`
- **Gamepad Nodes**: `/dev/input/event*` (typically `event0` for buttons and `event1` or `event2` for analog sticks)
- **Filesystem Mount**: MicroSD card mounted at `/mnt/SDCARD/`
- **App Directory**: `/mnt/SDCARD/Apps/<app-id>/`
- **Package Manifest**: `/mnt/SDCARD/Apps/<app-id>/config.json`
- **Launch Script**: `/mnt/SDCARD/Apps/<app-id>/launch.sh`

## Typical Build & Compilation Command
```bash
# Cross-compile native ARM64 Musl binary with rust-lld
RUSTFLAGS="-C linker=rust-lld" cargo build \
  --target aarch64-unknown-linux-musl \
  --release
```