From d296e00fd62e681cf87d898e84ac4195231a1a4a Mon Sep 17 00:00:00 2001
From: AI Bot <ai@local>
Date: Mon, 13 Apr 2026 19:29:49 +0200
Subject: [PATCH] Update README with usage documentation

---
 README.md | 206 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 203 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index d535ccd..11b344c 100644
--- a/README.md
+++ b/README.md
@@ -1,9 +1,209 @@
 # declpac
 
-`declpac` syncs a declarative package list with the `pacman` package manager.
+`declpac` is a declarative package manager for Arch Linux that syncs your system
+with a declared package list using `pacman`. It ensures your system matches your
+desired state, handling package installation, upgrades, and orphan cleanup
+automatically.
 
-## Building
+## Features
+
+- **Declarative state management** — Define your desired package list in files or stdin
+- **Automatic dependency resolution** — Pacman handles transitive dependencies
+- **Smart orphan cleanup** — Removes packages no longer needed
+- **Explicit package tracking** — Marks your declared packages as explicit
+- **AUR support** — Falls back to AUR for packages not in official repos
+- **Machine-readable output** — Perfect for scripting and automation
+
+## Installation
+
+### Build from Source
+
+```bash
+git clone https://github.com/Riyyi/declpac.git
+cd declpac
+go build -o declpac ./cmd/declpac
+sudo mv declpac /usr/local/bin/
+```
 
 ### Dependencies
 
-- go
+- Go 1.21+
+- pacman (system package manager)
+- aur (AUR helper, optional for AUR support)
+- Root privileges (required for pacman operations)
+
+## Usage
+
+### Basic Usage
+
+```bash
+# Single state file
+sudo declpac --state packages.txt
+
+# Multiple state files
+sudo declpac --state base.txt --state apps.txt
+
+# From stdin
+cat packages.txt | sudo declpac
+```
+
+### State File Format
+
+State files contain one package name per line:
+
+```
+bash
+vim
+git
+docker
+```
+
+Lines are treated as package names with whitespace trimmed:
+
+```
+bash          # bash
+  vim        # vim
+# comment   # ignored
+```
+
+### Command Line Options
+
+| Flag | Alias | Description |
+|------|-------|-------------|
+| `--state` | `-s` | State file(s) to read package list from (can be used multiple times) |
+| `--yes` | `-y` | Skip confirmation prompts (for scripting) |
+| `--help` | `-h` | Show help message |
+
+### Examples
+
+#### Minimal System
+
+```bash
+# Create a minimal system package list
+echo -e "base\nbase-devel\nlinux-headers\nvim\ngit\ncurl\nwget" > ~/.config/declpac/minimal.txt
+
+# Apply the state
+sudo declpac --state ~/.config/declpac/minimal.txt
+```
+
+#### Development Environment
+
+```bash
+# development.txt
+go
+nodejs
+python
+rust
+docker
+docker-compose
+kubectl
+helm
+terraform
+
+# Apply
+sudo declpac --state development.txt
+```
+
+#### Full System Sync
+
+```bash
+# Combine multiple files
+sudo declpac --state ~/.config/declpac/base.txt --state ~/.config/declpac/desktop.txt
+
+# Or use stdin
+cat ~/.config/declpac/full-system.txt | sudo declpac
+```
+
+## How It Works
+
+1. **Collect packages** — Reads from all `--state` files and stdin
+2. **Merge** — Combines all packages additively (duplicates allowed)
+3. **Validate** — Checks packages exist in repos or AUR
+4. **Mark explicit** — Marks declared packages as explicit dependencies
+5. **Sync** — Runs `pacman -Syu` to install/upgrade packages
+6. **Cleanup** — Removes orphaned packages with `pacman -Rns`
+7. **Report** — Outputs summary: `Installed X packages, removed Y packages`
+
+### Database Freshness
+
+If the pacman database is older than 24 hours, `declpac` automatically refreshes it with `pacman -Syy` before validation.
+
+### Orphan Cleanup
+
+After syncing, `declpac` identifies and removes packages that are:
+- Not explicitly installed
+- Not required by any other package
+
+This keeps your system clean from dependency artifacts.
+
+## Output Format
+
+```
+# Success (packages installed/removed)
+Installed 5 packages, removed 2 packages
+
+# Success (no changes)
+Installed 0 packages, removed 0 packages
+
+# Error
+error: package not found: <package-name>
+```
+
+### Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | Error (no packages, validation failure, pacman error) |
+
+## Security Considerations
+
+- **Run as root** — `declpac` requires root privileges for pacman operations
+- **Review state files** — Only install packages from trusted sources
+- **Backup** — Consider backing up your system before major changes
+
+## Troubleshooting
+
+### "Permission denied"
+
+`declpac` requires root privileges. Use `sudo`:
+
+```bash
+sudo declpac --state packages.txt
+```
+
+### "Package not found"
+
+The package doesn't exist in pacman repos or AUR. Check the package name:
+
+```bash
+pacman -Ss <package>
+```
+
+### Database sync fails
+
+Refresh manually:
+
+```bash
+sudo pacman -Syy
+```
+
+## File Structure
+
+```
+declpac/
+├── cmd/declpac/
+│   └── main.go         # Entry point
+├── pkg/
+│   ├── input/          # State file/stdin reading
+│   ├── merge/          # Package merging
+│   ├── validation/     # Package validation
+│   ├── pacman/         # Pacman integration
+│   └── output/         # Output formatting
+├── go.mod              # Go module
+└── README.md           # This file
+```
+
+## License
+
+GPL-3.0