Add Pulumi and spanning-tree guides and normalize filenames

.github/workflows/docs-quality.yml

@@ -29,17 +29,29 @@ jobs:
               "README.md",
               "CONTRIBUTING.md",
               "STYLE_GUIDE.md",
+              "visual-guides.md",
               "arista.md",
+              "aws.md",
               "azure.md",
               "cisco.md",
               "docker.md",
-              "gcloud.md",
+              "git.md",
+              "google-cloud.md",
               "iptables.md",
               "kubernetes.md",
+              "leaf-spine.md",
+              "linux-boot.md",
+              "pulumi.md",
               "rest-api.md",
+              "spanning-tree.md",
               "terraform.md",
           ]
 
+          supported_mermaid = re.compile(
+              r"^(flowchart|graph|sequenceDiagram|stateDiagram-v2|"
+              r"classDiagram|erDiagram|journey|gitGraph|mindmap|timeline)\b"
+          )
+
           errors = []
           for filename in files:
               path = Path(filename)
@@ -65,6 +77,26 @@ jobs:
                   if re.search(r"\[[^\]]*\]\(\s*\)", line):
                       errors.append(f"{filename}:{number}: empty Markdown link")
 
+              opening_count = text.count("```mermaid")
+              mermaid_blocks = re.findall(
+                  r"```mermaid\s*\n(.*?)```",
+                  text,
+                  flags=re.DOTALL,
+              )
+              if opening_count != len(mermaid_blocks):
+                  errors.append(f"{filename}: unclosed Mermaid code fence")
+
+              for index, block in enumerate(mermaid_blocks, start=1):
+                  first_line = next(
+                      (line.strip() for line in block.splitlines() if line.strip()),
+                      "",
+                  )
+                  if not supported_mermaid.match(first_line):
+                      errors.append(
+                          f"{filename}: Mermaid block {index} has an unsupported "
+                          f"or missing diagram declaration: {first_line!r}"
+                      )
+
           if errors:
               print("\n".join(errors))
               sys.exit(1)
@@ -88,13 +120,20 @@ jobs:
             README.md
             CONTRIBUTING.md
             STYLE_GUIDE.md
+            visual-guides.md
             arista.md
+            aws.md
             azure.md
             cisco.md
             docker.md
-            gcloud.md
+            git.md
+            google-cloud.md
             iptables.md
             kubernetes.md
+            leaf-spine.md
+            linux-boot.md
+            pulumi.md
             rest-api.md
+            spanning-tree.md
             terraform.md
-          fail: true
+          fail: true

README.md

@@ -11,17 +11,32 @@ Practical quick-reference notes for network engineering, Linux operations, cloud
 - Start with read-only inspection commands and capture the current state.
 - Treat `clear`, `delete`, `destroy`, `flush`, `reset`, `prune`, and `--force` operations as destructive.
 - Prefer official documentation for release-specific behavior.
+- Use [visual-guides.md](visual-guides.md) for topology, lifecycle, state-transition, and troubleshooting diagrams.
 - Open a content-correction issue when a command is obsolete, unsafe, ambiguous, or vendor-specific.
 
