Initial commit

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

debian/AGENTS.md

@@ -0,0 +1,123 @@
+# AGENTS.md
+
+## Project Overview
+
+This directory maintains a single shell script for initializing a newly
+installed Debian system. Except for this file and essential project documentation, do not
+split functionality into additional scripts, configuration generators, or other
+languages. Keep the initialization logic centralized, easy to review, and
+directly executable on the target machine.
+
+## Scope
+
+This file applies to the `debian/` directory. The repository-level `AGENTS.md`
+still applies; where the two conflict, this file takes precedence.
+
+## Target Machine
+
+- During development, debugging, and validation, you may connect to the target
+  machine with `ssh 192.168.122.130`.
+- When the current user lacks sufficient privileges on the target machine, you
+  may elevate privileges with `sudo`.
+
+## Development Principles
+
+- Write Bash and use `#!/usr/bin/env bash` as the first line.
+- New code must be compatible with the current Debian stable release. If a
+  command or option requires a specific version, document it in a comment or
+  the README.
+- The script must support repeated execution. Creating users, installing
+  packages, writing configuration, and enabling services should be idempotent
+  wherever possible. Avoid duplicate entries and failures caused by resources
+  that already exist.
+- Keep the single-script design. Prefer small functions with clear
+  responsibilities and use a `main` function as the entry point.
+- Prefer `set -Eeuo pipefail`, and explicitly handle commands that may be
+  expected to fail.
+- Double-quote variables unless word splitting or glob expansion is
+  intentionally required. Use `local` for local variables and clear names for
+  constants and environment variables.
+- Prefer native Debian tools and repositories. Do not introduce third-party
+  repositories, runtimes, or external dependencies without a valid reason.
+- Comments should explain reasons, compatibility constraints, or risks rather
+  than restating each line of code.
+
+## Security Requirements
+
+- Check for root privileges before operations that require them and provide a
+  clear error message. Do not silently elevate privileges inside the script.
+- Never store passwords, tokens, private keys, or other sensitive information
+  in the repository, command-line arguments, or logs.
+- Do not execute unverified remote content with patterns such as
+  `curl ... | sh` or `wget ... | bash`.
+- Download external files over HTTPS and verify fixed versions, checksums, or
+  signatures whenever possible.
+- Confirm target files and directories before changing system configuration.
+  When replacing important configuration, preserve a recoverable backup or use
+  a reviewable atomic write.
+- Avoid broad or irreversible commands, including recursive deletion with
+  unvalidated variables, globally relaxed permissions, and unconditional
+  firewall resets.
+- Do not change SSH login policy, network connectivity, disk partitions, boot
+  configuration, or existing user credentials without explicit authorization.
+  If the project explicitly requires such an operation, provide a prominent
+  warning and an explicit opt-in switch.
+- Scope noninteractive APT settings to only the commands that require them. Do
+  not permanently change the user's environment.
+
+## Behavior and Output
+
+- Early in startup, check the runtime environment, Debian version, privileges,
+  and required commands. Fail with actionable error messages.
+- Print concise and clear status messages for important steps. Write errors to
+  standard error and exit with a nonzero status.
+- Prefer environment variables with safe defaults or command-line options for
+  user-selectable features, and provide `--help`. Do not unexpectedly block
+  unattended execution.
+- Features with significant impact or machine-specific behavior must be
+  disabled by default and run only when explicitly enabled.
+- Combine package installation into as few `apt-get install` operations as
+  practical, and avoid unnecessary `apt-get upgrade` or distribution upgrades.
+- Do not assume a systemd service exists. Confirm that the relevant package and
+  service unit are available before enabling or restarting a service.
+
+## Change Constraints
+
+- Keep changes focused on Debian initialization. Do not add unrelated
+  functionality.
+- Do not perform broad rewrites solely for style. Preserve existing behavior
+  and configuration options.
+- Give new configuration options safe defaults and update script help and
+  related documentation.
+- Clearly state in the delivery notes when a change alters system behavior,
+  default packages, or security policy.
+
+## Validation
+
+After modifying the script, run at least:
+
+```bash
+bash -n ./*.sh
+```
+
+If ShellCheck is installed, also run:
+
+```bash
+shellcheck ./*.sh
+```
+
+For argument parsing or pure function logic, use temporary directories and
+mock input for targeted tests. Unless explicitly authorized by the user, do not
+install or remove packages, modify `/etc`, manage users, change networking,
+restart services, or reboot the current development machine during testing.
+List any system-level behavior that cannot be safely validated and recommend
+validation steps in a fresh Debian virtual machine.
+
+## Delivery Notes
+
+When completing a change, briefly describe:
+
+- Which initialization behavior changed.
+- Whether default behavior or system security policy changed.
+- Which static checks or tests were run.
+- Which operations still require validation in a fresh Debian virtual machine.