[patch] Unify the documentation (#2296)

Author: durera

.bob/plans/2026-05-20-docs-reorganization.md

@@ -0,0 +1,87 @@
+# Documentation Reorganization Plan
+
+## Objective
+
+Consolidate all documentation from `docs/commands/` into `docs/guides/`, ensuring each CLI function has a comprehensive guide. Review all documents for quality, consistency, and style using `docs/guides/install.md` as the exemplar. Split the existing backup-restore guide into separate backup and restore documents.
+
+## Critical Rules
+
+1. **Use install.md as the style exemplar** - All documents must follow the structure, formatting, and tone of `docs/guides/install.md`
+2. **One page at a time** - Complete each document fully before moving to the next
+3. **Configure redirects** - Add redirect mappings in `mkdocs.yml` for all moved/renamed pages
+4. **Preserve content** - Do not delete information; reorganize and improve it
+5. **Validate after each change** - Ensure mkdocs builds successfully after each document update
+
+## Execution Plan
+
+### Phase 1: Split Backup-Restore Guide
+
+- [ ] **1.1** Create `docs/guides/backup.md` from backup-restore.md content
+- [ ] **1.2** Create `docs/guides/restore.md` from backup-restore.md content
+- [ ] **1.3** Update mkdocs.yml navigation and add redirects
+- [ ] **1.4** Delete obsolete backup-restore.md and command files
+- [ ] **1.5** Validate Phase 1
+
+### Phase 2: Migrate Must-Gather Command
+
+- [ ] **2.1** Create comprehensive `docs/guides/must-gather.md`
+- [ ] **2.2** Update mkdocs.yml with navigation and redirect
+- [ ] **2.3** Delete `docs/commands/must-gather.md`
+- [ ] **2.4** Validate Phase 2
+
+### Phase 3: Migrate Airgap Configuration
+
+- [ ] **3.1** Create comprehensive `docs/guides/configure-airgap.md`
+- [ ] **3.2** Update mkdocs.yml with navigation and redirect
+- [ ] **3.3** Delete `docs/commands/configure-airgap.md`
+- [ ] **3.4** Validate Phase 3
+
+### Phase 4: Migrate Registry Commands
+
+- [ ] **4.1** Create `docs/guides/setup-registry.md`
+- [ ] **4.2** Create `docs/guides/teardown-registry.md`
+- [ ] **4.3** Update mkdocs.yml with navigation and redirects
+- [ ] **4.4** Delete obsolete command files
+- [ ] **4.5** Validate Phase 4
+
+### Phase 5: Migrate Provisioning Commands ✅ COMPLETED
+
+- [x] **5.1** Create `docs/guides/provision-fyre.md`
+- [x] **5.2** Create `docs/guides/provision-roks.md`
+- [x] **5.3** Create `docs/guides/provision-rosa.md`
+- [x] **5.4** Create `docs/guides/provision-aws.md`
+- [x] **5.5** Update mkdocs.yml with navigation and redirects
+- [x] **5.6** Delete obsolete provisioning command files
+- [x] **5.7** Validate Phase 5 - mkdocs serving successfully
+
+### Phase 6: Migrate Remaining Commands
+
+- [ ] **6.1** Create `docs/guides/mirror-redhat-images.md`
+- [ ] **6.2** Create `docs/guides/configtool-oidc.md`
+- [ ] **6.3** Create `docs/guides/debug.md` if needed
+- [ ] **6.4** Update mkdocs.yml and remove Command Reference section
+- [ ] **6.5** Delete all remaining command files
+- [ ] **6.6** Validate Phase 6
+
+### Phase 7: Review Existing Guides
+
+- [ ] **7.1** Review `docs/guides/install.md`
+- [ ] **7.2** Review `docs/guides/update.md`
+- [ ] **7.3** Review `docs/guides/upgrade.md`
+- [ ] **7.4** Review `docs/guides/uninstall.md`
+- [ ] **7.5** Review `docs/guides/aiservice-install.md`
+- [ ] **7.6** Review `docs/guides/image-mirroring.md`
+- [ ] **7.7** Review `docs/guides/image-validation.md`
+- [ ] **7.8** Validate Phase 7
+
+### Phase 8: Final Cleanup
+
+- [ ] **8.1** Verify docs/commands directory is empty or removed
+- [ ] **8.2** Review all redirects in mkdocs.yml
+- [ ] **8.3** Review navigation structure
+- [ ] **8.4** Build and test documentation
+- [ ] **8.5** Create summary of changes
+
+## Validation
+
+After each phase run `mkdocs serve` and verify builds, navigation, and redirects work correctly.

.bob/redis-locking/README.md

@@ -0,0 +1 @@
+These documents had been generated in `/docs` but were and are not part of the documentation site - I don't know if they are even needed or not, if they are needed they need a proper home - which is probably not even this repository given the role of the script?

docs/ibm-toolchain-redis-setup.sh …dis-locking/ibm-toolchain-redis-setup.shdocs/ibm-toolchain-redis-setup.sh renamed to .bob/redis-locking/ibm-toolchain-redis-setup.sh docs/ibm-toolchain-redis-setup.sh renamed to .bob/redis-locking/ibm-toolchain-redis-setup.sh

@@ -3,7 +3,7 @@
     "files": "build/bin/config/oscap/ssg-rhel9-ds.xml|^.secrets.baseline$|^docs/catalogs/",
     "lines": null
   },
