diff --git a/docs/roadmap.md b/docs/roadmap.md
new file mode 100644
index 0000000..f7bc1e4
--- /dev/null
+++ b/docs/roadmap.md
@@ -0,0 +1,118 @@
+# HIY Roadmap
+
+## Goal
+
+A complete self-hosted PaaS that runs on any Linux hardware with zero external service
+dependencies. You own the git server, the build pipeline, the runtime, the reverse proxy,
+and the auth — all in one binary + Caddy.
+
+```
+git push hiy main   # deploy your app, nothing else needed
+```
+
+---
+
+## Current state
+
+| Feature | Status |
+|---|---|
+| Web dashboard | ✓ done |
+| App CRUD + env vars | ✓ done |
+| GitHub webhook deploys | ✓ done |
+| Cloud Native Buildpacks + Dockerfile | ✓ done |
+| Caddy reverse proxy + auto-HTTPS | ✓ done |
+| Multi-user auth with per-app grants | ✓ done |
+| Docker-based container runtime | ✓ done |
+
+---
+
+## Planned changes
+
+### 1. Replace Docker with Podman
+
+**Why:** Docker requires a daemon running at all times. On low-powered or older hardware
+this is wasteful. Podman is daemonless, rootless by default, and is a drop-in OCI-compatible
+replacement. It runs on any Linux (x86, ARM, RISC-V, old laptops, VMs) without root.
+
+**What changes:**
+- `build.sh`: `docker` → `podman` (one-line change per invocation)
+- `docker-compose.yml`: switch the server image to use Podman socket if needed
+- No API or model changes — OCI images are the same standard
+
+**What stays the same:** Cloud Native Buildpacks, image tagging, container networking,
+resource limits — all work identically with Podman.
+
+---
+
+### 2. Git push deploy (`git push hiy main`)
+
+**Why:** The current webhook flow requires GitHub (or another hosted git service). The goal
+is zero SaaS dependency. The git-push model is self-contained: SSH is already on every
+Linux box, and HIY already has everything else needed.
+
+**How it works:**
+
+```
+developer laptop                   HIY server
+────────────────                   ──────────
+git push hiy main
+  └─ SSH → hiy@myserver            accepts connection (authorized_keys)
+       └─ git-receive-pack         receives git objects into bare repo
+            └─ post-receive hook   queues a build in HIY's existing build worker
+                 └─ build + deploy (same pipeline as today)
+```
+
+Setup (once per app):
+```bash
+git remote add hiy ssh://hiy@myserver/myapp
+git push hiy main
+```
+
+**What HIY adds:**
+- Stores a bare git repo per app under `HIY_DATA_DIR/repos/<app-id>.git`
+- An SSH `authorized_keys` entry per user with a `command=` override that routes
+  pushes to the right app (same trick Piku and old Heroku use)
+- A `post-receive` hook that calls into the existing build queue
+- The app's git URL becomes the repo itself — no external remote needed
+
+**Compatibility:** The existing GitHub webhook flow keeps working. Both paths feed the
+same build queue. Users who want to keep using GitHub/Gitea/Forgejo can; users who want
+full self-containment use git push.
+
+---
+
+### 3. HIY as its own git server (optional, follows from #2)
+
+Once git push works, HIY can optionally act as the authoritative remote — no Gitea,
+no Forgejo, nothing external. Developers push to HIY, HIY stores the repo and deploys.
+
+For teams who want a browsable git UI, HIY can integrate with or recommend
+[Forgejo](https://forgejo.org) (a fully self-hosted Gitea fork) as a companion — but
+it is never a requirement.
+
+---
+
+## What this looks like when done
+
+| Concern | Solution | External service? |
+|---|---|---|
+| Git hosting | HIY bare repos (or self-hosted Forgejo) | No |
+| Deploy trigger | `git push hiy main` | No |
+| Build | Cloud Native Buildpacks / Dockerfile | No |
+| Container runtime | Podman (rootless, daemonless) | No |
+| Reverse proxy + TLS | Caddy (Let's Encrypt) | No* |
+| Auth | Multi-user, per-app grants | No |
+| DNS | User's own domain / router | No |
+
+\* Let's Encrypt requires outbound HTTPS on port 443 for certificate issuance.
+   For fully air-gapped setups, Caddy can use a self-signed or manually provided cert.
+
+---
+
+## Non-goals
+
+- **Not a Kubernetes replacement.** HIY targets single-node home/office servers, not
+  clusters. If you need multi-node, use k3s or Nomad.
+- **Not a managed service.** There is no HIY cloud. The point is that you run it.
+- **Not opinionated about language.** Any app with a Dockerfile or a standard buildpack
+  language (Node, Python, Go, Ruby, Java...) deploys without configuration.