Initial commit

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

macos/AGENTS.md

@@ -0,0 +1,90 @@
+# AGENTS.md
+
+## Project Overview
+
+This directory maintains a single shell script for initializing a newly set up
+macOS user account. Except for this file, do not split functionality into
+additional scripts, configuration generators, or other languages. Keep the
+script flat, easy to review, and directly executable on the target machine,
+in the same style as `../debian/debian13-init.sh`.
+
+## Scope
+
+This file applies to the `macos/` directory. The repository-level `AGENTS.md`
+still applies; where the two conflict, this file takes precedence.
+
+## Development Principles
+
+- Write Bash and use `#!/usr/bin/env bash` as the first line.
+- macOS ships bash 3.2 as `/bin/bash`. Do not use associative arrays,
+  `mapfile`, `${var,,}`, or other bash 4+ features.
+- Keep the script flat: a short comment followed by the commands it explains,
+  with no helper functions unless repetition clearly demands one.
+- Prefer `defaults write` for per-user preferences. Each write must be safe to
+  repeat. Use `-bool`, `-int`, or `-string` explicitly so the stored type is
+  stable.
+- Double-quote variables, and use `"${HOME}"` rather than `~` inside strings.
+- If a key only works on a specific macOS release, say so in a comment and
+  keep the version check in the script in sync.
+- Comments should explain reasons, compatibility constraints, or risks rather
+  than restating each line of code.
+
+## Security Requirements
+
+- 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`. This rules out the official Homebrew
+  installer; install it by hand if needed.
+- Do not change SSH or Remote Login, the firewall, FileVault, Gatekeeper,
+  System Integrity Protection, networking, disks, boot configuration, or user
+  credentials without an explicit opt-in switch and a prominent warning.
+- The script runs as the login user. Do not add `sudo`, and do not write
+  preferences into root's domain.
+
+## Behavior and Output
+
+- Check the OS and version first; fail with an actionable message on stderr
+  and a nonzero exit status.
+- Restart only the apps whose preferences were changed, once, at the end.
+- Features with significant impact or machine-specific behavior must be
+  disabled by default and run only when explicitly enabled.
+- Mention in the final message anything that needs a logout or a restart to
+  take effect.
+
+## Change Constraints
+
+- Keep changes focused on macOS initialization. Do not add unrelated
+  functionality.
+- Do not perform broad rewrites solely for style. Preserve existing behavior.
+- Clearly state in the delivery notes when a change alters system behavior or
+  security policy.
+
+## Validation
+
+After modifying the script, run at least:
+
+```bash
+bash -n ./*.sh
+```
+
+If ShellCheck is installed, also run:
+
+```bash
+shellcheck ./*.sh
+```
+
+The development machine is usually the target machine. Unless explicitly
+authorized by the user, do not run the script itself or `defaults write` on it
+while testing; check a key with `defaults read` or `defaults read-type`
+instead. List any behavior that could not be safely validated and recommend
+running the script twice on a fresh macOS user account.
+
+## 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 on a fresh macOS user account.