Enforce a "How it works" section in how-to guides (#40115)

Architecture is often a point of confusion among Teleport users. When
following how-to guides, it is important for users to understand how the
components of a setup fit together so they can (a) form a mental model
of where each step first in an overall procedure and (b) troubleshoot
more easily if they encounter the unexpected.

This change ensures that the first H2 section of a how-to guide is
called "How it works" by adding a vale
[script](https://vale.sh/docs/topics/styles/#script) rule. As the error
message associated with the rule indicates, the "How it works" section
is intended to include architectural information.

The "How it works" section is intended as a complement to any dedicated
architectural docs. Since most users visit the docs through organic
search, we can't guarantee that a user visiting a guide will have
discovered the relevant architectural information.

.github/vale-styles/structure/architecture-h2.yml

@@ -0,0 +1,32 @@
+# This style enforces the presence of architectural information in how-to
+# guides. The motivation is that the architecture of the setups shown in how-to
+# guides is often a point of confusion for users.
+#
+# In this rule, the first H2 of a how-to guide must be called "How it works".
+# This style defines a how-to guide as any guide that includes at least one H2
+# beginning "Step [0-9]". 
+extends: script
+level: error
+message: "In a how-to guide, the first H2-level section must be called `## How it works`. Use this section to include 1-3 paragraphs that describe the high-level architecture of the setup shown in the guide, i.e., which infrastructure components are involved and how they communicate. If there is already architectural information in the guide, include it in a `## How it works` section."
+scope: raw
+script: |
+  text := import("text")
+  getMatches := func() {
+    // If there is no "Step" H2, this is not a how-to guide.
+    if !text.re_match(`\n## [sS]tep [0-9]`, scope) {
+      return []
+    }
+ 
+    // Find the first H2 section. If it is not called "How it works", return
+    // an error at the position of the first H2.
+    firstH2 := text.re_find(`\n## [^#\n]+\n`, scope, 1)
+    if firstH2 && firstH2[0][0].text != "\n## How it works\n" {
+      return [{
+        begin: firstH2[0][0].begin,
+        end: firstH2[0][0].end
+      }]
+    }
+  }
+
+  matches := getMatches()
+

.vale.ini

@@ -5,4 +5,4 @@ MinAlertLevel = suggestion
 mdx = md
 
 [*.md]
-BasedOnStyles = messaging,examples,aws-products
+BasedOnStyles = messaging,examples,aws-products,structure