feat(setup/local): add install-cli-tools, setup-shell, setup-ssh, setup-gpg, configure-git, configure-kubectl, configure-terraform, and verify-workstation with docs

Author: rudraditya21

docs/scripts/setup/local/configure-git.md

@@ -0,0 +1,70 @@
+# configure-git.sh
+
+## Purpose
+Apply consistent global Git configuration for identity, workflow defaults, and optional signing.
+
+## Location
+`setup/local/configure-git.sh`
+
+## Preconditions
+- Required tools: `bash`, `git`
+- Required permissions: write access to global git config
+- Required environment variables: none
+
+## Arguments
+| Flag | Required | Default | Description |
+|------|----------|---------|-------------|
+| `--name VALUE` | No | unchanged | Set `user.name` |
+| `--email VALUE` | No | unchanged | Set `user.email` |
+| `--default-branch NAME` | No | `main` | Set `init.defaultBranch` |
+| `--editor VALUE` | No | unchanged | Set `core.editor` |
+| `--credential-helper V` | No | platform auto | Set `credential.helper` |
+| `--rebase-pull BOOL` | No | `false` | Set `pull.rebase` |
+| `--signing-key KEYID` | No | unchanged | Set `user.signingkey` |
+| `--gpg-sign BOOL` | No | auto/unchanged | Set `commit.gpgsign` |
+| `--dry-run` | No | `false` | Print planned changes |
+
+## Scenarios
+- Happy path: apply baseline global Git settings.
+- Common operational path: bootstrap new workstation developer identity + defaults.
+- Failure path: git unavailable or invalid boolean values.
+- Recovery/rollback path: rerun with corrected values or reset keys via `git config --global --unset`.
+
+## Usage
+```bash
+setup/local/configure-git.sh --name "Jane Doe" --email jane@example.com
+setup/local/configure-git.sh --rebase-pull true --editor "code --wait"
+setup/local/configure-git.sh --signing-key ABCD1234 --gpg-sign true --dry-run
+```
+
+## Behavior
+- Main execution flow: validate options, set global git keys, optionally configure signing.
+- Idempotency notes: idempotent; sets target values repeatedly.
+- Side effects: modifies `~/.gitconfig`.
+
+## Output
+- Standard output format: timestamped status logs and dry-run command output.
+- Exit codes:
+  - `0` success
+  - `2` invalid arguments
+
+## Failure Modes
+- Common errors and likely causes:
+  - git not installed
+  - invalid boolean input
+- Recovery and rollback steps:
+  - install git
+  - pass boolean as true/false
+
+## Security Notes
+- Secret handling: no secret storage; consider secure credential helper backend.
+- Least-privilege requirements: user-level git config operations.
+- Audit/logging expectations: safe for bootstrap logs.
+
+## Testing
+- Unit tests:
+  - boolean normalization and option parsing
+- Integration tests:
+  - dry-run vs apply behavior on test HOME
+- Manual verification:
+  - `git config --global --list` inspection

docs/scripts/setup/local/configure-kubectl.md

@@ -0,0 +1,68 @@
+# configure-kubectl.sh
+
+## Purpose
+Set local kubectl defaults (kubeconfig path, context, namespace) for safer and repeatable cluster operations.
+
+## Location
+`setup/local/configure-kubectl.sh`
+
+## Preconditions
+- Required tools: `bash`, `kubectl`
+- Required permissions: write access to kubeconfig file/path
+- Required environment variables: none
+
+## Arguments
+| Flag | Required | Default | Description |
+|------|----------|---------|-------------|
+| `--kubeconfig PATH` | No | `~/.kube/config` | Target kubeconfig file |
+| `--context NAME` | No | unchanged | Context to select |
+| `--namespace NAME` | No | unchanged | Namespace to set |
+| `--dry-run` | No | `false` | Print commands without execution |
+
+## Scenarios
+- Happy path: context and namespace are configured successfully.
+- Common operational path: enforce default namespace to avoid accidental cross-namespace actions.
+- Failure path: missing kubectl or invalid context.
+- Recovery/rollback path: run with valid context/namespace values and verify config.
+
+## Usage
+```bash
+setup/local/configure-kubectl.sh --context prod-cluster --namespace platform
+setup/local/configure-kubectl.sh --kubeconfig "$HOME/.kube/prod-config" --context prod
+setup/local/configure-kubectl.sh --namespace default --dry-run
+```
+
+## Behavior
+- Main execution flow: ensure kubeconfig path exists, apply context and namespace updates.
+- Idempotency notes: idempotent for identical target settings.
+- Side effects: modifies kubeconfig.
+
+## Output
+- Standard output format: timestamped logs and optional dry-run commands.
+- Exit codes:
+  - `0` success
+  - `2` invalid arguments
+  - non-zero from kubectl on command failure
+
+## Failure Modes
+- Common errors and likely causes:
+  - kubectl missing
+  - invalid context name
+  - kubeconfig write permission issues
+- Recovery and rollback steps:
+  - validate context list (`kubectl config get-contexts`)
+  - fix file permissions/path
+  - rerun with corrected inputs
+
+## Security Notes
+- Secret handling: kubeconfig may contain credentials; keep file permissions strict.
+- Least-privilege requirements: user-level config modifications only.
+- Audit/logging expectations: avoid printing sensitive kubeconfig content.
+
+## Testing
+- Unit tests:
+  - argument parsing and dry-run behavior
+- Integration tests:
+  - context/namespace changes on test kubeconfig
+- Manual verification:
+  - `kubectl config view --minify` output check

