docs: improve readme and add robust lifecycle tests

README.md

@@ -1,12 +1,14 @@
 # LoopAware Infrastructure CLI
 
-Professional CLI tooling for managing dynamic infrastructure resources on the LoopAware flat network (10.32.0.0/16) (DNS, DHCP, Ingress, and Port Forwarding).
+A professional Python-based CLI for programmatically managing the LoopAware flat network (`10.32.0.0/16`).
 
 ## Features
-- **DNS/DHCP:** Manage `dnsmasq` reservations and custom records on `la-dnsmasq-01`.
-- **Ingress:** Manage HAProxy subdomains and backend routing.
-- **Router:** Manage OpenWrt firewall redirects.
-- **Agent-Friendly:** Designed for use by AI agents and developers.
+
+- **DNS/DHCP:** Manage `dnsmasq` reservations and records on `la-dnsmasq-01`.
+- **Ingress:** Dynamic HAProxy routing for subdomains.
+- **Router:** Manage OpenWrt firewall DNAT rules (TCP/UDP).
+- **Proxmox:** Provision and manage LXC containers across physical nodes (`vmh-07` to `vmh-13`).
+- **Samba:** Automated User and Group management for Active Directory.
 
 ## Installation
 
@@ -17,30 +19,63 @@ pip install -e .
 
 ## Configuration
 
-Copy `config.yaml.example` to `config.yaml` and update with your infrastructure details.
+The CLI requires a `config.yaml` file. A template is provided in `config.yaml.example`.
 
 ```bash
 cp config.yaml.example config.yaml
+# Update the nodes, IPs, and SSH key paths
 ```
 
-## Usage
+### Environment Variables
+- `ROUTER_PASS`: Required for router operations (if SSH keys are not deployed).
+- `INFRA_CONFIG`: Optional path to a custom config file.
 
-Use the `infra` command:
+## Usage Guide
 
+### 1. Identity & Access (Samba)
 ```bash
-# List DNS entries
-infra dns list
+# List all users
+infra samba list-users
 
-# Add an ingress
-infra ingress add my-app.loopaware.com 10.32.70.50 80
+# Create a new user
+infra samba add-user "jdoe" "SecurePass123!"
 
-# Add a port forward (requires ROUTER_PASS env var)
-export ROUTER_PASS='...'
-infra router add "My-Service" tcp 5000 10.32.70.50 5000
+# Grant XMPP access
+infra samba add-to-group "xmpp-users" "jdoe"
 ```
 
-## Testing
-
+### 2. Compute (Proxmox)
 ```bash
-pytest tests/test_cli.py
+# List containers on a specific node
+infra proxmox list-lxcs --node la-vmh-12
+
+# Create a new container
+infra proxmox create-lxc 12150 local:vztmpl/debian-13-standard "new-app" "10.32.70.100/16" "10.32.0.1" --node la-vmh-12
 ```
+
+### 3. Networking (DNS & DHCP)
+```bash
+# Register the new machine in DHCP
+infra dns add-host "aa:bb:cc:dd:ee:ff" "10.32.70.100" "new-app"
+
+# Add a custom DNS record
+infra dns add-dns "api.loopaware.com" "10.32.70.100"
+```
+
+### 4. Public Ingress (HAProxy)
+```bash
+# Expose the service to the internet
+infra ingress add "app.loopaware.com" "10.32.70.100" 80
+```
+
+## Advanced Workflows for AI Agents
+
+For detailed automation workflows, see [Workflow Documentation](../../docs/guides/dynamic-infrastructure-workflow.md).
+
+## Development and Testing
+
+Run the integration test suite:
+```bash
+export ROUTER_PASS="..."
+pytest tests/test_cli.py -s
+```