1 files changed, 150 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..f9ed799
--- /dev/null
+++ b/README.md
@@ -0,0 +1,150 @@
+# Witryna
+
+Witryna is a minimalist Git-based static site deployment orchestrator.
+It listens for webhook triggers, pulls Git repositories, runs
+containerized build commands, and publishes static assets via atomic
+symlink switching.
+
+## How it works
+
+A webhook POST triggers Witryna to pull a Git repository (with
+automatic submodule initialization and Git LFS fetch), run a build
+command inside a container, copy the output to a timestamped directory,
+and atomically switch a symlink to the new build.
+Your web server serves files from the symlink — zero-downtime deploys.
+
+## Install
+
+Pre-built packages are available at
+[release.craftknight.com](https://release.craftknight.com/).
+
+From a `.deb` package (Debian/Ubuntu):
+
+    curl -LO https://release.craftknight.com/witryna_0.1.0-1_amd64.deb
+    sudo dpkg -i witryna_0.1.0-1_amd64.deb
+
+From an `.rpm` package (Fedora/RHEL):
+
+    curl -LO https://release.craftknight.com/witryna-0.1.0-1.x86_64.rpm
+    sudo rpm -i witryna-0.1.0-1.x86_64.rpm
+
+From a tarball (any Linux):
+
+    curl -LO https://release.craftknight.com/witryna-0.1.0-linux-amd64.tar.gz
+    tar xzf witryna-0.1.0-linux-amd64.tar.gz
+    sudo cp witryna-0.1.0-linux-amd64/witryna /usr/local/bin/
+
+From source:
+
+    cargo install --path .
+
+## Post-install
+
+The deb/rpm packages automatically detect your container runtime:
+
+- **Docker**: `witryna` user added to `docker` group, systemd override installed
+- **Podman**: subuids/subgids allocated, lingering enabled, systemd override installed
+- **Neither found**: warning with instructions
+
+If you install a runtime later, reinstall the package or manually copy the
+override from `/usr/share/doc/witryna/examples/systemd/` to
+`/etc/systemd/system/witryna.service.d/10-runtime.conf` and run
+`sudo systemctl daemon-reload`.
+
+## Quickstart
+
+1. Create `/etc/witryna/witryna.toml`:
+
+    ```toml
+    listen_address = "127.0.0.1:8080"
+    container_runtime = "podman"
+    base_dir = "/var/lib/witryna"
+    log_level = "info"
+
+    [[sites]]
+    name = "my-site"
+    repo_url = "https://github.com/user/my-site.git"
+    branch = "main"
+    webhook_token = "YOUR_TOKEN"  # omit to disable auth
+    ```
+
+2. Add a build config to the root of your Git repository (`.witryna.yaml`,
+   `.witryna.yml`, `witryna.yaml`, or `witryna.yml`):
+
+    ```yaml
+    image: node:20-alpine
+    command: "npm ci && npm run build"
+    public: dist
+    ```
+
+3. Start Witryna:
+
+    ```
+    witryna serve
+    ```
+
+4. Trigger a build:
+
+    ```
+    TOKEN=...  # your webhook_token from witryna.toml
+    curl -X POST -H "Authorization: Bearer $TOKEN" http://127.0.0.1:8080/my-site
+    # If webhook_token is omitted, the -H header is not needed.
+    ```
+
+## CLI
+
+| Command | Description |
+|---------|-------------|
+| `witryna serve` | Start the deployment server |
+| `witryna validate` | Validate config and print summary |
+| `witryna run <site>` | Run a one-off build (synchronous) |
+| `witryna status` | Show deployment status |
+
+## Configuration
+
+Witryna searches for its config file automatically: `./witryna.toml`,
+`$XDG_CONFIG_HOME/witryna/witryna.toml`, `/etc/witryna/witryna.toml`.
+Use `--config` to specify an explicit path.
+
+See `witryna.toml(5)` for the full configuration reference:
+
+    man witryna.toml
+
+Build config supports `.witryna.yaml`, `.witryna.yml`, `witryna.yaml`, and
+`witryna.yml` (searched in that order). See `examples/` for annotated files.
+
+## Reverse proxy
+
+Point your web server's document root at
+`/var/lib/witryna/builds/<site>/current` and reverse-proxy webhook
+requests to Witryna. See `examples/caddy/` and `examples/nginx/` for
+ready-to-use configurations.
+
+## Building from source
+
+    cargo build --release
+
+Development uses [just](https://github.com/casey/just) as a command runner:
+
+    cargo install just    # or: pacman -S just / brew install just
+
+Key recipes:
+
+    just test             # unit tests
+    just test-all         # lints + unit + integration tests
+    just lint             # fmt check + clippy + yamllint + gitleaks
+
+To build distribution packages:
+
+    just build-deb    # Debian .deb package
+    just build-rpm    # RPM package
+
+## Dependencies
+
+- Rust 1.85+ (build only)
+- Git
+- Podman or Docker
+
+## License
+
+MIT — see LICENSE for details.