Add README files and diagrams across repository

infra-run/scripts/README.md

@@ -0,0 +1,23 @@
+# infra-run/scripts
+
+This directory groups executable tooling used across the `infra-run` project. It separates shell-first operational scripts from future Python-based utilities while keeping both under one automation entry point.
+
+## Diagram
+
+```mermaid
+flowchart TD
+  A["scripts"] --> B["bash"]
+  A --> C["python"]
+  B --> D["Operational toolkits"]
+  C --> E["Future helper utilities"]
+```
+
+## Scope
+
+- `bash` - current implementation area with production-style operations toolkits.
+- `python` - reserved space for future supporting utilities.
+
+## Notes
+
+- The repository currently emphasizes Bash because it maps directly to day-to-day Linux operations.
+- The structure leaves room for higher-level helpers without mixing concerns.

infra-run/scripts/bash/README.md

@@ -2,6 +2,20 @@
 
 Small, practical Bash scripts for Linux operations checks and incident triage. The scripts are sanitized examples inspired by production Linux operations work and avoid destructive actions or root-only assumptions.
 
+## Diagram
+
+```mermaid
+flowchart TD
+  A["bash"] --> B["os-healthcheck"]
+  A --> C["disk-full"]
+  A --> D["veritas"]
+  A --> E["gpfs"]
+  B --> B1["Host diagnostics"]
+  C --> C1["Incident workflow"]
+  D --> D1["VxVM and VCS change flow"]
+  E --> E1["Spectrum Scale expansion flow"]
+```
+
 ## Scripts
 
 - `os-healthcheck/healthcheck.sh` - general host health overview.

infra-run/scripts/bash/disk-full/README.md

@@ -2,6 +2,20 @@
 
 Production-style Bash toolkit for diagnosing and handling a disk full incident on Linux systems. It is intentionally conservative: default mode is safe, cleanup actions require `--execute` and an operator confirmation prompt, and the scripts do not assume root access.
 
+## Diagram
+
+```mermaid
+flowchart TD
+  A["disk-full"] --> B["01_disk_overview.sh"]
+  A --> C["02_find_big_files.sh"]
+  A --> D["03_deleted_open_files.sh"]
+  A --> E["04_top_dirs.sh"]
+  A --> F["05_log_cleanup.sh"]
+  A --> G["06_quick_fix.sh"]
+  A --> H["07_postcheck.sh"]
+  A --> I["disk_full_runbook.sh"]
+```
+
 ## Why Disk Full Incidents Happen
 
 - **Logs** - application, audit, system, or middleware logs can grow faster than rotation policy expects.

infra-run/scripts/bash/gpfs/README.md

@@ -4,6 +4,21 @@ Safe, sanitized Bash examples for planning and executing a GPFS / IBM Spectrum S
 
 These scripts are examples. Exact GPFS commands, flags, quorum practices, failure-group design, and storage naming standards vary by Spectrum Scale version and site policy.
 
+## Diagram
+
+```mermaid
+flowchart TD
+  A["gpfs"] --> B["01_cluster_overview.sh"]
+  A --> C["02_precheck_gpfs.sh"]
+  A --> D["03_detect_new_disks.sh"]
+  A --> E["04_create_nsd_stanza.sh"]
+  A --> F["05_add_nsd_to_filesystem.sh"]
+  A --> G["06_rebalance_filesystem.sh"]
+  A --> H["07_postcheck_gpfs.sh"]
+  A --> I["08_generate_report.sh"]
+  A --> J["gpfs_extend_runbook.sh"]
+```
+
 ## Concepts
 
 - **Cluster** - the Spectrum Scale administrative domain containing the nodes, daemon configuration, quorum policy, filesystems, and NSDs.

infra-run/scripts/bash/os-healthcheck/README.md

@@ -0,0 +1,39 @@
+# Linux Operations Healthcheck Toolkit
+
+This directory contains first-pass Linux diagnostics for common host checks. The scripts focus on health visibility, disk usage, service status, network troubleshooting, and lightweight reporting without making system changes.
+
+## Diagram
+
+```mermaid
+flowchart TD
+  A["os-healthcheck"] --> B["healthcheck.sh"]
+  A --> C["disk_check.sh"]
+  A --> D["service_check.sh"]
+  A --> E["system_report.sh"]
+  A --> F["network_troubleshoot.sh"]
+```
+
+## Scripts
+
+- `healthcheck.sh` - consolidated host overview.
+- `disk_check.sh` - threshold-based filesystem usage check.
+- `service_check.sh` - service state validation for critical daemons.
+- `system_report.sh` - timestamped report generation for quick evidence capture.
+- `network_troubleshoot.sh` - local network, DNS, route, and connectivity checks.
+
+## Usage
+
+```bash
+cd infra-run/scripts/bash/os-healthcheck
+
+./healthcheck.sh
+./disk_check.sh 90
+./service_check.sh sshd nginx
+./system_report.sh
+./network_troubleshoot.sh 8.8.8.8
+```
+
+## Notes
+
+- The toolkit is read-only and suited to initial triage.
+- It aligns with the portfolio pattern of quick pre-check and evidence collection steps.

infra-run/scripts/bash/veritas/README.md

@@ -2,6 +2,21 @@
 
 Production-style Bash examples for expanding storage in a Veritas environment. These scripts are sanitized operational tooling for a Linux Infrastructure Engineer portfolio: they show the flow, guardrails, logging, and validation patterns used in enterprise change work.
 
+## Diagram
+
+```mermaid
+flowchart TD
+  A["veritas"] --> B["01_detect_new_luns.sh"]
+  A --> C["02_precheck_vcs_vxvm.sh"]
+  A --> D["03_freeze_vcs_group.sh"]
+  A --> E["04_init_vxvm_disks.sh"]
+  A --> F["05_extend_diskgroup.sh"]
+  A --> G["06_extend_volume_fs.sh"]
+  A --> H["07_postcheck_vcs_vxvm.sh"]
+  A --> I["08_unfreeze_vcs_group.sh"]
+  A --> J["veritas_extend_runbook.sh"]
+```
+
 ## VxVM vs VCS
 
 Veritas Volume Manager (VxVM) manages disks, disk groups, volumes, plexes, and subdisks. It is the storage virtualization layer used to initialize SAN LUNs, add capacity to disk groups, and grow volumes.

infra-run/scripts/python/README.md

@@ -0,0 +1,17 @@
+# infra-run/scripts/python
+
+This directory is reserved for Python helpers that may later complement the Bash-first operations tooling. It provides a separate place for richer parsing, reporting, or integration logic without mixing languages in the same toolkit directory.
+
+## Diagram
+
+```mermaid
+flowchart LR
+  A["python"] --> B["Future reporting utilities"]
+  A --> C["Parsers"]
+  A --> D["Automation helpers"]
+```
+
+## Notes
+
+- The folder currently contains only a placeholder file.
+- Keeping it explicit now makes future multi-language tooling easier to organize.