Reconcile enterprise/cloud doc divergence + add bump-last-updated tooling

.github/scripts/README.md

@@ -1,5 +1,40 @@
 # GitHub Actions scripts
 
+This directory contains scripts invoked by [.pre-commit-config.yaml](../../.pre-commit-config.yaml) or by the GitHub Actions workflows under [.github/workflows/](../workflows/). See the [README's "Workflows and actions audit"](../../README.md#workflows-and-actions-audit) section for how each workflow uses these.
+
+## bump-last-updated.py
+
+Pre-commit fixer hook that bumps frontmatter `last updated:` to today's date (`YYYY-MM-DD`) on changed Markdown files. If a file has `date created:` but no `last updated:`, it inserts the field immediately after `date created:`.
+
+### Invocation
+
+Invoked automatically by [pre-commit](https://pre-commit.com/) and the [pre-commit-fix.yaml](../workflows/pre-commit-fix.yaml) CI workflow. Pre-commit passes each changed `.md` / `.mdx` file as a positional argument:
+
+```bash
+python3 .github/scripts/bump-last-updated.py path/to/file1.md path/to/file2.md
+```
+
+### Behavior
+
+- Files with `date created:` and `last updated:` → bumps `last updated:` to today, no other changes.
+- Files with `date created:` only → inserts `last updated:` after `date created:` with today's date.
+- Files without `date created:` (changelog entries, partials) → skipped.
+- Idempotent: a second run with no changes exits 0.
+
+### Exit codes
+
+- `0` — no files were modified.
+- `1` — at least one file was modified (signals pre-commit to re-stage and re-run, per the standard fixer-hook convention).
+
+### Scope
+
+Excluded by `.pre-commit-config.yaml`:
+- `platform-enterprise_versioned_docs/` — frozen release snapshots; their `last updated:` should reflect when the snapshot was cut.
+- `changelog/` — entries don't follow the `date created:` / `last updated:` convention.
+- Standard build/vendor dirs (`node_modules/`, `build/`, `dist/`, `.git/`).
+
+---
+
 ## verify-agent-findings.py
 
 Validates agent output by checking that quoted text actually exists at the claimed line numbers, preventing hallucinations from being reported.

.github/scripts/bump-last-updated.py

@@ -0,0 +1,87 @@
+#!/usr/bin/env python3
+"""Bump frontmatter `last updated:` to today on changed Markdown files.
+
+Used by the `bump-last-updated` pre-commit / prek hook. Pre-commit passes
+each changed `.md` / `.mdx` file path as a positional argument. For each:
+
+- If frontmatter has `last updated:`, set its value to today (YYYY-MM-DD).
+- If frontmatter has `date created:` but no `last updated:`, insert
+  `last updated:` immediately after `date created:` with today's date.
+- Files without a `date created:` field are skipped — they don't follow
+  the convention this hook enforces.
+
+Standard pre-commit fixer convention: exits non-zero if any file was
+modified so pre-commit re-stages and re-runs. Exits zero on a no-op.
+"""
+from __future__ import annotations
+
+import re
+import sys
+from datetime import date
+from pathlib import Path
+
+TODAY = date.today().strftime("%Y-%m-%d")
+
+FRONTMATTER_RE = re.compile(r"^---[ \t]*\n(.*?\n)---[ \t]*\n", re.DOTALL)
+LAST_UPDATED_RE = re.compile(r"^(last updated:\s*).*$", re.MULTILINE)
+DATE_CREATED_LINE_RE = re.compile(r"^date created:\s*")
+
+
+def process(path: Path) -> bool:
+    """Bump `last updated:` to today. Return True if file was modified."""
+    try:
+        content = path.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError):
+        return False
+
+    m = FRONTMATTER_RE.match(content)
+    if not m:
+        return False
+    fm = m.group(1)
+    rest = content[m.end():]
+
+    # Skip files that don't declare `date created:` — they're outside the
+    # convention this hook owns (changelog entries, partials, etc.).
+    if not any(DATE_CREATED_LINE_RE.match(line) for line in fm.splitlines()):
+        return False
+
+    if LAST_UPDATED_RE.search(fm):
+        new_fm = LAST_UPDATED_RE.sub(rf'\1"{TODAY}"', fm, count=1)
+    else:
+        # Insert `last updated:` right after the `date created:` line.
+        out = []
+        inserted = False
+        for line in fm.splitlines():
+            out.append(line)
+            if not inserted and DATE_CREATED_LINE_RE.match(line):
+                out.append(f'last updated: "{TODAY}"')
+                inserted = True
+        new_fm = "\n".join(out) + "\n"
+
+    if new_fm == fm:
+        return False
+
+    path.write_text(f"---\n{new_fm}---\n{rest}", encoding="utf-8")
+    return True
+
+
+def main(argv: list[str]) -> int:
+    modified: list[str] = []
+    for arg in argv:
+        p = Path(arg)
+        if not p.is_file() or p.suffix not in (".md", ".mdx"):
+            continue
+        if process(p):
+            modified.append(str(p))
+
+    if modified:
+        print(f"Bumped `last updated:` to {TODAY} in:")
+        for f in modified:
+            print(f"  {f}")
+        # Non-zero exit signals pre-commit to re-stage and re-run.
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

.github/workflows/pre-commit-fix.yaml

@@ -1,30 +1,52 @@
-name: Run pre-commit when requested via comment
+name: Run pre-commit on PRs or via comment
 on:
   issue_comment:
     types: [created]
+  pull_request:
+    types: [opened, synchronize, reopened]
 
 jobs:
   pre_commit_fix:
     runs-on: ubuntu-latest
-    # Only run if comment is on a PR with the main repo, and if it contains the magic keywords
+    # Run when:
+    # - An "fix formatting" comment is posted on any PR (works for fork PRs too).
+    # - A PR is opened/updated from a same-repo branch (skip forks — they have
+    #   read-only tokens that can't push; fork contributors can still trigger
+    #   the fix via the comment route above).
     if: >
-      github.event.issue.pull_request &&
-      startsWith(github.event.comment.body, 'fix formatting')
+      (github.event_name == 'issue_comment' &&
+       github.event.issue.pull_request &&
+       startsWith(github.event.comment.body, 'fix formatting'))
+      ||
+      (github.event_name == 'pull_request' &&
+       github.event.pull_request.head.repo.full_name == github.repository &&
+       github.event.pull_request.user.login != 'seqera-docs-bot')
 
     permissions:
       contents: write
       pull-requests: read
 
     steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # ratchet:actions/checkout@v6.0.2
+      - name: Checkout default ref
+        if: github.event_name == 'issue_comment'
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # ratchet:actions/checkout@v6.0.2
 
-      # Action runs on the issue comment, so we don't get the PR by default.
-      # Use the GitHub CLI to check out the PR.
-      - name: Checkout Pull Request
+      # issue_comment events don't give us the PR ref, so use gh CLI to switch.
+      - name: Checkout PR branch (comment trigger)
+        if: github.event_name == 'issue_comment'
         env:
           GH_TOKEN: ${{ github.token }}
         run: gh pr checkout ${{ github.event.issue.number }}
 
+      # pull_request events already supply head ref — use it directly so the
+      # subsequent push lands on the contributor's branch.
+      - name: Checkout PR branch (pull_request trigger)
+        if: github.event_name == 'pull_request'
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # ratchet:actions/checkout@v6.0.2
+        with:
+          ref: ${{ github.event.pull_request.head.ref }}
+          fetch-depth: 0
+
       - uses: j178/prek-action@bdca6f102f98e2b4c7029491a53dfd366469e33d # ratchet:j178/prek-action@v2.0.4
         id: pre-commit
         continue-on-error: true

.pre-commit-config.yaml

@@ -46,6 +46,24 @@ repos:
         \.git/
       )
 
