Initial commit

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

AGENTS.md

@@ -0,0 +1,20 @@
+# AGENTS.md
+
+## Project Overview
+
+Collection of post-install initialization scripts, one directory per OS
+(`debian/`, `macos/`, ...). Each directory has its own `AGENTS.md`; the nearest
+one takes precedence over this file.
+
+## Shared Rules
+
+- One self-contained script per OS directory; do not share code across OSes
+  via sourced libraries, so each script can be copied and run on its own.
+- Scripts must be idempotent, check the OS/version and privileges early, and
+  fail with actionable errors.
+- Never store secrets in the repository. Do not execute unverified remote
+  content (`curl | sh`).
+- Do not change SSH policy, networking, disks, boot config, or user
+  credentials without an explicit opt-in switch.
+- Keep README.md's OS table in sync when adding or renaming scripts.
+- Validate with `bash -n` (and `shellcheck` if available) before delivering.

README.md

@@ -0,0 +1,17 @@
+# os-init
+
+Post-install initialization scripts, one directory per operating system.
+
+| Directory | Target | Script |
+|-----------|--------|--------|
+| `debian/` | Debian 13 (GNOME desktop) | `debian13-init.sh` |
+| `macos/`  | macOS | `macos-init.sh` (starter) |
+
+## Conventions
+
+- Each OS directory is self-contained: a single script, run directly on the
+  target machine, plus its own `AGENTS.md` for OS-specific rules.
+- Scripts must be idempotent (safe to run repeatedly) and must not change
+  security-sensitive settings without an explicit opt-in.
+- Add a new OS by creating `<os>/` with `<os><version>-init.sh` and adding a
+  row to the table above.

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.

debian/debian13-init.sh

@@ -0,0 +1,79 @@
+#!/usr/bin/env bash
+
+set -Eeuo pipefail
+
+# Runtime environment
+source /etc/os-release
+if [[ "${ID:-}" != "debian" || "${VERSION_ID:-}" != "13" ]]; then
+    echo "Error: this script supports Debian 13 only." >&2
+    exit 1
+fi
+
+# Ensure interactive login shells can find system administration commands.
+USR_SBIN_PROFILE=/etc/profile.d/usr-sbin-path.sh
+if [[ ! -e "${USR_SBIN_PROFILE}" ]]; then
+    sudo tee "${USR_SBIN_PROFILE}" >/dev/null <<'EOF'
+case ":${PATH}:" in
+    *:/usr/sbin:*) ;;
+    *) export PATH="${PATH}:/usr/sbin" ;;
+esac
+EOF
+    sudo chmod 0644 "${USR_SBIN_PROFILE}"
+    echo "Configured ${USR_SBIN_PROFILE}."
+fi
+
+# Prevent /tmp from being mounted as a tmpfs
+sudo systemctl mask tmp.mount
+
+# Window title bar buttons
+gsettings set org.gnome.desktop.wm.preferences button-layout \
+    ':minimize,maximize,close'
+
+# Show the weekday and seconds in the desktop clock
+gsettings set org.gnome.desktop.interface clock-show-weekday true
+gsettings set org.gnome.desktop.interface clock-show-seconds true
+
+# Set the idle timeout to 30 minutes
+gsettings set org.gnome.desktop.session idle-delay 'uint32 1800'
+
+# Use touch-style scrolling direction for the mouse
+gsettings set org.gnome.desktop.peripherals.mouse natural-scroll true
+
+# Disable Caps Lock
+# gsettings set org.gnome.desktop.input-sources xkb-options "['caps:none']"
+# Enable Caps Lock to toggle between keyboard layouts
+gsettings set org.gnome.desktop.input-sources xkb-options "['grp:caps_toggle']"
+
+# Disable GNOME Software update checks, downloads, and notifications
+gsettings set org.gnome.software allow-updates false
+gsettings set org.gnome.software download-updates false
+gsettings set org.gnome.software download-updates-notify false
+
+# Install Dash to Dock
+sudo apt-get install -y gnome-shell-extension-dashtodock
+
+# Keep the Dash visible
+gsettings set org.gnome.shell.extensions.dash-to-dock dock-fixed true
+gsettings set org.gnome.shell.extensions.dash-to-dock autohide false
+gsettings set org.gnome.shell.extensions.dash-to-dock intellihide false
+
+# Do not open the Activities Overview automatically after login
+gsettings set org.gnome.shell.extensions.dash-to-dock \
+    disable-overview-on-startup true
+
+# Dash click behavior
+gsettings set org.gnome.shell.extensions.dash-to-dock click-action \
+    'focus-minimize-or-appspread'
+
+# Show one running indicator dot per application window
+gsettings set org.gnome.shell.extensions.dash-to-dock \
+    running-indicator-style 'DOTS'
+
+# Install AppIndicator
+sudo apt-get install -y gnome-shell-extension-appindicator
+
+# Enable GNOME extensions
+gsettings set org.gnome.shell enabled-extensions \
+    "['dash-to-dock@micxgx.gmail.com', 'ubuntu-appindicators@ubuntu.com']"
+
+echo "GNOME desktop configuration completed. Log out and back in if a newly installed extension is not visible."

macos/macos-init.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+
+set -Eeuo pipefail
+
+# Runtime environment
+if [[ "$(uname -s)" != "Darwin" ]]; then
+    echo "Error: this script supports macOS only." >&2
+    exit 1
+fi
+
+# Show all file extensions in Finder
+defaults write NSGlobalDomain AppleShowAllExtensions -bool true
+
+# Show the path bar in Finder
+defaults write com.apple.finder ShowPathbar -bool true
+
+# Restart Finder so the settings above take effect
+killall Finder >/dev/null 2>&1 || true
+
+echo "macOS configuration completed."