+## Visual guides
+
+The diagrams are intentionally limited to concepts where visual relationships improve understanding; command-oriented references remain text-first.
+
+| Concept | Visual reference | Detailed reference |
+|---|---|---|
+| Spanning-tree root and alternate path | [Visual guide](visual-guides.md#spanning-tree-root-and-alternate-path) | [spanning-tree.md](spanning-tree.md) |
+| Leaf-spine topology | [Visual guide](visual-guides.md#leaf-spine-fabric) | [leaf-spine.md](leaf-spine.md) |
+| Pulumi change lifecycle | [Visual guide](visual-guides.md#pulumi-change-lifecycle) | [pulumi.md](pulumi.md) |
+| Linux boot sequence | [Visual guide](visual-guides.md#linux-boot-sequence) | [linux-boot.md](linux-boot.md) |
+| Git branch and pull-request workflow | [Visual guide](visual-guides.md#git-branch-and-pull-request-workflow) | [git.md](git.md) |
+| Operational troubleshooting sequence | [Visual guide](visual-guides.md#operational-troubleshooting-sequence) | [STYLE_GUIDE.md](STYLE_GUIDE.md) |
+
 ## Networking fundamentals
 
 | Topic | Reference |
 |---|---|
 | Clos fabrics | [clos.md](clos.md) |
-| Leaf-spine design | [leafspine.md](leafspine.md) |
+| Leaf-spine design | [leaf-spine.md](leaf-spine.md) |
 | LLDP | [lldp.md](lldp.md) |
 | OSI model | [osi.md](osi.md) |
 | OSPF | [ospf.md](ospf.md) |
+| Spanning Tree Protocol | [spanning-tree.md](spanning-tree.md) |
 | TCP | [tcp.md](tcp.md) |
 | UDP | [udp.md](udp.md) |
 
@@ -45,20 +60,19 @@ Practical quick-reference notes for network engineering, Linux operations, cloud
 
 ## Cloud platforms
 
-| Topic | Reference |
+| Platform | Reference |
 |---|---|
-| AWS services | [awscloud.md](awscloud.md) |
-| AWS CLI | [awscli.md](awscli.md) |
+| Amazon Web Services and AWS CLI | [aws.md](aws.md) |
 | Microsoft Azure and Azure CLI | [azure.md](azure.md) |
-| Google Cloud services | [gcpcloud.md](gcpcloud.md) |
-| Google Cloud CLI | [gcloud.md](gcloud.md) |
+| Google Cloud and Google Cloud CLI | [google-cloud.md](google-cloud.md) |
 
 ## Containers, orchestration, and infrastructure as code
 
 | Topic | Reference |
 |---|---|
 | Docker and Docker Compose | [docker.md](docker.md) |
 | Kubernetes and kubectl | [kubernetes.md](kubernetes.md) |
+| Pulumi | [pulumi.md](pulumi.md) |
 | Terraform | [terraform.md](terraform.md) |
 | Jenkins CI/CD | [jenkins-cicd.md](jenkins-cicd.md) |
 | Puppet | [puppet.md](puppet.md) |
@@ -71,7 +85,7 @@ Practical quick-reference notes for network engineering, Linux operations, cloud
 | Debian | [debian.md](debian.md) |
 | HAProxy | [haproxy.md](haproxy.md) |
 | iptables | [iptables.md](iptables.md) |
-| Linux boot process | [linux_kernel_boot.md](linux_kernel_boot.md) |
+| Linux boot and kernel | [linux-boot.md](linux-boot.md) |
 | nmap | [nmap.md](nmap.md) |
 | Pacemaker | [pacemaker.md](pacemaker.md) |
 | Corosync | [corosync.md](corosync.md) |
@@ -84,11 +98,15 @@ Practical quick-reference notes for network engineering, Linux operations, cloud
 
 | Topic | Reference |
 |---|---|
-| Git | [github.md](github.md) |
+| Git | [git.md](git.md) |
 | Kafka | [kafka.md](kafka.md) |
 | REST APIs | [rest-api.md](rest-api.md) |
 | SQL | [sql.md](sql.md) |
 
+## Filename conventions
+
+New and renamed sheets use descriptive lowercase kebab-case names, such as `google-cloud.md`, `leaf-spine.md`, and `spanning-tree.md`. A platform overview and its primary CLI belong in one file when they serve the same operational audience.
+
 ## Maintenance policy
 
 Accuracy-sensitive documents should include an **Applies to** line and a **Last reviewed** date. A review date means the examples received a documentation review; it does not guarantee compatibility with every release or environment.
@@ -97,4 +115,4 @@ Repository quality checks validate the maintained documentation surface on pull
 
 ## License
 
-Content is available under the [MIT License](LICENSE).
+Content is available under the [MIT License](LICENSE).

STYLE_GUIDE.md

@@ -4,6 +4,28 @@
 
 Each file should help an engineer answer a specific operational question quickly. Prefer commands, decision points, expected output, and cautions over broad product descriptions.
 
+## Filename conventions
+
+Use descriptive lowercase kebab-case filenames:
+
+```text
+google-cloud.md
+leaf-spine.md
+spanning-tree.md
+```
+
+Rules:
+
+- Use the product or protocol name an engineer is likely to search for.
+- Separate words with hyphens, not underscores or compressed spellings.
+- Avoid filenames that are broader or narrower than the actual content.
+- Do not name a Git reference `github.md` unless the document is specifically about GitHub rather than Git.
+- Combine a platform overview and its primary CLI when they serve the same audience and would otherwise repeat concepts.
+- Keep separate files when tools have different lifecycles, safety models, or operational workflows, such as Terraform and Pulumi.
+- Avoid renaming stable single-word files only for cosmetic consistency.
+
+When renaming or merging files, update the README, cross-references, and documentation-quality workflow in the same change.
+
 ## Required metadata for maintained sheets
 
 Place these lines immediately below the title:
@@ -28,6 +50,33 @@ Do not use realistic credentials, public IP addresses belonging to third parties
 
 For state-changing commands, show a read-only verification command first and add an inline warning when the operation is destructive.
 
+## Visual diagrams
+
+Use Mermaid when a diagram explains relationships that are harder to understand as a flat list. Good candidates include:
+
+- physical or logical topology;
+- packet, request, or control-plane paths;
+- state transitions;
+- deployment and infrastructure lifecycles;
+- decision trees;
+- failure domains;
+- ordered boot or troubleshooting sequences.
+
+Do not add a diagram merely to repeat a command list, glossary, or short numbered procedure. A diagram should make a specific concept faster to understand.
+
+Guidelines:
+
+- Keep diagrams conceptual unless the document is explicitly vendor-specific.
+- Use labels that remain readable in both GitHub light and dark themes.
+- Avoid custom colors and styling unless they convey essential meaning.
+- Keep node and edge counts low enough to read without zooming.
+- Add a short explanation before or after each diagram.
+- State important simplifications and do not imply that one diagram represents every vendor or failure case.
+- Link visual guides to the detailed operational reference containing commands and cautions.
+- Prefer one focused diagram over a large all-in-one architecture drawing.
+
+The repository-wide diagrams live in [visual-guides.md](visual-guides.md). Command-heavy cloud and utility sheets remain text-first unless a topology or lifecycle diagram adds clear operational value. Topic files may embed a diagram directly when it is essential to understanding that specific page.
+
 ## Troubleshooting order
 
 Troubleshooting sections should generally proceed in this order: