Merge remote-tracking branch 'origin/dev' into test-main-dev-merge-20260615

# Conflicts:
#	src/tool_implementations.py
#	static/js/research/panel.js

Author: pewdiepie-archdaemon

.dockerignore

@@ -10,6 +10,12 @@ dist/
 build/
 .env
 .env.bak.*
+# Secrets: keep plaintext and every transient secrets.env variant out of
+# the build context. If an encrypted secrets.env is used, it is mounted
+# at runtime — never baked into the image. Mirrored in .gitignore.
+secrets.env
+secrets.env.*
+!secrets.env.example
 /data/
 /logs/
 .git/

.env.example

@@ -190,3 +190,10 @@ SEARXNG_INSTANCE=http://localhost:8080
 # These overlays only expose the GPU devices. The slim Odysseus image
 # still needs CUDA/ROCm userspace via Cookbook -> Dependencies (vLLM,
 # llama-cpp-python, etc.) before models can actually serve on GPU.
+
+# ============================================================
+# Storage Paths (Docker Compose)
+# ============================================================
+
+# APP_DATA_DIR=./data
+# APP_LOGS_DIR=./logs

.github/CODEOWNERS

@@ -0,0 +1,9 @@
+# Code owners.
+#
+# Intentionally empty for now. The catch-all rule that mapped every path to a
+# single owner froze all merges the moment "Require review from Code Owners"
+# was enabled, because no other maintainer's approval could satisfy the gate.
+# A per-area ownership map (security/auth, CI, frontend, agent internals, with
+# multiple named owners per line) is being worked out in issue #593; once
+# agreed it replaces this file. Until then, required reviews and the security
+# CI gate (docs/security-ci.md) remain in force via branch protection.

.github/dependabot.yml

@@ -0,0 +1,48 @@
+# Dependabot keeps dependencies and pinned action versions current.
+#
+# Why this matters for security: every workflow in this repo pins its GitHub
+# Actions to an exact commit (a SHA), which is safe but freezes them in time.
+# Dependabot opens a small, reviewable pull request whenever a newer version
+# exists -- for Python packages, npm packages, the Docker base image, and the
+# pinned Actions themselves -- so staying patched does not require manual work.
+# Updates are grouped so a week's bumps arrive as one PR per ecosystem, not a
+# flood of separate ones.
+
+version: 2
+updates:
+  # Python dependencies (requirements.txt + requirements-optional.txt).
+  - package-ecosystem: pip
+    directory: "/"
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+    groups:
+      python:
+        patterns: ["*"]
+
+  # Frontend / tooling npm packages (package.json).
+  - package-ecosystem: npm
+    directory: "/"
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+    groups:
+      npm:
+        patterns: ["*"]
+
+  # The pinned action SHAs used across .github/workflows.
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+    groups:
+      actions:
+        patterns: ["*"]
+
+  # The Docker base image in the Dockerfile.
+  - package-ecosystem: docker
+    directory: "/"
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5

.github/pull_request_review_template.md

