docs(contribute): require sentence-case headings including catalog labels

AGENTS.md

@@ -62,10 +62,13 @@ Canonical framework overview example: `docs/pages/supply-chain/overview.mdx`.
 
 - Explain: non-technical first, then technical depth
 - Language: direct/technical, no first person (`implement X` not `I suggest`)
+- Headings: **sentence case required** (`## Signing verification`, not Title Case). Applies to all H2/H3 **including**
+  catalog labels: `## Further reading`, `## Related frameworks`, `## What this framework covers` — never
+  `## Further Reading & Tools` or Title Case reserved names. See `docs/pages/contribute/style-and-terminology.mdx`
 - Key Takeaway (canonical): `> 🔑 **Key Takeaway**:` under ~40 words; the point of the page, not a TOC summary
 - Use `<Checklist>` for interactive checklists; never plain `- [ ]` task lists outside examples
 - Failure modes: anchor next to the related recommendation (do not invent a generic "Pitfalls" dump by default)
-- Links: descriptive text; Further reading / Resources; relative internal paths
+- Links: descriptive text; `## Further reading` / `## Resources`; relative internal paths
 - Frontmatter precision: title under 60 chars or use `| SEAL`; description 140–160 chars; contributors use GitHub
   usernames. First-time contributors register in `docs/pages/config/contributors.json`
 - Contributors database shape:

docs/pages/config/template.mdx

@@ -210,14 +210,15 @@ CISA advisory, a CVE, a post-mortem, or a credible reporting source.]
 {/* ============================================================================
     OVERVIEW PAGES ONLY: include a page map section.
 
-    Acceptable H2 titles (see content-model.mdx):
-    - ## What This Framework Covers
-    - ## Framework structure / ## Contents (only if each child has a one-line
-      description, not bare links)
+    Acceptable H2 titles (sentence case; see content-model.mdx and style guide):
+    - ## What this framework covers (preferred)
+    - ## Framework structure
+    - ## Contents
+    - ## Table of contents
 
     Example:
 
-    ## What This Framework Covers
+    ## What this framework covers
 
     1. [Dependency Awareness](/supply-chain/dependency-awareness):
        managing external packages, version pinning, lockfile integrity, and
@@ -230,10 +231,10 @@ CISA advisory, a CVE, a post-mortem, or a credible reporting source.]
     or removed. Reference: docs/pages/supply-chain/overview.mdx
 
     If this is a regular sub-page (not an overview), delete this comment and
-    skip straight to "Further Reading & Tools" below.
-============================================================================ */}
+    skip straight to "Further reading" below.
+*/}
 
