docs: create comprehensive integration howto for external tools

- Add INTEGRATION_HOWTO.md with complete treefile format specification
- Include example treefile (debian-trixie-base.yaml) for deb-bootc-compose
- Document integration patterns: CLI, Rust library, and future REST API
- Cover validation, error handling, best practices, and migration guide
- Address format mismatch between deb-bootc-compose and apt-ostree
- Provide clear documentation for external tool integration

examples/debian-trixie-base.yaml

@@ -0,0 +1,98 @@
+# Example apt-ostree treefile for Debian Trixie base system
+# This demonstrates the format that external tools should use
+
+apiVersion: v1
+kind: Treefile
+metadata:
+  name: "debian-trixie-base"
+  description: "Base Debian Trixie system with essential packages"
+  version: "0.1.0"
+  parent: "debian-trixie-20250819"  # Optional: parent tree reference
+  
+spec:
+  # Base system configuration
+  base:
+    distribution: "trixie"
+    architecture: "amd64"
+    mirror: "http://deb.debian.org/debian"
+    
+  # Package management
+  packages:
+    include:
+      # Essential system packages
+      - "systemd"
+      - "apt"
+      - "ostree"
+      - "bash"
+      - "coreutils"
+      - "util-linux"
+      - "procps"
+      - "grep"
+      - "sed"
+      - "gawk"
+      - "findutils"
+      - "tar"
+      - "gzip"
+      - "bzip2"
+      - "xz-utils"
+      
+      # Network and security
+      - "ca-certificates"
+      - "openssl"
+      - "curl"
+      - "wget"
+      - "iproute2"
+      - "net-tools"
+      - "iptables"
+      
+      # Development tools (optional)
+      - "build-essential"
+      - "pkg-config"
+      - "git"
+      
+    exclude:
+      - "unwanted-package"
+      - "conflicting-package"
+      
+  # Customizations
+  customizations:
+    users:
+      - name: "admin"
+        groups: ["sudo", "docker"]
+        ssh_keys:
+          - "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC..."
+    
+    files:
+      - path: "/etc/hostname"
+        content: "debian-atomic"
+        mode: "0644"
+        owner: "root:root"
+        
+      - path: "/etc/motd"
+        content: "Welcome to Debian Atomic (apt-ostree)"
+        mode: "0644"
+        owner: "root:root"
+        
+    services:
+      enable:
+        - "systemd-networkd"
+        - "systemd-resolved"
+        - "systemd-timesyncd"
+      disable:
+        - "unwanted-service"
+        
+  # OSTree configuration
+  ostree:
+    ref: "debian/trixie/amd64/base"
+    parent_ref: "debian/trixie/amd64/base"  # Optional
+    commit_message: "Debian Trixie base system with apt-ostree"
+    metadata:
+      build_tool: "deb-bootc-compose"
+      build_timestamp: "2025-08-19T18:44:29Z"
+      build_version: "1.0.0"
+    
+  # Build options
+  build:
+    parallel_jobs: 4
+    cache_dir: "/var/cache/apt-ostree"
+    cleanup: true