diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml
new file mode 100644
index 0000000..af80b3d
--- /dev/null
+++ b/.github/workflows/codeql.yml
@@ -0,0 +1,54 @@
+name: "CodeQL Advanced"
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+  schedule:
+    - cron: '37 7 * * 4'
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  # Preserve completed push-to-main analyses; only supersede stale PR runs.
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  analyze:
+    name: Analyze (${{ matrix.language }})
+    runs-on: ubuntu-24.04
+    permissions:
+      # required for all workflows
+      security-events: write
+
+      # required to fetch internal or private CodeQL packs
+      packages: read
+
+      # only required for workflows in private repositories
+      actions: read
+      contents: read
+
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+        - language: actions
+          build-mode: none
+        - language: javascript-typescript
+          build-mode: none
+        - language: python
+          build-mode: none
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+    - name: Initialize CodeQL
+      uses: github/codeql-action/init@988661ebb5e81487b3fb31b2185d2856c0a10679 # v4
+      with:
+        languages: ${{ matrix.language }}
+        build-mode: ${{ matrix.build-mode }}
+
+    - name: Perform CodeQL Analysis
+      uses: github/codeql-action/analyze@988661ebb5e81487b3fb31b2185d2856c0a10679 # v4
+      with:
+        category: "/language:${{matrix.language}}"
diff --git a/docs/operations.md b/docs/operations.md
index 1def561..1b60a34 100644
--- a/docs/operations.md
+++ b/docs/operations.md
@@ -168,7 +168,7 @@ Four automated layers run against `main` (plus the opt-in ZAP scan below):
 |---|---|---|
 | `pip-audit`, `bandit` (medium+), `npm audit` (high+) | `make test-security`, so every CI run | **Yes** — any finding fails the build |
 | Snyk Code (SAST) + Snyk Open Source (SCA) | `.github/workflows/snyk-security.yml`, on push/PR to `main` | No — findings are uploaded to the GitHub **Security → Code scanning** tab for review |
-| CodeQL | GitHub *default setup* (repo Settings → Code security), weekly + on push. Note there is **no workflow file** for it — it won't show up in `.github/workflows/` | No — reports to the same Code scanning tab |
+| CodeQL | `.github/workflows/codeql.yml`, on push/PR to `main` and weekly | No — reports to the same Code scanning tab |
 | Dependabot | `.github/dependabot.yml` — pip, npm (`frontend/`, `tests/e2e/`), github-actions, docker-compose, devcontainers | No — opens PRs |
 
 Two Snyk gotchas worth knowing before you debug that workflow: