Skip to content

AGENTS.md

Latest commit

 

History

History
35 lines (30 loc) · 7.05 KB

AGENTS.md

File metadata and controls

35 lines (30 loc) · 7.05 KB
Raw

Paper Linux quick brief for AI Coding Agents

  • Goal: integrated Linux PDA OS for e-ink readers; current dev targets Kindle 3-class hardware (ARM11 ~532 MHz, 256 MB RAM, no GPU) but keep designs hardware-agnostic for future devices.
  • Build: buildroot-based, repo is a buildroot external tree, buildroot subdirectory is a git submodule; make changes (config files, new buildroot packages, patches) to the external tree (repo root), not the buildroot checkout.
  • Buildroot config workflow: when changing an existing output tree config, use just config <configuration> ... (a thin wrapper around buildroot/utils/config) instead of editing .config by hand, then refresh it via just build <configuration> olddefconfig. Direct buildroot/utils/config --file output/<board>/.config ... remains available for unusual cases.
  • Buildroot build workflow: prefer the project wrapper just build <configuration> [target ...] (for example just build kindle3_mainline olddefconfig, just build kindle3_mainline <pkg>, or just build kindle3_mainline <pkg>-rebuild). Direct targets through the generated Makefile in output/<configuration>/ remain valid (make -C output/kindle3_mainline, etc.); do not invoke make -C buildroot ... directly for normal board builds because the output-tree Makefile already carries the correct O= and BR2_EXTERNAL= wiring.
  • Patch files: for the manual workflow, edit a copy directly and generate the patch via diff -u; always add an email-style header to .patch files. For a Paper Resources package workspace, use ordinary Git commits and its workspace export operation, which deliberately uses git format-patch and preserves the managed destination notes.
  • Commits: use descriptive Conventional Commit-style messages; use git commit -m multiple times (first for the subject, then a description of what the commit does and why it was needed when relevant).
  • Resource policy: musl, busybox, shared libs, dropbear, CLI/TUI-first; avoid heavy daemons and GUIs.
  • External resources: Paper Resources is this project's custom MCP server and CLI for reference documents, immutable source revisions, provenance, and indexed code navigation. Prefer its MCP tools when available and read the authoritative paper-resource://help resource before a substantial hardware or kernel-archaeology investigation; the same guide is stored at tools/paper-resources/src/paper_resources/agent-guide.md. Use equivalent just resource ... commands when MCP is unavailable.
  • Kernel policy: prefer upstream kernels where hardware support is practical, but preserve vendor-kernel configurations where needed. The Kindle 3 vendor target uses Linux 2.6.26 RT and therefore expects old syscalls/APIs; keep those compatibility changes inside its selected patch layers and keep the syscall ABI intact when patching headers. Mainline targets must not select the 2.6.26 compatibility layer.
  • Patch layering: every defconfig explicitly composes BR2_GLOBAL_PATCH_DIR from global, kernel-compatibility, board-common, and board-variant layers as needed. Follow patches/README.md; do not make board- or kernel-specific patches global.
  • Current state: custom chroot with modern musl, busybox, wpa_supplicant, OpenSSL, curl, etc.; some patches applied. Aim to grow into full flashable OS (kernel + bootloader + userland).
  • System glue: prefer built-in tools—busybox init/mdev/uevent helpers; no systemd or heavyweight supervisors.
  • UX target: tinkerers/power users wanting distraction-free, keyboarded, pocket e-ink Linux for reading, notes, SSH, small terminal apps; battery life and low write/refresh churn are critical.
  • Roadmap highlights: Emacs (possibly fbink GUI backend); session manager for launching, focus/display/keyboard arbitration, background pause, LRU killing; slim networking daemon using wpa_supplicant + netlink + busybox udhcpcd with lease-based radio control; power daemon; e-ink-optimized home screen and file manager.
  • Design reminders: e-ink refresh latency is hundreds of ms; flash is slow; memory is tight; minimize radios-on time; be frugal with RAM/CPU and filesystem writes.
  • Docs tone: stay generalized to e-ink readers—refer to “Kindle 3-class” only when necessary; avoid implying the project is Kindle-only.

External resource workflow

  • Configuration is machine-specific and gitignored: inspect it with just resource env and discover the resolved directory with just resource path; never assume a developer path. Population remains CLI-only through just resource populate and just resource check.
  • For hardware-enablement questions, use search_hardware_references when code and datasheets may both matter. Cite document manifest IDs with physical pages or sections, and distinguish datasheet guarantees from board wiring and observed behavior.
  • For source archaeology, use search_code_tags for known language objects, search_source_text for register names, compatible strings, configuration symbols, log text, and other literals, and outline_file before reading large files. Direct rg is still appropriate for a quick search in one worktree.
  • Compare bounded summaries and definitions before reading diffs: use compare_revisions, compare_file_outlines, or compare_symbol_definitions, then request only a selected tag region or one file. Use history, blame, and identical-blob tools when the question is about origin or change over time.
  • Treat derived_from as exact ancestry. reference_base is approximate and its reason must accompany conclusions. Identical content does not by itself prove authorship, and code presence does not prove runtime use.
  • Git revisions are authoritative. The Ctags index is selective, so a missing tag is not proof that source is absent; use describe_file_index and Git-backed search or line reading when necessary. Public selectors are human-readable repository, revision, and path; tag IDs are opaque and database-local.

Near-term engineering plans

  • Init/boot: stick with BusyBox init; generate rcS ordering at boot from /etc/paper/services.dep via tsort; keep scripts simple (start|stop|restart|status); prefer start-stop-daemon; no runtime supervision.
  • Networking daemon: orchestrates wpa_supplicant + busybox udhcpc; lease-based radio control so Wi-Fi powers up only when a lease is held; coordinates with session manager for user UI. netctl or similar command to request, renew, and release leases holding the network online.
  • Session manager (home/launcher/compositor): owns framebuffer; keeps apps off /dev/fb0; reads evdev directly and re-emits via uinput; TUIs run on PTYs; GUIs render to shared memory and send damage rects; arbitrates focus, refresh, freeze/thaw, LRU kill; protect it with high OOM priority.
  • App sandboxes/portal: per-app mount+net namespaces when available; default view is minimal; paperfm acts as portal for open/save—session manager opens files and passes fds (SCM_RIGHTS) or bind-mounts selected paths into the app namespace; optional full-FS toggle.
  • File manager/home: custom e-ink-friendly file manager (paperfm) plus lightweight home UI (not Emacs) integrated with the session manager and portal flow.