docs/scripts/setup/local/configure-terraform.md

@@ -0,0 +1,67 @@
+# configure-terraform.sh
+
+## Purpose
+Apply managed Terraform CLI configuration for plugin caching, checkpoint behavior, and optional registry credentials.
+
+## Location
+`setup/local/configure-terraform.sh`
+
+## Preconditions
+- Required tools: `bash`
+- Required permissions: write access to Terraform config and cache directories
+- Required environment variables: optional `TF_TOKEN`
+
+## Arguments
+| Flag | Required | Default | Description |
+|------|----------|---------|-------------|
+| `--config-file PATH` | No | `~/.terraformrc` | Terraform CLI config path |
+| `--plugin-cache-dir PATH` | No | `~/.terraform.d/plugin-cache` | Plugin cache directory |
+| `--disable-checkpoint B` | No | `true` | `true\|false` checkpoint behavior |
+| `--registry-host HOST` | No | `app.terraform.io` | Credentials host |
+| `--token TOKEN` | No | from `TF_TOKEN` | Registry token |
+| `--dry-run` | No | `false` | Show resulting managed config |
+
+## Scenarios
+- Happy path: managed Terraform block applied with plugin cache and defaults.
+- Common operational path: set team-wide Terraform behavior on onboarding.
+- Failure path: invalid boolean value or inaccessible config path.
+- Recovery/rollback path: correct options and rerun, or remove managed block markers manually.
+
+## Usage
+```bash
+setup/local/configure-terraform.sh
+setup/local/configure-terraform.sh --plugin-cache-dir "$HOME/.cache/terraform/plugins"
+setup/local/configure-terraform.sh --token "$TF_TOKEN" --registry-host app.terraform.io --dry-run
+```
+
+## Behavior
+- Main execution flow: create config/cache paths, replace managed block in config file.
+- Idempotency notes: managed block replacement is idempotent.
+- Side effects: updates config file and creates plugin cache directory.
+
+## Output
+- Standard output format: timestamped status logs and config preview in dry-run mode.
+- Exit codes:
+  - `0` success
+  - `2` invalid arguments
+
+## Failure Modes
+- Common errors and likely causes:
+  - invalid `--disable-checkpoint` value
+  - filesystem permission issues for config/cache paths
+- Recovery and rollback steps:
+  - fix option values
+  - ensure directory ownership/permissions
+
+## Security Notes
+- Secret handling: token may be written in plaintext to Terraform config; restrict file permissions.
+- Least-privilege requirements: user-level config writes.
+- Audit/logging expectations: do not print token values in shared logs.
+
+## Testing
+- Unit tests:
+  - boolean parsing and argument validation
+- Integration tests:
+  - managed block merge behavior with pre-existing config
+- Manual verification:
+  - run `terraform init` and confirm plugin cache usage

docs/scripts/setup/local/install-cli-tools.md

