From 6cf56aa8f7f7673c17b5437663e0265ec3b067dd Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Michael=20Loipf=C3=BChrer?= <michael.loipfuehrer@stusta.de>
Date: Tue, 4 Aug 2026 18:18:49 +0200
Subject: [PATCH] docs(cli): add a dedicated readme to be packaged with our
 pypi package

---
 packages/debmagic/README.md      | 70 ++++++++++++++++++++++++++++++++
 packages/debmagic/pyproject.toml |  4 +-
 2 files changed, 72 insertions(+), 2 deletions(-)
 create mode 100644 packages/debmagic/README.md

diff --git a/packages/debmagic/README.md b/packages/debmagic/README.md
new file mode 100644
index 0000000..8deaf3b
--- /dev/null
+++ b/packages/debmagic/README.md
@@ -0,0 +1,70 @@
+# Debmagic
+
+Modern, robust & easy tooling for building and packaging [Debian](https://debian.org)/[Ubuntu](https://ubuntu.com) packages — while staying backwards compatible.
+
+- **Build any package** in an isolated container environment with `debmagic build`
+- **Test and lint** with `debmagic test` and `debmagic check`
+- **Debug** build environments interactively with `debmagic shell`
+
+## Installation
+
+```shell
+pip install debmagic
+```
+
+or run it directly:
+
+```shell
+uvx debmagic
+```
+
+## Quickstart
+
+Build any Debian-packaged source tree in an isolated environment:
+
+```shell
+cd your-package
+debmagic build binary --driver lxd \
+  --output-dir /tmp/build-artifacts
+```
+
+Pick a driver explicitly — there's no auto-detection:
+
+| Driver | Check it's available | Isolation |
+|---|---|---|
+| `lxd` / `incus` | `lxc list` / `incus list` | Full container isolation |
+| `docker` | `docker info` | Full container isolation |
+| `bare` | none (no daemon) | None — only use in a disposable/CI environment |
+
+Create a source package (`.dsc`) without compilation:
+
+```shell
+debmagic build source
+```
+
+### Useful options
+
+- `--distro <codename>` — select the target distro/release (e.g. `trixie`, `noble`) if the changelog is ambiguous
+- `--persistent` — retain the build environment for repeated attempts
+- `--incremental` — sync only changed sources for faster rebuilds; implies `--persistent`
+- `--sign` — GPG-sign the resulting `.changes`/`.dsc`/`.buildinfo` with `debsign`
+- `--apt-mirror <url>` — use a faster mirror for build-dependency resolution
+
+Any of these can be persisted in a `debmagic.toml` config file instead of repeating CLI flags.
+
+### Inspecting a failed build
+
+Failed builds tear down their environment by default. Build with `--persistent` up front, then attach an interactive shell inside the build environment:
+
+```shell
+debmagic shell
+```
+
+## Documentation
+
+For the full documentation — the [build quick reference](https://debmagic.readthedocs.io/en/latest/usage/build.html), 
+packaging guides, configuration and module references — visit **[debmagic.readthedocs.io](https://debmagic.readthedocs.io)**.
+
+## License
+
+Released under the **GNU General Public License** version 2 or later.
diff --git a/packages/debmagic/pyproject.toml b/packages/debmagic/pyproject.toml
index 6d09005..3bc3d05 100644
--- a/packages/debmagic/pyproject.toml
+++ b/packages/debmagic/pyproject.toml
@@ -5,10 +5,10 @@ build-backend = 'maturin'
 [project]
 name = "debmagic"
 version = "0.0.1-alpha.5"
-description = "build debian packages"
+description = "modern tooling for building and packaging Debian/Ubuntu packages in isolated environments"
 license = "GPL-2.0-or-later"
 # license-files = ["../../LICENSE"]
-# readme = "../../README.md"
+readme = "README.md"
 requires-python = ">=3.12"
 classifiers = ["Programming Language :: Python :: 3"]