# AGENTS.md

## Purpose

This repository builds and maintains the CISS Debian Live Builder for Debian 13 Trixie.
Treat every change as security-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 user 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 in doubt, choose the safer, smaller, more easily reviewable change and explain the uncertainty.

## Non-negotiable constraints

- Target Debian 13 Trixie unless the task explicitly states otherwise.
- Do not introduce Ubuntu-specific assumptions.
- Do not invent live-build, live-boot, initramfs, cryptsetup, systemd, GRUB, Debian package, or upstream tool behavior.
- Verify uncertain behavior against existing repository code or authoritative upstream documentation.
- Do not add phase-argument gates to live-boot or initramfs scripts. Execution phase is controlled by Debian hook placement.
- Preserve encrypted-root and encrypted-SquashFS architecture unless the task explicitly changes it.
- Prefer simple, explicit, inspectable Bash over clever abstraction.
- Do not use `eval`.
- Do not print secrets, private keys, passphrases, tokens, or sensitive environment values.

## Repository map

Common areas:

- `ciss_live_builder.sh`, `lib/*.sh`: host-side orchestration and argument handling.
- `makefile`: local wrapper for composing and executing builder invocations.
- `config/hooks/live/*.chroot`: live-build chroot hooks.
- `config/hooks/live/*.binary`: live-build binary-image hooks.
- `config/includes.chroot/etc/initramfs-tools/hooks/*`: initramfs build hooks.
- `config/includes.chroot/etc/initramfs-tools/scripts/*`: initramfs boot scripts.
- `config/includes.chroot/usr/lib/live/boot/*`: live-boot runtime scripts.
- `scripts/*`: helper scripts or files copied into the generated image.
- `docs/*`: project documentation and conventions.

## Working method

Before editing:

1. Inspect the relevant scripts, hooks, configuration files, documentation, tests, and naming conventions.
2. Identify the affected build or boot phase.
3. Give a concise implementation plan and list the 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 helper functions for logging, fatal errors, validation, downloads, temporary files, and tool checks where available.
- 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 <file>` and `shellcheck <file>` if ShellCheck is available.
- Changed POSIX shell files, if any exist and must remain POSIX: run `sh -n <file>`.
- Make wrapper or builder argument-composition changes: run the relevant dry-run or help/parser check, usually `make dry-run` if available.
- Changed Python files: run the repository's relevant Python checks if present.
- CLI or user-facing behavior changes: update `usage()` and relevant documentation.
- Live-build, initramfs, or ISO behavior changes: state the required Debian Trixie validation command. Do not run a full live build unless requested or necessary.

## Bash conventions summary

See `docs/CODING_CONVENTION.md` for detail.

- Use Bash for new and modified project scripts unless an existing Debian interface file explicitly requires POSIX shell.
- Prefer `set -Ceuo pipefail` where feasible.
- Use `declare` for variables inside functions.
- Quote expansions unless word splitting or globbing is explicitly required.
- Prefer arrays where argument boundaries matter.
- Use `[[ ... ]]` for Bash conditionals.
- Use `case` for option dispatch and multi-branch string handling.
- Avoid parsing `ls`.
- Prefer `command -v` over `which`.
- Keep functions small and readable.
- End functions explicitly with `return 0` where consistent with surrounding code.
- Code comments must be in English.

## Security-sensitive areas

Before finalizing a change, check whether it affects:

- boot trust
- initramfs behavior
- live-boot runtime behavior
- cryptsetup/LUKS handling
- encrypted SquashFS handling
- key material
- remote unlock
- TLS, mTLS, signature, checksum, or provenance verification
- package sources or remote downloads
- network exposure
- file permissions
- persistence
- logging of sensitive values

If affected, document the concrete risk and mitigation in the final response.

## 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/)**
<!-- vim: set number et ts=2 sw=2 sts=2 ai tw=128 ft=markdown -->