# AGENTS.md - dotcube

## Project Overview

dotcube is a dotfiles management system that provisions ZSH shell configurations and system environments using Ansible. It supports macOS, Ubuntu/Debian, Raspbian, and WSL.

## Repository Structure

```
bin/                    # Executable shell scripts
  dotcube               # Main bootstrap and provisioning script
  dotcube-remote        # Remote machine provisioning via SSH
  dotcube-custom        # Machine-specific custom config deployer
  spinner               # UI spinner utility for long operations

ansible/                # Ansible playbook infrastructure
  main.yml              # Local provisioning playbook (hosts: localhost)
  remote.yml            # Remote provisioning playbook (hosts: all)
  ansible.cfg           # Ansible configuration
  requirements.yml      # Ansible Galaxy dependencies
  group_vars/all/       # Default role list and variables
  pre_tasks/            # Environment detection (WSL, user)
  callback_plugins/     # Custom output formatter
  roles/
    system/             # Base OS setup (first-run only)
    zsh/                # ZSH plugins, prompt, and config (every run)
    extra-tools/        # Convenience utilities (lsd, gh, jq, htop, etc.)
    netops/             # Networking tools (optional, -t netops)
    custom/             # Machine-specific configs from external repo
    upgrade/            # OS package upgrades
    rollback/           # Revert shell to original state

dotfiles/               # Configuration files deployed to the system
  zsh/
    zshrc               # Main zshrc (symlinked to ~/.zshrc)
    zsh-config/         # Sourced config files (exports, aliases, functions, prompt)
  starship/
    starship.toml       # Starship prompt configuration
  terminals/            # Terminal emulator configs
```

## Execution Flow

1. `bin/dotcube` bootstraps dependencies (git, python3, ansible) and clones/updates the repo
2. It runs `ansible-playbook` against `ansible/main.yml` (local) or `ansible/remote.yml` (remote)
3. Ansible pre-tasks detect WSL and current user
4. Roles execute based on tags (`-t`) or defaults defined in `group_vars/all/roles.yml`
5. The first-run marker at `~/.config/.dotcube.run` controls one-time-only tasks
6. ZSH config is symlinked: `~/.zshrc` -> `~/.dotcube/dotfiles/zsh/zshrc`

## Development Workflow

### Branch Strategy

- `main` is the default and production branch
- All changes (bug fixes, features, improvements) go through pull requests
- Each fix or feature gets its own branch off `main`

### Making Changes

For each fix or feature:

1. Create a branch off `main` with a descriptive name:
   - Bug fixes: `fix/<short-description>` (e.g. `fix/rollback-restore-typo`)
   - Features: `feat/<short-description>` (e.g. `feat/add-tmux-role`)
   - Improvements: `improve/<short-description>` (e.g. `improve/quote-shell-vars`)
2. Make the code changes on that branch
3. Commit with a message that explains **what** changed and **why** (not just "fixed bug")
4. Push the branch to origin
5. Create a pull request against `main` with:
   - A clear title (under 70 characters)
   - A summary section with bullet points describing the changes
   - A test plan section with steps to verify the fix/feature
6. After PR is created, delete the local branch (`git branch -d <branch>`)

### Multiple Fixes

When working on multiple independent fixes:
- Create each on a separate branch off `main`
- Each branch gets its own commit, push, and PR
- Clean up all local branches after PRs are created

## Code Change Guidelines

### Shell Scripts (`bin/`)

- All scripts use `#!/bin/bash` and `set -e`
- Color variables and emoji codes are defined at the top of each script that uses them
- The `_task` / `_cmd` / `_task_done` pattern in `bin/dotcube` handles progress display and error logging
- `_cmd` uses `eval` - avoid passing untrusted input
- Use `"$@"` (not `$*`) when forwarding arguments to preserve quoting

### Ansible Roles (`ansible/roles/`)

- Each role has a `tasks/main.yml` that dispatches to OS-specific files (`ubuntu.yml`, `osx.yml`) or a `common.yml`
- OS detection uses `ansible_os_family`: `Debian` for Linux, `Darwin` for macOS
- First-run detection: stat `{{ ansible_user_dir }}/.config/.dotcube.run` - the marker is created by the `dotcube` shell script, not by Ansible
- Default variables go in `defaults/main.yml` within each role
- Tasks use `become: true` when root privileges are needed
- Use `community.general.homebrew` for macOS packages, `ansible.builtin.apt` for Debian/Ubuntu

### ZSH Configuration (`dotfiles/zsh/`)

- `zshrc` sources everything through helper functions defined in `zsh-config/zsh-functions`
- `zsh_add_file` sources from the repo (`$ZDOTDIR_REPO`), `zsh_add_file_local` from `$ZDOTDIR` (~/.config/zsh)
- Plugins are cloned to `~/.config/zsh/plugins/` by both Ansible (initial install) and `zsh_add_plugin` (runtime fallback)
- The prompt is controlled by `MYPROMPT` variable in `zsh-config/zsh-options` (starship or pure)
- Machine-specific ZSH overrides go in `~/.config/zsh/zsh-custom` (not tracked in this repo)

### Adding a New Ansible Role

1. Create `ansible/roles/<name>/tasks/main.yml`
2. Add OS-specific task files if needed (`ubuntu.yml`, `osx.yml`)
3. Add default variables in `ansible/roles/<name>/defaults/main.yml`
4. To include in default runs, add the role name to `ansible/group_vars/all/roles.yml`
5. The role is always available via `dotcube -t <name>` regardless of the default list

### Testing Changes

- Run `dotcube -t <role> -vv` to test a specific role with verbose output
- Ansible tasks are idempotent - safe to run repeatedly
- Use `dotcube -t rollback` to revert shell changes
- For remote testing: `dotcube-remote <host> -t <role> -vv`

### Conventions

- Ansible task names follow the pattern: `ROLE | PLATFORM | Description`
- Shell scripts use `snake_case` functions prefixed with `_` for internal helpers
- Color output: define variables at script top, use `printf` with color codes
- Commit messages should describe what changed and why