-## Further Reading & Tools
+## Further reading
 
 [Required. Two types of links belong here:
 

docs/pages/contribute/content-model.mdx

@@ -200,17 +200,20 @@ Do not rewrite historical contributor attribution without clear evidence it is w
 Unheaded introduction (2–3 short paragraphs)
 ## Foundational section (named for the topic)
 ## Main sections...
-## Further Reading & Tools (or equivalent)
+## Further reading
 ---
 <ContributeFooter />
 ```
 
+All `##` / `###` headings use **sentence case** (first word and proper nouns only). See
+[Heading sentence case](/contribute/style-and-terminology#heading-sentence-case-required) in the style guide.
+Reserved catalog names below are already written in sentence case — do not Title-Case them.
+
 ## Key Takeaway contract
 
 Canonical form (exact label and punctuation):
 
 > 🔑 **Key Takeaway**: Concrete claim a reader can act on or remember. Prefer one or two sentences under 40 words.
-```
 
 Rules:
 
@@ -239,10 +242,24 @@ A framework overview must:
 9. Link adjacent frameworks when reader journeys commonly cross domains
 10. Include Further reading and/or Related frameworks for primary references
 
-Name the page map section family of titles:
+Name the page map section with one of these **sentence-case** titles (validator matches case-insensitively):
+
+- `## What this framework covers` (preferred)
+- `## Framework structure`
+- `## Contents`
+- `## Table of contents`
+- `## Pages` (legacy accept; prefer a more descriptive map title on new work)
+
+Name further-material sections with one of these **sentence-case** titles:
+
+- `## Further reading` (preferred for mixed internal + external links)
+- `## Resources`
+- `## References`
+- `## Related frameworks` (framework overviews and cross-domain hubs)
+- `## Tools`
 
-- `## What This Framework Covers`
-- `## Framework structure` / `## Contents` when those headings already enumerate linked children with descriptions
+Do **not** use `## Further Reading & Tools`, Title Case variants (`## Further Reading`, `## Related Frameworks`), or
+other synonyms. Put tools and external catalogs under `## Further reading` or `## Tools` as appropriate.
 
 A bare bullet list of links without one-line descriptions is not enough.
 
@@ -309,7 +326,8 @@ exception block when automation supports it.
 - Canonical Key Takeaway label present when required
 - Heading level skips
 - Static checklist detection
-- Overview page-map heading presence
+- Overview page-map heading presence (allowed sentence-case catalog names)
+- Further-material heading presence (allowed sentence-case catalog names)
 - `dev: true` reminders are CI-side elsewhere
 
 **Human / steward judgment:**
@@ -320,6 +338,7 @@ exception block when automation supports it.
 - When to split pages
 - Substantive conflicts between frameworks
 - Exception approval
+- **Heading sentence case** on non-catalog H2/H3 labels (validator does not Title-Case-lint freeform headings yet)
 
 ## Migration strategy
 

docs/pages/contribute/contributing.mdx

@@ -74,7 +74,9 @@ the starting point for any new page. It lays out the required sections (key take
 further reading), the optional ones, the frontmatter rules, and the import paths. The structure is the same one used
 across every page on the site, which is what makes the Frameworks readable as a whole rather than as a pile of
 individual contributions. Open it before you start writing, even if you are only adding a section to an existing page,
-since the same structural rules apply.
+since the same structural rules apply. Headings use **sentence case** (see
+[style and terminology](/contribute/style-and-terminology#heading-sentence-case-required)); catalog names such as
+`## Further reading` and `## What this framework covers` stay sentence case too.
 
 **Keep each page focused on a single topic.** If your content would require more than 5-6 top-level
 sections (## headings), it is covering too much ground in one place. Split it into separate pages
@@ -355,6 +357,9 @@ is a useful starting point.
 
 - Objective, explanatory tone; no first-person recommendations (`Implement X`, not `I suggest X`)
 - Concise sentences; use lists, tables, Mermaid, and block quotes to break down complexity
+- **Headings in sentence case** on every `##` / `###`, including catalog labels (`## Further reading`, not
+  `## Further Reading` or `## Further Reading & Tools`) — full rule:
+  [Heading sentence case](/contribute/style-and-terminology#heading-sentence-case-required)
 - Link and verify resources; introduce acronyms on first use
 - Web3 changes fast: prefer future-proof wording
 - Do **not** submit fully AI-generated pages; grammar/phrasing help is fine

docs/pages/contribute/docs-normalization-checklist.mdx

@@ -51,9 +51,11 @@ import { TagList, AttributionList, ContributeFooter, Checklist } from '../../../
 - [ ] Unheaded introduction establishes stakes without filler
 - [ ] Foundational section orients top new readers
 - [ ] Heading levels do not skip
+- [ ] Headings use sentence case (first word + proper nouns only; including `## Further reading`, not Title Case)
 - [ ] Page focus roughly ≤6 top-level sections or intentionally split
-- [ ] Further reading / related frameworks present when required
+- [ ] Further reading / related frameworks present when required (catalog H2 names; sentence case)
 - [ ] Overview page map lists every child sidebar page with one-line descriptions
+- [ ] Overview page-map H2 is a catalog name (`What this framework covers`, `Contents`, …)
 - [ ] Interactive `<Checklist>` used instead of static task lists where appropriate
 - [ ] Terminology and modality match the style guide
 - [ ] Citations present for incidents, standards, and product-specific claims

docs/pages/contribute/style-and-terminology.mdx

@@ -79,7 +79,7 @@ Guidelines:
 - Historical loss figures and attack attributions need a citation or must be softened/removed
 - Prefer descriptive link text (`OWASP ASVS`, not `this article`)
 - Use **relative paths** for internal links (`/wallet-security/overview`)
-- Prefer a **Further Reading & Tools** (or Resources) section for external catalogs; keep in-body citations where
+- Prefer a **Further reading** (or Resources / Tools) section for external catalogs; keep in-body citations where
   the claim appears when that helps verification
 - For important external material, add archived mirrors when available
 - Do not invent citations from model memory
@@ -94,7 +94,34 @@ Dead or unstable links: replace, archive, or remove the claim. Do not leave know
 | SEAL | Acronym after first expansion when needed; acceptable in titles with `\| SEAL` |
 | Security Frameworks | This project’s suite |
 | Vault Boy–style product names | Use official capitalization (GitHub, Discord, Cloudflare) |
-| Headings | Sentence case preferred (`Signing verification`), not Title Case Every Word, unless a proper noun |
+| Headings (`#` / `##` / `###`) | **Sentence case required** (see below) |
+
+### Heading sentence case (required)
+
+All Markdown headings on framework pages use **sentence case**:
+
+1. Capitalize the first word
+2. Capitalize proper nouns, product names, and acronyms (`GitHub`, `STRIDE`, `MFA`, `Web3`)
+3. Leave every other word lowercase
+
+| Use | Avoid |
+| --- | --- |
+| `## Signing verification` | `## Signing Verification` |
+| `## Steps to create a threat model` | `## Steps to Create a Threat Model` |
+| `## What this framework covers` | `## What This Framework Covers` |
+| `## Further reading` | `## Further Reading`, `## Further Reading & Tools` |
+| `## Related frameworks` | `## Related Frameworks` |
+
+This applies to **every** heading level, including fixed catalog section names used by the content model and
+`validate:content` (page maps, further-material sections, and similar). Do not switch reserved labels to Title Case
+“because they are special.” Write them in sentence case; the validator matches those names case-insensitively so older
+Title Case headings still pass until framework PRs finish migrating.
+
+Frontmatter `title` values are a separate concern (browser tab chrome with `| Security Alliance` / `| SEAL`). They are
+not required to follow body-heading sentence case.
+
+Sidebar labels in `vocs.config.ts` should read naturally and match the page H1 topic; prefer the same words as the
+page title without truncated grammar (for example `Identify and Mitigate Threats`, not `Identity Mitigate Threats`).
 
 ## Canonical terminology
 

utils/validate-content.cjs

@@ -2,7 +2,13 @@
 /**
  * Objective content-structure checks for SEAL Security Frameworks MDX pages.
  * Structural rules: docs/pages/contribute/content-model.mdx
- * Editorial rules remain human-reviewed.
+ * Editorial rules (including heading sentence case): style-and-terminology.mdx
+ * Editorial judgment remains human-reviewed.
+ *
+ * Catalog H2 names below are matched case-insensitively so unmigrated Title Case
+ * still validates; preferred spelling is sentence case (e.g. "Further reading",
+ * "What this framework covers"). Strict Title-Case lint for freeform headings is
+ * intentionally not automated yet.
  *
  * Usage:
  *   node utils/validate-content.cjs
@@ -84,6 +90,8 @@ function hasAnyTakeaway(body) {
 }
 
 function hasPageMap(hs) {
+  // Preferred labels (sentence case): What this framework covers, Framework structure,
+  // Contents, Table of contents. "Pages" remains accepted for legacy maps.
   return hs.some(
     (h) =>
       h.level === 2 &&
@@ -94,6 +102,8 @@ function hasPageMap(hs) {
 }
 
 function hasFurther(hs) {
+  // Preferred label (sentence case): Further reading. Also: Resources, References,
+  // Related frameworks, Tools. Do not use "Further Reading & Tools".
   return hs.some(
     (h) =>
       h.level === 2 &&