@@ -0,0 +1,71 @@
+# install-cli-tools.sh
+
+## Purpose
+Install common DevOps CLI tooling using the host package manager with repeatable, scriptable behavior.
+
+## Location
+`setup/local/install-cli-tools.sh`
+
+## Preconditions
+- Required tools: `bash`, selected package manager (`brew`, `apt-get`, `dnf`, or `yum`), optional `sudo`
+- Required permissions: package-install privileges on workstation
+- Required environment variables: none
+
+## Arguments
+| Flag | Required | Default | Description |
+|------|----------|---------|-------------|
+| `--tools CSV` | No | built-in tool set | Comma-separated tool list |
+| `--tool NAME` | No | none | Add one tool (repeatable) |
+| `--manager NAME` | No | `auto` | `auto\|brew\|apt\|dnf\|yum` |
+| `--yes` | No | `false` | Non-interactive package install |
+| `--dry-run` | No | `false` | Print commands only |
+| `--update-cache` | No | `false` | Refresh package metadata before install |
+
+## Scenarios
+- Happy path: missing tools are installed, existing tools are skipped.
+- Common operational path: bootstrap a fresh developer workstation.
+- Failure path: unsupported manager/tool mapping or package install failure.
+- Recovery/rollback path: rerun with explicit manager/tool list and fixed package sources.
+
+## Usage
+```bash
+setup/local/install-cli-tools.sh --update-cache --yes
+setup/local/install-cli-tools.sh --manager brew --tools git,jq,shellcheck,shfmt
+setup/local/install-cli-tools.sh --tool kubectl --tool terraform --dry-run
+```
+
+## Behavior
+- Main execution flow: detect manager, optionally update cache, install requested/missing tools.
+- Idempotency notes: idempotent for already-installed tools.
+- Side effects: system package installation and updates.
+
+## Output
+- Standard output format: timestamped installation logs on stderr.
+- Exit codes:
+  - `0` all requested tools available/installed
+  - `1` one or more tools failed/unsupported
+  - `2` invalid arguments
+
+## Failure Modes
+- Common errors and likely causes:
+  - no supported package manager found
+  - package unavailable in configured repositories
+  - insufficient privileges for system install
+- Recovery and rollback steps:
+  - verify repository configuration and credentials
+  - rerun with explicit `--manager`
+  - install failed tools manually and rerun verification
+
+## Security Notes
+- Secret handling: no secret input expected.
+- Least-privilege requirements: use elevated privileges only for package operations.
+- Audit/logging expectations: installation logs should be retained during bootstrap.
+
+## Testing
+- Unit tests:
+  - manager/tool mapping logic
+  - argument parsing
+- Integration tests:
+  - dry-run/install behavior on supported OS images
+- Manual verification:
+  - run then confirm each tool in `PATH`

docs/scripts/setup/local/setup-gpg.md

@@ -0,0 +1,69 @@
+# setup-gpg.sh
+
+## Purpose
+Apply baseline GPG workstation setup and optional key/ownertrust imports for signing workflows.
+
+## Location
+`setup/local/setup-gpg.sh`
+
+## Preconditions
+- Required tools: `bash`, `gpg`, `gpgconf`, `awk`
+- Required permissions: write access to `~/.gnupg`
+- Required environment variables: none
+
+## Arguments
+| Flag | Required | Default | Description |
+|------|----------|---------|-------------|
+| `--public-key FILE` | No | none | Import public key (repeatable) |
+| `--private-key FILE` | No | none | Import private key (repeatable) |
+| `--ownertrust FILE` | No | none | Import ownertrust data |
+| `--default-key KEYID` | No | unset | Set default signing key |
+| `--pinentry-program PATH` | No | unset | Set pinentry executable |
+| `--dry-run` | No | `false` | Print planned actions/config |
+
+## Scenarios
+- Happy path: GPG home is secured and managed config applied.
+- Common operational path: import team signing keys on new machine.
+- Failure path: unreadable key files or missing `gpg` binary.
+- Recovery/rollback path: correct inputs, re-import keys, reapply managed config.
+
+## Usage
+```bash
+setup/local/setup-gpg.sh --default-key ABCD1234
+setup/local/setup-gpg.sh --public-key ./pub.asc --private-key ./secret.asc
+setup/local/setup-gpg.sh --pinentry-program /opt/homebrew/bin/pinentry-mac --dry-run
+```
+
+## Behavior
+- Main execution flow: ensure `~/.gnupg` permissions, import inputs, update managed `gpg.conf`, launch agent.
+- Idempotency notes: safe to rerun; imports may be no-op for existing keys.
+- Side effects: updates keyring/ownertrust and gpg configuration files.
+
+## Output
+- Standard output format: timestamped setup logs and optional dry-run config output.
+- Exit codes:
+  - `0` success
+  - `2` invalid arguments or unreadable inputs
+
+## Failure Modes
+- Common errors and likely causes:
+  - missing `gpg` installation
+  - unreadable key/ownertrust file
+  - invalid config options
+- Recovery and rollback steps:
+  - verify file paths and permissions
+  - reinstall/repair GPG tooling
+  - rerun import/config commands
+
+## Security Notes
+- Secret handling: private key imports are sensitive; use secure local storage and cleanup.
+- Least-privilege requirements: user-level keyring writes.
+- Audit/logging expectations: avoid verbose logs that expose key metadata unnecessarily.
+
+## Testing
+- Unit tests:
+  - option parsing and file validation
+- Integration tests:
+  - import behavior with test keyring
+- Manual verification:
+  - `gpg --list-secret-keys` and signing test