docs: replace detailed roadmap with directional overview

.env.example

@@ -189,7 +189,6 @@ SEARXNG_INSTANCE=http://localhost:8080
 # ODYSSEUS_EMAIL_COMPOSE_UPLOAD_MAX_BYTES=26214400       # email compose attachment (25 MB)
 # ODYSSEUS_STT_MAX_AUDIO_BYTES=26214400                  # speech-to-text audio (25 MB)
 # ODYSSEUS_ICS_MAX_BYTES=10485760                        # calendar .ics import (10 MB)
-# ODYSSEUS_TTS_CACHE_MAX_BYTES=524288000                 # TTS cache (500 MB)
 
 # ============================================================
 # Host Docker access (explicit opt-in)

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -8,8 +8,8 @@ body:
       value: |
         **Before submitting:** search [open issues](https://github.com/odysseus-dev/odysseus/issues)
         and [discussions](https://github.com/odysseus-dev/odysseus/discussions) first.
-        Feature requests that duplicate [ROADMAP.md](https://github.com/odysseus-dev/odysseus/blob/main/ROADMAP.md)
+        The [roadmap](https://github.com/odysseus-dev/odysseus/blob/main/ROADMAP.md) is directional rather than a complete backlog.
-        or an existing open issue will be closed as duplicates.
+        Feature requests that duplicate an existing issue or accepted proposal may be closed as duplicates.
 
         If your idea needs community input before it becomes a concrete proposal,
         start a [discussion](https://github.com/odysseus-dev/odysseus/discussions/categories/ideas) instead.

.github/scripts/check-issue-description.js

@@ -153,16 +153,6 @@ module.exports = async ({ github, context, core }) => {
     }
   }
 
-  const LABEL_BAD  = 'needs more info';
-  const LABEL_GOOD = 'ready for review';
-
-  // Closed issues are no longer awaiting review.
-  // This also prevents later edits to closed issues from restoring the label.
-  if (issue.state === 'closed') {
-    await dropLabel(LABEL_GOOD);
-    return;
-  }
-
   // ── Find existing bot comment to update in-place ──────────────────────────
   const MARKER = '<!-- issue-description-check -->';
   const { data: comments } = await github.rest.issues.listComments({
@@ -170,6 +160,9 @@ module.exports = async ({ github, context, core }) => {
   });
   const existing = comments.find(c => c.user.type === 'Bot' && c.body.includes(MARKER));
 
+  const LABEL_BAD  = 'needs more info';
+  const LABEL_GOOD = 'ready for review';
+
   if (failures.length === 0) {
     if (existing) {
       await github.rest.issues.deleteComment({ owner, repo, comment_id: existing.id });

.github/workflows/ci.yml

@@ -21,7 +21,7 @@ jobs:
     runs-on: ubuntu-latest
     continue-on-error: true
     steps:
-      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
         with:
           fetch-depth: 0
           persist-credentials: false
@@ -73,10 +73,10 @@ jobs:
     name: Python syntax (compileall)
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
         with:
           persist-credentials: false
-      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
         with:
           python-version: "3.11"
       # Byte-compile sources — catches syntax errors without installing deps.
@@ -86,10 +86,10 @@ jobs:
     name: JS syntax (node --check)
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
         with:
           persist-credentials: false
-      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020  # v7.0.0
+      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e  # v6.4.0
         with:
           node-version: "20"
       # Syntax-check our own JS (skip vendored libs in static/lib).
@@ -108,7 +108,7 @@ jobs:
     # ROADMAP "fresh install smoke tests" item; make this required once green.
     continue-on-error: true
     steps:
-      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
         with:
           fetch-depth: 0
           persist-credentials: false
@@ -135,7 +135,7 @@ jobs:
             echo "docs_only=false" >> "$GITHUB_OUTPUT"
           fi
 
-      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
+      - 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

@@ -27,15 +27,15 @@ jobs:
         language: [actions, javascript-typescript, python]
     steps:
       - name: Checkout
-        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
         with:
           persist-credentials: false
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@f205ea1c3313d32999d8d6a48b4f6530d4437b38  # v4.37.4
+        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@f205ea1c3313d32999d8d6a48b4f6530d4437b38  # v4.37.4
+        uses: github/codeql-action/analyze@8aad20d150bbac5944a9f9d289da16a4b0d87c1e  # v4.36.2
         with:
           category: "/language:${{ matrix.language }}"

.github/workflows/container-scan.yml

@@ -37,12 +37,12 @@ jobs:
       contents: read
     steps:
       - name: Checkout repository
-        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
         with:
           persist-credentials: false
 
       - name: Lint Dockerfile
-        uses: hadolint/hadolint-action@2a66e89f53d0771bb131a7fa31f3136336094aa6  # v3.4.0
+        uses: hadolint/hadolint-action@2332a7b74a6de0dda2e2221d575162eba76ba5e5  # v3.3.0
         with:
           dockerfile: Dockerfile
           # DL3008: pinning apt package versions is impractical on a -slim base

.github/workflows/container-trivy.yml

@@ -52,17 +52,17 @@ jobs:
       contents: read
     steps:
       - name: Checkout repository
-        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
         with:
           persist-credentials: false
 
       - name: Set up Buildx
-        uses: docker/setup-buildx-action@bb05f3f5519dd87d3ba754cc423b652a5edd6d2c  # v4.2.0
+        uses: docker/setup-buildx-action@d7f5e7f509e45cec5c76c4d5afdd7de93d0b3df5  # v4.1.0
 
       # Build without pushing so a broken Dockerfile is caught here, and the
       # exact image we ship is what gets scanned.
       - name: Build image
-        uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a  # v7.3.0
+        uses: docker/build-push-action@f9f3042f7e2789586610d6e8b85c8f03e5195baf  # v7.2.0
         with:
           context: .
           push: false
@@ -93,15 +93,15 @@ jobs:
       security-events: write  # upload SARIF to the Security tab
     steps:
       - name: Checkout repository
-        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
         with:
           persist-credentials: false
 
       - name: Set up Buildx
-        uses: docker/setup-buildx-action@bb05f3f5519dd87d3ba754cc423b652a5edd6d2c  # v4.2.0
+        uses: docker/setup-buildx-action@d7f5e7f509e45cec5c76c4d5afdd7de93d0b3df5  # v4.1.0
 
       - name: Build image
-        uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a  # v7.3.0
+        uses: docker/build-push-action@f9f3042f7e2789586610d6e8b85c8f03e5195baf  # v7.2.0
         with:
           context: .
           push: false
@@ -119,7 +119,7 @@ jobs:
           TRIVY_DB_REPOSITORY: ghcr.io/aquasecurity/trivy-db:2
 
       - name: Upload Trivy results
-        uses: github/codeql-action/upload-sarif@f205ea1c3313d32999d8d6a48b4f6530d4437b38  # v4.37.4
+        uses: github/codeql-action/upload-sarif@8aad20d150bbac5944a9f9d289da16a4b0d87c1e  # v4.36.2
         with:
           sarif_file: trivy-results.sarif
           category: trivy-image

.github/workflows/dependency-review.yml

@@ -36,7 +36,7 @@ jobs:
       contents: read
     steps:
       - name: Checkout repository
-        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
         with:
           persist-credentials: false
 
@@ -55,12 +55,12 @@ jobs:
       contents: read
     steps:
       - name: Checkout repository
-        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
         with:
           persist-credentials: false
 
       - name: Set up Python
-        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
         with:
           python-version: '3.12'
 

.github/workflows/docker-publish.yml

@@ -45,20 +45,20 @@ jobs:
             arch: arm64
             runner: ubuntu-24.04-arm
     steps:
-      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
         with:
           persist-credentials: false
       - name: Set up Buildx
-        uses: docker/setup-buildx-action@bb05f3f5519dd87d3ba754cc423b652a5edd6d2c  # v4.2.0
+        uses: docker/setup-buildx-action@d7f5e7f509e45cec5c76c4d5afdd7de93d0b3df5  # v4.1.0
       - name: Log in to GHCR
-        uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f  # v4.6.0
+        uses: docker/login-action@650006c6eb7dba73a995cc03b0b2d7f5ca915bee  # v4.2.0
         with:
           registry: ${{ env.REGISTRY }}
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
       - name: Build and push by digest
         id: build
-        uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a  # v7.3.0
+        uses: docker/build-push-action@f9f3042f7e2789586610d6e8b85c8f03e5195baf  # v7.2.0
         with:
           context: .
           platforms: ${{ matrix.platform }}
@@ -86,7 +86,7 @@ jobs:
       contents: read
       packages: write
     steps:
-      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
         with:
           persist-credentials: false
       - name: Read APP_VERSION + short sha
@@ -103,16 +103,16 @@ jobs:
           pattern: digest-*
           merge-multiple: true
       - name: Set up Buildx
-        uses: docker/setup-buildx-action@bb05f3f5519dd87d3ba754cc423b652a5edd6d2c  # v4.2.0
+        uses: docker/setup-buildx-action@d7f5e7f509e45cec5c76c4d5afdd7de93d0b3df5  # v4.1.0
       - name: Log in to GHCR
-        uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f  # v4.6.0
+        uses: docker/login-action@650006c6eb7dba73a995cc03b0b2d7f5ca915bee  # v4.2.0
         with:
           registry: ${{ env.REGISTRY }}
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
       - name: Compute tags
         id: meta
-        uses: docker/metadata-action@dc802804100637a589fabce1cb79ff13a1411302  # v6.2.0
+        uses: docker/metadata-action@80c7e94dd9b9319bd5eb7a0e0fe9291e23a2a2e9  # v6.1.0
         with:
           images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
           tags: |

.github/workflows/issue-description-check.yml

@@ -2,7 +2,7 @@ name: ci / issue description check
 
 on:
   issues:
-    types: [opened, edited, reopened, closed]
+    types: [opened, edited, reopened]
 
 permissions:
   issues: write
@@ -14,7 +14,7 @@ jobs:
     # Skip bots (Dependabot, release-drafter, etc.)
     if: ${{ github.event.issue.user.type != 'Bot' }}
     steps:
-      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
         with:
           sparse-checkout: .github/scripts
           persist-credentials: false

.github/workflows/pr-description-check.yml

@@ -23,7 +23,7 @@ jobs:
     # Skip bots: they open PRs programmatically and have their own process.
     if: github.event.pull_request.user.type != 'Bot'
     steps:
-      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
         with:
           ref: ${{ github.base_ref }}
           sparse-checkout: .github/scripts

.github/workflows/secret-scan.yml

@@ -35,7 +35,7 @@ jobs:
       contents: read
     steps:
       - name: Checkout repository
-        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
         with:
           # Full history so a secret committed in an earlier commit (and later
           # deleted) is still caught -- deletion does not remove it from Git.

.github/workflows/workflow-security.yml

@@ -36,7 +36,7 @@ jobs:
       contents: read
     steps:
       - name: Checkout repository
-        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
         with:
           persist-credentials: false
 
@@ -61,12 +61,12 @@ jobs:
       contents: read
     steps:
       - name: Checkout repository
-        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
         with:
           persist-credentials: false
 
       - name: Set up Python
-        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97  # v7.0.0
+        uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
         with:
           python-version: '3.12'
 

README.md

@@ -55,7 +55,7 @@ A full hover-to-play tour lives on the landing page: [`docs/index.html`](docs/in
 
 ## Contributing
 
-Help is welcome. The best entry points are fresh-install testing, provider setup bugs, mobile/editor polish, docs, and small focused refactors. See [CONTRIBUTING.md](CONTRIBUTING.md) and [ROADMAP.md](ROADMAP.md).
+Help is welcome. The best entry points are fresh-install testing, provider setup bugs, mobile/editor polish, documentation, and small focused refactors. See [CONTRIBUTING.md](CONTRIBUTING.md), the [public roadmap](ROADMAP.md), and the open [GitHub issues](https://github.com/odysseus-dev/odysseus/issues).
 
 ## Security
 

ROADMAP.md

@@ -1,87 +1,55 @@
-# Roadmap / Help Wanted
+# Roadmap
 
-Odysseus is on a voyage, but not home yet. It works great for me (lol), but this ship is moving fast and feedback/help would be appreciated! (I don't know what I'm doing, help).
+This document provides a high-level view of the areas Odysseus is currently improving.
 
-If you see weird CSS, strange layout behavior, or a suspiciously murky corner of
+It is directional rather than exhaustive. Priorities may change as the project evolves, defects are discovered, and maintainers learn more from implementation work and user feedback.
-the codebase, you are probably right to stay away.
 
-## High Priority
+For current implementation work, see the open [GitHub issues](https://github.com/odysseus-dev/odysseus/issues). Accepted behaviour should be documented in the repository alongside the code.
 
-- SQUASH BUGS
+## Current priorities
-- Fresh install smoke tests on Linux, macOS, and Windows. Docker, native Python,
-  and WSL all need coverage.
 
-- Integration audit: do integrations even work? Confirm what works, what needs setup docs, and what should be removed or hidden. 
+### Reliability and setup
-- Cookbook reliability on other computers. This is probably the area most likely to need work across different machines, GPUs, drivers, shells, and Python environments.
-- Cookbook SGLang support across platforms. Make sure SGLang setup/serve works
-  predictably on Linux, Windows/WSL, macOS where possible, Docker, and common
-  NVIDIA/AMD hardware paths.
-- Deep Research model presets by hardware. Recommend approved model/parameter
-  profiles for small, medium, and large local setups so people with different
-  hardware can use Deep Research without guessing. Surface this either in Deep
-  Research settings or as a Cookbook scan/dropdown suggestion.
-- Cookbook model scan/download ranking. Prioritize newer architectures and
-  better hardware-fit models instead of scoring everything almost the same.
-  Ranking should account for architecture age, quant format, VRAM/RAM fit,
-  backend support, vision/mmproj requirements, and likely serve reliability.
-- Cookbook error feedback and logging. Failed downloads, dependency installs,
-  preflights, and serve jobs should show the actual command/output/error in the
-  UI, with copyable logs and clear next steps instead of just "crashed".
-- Agent prompt/context bloat. Agent mode is too heavy for smaller local models:
-  tool schemas, skills, memory, documents, and instructions can eat the context
-  before the user request really starts. We need slimmer prompts, better tool
-  selection, smaller default tool sets, and clearer guidance for models with
-  4k/8k/16k context windows.
-- Local model speculative decoding support. For Odysseus-tuned local models,
-  plan to ship or recommend a small same-tokenizer draft model when the serving
-  backend supports it. Early vLLM testing showed a generic `Qwen3-0.6B` draft
-  beside `Qwen3-8B` can materially reduce wall time, while an unsupported
-  DSpark conversion performed poorly. Treat this as a supported draft-model lane
-  first; keep MTP-specific packaging as future work only when the architecture
-  and runtime support are real. Judge this by time-to-success, tool correctness,
-  grammar, and unchanged target output, not tokens/sec alone.
-- Skill/tool prompt-injection audit. User-editable skills, notes, documents,
-  fetched pages, and memories should be treated as untrusted data. Keep testing
-  whether models follow malicious instructions from those surfaces.
-- Better degraded-state reporting for ChromaDB, SearXNG, email, ntfy, and provider probes.
-- Email performance audit. Fetching, searching, opening, deleting, and sending
-  email can feel slow, especially over IMAP/SMTP providers with high latency.
-  Need someone who knows mail performance to profile the current flow, identify
-  whether the bottleneck is IMAP folder select/fetch, cache invalidation,
-  attachment/body loading, SMTP handshakes, or frontend refresh behavior, then
-  propose safer caching/prefetch/batching without breaking multi-account state.
-- Provider setup/probing audit for Anthropic, Gemini, Groq, xAI, OpenRouter, OpenAI, and DeepSeek.
 
-## Refactor Targets
+- Improve fresh-install and smoke-test coverage across supported environments.
-- CSS cleanup. `static/style.css` basically Calypso's island atm.
+- Make provider setup, probing, and failure states more predictable.
-- Tour core helper. The onboarding tours have too much copy-pasted scaffolding; promote a shared `tour-core.js` helper before adding more tours.
+- Improve Cookbook reliability across hardware, operating systems, drivers, shells, and serving backends.
-- Modal/window positioning cleanup. Some window controls have improved, but the
+- Improve degraded-state reporting and recovery guidance when optional services are unavailable.
-  underlying popup/dropdown/fixed-position behavior is still too fragile.
-- Mobile media override discoverability. A lot of "CSS did not move" bugs are mobile `@media` overrides of the same selector; comments or linting around desktop/mobile paired rules would help.
-- Dead code pass for old routes, stale feature flags, and unused UI states.
 
-## Frontend
+### Local model workflows
 
-- Expand the Editor for quicker, more robust everyday use. Better file/document
+- Improve hardware-aware model recommendations and compatibility guidance.
-  handling, smoother window behavior, clearer save/export flows, stronger image
+- Evaluate serving optimizations, including speculative decoding, through reproducible benchmarks.
-  editing affordances, and fewer brittle edge cases.
+- Improve installation, preflight checks, logging, and error reporting for local model serving.
-- Better AI integration for Notes and Todos. Notes should be easier for the
+- Reduce prompt and context overhead for smaller local models.
-  agent to read, update, summarize, and turn into actions. Todos should be
-  assignable to an agent from the UI, possibly through a button, task action,
-  or dedicated skill/tool flow.
-- Mobile gallery/editor polish. Easier to launch/download inpaint model or any missing pieces.
-- Accessibility pass: keyboard navigation, focus states, contrast, reduced motion.
-- Improve empty states and error messages on fresh installs.
-- Tighten first-run setup, hints, and tours so they do not repeat or fight each other.
-- Vendor CDN assets eventually for a more fully self-hosted/offline mode.
 
-## Backend
+### Safety and resilience
 
-- More tests around endpoint probing and provider setup.
+- Continue hardening tool execution, filesystem access, credentials, networking, and destructive operations.
-- Better task scheduler defaults and visibility.
+- Treat content from documents, notes, memories, skills, and fetched pages as potentially untrusted.
-- Backup/restore guide and helper flow for `data/`.
+- Improve security-focused regression coverage and operational guidance.
-- Security hardening around admin-only tools and clear docs for their risk.
+- Review integrations that expand access to sensitive data or privileged operations.
 
-## Not The Focus Right Now
+### Product usability
 
-I prob shouldnt add more themes.
+- Improve first-run setup, onboarding, hints, and tours.
+- Improve accessibility, keyboard navigation, focus behaviour, contrast, and reduced-motion support.
+- Improve empty states, error messages, and recovery paths.
+- Strengthen Notes, Todos, Editor, mobile, and everyday workspace flows.
+
+### Architecture and maintainability
+
+- Reduce duplication and technical debt through focused, reviewable refactors.
+- Improve subsystem documentation as behaviour and architecture become stable.
+- Remove stale code, obsolete feature flags, and unsupported integrations.
+- Keep implementation decisions grounded in current code and verified behaviour.
+
+## Tracking work
+
+Concrete implementation tasks, defects, proposals, and technical investigations are tracked in:
+
+- [GitHub Issues](https://github.com/odysseus-dev/odysseus/issues)
+- [Contributing Guide](CONTRIBUTING.md)
+
+Maintainers may use additional private coordination tools for ownership, planning, and unresolved decisions.
+
+This roadmap is not a complete backlog or a guarantee that a particular item will be delivered.

THREAT_MODEL.md

@@ -68,14 +68,14 @@ External content that reaches the LLM is treated as untrusted via `src/prompt_se
 - `X-Content-Type-Options: nosniff` and `Referrer-Policy: no-referrer` everywhere.
 - **CSP:** nonce-based `script-src 'self' 'nonce-{nonce}' https://cdn.jsdelivr.net`. `style-src 'unsafe-inline'` is intentionally kept — `static/index.html` ships inline `<style>` blocks and JS modules set `style=""` attributes at runtime. Inline styles do not execute script so the risk is visual-only. Removing this requires templating the HTML files and auditing all JS-set style attributes.
 
+## Token-Supplied Model Endpoints
+
+Direct `/api/v1/chat` requests with a token-supplied `base_url` must use a public HTTP(S) endpoint. This restriction applies only to untrusted direct values; administrator-configured endpoints may intentionally use local or LAN URLs for private model providers.
+
 ## Known Gaps
 
 These are open, acknowledged, and contributor help is welcome:
 
 1. **No shell/filesystem sandbox.** The agent `bash` and `read_file`/`write_file` tools run as the app process user with no network egress filtering or filesystem confinement. A successful prompt-injection reaching a shell-enabled admin session can make outbound requests to internal services. See #1058 for the sandbox proposal.
 
-2. **SSRF via `/api/v1/chat` `base_url` parameter.** A chat-scoped API token can supply an arbitrary `base_url`; the server forwards the LLM request to that host without validating the scheme or address. PR #1039 fixes this.
+2. **Token scopes are coarse.** There is no way to grant a session a subset of the owning user's privileges. Companion/mobile tokens carry either `chat` or `admin` scope with no per-capability granularity.
-
-3. **`src/search/` partial consolidation.** `src.search.core` and `src.search.providers` correctly alias `services.search` via `sys.modules` replacement. `analytics`, `cache`, `content`, `query`, and `ranking` are still independent copies that can drift. The SSRF regression tests in `tests/test_webhook_ssrf_resilience.py` test `src.webhook_manager` directly (separate from search), so the safety net there is intact. See #1058.
-
-4. **Token scopes are coarse.** There is no way to grant a session a subset of the owning user's privileges. Companion/mobile tokens carry either `chat` or `admin` scope with no per-capability granularity.

app.py

@@ -692,7 +692,7 @@ from routes.history.history_routes import setup_history_routes
 app.include_router(setup_history_routes(session_manager, upload_handler=upload_handler))
 
 # Search
-from routes.search.search_routes import setup_search_routes
+from routes.search_routes import setup_search_routes
 app.include_router(setup_search_routes(config))
 
 # Presets

discovery/README.md

@@ -0,0 +1,34 @@
+# Odysseus discovery maps
+
+Compact, code-grounded discovery maps of cross-cutting systems in the checked-in Odysseus codebase. They preserve investigation context and open factual questions; they are not canonical subsystem specifications, a feature certification, or a substitute for normal testing.
+
+> [!IMPORTANT]
+> Checked-in code is the source of truth for current behaviour. Mature subsystem specifications, where they exist, are the canonical documentation of accepted subsystem behaviour. Check code, tests, and configuration before reconciling a discovery finding. Discovery remains non-canonical.
+
+## Explore the maps
+
+| Document | Purpose |
+|---|---|
+| [Current system map](system-map.md) | Records evidence locations, confirmed local observations, and factual open questions about subsystem boundaries. |
+| [Safety boundaries](safety-boundaries.md) | Records evidence about broad authority, safeguards, confirmed risks or gaps, and unverified behaviour. |
+
+## Working rules
+
+- **Trace the code first.** Confirm the current path in source before recording a claim.
+- **Promote selectively.** When an owning mature specification exists, add a fact only when it is verified, useful, and not already represented there.
+- **Record missing ownership.** When no owning specification exists, retain the verified finding in discovery and record missing documentation ownership as a follow-up.
+- **Retain uncertainty here.** Keep unresolved questions and useful investigation context in discovery rather than treating them as canonical truth.
+- **Keep specifications current-state only.** Do not record intentions, design direction, refactor plans, decision history, priority, ownership, or sequencing here.
+- **Investigate with cause.** Do not exhaustively revalidate existing functionality without a report, visible failure, relevant change, or high-authority review need.
+- **Review authority carefully.** Give execution, data access, external tools, credentials, destructive operations, and unattended work focused review.
+- **Use stable locations.** Cite modules, routes, classes, and functions instead of fragile line ranges or generated evidence tables.
+
+## Reconciliation flow
+
+1. Start with the relevant map and trace the cited code.
+2. Classify the finding against current source evidence and an owning mature specification where one exists.
+3. Promote only verified, useful facts that are missing from an existing owning specification.
+4. When no owning specification exists, retain the verified finding here and record missing documentation ownership as a follow-up; otherwise retain unresolved context here and correct stale wording.
+
+> [!NOTE]
+> This package intentionally contains no generator, validator, maturity scale, feature database, or parallel work tracker. The [architecture runtime inventory](../specs/architecture-runtime-inventory.md) remains useful structural context, but is an explicitly draft snapshot.

discovery/safety-boundaries.md

@@ -0,0 +1,142 @@
+# Safety boundaries
+
+> [!IMPORTANT]
+> This non-canonical discovery map records code-grounded safeguards, confirmed risks or gaps, and unverified behaviour. Broad authority does not by itself establish a vulnerability. Verify the cited source before relying on a finding. No destructive test, external connection, or real credential was used for this map.
+
+## Navigate the boundaries
+
+- [Shell and subprocess execution](#shell-and-subprocess-execution)
+- [Filesystem access and workspace confinement](#filesystem-access-and-workspace-confinement)
+- [Agent-controlled tool dispatch](#agent-controlled-tool-dispatch)
+- [MCP and external tool servers](#mcp-and-external-tool-servers)
+- [Outbound network requests and URL validation](#outbound-network-requests-and-url-validation)
+- [Secrets, credentials, and vault sessions](#secrets-credentials-and-vault-sessions)
+- [Authentication and privileged administration](#authentication-and-privileged-administration)
+- [Deletion, wipe, backup, and restore](#deletion-wipe-backup-and-restore)
+- [Background jobs and unattended task execution](#background-jobs-and-unattended-task-execution)
+
+## Shell and subprocess execution
+
+- **Boundary:** Shell routes, agent `bash` and `python` tools, local model serving, and detached background jobs.
+
+- **Available authority:** Commands run as the application process user and can create child processes.
+
+- **User-controlled inputs:** Direct shell requests, model-produced tool arguments, scheduled-task prompts, and model-serving configuration.
+
+- **Current safeguards:** Agent dispatch applies owner/admin checks and tool policy; process helpers use timeouts or bounded background-job lifecycle where implemented.
+
+- **Confirmed risks or gaps:** Intentional authority with a confirmed gap: the agent shell starts in its workspace but is not sandboxed to it, and has no egress sandbox. This is documented in source and the threat model; it is not a newly demonstrated bypass.
+
+- **Unverified behaviour:** Role-gate and disabled-tool outcomes, direct shell-route behaviour, and timeout, cancellation, and output handling for foreground and detached processes remain unverified.
+
+## Filesystem access and workspace confinement
+
+- **Boundary:** Agent read, write, patch, listing, glob, and grep tools.
+
+- **Available authority:** Read and modify files within active workspace confinement or fallback allowlisted roots.
+
+- **User-controlled inputs:** Tool paths, patches, file contents, search patterns, and workspace selection passed into the tool dispatcher.
+
+- **Current safeguards:** [`src/tool_execution.py`](../src/tool_execution.py) resolves paths, blocks sensitive subpaths, applies allowlist containment, and tightens paths to the active workspace when one is bound. File tools use those resolvers.
+
+- **Confirmed risks or gaps:** Intentional authority with safeguards. The file-tool policy does not sandbox the shell; treating a workspace as a whole-process containment boundary would be incorrect.
+
+- **Unverified behaviour:** Traversal, symlink, sensitive-name, absolute-path, and workspace-switch behaviour remains unverified.
+
+## Agent-controlled tool dispatch
+
+- **Boundary:** Model output becomes native or parsed tool calls and is dispatched by the agent loop.
+
+- **Available authority:** The authority of every enabled tool, including privileged built-ins and external tools.
+
+- **User-controlled inputs:** Chat content, attached/retrieved content that may influence the model, tool arguments, per-request tool selection, and policy toggles.
+
+- **Current safeguards:** [`src/tool_security.py`](../src/tool_security.py) blocks protected tools for non-admin users and fails closed for malformed tool names; [`src/tool_policy.py`](../src/tool_policy.py) supports disabled and guide-only policy; prompt-security helpers label untrusted context.
+
+- **Confirmed risks or gaps:** Credible risk requiring verification: aliases, legacy text tools, native function calls, and MCP-qualified names must all reach the same policy outcome. The code has specific alias handling for email/MCP names, which makes this a sensitive compatibility seam.
+
+- **Unverified behaviour:** The current policy outcomes for owner role, request mode, disabled state, native versus parsed invocation, qualified aliases, and external-content entry points remain unverified.
+
+## MCP and external tool servers
+
+- **Boundary:** Configured MCP servers and their tools are exposed to the agent through the MCP manager and routes.
+
+- **Available authority:** Depends on the server: external network access, local process access, messaging, or data mutation may be delegated outside the application.
+
+- **User-controlled inputs:** Server configuration, remote OAuth completion, tool arguments, and model-selected MCP calls.
+
+- **Current safeguards:** MCP routes are registered through [`routes/mcp_routes.py`](../routes/mcp_routes.py); MCP-qualified tools are denied to non-admin users by [`src/tool_security.py`](../src/tool_security.py). OAuth state and token persistence are handled in [`src/mcp_oauth.py`](../src/mcp_oauth.py).
+
+- **Confirmed risks or gaps:** Credible risk requiring verification: an MCP server authority is broader than the application can infer from its tool name. This map does not establish a trust or approval model for server installation and individual tool invocation.
+
+- **Unverified behaviour:** Server onboarding, credential storage, server-origin trust, OAuth callback deployment, tool disablement, and invocation audit behaviour remain unverified.
+
+## Outbound network requests and URL validation
+
+- **Boundary:** Search/content fetch, research, webhooks, skill import, provider endpoints, and other HTTP clients.
+
+- **Available authority:** The application can make outbound requests from its network position.
+
+- **User-controlled inputs:** Search/fetch URLs, imported skill URLs, webhook configuration, and some endpoint settings.
+
+- **Current safeguards:** [`src/url_security.py`](../src/url_security.py) validates untrusted public HTTP URLs and fails closed on unsuitable schemes or private addresses. [`services/search/content.py`](../services/search/content.py) resolves and rejects non-public hosts, pins resolved addresses for fetches, caps bodies, and limits redirects.
+
+- **Confirmed risks or gaps:** Intentional split: administrator-created model endpoints may target private providers, while untrusted URLs use public-address checks. That distinction is required for self-hosted deployments but needs explicit call-site review.
+
+- **Unverified behaviour:** The URL-source classification for outbound clients and the current handling of redirects and DNS changes remain unverified.
+
+## Secrets, credentials, and vault sessions
+
+- **Boundary:** Application-managed encrypted secrets, API keys, provider credentials, and Bitwarden/Vaultwarden CLI sessions.
+
+- **Available authority:** Credentials unlock remote providers and connected personal services.
+
+- **User-controlled inputs:** Administrative configuration, login/unlock requests, imported settings, and agent vault tool arguments.
+
+- **Current safeguards:** [`src/secret_storage.py`](../src/secret_storage.py) uses a locally stored Fernet key with restrictive permissions for supported database secrets. Vault routes require an administrator, avoid passing master passwords in command arguments, and set restrictive permissions on the vault-session file.
+
+- **Confirmed risks or gaps:** Confirmed current boundary: vault session data is persisted through the vault path, not through [`src/secret_storage.py`](../src/secret_storage.py). This is an unresolved question about current security semantics, not a confirmed exposure.
+
+- **Unverified behaviour:** Current encryption-at-rest, owner scope, rotation, lock/logout, backup/restore, and log/tool-result exposure behaviour remains unverified.
+
+## Authentication and privileged administration
+
+- **Boundary:** Session authentication, API tokens, privileged routes, and internal tool loopback.
+
+- **Available authority:** Administrative identity can access execution, settings, integrations, data deletion, and secrets.
+
+- **User-controlled inputs:** Login/signup data, session cookies, API tokens, authentication configuration, and requests to privileged routes.
+
+- **Current safeguards:** [`core/auth.py`](../core/auth.py), [`core/middleware.py`](../core/middleware.py), and route-level checks establish identity and administrator gates. [`app.py`](../app.py) warns when localhost bypass is configured; [`SECURITY.md`](../SECURITY.md) documents deployment requirements.
+
+- **Confirmed risks or gaps:** Intentional authority with safeguards. Security depends on deployments keeping authentication enabled and internal services private; this map does not audit reverse-proxy or environment configuration.
+
+- **Unverified behaviour:** Setup, anonymous, non-admin, admin, token, and internal-loopback behaviour, including privileged-route gate consistency, remains unverified.
+
+## Deletion, wipe, backup, and restore
+
+- **Boundary:** Administrative wipe, cleanup, backup import/export, and the backup restore command.
+
+- **Available authority:** Delete or replace user data and credentials.
+
+- **User-controlled inputs:** Administrative HTTP requests, cleanup choices, backup payloads, archive paths, and restore command options.
+
+- **Current safeguards:** Administrative wipe routes use the administrative boundary. Cleanup exposes a preview route before mutation. The documented backup tool requires explicit restore confirmation, stages the old data directory, and validates archive members before extraction.
+
+- **Confirmed risks or gaps:** Intentional destructive authority. Backup archives contain secrets by design, as documented in [`docs/backup-restore.md`](../docs/backup-restore.md); this is an operator confidentiality responsibility, not a code defect established here.
+
+- **Unverified behaviour:** Role-gate, confirmation, archive-rejection, staged-recovery, and owner-isolation behaviour remains unverified. No destructive runtime test was performed.
+
+## Background jobs and unattended task execution
+
+- **Boundary:** Scheduled tasks, background-job monitor, startup tasks, and notification/delivery work that continue without an active browser request.
+
+- **Available authority:** Scheduled agent work can obtain model access and, for eligible owners, shell and file tools; task output can interact with connected services.
+
+- **User-controlled inputs:** Stored task prompt, schedule, model/crew selection, enabled-tool configuration, output target, and prior persisted state.
+
+- **Current safeguards:** [`src/task_scheduler.py`](../src/task_scheduler.py) serializes execution, records task runs, associates work with an owner, and applies the agent owner-based tool gate. [`src/bg_jobs.py`](../src/bg_jobs.py) keeps bounded state and can terminate overlong subprocess jobs.
+
+- **Confirmed risks or gaps:** Credible risk requiring verification: authority is inherited and exercised later, so changes to roles, task configuration, and disabled tools must be checked at execution time rather than assumed from task creation.
+
+- **Unverified behaviour:** Creation, editing, role-change, scheduling, cancellation, restart-recovery, and execution behaviour remains unverified, including whether current policy is re-evaluated before privileged action.

discovery/system-map.md

@@ -0,0 +1,139 @@
+# Current system map
+
+> [!NOTE]
+> This non-canonical discovery map is an evidence guide, not an exhaustive feature catalog or runtime certification. Verify the cited source before relying on a finding. Each section records local implementation observations, evidence locations, confirmed current problems, and unresolved factual questions.
+
+## Navigate the system
+
+- [Startup and application composition](#startup-and-application-composition)
+- [Frontend shell and browser interaction](#frontend-shell-and-browser-interaction)
+- [Chat, sessions, and streaming](#chat-sessions-and-streaming)
+- [Agents, tools, and execution](#agents-tools-and-execution)
+- [Models, providers, and local serving](#models-providers-and-local-serving)
+- [Search and research](#search-and-research)
+- [Documents, retrieval, and personal knowledge](#documents-retrieval-and-personal-knowledge)
+- [Memory and skills](#memory-and-skills)
+- [Email, calendar, contacts, notes, and tasks](#email-calendar-contacts-notes-and-tasks)
+- [Media, speech, and image work](#media-speech-and-image-work)
+- [Authentication, secrets, and privileged administration](#authentication-secrets-and-privileged-administration)
+- [Persistence, background work, and operations](#persistence-background-work-and-operations)
+
+## Startup and application composition
+
+- **How it works:** [`app.py`](../app.py) creates the application, mounts static assets, constructs shared services, registers route factories, and owns lifespan startup and shutdown. [`src/app_initializer.py`](../src/app_initializer.py) prepares application state; [`core/`](../core/) provides persistence, authentication, middleware, sessions, and platform helpers.
+
+- **Evidence locations:** [`app.py`](../app.py); [`src/app_initializer.py`](../src/app_initializer.py); [`core/database.py`](../core/database.py); [`core/auth.py`](../core/auth.py); [`core/middleware.py`](../core/middleware.py); [`routes/`](../routes/).
+
+- **Known problems:** None recorded by this mapping.
+
+- **Open question:** Which component currently owns startup and shutdown for each long-lived service?
+
+## Frontend shell and browser interaction
+
+- **How it works:** [`static/index.html`](../static/index.html) is served by the root and SPA deep-link routes in [`app.py`](../app.py); [`static/app.js`](../static/app.js), [`static/style.css`](../static/style.css), and [`static/js/`](../static/js/) implement the client surface.
+
+- **Evidence locations:** [`static/index.html`](../static/index.html); [`static/app.js`](../static/app.js); [`static/js/`](../static/js/); [`static/style.css`](../static/style.css); [`app.py`](../app.py) deep-link handlers.
+
+- **Known problems:** The `/backgrounds` route in [`app.py`](../app.py) calls `serve_html_with_nonce` for `static/backgrounds.html`, but that file is absent from [`static/`](../static/). This is a confirmed broken prototype route, not evidence about the rest of the frontend.
+
+- **Open question:** Is `/backgrounds` currently an intentionally supported route or an obsolete prototype?
+
+## Chat, sessions, and streaming
+
+- **How it works:** [`routes/chat_routes.py`](../routes/chat_routes.py) and [`routes/chat_helpers.py`](../routes/chat_helpers.py) coordinate requests, session state, and SSE delivery. [`src/chat_handler.py`](../src/chat_handler.py), [`src/chat_processor.py`](../src/chat_processor.py), [`src/llm_core.py`](../src/llm_core.py), and [`src/session_actions.py`](../src/session_actions.py) provide message preparation, provider interaction, and session operations.
+
+- **Evidence locations:** [`routes/chat_routes.py`](../routes/chat_routes.py); [`routes/chat_helpers.py`](../routes/chat_helpers.py); [`routes/session_routes.py`](../routes/session_routes.py); [`src/chat_handler.py`](../src/chat_handler.py); [`src/chat_processor.py`](../src/chat_processor.py); [`src/llm_core.py`](../src/llm_core.py); [`core/session_manager.py`](../core/session_manager.py).
+
+- **Known problems:** [`src/agent_loop.py`](../src/agent_loop.py) annotates `_resolved_tool_event_name` with `Any` but imports no `Any` and does not enable postponed annotation evaluation. Python evaluates that annotation while importing the module, so this is an import-time defect at the checked baseline.
+
+- **Open question:** No end-to-end provider or browser streaming run was performed for this map.
+
+## Agents, tools, and execution
+
+- **How it works:** [`src/agent_loop.py`](../src/agent_loop.py) drives multi-round tool use. [`src/tool_execution.py`](../src/tool_execution.py) dispatches calls and binds workspace context. [`src/agent_tools/`](../src/agent_tools/) contains individual implementations; [`src/tool_security.py`](../src/tool_security.py) and [`src/tool_policy.py`](../src/tool_policy.py) apply role and request policies. Long-running command work is represented by [`src/bg_jobs.py`](../src/bg_jobs.py).
+
+- **Evidence locations:** [`src/agent_loop.py`](../src/agent_loop.py); [`src/tool_execution.py`](../src/tool_execution.py); [`src/agent_tools/`](../src/agent_tools/); [`src/tool_security.py`](../src/tool_security.py); [`src/tool_policy.py`](../src/tool_policy.py); [`src/tool_schemas.py`](../src/tool_schemas.py); [`src/bg_jobs.py`](../src/bg_jobs.py).
+
+- **Known problems:** The import-time annotation defect above blocks the main agent/tool path. The shell is intentionally not a filesystem or network sandbox; that is an authority boundary, not by itself a vulnerability claim.
+
+- **Open question:** Which native, legacy, and MCP-qualified invocation paths reach each policy gate?
+
+## Models, providers, and local serving
+
+- **How it works:** Model routes delegate to discovery, capabilities, endpoint resolution, and LLM core modules. Cookbook routes and hardware-fit services handle model lifecycle and local-serving support.
+
+- **Evidence locations:** [`routes/model_routes.py`](../routes/model_routes.py); [`src/model_discovery.py`](../src/model_discovery.py); [`src/model_capabilities.py`](../src/model_capabilities.py); [`src/endpoint_resolver.py`](../src/endpoint_resolver.py); [`src/llm_core.py`](../src/llm_core.py); [`routes/cookbook_routes.py`](../routes/cookbook_routes.py); [`src/cookbook_serve_lifecycle.py`](../src/cookbook_serve_lifecycle.py); [`services/hwfit/`](../services/hwfit/).
+
+- **Known problems:** None recorded by this mapping.
+
+- **Open question:** Which endpoint inputs are administrator-created and permitted to use private provider addresses?
+
+## Search and research
+
+- **How it works:** HTTP search routes use [`services/search/`](../services/search/); research is exposed through [`routes/research/`](../routes/research/) and implemented in [`services/research/`](../services/research/), [`src/deep_research.py`](../src/deep_research.py), and related helpers. [`src/search/`](../src/search/) remains an import-compatibility layer for callers not yet moved to `services.search`.
+
+- **Evidence locations:** [`routes/search_routes.py`](../routes/search_routes.py); [`services/search/`](../services/search/); [`routes/research/research_routes.py`](../routes/research/research_routes.py); [`services/research/`](../services/research/); [`src/deep_research.py`](../src/deep_research.py); [`src/search/`](../src/search/).
+
+- **Known problems:** None recorded by this mapping.
+
+- **Open question:** No live provider request was made; provider configuration and network access remain unverified.
+
+## Documents, retrieval, and personal knowledge
+
+- **How it works:** Document routes coordinate upload handling, document processing, and editor actions. Personal-document and RAG modules use Chroma and embedding clients. PDF viewing uses the optional-dependency loader in [`src/pdf_runtime.py`](../src/pdf_runtime.py); form extraction and filling live separately in [`src/pdf_forms.py`](../src/pdf_forms.py) and [`src/pdf_form_doc.py`](../src/pdf_form_doc.py).
+
+- **Evidence locations:** [`routes/document_routes.py`](../routes/document_routes.py); [`src/upload_handler.py`](../src/upload_handler.py); [`src/document_processor.py`](../src/document_processor.py); [`src/document_actions.py`](../src/document_actions.py); [`src/personal_docs.py`](../src/personal_docs.py); [`src/rag_manager.py`](../src/rag_manager.py); [`src/embeddings.py`](../src/embeddings.py); [`src/pdf_runtime.py`](../src/pdf_runtime.py); [`src/pdf_forms.py`](../src/pdf_forms.py); [`src/pdf_form_doc.py`](../src/pdf_form_doc.py).
+
+- **Known problems:** PDF viewing/runtime loading and PDF form processing are separate implementations. That separation is confirmed and intentional in the source; it is not a defect without a reported behavioural failure.
+
+- **Open question:** Optional PDF dependencies and representative uploaded documents were not exercised.
+
+## Memory and skills
+
+- **How it works:** Memory routes use [`services/memory/`](../services/memory/) and vector helpers. Skills are exposed through [`routes/skills_routes.py`](../routes/skills_routes.py), stored and managed in [`services/memory/skills.py`](../services/memory/skills.py), and may be imported through [`services/memory/skill_importer.py`](../services/memory/skill_importer.py).
+
+- **Evidence locations:** [`routes/memory/memory_routes.py`](../routes/memory/memory_routes.py); [`services/memory/`](../services/memory/); [`src/memory.py`](../src/memory.py); [`src/memory_vector.py`](../src/memory_vector.py); [`routes/skills_routes.py`](../routes/skills_routes.py); [`services/memory/skills.py`](../services/memory/skills.py); [`services/memory/skill_importer.py`](../services/memory/skill_importer.py).
+
+- **Known problems:** None recorded by this mapping.
+
+- **Open question:** Which imported skill content can reach execution-capable paths, and which validation occurs before that point?
+
+## Email, calendar, contacts, notes, and tasks
+
+- **How it works:** Dedicated route modules own email, CalDAV calendar, CardDAV contacts, notes, and tasks. Supporting modules include email helpers and pollers, CalDAV sync and writeback, and the task scheduler.
+
+- **Evidence locations:** [`routes/email_routes.py`](../routes/email_routes.py); [`routes/calendar_routes.py`](../routes/calendar_routes.py); [`routes/contacts/contacts_routes.py`](../routes/contacts/contacts_routes.py); [`routes/note/note_routes.py`](../routes/note/note_routes.py); [`routes/task_routes.py`](../routes/task_routes.py); [`routes/assistant_routes.py`](../routes/assistant_routes.py); [`src/caldav_sync.py`](../src/caldav_sync.py); [`src/caldav_writeback.py`](../src/caldav_writeback.py); [`src/task_scheduler.py`](../src/task_scheduler.py).
+
+- **Known problems:** None recorded by this mapping.
+
+- **Open question:** External account behaviour, writeback, and delivery require controlled credentials and are not runtime-validated here.
+
+## Media, speech, and image work
+
+- **How it works:** Gallery and image routes coordinate media features. Service modules own speech and media integrations; [`src/generated_images.py`](../src/generated_images.py) and [`src/visual_report.py`](../src/visual_report.py) support artifact handling and presentation.
+
+- **Evidence locations:** [`routes/gallery/gallery_routes.py`](../routes/gallery/gallery_routes.py); [`routes/stt_routes.py`](../routes/stt_routes.py); [`routes/tts_routes.py`](../routes/tts_routes.py); [`src/generated_images.py`](../src/generated_images.py); [`services/stt/`](../services/stt/); [`services/tts/`](../services/tts/); [`services/faces/`](../services/faces/); [`src/visual_report.py`](../src/visual_report.py).
+
+- **Known problems:** None recorded by this mapping.
+
+- **Open question:** Hardware- and provider-dependent media workflows were not exercised.
+
+## Authentication, secrets, and privileged administration
+
+- **How it works:** [`core/auth.py`](../core/auth.py) and [`core/middleware.py`](../core/middleware.py) provide identity and request gates. [`src/secret_storage.py`](../src/secret_storage.py) encrypts application-managed database secrets with a local Fernet key. Vault handling is separate: [`routes/vault_routes.py`](../routes/vault_routes.py) and [`src/tools/vault.py`](../src/tools/vault.py) invoke the Bitwarden CLI and persist its session data in the application data area.
+
+- **Evidence locations:** [`core/auth.py`](../core/auth.py); [`core/middleware.py`](../core/middleware.py); [`routes/auth_routes.py`](../routes/auth_routes.py); [`routes/api_token_routes.py`](../routes/api_token_routes.py); [`src/secret_storage.py`](../src/secret_storage.py); [`routes/vault_routes.py`](../routes/vault_routes.py); [`src/tools/vault.py`](../src/tools/vault.py); [`routes/admin_wipe/admin_wipe_routes.py`](../routes/admin_wipe/admin_wipe_routes.py).
+
+- **Known problems:** Vault-command handling and local application secret storage are distinct paths with different storage mechanisms. This is a source-confirmed boundary, not evidence that either path is compromised.
+
+- **Open question:** What are the current confidentiality, ownership, rotation, and backup semantics for vault session data?
+
+## Persistence, background work, and operations
+
+- **How it works:** SQLite models and persistence are centred in [`core/database.py`](../core/database.py); managers use application data paths. The scheduler and background-job monitor can continue work outside a live browser request. Operational routes cover cleanup, backup, and administrative wipe; the repository also provides a backup script and user documentation.
+
+- **Evidence locations:** [`core/database.py`](../core/database.py); [`src/runtime_paths.py`](../src/runtime_paths.py); [`src/task_scheduler.py`](../src/task_scheduler.py); [`src/bg_jobs.py`](../src/bg_jobs.py); [`src/bg_monitor.py`](../src/bg_monitor.py); [`routes/backup_routes.py`](../routes/backup_routes.py); [`routes/cleanup/cleanup_routes.py`](../routes/cleanup/cleanup_routes.py); [`routes/admin_wipe/admin_wipe_routes.py`](../routes/admin_wipe/admin_wipe_routes.py); [`scripts/odysseus-backup`](../scripts/odysseus-backup); [`docs/backup-restore.md`](../docs/backup-restore.md).
+
+- **Known problems:** None recorded by this mapping.
+
+- **Open question:** What current behaviour applies to background execution, cancellation, retries, and authority inheritance?

docker-compose.gpu-amd.yml

@@ -67,7 +67,6 @@ services:
       - ODYSSEUS_EMAIL_COMPOSE_UPLOAD_MAX_BYTES=${ODYSSEUS_EMAIL_COMPOSE_UPLOAD_MAX_BYTES:-26214400}
       - ODYSSEUS_STT_MAX_AUDIO_BYTES=${ODYSSEUS_STT_MAX_AUDIO_BYTES:-26214400}
       - ODYSSEUS_ICS_MAX_BYTES=${ODYSSEUS_ICS_MAX_BYTES:-10485760}
-      - ODYSSEUS_TTS_CACHE_MAX_BYTES=${ODYSSEUS_TTS_CACHE_MAX_BYTES}
       - DATA_BRAVE_API_KEY=${DATA_BRAVE_API_KEY:-}
       - GOOGLE_API_KEY=${GOOGLE_API_KEY:-}
       - GOOGLE_PSE_CX=${GOOGLE_PSE_CX:-}

docker-compose.gpu-nvidia.yml

@@ -66,7 +66,6 @@ services:
       - ODYSSEUS_EMAIL_COMPOSE_UPLOAD_MAX_BYTES=${ODYSSEUS_EMAIL_COMPOSE_UPLOAD_MAX_BYTES:-26214400}
       - ODYSSEUS_STT_MAX_AUDIO_BYTES=${ODYSSEUS_STT_MAX_AUDIO_BYTES:-26214400}
       - ODYSSEUS_ICS_MAX_BYTES=${ODYSSEUS_ICS_MAX_BYTES:-10485760}
-      - ODYSSEUS_TTS_CACHE_MAX_BYTES=${ODYSSEUS_TTS_CACHE_MAX_BYTES}
       - DATA_BRAVE_API_KEY=${DATA_BRAVE_API_KEY:-}
       - GOOGLE_API_KEY=${GOOGLE_API_KEY:-}
       - GOOGLE_PSE_CX=${GOOGLE_PSE_CX:-}

docker-compose.yml

@@ -55,7 +55,6 @@ services:
       - ODYSSEUS_EMAIL_COMPOSE_UPLOAD_MAX_BYTES=${ODYSSEUS_EMAIL_COMPOSE_UPLOAD_MAX_BYTES:-26214400}
       - ODYSSEUS_STT_MAX_AUDIO_BYTES=${ODYSSEUS_STT_MAX_AUDIO_BYTES:-26214400}
       - ODYSSEUS_ICS_MAX_BYTES=${ODYSSEUS_ICS_MAX_BYTES:-10485760}
-      - ODYSSEUS_TTS_CACHE_MAX_BYTES=${ODYSSEUS_TTS_CACHE_MAX_BYTES}
       - DATA_BRAVE_API_KEY=${DATA_BRAVE_API_KEY:-}
       - GOOGLE_API_KEY=${GOOGLE_API_KEY:-}
       - GOOGLE_PSE_CX=${GOOGLE_PSE_CX:-}

docs/setup.md

@@ -441,7 +441,7 @@ uv pip sync requirements.lock                          # reproduce it exactly la
 ### Outlook / Office 365 email
 Odysseus email accounts currently use IMAP/SMTP username-password auth. Outlook
 and Microsoft 365 generally require OAuth instead, so normal Microsoft mailbox
-passwords will fail. See [docs/email-outlook.md](docs/email-outlook.md) for the
+passwords will fail. See [email-outlook.md](email-outlook.md) for the
 current limitation and the planned integration direction.
 
 ## Security Notes

requirements.txt

@@ -38,10 +38,7 @@ python-dateutil
 caldav
 cryptography
 bcrypt
-# Built-in servers use the v1 low-level Server decorator API. MCP SDK v2 is a
+mcp
-# breaking rewrite, so keep fresh installs on the maintained v1 line until the
-# servers are migrated together.
-mcp<2
 pyotp
 qrcode[pil]
 croniter

routes/search/__init__.py

@@ -1,5 +0,0 @@
-"""Search route domain package (slice 2j, #4082/#4071).
-
-Contains search_routes.py, migrated from the flat routes/ directory.
-Backward-compat shim at routes/search_routes.py re-exports from here.
-"""

routes/search/search_routes.py

@@ -1,111 +0,0 @@
-"""Search routes — /api/search/config GET, /api/search POST."""
-
-import logging
-from typing import Dict, Any
-
-from fastapi import APIRouter, Request
-
-import time
-
-from services.search import get_search_config, comprehensive_web_search, PROVIDER_INFO
-from services.search.core import _call_provider
-from services.search.providers import _get_provider_key, _get_search_instance
-
-logger = logging.getLogger(__name__)
-
-
-async def _request_values(request: Request) -> Dict[str, Any]:
-    """Accept JSON, form data, or query params for search endpoints.
-
-    The browser UI posts FormData, while the agent's generic app_api tool
-    posts JSON. FastAPI Form(...) rejects JSON with a 422 before our handler
-    runs, which made the model think SearXNG was broken.
-    """
-    values: Dict[str, Any] = dict(request.query_params)
-    content_type = (request.headers.get("content-type") or "").lower()
-    try:
-        if "application/json" in content_type:
-            body = await request.json()
-            if isinstance(body, dict):
-                values.update(body)
-        else:
-            form = await request.form()
-            values.update(dict(form))
-    except Exception:
-        pass
-    return values
-
-
-def setup_search_routes(config) -> APIRouter:
-    router = APIRouter(tags=["search"])
-
-    @router.get("/api/search/config")
-    async def get_search_settings() -> Dict[str, Any]:
-        return get_search_config()
-
-    @router.post("/api/search")
-    async def do_web_search(request: Request) -> Dict[str, Any]:
-        """Standalone web search — returns context string + source list.
-
-        Used by Compare mode to pre-search once and share results across panes.
-        """
-        values = await _request_values(request)
-        query = str(values.get("query") or values.get("q") or "").strip()
-        if not query:
-            return {"context": "", "sources": [], "error": "query is required"}
-        time_filter = values.get("time_filter") or values.get("freshness")
-        if time_filter is not None:
-            time_filter = str(time_filter).strip() or None
-        try:
-            context, sources = comprehensive_web_search(
-                query, return_sources=True, time_filter=time_filter,
-            )
-            return {"context": context, "sources": sources}
-        except Exception as e:
-            logger.error(f"Standalone web search failed: {e}")
-            return {"context": "", "sources": [], "error": str(e)}
-
-    @router.get("/api/search/providers")
-    async def list_search_providers():
-        """Return available search providers with config status."""
-        providers = []
-        for pid, (label, needs_key, needs_url) in PROVIDER_INFO.items():
-            if pid == "disabled":
-                continue
-            available = True
-            if needs_key and not _get_provider_key(pid):
-                available = False
-            if needs_url and pid == "searxng" and not _get_search_instance():
-                available = False
-            providers.append({
-                "id": pid,
-                "label": label,
-                "available": available,
-            })
-        return providers
-
-    @router.post("/api/search/query")
-    async def search_with_provider(request: Request) -> Dict[str, Any]:
-        """Search using a specific provider. Used by compare search mode."""
-        values = await _request_values(request)
-        query = str(values.get("query") or values.get("q") or "").strip()
-        provider = str(values.get("provider") or "").strip()
-        try:
-            count = int(values.get("count") or values.get("limit") or 10)
-        except Exception:
-            count = 10
-        if not query:
-            return {"results": [], "provider": provider, "error": "query is required"}
-        if provider not in PROVIDER_INFO or provider == "disabled":
-            return {"results": [], "provider": provider, "error": "Unknown provider"}
-        t0 = time.time()
-        try:
-            results = _call_provider(provider, query, min(count, 20))
-            elapsed = round(time.time() - t0, 2)
-            return {"results": results, "provider": provider, "time": elapsed}
-        except Exception as e:
-            elapsed = round(time.time() - t0, 2)
-            logger.error(f"Search provider {provider} failed: {e}")
-            return {"results": [], "provider": provider, "time": elapsed, "error": str(e)}
-
-    return router

routes/search_routes.py

@@ -1,13 +1,111 @@
-"""Backward-compat shim — canonical location is routes/search/search_routes.py.
+"""Search routes — /api/search/config GET, /api/search POST."""
 
-This module is replaced in ``sys.modules`` by the canonical module object so
+import logging
-that ``import routes.search_routes`` and ``from routes.search_routes import X``
+from typing import Dict, Any
-keep resolving to the canonical module. Keeps existing import paths working
-after slice 2j (#4082/#4071).
-"""
 
-import sys as _sys
+from fastapi import APIRouter, Request
 
-from routes.search import search_routes as _canonical  # noqa: F401
+import time
 
-_sys.modules[__name__] = _canonical
+from services.search import get_search_config, comprehensive_web_search, PROVIDER_INFO
+from services.search.core import _call_provider
+from services.search.providers import _get_provider_key, _get_search_instance
+
+logger = logging.getLogger(__name__)
+
+
+async def _request_values(request: Request) -> Dict[str, Any]:
+    """Accept JSON, form data, or query params for search endpoints.
+
+    The browser UI posts FormData, while the agent's generic app_api tool
+    posts JSON. FastAPI Form(...) rejects JSON with a 422 before our handler
+    runs, which made the model think SearXNG was broken.
+    """
+    values: Dict[str, Any] = dict(request.query_params)
+    content_type = (request.headers.get("content-type") or "").lower()
+    try:
+        if "application/json" in content_type:
+            body = await request.json()
+            if isinstance(body, dict):
+                values.update(body)
+        else:
+            form = await request.form()
+            values.update(dict(form))
+    except Exception:
+        pass
+    return values
+
+
+def setup_search_routes(config) -> APIRouter:
+    router = APIRouter(tags=["search"])
+
+    @router.get("/api/search/config")
+    async def get_search_settings() -> Dict[str, Any]:
+        return get_search_config()
+
+    @router.post("/api/search")
+    async def do_web_search(request: Request) -> Dict[str, Any]:
+        """Standalone web search — returns context string + source list.
+
+        Used by Compare mode to pre-search once and share results across panes.
+        """
+        values = await _request_values(request)
+        query = str(values.get("query") or values.get("q") or "").strip()
+        if not query:
+            return {"context": "", "sources": [], "error": "query is required"}
+        time_filter = values.get("time_filter") or values.get("freshness")
+        if time_filter is not None:
+            time_filter = str(time_filter).strip() or None
+        try:
+            context, sources = comprehensive_web_search(
+                query, return_sources=True, time_filter=time_filter,
+            )
+            return {"context": context, "sources": sources}
+        except Exception as e:
+            logger.error(f"Standalone web search failed: {e}")
+            return {"context": "", "sources": [], "error": str(e)}
+
+    @router.get("/api/search/providers")
+    async def list_search_providers():
+        """Return available search providers with config status."""
+        providers = []
+        for pid, (label, needs_key, needs_url) in PROVIDER_INFO.items():
+            if pid == "disabled":
+                continue
+            available = True
+            if needs_key and not _get_provider_key(pid):
+                available = False
+            if needs_url and pid == "searxng" and not _get_search_instance():
+                available = False
+            providers.append({
+                "id": pid,
+                "label": label,
+                "available": available,
+            })
+        return providers
+
+    @router.post("/api/search/query")
+    async def search_with_provider(request: Request) -> Dict[str, Any]:
+        """Search using a specific provider. Used by compare search mode."""
+        values = await _request_values(request)
+        query = str(values.get("query") or values.get("q") or "").strip()
+        provider = str(values.get("provider") or "").strip()
+        try:
+            count = int(values.get("count") or values.get("limit") or 10)
+        except Exception:
+            count = 10
+        if not query:
+            return {"results": [], "provider": provider, "error": "query is required"}
+        if provider not in PROVIDER_INFO or provider == "disabled":
+            return {"results": [], "provider": provider, "error": "Unknown provider"}
+        t0 = time.time()
+        try:
+            results = _call_provider(provider, query, min(count, 20))
+            elapsed = round(time.time() - t0, 2)
+            return {"results": results, "provider": provider, "time": elapsed}
+        except Exception as e:
+            elapsed = round(time.time() - t0, 2)
+            logger.error(f"Search provider {provider} failed: {e}")
+            return {"results": [], "provider": provider, "time": elapsed, "error": str(e)}
+
+    return router

routes/skills_routes.py

@@ -1409,7 +1409,7 @@ def setup_skills_routes(skills_manager: SkillsManager) -> APIRouter:
 
         # Prefer the configured DEFAULT (→ Utility) model — not the current chat
         # session's model. Fall back to the caller's session model only if unset.
-        url, model, headers = resolve_endpoint("utility", owner=user)
+        url, model, headers = resolve_endpoint("default", owner=user)
         if not url or not model:
             url = url or ((body.get("endpoint_url") or "").strip() or None)
             model = model or ((body.get("model") or "").strip() or None)

services/memory/skill_format.py

@@ -50,7 +50,7 @@ import json
 import logging
 import re
 from dataclasses import dataclass, field
-from datetime import datetime, timezone
+from datetime import datetime
 from typing import Any, Dict, List, Optional
 
 logger = logging.getLogger(__name__)
@@ -441,4 +441,4 @@ class Skill:
 
 
 def _now_iso() -> str:
-    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+    return datetime.utcnow().strftime("%Y-%m-%dT%H:%M:%SZ")

services/tts/tts_service.py

@@ -2,7 +2,6 @@
 """Multi-provider TTS service — dispatches to local Kokoro, OpenAI-compatible API, or browser."""
 
 import io
-import os
 import wave
 import logging
 import hashlib
@@ -42,11 +41,6 @@ class TTSService:
         self.cache_dir = Path(cache_dir)
         self.cache_dir.mkdir(parents=True, exist_ok=True)
         self._kokoro = None  # lazy-init
-        
-        try:
-            self.max_cache_bytes = int(os.getenv("ODYSSEUS_TTS_CACHE_MAX_BYTES", 500 * 1024 * 1024))
-        except ValueError:
-            self.max_cache_bytes = 500 * 1024 * 1024
 
     # ── Settings ──
 
@@ -95,53 +89,6 @@ class TTSService:
         ext = ".mp3" if (len(data) >= 3 and (data[:3] == b'ID3' or (data[0] == 0xff and (data[1] & 0xe0) == 0xe0))) else ".wav"
         (self.cache_dir / f"{key}{ext}").write_bytes(data)
 
-        self._enforce_cache_limit()
-
-    def _enforce_cache_limit(self):
-            """Evicts oldest files if the cache exceeds the configured byte limit."""
-            if self.max_cache_bytes <= 0:
-                return
-
-            try:
-                files = []
-                total_size = 0
-
-                # Safely scan files and sum sizes, ignoring files deleted mid-scan
-                for f in self.cache_dir.iterdir():
-                    try:
-                        if f.is_file() and f.suffix.lower() in (".mp3", ".wav"):
-                            files.append(f)
-                            total_size += f.stat().st_size
-                    except OSError:
-                        continue
-
-                if total_size > self.max_cache_bytes:
-                    logger.info(
-                        f"TTS cache ({total_size} bytes) exceeded limit ({self.max_cache_bytes} bytes). Evicting oldest files."
-                    )
-
-                    # Sort files by modification time (oldest first)
-                    try:
-                        files.sort(key=lambda f: f.stat().st_mtime)
-                    except OSError as e:
-                        logger.warning(f"Failed to sort cache files by mtime: {e}")
-
-                    # Trim down to 80% of max capacity
-                    target_size = self.max_cache_bytes * 0.8
-
-                    while files and total_size > target_size:
-                        f = files.pop(0)
-                        try:
-                            size = f.stat().st_size
-                            f.unlink()
-                            total_size -= size
-                        except OSError as e:
-                            logger.warning(f"Failed to evict cache file {f}: {e}")
-                            continue
-
-            except Exception as e:
-                logger.warning(f"Error enforcing TTS cache limit: {e}", exc_info=True)
-
     def clear_cache(self):
         count = 0
         for f in self.cache_dir.glob("*.*"):

src/agent_loop.py

@@ -12,7 +12,7 @@ import json
 import re
 import time
 import logging
-from typing import Any, AsyncGenerator, List, Dict, Optional, Set
+from typing import AsyncGenerator, List, Dict, Optional, Set
 from urllib.parse import urlparse
 
 from src.llm_core import (

src/llm_core.py

@@ -1237,27 +1237,15 @@ def _anthropic_rejects_temperature(model: str) -> bool:
         return False
     # `(?<![a-z])` anchors "opus" to a word boundary so a substring match like
     # `oct-opus`/`octopus-4-8` can't be read as Opus (it would otherwise strip
-    # temperature). Both version components are capped at 1-2 digits and forbid a
+    # temperature). Cap the minor at 1-2 digits and forbid a trailing digit so a
-    # trailing digit, so an 8-digit date can never be read as a version number:
+    # dated id like `claude-opus-4-20250514` (Opus 4.0) parses as major-only (no
-    # `claude-opus-4-20250514` (Opus 4.0) parses as major-only rather than reading
+    # minor match, kept) instead of reading the date `20250514` as a giant minor
-    # `20250514` as a giant minor, and `claude-3-opus-20240229` (legacy Claude 3
+    # that would falsely test >= 4.7. Dated 4.7+ snapshots (`claude-opus-4-7-
-    # Opus, date directly after "opus-") fails to match at all rather than reading
+    # 20260201`) keep their explicit minor and are still matched.
-    # the date as a giant major. Dated 4.7+ snapshots (`claude-opus-4-7-20260201`)
+    match = re.search(r"(?<![a-z])opus[-_]?(\d+)[-_.](\d{1,2})(?!\d)", model.lower())
-    # keep their explicit minor and are still matched.
-    #
-    # The minor is optional and a missing minor reads as `.0`, so major-only ids
-    # like `claude-opus-5` are correctly treated as >= 4.7 (issue #5753). Without
-    # this, every Opus 5 call kept `temperature` and failed with HTTP 400 — visible
-    # only on paths that pass a temperature, e.g. scheduled tasks inheriting
-    # `stream_agent_loop`'s 0.3 default, which returned empty responses.
-    match = re.search(
-        r"(?<![a-z])opus[-_]?(\d{1,2})(?!\d)(?:[-_.](\d{1,2})(?!\d))?", model.lower()
-    )
     if not match:
         return False
-    major = int(match.group(1))
+    return (int(match.group(1)), int(match.group(2))) >= (4, 7)
-    minor = int(match.group(2)) if match.group(2) else 0
-    return (major, minor) >= (4, 7)
 
 # Reasoning effort level sent to Mistral thinking-capable models. Mistral's
 # API accepts "high", "medium", "low", "none" — see

static/js/markdown.js

@@ -758,36 +758,30 @@ export function mdToHtml(src, opts) {
   // Remove empty paragraphs
   s = s.replace(/<p><\/p>/g, '');
 
-  // Every restore below passes a function replacer rather than the block string
-  // itself. With a string replacement, `String.replace` reads `$&`, `` $` ``,
-  // `$'` and `$$` in the *replacement* as substitution patterns, so a restored
-  // block containing them is corrupted: `$&` re-inserts the placeholder, `` $` ``
-  // and `$'` splice in the surrounding document, and `$$` collapses to `$`. Those
-  // sequences are ordinary content in fenced code (`perl -pe 's/x/$& y/'`,
-  // `echo "$$USD"`). A function replacer inserts its return value verbatim.
-
   // CRITICAL: Restore allowed HTML blocks first
   allowedHtmlBlocks.forEach((block, index) => {
-    s = s.replace(`___ALLOWED_HTML_${index}___`, () => block);
+    s = s.replace(`___ALLOWED_HTML_${index}___`, block);
   });
 
   // Restore math blocks
   mathBlocks.forEach((block, index) => {
-    s = s.replace(`___MATH_BLOCK_${index}___`, () => block);
+    s = s.replace(`___MATH_BLOCK_${index}___`, block);
   });
 
   // Restore mermaid diagram blocks
   mermaidBlocks.forEach((block, index) => {
-    s = s.replace(`___MERMAID_BLOCK_${index}___`, () => block);
+    s = s.replace(`___MERMAID_BLOCK_${index}___`, block);
   });
 
   // CRITICAL: Restore code blocks at the end
   codeBlocks.forEach((block, index) => {
-    s = s.replace(`___CODE_BLOCK_${index}___`, () => block);
+    s = s.replace(`___CODE_BLOCK_${index}___`, block);
   });
 
   // Restore inline code spans last, so placeholders carried inside restored
-  // <a>/allowed-HTML blocks are resolved too.
+  // <a>/allowed-HTML blocks are resolved too. The function replacer keeps the
+  // escaped code literal — e.g. a shell snippet like `echo $1` is not treated
+  // as a regex back-reference.
   inlineCodeBlocks.forEach((block, index) => {
     s = s.replace(`___INLINE_CODE_${index}___`, () => block);
   });

static/js/settings.js

@@ -3031,14 +3031,12 @@ async function initEmailAccountsSettings() {
       const body = {
         name: el('eaf-name').value.trim() || el('eaf-from').value.trim(),
         from_address: el('eaf-from').value.trim(),
-        display_name: el('eaf-display-name').value.trim(),
         imap_host: el('eaf-imap-host').value.trim(),
         imap_port: parseInt(el('eaf-imap-port').value) || 993,
         imap_user: el('eaf-imap-user').value.trim(),
         imap_starttls: el('eaf-imap-starttls').checked,
         smtp_host: el('eaf-smtp-host').value.trim(),
         smtp_port: parseInt(el('eaf-smtp-port').value) || 587,
-        smtp_security: el('eaf-smtp-security').value,
         smtp_user: el('eaf-imap-user').value.trim(),
       };
       if (!body.name) { el('eaf-msg').textContent = 'Enter a Name or Email first'; el('eaf-msg').style.color = 'var(--red)'; return; }
@@ -5790,30 +5788,29 @@ export function close() {
   window.history.replaceState(null, '', clean);
   const success = sp.has('email_oauth_success');
   const errMsg = sp.get('email_oauth_error') || '';
-  // Open settings → integrations once the document is ready. This module owns
+  // Open settings → integrations after the app has initialised.
-  // the open() API, so it does not need to wait for a window-level alias.
+  function _tryOpen() {
-  function _showResult() {
+    if (window.settingsModule && typeof window.settingsModule.open === 'function') {
-    open('integrations');
+      window.settingsModule.open('integrations');
-    // Brief toast-style banner.
+      // Brief toast-style banner.
-    const banner = document.createElement('div');
+      const banner = document.createElement('div');
-    banner.textContent = success
+      banner.textContent = success
-      ? 'Google account connected — email is ready'
+        ? '✓ Google account connected — email is ready'
-      : `Google OAuth failed: ${errMsg || 'unknown error'}`;
+        : `Google OAuth failed: ${errMsg || 'unknown error'}`;
-    Object.assign(banner.style, {
+      Object.assign(banner.style, {
-      position: 'fixed', bottom: '24px', left: '50%', transform: 'translateX(-50%)',
+        position: 'fixed', bottom: '24px', left: '50%', transform: 'translateX(-50%)',
-      background: success ? 'var(--accent, #50fa7b)' : 'var(--red, #ff5555)',
+        background: success ? 'var(--accent, #50fa7b)' : 'var(--red, #ff5555)',
-      color: '#000', padding: '8px 18px', borderRadius: '6px', fontSize: '12px',
+        color: '#000', padding: '8px 18px', borderRadius: '6px', fontSize: '12px',
-      fontWeight: '600', zIndex: '99999', pointerEvents: 'none',
+        fontWeight: '600', zIndex: '99999', pointerEvents: 'none',
-      boxShadow: '0 2px 12px rgba(0,0,0,0.3)',
+        boxShadow: '0 2px 12px rgba(0,0,0,0.3)',
-    });
+      });
-    document.body.appendChild(banner);
+      document.body.appendChild(banner);
-    setTimeout(() => banner.remove(), 4000);
+      setTimeout(() => banner.remove(), 4000);
-  }
+    } else {
-  if (document.readyState === 'loading') {
+      setTimeout(_tryOpen, 100);
-    document.addEventListener('DOMContentLoaded', _showResult, { once: true });
+    }
-  } else {
-    _showResult();
   }
+  _tryOpen();
 })();
 
 const settingsModule = { open, close, initIntegrations, initUnifiedIntegrations, syncAdminVisibility, refreshAiModelEndpoints };

tests/test_email_oauth_connect_smtp_security.py

@@ -1,15 +0,0 @@
-"""Regression coverage for SMTP security saved before Google OAuth."""
-
-from pathlib import Path
-
-
-_REPO = Path(__file__).resolve().parents[1]
-
-
-def test_email_tab_oauth_connect_persists_selected_smtp_security():
-    source = (_REPO / "static" / "js" / "settings.js").read_text(encoding="utf-8")
-    start = source.index("el('eaf-oauth-btn').addEventListener")
-    handler_body = source[start:source.index("if (!body.name)", start)]
-
-    assert "smtp_security: el('eaf-smtp-security').value" in handler_body
-    assert "display_name: el('eaf-display-name').value.trim()" in handler_body

tests/test_email_oauth_settings_redirect.py

@@ -1,19 +0,0 @@
-"""Regression coverage for the settings UI after Google OAuth redirects."""
-
-from pathlib import Path
-
-
-_REPO = Path(__file__).resolve().parents[1]
-
-
-def test_oauth_redirect_uses_the_module_local_settings_api():
-    source = (_REPO / "static" / "js" / "settings.js").read_text(encoding="utf-8")
-    handler = source[
-        source.index("(function _handleOauthRedirect"):
-        source.index("const settingsModule =")
-    ]
-
-    assert "open('integrations');" in handler
-    assert "window.settingsModule" not in handler
-    assert "window.__odysseusAppStarted" not in handler
-    assert "document.addEventListener('DOMContentLoaded', _showResult, { once: true })" in handler

tests/test_issue_description_check.py

@@ -1,86 +0,0 @@
-"""Regression coverage for issue-description label lifecycle events."""
-
-import json
-import shutil
-import subprocess
-from pathlib import Path
-
-import pytest
-
-
-_REPO = Path(__file__).resolve().parent.parent
-_CHECKER = _REPO / ".github" / "scripts" / "check-issue-description.js"
-_WORKFLOW = _REPO / ".github" / "workflows" / "issue-description-check.yml"
-pytestmark = pytest.mark.skipif(not shutil.which("node"), reason="node not on PATH")
-
-
-def _run_closed_issue(action):
-    harness = r"""
-const checkIssueDescription = require(process.argv[1]);
-const action = process.argv[2];
-const calls = [];
-const unexpected = (name) => async () => {
-  throw new Error(`${name} should not be called for a closed issue`);
-};
-
-const github = {
-  rest: {
-    issues: {
-      removeLabel: async (params) => calls.push({ method: 'removeLabel', params }),
-      getLabel: unexpected('getLabel'),
-      addLabels: unexpected('addLabels'),
-      listComments: unexpected('listComments'),
-      createComment: unexpected('createComment'),
-      updateComment: unexpected('updateComment'),
-      deleteComment: unexpected('deleteComment'),
-    },
-  },
-};
-const context = {
-  payload: {
-    action,
-    issue: { number: 42, state: 'closed', body: '', labels: [] },
-  },
-  repo: { owner: 'odysseus-dev', repo: 'odysseus' },
-};
-const core = {
-  warning: unexpected('core.warning'),
-  setFailed: unexpected('core.setFailed'),
-};
-
-checkIssueDescription({ github, context, core })
-  .then(() => process.stdout.write(JSON.stringify(calls)))
-  .catch((error) => {
-    console.error(error);
-    process.exitCode = 1;
-  });
-"""
-    proc = subprocess.run(
-        ["node", "-e", harness, str(_CHECKER), action],
-        capture_output=True,
-        text=True,
-        cwd=str(_REPO),
-        timeout=30,
-    )
-    assert proc.returncode == 0, proc.stderr
-    return json.loads(proc.stdout)
-
-
-def test_workflow_handles_issue_closures():
-    workflow = _WORKFLOW.read_text()
-    assert "types: [opened, edited, reopened, closed]" in workflow
-
-
-@pytest.mark.parametrize("action", ["closed", "edited"])
-def test_closed_issue_only_drops_ready_for_review(action):
-    assert _run_closed_issue(action) == [
-        {
-            "method": "removeLabel",
-            "params": {
-                "owner": "odysseus-dev",
-                "repo": "odysseus",
-                "issue_number": 42,
-                "name": "ready for review",
-            },
-        }
-    ]

tests/test_llm_core_anthropic_temp_omit.py

@@ -29,13 +29,6 @@ from src.llm_core import _anthropic_rejects_temperature, _build_anthropic_payloa
         "anthropic/claude-opus-4-7",  # tolerate a provider-prefixed id
         "claude-opus-4-10",  # future minor still >= 4.7
         "claude-opus-5-0",  # future major
-        # Major-only ids: a missing minor reads as `.0`, so these are >= 4.7 too
-        # (issue #5753). Before the fix the version pattern required a minor, so
-        # these fell through to "accepts temperature" and every call 400'd.
-        "claude-opus-5",
-        "claude-opus-5-20260101",  # major-only + dated snapshot
-        "anthropic/claude-opus-5",  # major-only behind a provider prefix
-        "claude-opus-6",  # future major-only
     ],
 )
 def test_opus_47_plus_rejects_temperature(model):
@@ -55,10 +48,7 @@ def test_opus_47_plus_rejects_temperature(model):
         "claude-opus-4-6-20251201",  # dated 4.6 snapshot — older, still keeps temperature
         "claude-sonnet-4-6",
         "claude-3-5-sonnet",
-        "claude-3-opus-20240229",  # legacy Claude 3 Opus — date directly after
+        "claude-3-opus-20240229",  # legacy Claude 3 Opus — no opus-N-M pattern, kept
-        # "opus-", so the major must not swallow it as version 20240229 (that is
-        # what makes capping the major at 1-2 digits necessary once the minor
-        # became optional in #5753).
         "claude-haiku-4-5",
         "claude-x",
         "octopus-4-8",  # "opus" only as a substring of another word — must not match
@@ -97,20 +87,6 @@ def test_payload_keeps_temperature_for_older_models():
     assert _payload("claude-3-5-sonnet", 1.2)["temperature"] == 1.0
 
 
-def test_payload_omits_temperature_for_major_only_opus_5():
-    # Issue #5753: the scheduled-task path calls stream_agent_loop() without a
-    # temperature and inherits its 0.3 default, so `claude-opus-5` 400'd on every
-    # run and surfaced as "the model returned an empty response". Interactive chat
-    # leaves temperature None and never hit it.
-    assert "temperature" not in _payload("claude-opus-5", 0.3)
-
-
-def test_payload_keeps_temperature_for_legacy_claude_3_opus():
-    # Guards the major-digit cap: `opus-20240229` must not parse as version
-    # 20240229, or Claude 3 Opus would silently lose the caller's temperature.
-    assert _payload("claude-3-opus-20240229", 0.5)["temperature"] == 0.5
-
-
 def test_payload_keeps_temperature_for_dated_opus_4_0():
     # Anthropic's dated id for Opus 4.0 (claude-opus-4-20250514) is in this repo's
     # ANTHROPIC_MODELS list. The date must not be misread as a >= 4.7 minor, or the

tests/test_markdown_rendering_js.py

@@ -214,50 +214,6 @@ def test_inline_code_content_is_html_escaped(node_available):
     assert "<b>" not in html
 
 
-def test_fenced_code_keeps_dollar_ampersand(node_available):
-    # Issue #5663: the block-restore pass used a string replacement, so `$&` in a
-    # restored block was read as "the matched text" and re-inserted the
-    # placeholder. `perl -pe 's/world/$& again/'` rendered as
-    # "s/world/___CODE_BLOCK_0___amp; again/" — the trailing "amp;" is the orphan
-    # left behind after `$&` consumed the `$&` of the escaped `$&amp;`.
-    html = _run_markdown_case(
-        "```sh\necho \"hello world\" | perl -pe 's/world/$& again/'\n```"
-    )
-
-    assert "___CODE_BLOCK_" not in html
-    assert "s/world/$&amp; again/" in html
-    assert "amp; again" not in html.replace("$&amp; again", "")
-
-
-def test_fenced_code_keeps_dollar_backtick_and_quote(node_available):
-    # `` $` `` and `$'` splice the text before/after the placeholder into the
-    # block. Unlike `$&` these leave no placeholder behind — the characters just
-    # vanish — so assert the content survives verbatim.
-    html = _run_markdown_case("```sh\nsed \"s/$`/x/\" && sed \"s/$'/y/\"\n```")
-
-    assert "___CODE_BLOCK_" not in html
-    assert "s/$`/x/" in html
-    assert "s/$&#39;/y/" in html
-
-
-def test_fenced_code_keeps_double_dollar(node_available):
-    # `$$` collapsed to a single `$` in the restored block.
-    html = _run_markdown_case('```sh\necho "$$USD and $$"\n```')
-
-    assert "$$USD and $$" in html
-
-
-def test_mermaid_block_keeps_dollar_ampersand(node_available):
-    # The mermaid restore site had the same hazard: a node label containing `$&`
-    # re-inserted the ___MERMAID_BLOCK_n___ placeholder into the diagram source,
-    # which then fails to parse. The math and allowed-HTML sites are fixed the
-    # same way; they need KaTeX/sanitizer conditions this harness doesn't set up.
-    html = _run_markdown_case('```mermaid\ngraph TD; A["$&"] --> B;\n```')
-
-    assert "___MERMAID_BLOCK_" not in html
-    assert "$&amp;" in html
-
-
 def test_currency_dollar_amounts_are_not_rendered_as_math(node_available):
     # "$5 to $10" used to pair the two dollar signs as inline-math delimiters
     # and render "5 to" through KaTeX. Pandoc-style rules now reject it: the

tests/test_mcp_dependency_compatibility.py

@@ -1,15 +0,0 @@
-"""Regression coverage for the built-in MCP servers' SDK compatibility line."""
-
-from pathlib import Path
-
-
-REQUIREMENTS = Path(__file__).resolve().parents[1] / "requirements.txt"
-
-
-def test_mcp_requirement_excludes_breaking_v2_sdk():
-    requirements = [
-        line.split("#", 1)[0].strip().replace(" ", "")
-        for line in REQUIREMENTS.read_text(encoding="utf-8").splitlines()
-    ]
-
-    assert "mcp<2" in requirements

tests/test_provider_endpoints_url_building.py

@@ -1,8 +1,8 @@
 """Provider endpoint URL-building tests.
 
-Covers ``build_chat_url`` and ``build_models_url`` for every provider named in
+Covers ``build_chat_url`` and ``build_models_url`` for the provider families
-ROADMAP.md: Anthropic, Gemini, Groq, xAI, OpenRouter, OpenAI, DeepSeek, Ollama
+exercised by this module: Anthropic, Gemini, Groq, xAI, OpenRouter, OpenAI,
-(local + cloud).
+DeepSeek, and Ollama (local and cloud).
 """
 import pytest
 

tests/test_search_routes_shim.py

@@ -1,11 +0,0 @@
-"""Regression test for the search route shim (slice 2j, #4082/#4071)."""
-
-import importlib
-
-import routes.search_routes as _shim_search  # noqa: F401
-
-
-def test_legacy_and_canonical_search_module_are_same_object():
-    legacy = importlib.import_module("routes.search_routes")
-    canonical = importlib.import_module("routes.search.search_routes")
-    assert legacy is canonical

tests/test_skill_format_timestamp.py

@@ -1,58 +0,0 @@
-"""Regression for issue #5697 — skill timestamps must not use ``datetime.utcnow()``.
-
-``_now_iso()`` builds the ``created`` value in skill frontmatter. ``utcnow()``
-returns a *naive* datetime and has been deprecated since Python 3.12, scheduled
-for removal. The replacement must stay timezone-aware while keeping the
-serialized ``YYYY-MM-DDTHH:MM:SSZ`` shape, so skill files written by older
-versions keep parsing.
-
-The UTC check matters on its own: a bare ``datetime.now()`` also produces the
-right shape, but emits local wall time, which would silently backdate or
-postdate skills for every user outside UTC.
-"""
-
-import os
-import re
-import time
-import warnings
-from datetime import datetime, timezone
-
-import pytest
-
-from services.memory.skill_format import _now_iso
-
-_ISO_Z = re.compile(r"^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$")
-
-
-def test_now_iso_keeps_serialized_shape():
-    assert _ISO_Z.match(_now_iso())
-
-
-def test_now_iso_emits_no_deprecation_warning():
-    with warnings.catch_warnings(record=True) as caught:
-        warnings.simplefilter("always")
-        _now_iso()
-    assert not [w for w in caught if issubclass(w.category, DeprecationWarning)]
-
-
-@pytest.mark.skipif(
-    not hasattr(time, "tzset"),
-    reason="time.tzset is unavailable on this platform",
-)
-def test_now_iso_is_utc_not_local_time():
-    """Pin UTC under a non-UTC local timezone, where the two visibly diverge."""
-    original_tz = os.environ.get("TZ")
-    os.environ["TZ"] = "Asia/Amman"  # UTC+3, never UTC
-    time.tzset()
-    try:
-        emitted = datetime.strptime(_now_iso(), "%Y-%m-%dT%H:%M:%SZ").replace(
-            tzinfo=timezone.utc
-        )
-        drift = abs((emitted - datetime.now(timezone.utc)).total_seconds())
-        assert drift < 60, f"timestamp is {drift}s off UTC — local time leaked in"
-    finally:
-        if original_tz is None:
-            os.environ.pop("TZ", None)
-        else:
-            os.environ["TZ"] = original_tz
-        time.tzset()

tests/test_tts_service_enforce_cache_limit.py

@@ -1,97 +0,0 @@
-import os
-import time
-from pathlib import Path
-import pytest
-
-# Adjust the import path if your file is directly in ./services instead of ./services/tts
-from services.tts.tts_service import TTSService
-
-def test_cache_under_limit(tmp_path, monkeypatch):
-    """Test that writing a file under the size limit does not trigger eviction."""
-    # Set a tiny limit: 100 bytes
-    monkeypatch.setenv("ODYSSEUS_TTS_CACHE_MAX_BYTES", "100")
-    
-    # Initialize service with pytest's temporary directory
-    service = TTSService(cache_dir=str(tmp_path))
-    
-    # Write a 40-byte file (under the 100-byte limit)
-    service._put_cache("test_key", b"x" * 40)
-    
-    # Verify the file was written and nothing was deleted
-    files = list(tmp_path.glob("*.*"))
-    assert len(files) == 1
-    assert sum(f.stat().st_size for f in files) == 40
-
-def test_cache_exceeds_limit_triggers_eviction(tmp_path, monkeypatch):
-    """Test that exceeding the limit evicts the oldest files down to 80% capacity."""
-    # Set limit to 100 bytes. 80% target capacity will be 80 bytes.
-    monkeypatch.setenv("ODYSSEUS_TTS_CACHE_MAX_BYTES", "100")
-    service = TTSService(cache_dir=str(tmp_path))
-    
-    # 1. Setup: Manually create two older files (40 bytes each)
-    file1 = tmp_path / "oldest.wav"
-    file2 = tmp_path / "middle.wav"
-    
-    file1.write_bytes(b"a" * 40)
-    file2.write_bytes(b"b" * 40)
-    
-    # Spoof timestamps so file1 is explicitly older than file2
-    now = time.time()
-    os.utime(file1, (now - 100, now - 100)) # 100 seconds ago
-    os.utime(file2, (now - 50, now - 50))   # 50 seconds ago
-    
-    # 2. Action: Write a 3rd file using the service method (40 bytes)
-    # Total cache is now 120 bytes, which exceeds 100.
-    # It should delete oldest (file1) to drop to 80 bytes (which matches the 80% target).
-    service._put_cache("newest", b"c" * 40)
-    
-    # 3. Assertions
-    # The newest file should exist (saved as .wav because it lacks MP3 magic bytes)
-    newest_file = tmp_path / "newest.wav"
-    
-    assert not file1.exists(), "The oldest file should have been evicted."
-    assert file2.exists(), "The middle file should still exist."
-    assert newest_file.exists(), "The newest file should have been saved."
-    
-    # Verify the final directory size is <= 80 bytes
-    total_size = sum(f.stat().st_size for f in tmp_path.glob("*.*"))
-    assert total_size <= 80
-
-def test_cache_limit_disabled(tmp_path, monkeypatch):
-    """Test that setting max bytes to 0 disables eviction."""
-    monkeypatch.setenv("ODYSSEUS_TTS_CACHE_MAX_BYTES", "0")
-    service = TTSService(cache_dir=str(tmp_path))
-    
-    # Write 3 large files that would normally trigger eviction
-    service._put_cache("file1", b"x" * 1000)
-    service._put_cache("file2", b"x" * 1000)
-    service._put_cache("file3", b"x" * 1000)
-    
-    # Ensure nothing was deleted
-    files = list(tmp_path.glob("*.*"))
-    assert len(files) == 3
-    assert sum(f.stat().st_size for f in files) == 3000
-
-def test_cache_eviction_handles_unlink_error_gracefully(tmp_path, monkeypatch):
-    """Test that if unlinking a file fails, _put_cache still succeeds without raising."""
-    service = TTSService(cache_dir=str(tmp_path))
-    service.max_cache_bytes = 50
-
-    # Create a file to evict
-    old_file = tmp_path / "old.wav"
-    old_file.write_bytes(b"x" * 40)
-
-    # Monkeypatch unlink on Path objects to simulate a PermissionError / file-lock failure
-    def mock_unlink(self_path):
-        raise OSError("Permission denied / file locked")
-
-    monkeypatch.setattr(Path, "unlink", mock_unlink)
-
-    # Writing a new file triggers eviction which encounters the mocked unlink error
-    try:
-        service._put_cache("new_key", b"y" * 40)
-    except Exception as e:
-        pytest.fail(f"_put_cache raised an exception during failed eviction: {e}")
-
-    # The new file should still be written successfully
-    assert (tmp_path / "new_key.wav").exists()