diff --git a/.gitignore b/.gitignore
index 6322726..d6290ee 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,4 +1,4 @@
-x86_64/
 src/
 logs/
 build-output/
+pkgs.omarchy.org/
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..a4086d9
--- /dev/null
+++ b/README.md
@@ -0,0 +1,235 @@
+# Omarchy Package Repository
+
+This repository manages the Omarchy Package Repository, building a host of PKGBUILDs and facilitating syncing from AUR where necessary.
+
+## Overview
+
+The build system uses Docker to create a clean, reproducible build environment. Packages are built unsigned, then signed in a separate step, promoted to production, and synced to a remote server.
+
+### Directory Structure
+
+```
+omarchy-pkgs/
+├── pkgbuilds/              # Source PKGBUILDs (one directory per package)
+├── build-output/           # Temporary build workspace
+├── pkgs.omarchy.org/       # Final signed packages
+├── build/                  # Build scripts that run inside of the Docker container
+├── bin/                    # Command-line tools
+└── logs/                   # Build and operation logs
+```
+
+## Quick Start
+
+### Complete Release Workflow
+
+Build, sign, promote, clean, and sync in one command:
+
+```bash
+bin/repo release
+```
+
+With options:
+```bash
+bin/repo release --skip-prod-check              # Skip production confirmation
+bin/repo release --sync-remote dev-pkgs:/       # Sync to dev remote instead
+bin/repo release --package omarchy-nvim         # Build only one package
+```
+
+### Step-by-Step Workflow
+
+```bash
+# 1. Build packages (unsigned)
+bin/repo build
+
+# 2. Sign all built packages (sitting in `build-output`)
+bin/repo sign
+
+# 3. Promote to production directory (copy from `build-output` -> `pkgs.omarchy.org`)
+bin/repo promote
+
+# 4. Clean old versions and update database
+bin/repo clean
+
+# 5. Sync to remote server
+bin/repo sync pkgs.omarchy.org/x86_64
+```
+
+## Commands
+
+### `bin/repo build`
+
+Builds packages from `pkgbuilds/` directory in a Docker container.
+
+**Options:**
+- `--package <name>` - Build only a specific package
+- `--arch <arch>` - Target architecture (default: x86_64)
+
+**What it does:**
+- Clears `build-output/` directory
+- Builds packages in dependency order
+- Creates unsigned `.pkg.tar.zst` files in `build-output/x86_64/`
+- Skips packages that are already up-to-date in `pkgs.omarchy.org/`
+
+**Examples:**
+```bash
+bin/repo build                         # Build all packages
+bin/repo build --package omarchy-nvim  # Build only yay
+```
+
+### `bin/repo sign`
+
+Signs all unsigned packages in `build-output/`.
+
+**What it does:**
+- Fetches GPG key and passphrase from env or 1Password
+- Signs all `.pkg.tar.zst` files
+
+### `bin/repo promote`
+
+Copies signed packages from `build-output/` to `pkgs.omarchy.org/`.
+
+**Options:**
+- `--arch <arch>` - Target architecture (default: x86_64)
+- `--dry-run` - Preview what would be copied
+
+**What it does:**
+- Copies all packages and signatures to production directory
+- Cleans up `build-output/` after successful promotion
+
+**Examples:**
+```bash
+bin/repo promote
+bin/repo promote --dry-run
+```
+
+### `bin/repo clean`
+
+Removes old package versions and updates the repository database.
+
+**Options:**
+- `--keep N` - Keep N versions of each package (default: 2)
+- `--dry-run` - Preview what would be removed
+- `--usage` - Show disk usage statistics
+
+**What it does:**
+- Removes old package versions (keeps latest 2 by default)
+- Updates `omarchy.db.tar.zst` repository database
+- Shows disk usage and statistics
+
+**Examples:**
+```bash
+bin/repo clean                      # Keep 2 versions
+bin/repo clean --keep 3             # Keep 3 versions
+bin/repo clean --dry-run            # Preview cleanup
+bin/repo clean --usage              # Show disk usage
+```
+
+### `bin/repo sync`
+
+Syncs the repository to a remote server using rclone.
+
+**Arguments:**
+- `<directory>` - Local directory to sync (e.g., `pkgs.omarchy.org/x86_64`)
+
+**Options:**
+- `--remote <remote>` - Rclone remote destination (default: `pkgs.omarchy.org:omarchy-pkgs`)
+- `--skip-prod-check` - Skip production confirmation
+
+**What it does:**
+- Syncs packages to remote (uses `--ignore-existing` to preserve versions)
+- Syncs database files with checksums
+- Prompts for confirmation when syncing to production
+
+**Examples:**
+```bash
+bin/repo sync pkgs.omarchy.org/x86_64                    # Sync to production
+bin/repo sync pkgs.omarchy.org/x86_64 --skip-prod-check  # Skip confirmation
+bin/repo sync pkgs.omarchy.org/x86_64 --remote dev-pkgs:/# Sync to dev
+```
+
+### `bin/repo release`
+
+Runs the complete release workflow in sequence.
+
+**Options:**
+- `--package <name>` - Build only a specific package
+- `--arch <arch>` - Target architecture (default: x86_64)
+- `--sync-remote <path>` - Rclone remote for sync (default: production)
+- `--skip-prod-check` - Skip production confirmation
+
+**What it does:**
+1. Builds packages
+2. Signs packages
+3. Promotes to production
+4. Cleans old versions
+5. Syncs to remote
+
+**Examples:**
+```bash
+bin/repo release                                    # Full workflow
+bin/repo release --skip-prod-check                  # Skip prod confirmation
+bin/repo release --sync-remote dev-pkgs:/           # Sync to dev
+bin/repo release --package omarchy-nvim             # Single package
+```
+
+### Other Commands
+
+**`bin/repo list`** - List all packages in the repository
+```bash
+bin/repo list
+```
+
+**`bin/repo remove <package>`** - Remove a package from the repository
+```bash
+bin/repo remove yay
+```
+
+**`bin/repo update`** - Update the repository database (usually done automatically by `clean`)
+```bash
+bin/repo update
+```
+
+## Adding New Packages
+
+### From AUR
+
+1. Add package name to `build/packages/omarchy-aur.packages` (for future syncing)
+2. Sync PKGBUILD to local directory:
+   ```bash
+   bin/sync-aur package-name
+   ```
+3. Build and release:
+   ```bash
+   bin/repo release --package package-name
+   ```
+
+### Custom Package
+
+1. Create directory in `pkgbuilds/`:
+   ```bash
+   mkdir pkgbuilds/my-package
+   ```
+2. Add PKGBUILD and any additional files
+3. Build and release:
+   ```bash
+   bin/repo release --package my-package
+   ```
+
+## Package Dependencies
+
+The build system automatically handles dependencies between packages being built. For example, if `aether` depends on `hyprshade`, the build system will:
+
+1. Detect the dependency relationship
+2. Build `hyprshade` first
+3. Add it to the `omarchy-build` temporary repository
+4. Build `aether` (which can now install `hyprshade` from `omarchy-build`)
+
+This works through two internal repositories:
+- **`omarchy-build`** - Temporary repo in `build-output/` (unsigned packages, used during build)
+- **`omarchy`** - Production repo in `pkgs.omarchy.org/` (signed packages)
+
+## Version Management
+
+Packages are only rebuilt if:
+- PKGBUILD version is newer than the version in the repository DB
+- Package doesn't exist in production yet