Fix review issues: harden auth gate, fix AWS VPN detection, improve docs

- Make GitHub auth a hard gate — abort setup if auth fails or is
  cancelled, so repo cloning is guaranteed
- Fix AWS VPN Client detection on Linux (GUI app at /opt/awsvpnclient,
  no PATH binary) — fixes CI doctor failure
- Support ARM64 for AWS CLI and VPN Client Ubuntu installs
- Add --yes to gpg --dearmor calls so 1Password re-installs don't fail
- Ensure unzip is present before AWS CLI install
- Use dpkg -s instead of dpkg -l for reliable package detection
- Guard docker compose doctor check on docker being installed
- Rename misleading variable in migrate.sh
- Update README with platforms up top, local run/doctor instructions
- Update ARCHITECTURE.md repo structure and AGENTS.md shellcheck command

Author: mhfs

AGENTS.md

@@ -82,7 +82,7 @@ It does **NOT** install:
 
 ## Commands
 
-- `shellcheck -x setup.sh doctor.sh lib/migrate.sh` — Lint bash scripts
+- `shellcheck -x setup.sh doctor.sh lib/*.sh` — Lint bash scripts
 - `bash -n setup.sh` — Check for syntax errors without executing
 - `bash doctor.sh` — Run post-setup diagnostic checks
 - `date +%s` — Generate a migration timestamp

ARCHITECTURE.md

@@ -143,11 +143,29 @@ cd <project> && bin/setup
 ```
 devsetup/
 ├── setup.sh              # Main bootstrap script (bash, entry point)
+├── doctor.sh             # Read-only diagnostic script (verifies setup.sh outcomes)
 ├── lib/
-│   └── migrate.sh        # Migration runner (sourced by setup.sh)
+│   ├── common.sh         # Shared helpers: OS detection, cmd_exists, formatting
+│   ├── migrate.sh        # Migration runner (sourced by setup.sh)
+│   ├── packages_setup.sh # Package manager bootstrap (brew/apt/pacman)
+│   ├── git_setup.sh      # git and GitHub CLI installation + auth
+│   ├── mise_setup.sh     # mise and Ruby (global default) installation
+│   ├── 1password_setup.sh # 1Password CLI installation
+│   ├── build_setup.sh    # Build essentials (Xcode CLT / build-essential / base-devel)
+│   ├── docker_setup.sh   # Docker, Docker Compose, Colima installation
+│   ├── aws_setup.sh      # AWS CLI and AWS VPN Client installation
+│   ├── repos_setup.sh    # ~/Work directory and repository cloning
+│   ├── packages_doctor.sh # Doctor checks for each corresponding setup module
+│   ├── git_doctor.sh
+│   ├── mise_doctor.sh
+│   ├── 1password_doctor.sh
+│   ├── build_doctor.sh
+│   ├── docker_doctor.sh
+│   ├── aws_doctor.sh
+│   ├── repos_doctor.sh
+│   └── migrate_doctor.sh
 ├── migrations/           # Run-once transition scripts
 │   └── .gitkeep
-├── doctor.sh             # Read-only diagnostic script (verifies setup.sh outcomes)
 ├── .github/
 │   └── workflows/
 │       └── ci.yml        # GitHub Actions: shellcheck + Ubuntu setup + doctor

README.md

@@ -2,9 +2,14 @@
 
 Bootstraps a developer machine with the baseline tools required to work on Trusted projects.
 
+**Supported platforms:** MacOS · Ubuntu · Omarchy
+
 ## What it installs
 
-- **Homebrew** (macOS) / apt updates (Ubuntu) / pacman updates (Arch)
+- **package management** 
+  - homebrew for MacOS 
+  - apt updates for Ubuntu 
+  - pacman/yay updates for Omarchy
 - **git** — version control
 - **gh** — GitHub CLI (+ authenticates with GitHub)
 - **mise** — version manager for Ruby, Node, etc.
@@ -32,34 +37,37 @@ cd <project> && bin/setup
 
 ## Re-running
 
-The script is idempotent. Run it again at any time to ensure your tools are up to date and apply new migrations:
+The script is idempotent. Run it again at any time to ensure your tools are up to date and apply new migrations.
+
+Locally from the cloned repo at `~/Work/devsetup`:
+
+```bash
+bash ~/Work/devsetup/setup.sh
+```
+
+Via curl (fetches latest from GitHub):
 
 ```bash
 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/trusted/devsetup/main/setup.sh)"
 ```
 
-## Migrations
 
-One-time environment changes are tracked as migration scripts in `migrations/`. They run automatically at the end of setup and are only executed once per machine.
+## Diagnosing your environment
 
-To re-run a specific migration:
+Run `doctor.sh` at any time to check that all expected tools are installed and no migrations are pending. It never changes anything — only reports:
 
 ```bash
