Update docs/ai for DX improvements

Refresh architecture, implementation-state, and gap-analysis docs to
reflect all DX changes: validate, completions, JSON output, boot/halt,
auto-width tables, confirmation flow, progress output, and partial
failure handling. Move resolved gaps to the Resolved section.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

docs/ai/architecture.md

@@ -8,14 +8,15 @@ zmgr is a single Rust binary that manages illumos zones via flat KDL config file
 
 ```
 src/
-  main.rs        CLI entry point (clap), command dispatch
+  main.rs        CLI entry point (clap), command dispatch, table formatting
   config.rs      Global config (/etc/zmgr/config.kdl)
-  template.rs    Zone templates (/etc/zmgr/templates/*.kdl)
+  template.rs    Zone templates (/etc/zmgr/templates/*.kdl) — multi-net
-  pool.rs        IPAM pools (/etc/zmgr/pools/*.kdl)
+  pool.rs        IPAM pools (/etc/zmgr/pools/*.kdl) — range + list modes
-  zone.rs        Zone registry (/etc/zmgr/zones/*.kdl)
+  zone.rs        Zone registry (/etc/zmgr/zones/*.kdl) — multi-net
   publisher.rs   IPS publishers (/etc/zmgr/publishers/*.kdl)
   exec.rs        System command wrappers (zonecfg, zoneadm, dladm)
   import.rs      Import existing zones into registry
+  validate.rs    Config validation (syntax, integrity, pool sanity)
   kdl_util.rs    KDL document parsing helpers
   error.rs       Error types (miette diagnostics)
 ```
@@ -24,36 +25,63 @@ src/
 
 ### Zone Creation (`zmgr create <name>`)
 
-1. Load global config → get default template name
+1. Load global config -> get default template name
-2. Load template → get brand, autoboot, pool reference
+2. Load template -> get brand, autoboot, net blocks (each references a pool)
-3. Load pool → get network, gateway, stub, IP range
+3. For each net: load pool -> allocate next free IP from pool
-4. Scan zone registry → find allocated IPs
+4. Build zonecfg commands with one `add net` block per network
-5. Allocate next free IP from pool range
+5. Step-by-step execution with progress:
-6. `dladm create-vnic` → create VNIC on stub
+   - Create VNICs via `dladm create-vnic`
-7. `zonecfg -z <name>` → pipe zone configuration
+   - Configure zone via `zonecfg -z <name>`
-8. `zoneadm -z <name> install` → install zone
+   - Install zone via `zoneadm -z <name> install`
-9. Write zone registry entry (KDL file)
+   - Write zone registry entry (KDL file)
-10. If autoboot, `zoneadm boot`
+   - If autoboot, `zoneadm boot`
+6. On partial failure: print what succeeded + cleanup commands
+
+### Zone Destruction (`zmgr destroy <name>`)
+
+1. Load zone from registry
+2. Require confirmation (type zone name, or `--yes`)
+3. Step-by-step teardown with progress:
+   - Halt zone
+   - Uninstall zone
+   - Delete zone configuration
+   - Delete VNICs (one per net)
+   - Remove registry entry
 
 ### Zone Import (`zmgr import`)
 
-1. `zoneadm list -cp` → get system zones
+1. `zoneadm list -cp` -> get system zones
 2. Filter out already-registered and bhyve zones
