diff --git a/DECISIONS.md b/DECISIONS.md
new file mode 100644
index 0000000..237a7ec
--- /dev/null
+++ b/DECISIONS.md
@@ -0,0 +1,13 @@
+# Decisions
+
+## 2026-04-20 – CI wipes all package versions before upload to kill DB zombies
+- **Who**: Dominik, ClaudeCode
+- **Why**: `paru -Syu` stopped offering `moonarch-git` updates after the r99 → r105 pkgver bump. Root cause: Gitea's Arch registry updates `moonarch.db` incrementally on upload, but does not evict old entries when a pkgver changes. `r99` lingered in the DB as a zombie — file already 404, but desc/sig still present — so clients saw `r99` as "latest" and never got `r105`. Not a one-off: every future pkgver bump would repeat the issue.
+- **Tradeoffs**: Delete-before-upload adds an HTTP round-trip per package and requires `read:package` on the registry token (`write:package` was already there for upload). Alternative was an admin-side DB scrub per zombie — unscalable and hostile to the user.
+- **How**: `build-and-publish.yaml` now lists every existing version of each built package via `GET /api/v1/packages/{owner}?type=arch&q={name}` and `DELETE`s them before the upload loop. jq installed on the runner as a dependency of the listing parser. The per-upload `DELETE` of the exact new version was removed (redundant).
+
+## 2026-04-20 – Register moongreet/moonset/sweet-cursors in the Arch registry
+- **Who**: Dominik, ClaudeCode
+- **Why**: These three packages were missing entirely from the registry — their last pkgver-bumps landed before the `build-and-publish` CI fixes (makedepends install, source-based PKGBUILD parse, multi-artifact upload). Without a new PKGBUILD change, the workflow never re-triggered, so they stayed absent.
+- **Tradeoffs**: Bumping `pkgrel` manually is a one-shot push. Alternative (wait for the next real upstream change) would have left packages uninstallable indefinitely.
+- **How**: Bumped `pkgrel` in each PKGBUILD, single commit, triggered the `build-and-publish` workflow.
diff --git a/README.md b/README.md
index 28a2f28..30db289 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,7 @@
 # Moonarch PKGBUILDs
 
-Arch Linux package builds for the Moonarch ecosystem. Use with [paru](https://github.com/Morganamilo/paru) as a custom AUR source.
+PKGBUILDs for the Moonarch ecosystem. Published as prebuilt Arch packages
+via the Gitea Package Registry at `gitea.moonarch.de`.
 
 ## Packages
 
@@ -14,20 +15,16 @@ Arch Linux package builds for the Moonarch ecosystem. Use with [paru](https://gi
 
 ## Setup
 
-Add to `~/.config/paru/paru.conf`:
+The Moonarch installer configures `/etc/pacman.conf` with:
 
 ```ini
 [moonarch]
-Url = https://gitea.moonarch.de/nevaforget/moonarch-pkgbuilds
+SigLevel = Required DatabaseOptional
+Server = https://gitea.moonarch.de/api/packages/nevaforget/arch/$repo/$arch
 ```
 
-Then sync the repository index:
-
-```bash
-paru -Sy --pkgbuilds
-```
-
-This downloads the PKGBUILDs from Gitea. Without this step, paru will not find the moonarch packages.
+No extra paru setup required — `pacman` and `paru` both resolve moonarch
+packages from the registry.
 
 ## Install
 
@@ -37,19 +34,41 @@ paru -S moonarch-git   # pulls in all ecosystem packages as dependencies
 
 ## Update
 
-Standard system upgrade picks up new versions automatically:
-
 ```bash
 paru -Syu
 ```
 
+Version bumps land in the registry automatically:
+
+1. Push on `main` of `moonarch`, `moongreet`, `moonlock`, or `moonset`
+   triggers the per-project `update-pkgver.yaml` — pkgver-bot commits a
+   fresh `pkgver` to the matching PKGBUILD here.
+2. That commit triggers `build-and-publish.yaml` (this repo): the runner
+   builds every changed PKGBUILD and uploads the artifacts to the Arch
+   registry. Before each upload all existing versions of the package are
+   deleted so the repo DB stays clean — see `build-and-publish.yaml` for
+   the rationale (zombie DB entries after pkgver changes).
+
+`sweet-cursors-git` has no upstream CI; bump its `pkgrel` manually when
+a rebuild is needed.
+
 ## Troubleshooting
 
-**"not downloaded (use -Sy --pkgbuilds to download)"**: Run `paru -Sy --pkgbuilds` to fetch the repo index.
-
-**"cannot update the lock file ... --locked was passed"**: The PKGBUILD cache is stale. Clear it and retry:
+**`paru -Syu` shows no update even though a new version was published**:
+check the repo DB has the new version.
 
 ```bash
-rm -rf ~/.cache/paru/clone/repo/moonarch
-paru -Sy --pkgbuilds && paru -S <package>
+curl -s https://gitea.moonarch.de/api/packages/nevaforget/arch/moonarch/x86_64/moonarch.db \
+  | tar -tz | grep <pkgname>
+```
+
+If only an old version appears there, the `build-and-publish` workflow
+did not run cleanly — inspect the latest run under
+`gitea.moonarch.de/nevaforget/moonarch-pkgbuilds/actions`.
+
+**File conflict on install** (`foo/bar exists in filesystem`): the file
+was placed manually before the package claimed ownership. Once:
+
+```bash
+paru -Syu --overwrite=/path/to/conflicting/file
 ```