Initial commit: Comprehensive Debian bootc documentation

- Complete documentation for all bootc commands and subcommands
- Debian-specific adaptations and workarounds
- Manual installation methods to bypass bootc reliability issues
- Technical guides with Rust source code analysis
- Flowcharts and external command references
- Hidden command documentation (bootc internals, state, etc.)
- Composefs integration analysis
- Base image creation guides (with and without bootc binary)
- Management scripts and automation
- Comprehensive troubleshooting and examples

building/kernel-arguments.md

@@ -0,0 +1,101 @@
+# Kernel arguments
+
+The default bootc model uses "type 1" bootloader config files stored in `/boot/loader/entries`, which define arguments provided to the Linux kernel.
+
+The set of kernel arguments can be machine-specific state, but can also be managed via container updates.
+
+The bootloader entries are currently written by the OSTree backend.
+
+More on Linux kernel arguments: [Kernel Parameters](https://docs.kernel.org/admin-guide/kernel-parameters.html)
+
+## /usr/lib/bootc/kargs.d
+
+Many bootc use cases will use generic "OS/distribution" kernels. In order to support injecting kernel arguments, bootc supports a small custom config file format in `/usr/lib/bootc/kargs.d` in TOML format, that have the following structure:
+
+```toml
+[kargs]
+append = ["console=ttyS0", "quiet"]
+prepend = ["rd.luks.uuid=12345678-1234-1234-1234-123456789abc"]
+```
+
+The `append` and `prepend` arrays contain kernel arguments that will be added to the kernel command line. Arguments in `prepend` are added at the beginning, while `append` arguments are added at the end.
+
+## Local kernel argument management
+
+It is currently undefined behavior to remove kernel arguments locally that are included in the base image via `/usr/lib/bootc/kargs.d`.
+
+## Injecting default arguments into custom kernels
+
+The Linux kernel supports building in arguments into the kernel binary, at the time of this writing via the `config CMDLINE` build option. If you are building a custom kernel, then it often makes sense to use this instead of `/usr/lib/bootc/kargs.d` for example.
+
+## Debian-Specific Considerations
+
+### Debian Kernel Management
+
+When working with Debian bootc images:
+
+- **Kernel packages**: Debian provides multiple kernel packages (linux-image-generic, linux-image-cloud, etc.)
+- **Kernel headers**: Install `linux-headers-*` packages for development
+- **Kernel modules**: Located in `/lib/modules/$(uname -r)/`
+
+### Example Debian Kernel Configuration
+
+```dockerfile
+FROM debian:bookworm-slim
+
+# Install kernel and bootc dependencies
+RUN apt update && \
+    apt install -y linux-image-generic linux-headers-generic bootc ostree && \
+    apt clean && \
+    rm -rf /var/lib/apt/lists/*
+
+# Configure kernel arguments for Debian
+COPY kargs.d/99-debian.conf /usr/lib/bootc/kargs.d/
+```
+
+### Debian Bootloader Integration
+
+Debian uses GRUB as the default bootloader:
+
+- **GRUB configuration**: `/etc/default/grub`
+- **GRUB scripts**: `/etc/grub.d/`
+- **Update GRUB**: `update-grub` command
+
+### Example kernel arguments configuration
+
+Create `/usr/lib/bootc/kargs.d/99-debian.conf`:
+
+```toml
+[kargs]
+append = [
+    "console=ttyS0",
+    "quiet",
+    "splash",
+    "systemd.show_status=false"
+]
+prepend = [
+    "rd.luks.uuid=12345678-1234-1234-1234-123456789abc"
+]
+```
+
+### Debian Security Considerations
+
+For Debian bootc images, consider these security-related kernel arguments:
+
+- **AppArmor**: `apparmor=1 security=apparmor`
+- **SELinux**: `selinux=1 security=selinux` (if using SELinux)
+- **KASLR**: `kaslr` (Kernel Address Space Layout Randomization)
+- **SMEP/SMAP**: `nosmep nosmap` (if needed for compatibility)
+
+### Hardware-Specific Arguments
+
+Debian bootc images may need hardware-specific kernel arguments:
+
+- **Virtualization**: `console=ttyS0` for cloud instances
+- **Storage**: `root=UUID=...` for specific root device
+- **Network**: `net.ifnames=0` for predictable network interface names
+
+---
+
+The Linux Foundation® (TLF) has registered trademarks and uses trademarks. For a list of TLF trademarks, see Trademark Usage.
+