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/README.md

@@ -0,0 +1,106 @@
+# apt-ostree Examples
+
+This directory contains example treefiles and integration patterns for `apt-ostree`.
+
+## Example Treefiles
+
+### `debian-trixie-base.yaml`
+A complete example of a Debian Trixie base system treefile that demonstrates:
+- Basic treefile structure and required fields
+- Package inclusion and exclusion patterns
+- User and file customizations
+- Service management
+- OSTree reference configuration
+- Build options
+
+## Usage
+
+### 1. Validate the Example
+
+```bash
+# Validate the treefile syntax and structure
+apt-ostree compose --treefile examples/debian-trixie-base.yaml --validate-only
+```
+
+### 2. Build the Example
+
+```bash
+# Build the tree using the example configuration
+apt-ostree compose \
+  --treefile examples/debian-trixie-base.yaml \
+  --output-dir /tmp/debian-trixie-output
+```
+
+### 3. Customize for Your Needs
+
+Copy the example and modify it for your specific requirements:
+
+```bash
+cp examples/debian-trixie-base.yaml my-custom-tree.yaml
+# Edit my-custom-tree.yaml with your customizations
+```
+
+## Integration Patterns
+
+### For deb-bootc-compose
+
+The example treefile shows the exact format that `deb-bootc-compose` should use:
+
+```yaml
+apiVersion: v1
+kind: Treefile
+metadata:
+  name: "your-tree-name"
+  # ... other metadata
+spec:
+  base:
+    distribution: "trixie"
+    architecture: "amd64"
+  # ... rest of specification
+```
+
+### For Other Tools
+
+External tools can use the same format and integrate via:
+- Command-line interface (`apt-ostree compose`)
+- Rust library (`apt_ostree::commands::compose`)
+- Future REST API endpoints
+
+## Testing
+
+### Validation Tests
+
+```bash
+# Test YAML syntax
+yamllint examples/debian-trixie-base.yaml
+
+# Test apt-ostree validation
+apt-ostree compose --treefile examples/debian-trixie-base.yaml --validate-only
+```
+
+### Build Tests
+
+```bash
+# Test actual tree composition
+apt-ostree compose \
+  --treefile examples/debian-trixie-base.yaml \
+  --output-dir /tmp/test-output \
+  --verbose
+```
+
+## Contributing
+
+When adding new examples:
+
+1. **Follow the established format** from existing examples
+2. **Include comprehensive comments** explaining each section
+3. **Test the example** before committing
+4. **Update this README** to document the new example
+5. **Ensure portability** across different environments
+
+## Support
+
+For questions about these examples or help with customizations:
+- Check the [Integration Howto](../docs/INTEGRATION_HOWTO.md)
+- Open an issue on the project repository
+- Join the community discussions