[DO NOT MERGE until #3630] Unify contributor pre-commit setup + docs (#3631)

> [!WARNING]
> **Draft — merge last.** Merge order: **#3629 → #3630 → this PR.**
> This branch is stacked on #3629, so #3629's commits appear in this
diff until it merges (then the diff collapses to this PR's three
commits). It must also land after #3630 because the docs describe the
SCSS/stylelint hook that #3630 adds.

Fixes a gap in the local contributor setup: following the documented
steps left the pre-commit **framework** checks not running locally, so
lint/secret/spell issues surfaced only in CI.

## The problem

`setup-hooks.sh` runs `git config core.hooksPath .githooks`. Once
`core.hooksPath` is set, git looks **only** there and ignores
`.git/hooks` — which is where `pre-commit install` puts its hook. So the
two documented setup steps conflict: `pre-commit install` even refuses
to run (`Cowardly refusing to install hooks with core.hooksPath set`),
and the framework checks never fired locally. `.githooks/pre-commit`
only stamped dates.

## The fix

**One hook runs everything.** `.githooks/pre-commit` now stamps content
dates (as before), then invokes `pre-commit run` on the staged files.
Contributors run a single setup — install the `pre-commit` binary and
run `./setup-hooks.sh`; no `pre-commit install`. If the binary isn't
installed, the hook stamps dates and prints a reminder rather than
failing.

Also in this PR:

- **README + contributor hook guide rewritten** for the single setup
path, with SCSS/stylelint added to the list of checks.
- **Corrected tag validation from "blocking" to advisory** in both docs
— `scripts/hooks/content_checks.py` tags mode always returns 0 (warns,
never blocks). The old guide's "commit blocked due to tag errors"
example was fiction.
- **Fixed an invalid `margin-left: 0 em`** in `.docs-content`
(`_custom.scss`) — the stray space made the declaration invalid, so the
intended zero margin never applied. (The out-of-scope item spotted
during DOCS-78.)

## Verification

- Ran real commits with `core.hooksPath=.githooks`: the hook stamps
dates **and** runs the full framework (previously it ran neither the
framework nor blocked). Confirmed the framework's per-hook table appears
and a clean tree passes.
- markdownlint (via the hook) passes on the rewritten docs.
- Empirically reproduced the original conflict: `pre-commit install`
refuses when `core.hooksPath` is set.

---
Created in collaboration with Claude Code running Opus 4.8 on
2026-07-23.

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: matthewhelmke

.githooks/pre-commit

@@ -1,16 +1,23 @@
 #!/usr/bin/env python3
-"""Git pre-commit hook: stamp date/lastmod on Hugo content files.
+"""Git pre-commit hook: stamp content dates, then run the pre-commit framework.
 
-This is kept as a native git hook (enabled via ./setup-hooks.sh) rather than a
-pre-commit-framework hook because it stamps the current time and re-stages the
-file into the same commit -- pre-commit does not auto-restage, and a "now"
-timestamp can never pass a CI idempotency check.
+This is the single local entry point for commit checks. It runs in two steps:
 
-Tag validation and spell checking now live in the pre-commit framework
-(.pre-commit-config.yaml -> scripts/hooks/content_checks.py).
+1. Stamp date/lastmod on staged Hugo content files. This stays a native hook
+   (rather than a pre-commit-framework hook) because it stamps the current time
+   and re-stages the file into the same commit -- pre-commit does not
+   auto-restage, and a "now" timestamp can never pass a CI idempotency check.
+2. Delegate to the pre-commit framework (.pre-commit-config.yaml) for linting,
+   secret scanning, tag validation, spell checking, and SCSS/stylelint.
+
+Both run from one hook on purpose. Enabling this hook sets
+core.hooksPath=.githooks (see ./setup-hooks.sh), which makes git ignore
+.git/hooks entirely -- so a separately `pre-commit install`ed hook would never
+fire. Chaining the framework from here keeps a single, conflict-free setup.
 """
 
 import re
+import shutil
 import subprocess
 import sys
 from datetime import datetime, timezone
@@ -80,6 +87,22 @@ def update_dates():
     return added, updated
 
 
+def run_framework_checks():
+    """Run the pre-commit framework on staged files (lint, secrets, tags, spell, SCSS).
+
+    Returns pre-commit's exit code so a failing check blocks the commit. If the
+    `pre-commit` binary is not installed, warn and let the commit through --
+    the same checks still run as a required check in CI.
+    """
+    if shutil.which('pre-commit') is None:
+        print("\n⚠️  'pre-commit' is not installed, so lint/secret/tag/spell/SCSS "
+              "checks did not run locally.")
+        print("   Install it so they run before you push:")
+        print("     brew install pre-commit   # or: pipx install pre-commit")
+        return 0
+    return subprocess.run(['pre-commit', 'run']).returncode
+
+
 def main():
     added, updated = update_dates()
     if added:
@@ -90,7 +113,7 @@ def main():
         print(f"📅 Updated lastmod on {len(updated)} file(s):")
         for f in updated:
             print(f"   - {f}")
-    return 0
+    return run_framework_checks()
 
 
 if __name__ == '__main__':

README.md

@@ -121,36 +121,48 @@ You can review our current list of [Tags](https://edu.chainguard.dev/tags).
 ### Pre-commit
 
 This repository uses the [pre-commit](https://pre-commit.com/) framework to check
-changes before they merge. The `pre-commit` check is **required** on pull requests,
-and it runs only on the files a PR changes (a pre-existing backlog is not gated).
-It checks:
+changes before they merge. The `pre-commit` check is **required** on pull
+requests and runs only on the files a pull request changes (a pre-existing
+backlog is not gated). Run the same checks locally to catch problems before you
+push. They cover:
 
-- Secret scanning, private keys, large files, and file hygiene (whitespace, EOF, line endings)
+- Secret scanning, private keys, large files, and file hygiene such as trailing whitespace and end-of-file newlines
 - GitHub Actions security (`zizmor`) and linting (`actionlint`)
-- JavaScript (`eslint`), Markdown (`markdownlint`), and Python (`bandit`, `black`)
-- **Content tag validation** against the approved taxonomy (blocking)
-- **Spell checking** of prose with aspell — advisory and local-only (skipped in CI)
+- JavaScript (`eslint`), Markdown (`markdownlint`), SCSS (`stylelint`), and Python (`bandit`, `black`)
+- Content tag validation against the approved taxonomy (advisory: it warns but never blocks a commit)
+- Prose spell checking with aspell (advisory and local-only; skipped in CI)
+
+**One-time setup:**
 
-**Setup (one-time):**
 ```sh
-# Install pre-commit
+# 1. Install the pre-commit framework
 brew install pre-commit        # or: pipx install pre-commit
 
-# Enable it in your clone
-pre-commit install
+# 2. Enable the repository's git hook
+./setup-hooks.sh
 
-# Optional: enable local prose spell checking
+# 3. If you edit SCSS (assets/scss/), install the Node dependencies
+npm install
+
+# 4. Optional: install aspell for local spell checking
 brew install aspell
 ```
 
-Separately, a native git hook stamps `date`/`lastmod` on content files (it
-re-stages into the same commit, so it stays a git hook rather than a pre-commit
-hook). Enable it once with:
-```sh
-./setup-hooks.sh
-```
+`setup-hooks.sh` points git at the `.githooks/` directory. On each commit, that
+hook stamps `date` and `lastmod` on changed content files, then runs the
+pre-commit framework, so one hook covers everything. You don't need to run
+`pre-commit install`: git ignores `.git/hooks` once `core.hooksPath` is set, so a
+separately installed hook wouldn't run. To skip the hook for a single commit, use
+`git commit --no-verify`.
+
+The SCSS lint step runs the project's own `stylelint`, so it needs the Node
+dependencies from `npm install`. The other hooks use pre-commit-managed
+environments, so they need nothing beyond the framework itself. If you edit
+`assets/scss/` without installing the dependencies, that one hook fails; content
+and other contributors are unaffected.
 
 **Resources:**
-- 📖 [Complete Pre-commit Hook Guide for Contributors](docs/pre-commit-hook-guide.md) - Detailed guide with examples
-- 📋 [Tag Guidelines](TAG_GUIDELINES.md) - Complete approved tag taxonomy
-- 📝 [Custom Dictionary](.aspell.en.pws) - Technical terms for spell checker
+
+- [Complete pre-commit hook guide for contributors](docs/pre-commit-hook-guide.md) — detailed guide with examples
+- [Tag guidelines](TAG_GUIDELINES.md) — the approved tag taxonomy
+- [Custom dictionary](.aspell.en.pws) — technical terms for the spell checker

assets/scss/common/_custom.scss

@@ -93,7 +93,7 @@ html[data-dark-mode] .logo-purple {
 }
 
 .docs-content {
-    margin-left: 0 em;
+    margin-left: 0;
     padding: 0;
 }
 

docs/pre-commit-hook-guide.md

@@ -2,58 +2,84 @@
 
 This guide explains the automated checks that run on your content before it merges.
 
-## Two systems
+## How local checks run
 
-Content quality is enforced by two complementary systems:
+One git hook (`.githooks/pre-commit`, enabled by `./setup-hooks.sh`) runs on
+every commit and does two things:
 
-1. **The [pre-commit](https://pre-commit.com/) framework** (`.pre-commit-config.yaml`)
-   runs on `git commit` and as a **required** CI check on pull requests. It handles
-   tag validation and spell checking (plus repo-wide security/lint hooks). In CI it
-   runs only on the files a PR changes.
-2. **A native git hook** (`.githooks/pre-commit`, enabled via `./setup-hooks.sh`)
-   stamps content dates. It stays a git hook because it re-stages the stamped file
-   into your commit, which the pre-commit framework does not do.
+1. **Stamps content dates.** It adds `date` and `lastmod` to new content files
+   and refreshes `lastmod` on edited ones, then re-stages the file into your
+   commit. This stays a native git hook because the pre-commit framework doesn't
+   re-stage files, and a "now" timestamp would never pass a CI idempotency check.
+2. **Runs the [pre-commit](https://pre-commit.com/) framework**
+   (`.pre-commit-config.yaml`) for linting, secret scanning, tag validation,
+   spell checking, and SCSS/stylelint. The same framework runs as a **required**
+   check on pull requests, where it lints only the files a pull request changes.
+
+Because `./setup-hooks.sh` sets `core.hooksPath=.githooks`, git runs this hook
+and ignores anything in `.git/hooks`. You don't run `pre-commit install`: the
+hook calls the framework for you, so one setup covers everything.
 
 ## What gets checked
 
-### 1. Automatic Date Management (git hook)
+### Content date stamping (git hook step)
+
+- **New files**: Adds `date` and `lastmod` fields with the current timestamp
+- **Modified files**: Refreshes the `lastmod` field
+- **Format**: ISO 8601 with UTC timezone, for example `2025-01-16T10:30:45+00:00`
+- You don't add or update these fields yourself
+
+### Linting and security (pre-commit framework)
+
+These fail the commit, and the required CI check, when they find a problem:
+
+- **Code and content linting**: JavaScript (`eslint`), Markdown (`markdownlint`), SCSS (`stylelint`), and Python (`bandit`, `black`)
+- **Security and hygiene**: secret scanning (`gitleaks`), private-key detection, large-file checks, and whitespace, end-of-file, and line-ending fixes
+- **GitHub Actions**: workflow security (`zizmor`) and linting (`actionlint`)
 
-- **New files**: Automatically adds `date` and `lastmod` fields with the current timestamp
-- **Modified files**: Automatically updates the `lastmod` field to reflect when changes were made
-- **Format**: Uses ISO 8601 format with UTC timezone (e.g., `2025-01-16T10:30:45+00:00`)
-- **No manual work needed**: You no longer need to add or update these fields yourself!
+Each linter reads the repository's own configuration, for example
+`.stylelintrc.json` for SCSS and `.markdownlint-cli2.jsonc` for Markdown.
 
-### 2. Tag Validation (pre-commit framework, blocking)
+The SCSS lint step runs the project's own `stylelint` from `node_modules`, so it
+needs `npm install` (see [Setting up](#setting-up)). The other linters use
+pre-commit-managed environments and need nothing more.
 
-- Ensures all tags match our approved taxonomy
-- Checks that you haven't exceeded 5 tags per article
-- Verifies proper capitalization (Title Case vs. acronyms)
+### Tag validation (pre-commit framework, advisory)
 
-### 3. Spelling (pre-commit framework, advisory + local-only)
+- Checks that tags match the approved taxonomy, stay within five per article, and use the expected capitalization
+- Reports problems as warnings but never blocks a commit
+
+### Spelling (pre-commit framework, advisory and local-only)
 
 - Catches typos and misspellings; reports but never blocks a commit
-- Runs locally only — the CI check skips it (`SKIP=content-spellcheck`)
-- Ignores code blocks (between ```), Hugo shortcodes (e.g. `{{< youtube >}}`), inline code (between `), and URLs
+- Runs locally only; the CI check skips it (`SKIP=content-spellcheck`)
+- Ignores code blocks, Hugo shortcodes (for example `{{< youtube >}}`), inline code, and URLs
 - Uses a custom dictionary for technical terms (`.aspell.en.pws`)
 
 ## Setting up
 
-### One-time setup
+Do this once per clone:
 
-1. **Install and enable pre-commit** (tags, spell check, security/lint):
+1. **Install the pre-commit framework:**
 
    ```bash
    brew install pre-commit        # or: pipx install pre-commit
-   pre-commit install
    ```
 
-2. **Enable the date-stamping git hook**:
+2. **Enable the git hook:**
 
    ```bash
    ./setup-hooks.sh
    ```
 
-3. **(Optional) Install aspell** so the local spell check runs:
+3. **Install Node dependencies if you edit SCSS** (`assets/scss/`), so the
+   stylelint hook can run:
+
+   ```bash
+   npm install
+   ```
+
+4. **Optional: install aspell** so the local spell check runs:
 
    ```bash
    # macOS
@@ -72,69 +98,51 @@ Content quality is enforced by two complementary systems:
    sudo pacman -S aspell
    ```
 
-That's it! Both run automatically when you commit.
+Every commit now stamps content dates and runs the framework checks. If you
+commit before installing the `pre-commit` framework, the hook still stamps dates
+and prints a reminder to install it.
 
-## Understanding the Output
+## Understanding the output
 
-When you run `git commit`, you'll see output like this:
+When you run `git commit`, the hook prints its date-stamp result first, then the
+pre-commit framework's per-hook results.
 
-### ✅ Success Case
+### A passing commit
 
 ```text
-🔍 Running pre-commit checks...
-
-📅 Updated lastmod dates for 1 file(s)
+📅 Updated lastmod on 1 file(s):
    - content/chainguard/chainguard-images/getting-started.md
-
-✅ All checks passed!
+trim trailing whitespace.................................................Passed
+fix end of files.........................................................Passed
+Detect hardcoded secrets.................................................Passed
+markdownlint-cli2........................................................Passed
+Validate content tags....................................................Passed
 ```
 
-### ⚠️ With Warnings
+### A blocked commit
 
-```text
-🔍 Running pre-commit checks...
+A blocking hook (a linter, a secret scan, or a file-hygiene check) prints the
+failure and stops the commit. Fix the reported issue, stage the change, and
+commit again:
 
-📅 Added date fields to 1 new file(s)
-   - content/chainguard/new-tutorial.md
+```text
+markdownlint-cli2........................................................Failed
+- hook id: markdownlint-cli2
+- exit code: 1
 
-📄 content/chainguard/getting-started.md
-   Tags: ["Chainguard Containers", "Overview", "NewTag"]
-   ⚠️  Tag not in approved list: 'NewTag'
-   📝 Spelling errors found:
-      - 'recieve' on line(s): 23
-      - 'configuation' on line(s): 45
-
-============================================================
-Pre-commit Check Summary:
-  Tag Warnings: 1
-  Tag Errors: 0
-  Files with spelling issues: 1
-
-💡 Consider reviewing TAG_GUIDELINES.md for approved tags
-
-📝 Spelling issues found. Consider:
-   - Fixing typos
-   - Adding technical terms to your personal dictionary
-   - Using 'git commit --no-verify' to skip this check
+content/chainguard/tutorial.md:14 MD012/no-multiple-blanks Multiple consecutive blank lines
 ```
 
-### ❌ With Errors (Blocks Commit)
+Some hooks fix the file for you (for example, trailing-whitespace and
+end-of-file-fixer) and then fail so you can review and re-stage the change.
 
-```text
-🔍 Running pre-commit checks...
-
-📄 content/chainguard/tutorial.md
-   Tags: ["CHAINGUARD", "TUTORIAL"]
-   ❌  Tag should use Title Case: 'CHAINGUARD'
-   ❌  Tag should use Title Case: 'TUTORIAL'
+### Advisory warnings
 
-============================================================
-Pre-commit Check Summary:
-  Tag Warnings: 0
-  Tag Errors: 2
-  Files with spelling issues: 0
+Tag and spelling checks print warnings but don't stop the commit:
 
-❌ Commit blocked due to tag errors. Please fix and try again.
+```text
+Validate content tags....................................................Passed
+   ⚠️  Tag not in approved list: 'NewTag'
 ```
 
 ## Common Scenarios
@@ -189,9 +197,9 @@ lastmod: 2025-01-16T10:45:30+00:00
 ---
 ```
 
-### Fixing Tag Errors
+### Fixing tag warnings
 
-If you see a tag error, update your frontmatter:
+If you see a tag warning, update your frontmatter so the tag matches the approved taxonomy:
 
 ```yaml
 # ❌ Wrong