-3. `zonecfg -z <name> info` → extract config
+3. `zonecfg -z <name> info` -> extract config (multiple nets)
-4. Match brand → template, IP → pool
+4. Match brand -> template, IP -> pool, net names -> template net names
-5. Write zone registry entry
+5. Write zone registry entry with current date
+
+### Validation (`zmgr validate`)
+
+1. Parse all KDL files (config, templates, pools, zones)
+2. Check referential integrity (template -> pool, config -> template)
+3. Check pool sanity (gateway in network, range in network)
+4. Check for duplicate IPs across zones
+5. Warn on high pool utilization (>90%)
+
+## Output Modes
+
+- **Human** (default): auto-sized tables, key-value detail views
+- **JSON** (`--json`): structured output for scripting
+- **Dry-run** (`-n`): shows commands without executing
 
 ## Dependency Graph
 
 ```
 main.rs
-  ├── config.rs     ← kdl_util.rs, error.rs
+  ├── config.rs     <- kdl_util.rs, error.rs
-  ├── template.rs   ← kdl_util.rs, error.rs
+  ├── template.rs   <- kdl_util.rs, error.rs
-  ├── pool.rs       ← kdl_util.rs, error.rs, zone.rs
+  ├── pool.rs       <- kdl_util.rs, error.rs
-  ├── zone.rs       ← kdl_util.rs, error.rs
+  ├── zone.rs       <- kdl_util.rs, error.rs
-  ├── publisher.rs  ← kdl_util.rs, error.rs
+  ├── publisher.rs  <- kdl_util.rs, error.rs
-  ├── exec.rs       ← error.rs
+  ├── exec.rs       <- error.rs
-  └── import.rs     ← exec.rs, pool.rs, template.rs, zone.rs
+  ├── import.rs     <- exec.rs, pool.rs, template.rs, zone.rs
+  └── validate.rs   <- config.rs, pool.rs, template.rs, zone.rs
 ```
 
 ## Boundary with vm-manager

docs/ai/gap-analysis.md

@@ -5,9 +5,6 @@
 ### Publishers Not Applied During Install
 Publishers are stored and listed but not yet passed to `zonecfg`/`zoneadm` during zone creation. Future: configure IPS publishers inside the zone after install via `zlogin` or `sysding`.
 
-### No Zone Boot/Halt Commands
-`zmgr` doesn't expose boot/halt/reboot as subcommands. Users must use `zoneadm -z <name> boot` directly. Could add `zmgr boot <name>` / `zmgr halt <name>` as thin wrappers.
-
 ### No Template Create/Edit via CLI
 Templates must be edited as KDL files directly. Could add `zmgr template create` / `zmgr template edit` commands.
 
@@ -29,11 +26,28 @@ Import matches zones to templates by brand and IPs to pools by network containme
 ### No IPv6 Support
 IPAM only handles IPv4 pools. Could extend to dual-stack.
 
+### No Automatic Rollback on Create Failure
+On partial failure, zmgr prints cleanup guidance but does not automatically undo. Could add `--rollback-on-failure` flag.
+
+### No Colored Output
+Could add colored state indicators (green=running, red=halted) using `owo-colors`. Should respect `NO_COLOR` env var.
+
 ## Resolved
 
-- ~~No Dry-Run Mode~~ — Implemented: `--dry-run` / `-n` flag on create and destroy
+- ~~No Dry-Run Mode~~ — `--dry-run` / `-n` flag on create and destroy
-- ~~Single network per zone~~ — Implemented: templates define multiple `net` blocks, each referencing a pool
+- ~~Single network per zone~~ — Templates define multiple `net` blocks
-- ~~No public/hoster IP support~~ — Implemented: pools support explicit address lists in addition to contiguous ranges
+- ~~No public/hoster IP support~~ — Pools support explicit address lists
+- ~~No destructive operation confirmation~~ — Destroy requires typing zone name (or `--yes`)
+- ~~No progress output~~ — Create/destroy show numbered step-by-step progress
+- ~~No partial failure guidance~~ — Prints cleanup commands on failure
+- ~~No config validation~~ — `zmgr validate` checks syntax, integrity, pool sanity
+- ~~No machine-readable output~~ — `--json` flag on all list/show/status commands
+- ~~No shell completions~~ — `zmgr completions bash|zsh|fish`
+- ~~No version flag~~ — `zmgr --version`
+- ~~No boot/halt commands~~ — `zmgr boot` and `zmgr halt`
+- ~~Publisher naming confusion~~ — Remove accepts both publisher name and filename stem
+- ~~Hardcoded column widths~~ — Tables auto-size based on content
+- ~~Import empty created date~~ — Uses current date, matches template net names
 
 ## Future Considerations
 