-./setup.sh --rerun <timestamp>
+bash ~/Work/devsetup/doctor.sh
 ```
 
-## Supported platforms
-
-- macOS (Homebrew)
-- Ubuntu / Debian (apt)
-- Omarchy (pacman/yay)
+## Migrations
 
-## Diagnosing your environment
+One-time environment changes are tracked as migration scripts in `migrations/`. They run automatically at the end of setup and are only executed once per machine.
 
-Run `doctor.sh` at any time to check that all expected tools are installed and no migrations are pending. It never changes anything — only reports:
+To re-run a specific migration:
 
 ```bash
-bash doctor.sh
+bash ~/Work/devsetup/setup.sh --rerun <timestamp>
 ```
 
 ## How it works

lib/1password_setup.sh

@@ -17,15 +17,15 @@ else
     ubuntu)
       # Official 1Password CLI installation for Debian/Ubuntu
       curl -sS https://downloads.1password.com/linux/keys/1password.asc | \
-        sudo gpg --dearmor --output /usr/share/keyrings/1password-archive-keyring.gpg 2>/dev/null
+        sudo gpg --yes --dearmor --output /usr/share/keyrings/1password-archive-keyring.gpg 2>/dev/null
       echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/1password-archive-keyring.gpg] https://downloads.1password.com/linux/debian/$(dpkg --print-architecture) stable main" | \
         sudo tee /etc/apt/sources.list.d/1password.list > /dev/null
       sudo mkdir -p /etc/debsig/policies/AC2D62742012EA22/
       curl -sS https://downloads.1password.com/linux/debian/debsig/1password.pol | \
         sudo tee /etc/debsig/policies/AC2D62742012EA22/1password.pol > /dev/null
       sudo mkdir -p /usr/share/debsig/keyrings/AC2D62742012EA22
       curl -sS https://downloads.1password.com/linux/keys/1password.asc | \
-        sudo gpg --dearmor --output /usr/share/debsig/keyrings/AC2D62742012EA22/debsig.gpg 2>/dev/null
+        sudo gpg --yes --dearmor --output /usr/share/debsig/keyrings/AC2D62742012EA22/debsig.gpg 2>/dev/null
       sudo apt-get update -qq
       sudo apt-get install -y -qq 1password-cli
       ;;

lib/aws_doctor.sh

@@ -36,7 +36,8 @@ case "$OS" in
     fi
     ;;
   ubuntu|arch)
-    if cmd_exists awsvpnclient; then
+    # AWS VPN Client is a GUI app installed to /opt/awsvpnclient (no PATH binary)
+    if [ -d "/opt/awsvpnclient" ]; then
       check_pass "AWS VPN Client is installed"
     else
       check_fail "AWS VPN Client is not installed"

lib/aws_setup.sh

@@ -19,7 +19,15 @@ else
       brew install awscli
       ;;
     ubuntu)
-      curl -fsSL "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o /tmp/awscliv2.zip
+      # Ensure unzip is available (not always present on minimal Ubuntu installs)
+      if ! cmd_exists unzip; then
+        sudo apt-get install -y -qq unzip
+      fi
+      aws_arch="x86_64"
+      if [ "$(uname -m)" = "aarch64" ]; then
+        aws_arch="aarch64"
+      fi
+      curl -fsSL "https://awscli.amazonaws.com/awscli-exe-linux-${aws_arch}.zip" -o /tmp/awscliv2.zip
       unzip -qo /tmp/awscliv2.zip -d /tmp/aws-install
       sudo /tmp/aws-install/aws/install
       rm -rf /tmp/awscliv2.zip /tmp/aws-install
@@ -53,17 +61,19 @@ case "$OS" in
     fi
     ;;
   ubuntu)
-    if cmd_exists awsvpnclient; then
+    # AWS VPN Client is a GUI app installed to /opt/awsvpnclient (no PATH binary)
+    if [ -d "/opt/awsvpnclient" ]; then
       fmt_ok "AWS VPN Client already installed"
     else
       fmt_install "AWS VPN Client"
-      curl -fsSL "https://d20adtppz83p9s.cloudfront.net/GTK/latest/awsvpnclient_amd64.deb" -o /tmp/awsvpnclient.deb
+      vpn_arch="$(dpkg --print-architecture)"
+      curl -fsSL "https://d20adtppz83p9s.cloudfront.net/GTK/latest/awsvpnclient_${vpn_arch}.deb" -o /tmp/awsvpnclient.deb
       sudo apt-get install -y -qq /tmp/awsvpnclient.deb
       rm -f /tmp/awsvpnclient.deb
     fi
     ;;
   arch)
-    if cmd_exists awsvpnclient; then
+    if [ -d "/opt/awsvpnclient" ]; then
       fmt_ok "AWS VPN Client already installed"
     else
       fmt_install "AWS VPN Client"

lib/build_doctor.sh

@@ -25,7 +25,7 @@ case "$OS" in
     fi
     ;;
   ubuntu)
-    if dpkg -l build-essential > /dev/null 2>&1; then
+    if dpkg -s build-essential > /dev/null 2>&1; then
       check_pass "build-essential is installed"
     else
       check_fail "build-essential is not installed"

lib/build_setup.sh

@@ -18,7 +18,7 @@ case "$OS" in
     fi
     ;;
   ubuntu)
-    if dpkg -l build-essential > /dev/null 2>&1; then
+    if dpkg -s build-essential > /dev/null 2>&1; then
       fmt_ok "build-essential already installed"
     else
       fmt_install "build-essential"

lib/docker_doctor.sh

@@ -27,7 +27,7 @@ fi
 
 fmt_header "Docker Compose"
 
-if docker compose version > /dev/null 2>&1; then
+if cmd_exists docker && docker compose version > /dev/null 2>&1; then
   version_output="$(docker compose version --short 2>&1)"
   check_pass "Docker Compose is installed: $version_output"
 else

lib/git_setup.sh

@@ -59,11 +59,23 @@ fmt_header "GitHub Authentication"
 if gh auth status > /dev/null 2>&1; then
   fmt_ok "Already authenticated with GitHub"
 elif [ "${CI:-}" = "true" ]; then
-  echo "  Skipping interactive GitHub auth (CI environment detected)."
-  echo "  Set GH_TOKEN to authenticate gh in CI."
+  echo ""
+  echo "ERROR: Not authenticated with GitHub in CI."
+  echo "Set GH_TOKEN or GITHUB_TOKEN in your workflow environment."
+  exit 1
 else
   echo "  GitHub CLI needs to be authenticated."
   echo "  This will open a browser window for GitHub login."
   echo ""
   gh auth login --web --git-protocol https
+
+  # Verify authentication succeeded before continuing
+  if ! gh auth status > /dev/null 2>&1; then
+    echo ""
+    echo "ERROR: GitHub authentication failed or was cancelled."
+    echo "Setup cannot continue without GitHub access."
+    echo "Run this script again and complete the authentication step."
+    exit 1
+  fi
+  fmt_ok "Authenticated with GitHub"
 fi