@@ -0,0 +1,123 @@
+# Pull Request Review Template
+
+Use this shape as a copyable reference for substantive PR reviews; GitHub does
+not auto-apply this file to review comments. Omit sections that do not add
+useful signal. Lead with confirmed findings; keep speculative notes out of the
+public review unless they are framed as a concrete open question.
+
+## Small PR Path
+
+For narrow docs, typo, test-only, or obvious local fixes, a short review is
+enough:
+
+```md
+LGTM after checking:
+- scope:
+- validation:
+- residual risk:
+```
+
+Use the fuller structure below for larger, risky, multi-finding, or
+security-sensitive reviews.
+
+## Findings
+
+**<sub><sub>![P2 Badge](https://img.shields.io/badge/P2-yellow?style=flat)</sub></sub> issue (test): Short issue title**
+
+- **Problem:** Concrete broken flow, contract, input, or risk.
+
+- **Impact:** Why this matters to users, CI, maintainers, data, security, or scale.
+
+- **Ask:** Smallest practical correction or decision the author should make.
+
+- **Location:** `path:line`
+
+## Open Questions
+
+- **question (scope, non-blocking): Short author question** Ask the concrete
+  intent, scope, or tradeoff question.
+
+## Validation
+
+- Ran:
+- Not run:
+- Residual risk:
+
+## PR Hygiene
+
+- Target/template/checks:
+- Related, duplicate, or superseding context:
+
+## No Findings Variant
+
+```md
+## Findings
+
+none confirmed
+
+## Validation
+
+- Ran:
+- Not run:
+- Residual risk:
+```
+
+## Legend
+
+- **Findings:** Verified, author-actionable issues that should be fixed or
+  consciously accepted before merge.
+- **Priority badges:** The shields.io badges below are optional formatting for
+  priority labels. Plain `P0`, `P1`, `P2`, or `P3` text is also acceptable when
+  an external image dependency is undesirable or may not render.
+  - **P0:** `![P0 Badge](https://img.shields.io/badge/P0-red?style=flat)` -
+    release-blocking or actively dangerous.
+  - **P1:** `![P1 Badge](https://img.shields.io/badge/P1-orange?style=flat)` -
+    serious bug, security risk, data-loss risk, or broken primary flow.
+  - **P2:** `![P2 Badge](https://img.shields.io/badge/P2-yellow?style=flat)` -
+    meaningful correctness, test, maintainability, or edge-case issue.
+  - **P3:** `![P3 Badge](https://img.shields.io/badge/P3-lightgrey?style=flat)` -
+    minor polish or low-risk cleanup.
+- **Intent labels:**
+  - **`issue`:** A confirmed defect, regression, broken contract, or concrete
+    risk.
+  - **`suggestion`:** A non-blocking improvement that would make the PR clearer,
+    safer, or easier to maintain.
+  - **`nit`:** A tiny, non-blocking cleanup or style note. Use it only when the
+    author can safely ignore it without changing the review outcome.
+  - **`question`:** A real author-facing clarification about intent, scope, or
+    tradeoffs. Do not use questions to hide an issue that should be stated
+    directly.
+  - **`LGTM`:** "Looks good to me." Use only when the review found no blocking
+    issues, or when any remaining notes are clearly optional.
+- **Decorations:** Optional labels in parentheses that clarify the finding type,
+  scope, or merge impact.
+  - **`security`:** Auth, authorization, ownership, secrets, SSRF, injection,
+    unsafe external input, or other trust-boundary concerns.
+  - **`test`:** Missing, failing, misleading, brittle, or insufficient tests.
+  - **`scope`:** PR scope, feature boundaries, unrelated churn, or work that
+    should be split into a separate issue or PR.
+  - **`ci`:** CI configuration, workflow failures, flaky checks, or validation
+    signal quality.
+  - **`api`:** Route, request/response, public function, schema, persistence, or
+    integration contract changes.
+  - **`docs`:** User-facing docs, contributor docs, examples, or comments that
+    need to change with the code.
+  - **`non-blocking`:** Useful feedback that should not prevent merge by
+    itself.
+- **Finding fields:**
+  - **Problem:** What is wrong, what contract is ambiguous, or what risk the PR
+    introduces.
+  - **Impact:** Why the problem matters in practical terms.
+  - **Ask:** The smallest concrete fix, test, or decision requested from the PR
+    author.
+  - **Location:** The most useful repo-relative file and line reference for the
+    finding, using `path:line`.
+- **Optional sections:**
+  - **Open Questions:** Genuine scope or intent questions; omit when there are
+    no real questions.
+  - **Validation:** What the reviewer ran, what was intentionally not run, and
+    what risk remains after review.
+  - **PR Hygiene:** Target-branch, template, CI/check, duplicate, related-work,
+    or superseding-PR notes.
+- **`none confirmed`:** Use only when no review-worthy findings were confirmed;
+  still list validation gaps or residual risk when relevant.

.github/workflows/ci.yml

@@ -19,10 +19,10 @@ jobs:
     name: Python syntax (compileall)
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10  # v6.0.3
         with:
           persist-credentials: false
-      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065  # v5
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
         with:
           python-version: "3.11"
       # Byte-compile sources — catches syntax errors without installing deps.
@@ -32,10 +32,10 @@ jobs:
     name: JS syntax (node --check)
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10  # v6.0.3
         with:
           persist-credentials: false
-      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020  # v4
+      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e  # v6.4.0
         with:
           node-version: "20"
       # Syntax-check our own JS (skip vendored libs in static/lib).
@@ -54,7 +54,7 @@ jobs:
     # ROADMAP "fresh install smoke tests" item; make this required once green.
     continue-on-error: true
     steps:
-      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10  # v6.0.3
         with:
           fetch-depth: 0
           persist-credentials: false
@@ -81,7 +81,7 @@ jobs:
             echo "docs_only=false" >> "$GITHUB_OUTPUT"
           fi
 
-      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065  # v5
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
         if: steps.docs-check.outputs.docs_only != 'true'
         with:
           python-version: "3.11"

.github/workflows/codeql.yml

@@ -0,0 +1,61 @@
+# CodeQL code scanning
+#
+# Purpose: GitHub's own static analysis engine reads the application source
+# (Python backend + the JavaScript frontend) and looks for real
+# vulnerabilities -- SQL/command injection, path traversal, auth mistakes,
+# unsafe deserialization. Findings appear in the repo's Security tab. This is
+# the deepest check in the suite and the most valuable for a high-profile
+# target.
+#
+# It runs on every push to main and on a weekly schedule (to catch newly
+# disclosed query patterns against unchanged code). It deliberately does NOT
+# run on pull requests: most PRs here come from forks, whose read-only token
+# cannot publish results, which would produce confusing failures. To scan pull
+# requests too, a maintainer can instead enable CodeQL "default setup" in
+# Settings -> Security -> Code scanning (one toggle, no file needed) -- see
+# docs/security-ci.md.
+
+name: CodeQL
+
+on:
+  push:
+    branches: [main]
+  schedule:
+    # Weekly, Monday 06:00 UTC.
+    - cron: '0 6 * * 1'
+  workflow_dispatch:
+
+permissions: {}
+
+concurrency:
+  group: codeql-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  analyze:
+    name: Analyze (${{ matrix.language }})
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      security-events: write  # publish results to the Security tab
+    strategy:
+      fail-fast: false
+      matrix:
+        # Both are interpreted, so CodeQL needs no build step (build-mode none).
+        language: [python, javascript-typescript]
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10  # v6.0.3
+        with:
+          persist-credentials: false
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@8aad20d150bbac5944a9f9d289da16a4b0d87c1e  # v4.36.2
+        with:
+          languages: ${{ matrix.language }}
+          build-mode: none
+
+      - name: Perform CodeQL analysis
+        uses: github/codeql-action/analyze@8aad20d150bbac5944a9f9d289da16a4b0d87c1e  # v4.36.2
+        with:
+          category: "/language:${{ matrix.language }}"

.github/workflows/container-scan.yml

@@ -0,0 +1,52 @@
+# Container security: Dockerfile lint
+#
+# Purpose: the Docker image is how most people run Odysseus, so it is part of
+# the attack surface. hadolint lints the Dockerfile for mistakes and insecure
+# patterns (running as root longer than needed, unpinned base image, bad apt
+# usage). Blocking.
+#
+# The image vulnerability scan (Trivy, advisory) lives in its own file,
+# container-trivy.yml. Keeping it separate lets that advisory scan be
+# path-filtered and held to a read-only token on pull requests without
+# weakening this blocking gate, which must always report so a required check
+# never hangs.
+#
+# Note: a separate open PR (#120) proposes a local `scripts/scan_image.py`.
+# This job is complementary -- it is a CI gate, not a script a contributor has
+# to remember to run.
+
+name: Container scan
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions: {}
+
+concurrency:
+  group: container-scan-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  hadolint:
+    name: hadolint (Dockerfile lint)
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10  # v6.0.3
+        with:
+          persist-credentials: false
+
+      - name: Lint Dockerfile
+        uses: hadolint/hadolint-action@2332a7b74a6de0dda2e2221d575162eba76ba5e5  # v3.3.0
+        with:
+          dockerfile: Dockerfile
+          # DL3008: pinning apt package versions is impractical on a -slim base
+          # image. Debian purges old package versions from its repos, so a
+          # pinned version breaks future rebuilds. The base image itself is
+          # what should be pinned (tracked by Dependabot's docker ecosystem).
+          ignore: DL3008