# Vanta — Android 17 for the Galaxy Z Flip5 and as a GSI

A custom Android 17 ROM built on **LineageOS `lineage-24.0`** (real `android-17.0.0_r1`) with our
own UI, branding and feature layer over every surface the user sees — boot animation, recovery,
fonts, SystemUI, launcher, the Flip5's cover screen, setup, Settings strings.

| Target | Profile | Output | State |
|---|---|---|---|
| Galaxy Z Flip5 (SM-F731B) | `devices/b5q.env` | `Vanta-<ver>-<date>-b5q.zip` | default build |
| GSI, any arm64 Treble phone | `devices/gsi_arm64.env` | `Vanta-<ver>-<date>-gsi_arm64.img.xz` | builds from the same layer |
| Galaxy S10+ (SM-G975F) | `devices/beyond2lte.env` | `Vanta-<ver>-<date>-beyond2lte.zip` | **cancelled 2026-10-11**, kept buildable |

BUILD.md is how a build host runs it.

## How the pieces fit

```
LineageOS 24.0 source (repo init -u LineageOS/android -b lineage-24.0)
 + manifest/<device>.xml       Flip5: official Lineage sm8550-common/kernel/hardware/common blobs
                               (lineage-24.0, maintained for the S23) + Exynoobs b5q tree + blobs
                               (lineage-23.2, pinned by full SHA). GSI: no local manifest.
 + vendor/extra/product.mk     Lineage's own override hook, inherited FIRST
     -> vendor/vanta/vanta.mk  apps, overlays, brand RROs, fonts, tones, boot animation
 + patches/                    SystemUI (12) + recovery palette/title
 + tools/recovery.sh           recovery header + install animation, by file name
 (S10 only: device/uprev.py, kernel/ksu.sh + vanta.config)
```

**vendor/lineage is not patched.** `vendor/lineage/config/common.mk` inherits
`vendor/extra/product.mk` before anything else; `lineage_gsi_arm64` reaches it through
`lineage_generic_target.mk`. `tools/verify_tree.py` checks the hooks, the modules Vanta
overrides, every overlaid name, and per device what its makefiles inherit, after every sync.

## Stages and gates

Every gate has to pass before the next stage starts. A gate is either a script
that can fail (`tools/check.sh`, `tools/verify_tree.py`, `tools/gate.sh`) or
something Zandy looks at.

### Stage 0: here, on Zo (done)

`tools/check.sh` passes with no build box and no phone. It runs the uprev on the
real pinned 23.2 files, checks the tree assumptions against a verbatim slice of
LineageOS 24.0 (`tools/fixtures/lineage-24.0`), builds the overlays and VantaSetup with the SDK, unit-tests
the theme merge, and drives `tools/gate.sh` against a fake adb. Every gate is
also shown to fail on an injected fault.

### Stage 1: build host

- **G0 host**: `tools/preflight.sh` (≥16 cores, ≥64 GB RAM, ≥400 GB free,
  x86_64). The planned box is 64 cores / 512 GB. Then `tools/sync.sh`,
  `tools/apply.sh` (ends in `verify_tree.py`, which must be green).
- **G1 build**: `VANTA_DEVICE=b5q tools/host-run.sh` (or `gsi_arm64`) produces the
  zip / image named in the table above. A device-side break goes into a profile's
  uprev step as an anchored edit, never as a hand edit on the box.

### Stage 2: the phone (needs Zandy's go; flashing wipes it)

**Flashing wipes the phone.** Data is formatted. Lost until reinstalled: the s10
bridge enrolment, the KernelSU manager, module `s10_boot` (its identity is now
baked into the ROM, so it should not come back). Rollback is the Infinity 3.12
zip in `Projects/failure-s10/infinity-kit/`, sideloaded the same way.

Procedure is the 3.12 one from `Projects/failure-s10/README.md`: the build's
`recovery.img` via Download mode, format data, `adb sideload` the zip.

Then `tools/gate.sh`:

| Gate | What it proves |
|---|---|
| G1 | boots, Android 17, Vanta layer present |
| **G2** | **mobile data**: the framework sees 2 SIM slots, and a VALIDATED cellular network exists |
| G3 | identity: accent 35E0FF, IBM Plex, overlay on, 0.75 animation scale |
| G4 | desktop windowing on (DP-alt glasses) |
| G5 | KernelSU-Next in the kernel |

**G2 decides whether the project continues.** Mobile data is why the phone ran
Infinity 3.12 instead of LineageOS 23.2. `ril/README.md` has the evidence for the
fix we carry (one overlay line). If G2 fails anyway, build stock LineageOS 24.0
for `beyond2lte` with no Vanta layer. That tells us whether the bug is ours or is
in the Android 17 port itself.

Manual, by eye: boot animation, panel and touch, speakers and mic in a call,
fingerprint, glasses desktop.

### Stage 3: the overhaul (after G1–G5)

The full custom UI is patch work on SystemUI, Launcher3 and Settings, a patch
series in `patches/` applied by `tools/apply.sh`, checked against the
lineage-24.0 reference clones in `build/l24/` before it reaches the box. FEATURES.md
lists the tracks and what state each is in.

## What is a guess until hardware

- The 4.14 kernel on Android 17. It ran Android 16, and nothing found upstream
  says 17 drops it, but G1 decides.
- That one overlay line fixes mobile data (see above).
- KernelSU-Next's kprobes hook on this kernel (the LineageOS kernel has
  `CONFIG_KPROBES=y`).
