Rewrite README with accurate docs

README.md

@@ -1,18 +1,14 @@
 # declpac
 
-`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.
+Declarative package manager for Arch Linux that syncs your system with a declared package list using pacman.
 
 ## 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
+- Declarative state management — define your desired package list in files or stdin
+- Smart orphan cleanup — removes packages no longer needed
+- Explicit package tracking — marks declared packages as explicit
+- AUR support — builds and installs AUR packages automatically
+- Machine-readable output — perfect for scripting
 
 ## Installation
 
@@ -28,14 +24,13 @@ sudo mv declpac /usr/local/bin/
 ### Dependencies
 
 - Go 1.21+
-- pacman (system package manager)
-- aur (AUR helper, optional for AUR support)
-- Root privileges (required for pacman operations)
+- pacman
+- makepkg (for AUR support)
+- git (for AUR support)
+- Root privileges
 
 ## Usage
 
-### Basic Usage
-
 ```bash
 # Single state file
 sudo declpac --state packages.txt
@@ -45,119 +40,63 @@ sudo declpac --state base.txt --state apps.txt
 
 # From stdin
 cat packages.txt | sudo declpac
+
+# Preview changes without applying
+sudo declpac --dry-run --state packages.txt
 ```
 
 ### State File Format
 
-State files contain one package name per line:
+One package name per line, lines beginning with `#` are comments:
 
 ```
 bash
 vim
 git
 docker
+# this is a comment
 ```
 
-Lines are treated as package names with whitespace trimmed:
-
-```
-bash          # bash
-  vim        # vim
-# comment   # ignored
-```
-
-### Command Line Options
+### 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) |
-| `--dry-run` | | Simulate sync without making changes |
+| `--state` | `-s` | State file to read package list from (can be used multiple times) |
+| `--dry-run` | | Preview changes without applying them |
 | `--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
-```
-
-#### Dry-Run Preview
-
-```bash
-# Preview what would happen without making changes
-sudo declpac --dry-run --state packages.txt
-
-# Example output:
-# Installed 3 packages, removed 2 packages
-# Would install: vim, git, docker
-# Would remove: python2, perl-xml-parser
-```
-
 ## 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`
+1. **Read** — Collect packages from all state files and stdin
+2. **Merge** — Combine into single package list
+3. **Categorize** — Check if packages are in official repos or AUR
+4. **Sync** — Install/update packages via pacman
+5. **Build** — Build and install AUR packages via makepkg
+6. **Mark** — Mark declared packages as explicit, all others as dependencies
+7. **Cleanup** — Remove orphaned packages
 
 ### Database Freshness
 
-If the pacman database is older than 24 hours, `declpac` automatically refreshes it with `pacman -Syy` before validation.
-
-### Orphan Cleanup
+If the pacman database is older than 24 hours, it is automatically refreshed.
 
-After syncing, `declpac` identifies and removes packages that are:
-- Not explicitly installed
-- Not required by any other package
+### Logging
 
-This keeps your system clean from dependency artifacts.
+Operations are logged to `/var/log/declpac.log`.
 
-## Output Format
+## Output
 
 ```
-# Success (packages installed/removed)
+# Packages installed/removed
 Installed 5 packages, removed 2 packages
 
-# Success (no changes)
+# No changes needed
 Installed 0 packages, removed 0 packages
 
+# Dry-run preview
+Installed 3 packages, removed 1 packages
+Would install: vim, git, docker
+Would remove: python2
+
 # Error
 error: package not found: <package-name>
 ```
@@ -167,36 +106,54 @@ error: package not found: <package-name>
 | Code | Meaning |
 |------|---------|
 | 0 | Success |
-| 1 | Error (no packages, validation failure, pacman error) |
+| 1 | Error |
 
-## Security Considerations
+## Examples
 
-- **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
+### Minimal System
 
-## Troubleshooting
+```bash
+echo -e "base\nbase-devel\nlinux-headers\nvim\ngit\ncurl" > ~/.config/declpac/minimal.txt
+sudo declpac --state ~/.config/declpac/minimal.txt
+```
 
-### "Permission denied"
+### Development Environment
 
-`declpac` requires root privileges. Use `sudo`:
+```bash
+# development.txt
+go
+nodejs
+python
+rust
+docker
+
+sudo declpac --state development.txt
+```
+
+### Dry-Run
 
 ```bash
-sudo declpac --state packages.txt
+sudo declpac --dry-run --state packages.txt
 ```
 
-### "Package not found"
+## Troubleshooting
 
-The package doesn't exist in pacman repos or AUR. Check the package name:
+### Permission denied
 
+Use sudo:
+```bash
+sudo declpac --state packages.txt
+```
+
+### Package not found
+
+Check if the package exists:
 ```bash
 pacman -Ss <package>
 ```
 
 ### Database sync fails
 
-Refresh manually:
-
 ```bash
 sudo pacman -Syy
 ```
@@ -210,13 +167,14 @@ declpac/
 ├── 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
+│   ├── fetch/         # Package resolution (pacman/AUR)
+│   ├── pacman/         # Pacman operations
+│   ├── validation/    # Database freshness check
+│   ├── output/        # Output formatting
+│   └── state/         # Logging
+└── README.md
 ```
 
 ## License
 
-GPL-3.0
+GPL-3.0