chore: strengthen agent onboarding, lint pinning and CI structure

.github/workflows/gh-page.yml

@@ -1,72 +1,89 @@
-# .github/workflows/deploy.yml
-
 name: gh-page
 
-on: [push, pull_request]
+on:
+  # Branch pushes are covered by the pull_request trigger; restricting push to
+  # main keeps forks from running the whole workflow on every branch push.
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  # Superseded PR runs are worth cancelling; a deploy in flight is not.
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+permissions:
+  contents: read
 
 jobs:
 
-  markdown-lint:
-    name: Markdown Lint
+  lint:
+    name: Lint
     runs-on: ubuntu-latest
     steps:
     - name: Checkout Code
       uses: actions/checkout@v4
+    - name: Setup Node.js
+      uses: actions/setup-node@v4
       with:
-        fetch-depth: 0
-    - name: markdownlint-cli2-action
-      uses: DavidAnson/markdownlint-cli2-action@v18.0.0
-      with:
-        globs: |
-          *.md
-          docs/**/*.md
-          i18n/**/*.md
-
-  typescript-lint:
-    name: TypeScript Lint
+        node-version: '22'
+        cache: npm
+    - name: Install Dependencies
+      run: npm ci
+    - name: Markdown and TypeScript Lint
+      # Same command contributors run locally, so CI cannot disagree with them
+      # about which markdownlint version or globs apply.
+      run: npm run lint
+
+  build:
+    name: Build
+    # On main the deploy job builds the site; building twice would be waste.
+    if: github.event_name == 'pull_request'
     runs-on: ubuntu-latest
     steps:
     - name: Checkout Code
       uses: actions/checkout@v4
       with:
+        # showLastUpdateAuthor/showLastUpdateTime read git history. Without the
+        # full history every page reports the same last-updated date.
         fetch-depth: 0
     - name: Setup Node.js
       uses: actions/setup-node@v4
       with:
         node-version: '22'
+        cache: npm
     - name: Install Dependencies
-      run: npm install
-    - name: TypeScript Lint
-      run: npm run typecheck
+      run: npm ci
+    - name: Build Docusaurus site
+      run: npm run build
 
   deploy:
-    needs:
-      - markdown-lint
-      - typescript-lint
     name: Deploy to GitHub Pages
+    if: github.event_name == 'push'
+    needs:
+      - lint
     runs-on: ubuntu-latest
     permissions:
       contents: write
     concurrency:
-      group: ${{ github.workflow }}-${{ github.ref }}
+      group: deploy-gh-pages
+      cancel-in-progress: false
     steps:
-      - name: Checkout repository
-        uses: actions/checkout@v4
-
-      - name: Set up Node.js
-        uses: actions/setup-node@v4
-        with:
-            node-version: '22'
-
-      - name: Install dependencies
-        run: npm install
-
-      - name: Build Docusaurus site
-        run: npm run build
-
-      - name: Deploy to GitHub Pages
-        uses: peaceiris/actions-gh-pages@v3
-        if: ${{ github.ref == 'refs/heads/main' && github.event_name == 'push' }}
-        with:
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: ./build
+    - name: Checkout Code
+      uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+    - name: Setup Node.js
+      uses: actions/setup-node@v4
+      with:
+        node-version: '22'
+        cache: npm
+    - name: Install Dependencies
+      run: npm ci
+    - name: Build Docusaurus site
+      run: npm run build
+    - name: Deploy to GitHub Pages
+      uses: peaceiris/actions-gh-pages@v3
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: ./build