docs(queries): Query limits & performance, LCQL reference, and compiled SDK snippets

.github/workflows/deploy-pages.yml

@@ -6,20 +6,20 @@ on:
       - master
   workflow_dispatch:
 
-permissions:
-  contents: read
-  pages: write
-  id-token: write
-
 concurrency:
   group: "pages"
   cancel-in-progress: false
 
 jobs:
   build:
     runs-on: ubuntu-latest
+    timeout-minutes: 15
+    permissions:
+      contents: read
     steps:
       - uses: actions/checkout@v6
+        with:
+          persist-credentials: false
 
       - name: Set up Python
         uses: actions/setup-python@v6
@@ -55,7 +55,11 @@ jobs:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}
     runs-on: ubuntu-latest
+    timeout-minutes: 10
     needs: build
+    permissions:
+      pages: write
+      id-token: write
     steps:
       - name: Deploy to GitHub Pages
         id: deployment

.github/workflows/docs-preview.yml

@@ -0,0 +1,71 @@
+name: Docs Preview
+
+# Builds the documentation on a pull request and uploads the fully rendered
+# site as a downloadable artifact so reviewers can view the rendered pages
+# before merge.
+#
+# Security posture: build only. There is no deploy step, no secrets are used,
+# and the token is read-only, so this cannot publish anywhere or leak
+# credentials. It runs only for pull requests from branches in this repository
+# (collaborators), not from forks.
+
+on:
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build-preview:
+    name: Build rendered docs
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: '3.11'
+
+      - name: Install dependencies
+        run: |
+          pip install --upgrade pip
+          pip install -r requirements.txt
+
+      - name: Build documentation
+        run: mkdocs build --strict
+
+      # Fails the PR only on NEW ordered-list numbering breaks (an item the
+      # author numbered >1 that renders as a restarted "1." because its content
+      # is mis-indented). Pre-existing cases are recorded in the baseline and do
+      # not fail; see scripts/check-list-numbering.py for the full rationale.
+      - name: Check ordered-list numbering
+        run: python scripts/check-list-numbering.py docs site --baseline scripts/list-numbering-baseline.json
+
+      - name: Upload rendered site
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs-preview
+          path: site
+          retention-days: 1
+
+      - name: How to view the preview
+        run: |
+          {
+            echo "### Rendered docs preview"
+            echo ""
+            echo "Download the **docs-preview** artifact from this run (the Artifacts section above), unzip it, then serve it locally:"
+            echo ""
+            echo '```bash'
+            echo "cd docs-preview   # the unzipped folder"
+            echo "python -m http.server 8000"
+            echo '```'
+            echo ""
+            echo "Open <http://localhost:8000/> in your browser. Serving over HTTP (rather than opening index.html directly) makes internal links and search work correctly."
+          } >> "$GITHUB_STEP_SUMMARY"

.github/workflows/lexer-tests.yml

@@ -0,0 +1,41 @@
+name: Lexer Tests
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+  workflow_dispatch:
+
+# Minimum permissions: this workflow only reads the repository. The job token
+# has no write scope and no secrets are exposed to it.
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: LCQL lexer unit tests
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    # Run for repository events (push to master, manual dispatch) and for pull
+    # requests only when they come from a branch in this repository, never from
+    # a fork. Untrusted contributors therefore cannot trigger this job.
+    if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+        with:
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: '3.11'
+
+      - name: Install dependencies
+        run: |
+          pip install --upgrade pip
+          pip install -r requirements.txt pytest
+
+      - name: Run LCQL lexer tests
+        run: pytest tests/ -v

.github/workflows/link-checker.yml

@@ -16,17 +16,25 @@ on:
     # Run weekly on Sundays at midnight UTC
     - cron: '0 0 * * 0'
 
+# Least privilege at the workflow scope; jobs opt in to more where needed.
 permissions:
   contents: read
-  pull-requests: write
 
 jobs:
   check-links:
     runs-on: ubuntu-latest
+    timeout-minutes: 15
+    permissions:
+      contents: read
+    # Only run for pull requests from branches in this repository (collaborators),
+    # not from forks; external contributions are not accepted for this repository.
+    if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository
 
     steps:
       - name: Checkout repository
         uses: actions/checkout@v6
+        with:
+          persist-credentials: false
 
       - name: Set up Python
         uses: actions/setup-python@v6
@@ -57,7 +65,9 @@ jobs:
           restore-keys: |
             lychee-cache-
 
-      # PRs: internal links only (fast, catches broken cross-references)
+      # PRs: internal links only (fast, catches broken cross-references).
+      # Blocking (fail: true): a broken internal cross-reference is a real
+      # regression introduced by the PR, so it should fail the check.
       - name: Check internal links (PR)
         if: github.event_name == 'pull_request'
         uses: lycheeverse/lychee-action@8646ba30535128ac92d33dfc9133794bfdd9b411  # v2.8.0
@@ -69,10 +79,12 @@ jobs:
             --exclude '^https?://'
             --exclude '^mailto:'
             ./site
-          fail: false
+          fail: true
           output: ./linkcheck-results.txt
 
-      # Push/schedule/manual: full check including external links
+      # Push/schedule/manual: full check including external links.
+      # Advisory (fail: false): external sites go down or rate-limit for reasons
+      # outside our control, so a transient external failure must not block.
       - name: Check all links
         if: github.event_name != 'pull_request'
         uses: lycheeverse/lychee-action@8646ba30535128ac92d33dfc9133794bfdd9b411  # v2.8.0
@@ -94,10 +106,32 @@ jobs:
         with:
           name: linkcheck-results
           path: linkcheck-results.txt
-          retention-days: 7
+          retention-days: 1
+
+  # The comment job is split out so that pull-requests: write is granted only to
+  # the step that needs it, not to the job that builds the docs and runs lychee.
+  comment-links:
+    needs: check-links
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      contents: read
+      pull-requests: write
+    # Post the results comment even when the link check above failed, but only
+    # for pull requests from branches in this repository (not forks).
+    if: always() && github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository
+
+    steps:
+      # If check-links failed before lychee ran (e.g. mkdocs build broke), the
+      # results artifact is never created. Don't fail this job on a missing
+      # artifact; the script step below no-ops when the file is absent.
+      - name: Download link check results
+        uses: actions/download-artifact@v8
+        continue-on-error: true
+        with:
+          name: linkcheck-results
 
       - name: Comment on PR with broken links
-        if: github.event_name == 'pull_request'
         uses: actions/github-script@v8
         with:
           script: |
@@ -138,12 +172,17 @@ jobs:
 
   check-markdown:
     runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
 
     steps:
       - name: Checkout repository
         uses: actions/checkout@v6
+        with:
+          persist-credentials: false
 
       - name: Check markdown formatting
-        uses: DavidAnson/markdownlint-cli2-action@v22
+        uses: DavidAnson/markdownlint-cli2-action@07035fd053f7be764496c0f8d8f9f41f98305101  # v22
         with:
           globs: 'docs/**/*.md'

.github/workflows/publish-release-notes.yml

@@ -10,6 +10,7 @@ permissions:
 jobs:
   publish:
     runs-on: ubuntu-latest
+    timeout-minutes: 10
     steps:
       - uses: actions/checkout@v6