@@ -41,3 +55,4 @@ IPAM only handles IPv4 pools. Could extend to dual-stack.
 - **Snapshots**: ZFS snapshot management for zone rollback
 - **Migration**: Move zones between hosts
 - **Monitoring**: Health checks, resource usage
+- **Drift detection**: Dedicated command to compare registry vs system state

docs/ai/implementation-state.md

@@ -2,8 +2,9 @@
 
 ## Completed
 
+### Core
 - [x] Project scaffold (Cargo.toml, module structure)
-- [x] KDL parsing helpers (`kdl_util.rs`)
+- [x] KDL v2 parsing helpers (`kdl_util.rs`)
 - [x] Error types with miette diagnostics (`error.rs`)
 - [x] Global config loading (`config.rs`)
 - [x] Template loading + defaults — multi-net support (`template.rs`)
@@ -12,31 +13,54 @@
 - [x] Publisher management (`publisher.rs`)
 - [x] Exec layer for system commands (`exec.rs`)
 - [x] Import logic from existing zones — multi-net parsing (`import.rs`)
-- [x] CLI commands: init, create, destroy, list, status, import
+- [x] Validation engine (`validate.rs`)
-- [x] CLI commands: template list/show, pool list/show
+
-- [x] CLI commands: publisher list/add/remove
+### CLI Commands
+- [x] `init`, `create`, `destroy`, `list`, `status`, `import`
+- [x] `boot`, `halt` — thin wrappers around zoneadm
+- [x] `validate` — checks KDL syntax, referential integrity, pool sanity, duplicate IPs
+- [x] `template list|show`, `pool list|show`
+- [x] `publisher list|add|remove`
+- [x] `completions <shell>` — bash/zsh/fish shell completions
+
+### DX Features
 - [x] `--dry-run` / `-n` flag for create and destroy
-- [x] Multi-network zones (multiple net blocks per template/zone)
+- [x] `--yes` / `-y` flag to skip confirmation (scripting)
+- [x] `--json` flag for machine-readable output
+- [x] `--version` flag
+- [x] Destroy confirmation: type zone name to confirm (TTY detection)
+- [x] Step-by-step numbered progress during create/destroy
+- [x] Partial failure guidance: prints cleanup commands on create failure
+- [x] Auto-sizing table columns (measures content before printing)
+- [x] Dry-run notes that IP allocation is tentative
+- [x] Publisher remove accepts publisher name or filename stem
+- [x] Import uses current date + matches template net names
+- [x] RFC 5737 comment on default public pool
+
+### Multi-Network
+- [x] Templates define multiple `net` blocks, each referencing a pool
 - [x] List-based IPAM pools (explicit addresses from hoster)
 - [x] Default router template with internal + public nets
-- [x] Backward compat: legacy flat `pool` field in templates, flat address fields in zones
+- [x] Backward compat: legacy flat `pool` field in templates
-- [x] Clean build (zero warnings)
-- [x] Tested: init, template list/show, pool list/show, publisher list, list, dry-run single+multi-net
 
 ## Not Yet Tested on illumos
 
-- [ ] `zmgr create` (requires illumos with zonecfg/zoneadm/dladm)
+- [ ] `zmgr create` (requires zonecfg/zoneadm/dladm)
 - [ ] `zmgr destroy`
 - [ ] `zmgr import`
 - [ ] `zmgr status` (requires zoneadm)
+- [ ] `zmgr boot` / `zmgr halt`
 
 ## Dependencies
 
 | Crate | Version | Purpose |
 |---|---|---|
 | clap | 4.6.0 | CLI parsing (derive) |
+| clap_complete | 4.6.0 | Shell completion generation |
 | kdl | 6.5.0 | KDL v2 document parsing |
 | miette | 7.6.0 | Diagnostic error reporting |
 | thiserror | 2.0.18 | Error type derives |
 | ipnet | 2.12.0 | IP network arithmetic |
 | chrono | 0.4.44 | Date formatting |
+| serde | 1.0.228 | Serialization framework |
+| serde_json | 1.0.149 | JSON output |