docs: enhance README and usage documentation for various tools, including 1Password, AWS, Docker, Git, GitHub, Go, Kubernetes, Python, Terraform, and VS Code; remove outdated files and improve terminal setup instructions

README.md

···
 
 My collection of my dotfiles used across multiple systems and managed by [chezmoi](https://www.github.com/twpayne/chezmoi).
 
+## Core Prerequisite
+
+To get started, you primarily need a shell environment with `curl` or `wget` to download and execute the `chezmoi` installation script.
+
 ## Quick Start
+
+The following command will download and install `chezmoi` (if not already present), initialize it with this dotfiles repository, and apply the configuration. This process will also install and configure other necessary tools such as Homebrew, Zsh, oh-my-zsh, oh-my-posh, and the 1Password CLI.
 
 ```sh
   sh -c "$(curl -fsSL get.chezmoi.io)" -- init --apply mauvehed
 ```
 
-Personal secrets are stored in [1Password](https://1password.com) and you'll
-need the [1Password CLI](https://developer.1password.com/docs/cli/) installed.
+### 1Password Integration
 
-After installation or major changes you may need to relogin to 1Password with:
+Personal secrets are stored in [1Password](https://1password.com). The `chezmoi` setup will install the [1Password CLI](https://developer.1password.com/docs/cli/).
 
-```sh
-  eval $(op signin)
-```
+1.  **After the initial `chezmoi apply` completes**, you must sign in to the 1Password CLI:
+    ```sh
+    eval $(op signin)
+    ```
+2.  **Re-apply `chezmoi` (if needed)**: If the initial `chezmoi apply` could not fully provision all configurations due to 1Password not being authenticated, run the apply command again after signing in:
+    ```sh
+    chezmoi apply
+    ```
+
+## Tools Managed by These Dotfiles
 
-## Tools Used
+These dotfiles, through `chezmoi`, will install and manage the following tools and configurations on your system:
 
-| Name | Description | Required |
-| ---- | ----------- | -------- |
-| Terminal | [iTerm2](https://iterm2.com) | No |
-| Package manager | [homebrew](https://brew.sh/) | Yes |
-| Shell | [oh-my-zsh](https://github.com/ohmyzsh/ohmyzsh/wiki/Installing-ZSH) | Yes |
-| oh-my-posh         | [oh-my-posh](https://ohmyposh.dev) | Yes |
-| Dotfiles manager  | [chezmoi](https://chezmoi.io/) | Yes |
-| Password Manager  | [1password](https://www.1password.com/) | Yes |
+| Name                | Description                                       | Managed |
+| ------------------- | ------------------------------------------------- | -------- |
+| Terminal            | [iTerm2](https://iterm2.com) (macOS)              | Optional |
+| Package manager     | [Homebrew](https://brew.sh/)                      | Yes      |
+| Shell               | [Zsh](https://www.zsh.org/)                       | Yes      |
+| Shell Framework     | [oh-my-zsh](https://ohmyzsh.org/)                 | Yes      |
+| Shell Prompt Customizer | [oh-my-posh](https://ohmyposh.dev)              | Yes      |
+| Dotfiles manager    | [chezmoi](https://chezmoi.io/)                    | Yes      |
+| Password Manager CLI| [1Password CLI](https://www.1password.com/)       | Yes      |
 
 ## Command Reference
 

docs/1password-usage.md

···
+# 1Password Usage
+
+This document outlines how the [1Password CLI](https://developer.1password.com/docs/cli/) is integrated with `chezmoi` for managing secrets and sensitive configuration data in this dotfiles setup.
+
+## Overview
+
+1Password is the primary secrets manager for this dotfiles configuration. `chezmoi` is configured to use the 1Password CLI (`op`) to fetch secrets, which are then injected into configuration files via templates.
+
+## Prerequisites
+
+1.  **1Password Account**: You need an active 1Password account.
+2.  **1Password CLI Installed**: The `chezmoi` quick start process (see main `README.md`) handles the installation of the `op` CLI tool.
+3.  **Initial Sign-in**: As detailed in the main `README.md`, after the initial `chezmoi apply`, you must sign in to the 1Password CLI:
+    ```sh
+    eval $(op signin)
+    ```
+    You may need to run `chezmoi apply` again after this initial sign-in if some secrets were not provisioned.
+
+## Storing and Referencing Secrets with Chezmoi
+
+`chezmoi` utilizes its template functions to interact with the `op` CLI. Secrets are stored in your 1Password vaults, and `chezmoi` templates reference them, typically using the `onepassword` template function or by directly calling `op`.
+
+### General Approach
+
+1.  **Store Secret in 1Password**: Add your secret (e.g., API key, token, password) to your 1Password vault.
+    *   Use clear, consistent item names.
+    *   For multi-field items, note the field names you want to retrieve.
+2.  **Reference in Chezmoi Template**: In your `chezmoi` template file (e.g., `private_dot_config/some_app/config.toml.tmpl`), use a `chezmoi` template function to fetch the secret.
+
+### Example: Storing an API Key
+
+*   **In 1Password**:
+    *   Create a "Login" or "API Credential" item named, for example, `My App API Key`.
+    *   Store the API key in the `password` field or a custom field.
+*   **In `chezmoi` template**:
+    ```toml
+    # Example: .config/my_app/credentials.tmpl
+    # api_key = "{{ (onepasswordRead "op://Personal/My App API Key/password").stdout }}"
+    ```
+    *(Note: The exact `onepasswordRead` syntax or alternative `op` calls might vary based on your specific `chezmoi` helper functions or direct CLI usage in templates.)*
+
+### Storing GPG Git Signing Key ID
+
+To securely store and retrieve your GPG key ID for Git commit signing:
+
+1.  **In 1Password**:
+    *   Create a "Secure Note" or "Login" item, perhaps named `Git Configuration` or `My GPG Key`.
+    *   Add a custom field (e.g., named `git_signingkey_id`) and paste your GPG key ID into its value.
+2.  **In `chezmoi` template (e.g., `dot_gitconfig.tmpl`):**
+    ```gitconfig
+    # Example for .gitconfig.tmpl
+    [user]
+        name = {{ .name | quote }}
+        email = {{ .email | quote }}
+    #   signingkey = "{{ (onepasswordRead "op://Personal/Git Configuration/git_signingkey_id").stdout }}"
+    ```
+    *(Adjust the item name and path as per your 1Password setup.)*
+
+## Common `chezmoi` Template Functions for 1Password
+
+*(This section can be expanded with specific examples of `onepassword` functions or custom `op` CLI wrappers you use in your templates.)*
+
+*   `onepassword "item_name"`
+*   `onepasswordDetails "item_name"`
+*   `onepasswordRead "op_item_path"` (e.g., `op://Vault/ItemName/fieldname`)
+
+Refer to your `chezmoi` configuration and the official `chezmoi` documentation for the exact functions and syntax available and preferred in your setup.
+
+## Troubleshooting
+
+*   **Authentication Issues**: Ensure `eval $(op signin)` has been run and your session is active.
+*   **Item Paths**: Double-check the 1Password item names, vault names, and field names used in your templates. The `op item get "Item Name" --fields label="Field Name"` command can be useful for verifying.
+*   **Chezmoi Apply**: Remember to run `chezmoi apply` to propagate changes after updating templates or 1Password items. 

docs/DEPLOY.md

···
-# dotfiles
-
->This document is out of date/old and was a manual install process. Please follow the directions in [Chezmoi README](../README.md) instead of using this document.
->
->I am keeping this for historical reference in case I need any steps from here.
-
-## Linux
-
-Follow [Chezmoi README](../README.md)
-
-## MacOS
-
-Mostly follows [this guide](https://blog.larsbehrenberg.com/the-definitive-iterm2-and-oh-my-zsh-setup-on-macos)
-
-### Homebrew
-
-```sh
-/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
-```
-
-### iTerm2 or Warp.dev
-
-`https://app.warp.dev/download`
-
-`brew cask install iterm2` or [download](https://iterm2.com/downloads.html)
-
-### oh-my-zsh
-
-```sh
-brew install zsh && sh -c "$(curl -fsSL https://raw.githubusercontent.com/robbyrussell/oh-my-zsh/master/tools/install.sh)"
-```
-
-#### ohmyzsh theme
-
-```sh
-git clone --depth=1 https://github.com/romkatv/powerlevel10k.git ${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/themes/powerlevel10k
-```
-
-##### Install fonts/fix things
-
-```sh
-p10k configure
-```
-
-### YouTube Music Desktop App
-
-```sh
-brew install --cask ytmdesktop-youtube-music
-```
-
-### Setup TMUX
-
-Install TMUX PLugin Manager
-
-```sh
-git clone https://github.com/tmux-plugins/tpm ~/.tmux/plugins/tpm
-```
-
-#### Fetch updated tpm module (fixes error)
-
-``
-
-#### Install plugins from tmux.conf
-
-```sh
-run ^b-I inside tmux session
-```
-
-### Enable fingerprint auth for sudo on macOS
-
-```bash
-#!/bin/bash
-#
-# credit to machupicchubeta/dotfiles/bin/enable_to_sudo_authenticate_with_touch_id.sh
-set -eu
-set -o pipefail
-
-sudo chmod +w /etc/pam.d/sudo
-if ! grep -Eq '^auth\s.*\spam_tid\.so$' /etc/pam.d/sudo; then
-    ( set -e; set -o pipefail
-      # Add "pam_tid.so" to a first authentication
-      pam_sudo=$(awk 'fixed||!/^auth /{print} !fixed&&/^auth/{print "auth       sufficient     pam_tid.so";print;fixed=1}' /etc/pam.d/sudo)
-      sudo tee /etc/pam.d/sudo <<<"$pam_sudo"
-    )
-fi
-```
-
-## pyenv (& friends)
-
-Adopted from <https://realpython.com/intro-to-pyenv/>
-
-### macOS
-
-```sh
-brew install openssl readline sqlite3 xz zlib exa asdf fzf zoxide
-```
-
-```sh
-npm install -g opencommit
-```
-
-```sh
-curl https://pyenv.run | bash
-```
-
-```sh
-source ~/.zshrc
-```
-
-```sh
-python install <go find the latest from python.org>
-```

docs/README.md

···
-# dotfiles & config management
+# Dotfiles Documentation
 
-mauveFILES for personal and work systems running macOS or Linux
+Welcome to the documentation for this `dotfiles` collection. This section provides detailed information on various tools, configurations, and processes used.
 
-## quick start
+## Table of Contents
 
-```sh
-sh -c "$(curl -fsSL get.chezmoi.io)" -- init --apply mauvehed
-```
+Below is a list of available documents. Please refer to them for specific usage instructions and notes.
 
-## quick commands
+*   **[1Password Usage](./1password-usage.md)**: How 1Password CLI is used with `chezmoi` for secret management.
+*   **[AWS Usage](./aws-usage.md)**: Notes and common commands for interacting with AWS.
+*   **[Chezmoi Usage](./chezmoi-usage.md)**: In-depth details about `chezmoi` setup, template functions, and advanced usage.
+*   **[CLI Usage](./cli-usage.md)**: Information about various command-line interface tools and utilities.
+*   **[Corporate Apps Usage](./corporate-apps-usage.md)**: Notes on configuring and using corporate-specific applications.
+*   **[DEPLOY](./DEPLOY.md)**: Historical manual deployment instructions. **Note: This document is outdated. For current deployment, follow the `chezmoi` instructions in the main [project README](../README.md).**
+*   **[Docker Usage](./docker-usage.md)**: Tips and configurations related to Docker.
+*   **[Git Usage](./git-usage.md)**: Detailed Git workflows, aliases, and configurations.
+*   **[GitHub Usage](./github-usage.md)**: Notes on GitHub-specific configurations or workflows.
+*   **[Go Usage](./go-usage.md)**: Go programming language setup and environment.
+*   **[Kubernetes Usage](./kubernetes-usage.md)**: Kubernetes (k8s) setup, aliases, and common commands.
+*   **[Python Usage](./python-usage.md)**: Python environment setup and project notes.
+*   **[System Usage](./system-usage.md)**: General system-level configurations and macOS/Linux specific notes.
+*   **[Terminal Usage](./terminal-usage.md)**: Details about terminal setup (iTerm2, Zsh, Oh My Posh), keybindings, and plugins.
+*   **[Terraform Usage](./terraform-usage.md)**: Terraform setup, common commands, and state management notes.
+*   **[TODO](./TODO.md)**: A list of pending tasks and improvements for the dotfiles or documentation.
+*   **[User Apps Usage](./user-apps-usage.md)**: Configuration notes for various user applications.
+*   **[VSCode Usage](./vscode-usage.md)**: Visual Studio Code setup, extensions, and settings synchronization.
 
-To add new files to chezmoi control:
-
-```sh
-chezmoi add <file>
-```
-
-To edit a file under chezmoi control:
-
-```sh
-chezmoi edit <file>
-```
-
-To preview changes before applying:
-
-```sh
-chezmoi diff
-```
-
-To apply changes from `.local/share/chezmoi/` to ~/ use:
-
-```sh
-chezmoi apply
-```
-
-To both `git pull` and `chezmoi apply` use `update`
-
-```sh
-chezmoi update
-```
-
-To force a refresh the downloaded archives (from .`chezmoiexternal.toml`), use the --refresh-externals flag to chezmoi apply:
-
-```sh
-chezmoi --refresh-externals apply
-```
-
-Or `--refresh-externals` can be shortened to -R:
-
-```sh
-chezmoi -R apply
-```
-
-## resources
-
-* [Install](https://www.chezmoi.io/install/)
-* [Quick Start](https://www.chezmoi.io/quick-start/#using-chezmoi-across-multiple-machines)
-* [Setup](https://www.chezmoi.io/user-guide/setup/)
+Please explore the linked documents for more information on each topic.

docs/aws-usage.md

···
 # AWS Usage
 
-- [AWS Usage](#aws-usage)
-  - [TODO: Create documentation](#todo-create-documentation)
+This document provides an overview of using Amazon Web Services (AWS) tools, primarily the AWS Command Line Interface (CLI), within this dotfiles setup.
+
+## Overview
+
+The AWS CLI is a unified tool to manage your AWS services. This guide covers basic configuration and common commands.
+
+## Prerequisites
+
+*   **AWS Account**: An active AWS account.
+*   **AWS CLI Installed**: The AWS CLI is typically installed via Homebrew as part of the `chezmoi` setup if specified in your configurations.
+    ```sh
+    brew install awscli
+    ```
+*   **Configured Credentials**: AWS CLI needs credentials to interact with your AWS account. These are typically stored in `~/.aws/credentials` and `~/.aws/config`.
+    *   **Security Note**: It is highly recommended to manage AWS credentials securely, for example, by storing them in 1Password and having `chezmoi` templates populate the AWS configuration files, or by using a tool like `aws-vault`.
+
+## Configuration
+
+AWS CLI configuration can be managed via `aws configure` or by directly editing the files:
+
+*   `~/.aws/config`: Stores default region, output format, and named profiles.
+*   `~/.aws/credentials`: Stores AWS access keys for different profiles.
+
+### Example `~/.aws/config`:
+```ini
+[default]
+region = us-east-1
+output = json
 
-## TODO: Create documentation
+[profile my-other-profile]
+region = us-west-2
+output = text
+```
 
-- Package aws-vault
-- Package awscli
+### Example `~/.aws/credentials` (managed via 1Password/`chezmoi` or `aws-vault`):
+```ini
+[default]
+aws_access_key_id = YOUR_ACCESS_KEY_ID_DEFAULT
+aws_secret_access_key = YOUR_SECRET_ACCESS_KEY_DEFAULT
+
+[profile my-other-profile]
+aws_access_key_id = YOUR_ACCESS_KEY_ID_OTHER
+aws_secret_access_key = YOUR_SECRET_ACCESS_KEY_OTHER
+```
+
+Refer to `docs/1password-usage.md` for guidance on storing these credentials in 1Password and using `chezmoi` templates.
+
+## `aws-vault` (Recommended for Enhanced Security)
+
+[aws-vault](https://github.com/99designs/aws-vault) is a tool to securely store and access AWS credentials in your operating system's keystore. It helps in avoiding storing AWS credentials in plaintext files.
+
+### Installation (if not managed by `chezmoi`):
+```sh
+brew install aws-vault
+```
+
+### Basic Usage:
+
+1.  **Add credentials to `aws-vault`**:
+    ```sh
+    aws-vault add my-profile
+    ```
+    (This will prompt for your access key ID and secret access key)
+
+2.  **Execute commands using a profile**:
+    ```sh
+    aws-vault exec my-profile -- aws s3 ls
+    ```
+
+## Common AWS CLI Commands
+
+Replace `my-profile` with your desired AWS profile if not using `default`.
+
+*   **List S3 Buckets**:
+    ```sh
+    aws s3 ls --profile my-profile
+    # Using aws-vault:
+    # aws-vault exec my-profile -- aws s3 ls
+    ```
+
+*   **List EC2 Instances**:
+    ```sh
+    aws ec2 describe-instances --profile my-profile
+    # Using aws-vault:
+    # aws-vault exec my-profile -- aws ec2 describe-instances
+    ```
+
+*   **Get Caller Identity (useful for verifying current credentials)**:
+    ```sh
+    aws sts get-caller-identity --profile my-profile
+    # Using aws-vault:
+    # aws-vault exec my-profile -- aws sts get-caller-identity
+    ```
+
+## Resources
+
+*   **Official AWS CLI Documentation**:
+    *   [AWS CLI User Guide](https://docs.aws.amazon.com/cli/latest/userguide/)
+    *   [AWS CLI Command Reference](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/index.html)
+*   **`aws-vault` GitHub Repository**: [https://github.com/99designs/aws-vault](https://github.com/99designs/aws-vault)
+*   **1Password Documentation**: Refer to `docs/1password-usage.md` for managing secrets.
+
+This document is a starting point. Please refer to the official documentation for comprehensive information.

docs/bitwarden-usage.md

···
-# Bitwarden Usage
-
-- [Bitwarden Usage](#bitwarden-usage)
-  - [Overview](#overview)
-  - [Configuration](#configuration)
-    - [Prerequisites](#prerequisites)
-    - [Test](#test)
-
-## Overview
-
-This project uses [Bitwarden CLI](https://bitwarden.com/help/cli/) as a default password manager to store its non-sensitive configuration data. It is installed the first time the dotfiles run.
-
-## Configuration
-
-### Prerequisites
-
-- [Create your Bitwarden account](https://bitwarden.com/help/create-bitwarden-account/)
-- [Login to the Bitwarden web vault](https://vault.bitwarden.com/#/login)
-- [Create a new Identity item](https://bitwarden.com/help/custom-fields/) with the `Name` filed set to `dotfiles`
-- Fill in the following fields
-  - `First name`
-  - `Last name`
-  - `Username` - this can be your shortcode
-  - `Email`
-  - `git_signingkey` - this is a custom field to store your gpg Git commit signing key ID
-
-### Test
-
-Log in using the Bitwarden CLI and fetch the `dotfiles` Identity item
-
-```shell
-bw login
-bw unlock # if your session has expired
-export BW_SESSION="[session]"
-bw get item dotfiles | jq
-```
-Tou should be presented with a similar output
-
-```json
-[
-  {
-    "object": "item",
-    "id": "00000000-0000-0000-0000-000000000000",
-    "name": "dotfiles",
-    ...
-    "fields": [
-      {
-        "name": "git_signingkey",
-        "value": "1234567890ABCDEF1234567890ABCDEF12345678"
-      }
-    ],
-    "identity": {
-      "firstName": "[your first name]",
-      "lastName": "[your last name]",
-      "email": "[your email]",
-      "username": "[your username]"
-    },
-    ...
-  }
-]
-```
-
-To fetch any changes made using the online service, run the following command:
-
-```shell
-bw sync
-```

docs/chezmoi-usage.md

···
-# Chezmoi Usage
+# Chezmoi Usage: In-Depth Guide
 
-- [Chezmoi Usage](#chezmoi-usage)
-  - [Overview](#overview)
-  - [Installation](#installation)
-    - [Flow diagram](#flow-diagram)
-  - [Usage](#usage)
-    - [Flow diagram](#flow-diagram-1)
-  - [Useful commands](#useful-commands)
-    - [Apply changes from the local repository](#apply-changes-from-the-local-repository)
-    - [Show cached configuration data](#show-cached-configuration-data)
-    - [Test a template code snippet](#test-a-template-code-snippet)
+This document provides a comprehensive guide to using `chezmoi` for managing your dotfiles, expanding on the information in the main `README.md`.
 
 ## Overview
 
-This dotfiles repository is configured and managed by the `chezmoi` project. [chezmoi](https://www.chezmoi.io/), pronounced _/ʃeɪ mwa/ (shay-moi)_ is currently the [most complete and most hackable](https://www.chezmoi.io/comparison-table/) dotfiles manager out there.
+[Chezmoi](https://www.chezmoi.io/) (pronounced _/ʃeɪ mwa/ - shay moi) is a powerful, flexible, and secure dotfiles manager. It helps you manage your configuration files (dotfiles) across multiple machines with ease.
 
-## Installation
+Key features leveraged in this setup include:
+*   **Templating**: Using Go templates (with Sprig functions and custom data) to make dotfiles dynamic.
+*   **Secret Management**: Integration with 1Password CLI to securely handle sensitive data.
+*   **OS-Specific Configuration**: Applying different configurations based on the operating system.
+*   **Script Execution**: Running scripts at various points in `chezmoi`'s lifecycle (`run_once_`, `run_onchange_`, etc.).
+*   **External File Management**: Managing files and archives from external sources.
+
+## Core Concepts
 
-The following instruction clones [dotfiles](https://github.com/make-ops-tools/dotfiles) repository into the `~/.local/share/chezmoi/` directory and next applies changes accordingly, to your home directory `~/`. During the setup it prompts you to provide configuration options like Git committer name and email address, etc.
+*   **Source Directory**: Where `chezmoi` stores your dotfiles and configurations (typically `~/.local/share/chezmoi`). This directory is a Git repository.
+*   **Target Directory**: Your home directory (`~`) where `chezmoi` applies the configurations.
+*   **Configuration File**: `~/.config/chezmoi/chezmoi.toml` (or `.yaml`/`.json`) stores `chezmoi`'s own configuration, including data accessible in templates.
 
-```shell
-bash -c "$(curl -fsLS get.chezmoi.io)" -- init --apply "make-ops-tools"
+## Installation and Initialization
+
+As covered in the main `README.md`, initialization typically involves:
+
+```sh
+sh -c "$(curl -fsSL get.chezmoi.io)" -- init --apply mauvehed
 ```
+This command:
+1.  Downloads and installs `chezmoi` if not present.
+2.  Clones your dotfiles repository (github.com/mauvehed/dotfiles) into `~/.local/share/chezmoi`.
+3.  Prompts for any initial configuration data defined in `.chezmoi.toml.tmpl`.
+4.  Applies the dotfiles to your home directory.
 
-### Flow diagram
+### Initial Setup Flow (Conceptual)
 
 ```mermaid
 sequenceDiagram
   autonumber
-  participant home directory
-  participant working copy
-  participant local repo
-  participant remote repo
-  Note over home directory: archive current files
-  remote repo->>local repo: chezmoi init --apply  <repo>
-  Note left of local repo: prompt for configuration
-  local repo->>home directory: chezmoi init --apply  <repo>
+  participant User
+  participant Shell
+  participant Chezmoi
+  participant Git
+  participant GitHub (mauvehed/dotfiles)
+  participant "1Password CLI (op)"
+
+  User->>Shell: Runs install/init command
+  Shell->>Chezmoi: Installs/Updates chezmoi binary
+  Chezmoi->>GitHub (mauvehed/dotfiles): Clones/Pulls repository into source dir
+  Chezmoi->>User: Prompts for template data (if .chezmoi.toml.tmpl exists)
+  Note over Chezmoi: Reads .chezmoi.toml, .chezmoidata.*, etc.
+  Chezmoi->>"1Password CLI (op)": (Potentially) Fetches data via template functions
+  Chezmoi->>Shell: Executes run_once_ scripts, creates symlinks, applies templates to target dir (Home)
 ```
+*(This diagram is a simplification of the actual process)*
+
+## Common `chezmoi` Commands
 
-## Usage
+*   **`chezmoi add <path_to_file_in_home>`**: Adds a file from your home directory to `chezmoi`'s source directory.
+    *   Example: `chezmoi add ~/.gitconfig`
+    *   Use the `-T` or `--template` flag to add it as a template: `chezmoi add ~/.gitconfig --template`
+    *   Use the `-e` or `--encrypt` flag to add it as an encrypted file (less common now with 1Password integration for secrets).
+
+*   **`chezmoi edit <path_to_file_in_home>`**: Opens a file managed by `chezmoi` in your `$EDITOR` by operating on the source file.
+    *   Example: `chezmoi edit ~/.gitconfig`
+
+*   **`chezmoi apply [-v --dry-run]`**: Applies changes from the source directory to the target directory.
+    *   `-v` / `--verbose`: Shows what changes are being made.
+    *   `--dry-run`: Shows what would be changed without actually making changes.
+    *   `--init`: Re-runs initialization steps (useful if `.chezmoi.toml.tmpl` changes).
+    *   `-R` / `--refresh-externals`: Forces a refresh of externally managed files.
+
+*   **`chezmoi update`**: Pulls changes from your Git remote, then applies changes.
+    *   Equivalent to `chezmoi git pull && chezmoi apply` (simplified).
+
+*   **`chezmoi diff`**: Shows the differences between the target state in your home directory and the state defined by your source directory and templates.
+
+*   **`chezmoi forget <path_to_file_in_home>`**: Removes a file from `chezmoi` management (it will no longer be updated by `chezmoi apply`). The file in your home directory is not deleted by this command.
+
+*   **`chezmoi remove <path_to_file_in_home>`**: Removes a file from `chezmoi` management AND deletes it from the source directory. The file in your home directory is not deleted by this command.
+
+*   **`chezmoi chattr <attributes> <target>`**: Changes attributes of a target in the source directory (e.g., `private`, `readonly`, `template`, `executable`, `empty`).
+    *   Example: `chezmoi chattr template ~/.gitconfig` (makes it a template)
+    *   Example: `chezmoi chattr private ~/.ssh/config` (marks it as private)
+
+*   **`chezmoi doctor`**: Checks for common problems with your setup.
+
+*   **`chezmoi cd`**: Opens a new shell in the source directory (`~/.local/share/chezmoi`).
+
+*   **`chezmoi data`**: Prints the data available to templates (merges data from various sources). Useful for debugging templates.
+    *   Example: `chezmoi data | jq` (if `jq` is installed)
+
+*   **`chezmoi execute-template <template_string_or_file>`**: Executes a Go template. Useful for testing template snippets.
+    *   Example (1Password): `chezmoi execute-template '{{ (onepasswordRead "op://Personal/API_KEY_MYAPP/password").stdout | trim }}'`
+    *   Example (OS specific): `chezmoi execute-template '{{ if eq .chezmoi.os "darwin" }}macOS Specific Value{{ else }}Other OS Value{{ end }}'`
+
+*   **`chezmoi git <git_args...>`**: Runs Git commands in the source directory.
+    *   Example: `chezmoi git status`, `chezmoi git push`
+
+## Templating
+
+`chezmoi` uses Go's [text/template](https://pkg.go.dev/text/template) package. This allows for dynamic configuration files.
+
+*   **Syntax**: Templates are enclosed in `{{ }}`.
+*   **Sprig Functions**: Over 100 helpful [Sprig functions](http://masterminds.github.io/sprig/) are available (e.g., string manipulation, math, data structures).
+*   **`chezmoi` Specific Data**: `chezmoi` provides variables like `.chezmoi.os`, `.chezmoi.hostname`, etc. See `chezmoi data`.
+*   **Custom Data**: Data from `.chezmoi.toml` or data files (e.g., `.chezmoidata.yaml`) is available.
+*   **1Password Integration**: Use functions like `onepassword`, `onepasswordRead`, `onepasswordDocument` to fetch secrets from 1Password. See `docs/1password-usage.md` for details.
+    ```toml
+    # Example in a .gitconfig.tmpl
+    [user]
+        email = {{ .email | quote }}
+        signingkey = {{ (onepasswordRead "op://Personal/Git Keys/signingkey_id").stdout | trim | quote }}
+    ```
 
-If you decide to extend the configuration of your dotfiles and include an additional file to be managed, here is an example on how to do that
+## Scripts
 
-```shell
-chezmoi add ~/.bashrc
-chezmoi edit ~/.bashrc
-chezmoi diff
-chezmoi apply -v
-chezmoi cd
-git add .
-git commit -S -m "Add .bashrc"
-git push
-exit
+`chezmoi` can execute scripts at different points:
+
+*   **`run_once_*.sh`** (or other extensions): Executed only once per machine. Useful for initial setup tasks (e.g., installing Homebrew).
+*   **`run_onchange_*.sh`**: Executed if their content (or the content of files they depend on via comments) changes. Useful for tasks that need to re-run if a related config file changes.
+*   **`run_before_*.sh`**: Run before `chezmoi apply` applies changes for that script's directory.
+*   **`run_after_*.sh`**: Run after `chezmoi apply` applies changes for that script's directory.
+
+Scripts must be executable. `chezmoi` adds template functions to the script's environment as environment variables.
+
+## Managing External Files (`.chezmoiexternal.toml`)
+
+`chezmoi` can manage files and archives from external sources (URLs) using a `.chezmoiexternal.toml` file in the source directory.
+
+*   **Use Cases**: Downloading a specific version of a tool, fetching a `Brewfile` from a gist, managing `oh-my-zsh` installation/updates.
+*   **Format**: TOML file defining targets and sources.
+*   **Refresh**: Use `chezmoi apply -R` or `chezmoi apply --refresh-externals` to force download/update.
+
+Example `.chezmoiexternal.toml` entry:
+```toml
+# ["{{ .chezmoi.sourceDir }}/path/to/oh-my-zsh.sh"]
+#   type = "file"
+#   url = "https://raw.github.com/ohmyzsh/ohmyzsh/master/tools/install.sh"
+#   refreshPeriod = "168h" # Refresh once a week
 ```
 
-### Flow diagram
+## Managing Dotfile Attributes
 
-```mermaid
-sequenceDiagram
-  participant home directory
-  participant working copy
-  participant local repo
-  participant your remote repo
-  home directory->>local repo: chezmoi init
-  home directory->>working copy: chezmoi add <file>
-  working copy->>working copy: chezmoi edit <file>
-  working copy-->>home directory: chezmoi diff
-  working copy->>home directory: chezmoi apply
-  home directory-->>working copy: chezmoi cd
-  working copy->>local repo: git add
-  working copy->>local repo: git commit
-  local repo->>local repo: git remote add origin<br/>git branch
-  local repo->>your remote repo: git push
-  working copy-->>home directory: exit
-```
+`chezmoi` allows setting attributes for files and directories in the source directory, influencing how they are treated:
+
+*   **`private_` prefix**: The target file will have permissions `0600` (or `0700` for directories).
+*   **`readonly_` prefix**: The target file will be read-only.
+*   **`executable_` prefix**: The target file will be executable.
+*   **`empty_` prefix**: The target file will be created empty if it does not exist.
+*   **`.tmpl` suffix**: The file is treated as a Go template.
+*   **`.encrypted` suffix**: The file is encrypted using GPG (less common with 1Password integration).
+
+These can also be managed with `chezmoi chattr`.
 
-## Useful commands
+## Troubleshooting
 
-### Apply changes from the local repository
+*   **`chezmoi doctor`**: Run this first to check for common issues.
+*   **`chezmoi -v apply --dry-run`**: Verbose dry run to see what `chezmoi` *thinks* it should do.
+*   **`chezmoi data`**: Inspect the data available to your templates.
+*   **Check Permissions**: Ensure scripts are executable, and `chezmoi` has rights to write to target locations.
+*   **Template Errors**: `chezmoi execute-template` is invaluable for debugging specific template snippets.
 
-```shell
-chezmoi cd
-pwd # should be ~/.local/share/chezmoi
-chezmoi apply --init
-```
+## Advanced Usage Flow (Adding a new templated file with a secret)
 
-### Show cached configuration data
+```mermaid
+sequenceDiagram
+  participant User
+  participant "1Password"
+  participant Shell (Terminal)
+  participant "Chezmoi Source Dir (~/.local/share/chezmoi)"
+  participant "Home Directory (~/)"
 
-```shell
-chezmoi data | jq
-cat ~/.config/chezmoi/chezmoi.toml
+  User->>"1Password": Add new secret (e.g., API key for myapp)
+  User->>Shell (Terminal): `touch ~/.config/myapp/config.toml` (create target file initially)
+  User->>Shell (Terminal): `chezmoi add ~/.config/myapp/config.toml -T` (add as template)
+  User->>Shell (Terminal): `chezmoi edit ~/.config/myapp/config.toml`
+  Note over Shell (Terminal): Editor opens `.../dot_config/myapp/config.toml.tmpl`
+  User->>Shell (Terminal): Edit template to include `{{ onepasswordRead "op://..." }}`
+  User->>Shell (Terminal): `chezmoi diff` (review changes)
+  User->>Shell (Terminal): `chezmoi apply -v`
+  Chezmoi Source Dir (~/.local/share/chezmoi)-->>Home Directory (~/): Applies templated file, fetching secret
+  User->>Shell (Terminal): `chezmoi cd`
+  User->>Shell (Terminal): `git add .`
+  User->>Shell (Terminal): `git commit -m "Add config for myapp with secret"`
+  User->>Shell (Terminal): `git push`
 ```
 
-### Test a template code snippet
+## Resources
 
-```shell
-chezmoi execute-template '{{ (bitwarden "item" "dotfiles").identity.firstName }} {{ (bitwarden "item" "dotfiles").identity.lastName }}'
-```
+*   **Official `chezmoi` Website**: [https://www.chezmoi.io/](https://www.chezmoi.io/)
+*   **`chezmoi` User Guide**: [https://www.chezmoi.io/user-guide/](https://www.chezmoi.io/user-guide/)
+*   **`chezmoi` Reference**: [https://www.chezmoi.io/reference/](https://www.chezmoi.io/reference/)
+*   **`docs/1password-usage.md`**: For details on 1Password integration.
+
+This guide should provide a solid foundation for working with `chezmoi` in this dotfiles setup. Refer to the official `chezmoi` documentation for the most detailed and up-to-date information.

docs/cli-usage.md

···
-# Command-line Interface Usage
+# Enhanced Command-Line Interface (CLI) Usage
+
+This document details configurations and tools aimed at creating a powerful, consistent, and user-friendly command-line interface (CLI) experience, primarily within a Zsh environment managed by `chezmoi`.
+
+## Overview
+
+A productive CLI environment goes beyond just the shell and prompt. It involves using enhanced versions of standard utilities, organizing shell configurations logically, and leveraging tools that streamline common tasks.
+
+## Striving for Consistency (GNU Coreutils on macOS)
+
+To achieve a more GNU/Linux-like CLI experience on macOS, GNU core utilities are often installed. These provide versions of common commands (`ls`, `cp`, `mv`, `date`, `cat`, etc.) with features and options consistent with their Linux counterparts.
+
+*   **Installation (macOS with Homebrew)**:
+    ```sh
+    brew install coreutils findutils gnu-tar gnu-sed gawk gnutls gnu-indent gnu-getopt grep
+    ```
+    (You might have a more specific list in your `Brewfile`.)
+*   **Usage**: These GNU versions are typically prefixed with `g` (e.g., `gls`, `gcat`, `gdate`) to avoid conflicts with the native macOS utilities.
+*   **PATH Configuration**: To use these GNU versions by their standard names (e.g., `ls` instead of `gls`), you would add their directory (e.g., `$(brew --prefix coreutils)/libexec/gnubin`) to the beginning of your `$PATH`.
+    *   This is often handled in a dedicated `.path` file or directly in your `.zshrc` / `.zshenv`, managed by `chezmoi`.
+
+## Shell Configuration Files
+
+To keep the main shell configuration file (e.g., `~/.zshrc`) clean and organized, specific aspects of the shell setup are often broken out into separate files, sourced by the main config. These are managed by `chezmoi`.
+
+*   **`~/.path` (or similar)**: Manages the `$PATH` environment variable. It defines the order in which directories are searched for executables. Example content:
+    ```sh
+    # Example .path structure
+    export PATH="$HOME/.local/bin:$PATH"
+    export PATH="$(brew --prefix)/bin:$(brew --prefix)/sbin:$PATH" # Homebrew
+    # Add GNU coreutils if preferred
+    # export PATH="$(brew --prefix coreutils)/libexec/gnubin:$PATH"
+    ```
+
+*   **`~/.exports` (or similar)**: Sets other essential environment variables (e.g., `EDITOR`, `LANG`, `PAGER`, custom variables for tools).
+    ```sh
+    # Example .exports
+    export EDITOR='vim'
+    export LANG='en_US.UTF-8'
+    export PAGER='less'
+    ```
+
+*   **`~/.functions` (or similar)**: Defines custom shell functions to automate common tasks or create complex commands.
+    ```sh
+    # Example function in .functions
+    # mkcd() {
+    #   mkdir -p "$1" && cd "$1"
+    # }
+    ```
+
+*   **`~/.aliases` (or similar)**: Contains command aliases for frequently used commands or commands with common options.
+    ```sh
+    # Example .aliases
+    # alias ll='ls -alhF'
+    # alias update='sudo apt update && sudo apt upgrade -y' # Linux example
+    # alias brewup='brew update && brew upgrade && brew cleanup' # macOS example
+    ```
 
-- [Command-line Interface Usage](#command-line-interface-usage)
-  - [TODO: Create documentation](#todo-create-documentation)
+These files are typically sourced from `~/.zshrc` in a specific order.
 
-## TODO: Create documentation
+## Essential CLI Enhancement Tools
 
-- Consistent GNU/Linux-like CLI experience
-- Shell files
-  - .path
-  - .exports
-  - .functions
-  - .aliases
+These tools replace or augment standard CLI utilities for a better experience. They are usually installed via package managers (Homebrew, apt, etc.) and managed by `chezmoi`.
+
+*   **`exa`** or **`lsd`**: Modern replacements for `ls` with more colors, icons, and features.
+    *   [exa](https://the.exa.website/), [lsd](https://github.com/Peltoche/lsd)
+*   **`bat`**: A `cat` clone with syntax highlighting and Git integration.
+    *   [bat](https://github.com/sharkdp/bat)
+*   **`fd`**: A simple, fast, and user-friendly alternative to `find`.
+    *   [fd](https://github.com/sharkdp/fd)
+*   **`ripgrep` (`rg`)**: A line-oriented search tool that recursively searches the current directory for a regex pattern (very fast alternative to `grep`).
+    *   [ripgrep](https://github.com/BurntSushi/ripgrep)
+*   **`fzf`**: A command-line fuzzy finder for history, files, processes, etc. Often integrated with shell keybindings (`Ctrl+R`, `Ctrl+T`).
+    *   [fzf](https://github.com/junegunn/fzf)
+*   **`zoxide`**: A smarter `cd` command that learns your habits.
+    *   [zoxide](https://github.com/ajeetdsouza/zoxide)
+*   **`jq`**: A lightweight and flexible command-line JSON processor.
+    *   [jq](https://stedolan.github.io/jq/)
+*   **`yq`**: A command-line YAML, JSON, and XML processor (similar to `jq` but for more formats).
+    *   [yq (Python version)](https://github.com/kislyuk/yq) or [yq (Go version)](https://github.com/mikefarah/yq)
+*   **`tldr`**: Collaborative cheatsheets for console commands. Provides simplified man pages.
+    *   [tldr-pages](https://tldr.sh/)
+*   **`navi`** or **`cheat`**: Interactive command-line cheatsheet tools.
+    *   [navi](https://github.com/denisidoro/navi), [cheat](https://github.com/cheat/cheat)
+*   **`procs`**: A modern replacement for `ps` written in Rust.
+    *   [procs](https://github.com/dalance/procs)
+*   **`httpie`** or **`curlie`**: User-friendly CLI HTTP clients, alternatives to `curl`.
+    *   [HTTPie](https://httpie.io/), [curlie](https://github.com/rs/curlie)
+
+## General Tips
+
+*   **Keybindings**: Customize Zsh keybindings (often in `.zshrc` or a dedicated file) for frequently used actions or fzf integrations.
+*   **Dotfiles Management**: Use `chezmoi edit <filename>` to easily edit any of these configuration files.
+
+## Resources
+
+*   **GNU Coreutils**: [https://www.gnu.org/software/coreutils/](https://www.gnu.org/software/coreutils/)
+*   Links to individual tools are provided in the list above.
+*   **Awesome Shell**: [https://github.com/alebcay/awesome-shell](https://github.com/alebcay/awesome-shell) (A curated list of awesome command-line frameworks, toolkits, guides, and gizmos)
+*   **Awesome CLI Apps**: [https://github.com/agarrharr/awesome-cli-apps](https://github.com/agarrharr/awesome-cli-apps)
+
+This setup aims to make your command-line interactions more efficient and enjoyable. Explore the tools and customize them to fit your workflow.

docs/corporate-apps-usage.md

···
-# Corporate Apps Usage
-
-- [Corporate Apps Usage](#corporate-apps-usage)
-  - [TODO: Create documentation](#todo-create-documentation)
-
-## TODO: Create documentation

docs/docker-usage.md

···
 # Docker Usage
 
-- [Docker Usage](#docker-usage)
-  - [TODO: Create documentation](#todo-create-documentation)
+This document provides a basic guide to using Docker, including common commands and concepts relevant to a development workflow.
+
+## Overview
+
+[Docker](https://www.docker.com/) is a platform for developing, shipping, and running applications in containers. Containers allow you to package an application with all of its dependencies into a standardized unit for software development.
+
+## Installation
+
+*   **Docker Desktop**: For macOS and Windows, [Docker Desktop](https://www.docker.com/products/docker-desktop/) is the easiest way to install Docker. It includes the Docker Engine, Docker CLI client, Docker Compose, Kubernetes, and more.
+*   **Linux**: On Linux, you can install the Docker Engine and CLI separately. Follow the official installation guides for your distribution (e.g., [Install Docker Engine on Ubuntu](https://docs.docker.com/engine/install/ubuntu/)).
+
+Installation might be managed by `chezmoi` if Docker is part of your standard toolset defined in your dotfiles.
+
+## Common Docker CLI Commands
+
+Here are some of the most frequently used Docker commands:
+
+*   **Pull an image from a registry (e.g., Docker Hub)**:
+    ```sh
+    docker pull <image_name>:<tag>
+    # Example: docker pull ubuntu:latest
+    ```
+
+*   **Run a container from an image**:
+    ```sh
+    docker run [options] <image_name>:<tag> [command]
+    # Example (interactive shell in an Ubuntu container):
+    # docker run -it ubuntu:latest /bin/bash
+    # Example (run a web server, map port 8080 to container's port 80):
+    # docker run -d -p 8080:80 nginx:latest
+    ```
+    *   `-d`: Detached mode (run in background)
+    *   `-it`: Interactive TTY
+    *   `-p <host_port>:<container_port>`: Port mapping
+    *   `--name <container_name>`: Assign a name to the container
+    *   `-v <host_path>:<container_path>`: Mount a volume
+
+*   **List running containers**:
+    ```sh
+    docker ps
+    ```
+
+*   **List all containers (running and stopped)**:
+    ```sh
+    docker ps -a
+    ```
+
+*   **View logs of a container**:
+    ```sh
+    docker logs <container_name_or_id>
+    # Follow logs: docker logs -f <container_name_or_id>
+    ```
+
+*   **Stop a running container**:
+    ```sh
+    docker stop <container_name_or_id>
+    ```
+
+*   **Remove a stopped container**:
+    ```sh
+    docker rm <container_name_or_id>
+    ```
+
+*   **List images**:
+    ```sh
+    docker images
+    ```
+
+*   **Remove an image**:
+    ```sh
+    docker rmi <image_name_or_id>
+    ```
+
+*   **Clean up unused resources (containers, networks, images)**:
+    ```sh
+    docker system prune
+    # To remove all unused images, not just dangling ones:
+    # docker system prune -a
+    ```
+
+## Docker Compose
+
+[Docker Compose](https://docs.docker.com/compose/) is a tool for defining and running multi-container Docker applications. With Compose, you use a YAML file (`docker-compose.yml`) to configure your application's services.
+
+### Example `docker-compose.yml` snippet:
+```yaml
+version: '3.8'
+services:
+  web:
+    image: nginx:latest
+    ports:
+      - "8080:80"
+  app:
+    image: my-custom-app
+    build: .
+    ports:
+      - "3000:3000"
+```
 
-## TODO: Create documentation
+### Common Docker Compose Commands:
 
-- [Development Containers](https://containers.dev/)
+*   **Start services defined in `docker-compose.yml`**:
+    ```sh
+    docker-compose up
+    # Start in detached mode: docker-compose up -d
+    ```
+
+*   **Stop services**:
+    ```sh
+    docker-compose down
+    ```
+
+*   **List services**:
+    ```sh
+    docker-compose ps
+    ```
+
+## Development Containers (Dev Containers)
+
+[Development Containers](https://containers.dev/) (Dev Containers) allow you to use a Docker container as a full-featured development environment. This is particularly useful with editors like VS Code.
+
+A `devcontainer.json` file in your project tells VS Code (and other tools) how to access (or create) a development container with a well-defined tool and runtime stack.
+
+### Key Benefits:
+*   **Consistent Environment**: Ensures everyone on the team uses the same development environment.
+*   **Tool Isolation**: Keeps tools and dependencies for different projects separate.
+*   **Pre-configured Setups**: Quickly onboard new developers with ready-to-use environments.
+
+Refer to the [official Dev Containers documentation](https://containers.dev/docs) and the [VS Code Remote - Containers documentation](https://code.visualstudio.com/docs/remote/containers) for setup and usage details.
+
+## Resources
+
+*   **Official Docker Documentation**: [https://docs.docker.com/](https://docs.docker.com/)
+*   **Docker Hub (Image Registry)**: [https://hub.docker.com/](https://hub.docker.com/)
+*   **Docker Compose Documentation**: [https://docs.docker.com/compose/](https://docs.docker.com/compose/)
+*   **Development Containers**: [https://containers.dev/](https://containers.dev/)
+*   **VS Code Remote - Containers**: [https://code.visualstudio.com/docs/devcontainers/containers](https://code.visualstudio.com/docs/devcontainers/containers) (Note: VS Code documentation now prefers /devcontainers/ over /remote/)
+
+This guide provides a starting point. Docker is a vast ecosystem, so refer to the official documentation for in-depth information.

docs/git-usage.md

···
-# Git Usage
+# Git Usage and Best Practices
 
-## Table of contents
+This document outlines Git configuration, best practices for commit signing with GPG and 1Password, and useful Git commands relevant to this dotfiles setup.
 
-- [Git Usage](#git-usage)
-  - [Table of contents](#table-of-contents)
-  - [Configuration](#configuration)
-  - [Signing commits](#signing-commits)
-    - [Troubleshooting](#troubleshooting)
-  - [Additional settings](#additional-settings)
-  - [Useful commands](#useful-commands)
+## Table of Contents
 
-## Configuration
+- [Git Usage and Best Practices](#git-usage-and-best-practices)
+  - [Table of Contents](#table-of-contents)
+  - [Core Git Configuration](#core-git-configuration)
+  - [Commit Signing with GPG and 1Password](#commit-signing-with-gpg-and-1password)
+    - [1. Generating or Importing Your GPG Key](#1-generating-or-importing-your-gpg-key)
+    - [2. Adding Your GPG Key ID to 1Password](#2-adding-your-gpg-key-id-to-1password)
+    - [3. Configuring Git to Use the GPG Key (via `chezmoi` and 1Password)](#3-configuring-git-to-use-the-gpg-key-via-chezmoi-and-1password)
+    - [4. Adding GPG Public Key to GitHub](#4-adding-gpg-public-key-to-github)
+    - [5. GPG Agent Configuration](#5-gpg-agent-configuration)
+    - [6. Troubleshooting GPG Signing](#6-troubleshooting-gpg-signing)
+  - [GitHub CLI Authentication (`gh auth login`)](#github-cli-authentication-gh-auth-login)
+  - [Common Git Workflows and Useful Commands](#common-git-workflows-and-useful-commands)
+    - [Basic Workflow](#basic-workflow)
+    - [Branching](#branching)
+    - [Stashing Changes](#stashing-changes)
+    - [Viewing History](#viewing-history)
+    - [Squashing Commits](#squashing-commits)
+    - [Tags](#tags)
+  - [Resources](#resources)
 
-<!-- markdownlint-disable-next-line no-inline-html -->
-The commands below will configure your Git command-line client globally. Please, update your username (<span style="color:red">Your Name</span>) and email address (<span style="color:red">youremail@domain</span>) in the code snippet below prior to executing it.
+## Core Git Configuration
 
-This configuration is to support trunk-based development and git linear history.
+Key Git settings are managed by `chezmoi` via the `dot_gitconfig.tmpl` template file, which generates `~/.gitconfig`.
+This configuration generally promotes trunk-based development and a linear Git history.
 
-```shell
-git config user.name "Your Name" # Use your full name here
-git config user.email "youremail@domain" # Use your email address here
-git config branch.autosetupmerge false
-git config branch.autosetuprebase always
-git config commit.gpgsign true
-git config core.autocrlf input
-git config core.filemode true
-git config core.hidedotfiles false
-git config core.ignorecase false
-git config credential.helper cache
-git config pull.rebase true
-git config push.default current
-git config push.followTags true
-git config rebase.autoStash true
-git config remote.origin.prune true
+Common global settings include:
+
+```ini
+# Example from dot_gitconfig.tmpl (values are templated)
+[user]
+  name = {{ .name | quote }}
+  email = {{ .email | quote }}
+  signingkey = {{ (onepasswordRead "op://Personal/Git GPG Key/key_id").stdout | trim | quote }} # Fetched from 1Password
+[commit]
+  gpgsign = true       # Sign all commits by default
+[pull]
+  rebase = true        # Prefer rebase over merge on pull
+[rebase]
+  autoStash = true     # Automatically stash changes before rebase
+[push]
+  default = current    # Push the current branch to a branch of the same name
+  followTags = true    # Push tags that point to commits being pushed
+[branch]
+  autosetupmerge = false # Do not automatically set up merge configurations
+  autosetuprebase = always # Always rebase when pulling on new branches
+[core]
+  autocrlf = input     # Handle line endings correctly
+  # ... other settings ...
+[remote "origin"]
+  prune = true         # Remove remote-tracking branches that no longer exist on the remote
 ```
 
-This is already set in the [`dot_gitconfig.tmpl`](https://github.com/make-ops-tools/dotfiles/blob/main/dot_gitconfig.tmpl) file, that is used as a template to create `~/.gitconfig`.
+*   The specific template is located at: `{{ .chezmoi.sourceDir }}/dot_gitconfig.tmpl`.
+*   Refer to the [Git Reference documentation](https://git-scm.com/docs) for details on these settings.
 
-More information on the git settings can be found in the [Git Reference documentation](https://git-scm.com/docs).
+## Commit Signing with GPG and 1Password
 
-## Signing commits
+Signing Git commits cryptographically verifies the committer's identity. This setup uses GPG for signing, with the GPG key ID managed via 1Password.
 
-Signing Git commits is a good practice and ensures the correct web of trust has been established for the distributed version control management.
+### 1. Generating or Importing Your GPG Key
 
-<!-- markdownlint-disable-next-line no-inline-html -->
-If you do not have it already generate a new pair of GPG keys. Please, change the passphrase (<span style="color:red">pleaseChooseYourKeyPassphrase</span>) below and save it in your password manager.
+If you don't have a GPG key, generate one:
 
-```shell
-USER_NAME="Your Name"
-USER_EMAIL="your.name@email"
-file=$(echo $USER_EMAIL | sed "s/[^[:alpha:]]/-/g")
-
-mkdir -p "$HOME/.gnupg"
-chmod 0700 "$HOME/.gnupg"
-cd "$HOME/.gnupg"
-cat > "$file.gpg-key.script" <<EOF
-  %echo Generating a GPG key
-  Key-Type: ECDSA
-  Key-Curve: nistp256
-  Subkey-Type: ECDH
-  Subkey-Curve: nistp256
-  Name-Real: $USER_NAME
-  Name-Email: $USER_EMAIL
-  Expire-Date: 0
-  Passphrase: pleaseChooseYourKeyPassphrase
-  %commit
-  %echo done
-EOF
-gpg --batch --generate-key "$file.gpg-key.script"
-rm "$file.gpg-key.script"
-# or do it manually by running `gpg --full-gen-key`
+```sh
+gpg --full-gen-key
 ```
+Follow the prompts. An `ECDSA` key with `nistp256` curve is a good modern choice. Ensure you use a strong passphrase and store it securely (e.g., in 1Password).
 
-Make note of the ID and save the keys.
+If you have an existing GPG key, ensure it's in your GPG keyring.
 
-```shell
-gpg --list-secret-keys --keyid-format LONG $USER_EMAIL
-```
+### 2. Adding Your GPG Key ID to 1Password
 
-You should see a similar output to this
+Once you have a GPG key, get its Key ID:
 
-```shell
-sec   nistp256/AAAAAAAAAAAAAAAA 2023-01-01 [SCA]
+```sh
+gpg --list-secret-keys --keyid-format LONG "Your Name" # Or your email
+```
+Output will look like:
+```
+sec   nistp256/XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX YYYY-MM-DD [SCA]
       XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
-uid                 [ultimate] Your Name <your.name@email>
-ssb   nistp256/BBBBBBBBBBBBBBBB 2023-01-01 [E]
+uid                 [ultimate] Your Name <[e-mail]>
+ssb   nistp256/YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY YYYY-MM-DD [E]
 ```
+The long Key ID is `XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX` (the 40-character string).
 
-Export your keys.
+Store this Key ID in 1Password. For example, create a "Secure Note" or "Login" item named "Git GPG Key" and add a field/label (e.g., `key_id`) with your GPG Key ID as the value.
 
-```shell
-ID=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
-gpg --armor --export $ID > $file.gpg-key.pub
-gpg --armor --export-secret-keys $ID > $file.gpg-key
-```
+See `docs/1password-usage.md` for more on storing items in 1Password.
 
-Import already existing private key.
+### 3. Configuring Git to Use the GPG Key (via `chezmoi` and 1Password)
 
-```shell
-gpg --import $file.gpg-key
+As shown in the "Core Git Configuration" section, `dot_gitconfig.tmpl` is set up to fetch the `user.signingkey` from 1Password:
+
+```ini
+[user]
+  signingkey = {{ (onepasswordRead "op://Personal/Git GPG Key/key_id").stdout | trim | quote }}
 ```
+Ensure the 1Password item path (`op://Personal/Git GPG Key/key_id`) in your `dot_gitconfig.tmpl` matches where you stored the key ID in 1Password.
+`chezmoi apply` will populate your `~/.gitconfig` with this signing key.
 
-Remove keys from the GPG agent if no longer needed.
+### 4. Adding GPG Public Key to GitHub
 
-```shell
-gpg --delete-secret-keys $ID
-gpg --delete-keys $ID
-```
+To have GitHub show your commits as "Verified":
 
-Configure Git to use the new key.
+1.  Export your GPG public key:
+    ```sh
+    gpg --armor --export XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX # Use your Key ID
+    ```
+2.  Copy the entire output (starting with `-----BEGIN PGP PUBLIC KEY BLOCK-----`).
+3.  Go to [GitHub GPG keys settings](https://github.com/settings/keys) and add the new GPG key.
 
-```shell
-git config user.signingkey $ID
+### 5. GPG Agent Configuration
+
+To avoid entering your GPG passphrase for every commit, configure the `gpg-agent` to cache it. `chezmoi` manages `~/.gnupg/gpg-agent.conf`:
+
 ```
+# Example content for gpg-agent.conf.tmpl
+# Managed by chezmoi
 
-Upload the public key to your GitHub profile into the [GPG keys](https://github.com/settings/keys) section. After doing so, please make sure your email address appears as verified against the commits pushed to the remote.
+pinentry-program {{ .pinentryProgram | quote }} # Path to pinentry, templated by chezmoi
+default-cache-ttl 10800 # Cache passphrase for 3 hours
+max-cache-ttl 10800     # Max cache time
+```
+`chezmoi` templates can determine the correct `pinentry-program` path based on your OS.
+After changes, you might need to restart the agent: `gpgconf --kill gpg-agent`.
+
+### 6. Troubleshooting GPG Signing
+
+*   **Error: `gpg failed to sign the data` or `Inappropriate ioctl for device`**:
+    Ensure `export GPG_TTY=$(tty)` is in your shell configuration (e.g., `~/.exports` or `~/.zshrc`, managed by `chezmoi`). This allows GPG to prompt for a passphrase in the current terminal.
+    ```sh
+    # Ensure this line is in a chezmoi-managed shell startup file:
+    # export GPG_TTY=$(tty)
+    ```
+    Restart your shell or source the updated file.
+*   **No Pinentry Program Found**: Ensure `pinentry` is installed (e.g., `brew install pinentry-mac` on macOS) and `gpg-agent.conf` points to the correct program.
+*   **Secret Key Not Available**: Verify the key ID in `~/.gitconfig` matches a private key in your `gpg --list-secret-keys` output.
+
+## GitHub CLI Authentication (`gh auth login`)
+
+While Git uses SSH or HTTPS (often with a credential helper) for repository access, the GitHub CLI (`gh`) requires its own authentication.
 
-```shell
-cat $file.gpg-key.pub
+```sh
+gh auth login
 ```
+Follow the prompts. Authenticating with a web browser (HTTPS) is often simplest.
+Refer to `docs/github-usage.md` for more on using `gh`.
 
-### Troubleshooting
+## Common Git Workflows and Useful Commands
 
-If you receive the error message "error: gpg failed to sign the data", make sure you added `export GPG_TTY=$TTY` to your `~/.zshrc` or other file that is sourced by it, like `~/.exports` and restarted your terminal.
+### Basic Workflow
 
-```shell
-sed -i '/^export GPG_TTY/d' ~/.exports
-echo "export GPG_TTY=\$TTY" >> ~/.exports
+```sh
+git pull             # Fetch and integrate changes from remote
+git add .            # Stage all changes in the current directory
+# Or git add <file1> <file2> ... to stage specific files
+git commit -S -m "Your descriptive commit message" # Create a signed commit
+git push             # Push changes to the remote repository
 ```
 
-## Additional settings
+### Branching
+
+*   Create a new branch and switch to it:
+    ```sh
+    git checkout -b new-feature-branch
+    ```
+*   Switch to an existing branch:
+    ```sh
+    git checkout main
+    ```
+*   Delete a local branch (after merging):
+    ```sh
+    git branch -d feature-branch # Safe delete (only if merged)
+    git branch -D feature-branch # Force delete
+    ```
+*   Push a new local branch to remote and set up tracking:
+    ```sh
+    git push -u origin new-feature-branch
+    ```
+
+### Stashing Changes
 
-Configure caching git commit signature passphrase for 3 hours
+Temporarily save uncommitted changes:
 
-```shell
-source ~/.zshrc
-mkdir -p ~/.gnupg
-sed -i '/^pinentry-program/d' ~/.gnupg/gpg-agent.conf 2>/dev/null ||:
-echo "pinentry-program $(whereis -q pinentry)" >> ~/.gnupg/gpg-agent.conf
-sed -i '/^default-cache-ttl/d' ~/.gnupg/gpg-agent.conf
-echo "default-cache-ttl 10800" >> ~/.gnupg/gpg-agent.conf
-sed -i '/^max-cache-ttl/d' ~/.gnupg/gpg-agent.conf
-echo "max-cache-ttl 10800" >> ~/.gnupg/gpg-agent.conf
-gpgconf --kill gpg-agent
+```sh
+git stash push -m "WIP: some changes for later"
+git stash list
+git stash apply stash@{0} # Apply a specific stash
+git stash pop           # Apply the latest stash and remove it from the list
+git stash drop stash@{0}  # Remove a specific stash
 ```
 
-Please, see the [`assets/03-install-developer-tools.macos.sh`](https://github.com/make-ops-tools/dotfiles/blob/main/assets/03-install-developer-tools.macos.sh) file, as this section is part of the automated configuration.
+### Viewing History
+
+*   Compact log view:
+    ```sh
+    git log --oneline --graph --decorate --all
+    ```
+    (Consider creating a Git alias like `git la` for this.)
+*   View changes for a specific commit:
+    ```sh
+    git show <commit_hash>
+    ```
+*   View changes for a specific file:
+    ```sh
+    git log -p -- <file_path>
+    ```
+
+### Squashing Commits
+
+Combine multiple commits into a single one, often done before merging a feature branch.
 
-Authenticate to GitHub and set up your authorisation token
+*   Interactively rebase onto `main` (or your target branch), squashing commits from your current feature branch:
+    ```sh
+    # Assuming you are on your feature branch that branched off main
+    git rebase -i main
+    ```
+    In the interactive editor, change `pick` to `s` (squash) or `f` (fixup) for commits you want to merge into the preceding one. Edit commit messages as needed.
+*   Force push (with lease) if you've rewritten history on a shared branch (use with caution):
+    ```sh
+    git push --force-with-lease
+    ```
 
-```shell
-$ gh auth login
-? What account do you want to log into? GitHub.com
-? What is your preferred protocol for Git operations? HTTPS
-? Authenticate Git with your GitHub credentials? No
-? How would you like to authenticate GitHub CLI? Paste an authentication token
-Tip: you can generate a Personal Access Token here https://github.com/settings/tokens
-The minimum required scopes are 'repo', 'read:org'.
-? Paste your authentication token: github_pat_**********************************************************************************
-- gh config set -h github.com git_protocol https
-✓ Configured git protocol
-✓ Logged in as your-github-handle
+Alternatively, the example from the previous version for squashing all commits on a branch into one based on `main`:
+```sh
+# git checkout your-feature-branch
+# git reset $(git merge-base main $(git branch --show-current))
+# git add .
+# git commit -S -m "New single commit message for the feature"
+# git push --force-with-lease origin your-feature-branch
 ```
 
-## Useful commands
+### Tags
 
-Add your changes, create a signed commit, update from and push to remote
+Create lightweight or annotated tags for releases:
 
-```shell
-git add .
-git commit -S -m "Create a signed commit"
-git pull
-git push
+```sh
+git tag v1.0.0                                # Lightweight tag
+git tag -a v1.0.1 -m "Version 1.0.1 release"  # Annotated tag (signed if gpgsign=true)
+git push origin v1.0.1                        # Push a specific tag
+git push --tags                               # Push all tags
 ```
 
-Squash all commits on branch as one
+## Resources
+
+*   **Pro Git Book**: [https://git-scm.com/book/en/v2](https://git-scm.com/book/en/v2) (Excellent, comprehensive guide)
+*   **Git Reference Documentation**: [https://git-scm.com/docs](https://git-scm.com/docs)
+*   **GitHub GPG Signing Documentation**: [https://docs.github.com/en/authentication/managing-commit-signature-verification](https://docs.github.com/en/authentication/managing-commit-signature-verification)
+*   **1Password Documentation**: See `docs/1password-usage.md`
+*   **GitHub CLI Documentation**: See `docs/github-usage.md`
 
-```shell
-git checkout your-branch-name
-git reset $(git merge-base main $(git branch --show-current))
-git add .
-git commit -S -m "Create just one commit instead"
-git push --force-with-lease
-```
+This guide covers key Git practices for this dotfiles setup. Consistent use of signed commits and a clean history are encouraged.

docs/github-usage.md

···
 # GitHub Usage
 
-- [GitHub Usage](#github-usage)
-  - [TODO: Create documentation](#todo-create-documentation)
+This document provides guidance on interacting with GitHub, primarily focusing on the GitHub CLI tool (`gh`) and general best practices.
+
+## Overview
+
+GitHub is a platform for version control and collaboration using Git. The GitHub CLI (`gh`) brings GitHub to your terminal, allowing you to manage repositories, pull requests, issues, and more without leaving the command line.
+
+## GitHub CLI (`gh`)
+
+The GitHub CLI is the preferred way to interact with GitHub programmatically and from the terminal for many tasks.
+
+### Installation
+
+The GitHub CLI is typically installed via Homebrew if specified in your `chezmoi` configurations:
+```sh
+brew install gh
+```
+Refer to the [official installation guide](https://github.com/cli/cli#installation) for other methods.
+
+### Authentication
+
+After installation, you need to authenticate `gh` with your GitHub account:
+```sh
+gh auth login
+```
+Follow the prompts. Using `HTTPS` and authenticating with web browser is often the easiest method.
+
+### Common `gh` Commands
+
+*   **Repository Commands (`gh repo ...`)**
+    *   Clone a repository:
+        ```sh
+        gh repo clone <owner>/<repository_name>
+        # Example: gh repo clone cli/cli
+        ```
+    *   Create a new repository:
+        ```sh
+        gh repo create <repository_name> [options]
+        # Example: gh repo create my-new-project --public --source=.
+        ```
+    *   View a repository in the browser:
+        ```sh
+        gh repo view --web
+        ```
+
+*   **Pull Request Commands (`gh pr ...`)**
+    *   List pull requests:
+        ```sh
+        gh pr list
+        ```
+    *   View a specific pull request:
+        ```sh
+        gh pr view <pr_number_or_branch_name>
+        # View in browser: gh pr view <pr_number_or_branch_name> --web
+        ```
+    *   Checkout a pull request locally:
+        ```sh
+        gh pr checkout <pr_number_or_branch_name>
+        ```
+    *   Create a pull request:
+        ```sh
+        gh pr create [options]
+        # Example (prompts for title, body, base branch, etc.):
+        # gh pr create
+        # Example (with details):
+        # gh pr create --title "My Awesome Feature" --body "Details about the feature." --base main
+        ```
+    *   Diff a pull request:
+        ```sh
+        gh pr diff <pr_number_or_branch_name>
+        ```
 
-## TODO: Create documentation
+*   **Issue Commands (`gh issue ...`)**
+    *   List issues:
+        ```sh
+        gh issue list
+        ```
+    *   View an issue:
+        ```sh
+        gh issue view <issue_number>
+        # View in browser: gh issue view <issue_number> --web
+        ```
+    *   Create an issue:
+        ```sh
+        gh issue create --title "My Issue Title" --body "Issue details."
+        ```
+
+*   **Alias Management (`gh alias ...`)**
+    *   `gh` supports creating aliases for complex commands. Example:
+        ```sh
+        gh alias set myprs "pr list --author @me"
+        gh myprs # Runs the aliased command
+        ```
+
+## Git Configuration for GitHub
+
+Ensure your local Git configuration (see `docs/git-usage.md`) is set up correctly with your GitHub username and email, especially if you contribute to multiple repositories or use different identities.
+
+SSH keys are recommended for `git push/pull` operations with GitHub for better security and convenience. Refer to GitHub's documentation on [generating a new SSH key](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent) and [adding it to your GitHub account](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account).
+
+## Resources
+
+*   **GitHub CLI Official Documentation**: [https://cli.github.com/manual/](https://cli.github.com/manual/)
+*   **GitHub CLI GitHub Repository**: [https://github.com/cli/cli](https://github.com/cli/cli)
+*   **GitHub Help Documentation**: [https://docs.github.com/](https://docs.github.com/)
+*   **GitHub SSH Key Setup**: [Connecting to GitHub with SSH](https://docs.github.com/en/authentication/connecting-to-github-with-ssh)
+
+This document provides a basic overview. The GitHub CLI is very powerful; explore its manual for more commands and options.

docs/go-usage.md

···
-# Go Usage
+# Go (Golang) Usage
+
+This document provides a guide to setting up and using the Go programming language, including managing versions and common commands.
+
+## Overview
+
+[Go](https://go.dev/) (often referred to as Golang) is an open-source programming language designed by Google. It is known for its simplicity, efficiency, strong support for concurrency, and robust standard library.
+
+## Installation
+
+There are several ways to install Go:
+
+*   **Official Installers**: Download from [go.dev/dl/](https://go.dev/dl/).
+*   **Homebrew (macOS)**:
+    ```sh
+    brew install go
+    ```
+    This usually installs the latest stable version.
+*   **Go Version Manager (`goenv`)** (Recommended for managing multiple Go versions):
+    [goenv](https://github.com/syndbg/goenv) lets you easily switch between multiple versions of Go. It's similar to `pyenv` for Python or `tfenv` for Terraform.
+
+    **Installation of `goenv` (macOS with Homebrew):**
+    ```sh
+    brew install goenv
+    ```
+    For other systems or manual install, see the [goenv installation guide](https://github.com/syndbg/goenv#installation).
+
+    **Using `goenv`:**
+    1.  Initialize `goenv` in your shell (add to `.zshrc` or `.bashrc`, managed by `chezmoi`):
+        ```sh
+        # Example for .zshrc
+        # if command -v goenv 1>/dev/null 2>&1; then
+        #   eval "$(goenv init -)"
+        # fi
+        ```
+    2.  List available Go versions to install:
+        ```sh
+        goenv install -l
+        ```
+    3.  Install a specific Go version:
+        ```sh
+        goenv install <version>
+        # Example: goenv install 1.18.3
+        ```
+    4.  Set global or local (per-project) Go version:
+        ```sh
+        goenv global <version> # Sets the default Go version
+        goenv local <version>  # Creates a .go-version file in the current directory
+        ```
+
+If `chezmoi` manages your Go installation, it will handle the chosen installation method.
+
+## Environment Variables
+
+Go uses several environment variables to configure its behavior:
+
+*   **`GOROOT`**: The root of your Go installation (e.g., `/usr/local/go` or a path managed by `goenv`). Usually set automatically.
+*   **`GOPATH`**: Defines the root of your workspace. Before Go Modules, it was crucial for organizing Go code and compiled binaries. With Go Modules, its role has diminished but it still defines a default location for `go install` outside a module (`$HOME/go` by default).
+*   **`GOBIN`**: The directory where `go install` will place compiled binaries (if set). If not set, binaries are placed in `$GOPATH/bin` (or `$HOME/go/bin`).
+*   **`GO111MODULE`**: Controls Go Modules behavior.
+    *   `on`: Forces module-aware mode (default in Go 1.16+).
+    *   `auto`: Enables module mode if a `go.mod` file is present in the current or any parent directory.
+    *   `off`: Disables module mode, uses `GOPATH` mode.
+
+These are typically set in your shell profile (`.zshrc`, `.bash_profile`), managed by `chezmoi`.
+
+## Basic Go Commands
+
+*   **`go version`**: Displays the current Go version.
+    ```sh
+    go version
+    ```
+
+*   **`go run <filename.go>`**: Compiles and runs a Go program.
+    ```sh
+    go run main.go
+    ```
+
+*   **`go build [packages]`**: Compiles packages and their dependencies. Creates an executable in the current directory (for `main` packages).
+    ```sh
+    go build
+    go build ./cmd/myprogram
+    ```
+
+*   **`go install [packages]`**: Compiles and installs packages. Executables are placed in `$GOBIN` or `$GOPATH/bin`.
+    ```sh
+    go install github.com/user/project/cmd/mytool@latest
+    ```
+
+*   **`go test [packages]`**: Runs tests for the specified packages.
+    ```sh
+    go test ./...
+    go test -v ./mypackage
+    ```
+
+*   **`go get [packages]`**: (Legacy behavior with Go Modules) Adds dependencies to `go.mod` and installs them. For installing tools, prefer `go install tool@version`.
+
+## Go Modules
+
+Go Modules are used for dependency management.
+
+*   **`go mod init <module_path>`**: Initializes a new module in the current directory, creating a `go.mod` file.
+    ```sh
+    go mod init github.com/myuser/myproject
+    ```
+
+*   **`go mod tidy`**: Adds missing and removes unused modules from `go.mod` and `go.sum`.
+    ```sh
+    go mod tidy
+    ```
+
+*   **`go mod download`**: Downloads modules to the local cache.
+    ```sh
+    go mod download
+    ```
 
-- [Go Usage](#go-usage)
-  - [TODO: Create documentation](#todo-create-documentation)
+*   **`go list -m all`**: Lists all modules used in the current project.
 
-## TODO: Create documentation
+## Common Go Tools
+
+*   **`gofmt`**: Formats Go programs.
+    ```sh
+    gofmt -w main.go # Formats and writes back to file
+    ```
+*   **`goimports`**: Updates your Go import lines, adding missing and removing unreferenced ones (superset of `gofmt`). Install with `go install golang.org/x/tools/cmd/goimports@latest`.
+*   **`golint` / `staticcheck` / `golangci-lint`**: Linters for Go code. `golangci-lint` is a popular meta-linter.
+
+## Resources
+
+*   **Official Go Website**: [https://go.dev/](https://go.dev/)
+*   **Go Documentation**: [https://go.dev/doc/](https://go.dev/doc/)
+*   **Effective Go (Best Practices)**: [https://go.dev/doc/effective_go](https://go.dev/doc/effective_go)
+*   **Go Modules Reference**: [https://go.dev/ref/mod](https://go.dev/ref/mod)
+*   **`goenv` GitHub Repository**: [https://github.com/syndbg/goenv](https://github.com/syndbg/goenv)
+*   **Go Playground**: [https://go.dev/play/](https://go.dev/play/)
+
+This document provides a starting point for working with Go. Refer to the official documentation for more in-depth information.

docs/kubernetes-usage.md

···
-# Kubernetes Usage
+# Kubernetes (k8s) Usage
+
+This document provides a guide to interacting with Kubernetes clusters, focusing on `kubectl` (the Kubernetes command-line tool) and common helper utilities.
+
+## Overview
+
+[Kubernetes](https://kubernetes.io/) (commonly stylized as k8s) is an open-source system for automating deployment, scaling, and management of containerized applications.
+
+## `kubectl`: The Kubernetes CLI
+
+`kubectl` is the primary command-line tool for running commands against Kubernetes clusters. It allows you to deploy applications, inspect and manage cluster resources, and view logs.
+
+### Installation
+
+*   **Homebrew (macOS)**:
+    ```sh
+    brew install kubectl
+    ```
+*   **Official Guides**: For other operating systems or specific versions, refer to the [official Kubernetes documentation on installing `kubectl`](https://kubernetes.io/docs/tasks/tools/install-kubectl/).
+
+Installation might be managed by `chezmoi` if `kubectl` is part of your standard toolset.
+
+### Configuration (`kubeconfig`)
+
+`kubectl` uses a configuration file, typically located at `~/.kube/config`, to store cluster access information (server endpoints, user credentials, namespaces, contexts).
+
+*   **Multiple Clusters**: The `kubeconfig` file can define multiple clusters and contexts.
+*   **Context Switching**: Use `kubectl config use-context <context_name>` to switch between defined contexts.
+*   **Environment Variable**: You can specify a different kubeconfig file by setting the `KUBECONFIG` environment variable:
+    ```sh
+    export KUBECONFIG=~/.kube/custom-config:~/.kube/another-config
+    ```
+*   **Security**: Kubeconfig files can contain sensitive credentials. 
+    *   Avoid committing them directly to public repositories.
+    *   Consider using tools that dynamically generate or fetch credentials (e.g., `aws eks update-kubeconfig` for Amazon EKS, `gcloud container clusters get-credentials` for GKE).
+    *   If you must store parts of a kubeconfig managed by `chezmoi`, ensure sensitive fields are templated and sourced from a secrets manager like 1Password (see `docs/1password-usage.md`).
+
+## Common `kubectl` Commands
 
-- [Kubernetes Usage](#kubernetes-usage)
-  - [TODO: Create documentation](#todo-create-documentation)
+*   **Cluster Information & Contexts**:
+    *   `kubectl cluster-info`: Display endpoint information about the master and services.
+    *   `kubectl config get-contexts`: List available contexts.
+    *   `kubectl config current-context`: Display the current context.
+    *   `kubectl config use-context <context_name>`: Switch to a different context.
 
-## TODO: Create documentation
+*   **Viewing Resources**:
+    *   `kubectl get nodes`: List all nodes in the cluster.
+    *   `kubectl get pods [-n <namespace>] [-o wide]`: List pods in a namespace (add `-A` or `--all-namespaces` for all).
+    *   `kubectl get services [-n <namespace>]`: List services.
+    *   `kubectl get deployments [-n <namespace>]`: List deployments.
+    *   `kubectl get namespaces`: List all namespaces.
+    *   `kubectl describe pod <pod_name> [-n <namespace>]`: Show detailed information about a pod.
+    *   `kubectl describe node <node_name>`: Show detailed information about a node.
+
+*   **Interacting with Pods**:
+    *   `kubectl logs <pod_name> [-n <namespace>] [-c <container_name>]`: Print the logs for a container in a pod.
+        *   `kubectl logs -f <pod_name>`: Follow log output.
+    *   `kubectl exec -it <pod_name> [-n <namespace>] [-c <container_name>] -- <command>`: Execute a command in a container.
+        *   Example (get a shell): `kubectl exec -it my-pod -- /bin/sh`
+    *   `kubectl cp <file_path> <pod_name>:<path_in_pod>`: Copy files and directories to and from containers.
+
+*   **Managing Applications**:
+    *   `kubectl apply -f <filename.yaml_or_directory>`: Apply a configuration to a resource by filename or stdin.
+    *   `kubectl delete -f <filename.yaml>`: Delete resources defined in a file.
+    *   `kubectl delete pod <pod_name> [-n <namespace>]`: Delete a pod.
+    *   `kubectl scale deployment <deployment_name> --replicas=<count>`: Scale a deployment.
+
+*   **Port Forwarding**:
+    *   `kubectl port-forward <pod_name_or_service/service_name> <local_port>:<remote_port>`: Forward one or more local ports to a pod or service.
+        *   Example: `kubectl port-forward svc/my-service 8080:80`
+
+## Helper Tools & Ecosystem
+
+*   **[k9s](https://k9scli.io/)**: A terminal-based UI to interact with your Kubernetes clusters. Highly recommended for easier navigation and management.
+    *   Installation (Homebrew): `brew install k9s`
+*   **[kubectx + kubens](https://github.com/ahmetb/kubectx)**: Tools to switch between Kubernetes contexts (`kubectx`) and namespaces (`kubens`) more easily.
+    *   Installation (Homebrew): `brew install kubectx`
+*   **[Helm](https://helm.sh/)**: The package manager for Kubernetes. Helps you manage Kubernetes applications through Helm Charts.
+    *   Installation (Homebrew): `brew install helm`
+*   **[Lens](https://k8slens.dev/)**: A popular open-source Kubernetes IDE for managing clusters.
+*   **[Stern](https://github.com/stern/stern)**: Multi-pod and container log tailing for Kubernetes.
+
+## Resources
+
+*   **Official Kubernetes Documentation**: [https://kubernetes.io/docs/](https://kubernetes.io/docs/)
+*   **`kubectl` Cheat Sheet**: [https://kubernetes.io/docs/reference/kubectl/cheatsheet/](https://kubernetes.io/docs/reference/kubectl/cheatsheet/)
+*   **`kubectl` Command Reference**: [https://kubernetes.io/docs/reference/generated/kubectl/kubectl-commands](https://kubernetes.io/docs/reference/generated/kubectl/kubectl-commands)
+*   **k9s**: [https://k9scli.io/](https://k9scli.io/)
+*   **kubectx + kubens**: [https://github.com/ahmetb/kubectx](https://github.com/ahmetb/kubectx)
+*   **Helm**: [https://helm.sh/docs/](https://helm.sh/docs/)
+
+This document provides a starting point. Kubernetes is a complex system; refer to the official documentation and tool-specific guides for detailed information.

docs/python-usage.md

···
 # Python Usage
 
-- [Python Usage](#python-usage)
-  - [TODO: Create documentation](#todo-create-documentation)
+This document provides a guide to setting up and using Python for development, focusing on version management with `pyenv`, and modern project/dependency management with tools like Poetry and `venv`.
+
+## Overview
+
+[Python](https://www.python.org/) is a versatile, high-level programming language. Effective Python development involves managing Python versions and project dependencies robustly.
+
+## Python Version Management with `pyenv`
+
+It is highly recommended to use [pyenv](https://github.com/pyenv/pyenv) to manage multiple Python versions.
+
+### Installation of `pyenv`
+
+*   **Homebrew (macOS)**:
+    ```sh
+    brew install pyenv
+    ```
+*   **Other Systems/Manual Install**: Follow the [official `pyenv` installation guide](https://github.com/pyenv/pyenv#installation).
 
-## TODO: Create documentation
+### `pyenv` Initialization
+
+Add `pyenv` init to your shell configuration file (e.g., `.zshrc`), managed by `chezmoi`:
+```sh
+# Example for .zshrc
+# if command -v pyenv 1>/dev/null 2>&1; then
+#  eval "$(pyenv init -)"
+#  eval "$(pyenv virtualenv-init -)" # If using pyenv-virtualenv (optional)
+# fi
+```
+
+### Installing Python Versions with `pyenv`
+
+1.  **List available Python versions**: `pyenv install --list`
+2.  **Install a Python version**: `pyenv install <version>` (e.g., `pyenv install 3.10.4`)
+3.  **Set Python version**:
+    *   **Globally**: `pyenv global <version>`
+    *   **Locally (per-project)**: `pyenv local <version>` (creates `.python-version`)
+    *   **Shell specific**: `pyenv shell <version>`
+
+## Project & Dependency Management
+
+Isolating project dependencies is crucial.
+
+### Option 1: Poetry (Recommended for New Projects)
+
+[Poetry](https://python-poetry.org/) is a modern tool for Python dependency management and packaging. It helps you declare, manage, and install dependencies of Python projects, ensuring you have the right stack everywhere.
+
+**Key Benefits of Poetry:**
+*   **Dependency Resolution**: Advanced resolver for compatible dependencies.
+*   **Unified Tool**: Manages project metadata, dependencies, virtual environments, building, and publishing.
+*   **`pyproject.toml`**: Uses the standard `pyproject.toml` file to manage project information.
+*   **Lock File**: Creates a `poetry.lock` file for deterministic builds.
+*   **Virtual Environment Management**: Automatically creates and manages virtual environments for your projects.
+
+**Installation of Poetry:**
+
+Refer to the [official Poetry installation guide](https://python-poetry.org/docs/#installation). A common method is using their custom installer or `pipx`:
+```sh
+# Using pipx (recommended for CLI tools)
+brew install pipx # If not already installed
+pipx ensurepath
+pipx install poetry
+
+# Or using the official installer
+# curl -sSL https://install.python-poetry.org | python3 -
+```
+
+**Common Poetry Commands:**
+
+*   **`poetry new <project_name>`**: Creates a new Python project with a standard structure.
+*   **`poetry init`**: Interactively creates a `pyproject.toml` in an existing project.
+*   **`poetry install`**: Installs dependencies defined in `pyproject.toml` (and `poetry.lock`). If a virtual environment doesn't exist, Poetry creates one.
+*   **`poetry add <package_name>`**: Adds a new dependency to `pyproject.toml` and installs it.
+    *   `poetry add requests`
+    *   `poetry add pytest --group dev` (for development dependencies)
+*   **`poetry remove <package_name>`**: Removes a dependency.
+*   **`poetry show`**: Lists all installed packages.
+*   **`poetry update`**: Updates dependencies to their latest allowed versions according to `pyproject.toml` and updates `poetry.lock`.
+*   **`poetry run <command>`**: Runs a command within the project's virtual environment.
+    *   `poetry run python my_script.py`
+    *   `poetry run pytest`
+*   **`poetry shell`**: Activates the project's virtual environment in your current shell.
+*   **`poetry build`**: Builds your project into a source archive (sdist) and a wheel (bdist_wheel).
+*   **`poetry publish`**: Publishes your package to a repository like PyPI.
+
+Poetry can be configured to use Python versions installed by `pyenv`:
+```sh
+poetry env use $(pyenv which python) # Or specify a path/version
+```
+
+### Option 2: `venv` and `pip` (Traditional)
+
+Python 3.3+ includes the `venv` module for creating virtual environments.
+
+1.  **Create a virtual environment**: `python -m venv .venv`
+2.  **Activate**:
+    *   Unix/macOS: `source .venv/bin/activate`
+    *   Windows: `.\.venv\Scripts\activate.bat` or `.\.venv\Scripts\Activate.ps1`
+3.  **Deactivate**: `deactivate`
+
+**Package Management with `pip` (within an active `venv`)**:
+
+*   Install: `pip install <package_name>`, `pip install -r requirements.txt`
+*   List: `pip list`
+*   Generate `requirements.txt`: `pip freeze > requirements.txt`
+
+### `pyenv-virtualenv` (Plugin for `pyenv`)
+
+The [pyenv-virtualenv](https://github.com/pyenv/pyenv-virtualenv) plugin integrates `venv` management with `pyenv` if you prefer this workflow over Poetry's built-in virtual environment handling.
+
+## Common Python Development Tools
+
+Install these within your project's virtual environment (via `poetry add --group dev tool_name` or `pip install tool_name`) or globally via `pipx`.
+
+*   **Linters**: `flake8`, `pylint`
+*   **Formatters**: `black`, `autopep8`, `isort`
+*   **Test Runners**: `pytest`, `unittest` (built-in)
+*   **`pipx`**: For installing and running Python CLI applications in isolated environments (`brew install pipx`).
+    *   Example: `pipx install black`
+
+## Resources
+
+*   **Official Python Documentation**: [https://docs.python.org/3/](https://docs.python.org/3/)
+*   **`pyenv` GitHub Repository**: [https://github.com/pyenv/pyenv](https://github.com/pyenv/pyenv)
+*   **Poetry Documentation**: [https://python-poetry.org/docs/](https://python-poetry.org/docs/)
+*   **Python `venv` Documentation**: [https://docs.python.org/3/library/venv.html](https://docs.python.org/3/library/venv.html)
+*   **`pip` Documentation**: [https://pip.pypa.io/](https://pip.pypa.io/)
+*   **Python Packaging User Guide**: [https://packaging.python.org/](https://packaging.python.org/)
+*   **`pipx`**: [https://pipx.pypa.io/](https://pipx.pypa.io/)
+
+This document covers essentials for a modern Python development setup. Choose the tools that best fit your project needs.

docs/system-usage.md

···
-# System Usage
+# System Usage & OS-Specific Notes
+
+This document outlines system-level configurations, OS-specific notes, and common utilities relevant to this dotfiles setup across different operating systems.
+
+## Overview
+
+These dotfiles aim to provide a consistent experience across macOS, Linux (primarily Ubuntu), and Windows (via WSL). `chezmoi` plays a crucial role in managing OS-specific configurations by using templates and conditional logic based on the operating system.
 
-- [System Usage](#system-usage)
-  - [TODO: Create documentation](#todo-create-documentation)
+## General Principles
+
+*   **`chezmoi` for OS Detection**: `chezmoi` templates often use variables like `.chezmoi.os` (e.g., "darwin", "linux", "windows") to apply OS-specific settings or install different packages.
+*   **Homebrew/Linuxbrew**: Homebrew (on macOS) and Linuxbrew (on Linux) are heavily utilized for package management. See `Brewfile` or `chezmoi` scripts for lists of managed packages.
+*   **Common Utilities**: Many command-line utilities are installed for enhanced productivity. Some common examples that might be included (and configured by these dotfiles) are:
+    *   `exa` or `lsd` (modern `ls` replacements)
+    *   `bat` (a `cat` clone with syntax highlighting)
+    *   `fd` (a simple, fast, and user-friendly alternative to `find`)
+    *   `ripgrep` (`rg`) (a line-oriented search tool that recursively searches your current directory for a regex pattern)
+    *   `fzf` (a command-line fuzzy finder)
+    *   `zoxide` (a smarter `cd` command)
+    *   `htop` or `btop` (interactive process viewers)
 
-## TODO: Create documentation
+## macOS Specifics
 
-- macOS
-- Ubutnu
-- Windows (Ubuntu WSL)
-- GitHub Codespaces
+*   **Package Manager**: [Homebrew](https://brew.sh/) is the primary package manager.
+*   **Shell**: Zsh, configured via `oh-my-zsh` and `oh-my-posh` (see `docs/terminal-usage.md`).
+*   **Finder Tweaks**: Your `chezmoi` setup might include scripts to apply common Finder settings (e.g., show hidden files, show path bar).
+    *   Example commands (often found in `run_once_` scripts):
+        ```sh
+        # Show hidden files
+        # defaults write com.apple.finder AppleShowAllFiles -bool true
+        # Show path bar
+        # defaults write com.apple.finder ShowPathbar -bool true
+        # Restart Finder to apply changes
+        # killall Finder
+        ```
+*   **Keyboard Shortcuts/Remapping**: Tools like Karabiner-Elements might be used for advanced keyboard customization (if included in your setup).
+*   **Spotlight**: Useful for launching applications and finding files (`Cmd+Space`).
+*   **System Updates**: `sudo softwareupdate -i -a`
+
+## Linux (Ubuntu Focus)
+
+*   **Package Manager**: `apt` is the system package manager. [Linuxbrew](https://docs.brew.sh/Homebrew-on-Linux) might also be used for user-space packages.
+*   **Shell**: Zsh, configured via `oh-my-zsh` and `oh-my-posh` (see `docs/terminal-usage.md`).
+*   **System Updates**:
+    ```sh
+    sudo apt update && sudo apt upgrade -y
+    sudo apt autoremove -y # To remove unused packages
+    ```
+*   **Firewall**: `ufw` (Uncomplicated Firewall) is commonly used.
+    ```sh
+    # sudo ufw status
+    # sudo ufw enable
+    # sudo ufw allow ssh
+    ```
+
+## Windows (via WSL - Windows Subsystem for Linux)
+
+*   **WSL Version**: It's recommended to use WSL 2 for better performance and system call compatibility.
+*   **Distribution**: Typically Ubuntu is used within WSL, so many Linux notes apply.
+*   **Accessing Windows Files**: Windows drives are typically mounted under `/mnt/` (e.g., `/mnt/c`).
+*   **Windows Terminal**: Recommended for a better WSL experience.
+*   **Interoperability**: You can run Windows executables from WSL and Linux executables from Windows (PowerShell/CMD).
+*   **Docker Desktop with WSL Backend**: Often used for Docker development on Windows.
+
+## GitHub Codespaces
+
+GitHub Codespaces typically run a Linux environment (often Ubuntu-based).
+*   **Dotfiles Integration**: Your dotfiles can be automatically installed into Codespaces if configured in your GitHub settings.
+*   **`devcontainer.json`**: Projects can define specific configurations for Codespaces using a `devcontainer.json` file, which can include features, extensions, and post-create commands.
+*   The environment is largely Linux-based, so Linux configurations from your dotfiles will apply.
+
+## Resources
+
+*   **macOS User Guide**: [https://support.apple.com/guide/mac-help/welcome/mac](https://support.apple.com/guide/mac-help/welcome/mac)
+*   **Ubuntu Server Guide / Desktop Guide**: [https://ubuntu.com/server/docs](https://ubuntu.com/server/docs), [https://ubuntu.com/desktop/docs](https://ubuntu.com/desktop/docs)
+*   **Windows Subsystem for Linux (WSL) Documentation**: [https://docs.microsoft.com/en-us/windows/wsl/](https://docs.microsoft.com/en-us/windows/wsl/)
+*   **Chezmoi Documentation (OS specific logic)**: [https://www.chezmoi.io/user-guide/templating/#variables](https://www.chezmoi.io/user-guide/templating/#variables)
+*   **Homebrew**: [https://brew.sh/](https://brew.sh/)
+*   **Linuxbrew**: [https://docs.brew.sh/Homebrew-on-Linux](https://docs.brew.sh/Homebrew-on-Linux)
+
+This document provides a high-level overview. Specific configurations and scripts are managed by `chezmoi` and can be found within the repository.

docs/terminal-usage.md

···
-# Terminal Usage
+# Terminal Setup and Usage
 
-- [Terminal Usage](#terminal-usage)
-  - [TODO: Create documentation](#todo-create-documentation)
+This document describes the terminal environment setup, including the shell, prompt, terminal emulators, and related tools used in this dotfiles configuration.
 
-## TODO: Create documentation
+## Overview
 
-- iTerm
+A customized and efficient terminal setup is crucial for productivity. This setup primarily revolves around Zsh, Oh My Zsh, Powerlevel10k/Oh My Posh for the prompt, and iTerm2 on macOS.
 
-Back up and restore iTerm configuration settings.
+## Terminal Emulator
 
-```shell
-defaults export com.googlecode.iterm2 assets/iterm2/com.googlecode.iterm2.plist
-plutil -convert xml1 -o assets/iterm2/com.googlecode.iterm2.xml assets/iterm2/com.googlecode.iterm2.plist
-cp assets/iterm2/com.googlecode.iterm2.xml assets/iterm2/settings.xml
-# Format `assets/iterm2/settings.xml` in vscode
-defaults import com.googlecode.iterm2 assets/iterm2/settings.xml
-```
+### iTerm2 (macOS)
 
-- Oh-My-Zsh
-- Powerlevel10k
+[iTerm2](https://iterm2.com/) is a popular replacement for Apple's Terminal on macOS. It offers a wide range of features, including split panes, profiles, triggers, and extensive customization options.
+
+**Configuration Management with `chezmoi`**:
+
+iTerm2 settings are stored in a `.plist` file, typically `~/Library/Preferences/com.googlecode.iterm2.plist`.
+Your `chezmoi` setup might manage this file or a human-readable version (e.g., XML) of it.
+
+The commands previously noted for backup/restore can be adapted for `chezmoi`:
+1.  **Exporting current iTerm2 settings to XML (for `chezmoi` source directory)**:
+    ```sh
+    # Ensure the target directory in your chezmoi source exists, e.g., private_dot_config/iterm2/
+    TARGET_XML="$HOME/.local/share/chezmoi/private_dot_config/iterm2/com.googlecode.iterm2.plist.xml" # Adjust path as needed
+    TEMP_PLIST=$(mktemp)
+    defaults export com.googlecode.iterm2 "$TEMP_PLIST"
+    plutil -convert xml1 -o "$TARGET_XML" "$TEMP_PLIST"
+    rm "$TEMP_PLIST"
+    echo "iTerm2 config exported to $TARGET_XML. Run 'chezmoi add private_dot_config/iterm2/com.googlecode.iterm2.plist.xml' if new."
+    ```
+    Then, format `$TARGET_XML` if desired and `chezmoi add` / `chezmoi apply`.
+
+2.  **Importing settings from `chezmoi` (managed by `chezmoi apply`)**:
+    If `chezmoi` manages an XML version, it might use a `run_script_` or template to convert it back to binary plist and import using `defaults import com.googlecode.iterm2 /path/to/your/plist/from/chezmoi` or directly manage the binary plist if `chezmoi`'s templating/symlinking handles it.
+
+*   **Official Website**: [https://iterm2.com/](https://iterm2.com/)
+
+### Other Terminal Emulators (Windows Terminal, Alacritty, etc.)
+For Linux and Windows (WSL), other terminal emulators like Windows Terminal, Alacritty, Kitty, etc., can be used. Configuration for these would be managed by `chezmoi` as well, typically by templating their respective configuration files.
+
+## Shell: Zsh (Z Shell)
+
+[Zsh](https://www.zsh.org/) is a powerful shell with numerous features, including improved tab completion, command history, and customization options.
+
+## Zsh Framework: Oh My Zsh
+
+[Oh My Zsh](https://ohmyz.sh/) is an open-source, community-driven framework for managing your Zsh configuration. It comes bundled with thousands of helpful functions, helpers, plugins, and themes.
+
+*   **Installation**: Typically managed by `chezmoi` as part of the initial setup.
+*   **Plugins**: Enhance functionality (e.g., `git`, `zsh-autosuggestions`, `zsh-syntax-highlighting`). Your `.zshrc` (managed by `chezmoi`) will list enabled plugins.
+*   **Themes**: Oh My Zsh offers many themes, but this setup often uses a more specialized prompt theme engine like Powerlevel10k or Oh My Posh.
+*   **Official Website**: [https://ohmyz.sh/](https://ohmyz.sh/)
+*   **GitHub**: [https://github.com/ohmyzsh/ohmyzsh](https://github.com/ohmyzsh/ohmyzsh)
+
+## Shell Prompt
+
+A highly customized and informative prompt is key for an efficient workflow.
+
+### Powerlevel10k (p10k)
+
+[Powerlevel10k](https://github.com/romkatv/powerlevel10k) is a theme for Zsh. It emphasizes speed, flexibility, and an out-of-the-box awesome experience. It's known for its configuration wizard that helps you tailor the prompt to your liking.
+
+*   **Installation**: Often installed as a theme for Oh My Zsh.
+*   **Configuration**: Run `p10k configure` to go through the setup wizard. The resulting configuration (`~/.p10k.zsh`) is typically managed by `chezmoi`.
+*   **Requires**: A Nerd Font or a font patched with Powerline symbols for icons to display correctly.
+*   **GitHub**: [https://github.com/romkatv/powerlevel10k](https://github.com/romkatv/powerlevel10k)
+
+### Oh My Posh
+
+[Oh My Posh](https://ohmyposh.dev/) is a custom prompt engine for any shell that has the ability to adjust the prompt string with a function or variable. It allows for finely tuned, themeable prompts.
+
+*   **Installation**: Typically installed via Homebrew or other package managers.
+*   **Configuration**: Defined by a JSON, TOML, or YAML theme file (e.g., `~/.config/omp.json` or similar, path defined in `.zshrc`). This theme file is managed by `chezmoi`.
+*   **Requires**: A Nerd Font for icons.
+*   **Official Website**: [https://ohmyposh.dev/](https://ohmyposh.dev/)
+
+*(Note: Your setup might use Powerlevel10k directly or use Oh My Posh with a p10k-like theme or another custom theme. Clarify which is primary if necessary in your `.zshrc` or this doc.)*
+
+## Terminal Multiplexer: `tmux` (If Used)
+
+If [tmux](https://github.com/tmux/tmux/wiki) is part of your setup for managing multiple terminal sessions:
+*   **Configuration**: `~/.tmux.conf` (managed by `chezmoi`).
+*   **Plugin Manager**: [TPM (Tmux Plugin Manager)](https://github.com/tmux-plugins/tpm) might be used.
+*   **Keybindings**: Custom keybindings would be defined in `.tmux.conf`.
+
+## Key Fonts (Nerd Fonts)
+
+For icons and special symbols in prompts (Powerlevel10k, Oh My Posh) and other terminal applications (e.g., `lsd`, `bat`), [Nerd Fonts](https://www.nerdfonts.com/) are commonly used. These are popular programming fonts patched with a high number of glyphs (icons).
+
+*   **Installation**: Download from Nerd Fonts website or install via Homebrew Cask (e.g., `brew tap homebrew/cask-fonts && brew install --cask font-hack-nerd-font`).
+*   Ensure your terminal emulator (iTerm2, etc.) is configured to use a Nerd Font.
+
+## Resources
+
+*   **iTerm2**: [https://iterm2.com/](https://iterm2.com/)
+*   **Zsh**: [https://www.zsh.org/](https://www.zsh.org/)
+*   **Oh My Zsh**: [https://ohmyz.sh/](https://ohmyz.sh/)
+*   **Powerlevel10k**: [https://github.com/romkatv/powerlevel10k](https://github.com/romkatv/powerlevel10k)
+*   **Oh My Posh**: [https://ohmyposh.dev/](https://ohmyposh.dev/)
+*   **Nerd Fonts**: [https://www.nerdfonts.com/](https://www.nerdfonts.com/)
+*   **tmux**: [https://github.com/tmux/tmux/wiki](https://github.com/tmux/tmux/wiki)
+
+This document outlines the core components of the terminal setup. Specific configurations are managed by `chezmoi`.

docs/terraform-usage.md

···
 # Terraform Usage
 
-- [Terraform Usage](#terraform-usage)
-  - [TODO: Create documentation](#todo-create-documentation)
+This document provides a guide to using Terraform for managing infrastructure as code, including version management with `tfenv`.
+
+## Overview
+
+[Terraform](https://www.terraform.io/) is an open-source infrastructure as code (IaC) software tool that enables you to safely and predictably create, change, and improve infrastructure. It codifies APIs into declarative configuration files.
+
+[tfenv](https://github.com/tfutils/tfenv) is a Terraform version manager, allowing you to easily switch between different versions of Terraform on a per-project basis.
+
+## Installation
 
-## TODO: Create documentation
+### `tfenv` (Terraform Version Manager)
 
-- Package tfswitch
+It's recommended to install `tfenv` first to manage your Terraform versions.
 
-```shell
-tfswitch -l
-tfswitch 1.0.0
-terraform --version
-which terraform
+**Installation (macOS with Homebrew):**
+```sh
+brew install tfenv
 ```
+For other installation methods (e.g., Git clone), refer to the [tfenv installation guide](https://github.com/tfutils/tfenv#installation).
+
+**Post-installation:**
+Ensure `tfenv` is added to your shell's PATH. If installed via Homebrew, this is usually handled automatically. Otherwise, you might need to add `$(brew --prefix tfenv)/bin` (or the equivalent for your installation method) to your PATH.
+
+### Terraform (via `tfenv`)
+
+Once `tfenv` is installed, you can install specific Terraform versions:
+
+1.  **List available Terraform versions**:
+    ```sh
+    tfenv list-remote
+    ```
+
+2.  **Install a specific version**:
+    ```sh
+    tfenv install <version>
+    # Example: tfenv install 1.0.0
+    ```
+    To install the latest stable version:
+    ```sh
+    tfenv install latest
+    ```
+
+3.  **Select a Terraform version to use**:
+    *   **Globally**:
+        ```sh
+        tfenv use <version>
+        # Example: tfenv use 1.0.0
+        ```
+    *   **Per project (recommended)**: Create a `.terraform-version` file in your project's root directory containing the desired version number:
+        ```
+        # .terraform-version
+        1.0.0
+        ```
+        `tfenv` will automatically pick up this version when you `cd` into the directory.
+
+4.  **Verify installation**:
+    ```sh
+    terraform --version
+    which terraform # Should point to a tfenv shim
+    ```
+
+## Basic Terraform Workflow
+
+Terraform commands are typically run within a directory containing your `.tf` configuration files.
+
+1.  **`terraform init`**: Initializes a working directory containing Terraform configuration files. This is the first command that should be run after writing a new Terraform configuration or cloning an existing one.
+    ```sh
+    terraform init
+    ```
+    This command also initializes backend configuration (for state storage) and downloads provider plugins.
+
+2.  **`terraform plan`**: Creates an execution plan. Terraform performs a refresh, unless explicitly disabled, and then determines what actions are necessary to achieve the desired state specified in the configuration files.
+    ```sh
+    terraform plan
+    # Save the plan to a file:
+    # terraform plan -out=tfplan
+    ```
+    This is a good way to check whether the proposed changes match your expectations before applying them.
+
+3.  **`terraform apply`**: Applies the changes required to reach the desired state of the configuration, or the pre-determined changes if a plan file is provided.
+    ```sh
+    terraform apply
+    # Apply a saved plan (prompts for confirmation):
+    # terraform apply tfplan
+    # Auto-approve (use with caution):
+    # terraform apply -auto-approve
+    # Or apply a saved plan without prompting:
+    # terraform apply -auto-approve tfplan
+    ```
+
+4.  **`terraform destroy`**: Destroys all remote objects managed by a particular Terraform configuration.
+    ```sh
+    terraform destroy
+    ```
+    Use with extreme caution, as this will remove your managed infrastructure.
+
+## Common Terraform Commands
+
+*   **`terraform fmt`**: Rewrites Terraform configuration files to a canonical format and style.
+    ```sh
+    terraform fmt
+    # Check for formatting issues: terraform fmt -check
+    ```
+*   **`terraform validate`**: Validates the syntax and arguments of configuration files.
+    ```sh
+    terraform validate
+    ```
+*   **`terraform output`**: Reads an output variable from a Terraform state file.
+    ```sh
+    terraform output <output_variable_name>
+    ```
+*   **`terraform state list`**: Lists resources within a Terraform state file.
+    ```sh
+    terraform state list
+    ```
+*   **`terraform workspace list/select/new/delete`**: Manages Terraform workspaces for different environments (e.g., dev, staging, prod).
+
+## Resources
+
+*   **Official Terraform Documentation**: [https://developer.hashicorp.com/terraform/docs](https://developer.hashicorp.com/terraform/docs)
+*   **Terraform CLI Commands**: [https://developer.hashicorp.com/terraform/cli/commands](https://developer.hashicorp.com/terraform/cli/commands)
+*   **`tfenv` GitHub Repository**: [https://github.com/tfutils/tfenv](https://github.com/tfutils/tfenv)
+*   **Terraform Registry (Providers & Modules)**: [https://registry.terraform.io/](https://registry.terraform.io/)
+
+This document provides fundamental guidance. Terraform is a comprehensive tool; always refer to the official documentation for detailed information and best practices.

docs/user-apps-usage.md

···
-# User Apps Usage
+# User Applications Usage
+
+This document lists common user (GUI) applications that are part of this development and productivity setup. It also notes if and how their configurations might be managed by `chezmoi`.
+
+## Overview
+
+While `chezmoi` excels at managing command-line tool configurations (dotfiles), it can also help manage settings for some GUI applications, typically by symlinking or templating their preference files (e.g., `.plist` files on macOS, JSON/XML configs).
+
+Many applications are installed via Homebrew Cask on macOS. Check your `Brewfile` (if used with `chezmoi`) or `chezmoi` installation scripts for a list of managed applications.
+
+## Common Application Categories & Examples
+
+Below are categories and examples of applications that might be part of your setup. Add your specific applications to these lists.
+
+### Web Browsers
+
+*   **[Google Chrome](https://www.google.com/chrome/)**
+    *   **Installation**: Homebrew Cask (`brew install --cask google-chrome`) or manual download.
+    *   **Configuration**: User profile settings are complex to manage directly with dotfiles. Consider using Chrome's built-in sync feature.
+*   **[Mozilla Firefox](https://www.mozilla.org/firefox/)**
+    *   **Installation**: Homebrew Cask (`brew install --cask firefox`) or manual download.
+    *   **Configuration**: Profile-based. Some `user.js` customizations can be managed.
+*   **[Safari](https://www.apple.com/safari/) (macOS)**
+    *   **Installation**: Comes with macOS.
+    *   **Configuration**: Some `.plist` files in `~/Library/Preferences/` or `~/Library/Containers/com.apple.Safari/Data/Library/Preferences/` might be manageable, but can be complex.
+
+### Productivity Tools
+
+*   **[Rectangle](https://rectangleapp.com/) (macOS Window Manager)**
+    *   **Installation**: Homebrew Cask (`brew install --cask rectangle`) or manual download.
+    *   **Configuration**: Preferences (`~/Library/Preferences/com.knollsoft.Rectangle.plist`) can often be managed by `chezmoi`.
+*   **[Alfred](https://www.alfredapp.com/) (macOS Launcher & Productivity)**
+    *   **Installation**: Homebrew Cask (`brew install --cask alfred`) or manual download.
+    *   **Configuration**: Alfred preferences can be synced to a folder (e.g., Dropbox, iCloud Drive), and `chezmoi` could potentially manage a symlink to this sync folder or specific non-sensitive parts of its config if exported.
+*   **[Obsidian](https://obsidian.md/) (Knowledge Base/Notes)**
+    *   **Installation**: Homebrew Cask (`brew install --cask obsidian`) or manual download.
+    *   **Configuration**: Vaults are user-managed. Some global configuration files might be linkable.
+*   **Password Manager (GUI)**
+    *   **1Password**: (Covered in `docs/1password-usage.md` for CLI, GUI is complementary)
+        *   **Installation**: Download from [1Password website](https://1password.com/downloads/).
+
+### Development Tools (GUI)
+
+*   **[Visual Studio Code](https://code.visualstudio.com/)**: (Covered in detail in `docs/vscode-usage.md`)
+*   **[Docker Desktop](https://www.docker.com/products/docker-desktop/)**: (Covered in `docs/docker-usage.md`)
+*   **Database GUI Clients** (e.g., TablePlus, DBeaver, pgAdmin)
+    *   **Example: [TablePlus](https://tableplus.com/)**
+        *   **Installation**: Homebrew Cask (`brew install --cask tableplus`) or manual download.
+        *   **Configuration**: Connection details are typically managed within the app; general preferences might be in a `.plist` file.
+*   **API Clients** (e.g., Postman, Insomnia)
+    *   **Example: [Postman](https://www.postman.com/)**
+        *   **Installation**: Homebrew Cask (`brew install --cask postman`) or manual download.
+        *   **Configuration**: Typically uses cloud sync for collections and environments.
+
+### Communication
+
+*   **[Slack](https://slack.com/)**
+    *   **Installation**: Homebrew Cask (`brew install --cask slack`) or manual download.
+*   **[Zoom](https://zoom.us/)**
+    *   **Installation**: Homebrew Cask (`brew install --cask zoom`) or manual download.
+
+### Other Utilities
+
+*   **[Spotify](https://www.spotify.com/)**
+    *   **Installation**: Homebrew Cask (`brew install --cask spotify`) or manual download.
+*   **[VLC Media Player](https://www.videolan.org/vlc/)**
+    *   **Installation**: Homebrew Cask (`brew install --cask vlc`) or manual download.
+
+## Managing Application Settings with `chezmoi`
+
+If an application stores its settings in a known file path (e.g., a `.plist` file in `~/Library/Preferences/` on macOS, or a JSON/INI/XML file in `~/.config/AppName/` on Linux), `chezmoi` can manage it:
+
+1.  **Identify the configuration file**.
+2.  **Copy it to your `chezmoi` source directory** (e.g., as `private_Library/Preferences/com.example.app.plist` for macOS, or `dot_config/AppName/settings.json`).
+3.  **Add it to `chezmoi`**: `chezmoi add ~/Library/Preferences/com.example.app.plist` (using the original path).
+4.  `chezmoi` will then create a symlink from the target path to your source directory version, or apply it as a template.
+
+**Caution**: Some applications do not like their preference files being symlinked or modified externally while they are running. Test thoroughly.
 
-- [User Apps Usage](#user-apps-usage)
-  - [TODO: Create documentation](#todo-create-documentation)
+## Resources
 
-## TODO: Create documentation
+*   **Homebrew Casks**: [https://formulae.brew.sh/cask/](https://formulae.brew.sh/cask/) (Find package names for Homebrew Cask installations)
+*   **`chezmoi` Documentation**: [https://www.chezmoi.io/](https://www.chezmoi.io/)
+
+This document is a template. Please populate it with the specific applications you use and how you manage their installation and configuration.

docs/vscode-usage.md

···
 # Visual Studio Code Usage
 
-- [Visual Studio Code Usage](#visual-studio-code-usage)
-  - [TODO: Create documentation](#todo-create-documentation)
+This document provides an overview of using Visual Studio Code (VS Code), including setup, key features, and customization relevant to this dotfiles environment.
 
-## TODO: Create documentation
+## Overview
 
-- Configuration
-  - Extensions
-  - Settings
-  - Key bindings
-- GitHub Codespaces
+[Visual Studio Code](https://code.visualstudio.com/) is a lightweight but powerful source code editor that runs on your desktop and is available for Windows, macOS, and Linux. It comes with built-in support for JavaScript, TypeScript, and Node.js and has a rich ecosystem of extensions for other languages and runtimes (such as C++, C#, Java, Python, PHP, Go) and tools (like Docker, Git, and various linters).
+
+## Installation
+
+*   **Download**: Download VS Code from the [official website](https://code.visualstudio.com/download).
+*   **Package Managers**:
+    *   **macOS (Homebrew)**: `brew install --cask visual-studio-code`
+    *   **Linux**: Refer to [VS Code Linux documentation](https://code.visualstudio.com/docs/setup/linux) for instructions for your distribution.
+
+Installation might be managed by `chezmoi` if VS Code is part of your standard toolset defined in your dotfiles.
+
+Launch VS Code and open a terminal within it (`View > Terminal` or ``Ctrl+` ``) to use the `code` command-line interface for opening files and folders.
+
+## Key Features & Customization
+
+### Command Palette
+Access all available commands based on your current context by pressing `Ctrl+Shift+P` (Windows/Linux) or `Cmd+Shift+P` (macOS).
+
+### Extensions
+VS Code extensions let you add languages, debuggers, and tools to your installation to support your development workflow.
+*   **Browse and Install**: Access the Extensions view by clicking on the Extensions icon in the Activity Bar on the side of VS Code or `Ctrl+Shift+X` / `Cmd+Shift+X`.
+*   **Recommended Extensions**: VS Code often suggests extensions based on the files you open. You can also find popular extensions for your languages and frameworks in the Marketplace.
+*   **Managing Extensions**: You can list your installed extensions from the command line:
+    ```sh
+    code --list-extensions
+    ```
+    To install an extension from the command line:
+    ```sh
+    code --install-extension <extension-id>
+    ```
+    Your `chezmoi` setup might manage a list of extensions to be installed automatically.
+
+### Settings
+Customize VS Code to your liking through its settings.
+*   **UI**: Open settings via `File > Preferences > Settings` (`Code > Preferences > Settings` on macOS) or `Ctrl+,` / `Cmd+,`.
+*   **JSON**: For more advanced configuration and to manage settings as code, you can edit the `settings.json` file directly. Access it via the Command Palette (`Ctrl+Shift+P` / `Cmd+Shift+P`) by typing "Preferences: Open User Settings (JSON)".
+*   **Workspace Settings**: You can also define settings specific to a project/workspace by creating a `.vscode/settings.json` file in your project root.
+*   Your `chezmoi` setup likely manages your global `settings.json` file.
+
+### Settings Sync
+VS Code has built-in Settings Sync, which allows you to share your VS Code configurations—such as settings, keybindings, and installed extensions—across your different machines using a GitHub or Microsoft account.
+*   **Enable/Disable**: Turn on Settings Sync from the Manage gear icon at the bottom of the Activity Bar, then "Turn on Settings Sync...".
+
+### Keybindings
+Customize keyboard shortcuts in VS Code.
+*   **UI**: `File > Preferences > Keyboard Shortcuts` (`Code > Preferences > Keyboard Shortcuts` on macOS) or `Ctrl+K Ctrl+S` / `Cmd+K Cmd+S`.
+*   **JSON**: For advanced customization, edit `keybindings.json`. Access it via the Command Palette with "Preferences: Open Keyboard Shortcuts (JSON)".
+*   Your `chezmoi` setup might manage your `keybindings.json`.
+
+### Integrated Terminal
+VS Code has an integrated terminal (`View > Terminal` or `` Ctrl+` ``) so you can run shell commands directly within the editor.
+
+## GitHub Codespaces
+
+[GitHub Codespaces](https://github.com/features/codespaces) provides cloud-powered development environments. You can use VS Code (desktop or web) to connect to a Codespace, giving you a fully configured development environment in the cloud, often based on a `devcontainer.json` configuration in your repository (see `docs/docker-usage.md` for more on Dev Containers).
+
+### Benefits:
+*   **Pre-configured environments**: Start coding immediately with environments tailored for your project.
+*   **Access from anywhere**: Develop from any machine with a browser or VS Code.
+*   **Consistent setup**: Ensures consistency across team members.
+
+## Resources
+
+*   **Official VS Code Documentation**: [https://code.visualstudio.com/docs](https://code.visualstudio.com/docs)
+*   **Introductory Videos**: [https://code.visualstudio.com/docs/getstarted/introvideos](https://code.visualstudio.com/docs/getstarted/introvideos)
+*   **VS Code Extension Marketplace**: [https://marketplace.visualstudio.com/vscode](https://marketplace.visualstudio.com/vscode)
+*   **Settings Sync Guide**: [https://code.visualstudio.com/docs/editor/settings-sync](https://code.visualstudio.com/docs/editor/settings-sync)
+*   **GitHub Codespaces Documentation**: [https://docs.github.com/en/codespaces](https://docs.github.com/en/codespaces)
+
+This document covers the basics. VS Code is highly extensible and configurable; explore the official documentation to tailor it to your workflow.