docs: add bilingual AXPR23 build guides

README.en.md

@@ -0,0 +1,225 @@
+# AXPR23 — user and build guide
+
+## 1. Introduction
+
+AXPR23 is a finished ROM for the **Google Pixel 4a (`sunfish`)**, based on
+LineageOS 23.2 / Android 16. The goal was to recover AXP.OS behaviour on a
+maintainable LineageOS base, not to create an unrelated generic ROM.
+
+The validated final line integrates, depending on the ship variant:
+
+- AXP packaging and Magisk preroot;
+- release signing and the project AVB posture;
+- microG and Google-compatibility adaptations;
+- AOSmium as the primary WebView provider;
+- attributed privacy, hardening and kernel changes under
+  `vendor/sunfish-a16/`;
+- project-defined product overlays and bundled applications.
+
+AXPR23 is **finished and EOL**. LineageOS no longer provides new 23.2 sunfish
+nightlies, so this must not be treated as a current-security release. AXPR24 /
+Android 17 is a separate line.
+
+## 2. What this repository contains
+
+The repository contains project source, patches, overlays, build scripts, tests
+and documentation. It does not contain:
+
+- Android or AVB private signing keys;
+- proprietary Google, microG, Magisk or WebView APKs;
+- Google/Qualcomm proprietary blobs or firmware;
+- full Android trees, `.repo`, `out/` or ccache;
+- generated or signed ROM ZIPs.
+
+This is intentional. To build your own image, obtain the required inputs
+lawfully and sign it with your own keys. Never copy another installation's
+private keys or publish proprietary APKs in Git.
+
+## 3. Main layout
+
+```text
+vendor/sunfish-a16/       AXPR23 product files, overlays and patches
+scripts/009-*.sh          build wrappers and postflight checks
+specs/009-axp-los23-port/ original scope and acceptance requirements
+docs/                     runbooks, evidence and decisions
+tests/                    automated project checks
+```
+
+The LineageOS source tree and build artifacts must stay outside this Git
+checkout, normally on a dedicated Linux build worker.
+
+## 4. Build-host requirements
+
+A complete build needs Linux x86_64 with substantial disk, memory and CPU. The
+validated historical worker used 8 vCPUs, roughly 62 GiB RAM, ccache and a
+large Android source tree. A laptop is not a suitable place for a full ROM
+build.
+
+Install the official LineageOS Android 16 dependencies plus Git, Git LFS,
+`repo`, Python 3, OpenJDK 17, `ccache`, and `adb`/`fastboot` if you will test
+the device. Always consult the official `sunfish` build page:
+<https://wiki.lineageos.org/devices/sunfish/build/>.
+
+## 5. Prepare LineageOS
+
+The last official pin used by AXPR23 is LineageOS 23.2 nightly `20261008`:
+
+```bash
+mkdir -p /srv/rom/src/lineage
+cd /srv/rom/src/lineage
+repo init \
+  -u https://github.com/LineageOS/android.git \
+  -b lineage-23.2 \
+  --git-lfs \
+  --no-clone-bundle
+repo sync -c -j8
+```
+
+Prepare the `sunfish` proprietary blobs according to LineageOS. Without them,
+the ROM may partially compile but it will not contain the complete Pixel
+hardware stack.
+
+For an exact historical rebuild, use the official `build-manifest.xml` from
+the selected nightly and record its SHA-256. Do not call a build reproducible
+if you only used a floating `lineage-23.2` branch without comparing revisions.
+
+## 6. Prepare AXPR23 inputs
+
+The maintainer must provide, outside Git, the APKs/blobs allowed by their
+licenses, the pinned Magisk/WebView versions and personal Android/AVB signing
+keys. The historical worker layout is:
+
+```text
+/srv/rom/src/lineage              LineageOS source tree
+/srv/rom/src/AXP_Resurection      this repository
+/srv/rom/prebuilts/                untracked inputs
+/srv/rom/secrets/android-certs/   private keys, host-only
+/srv/rom/ccache/                   compiler cache
+/srv/rom/artifacts/               generated ZIPs and manifests
+/srv/rom/logs/                    build logs
+```
+
+Several historical wrappers assume this layout; review them before relocating
+the tree.
+
+## 7. Run the build
+
+First make sure no other build uses the same `out/` directory. Never run two
+Ninja processes against one output tree:
+
+```bash
+cd /srv/rom/src/AXP_Resurection
+git checkout 009-axp-los23-port
+git status --short
+export LINEAGE_TREE=/srv/rom/src/lineage
+export AXP_PROJECT_SOURCE=/srv/rom/src/AXP_Resurection
+export LOS_SYNC=0
+export LOS_DATE=20261008
+bash scripts/009-rebuild-from-los.sh
+```
+
+The canonical entry point verifies the tree, records the manifest, copies
+`vendor/sunfish-a16/`, applies the kernel/userspace/product/WebView layers,
+builds the required `hardened_malloc` components, runs the release bacon and
+executes the post-build gates.
+
+To resync and pin every project, provide an official manifest and opt in:
+
+```bash
+export LOS_SYNC=1
+export LOS_MANIFEST=/path/to/build-manifest.xml
+export LOS_DATE=20261008
+bash scripts/009-rebuild-from-los.sh
+```
+
+`LOS_SYNC=1` cleans Android project worktrees before syncing. Do not use it over
+unsaved local changes. If the manifest is missing, the script must fail; do not
+replace the pin with a floating branch.
+
+## 8. Run long builds safely
+
+Do not leave `mka` attached to a laptop SSH session. Use `tmux`, systemd or the
+worker's detach wrapper:
+
+```bash
+tmux new -s axpr23-build
+cd /srv/rom/src/AXP_Resurection
+export AXP_PROJECT_SOURCE=/srv/rom/src/AXP_Resurection
+export LOS_SYNC=0
+export LOS_DATE=20261008
+bash scripts/009-rebuild-from-los.sh 2>&1 | tee /srv/rom/logs/axpr23-build.log
+```
+
+Detach with `Ctrl-b d` and reattach with `tmux attach -t axpr23-build`. The
+historical worker also used `/srv/rom/artifacts/bin/rom-detach`.
+
+## 9. Verify the output
+
+Do not accept a build merely because it exits with code 0:
+
+```bash
+find /srv/rom/artifacts/009-axp-los23-port -type f -name '*.zip' -print
+sha256sum /path/to/AXP-Resurection-Pro-23.2-YYYYMMDD-sunfish.zip
+unzip -t /path/to/AXP-Resurection-Pro-23.2-YYYYMMDD-sunfish.zip
+repo -C /srv/rom/src/lineage manifest -r \
+  -o /srv/rom/artifacts/009-axp-los23-port/manifest-final.xml
+```
+
+Check the ZIP name and SHA-256, `FLASH_READY`, release signing rather than
+test-keys, Magisk preroot, AOSmium WebView, microG/Phonesky, expected apps,
+SPL and build properties. There must be no patch errors, `.rej` files or
+silently omitted components. The full gate list is in
+[`docs/009-ota-rebuild-checklist.md`](docs/009-ota-rebuild-checklist.md).
+
+## 10. Sideload to a test device
+
+Only do this on an unlocked Pixel with a backup, and never as the first step on
+a personal phone:
+
+```bash
+adb devices
+adb reboot recovery
+```
+
+In recovery select **Apply update from ADB**, then run:
+
+```bash
+adb sideload /path/to/AXP-Resurection-Pro-23.2-YYYYMMDD-sunfish.zip
+```
+
+After the first boot:
+
+```bash
+adb shell getprop ro.product.device
+adb shell getprop ro.lineage.version
+adb shell getprop ro.build.type
+adb shell getprop ro.build.tags
+adb shell pm list packages | grep -E 'gms|finsky|aosmium|jelly'
+```
+
+Complete the boot, radio/Wi-Fi, storage, Magisk, Island/work-profile, WebView
+and bundled-app smoke tests before accepting the ZIP.
+
+## 11. Rollback and common failures
+
+Keep the last known-good ROM, the stock/rescue ZIP, the manifest and SHA-256 of
+each attempt, plus recovery and fastboot access. If a build does not boot, do
+not wipe data immediately: capture boot reason, A/B slot, available `logcat`,
+`dmesg` and verity/AVB state, then return to the known-good ZIP.
+
+| Symptom | Usual cause | Action |
+|---|---|---|
+| Release keys are missing | Keys are not distributed | Configure host-only keys of your own |
+| `vendor/sunfish-a16` is missing | `AXP_PROJECT_SOURCE` was not set | Run the wrapper from a valid checkout |
+| `repo sync` fails | Object-store drift or dirty worktree | Save changes and use `--force-sync` only on Android sources |
+| APK or JNI inputs are missing | Untracked prebuilts were not prepared | Check the worker inventory and reject corrupt files |
+| `.rej` files or missing markers | A patch no longer matches | Stop and port the patch explicitly |
+| ZIP uses test-keys | Release identity is absent | Do not flash it as a release; fix signing and rebuild |
+
+## 12. References
+
+- [LineageOS — build sunfish](https://wiki.lineageos.org/devices/sunfish/build/)
+- [`docs/009-eol-20261026.md`](docs/009-eol-20261026.md)
+- [`docs/009-ota-rebuild-checklist.md`](docs/009-ota-rebuild-checklist.md)
+- [`scripts/009-rebuild-from-los.sh`](scripts/009-rebuild-from-los.sh)
+- [`specs/009-axp-los23-port/spec.md`](specs/009-axp-los23-port/spec.md)

README.es.md

@@ -0,0 +1,225 @@
+# AXPR23 — guía de usuario y compilación
+
+## 1. Introducción
+
+AXPR23 es una ROM terminada para el **Google Pixel 4a (`sunfish`)**, basada en
+LineageOS 23.2 / Android 16. El objetivo fue recuperar el comportamiento de
+AXP.OS sobre una base LineageOS mantenible, no crear una ROM genérica desde
+cero.
+
+La línea final validada integra, según la variante de publicación:
+
+- empaquetado AXP y preroot Magisk;
+- firma de release y configuración AVB del proyecto;
+- adaptaciones de compatibilidad de microG y Google;
+- AOSmium como proveedor principal de WebView;
+- cambios de privacidad, hardening y kernel en `vendor/sunfish-a16/`;
+- overlays de producto y aplicaciones incluidas por el proyecto.
+
+AXPR23 está **finalizado y en EOL**. LineageOS ya no mantiene una rama 23.2
+nueva para `sunfish`, por lo que no debe considerarse una ROM con parches de
+seguridad actuales. AXPR24 / Android 17 es una línea separada.
+
+## 2. Qué contiene este repositorio
+
+Sí contiene código, parches, overlays, scripts, tests y documentación del
+proyecto. No contiene:
+
+- claves privadas de firma o AVB;
+- APK propietarios de Google, microG, Magisk o WebView;
+- blobs propietarios de Google/Qualcomm ni firmware;
+- árboles completos de Android, `.repo`, `out/` o ccache;
+- ZIPs de ROM generados.
+
+Esto es intencionado. Para generar una imagen propia hay que conseguir los
+insumos de forma legal y firmarla con claves propias. No se deben copiar claves
+de otra instalación ni publicar APK propietarios en Git.
+
+## 3. Estructura principal
+
+```text
+vendor/sunfish-a16/       overlays, product files y parches AXPR23
+scripts/009-*.sh          wrappers de build y postflight
+specs/009-axp-los23-port/ alcance funcional y aceptación
+docs/                     runbooks, evidencias y decisiones
+tests/                    comprobaciones automáticas del proyecto
+```
+
+El árbol LineageOS y sus artefactos deben vivir fuera del checkout, en un
+worker Linux dedicado.
+
+## 4. Requisitos del build host
+
+La compilación completa necesita Linux x86_64, mucho espacio libre, memoria y
+CPU. La configuración histórica validada usaba 8 vCPU, unos 62 GiB de RAM,
+ccache y un árbol Android grande. Un portátil no es un buen lugar para el build
+completo.
+
+Instala las dependencias oficiales de LineageOS para Android 16 y Git, Git LFS,
+`repo`, Python 3, OpenJDK 17, `ccache` y las herramientas `adb`/`fastboot` si
+vas a probar el dispositivo. Consulta siempre la guía oficial de `sunfish`:
+<https://wiki.lineageos.org/devices/sunfish/build/>.
+
+## 5. Preparar LineageOS
+
+El último pin oficial usado por AXPR23 corresponde al nightly `20261008` de
+LineageOS 23.2:
+
+```bash
+mkdir -p /srv/rom/src/lineage
+cd /srv/rom/src/lineage
+repo init \
+  -u https://github.com/LineageOS/android.git \
+  -b lineage-23.2 \
+  --git-lfs \
+  --no-clone-bundle
+repo sync -c -j8
+```
+
+Prepara después los blobs propietarios de `sunfish` siguiendo LineageOS. Sin
+ellos la ROM puede compilar parcialmente, pero no tendrá el stack completo de
+hardware del Pixel.
+
+Para una reconstrucción histórica exacta, usa el `build-manifest.xml` oficial
+del nightly elegido y conserva su SHA-256. No llames reproducible a un build
+basado solo en una rama flotante sin comparar revisiones.
+
+## 6. Preparar los insumos AXPR23
+
+El maintainer debe proporcionar fuera de Git los APK/blobs permitidos por sus
+licencias, las versiones fijadas de Magisk/WebView y sus propias claves de
+firma Android y AVB. El layout histórico del worker es:
+
+```text
+/srv/rom/src/lineage              árbol LineageOS
+/srv/rom/src/AXP_Resurection      este repositorio
+/srv/rom/prebuilts/                insumos no versionados
+/srv/rom/secrets/android-certs/   claves privadas, solo host
+/srv/rom/ccache/                   ccache
+/srv/rom/artifacts/               ZIPs y manifiestos generados
+/srv/rom/logs/                    logs de build
+```
+
+Varios wrappers históricos asumen este layout; revísalos antes de moverlo.
+
+## 7. Ejecutar el build
+
+Comprueba primero que no haya otro build usando el mismo `out/`. Desde el
+checkout del proyecto:
+
+```bash
+cd /srv/rom/src/AXP_Resurection
+git checkout 009-axp-los23-port
+git status --short
+export LINEAGE_TREE=/srv/rom/src/lineage
+export AXP_PROJECT_SOURCE=/srv/rom/src/AXP_Resurection
+export LOS_SYNC=0
+export LOS_DATE=20261008
+bash scripts/009-rebuild-from-los.sh
+```
+
+La entrada canónica comprueba el árbol, captura el manifiesto, copia
+`vendor/sunfish-a16/`, aplica kernel/userspace/product/WebView, compila los
+componentes necesarios de `hardened_malloc`, ejecuta el bacon de release y
+corre los gates post-build.
+
+Para sincronizar y pinnear todos los proyectos se necesita un manifest oficial:
+
+```bash
+export LOS_SYNC=1
+export LOS_MANIFEST=/ruta/al/build-manifest.xml
+export LOS_DATE=20261008
+bash scripts/009-rebuild-from-los.sh
+```
+
+`LOS_SYNC=1` limpia los worktrees Android antes de sincronizar. No lo uses sobre
+cambios locales sin guardar. Si falta el manifiesto, el script debe fallar; no
+lo sustituyas por una rama flotante.
+
+## 8. Builds largos
+
+No dejes un `mka` unido a una sesión SSH del portátil. Usa `tmux`, systemd o el
+wrapper de detach del worker:
+
+```bash
+tmux new -s axpr23-build
+cd /srv/rom/src/AXP_Resurection
+export AXP_PROJECT_SOURCE=/srv/rom/src/AXP_Resurection
+export LOS_SYNC=0
+export LOS_DATE=20261008
+bash scripts/009-rebuild-from-los.sh 2>&1 | tee /srv/rom/logs/axpr23-build.log
+```
+
+Desconecta con `Ctrl-b d` y vuelve a entrar con `tmux attach -t axpr23-build`.
+El worker histórico también usaba `/srv/rom/artifacts/bin/rom-detach`.
+
+## 9. Verificar el resultado
+
+No aceptes un build solo porque termine con código 0:
+
+```bash
+find /srv/rom/artifacts/009-axp-los23-port -type f -name '*.zip' -print
+sha256sum /ruta/al/AXP-Resurection-Pro-23.2-YYYYMMDD-sunfish.zip
+unzip -t /ruta/al/AXP-Resurection-Pro-23.2-YYYYMMDD-sunfish.zip
+repo -C /srv/rom/src/lineage manifest -r \
+  -o /srv/rom/artifacts/009-axp-los23-port/manifest-final.xml
+```
+
+Revisa nombre y SHA-256, `FLASH_READY`, firma de release, Magisk preroot,
+AOSmium WebView, microG/Phonesky, aplicaciones esperadas, SPL y propiedades de
+build. Debe haber cero errores de patch, `.rej` o componentes omitidos. La
+lista completa está en [`docs/009-ota-rebuild-checklist.md`](docs/009-ota-rebuild-checklist.md).
+
+## 10. Sideload de prueba
+
+Hazlo solo en un Pixel desbloqueado, con copia de seguridad y nunca como primer
+paso en un teléfono personal:
+
+```bash
+adb devices
+adb reboot recovery
+```
+
+En recovery selecciona **Apply update from ADB** y ejecuta:
+
+```bash
+adb sideload /ruta/al/AXP-Resurection-Pro-23.2-YYYYMMDD-sunfish.zip
+```
+
+Tras arrancar:
+
+```bash
+adb shell getprop ro.product.device
+adb shell getprop ro.lineage.version
+adb shell getprop ro.build.type
+adb shell getprop ro.build.tags
+adb shell pm list packages | grep -E 'gms|finsky|aosmium|jelly'
+```
+
+Completa el smoke test de boot, radio/Wi-Fi, almacenamiento, Magisk,
+Island/perfil de trabajo, WebView y aplicaciones antes de aceptar el ZIP.
+
+## 11. Rollback y fallos frecuentes
+
+Conserva la última ROM que arrancaba, el ZIP stock/rescue, el manifiesto y el
+SHA-256 de cada intento, además del acceso a recovery y fastboot. Si no arranca,
+no borres datos inmediatamente: captura boot reason, slot A/B, `logcat`,
+`dmesg` disponible y estado de verity/AVB; después vuelve al ZIP conocido como
+bueno.
+
+| Síntoma | Causa habitual | Acción |
+|---|---|---|
+| Faltan claves de release | No se distribuyen con el proyecto | Configura claves propias solo en el host |
+| Falta `vendor/sunfish-a16` | No se definió `AXP_PROJECT_SOURCE` | Ejecuta el wrapper desde un checkout válido |
+| Falla `repo sync` | Drift u worktree sucio | Guarda cambios y usa `--force-sync` solo en el árbol Android |
+| Faltan APK o JNI | Prebuilts no preparados | Revisa el inventario del worker y rechaza archivos corruptos |
+| `.rej` o marcador ausente | El parche no coincide | Detén el build y adapta el parche explícitamente |
+| ZIP con test-keys | Identidad de release ausente | No lo flashees como release; corrige y repite |
+
+## 12. Referencias
+
+- [LineageOS — build sunfish](https://wiki.lineageos.org/devices/sunfish/build/)
+- [`docs/009-eol-20261026.md`](docs/009-eol-20261026.md)
+- [`docs/009-ota-rebuild-checklist.md`](docs/009-ota-rebuild-checklist.md)
+- [`scripts/009-rebuild-from-los.sh`](scripts/009-rebuild-from-los.sh)
+- [`specs/009-axp-los23-port/spec.md`](specs/009-axp-los23-port/spec.md)

README.md

@@ -1,29 +1,65 @@
-# AXP_Resurection
+# AXP Resurrection — AXPR23
 
-Personal **AXP.OS resurrection** on LineageOS 23.2 / Android 16 for Google
+**AXPR23** is a finished Android 16 ROM project for the Google Pixel 4a
-Pixel 4a (`sunfish`): Magisk like GOLDEN, full AXP capability set, Spec Kit
+(`sunfish`). It recreates the AXP.OS user experience on top of LineageOS 23.2,
-feature `009-axp-los23-port`.
+while preserving the parts that matter on real hardware: Magisk preroot,
+release signing, AXP-style packaging, hardened userspace/kernel changes,
+microG/Google compatibility, AOSmium WebView and the bundled application
+surface.
 
-This tree is a **parallel product track** to `sunfish-a16-rom` (KernelSU /
+This is an **archive and reference implementation**. AXPR23 is EOL: LineageOS
-split-roadmap standby). Same Spec Kit / docs home pattern; **not** a
+23.2 no longer receives new sunfish nightlies. New Android work belongs to the
-SSYSTEMS / buildout-saar project.
+separate AXPR24 / Android 17 line and must not be mixed into this branch.
 
-## Project locations
+## Read this first
 
-- Public canonical repository: `https://gitea.vbits.me/sunfish-admin/AXP-Resurection`
+| Language | Guide |
-- Builds stay on the A16 `rom-dev01` worker; local checkouts are used for
+|---|---|
-  development and device tooling.
+| Español | [`README.es.md`](README.es.md) |
-- The sibling KernelSU/split-roadmap tree remains a separate track.
+| English | [`README.en.md`](README.en.md) |
 
-## Active feature
+The language guides explain what the project is, what is and is not included,
+how to prepare a build host, how to run the reproducible build wrapper, how to
+verify the resulting ZIP and how to sideload or recover safely.
 
-- Spec: `specs/009-axp-los23-port/spec.md`
+## Repository and architecture
-- Plan: `specs/009-axp-los23-port/plan.md`
 
-## Quick links
+- Canonical public repository: <https://gitea.vbits.me/sunfish-admin/AXP-Resurection>
+- Final branch: `009-axp-los23-port`
+- Target device: Pixel 4a / `sunfish`
+- Base: LineageOS 23.2 / Android 16
+- Build worker: a dedicated Linux host; do not build the full ROM on a laptop
+- Android source tree and build output: kept outside this Git repository
+- The sibling KernelSU/split-roadmap tree is a separate project
 
-- Constitution: `.specify/memory/constitution.md`
+## Important limitations
-- Agent rules: `AGENTS.md`
+
-- Specs: `specs/README.md`
+The public repository contains source, patches, scripts and documentation. It
-- Device roles (GOLDEN vs LAB): `docs/device-roles.md`
+does **not** contain release keys, proprietary APKs, Google/Qualcomm blobs,
-- AXP Pro parity matrix (non-normative): `docs/axp-pro-parity.md`
+build output, `out/`, ccache, device dumps or signed ROM ZIPs. A clean clone is
+therefore not, by itself, sufficient to reproduce the shipped binary: the
+builder must supply those inputs legally and use its own signing keys.
+
+AXPR23 is not a current-security release. Use it for preservation, study and
+the already validated reference device; use the AXPR24 project for new Android
+17 work.
+
+## Key documentation
+
+- [`docs/009-eol-20261026.md`](docs/009-eol-20261026.md) — final artifact and
+  verified state
+- [`docs/003-build-notes.md`](docs/003-build-notes.md) — vanilla Lineage build
+  background
+- [`docs/009-ota-rebuild-checklist.md`](docs/009-ota-rebuild-checklist.md) —
+  maintainer preflight and postflight gates
+- [`scripts/009-rebuild-from-los.sh`](scripts/009-rebuild-from-los.sh) —
+  canonical AXPR23 rebuild entry point
+- [`specs/009-axp-los23-port/spec.md`](specs/009-axp-los23-port/spec.md) —
+  functional scope and acceptance requirements
+
+## License and upstream work
+
+This repository is a project layer over LineageOS/AOSP and other upstream
+components. Each upstream component retains its own license. Do not assume
+that the project repository grants redistribution rights for proprietary blobs,
+Google applications, firmware or signing material.