diff --git a/README.md b/README.md
index 2002c2d..917c588 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,92 @@
# build_manifests
-device manifests for a-team digital solutions
\ No newline at end of file
+Device manifests for the A-Team Jenkins build pipelines.
+
+Each build job clones this repo, drops one device XML into `.repo/local_manifests/` of a warm source tree, syncs only the projects listed in it, and reads the device info from its annotations.
+
+## Layout
+
+**One branch per build base, one file per device.**
+
+```
+ofrp-12.1/ genevn.xml milanf.xml rtwo.xml ...
+twrp-12.1/ genevn.xml ...
+aera-16.0/ genevn.xml milanf.xml ...
+```
+
+A job points at a branch + file, e.g. `ofrp-12.1` / `genevn.xml`.
+
+## Device XML
+
+A standard repo local manifest, plus `ateam.*` annotations on the device tree project.
+
+```xml
+
+
+
+
+
+
+
+
+
+
+
+```
+
+### Annotations
+
+All four are required; the build stops if one is missing.
+
+| Annotation | Used for | Example |
+|---|---|---|
+| `ateam.model` | Release file name, portal device name | `XT2315` |
+| `ateam.device_name` | Portal device name | `Moto G Stylus 5G 2023` |
+| `ateam.manufacturer` | Portal | `Motorola` |
+| `ateam.partition` | Build target and flash target | `recovery` |
+
+`ateam.partition` must be one of:
+
+| Value | Builds |
+|---|---|
+| `recovery` | `recoveryimage` |
+| `boot` | `bootimage` |
+| `vendor_boot` | `vendorbootimage` |
+
+The portal shows the device as ` ()`.
+
+### Projects
+
+- List the device tree plus anything else the device needs (kernel, vendor, common trees).
+- Every project listed gets synced; nothing else in the base tree is touched.
+- Any git source works. Add another `` for GitHub or elsewhere; the device tree doesn't have to live on A-Team Forgejo.
+- Pin `revision` to the branch for that base (e.g. `ofrp-12.1`).
+- Don't add projects that override the base's own repos. Device-specific fixes go in the device trees.
+
+## Release naming
+
+Builds come out as:
+
+```
+-_A-Team__-.
+```
+
+plus a `.sha256` for each, e.g. `OFRP-12.1_A-Team_genevn_XT2315-261009.zip`.
+
+## Adding a device
+
+1. Clone and switch to the base branch:
+ ```
+ git clone ssh://git@ateam.gotadell.com/A-Team_Digital_Solutions/build_manifests.git
+ cd build_manifests
+ git checkout ofrp-12.1
+ ```
+2. Copy an existing XML to `.xml` and edit the projects and annotations.
+3. Commit and push.
+4. Create the Jenkins job (`-`, e.g. `OFRP-genevn`) pointing at the branch and file.
+
+## Adding a base
+
+Create a new branch named `-` (e.g. `shrp-12.1`) and add a device XML for each device built on it. Each base has its own copy of a device's XML, so update model or name changes on every branch that has that device.
diff --git a/avatrn.xml b/avatrn.xml
new file mode 100644
index 0000000..31635c8
--- /dev/null
+++ b/avatrn.xml
@@ -0,0 +1,13 @@
+
+
+
+
+
+
+
+
+
+
+
diff --git a/milanf.xml b/milanf.xml
new file mode 100644
index 0000000..cc3ddb8
--- /dev/null
+++ b/milanf.xml
@@ -0,0 +1,13 @@
+
+
+
+
+
+
+
+
+
+
+
diff --git a/mona.xml b/mona.xml
new file mode 100644
index 0000000..037e871
--- /dev/null
+++ b/mona.xml
@@ -0,0 +1,13 @@
+
+
+
+
+
+
+
+
+
+
+
diff --git a/rtwo.xml b/rtwo.xml
new file mode 100644
index 0000000..0171354
--- /dev/null
+++ b/rtwo.xml
@@ -0,0 +1,13 @@
+
+
+
+
+
+
+
+
+
+
+
diff --git a/sycamore_row_5G.xml b/sycamore_row_5G.xml
new file mode 100644
index 0000000..a2bb13d
--- /dev/null
+++ b/sycamore_row_5G.xml
@@ -0,0 +1,13 @@
+
+
+
+
+
+
+
+
+
+
+