Initial project setup: README, Cargo.toml, and CLI scaffolding

- Add README with project overview, architecture, and roadmap
- Set up Rust project with clap, toml, serde, tracing dependencies
- Scaffold CLI with 6 commands (init, validate, diff, check, apply, rollback)
- Create module structure for config, state, planner, executor, jail, vm, zfs
- Create test directory structure for unit/integration/idempotency tests

README.md

@@ -1,2 +1,104 @@
 # Rostyr
 
+A Rust-based configuration management tool for FreeBSD hosts, designed to configure workstations, servers, virtual machines, and jails using an idempotent, test-driven approach.
+
+## Overview
+
+Rostyr rewrites and extends [styr](https://gitea.rowanbrook.net/jakob/styr) in Rust, bringing:
+- **Idempotency** - All operations are safe to run repeatedly
+- **Testing first** - Snapshot-based tests for every feature
+- **Safe rollbacks** - ZFS snapshots before every apply
+
+## Architecture
+
+| Component | Technology |
+|-----------|------------|
+| Hosts | FreeBSD only |
+| Service Isolation | FreeBSD Jails (primary) |
+| Linux VMs | bhyve hypervisor |
+| Filesystem | ZFS with snapshots |
+| Config Format | TOML |
+
+## CLI Commands
+
+```
+rostyr init <hostname>     # Scaffold new host config
+rostyr validate           # Validate all TOML configs
+rostyr diff [--host H]   # Show pending changes (dry-run)
+rostyr check [--host H]  # Detect current system state
+rostyr apply [--host H]  # Apply changes (creates ZFS snapshot first)
+rostyr rollback          # Revert to last ZFS snapshot
+```
+
+## Idempotency Strategy
+
+1. **Detect** current state (jails, VMs, ZFS, users, packages)
+2. **Diff** desired vs actual state
+3. **Plan** minimal changes needed
+4. **Execute** only when state differs
+5. **Snapshot** ZFS before any apply
+
+## Testing Strategy
+
+- **Unit tests**: Config parsing, state detection, diff logic
+- **Integration tests**: CLI commands against isolated test VMs
+- **Idempotency tests**: Run apply twice, verify no changes on second run (snapshot comparison)
+- **VMs for testing**: All tests run in isolated bhyve VMs before production deployment
+
+## Project Structure
+
+```
+rostyr/
+├── src/
+│   ├── main.rs
+│   ├── cli.rs           # CLI argument handling
+│   ├── config/          # TOML parsing & validation
+│   ├── state/           # System state detection
+│   ├── planner/         # Diff & idempotency logic
+│   ├── executor/        # Command execution
+│   ├── jail/            # Jail management
+│   ├── vm/              # bhyve VM management
+│   ├── zfs/             # ZFS snapshot/rollback
+│   └── commands/        # init, validate, diff, apply, rollback
+├── configs/
+│   ├── hosts/           # Host TOML files
+│   ├── users/           # User TOML files
+│   └── services/        # Service definitions
+├── tests/
+│   ├── unit/            # Unit tests
+│   ├── integration/     # CLI tests
+│   └── idempotency/     # Snapshot-based tests
+└── Cargo.toml
+```
+
+## Phased Roadmap
+
+### Phase 1 - Core Foundation
+- Project scaffolding (Rust, CLI framework)
+- Config parsing (TOML)
+- Basic state detection (host info, ZFS)
+- init, validate commands
+
+### Phase 2 - Idempotent Apply
+- Diff/planner logic
+- Apply command with ZFS snapshot
+- Rollback command
+- check command
+
+### Phase 3 - Jails
+- Jail creation/management
+- Basic service jail templates
+- User management inside jails
+
+### Phase 4 - bhyve VMs
+- VM lifecycle management
+- Linux VM templates
+- Service deployment to VMs
+
+### Phase 5+ - Services
+- Individual service implementations (from styr)
+- Full port of styr functionality
+
+## License
+
+Unlicense - see LICENSE file