-  "generated_at": "2026-05-19T12:05:11Z",
+  "generated_at": "2026-05-20T23:47:35Z",
   "plugins_used": [
     {
       "name": "AWSKeyDetector"
@@ -87,52 +87,70 @@
         "verified_result": null
       }
     ],
-    "docs/commands/provision-fyre.md": [
+    "docs/guides/configure-airgap.md": [
       {
-        "hashed_secret": "b60d121b438a380c343d5ec3c2037564b82ffef3",
+        "hashed_secret": "354b3a4b7715d3694c88a4fa7db49e41de86568e",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 44,
+        "line_number": 145,
         "type": "Secret Keyword",
         "verified_result": null
       }
     ],
-    "docs/commands/provision-roks.md": [
+    "docs/guides/image-mirroring.md": [
       {
         "hashed_secret": "b60d121b438a380c343d5ec3c2037564b82ffef3",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 40,
+        "line_number": 46,
         "type": "Secret Keyword",
         "verified_result": null
       }
     ],
-    "docs/commands/setup-registry.md": [
+    "docs/guides/install.md": [
       {
         "hashed_secret": "b60d121b438a380c343d5ec3c2037564b82ffef3",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 31,
+        "line_number": 353,
         "type": "Secret Keyword",
         "verified_result": null
       }
     ],
-    "docs/guides/image-mirroring.md": [
+    "docs/guides/private-registry.md": [
       {
-        "hashed_secret": "b60d121b438a380c343d5ec3c2037564b82ffef3",
+        "hashed_secret": "354b3a4b7715d3694c88a4fa7db49e41de86568e",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 46,
+        "line_number": 122,
         "type": "Secret Keyword",
         "verified_result": null
       }
     ],
-    "docs/guides/install.md": [
+    "docs/guides/provision-fyre.md": [
       {
-        "hashed_secret": "b60d121b438a380c343d5ec3c2037564b82ffef3",
+        "hashed_secret": "11fa7c37d697f30e6aee828b4426a10f83ab2380",
+        "is_secret": false,
+        "is_verified": false,
+        "line_number": 107,
+        "type": "Secret Keyword",
+        "verified_result": null
+      },
+      {
+        "hashed_secret": "c7f112c59ab7e077fd20a28107b7a200469ebdac",
+        "is_secret": false,
+        "is_verified": false,
+        "line_number": 252,
+        "type": "Secret Keyword",
+        "verified_result": null
+      }
+    ],
+    "docs/guides/provision-roks.md": [
+      {
+        "hashed_secret": "11fa7c37d697f30e6aee828b4426a10f83ab2380",
         "is_secret": false,
         "is_verified": false,
-        "line_number": 361,
+        "line_number": 95,
         "type": "Secret Keyword",
         "verified_result": null
       }

docs/redis-locking-setup.md .bob/redis-locking/redis-locking-setup.mddocs/redis-locking-setup.md renamed to .bob/redis-locking/redis-locking-setup.md

@@ -259,6 +259,17 @@ detect-secrets:
 	detect-secrets scan --update .secrets.baseline
 	detect-secrets audit .secrets.baseline
 
+
+.venv-docs:
+# We need to install the python-devops and cli packages because we generate documentation from their code using mkdocs directives
+	python3 -m venv .venv-docs
+	. .venv-docs/bin/activate && python -m pip install setuptools
+	. .venv-docs/bin/activate && python -m pip install -e ../python-devops
+	. .venv-docs/bin/activate && python -m pip install -e ./python
+# Install mkdocs and the various plugins that we use, including our custom plugins
+	. .venv-docs/bin/activate && python -m pip install -q mkdocs properdocs mkdocs-carbon mkdocs-glightbox mkdocs-redirects
+	. .venv-docs/bin/activate && python -m pip install -e ./mkdocs_plugins
+
 .PHONY: mkdocs-serve
-mkdocs-serve:
+mkdocs-serve: .venv-docs
 	. .venv-docs/bin/activate && mkdocs serve --livereload --dev-addr localhost:9010

.secrets.baseline

@@ -521,7 +521,7 @@ The packages available in these catalogs are fixed. Multiple installations at di
 #### Disconnected Install
 > I want to run a disconnected environment using a private mirror registry
 
-The MAS CLI [mirror-images](../guides/image-mirroring.md) function is the easiest way to mirror the content from a specific version of the Maximo Operator Catalog.  Once the images are mirrored simply run the [configure-airgap](../commands/configure-airgap.md) function to add the IBM Maximo Application Suite **ImageDigestMirrorset** to your cluster before starting the installation.
+The MAS CLI [mirror-images](../guides/image-mirroring.md) function is the easiest way to mirror the content from a specific version of the Maximo Operator Catalog.  Once the images are mirrored simply run the [configure-airgap](../guides/configure-airgap.md) function to add the IBM Maximo Application Suite **ImageDigestMirrorset** to your cluster before starting the installation.
 
 
 ### Dynamic Catalog