docs: add bilingual AXPR23 build guides

README.md

@@ -1,29 +1,65 @@
-# AXP_Resurection
+# AXP Resurrection — AXPR23
 
-Personal **AXP.OS resurrection** on LineageOS 23.2 / Android 16 for Google
-Pixel 4a (`sunfish`): Magisk like GOLDEN, full AXP capability set, Spec Kit
-feature `009-axp-los23-port`.
+**AXPR23** is a finished Android 16 ROM project for the Google Pixel 4a
+(`sunfish`). It recreates the AXP.OS user experience on top of LineageOS 23.2,
+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 /
-split-roadmap standby). Same Spec Kit / docs home pattern; **not** a
-SSYSTEMS / buildout-saar project.
+This is an **archive and reference implementation**. AXPR23 is EOL: LineageOS
+23.2 no longer receives new sunfish nightlies. New Android work belongs to the
+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`
-- Builds stay on the A16 `rom-dev01` worker; local checkouts are used for
-  development and device tooling.
-- The sibling KernelSU/split-roadmap tree remains a separate track.
+| Language | Guide |
+|---|---|
+| Español | [`README.es.md`](README.es.md) |
+| 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`
-- Plan: `specs/009-axp-los23-port/plan.md`
+## Repository and architecture
 
-## 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`
-- Agent rules: `AGENTS.md`
-- Specs: `specs/README.md`
-- Device roles (GOLDEN vs LAB): `docs/device-roles.md`
-- AXP Pro parity matrix (non-normative): `docs/axp-pro-parity.md`
+## Important limitations
+
+The public repository contains source, patches, scripts and documentation. It
+does **not** contain release keys, proprietary APKs, Google/Qualcomm blobs,
+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.