+# Bump frontmatter `last updated:` to today on changed docs
+- repo: local
+  hooks:
+  - id: bump-last-updated
+    name: Bump frontmatter last updated date
+    language: python
+    entry: python3 .github/scripts/bump-last-updated.py
+    files: \.(md|mdx)$
+    exclude: |
+      (?x)^(
+        node_modules/|
+        build/|
+        dist/|
+        \.git/|
+        platform-enterprise_versioned_docs/|
+        changelog/
+      )
+
 # Standard pre-commit hooks
 - repo: https://github.com/pre-commit/pre-commit-hooks
   rev: v6.0.0

README.md

@@ -51,7 +51,14 @@ We have a script which can select a commit (or ideally release tag) to be used f
 ### Install pre-commit
 
 We use [pre-commit](https://pre-commit.com/) in our repo, which is invoked when a commit is made. When you (or Claude) are working locally and commit your changes in VS Code (or run `git commit`) the pre-commit hooks defined in the [precommit config file](./.pre-commit-config.yaml) are executed and may tweak the files you're staging.
-We currently use basic standard hooks to remove trailing whitespaces, make sure the file ends with a newline, we check yaml documents and we prevent very large files from getting committed. More hooks may get installed in the future.
+
+Current hooks:
+
+- **Standard formatting hooks** — trailing whitespace removal, end-of-file newline, YAML validity check, large-file guard.
+- **`check-netlify-excludes`** — reminds contributors which doc sections are included or excluded from deploy previews.
+- **`check-doc-tags`** — validates frontmatter `tags:` against the canonical allowlist in [.github/doc-tags-allowed.txt](.github/doc-tags-allowed.txt). Backed by [.github/scripts/check-doc-tags.py](.github/scripts/check-doc-tags.py).
+- **`bump-last-updated`** — bumps frontmatter `last updated:` to today's date on any changed `.md`/`.mdx` file. Inserts the field if the file has `date created:` but no `last updated:`. Backed by [.github/scripts/bump-last-updated.py](.github/scripts/bump-last-updated.py). Excludes `platform-enterprise_versioned_docs/` (frozen snapshots) and `changelog/` (entries don't follow the convention). If you skip the local install, [pre-commit-fix.yaml](.github/workflows/pre-commit-fix.yaml) runs the same logic in CI on every PR (same-repo only) and the bot commits the bump back.
+- **Vale** — manual-only (`pre-commit run vale --all-files`); doesn't block commits.
 
 1. Open up a Terminal window and navigate to the `docs` repository.
 2. Run the following commands to set up [pre-commit](https://github.com/pre-commit/pre-commit) hooks:
@@ -229,7 +236,7 @@ This repository ships 18 GitHub Actions workflows under [.github/workflows/](.gi
 |---|---|---|---|---|
 | No unresolved conflicts | [no-conflict-markers.yml](.github/workflows/no-conflict-markers.yml) | `pull_request` to `master` | Automatic | Active |
 | Pre-commit check | [pre-commit-check.yaml](.github/workflows/pre-commit-check.yaml) | `pull_request` | Automatic | Active |
-| Pre-commit fix | [pre-commit-fix.yaml](.github/workflows/pre-commit-fix.yaml) | PR comment `fix formatting` | Manual (comment) | Active |
+| Pre-commit fix | [pre-commit-fix.yaml](.github/workflows/pre-commit-fix.yaml) | `pull_request: opened/synchronize/reopened` (same-repo PRs only), PR comment `fix formatting` (any PR) | Automatic + manual | Active |
 | Internal link checking | [check-internal-links.yml](.github/workflows/check-internal-links.yml) | `pull_request` | Automatic | Active |
 || External link check (Links) | [links.yml](.github/workflows/links.yml) | Weekly cron (Sat 18:00 UTC), `repository_dispatch`, manual | Automatic + manual | Active |
 | markdownlint-cli2 | [markdown-lint.yml](.github/workflows/markdown-lint.yml) | `workflow_dispatch` only | Manual | Disabled (manual-only) |
@@ -251,8 +258,8 @@ This repository ships 18 GitHub Actions workflows under [.github/workflows/](.gi
 These checks gate merges; `pre-commit-fix.yaml` is an on-demand helper for fixing formatting failures.
 
 - **[no-conflict-markers.yml](.github/workflows/no-conflict-markers.yml)** — fails if any tracked file outside `.github/` contains `<<<<<<<`.
-- **[pre-commit-check.yaml](.github/workflows/pre-commit-check.yaml)** — runs the hooks defined in [.pre-commit-config.yaml](./.pre-commit-config.yaml) (whitespace, EOF newline, YAML validity, large-file guard, and the `check-doc-tags` hook backed by [.github/scripts/check-doc-tags.py](.github/scripts/check-doc-tags.py)). Paired with `pre-commit-fix.yaml` for one-click fixes.
-- **[pre-commit-fix.yaml](.github/workflows/pre-commit-fix.yaml)** — on-demand helper triggered by a PR comment starting with `fix formatting`; re-runs pre-commit, commits any changes, and pushes to the PR branch (not a required merge gate).
+- **[pre-commit-check.yaml](.github/workflows/pre-commit-check.yaml)** — runs the hooks defined in [.pre-commit-config.yaml](./.pre-commit-config.yaml) (whitespace, EOF newline, YAML validity, large-file guard, plus the `check-doc-tags` and `bump-last-updated` hooks backed by [.github/scripts/check-doc-tags.py](.github/scripts/check-doc-tags.py) and [.github/scripts/bump-last-updated.py](.github/scripts/bump-last-updated.py)). Paired with `pre-commit-fix.yaml` for one-click fixes.
+- **[pre-commit-fix.yaml](.github/workflows/pre-commit-fix.yaml)** — auto-runs on `pull_request` events from same-repo branches and on the `fix formatting` PR comment (the comment route covers fork PRs, which can't be auto-pushed to from CI). Re-runs pre-commit, commits any changes (formatting fixes, frontmatter `last updated:` bumps), and pushes to the PR branch as `Seqera Docs Bot`. Not a required merge gate, but ensures `last updated:` dates stay current even when contributors skip the local pre-commit install.
 - **[check-internal-links.yml](.github/workflows/check-internal-links.yml)** — runs `npm run build` with `FAIL_ON_BROKEN_LINKS=true`. The slowest required check; caches `.docusaurus` and `**/.cache` between runs.
 
 ### Scheduled/background jobs
@@ -315,10 +322,11 @@ Platform repo (release tag cut)
 tower-cli release
    └── check-cli-updates.yml ──► dispatch: cli-release ──► update-cli-docs.yml ──► PR
 
-PR comment `/editorial-review`  ──► docs-review.yml (gates + Vale + /editorial-review skill)
-PR comment `fix formatting`     ──► pre-commit-fix.yaml
-PR label `overlays-approved`    ──► apply-overlays-and-regenerate.yml
-@claude in comment/issue/review ──► claude.yml
+PR comment `/editorial-review`   ──► docs-review.yml (gates + Vale + /editorial-review skill)
+PR opened/synchronize (same-repo)──► pre-commit-fix.yaml (bumps last-updated, fixes formatting)
+PR comment `fix formatting`      ──► pre-commit-fix.yaml (manual route, works for fork PRs)
+PR label `overlays-approved`     ──► apply-overlays-and-regenerate.yml
+@claude in comment/issue/review  ──► claude.yml
 ```
 
 The two `repository_dispatch` content pipelines (permissions, audit events) and the API overlay pipeline are independent of each other — they share the `DOCS_BOT_APP_ID` / `DOCS_BOT_APP_PRIVATE_KEY` GitHub App credentials but otherwise don't interact.