# AGENTS.md ## Purpose This repository builds and maintains CISS.debian.installer, a script-driven Debian installer for hardened and reproducible system installation workflows. Treat every change as security-sensitive, disk-destruction-sensitive, and boot-chain-sensitive. Persistent coding details live in `docs/CODING_CONVENTION.md`. Review-only instructions live in `code_review.md`. ## Instruction precedence for this repository Use this order when instructions differ: 1. The current task prompt defines the immediate objective and task-specific acceptance criteria. 2. This `AGENTS.md` defines repository-wide constraints and routing guidance. 3. `docs/CODING_CONVENTION.md` defines detailed coding conventions. 4. `code_review.md` applies when performing a review or final self-review. 5. Personal/global Codex instructions apply only where they do not conflict with repository rules. When instructions conflict, prefer the safer, smaller, more easily reviewable change and explain the conflict. ## Non-negotiable constraints - Target Debian 13 Trixie unless the task or repository explicitly states otherwise. - Do not introduce Ubuntu-specific assumptions. - Do not invent Debian Installer, debootstrap, initramfs-tools, cryptsetup, GRUB, systemd, Btrfs, Debian package, or upstream tool behavior. - Verify uncertain behavior against existing repository code or authoritative upstream documentation. - Preserve encrypted-root and boot-chain security assumptions unless the task explicitly changes them. - Preserve existing module source guards, especially `guard_sourcing`, `source_guard`, and `readonly -f` conventions. - Do not overwrite existing `ERR`, `EXIT`, `INT`, or `TERM` traps from modules or runtime scripts. - Prefer simple, explicit, inspectable Bash over clever abstraction. - Do not use `eval`. - Do not print secrets, passphrases, private keys, tokens, or sensitive environment values. - Do not perform destructive disk operations in validation unless explicitly requested and safely isolated. ## Repository map Common areas: - `ciss_debian_installer.sh`: primary installer entrypoint and phase orchestration. - `meta_loader_*.sh`: ordered module, library, and variable sourcing. - `.preseed/preseed.yaml`, `.preseed/partitioning.yaml`, `.preseed/SECRETS.yaml`: installer configuration, partition recipes, and secret input material. - `var/*.sh`: global variables, colors, terminal settings, and error codes. - `lib/cdi_0000_preliminary/*`: contact, usage, and version helpers. - `lib/cdi_0005_guard/*`: sourcing, source-guard, safe-execution, directory, and variable guards. - `lib/cdi_0010_basic/*`, `lib/cdi_0025_logging/*`, `lib/cdi_0030_checks/*`, `lib/cdi_0050_debug/*`, `lib/cdi_0060_traps/*`: basic helpers, logging, package/git checks, debug support, and traps. - `lib/cdi_0100_arg/*`, `lib/cdi_0110_interactive/*`, `lib/cdi_0200_dialog/*`: argument handling and interactive dialogs. - `func/cdi_1000_helper/*`: chroot helpers, GRUB helpers, module helpers, sanitizers, secure downloads, and YAML helpers. - `func/cdi_1200_validation/*`, `func/cdi_1250_yaml/*`: validation and preseed/YAML processing. - `func/cdi_3200_partitioning/*`: destructive partitioning, LUKS setup, formatting, mounting, and UUID logging. - `func/cdi_4000_debootstrap/*`: debootstrap, target mount preparation, and base target setup. - `func/cdi_4100_base/*`: APT sources, kernel, initramfs, systemd, firmware, and base package setup. - `func/cdi_4200_boot/*`: fstab, crypttab, cryptsetup, GRUB, GRUB password, and boot parameter handling. - `func/cdi_4300_network/*`: network setup, Dropbear initramfs remote unlock, initramfs updates, and SSH setup. - `func/cdi_4400_hardening/*`, `func/cdi_4500_user/*`, `func/cdi_4600_packages/*`: hardening, account setup, package installation, security verification, and auditing packages. - `func/cdi_4900_xtended/*`, `func/cdi_5000_recovery/*`: final commands, logrotate, chroot exit, and recovery target handling. - `includes/target/*`: files installed into the target system, including initramfs-tools hooks, scripts, Dropbear unlock files, GRUB assets, SSH, OpenSSL, sysctl, modprobe, PAM, and profile configuration. - `includes/chroot/hooks/*`: hook payloads copied into or executed inside the target environment. - `upgrades/*`: vendored or upgrade-related materials for Dropbear, Linux image options, and Secure Boot work. - `py/*`: Python-based configurator support. - `docs/*`, `.gitea/workflows/*`: project documentation and repository automation. ## Working method Before editing: 1. Inspect the relevant scripts, configuration files, documentation, workflows, and naming conventions. 2. Identify the affected installer phase: host orchestration, YAML/preseed handling, destructive disk setup, target chroot, initramfs, bootloader, network/Dropbear, hardening, user setup, package installation, finalization, or recovery. 3. Check existing source guards, trap behavior, logging, secret handling, and helper APIs before changing code. 4. Give a concise implementation plan and list likely files to touch unless the change is trivial. While editing: - Keep changes minimal and local to the task. - Preserve existing architecture, naming style, error handling, formatting, and security posture. - Do not perform unrelated cleanup or formatting churn. - Reuse existing helpers for logging, fatal errors, validation, source guards, chroot execution, secure downloads, temporary files, and secret cleanup where available. - Prefer arrays for command argument composition. - Do not introduce new runtime dependencies unless technically necessary and justified. After editing: - Run only the narrowest checks that prove the change. - Changed Bash files: run `bash -n ` and `shellcheck ` if ShellCheck is available. - Changed POSIX shell files: run `sh -n `. - Changed CLI behavior: update `usage()` and relevant documentation, then run the safest available parser/help check if the environment permits it. - Changed Python files: run the relevant checks configured under `py/` when applicable. - Changed installer, disk, initramfs, cryptsetup, GRUB, or Dropbear behavior: state the required Debian 13 Trixie validation command or isolated test, but do not run destructive or full installer validation unless explicitly requested. - For documentation-only changes, confirm the target files exist and review the final diff. ## Bash conventions summary See `docs/CODING_CONVENTION.md` for details. - Use Bash for installer logic unless an existing Debian interface file must remain POSIX shell. - Preserve module source guards and `readonly -f` usage where surrounding files use them. - Prefer strict Bash mode where feasible and consistent with the file's execution context. - Use `declare` for variables inside functions. - Quote expansions unless word splitting or globbing is explicitly required. - Prefer arrays where argument boundaries matter. - Use `[[ ... ]]`, `case`, and `$(...)`. - Avoid parsing `ls`; prefer structured tool output or existing helpers. - Prefer `command -v` over `which`. - Code comments must be in English. ## Security-sensitive areas Before finalizing a change, check whether it affects: - disk wiping, partition table creation, partition type codes, or filesystem formatting - cryptsetup/LUKS2 parameters, passphrases, key files, key slots, LUKS header backups, or nuke behavior - Btrfs subvolumes, mount ordering, mount options, snapshots, or labels - `/etc/fstab`, `/etc/crypttab`, UUIDs, PARTUUIDs, or mapper names - initramfs-tools hooks, scripts, included binaries, or early boot behavior - Dropbear initramfs remote unlock, forced commands, firewalling, host keys, unlock wrapper signatures, or hashes - GRUB installation, GRUB modules, encrypted `/boot`, UEFI/BIOS paths, NVRAM handling, or Secure Boot material - chroot command execution, mount propagation, target/root separation, or environment sanitization - APT sources, package authentication, TLS, signatures, checksums, or remote downloads - account setup, SSH policy, PAM, sudo, permissions, hardening files, or network exposure - logging, debug tracing, traps, cleanup paths, or exposure of sensitive values If affected, document the concrete risk and mitigation in the final response. ## Validation policy Use the narrowest validation that proves the requested change. Do not run full installer builds, debootstrap runs, live disk tests, destructive partitioning, broad repository audits, or network-heavy validation unless the task explicitly asks for them or the change cannot be validated responsibly without them. ## Final response Return a concise implementation report: - changed files - what changed - checks run and result - real remaining risks or follow-up steps Do not claim success for checks that were not run. --- **[no tracking | no logging | no advertising | no profiling | no bullshit](https://coresecret.eu/)**