diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 03c5d5ea1..ecb768a81 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -1,8 +1,13 @@
-# Ouroboros CI — Three-tier cross-platform testing and release pipeline
+# Ouroboros CI — Four-tier cross-platform testing and release pipeline
 #
-# Tier 1: Every push to ouroboros / ouroboros-three-layer (code paths) → Ubuntu-only tests (~1 min)
-# Tier 2: Push to ouroboros-stable / manual / tag → Full 3-OS matrix (~5 min)
-# Tier 3: Tag v* → Full matrix + build artifacts + GitHub Release (~15 min)
+# Tier 1 (Quick):       Push to ouroboros (code paths)                                → Ubuntu-only tests (~1 min)
+# Tier 2 (Full):        Push to ouroboros-stable / manual / tag                       → Full 3-OS matrix          (~5 min)
+# Tier 2.5 (Integration): Push to main / ouroboros / ouroboros-stable / manual / tag  → Real-provider tests       (~2 min)
+# Tier 3 (Build+Release): Tag v*                                                       → PyInstaller + GitHub Release (~15 min)
+#
+# Tier 2.5 requires OPENROUTER_API_KEY / OPENAI_API_KEY / ANTHROPIC_API_KEY in
+# repository secrets and runs the `integration` pytest marker; locally these
+# tests are excluded by `addopts = -m 'not integration'` in pyproject.toml.
 
 name: CI
 
@@ -10,7 +15,7 @@ name: CI
 # This ensures tag pushes always fire (even if only VERSION/README changed).
 on:
   push:
-    branches: [ouroboros, ouroboros-three-layer, ouroboros-stable]
+    branches: [main, ouroboros, ouroboros-stable]
     paths:
       - 'ouroboros/**'
       - 'supervisor/**'
@@ -37,15 +42,12 @@ on:
 
 jobs:
   # ──────────────────────────────────────────────────────────────────
-  # Tier 1: Quick tests on Ubuntu (every push to ouroboros / ouroboros-three-layer)
+  # Tier 1: Quick tests on Ubuntu (every push to ouroboros)
   # ──────────────────────────────────────────────────────────────────
   quick-test:
     if: |
       github.event_name == 'push'
-      && (
-        github.ref == 'refs/heads/ouroboros'
-        || github.ref == 'refs/heads/ouroboros-three-layer'
-      )
+      && github.ref == 'refs/heads/ouroboros'
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -86,6 +88,42 @@ jobs:
       - name: Run tests
         run: python -m pytest tests/ -q --tb=short
 
+  # ──────────────────────────────────────────────────────────────────
+  # Tier 2.5: Integration tests against real provider APIs
+  # Triggered on push to main / ouroboros / ouroboros-stable, manual,
+  # or tag v*. Requires OPENROUTER_API_KEY / OPENAI_API_KEY /
+  # ANTHROPIC_API_KEY in repository secrets. The `integration` pytest
+  # marker (in pyproject.toml) controls inclusion via `-m integration`;
+  # within an included test file, missing-key skipping is done by per-
+  # test `@pytest.mark.skipif(not os.environ.get(KEY))` decorators (see
+  # tests/test_provider_integration.py). NOT a `needs:` of build/
+  # release: a provider outage must not block a tagged release.
+  # ──────────────────────────────────────────────────────────────────
+  integration-test:
+    if: |
+      github.event_name == 'workflow_dispatch'
+      || github.ref == 'refs/heads/main'
+      || github.ref == 'refs/heads/ouroboros'
+      || github.ref == 'refs/heads/ouroboros-stable'
+      || startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.10'
+          cache: 'pip'
+      - name: Install dependencies
+        run: |
+          pip install -r requirements.txt
+          pip install pytest
+      - name: Run integration tests
+        env:
+          OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+        run: python -m pytest tests/test_provider_integration.py -m integration -q --tb=short
+
   # ──────────────────────────────────────────────────────────────────
   # Tier 3: Build & Release (tag push only)
   # ──────────────────────────────────────────────────────────────────
@@ -138,8 +176,37 @@ jobs:
             artifact: zip
     runs-on: ${{ matrix.os }}
     env:
-      OUROBOROS_MANAGED_SOURCE_BRANCH: ouroboros-three-layer
+      OUROBOROS_MANAGED_SOURCE_BRANCH: ouroboros
       OUROBOROS_RELEASE_TAG: ${{ github.ref_name }}
+      # Apple signing secrets at JOB LEVEL with a per-matrix-shard guard.
+      #
+      # Step-level `if:` conditions can only read `env.*`, never `secrets.*`
+      # directly (GitHub Actions rejects the workflow with "Unrecognized
+      # named-value: 'secrets'"). See docs/DEVELOPMENT.md::"GitHub Actions:
+      # secrets in step-level if conditions".
+      #
+      # The `matrix.os == 'macos-latest' && ... || ''` GHA expression keeps
+      # the Apple signing/notarization values **scoped to the macOS shard
+      # only** — Linux and Windows shards (which run `build_linux.sh` and
+      # `build_windows.ps1` respectively, neither of which needs Apple
+      # creds) receive empty strings. This avoids exposing the signing
+      # material to non-macOS build subprocesses where it has no business
+      # being. When a secret is not configured even on macOS, the value
+      # is also empty string (not unset), and the gate `env.X != ''`
+      # evaluates false — the signing/notarization steps skip cleanly.
+      BUILD_CERTIFICATE_BASE64: ${{ matrix.os == 'macos-latest' && secrets.BUILD_CERTIFICATE_BASE64 || '' }}
+      P12_PASSWORD: ${{ matrix.os == 'macos-latest' && secrets.P12_PASSWORD || '' }}
+      KEYCHAIN_PASSWORD: ${{ matrix.os == 'macos-latest' && secrets.KEYCHAIN_PASSWORD || '' }}
+      APPLE_TEAM_ID: ${{ matrix.os == 'macos-latest' && secrets.APPLE_TEAM_ID || '' }}
+      APPLE_ID: ${{ matrix.os == 'macos-latest' && secrets.APPLE_ID || '' }}
+      APPLE_APP_SPECIFIC_PASSWORD: ${{ matrix.os == 'macos-latest' && secrets.APPLE_APP_SPECIFIC_PASSWORD || '' }}
+      # SIGN_IDENTITY is a forks-friendly override: when a fork configures
+      # a Developer ID secret whose CN differs from the upstream default
+      # (e.g. "Developer ID Application: <Other Name> (<OtherTeamID>)"),
+      # they set `SIGN_IDENTITY` as a repository secret and codesign in
+      # build.sh picks it up via `${SIGN_IDENTITY:-...}`. Same matrix.os
+      # guard so Linux/Windows shards never see it.
+      SIGN_IDENTITY: ${{ matrix.os == 'macos-latest' && secrets.SIGN_IDENTITY || '' }}
     steps:
       - uses: actions/checkout@v4
         with:
@@ -184,10 +251,49 @@ jobs:
         shell: pwsh
         run: .\scripts\download_python_standalone.ps1
 
-      # —— macOS build ——
+      # —— macOS: import signing certificate (only when ALL four signing
+      #         secrets are present at job level — see env: block above)
+      - name: Import Apple signing certificate
+        if: matrix.os == 'macos-latest' && env.BUILD_CERTIFICATE_BASE64 != '' && env.P12_PASSWORD != '' && env.KEYCHAIN_PASSWORD != '' && env.APPLE_TEAM_ID != ''
+        run: |
+          set -euo pipefail
+          CERTIFICATE_PATH="$RUNNER_TEMP/build_certificate.p12"
+          KEYCHAIN_PATH="$RUNNER_TEMP/app-signing.keychain-db"
+          # Always remove the .p12 on EXIT, including failure mid-import:
+          # `set -e` would otherwise abort before the trailing `rm -f` and
+          # leave the certificate blob on the runner until cleanup. The
+          # later `Cleanup keychain` step only handles the keychain itself.
+          trap 'rm -f "$CERTIFICATE_PATH"' EXIT
+          echo "${BUILD_CERTIFICATE_BASE64}" | base64 --decode > "$CERTIFICATE_PATH"
+          security create-keychain -p "${KEYCHAIN_PASSWORD}" "$KEYCHAIN_PATH"
+          security set-keychain-settings -lut 21600 "$KEYCHAIN_PATH"
+          security unlock-keychain -p "${KEYCHAIN_PASSWORD}" "$KEYCHAIN_PATH"
+          security import "$CERTIFICATE_PATH" -P "${P12_PASSWORD}" -A -t cert -f pkcs12 -k "$KEYCHAIN_PATH"
+          security list-keychain -d user -s "$KEYCHAIN_PATH"
+          security set-key-partition-list -S apple-tool:,apple: -k "${KEYCHAIN_PASSWORD}" "$KEYCHAIN_PATH" >/dev/null
+          security find-identity -v -p codesigning "$KEYCHAIN_PATH"
+
+      # —— macOS build (signed + optionally notarized when secrets are
+      #         present, otherwise unsigned). build.sh reads the same
+      #         env vars from the job-level env block above.
       - name: Build macOS app
         if: matrix.os == 'macos-latest'
-        run: OUROBOROS_SIGN=0 bash build.sh
+        run: |
+          if [ -n "${BUILD_CERTIFICATE_BASE64:-}" ] && [ -n "${P12_PASSWORD:-}" ] && [ -n "${KEYCHAIN_PASSWORD:-}" ] && [ -n "${APPLE_TEAM_ID:-}" ]; then
+            echo "Signing certificate detected — building with codesign + (optional) notarization"
+            bash build.sh
+          else
+            echo "No signing secrets — building unsigned (OUROBOROS_SIGN=0)"
+            OUROBOROS_SIGN=0 bash build.sh
+          fi
+
+      # —— macOS: cleanup keychain (always, even on build failure) so the
+      #         temporary signing material never persists across runs.
+      - name: Cleanup keychain
+        if: always() && matrix.os == 'macos-latest' && env.BUILD_CERTIFICATE_BASE64 != ''
+        run: |
+          KEYCHAIN_PATH="$RUNNER_TEMP/app-signing.keychain-db"
+          security delete-keychain "$KEYCHAIN_PATH" || true
 
       # —— Linux build ——
       - name: Build Linux binary
diff --git a/README.md b/README.md
index 49b3d57ab..3ba5ffb74 100644
--- a/README.md
+++ b/README.md
@@ -6,7 +6,7 @@
 [![macOS 12+](https://img.shields.io/badge/macOS-12%2B-black.svg)](https://github.com/joi-lab/ouroboros-desktop/releases)
 [![Linux](https://img.shields.io/badge/Linux-x86__64-orange.svg)](https://github.com/joi-lab/ouroboros-desktop/releases)
 [![Windows](https://img.shields.io/badge/Windows-x64-blue.svg)](https://github.com/joi-lab/ouroboros-desktop/releases)
-[![Version 5.0.0](https://img.shields.io/badge/version-5.0.0-green.svg)](VERSION)
+[![Version 5.1.0](https://img.shields.io/badge/version-5.1.0-green.svg)](VERSION)
 
 A self-modifying AI agent that writes its own code, rewrites its own mind, and evolves autonomously. Born February 16, 2026.
 
@@ -231,6 +231,37 @@ Output: `dist/Ouroboros-<VERSION>.dmg`
 configured local Developer ID identity; set `OUROBOROS_SIGN=0` for an unsigned
 local release. Unsigned builds require right-click → **Open** on first launch.
 
+#### Optional signing & notarization (env vars)
+
+`build.sh` honours these env overrides so the same script ships local,
+shared-machine, and CI builds without forking the script:
+
+| Env var | Effect |
+|---------|--------|
+| `OUROBOROS_SIGN=0` | Skip codesigning entirely (unsigned `.app` + `.dmg`). |
+| `SIGN_IDENTITY="Developer ID Application: <Name> (<TeamID>)"` | Override the codesign identity. Useful for forks whose Developer ID is not the upstream default. |
+| `APPLE_ID`, `APPLE_TEAM_ID`, `APPLE_APP_SPECIFIC_PASSWORD` | When all three are set, after codesign the DMG is submitted to Apple via `xcrun notarytool submit ... --wait` and stapled with `xcrun stapler staple` so receivers do not need right-click → **Open**. Missing any one falls back to "signed but not notarized" (no Apple-side ticket exists). |
+
+**Forks: enabling signed CI builds.** The CI release flow
+(`.github/workflows/ci.yml::build`) wires the build-script env vars above
+from GitHub repository secrets, plus a small set of CI-only secrets that
+import the Developer ID certificate into a temporary keychain on the
+macOS runner. To exercise the signed-build path in a fork, configure
+**all four** of the following as repository secrets (Settings → Secrets
+and variables → Actions): `BUILD_CERTIFICATE_BASE64` (base64-encoded
+`.p12`), `P12_PASSWORD`, `KEYCHAIN_PASSWORD` (an arbitrary passphrase
+the workflow uses for its temporary keychain), and `APPLE_TEAM_ID`. Add
+`APPLE_ID` + `APPLE_APP_SPECIFIC_PASSWORD` to additionally enable
+notarization. If your Developer ID identity differs from the upstream
+default, also set `SIGN_IDENTITY` (e.g.
+`Developer ID Application: <Your Name> (<YOUR_TEAM_ID>)`). With no
+Apple secrets configured the build job falls through to
+`OUROBOROS_SIGN=0 bash build.sh` and ships an unsigned DMG identical to
+v5.0.0 behaviour. See `docs/ARCHITECTURE.md` §8.1 and
+`docs/DEVELOPMENT.md::"GitHub Actions: secrets in step-level if conditions"`
+for the rationale (job-level `env:` mapping so step-level `if:` can read
+`env.*`; GHA rejects `secrets.*` in step `if:`).
+
 ### Linux (.tar.gz)
 
 ```bash
@@ -413,11 +444,11 @@ Full text: [BIBLE.md](BIBLE.md)
 
 | Version | Date | Description |
 |---------|------|-------------|
+| 5.1.0 | 2026-04-26 | **feat(chat+ci): selective port from PR #25 + chat bottom-fade layer fix.** (1) **Clipboard image paste** — `web/modules/chat.js` registers a `paste` listener on `#chat-input` that scans `e.clipboardData.items` for `image/*`, calls `getAsFile()`, wraps the blob as `File("clipboard-<unix-ts>.<ext>")`, and stages it through the same `pendingAttachment` slot the paperclip button uses (no inline upload — the file uploads when Send/Enter fires, with the same offline-WS guard). `e.preventDefault()` runs only when an image item is matched, so non-image clipboard payloads still paste natively. (2) **Browser-level mangling disabled on the chat textarea** — `#chat-input` gains `autocorrect="off" autocapitalize="off" spellcheck="false"` so code, identifiers, and slash-commands are not silently rewritten. (3) **Chat bottom gradient moved to its own layer** — previously `#chat-input-area`'s `background: linear-gradient(...)` painted directly behind the textarea, which made the lower edge of the input visually dissolve into the dense end of the gradient. `web/style.css` now strips the gradient/mask from `#chat-input-area` (which keeps `z-index: 5`), and a dedicated sibling element `<div class="chat-bottom-fade" aria-hidden="true">` (`position: absolute; bottom: 0; pointer-events: none; z-index: 4`) renders the same fade *below* the input. The textarea no longer sinks into its own backdrop. The mobile `@media (max-width: 640px)` block carries the safe-area-aware height for the new fade layer. (4) **Integration tier in CI (Tier 2.5)** — `.github/workflows/ci.yml` header now describes a Four-tier pipeline (Quick / Full / Integration / Build+Release); a new `integration-test` job runs `pytest tests/test_provider_integration.py -m integration` on `ubuntu-latest` against real provider keys when present as repository secrets. Triggered on push to `main` / `ouroboros` / `ouroboros-stable`, on `workflow_dispatch`, and on tag `v*`. Locally, the `integration` pytest marker plus `addopts = "-m 'not integration'"` in `pyproject.toml` excludes these tests from the default run so contributors do not accidentally burn provider tokens. (5) **Optional macOS code signing & notarization (Build tier)** — when `BUILD_CERTIFICATE_BASE64` / `P12_PASSWORD` / `KEYCHAIN_PASSWORD` / `APPLE_TEAM_ID` are configured as repository secrets, the build job creates a temporary keychain, imports the Developer ID certificate, runs `bash build.sh` (which signs `.app` and `.dmg` using the env-overridable `SIGN_IDENTITY`), and — when `APPLE_ID` + `APPLE_APP_SPECIFIC_PASSWORD` are also present — runs `xcrun notarytool submit ... --wait` followed by `xcrun stapler staple` so the DMG can be opened without right-click → **Open**. With no Apple secrets the build falls back to the unsigned path (`OUROBOROS_SIGN=0 bash build.sh`) — behaviour identical to v5.0.0. **Critical GHA detail**: signing secrets are mapped at the **build job's `env:` block, not at step level**, because GitHub Actions rejects `secrets.*` references inside step-level `if:` expressions ("Unrecognized named-value: 'secrets'"). Step `if:` conditions read `env.*` instead. This rule is now formalized in `docs/DEVELOPMENT.md::GitHub Actions: secrets in step-level if conditions`. A `Cleanup keychain` step with `if: always() && matrix.os == 'macos-latest' && env.BUILD_CERTIFICATE_BASE64 != ''` deletes the temporary keychain regardless of build outcome (the `matrix.os` gate keeps the bash-only `security delete-keychain` invocation off Linux/Windows shards). The Apple secrets in the build job's `env:` block are themselves wrapped in a `matrix.os == 'macos-latest' && ... || ''` GHA expression so they resolve to empty strings on non-macOS shards — the signing material is never exposed to `build_linux.sh` / `build_windows.ps1` subprocesses. (6) **Tests**: `tests/test_chat_logs_ui.py` gains three tests — `test_chat_input_disables_autocorrect`, `test_clipboard_paste_handler_exists`, and `test_chat_bottom_fade_is_separate_layer` (asserts `.chat-bottom-fade` exists with `pointer-events: none` and `z-index < 5`, that `#chat-input-area` no longer carries `linear-gradient`, and that the chat.js template inserts the dedicated `<div class="chat-bottom-fade">` sibling); `tests/test_build_scripts.py` gains a new `TestMacOSSigning` class with seven tests — `test_ci_signing_secrets_at_job_level`, `test_ci_uses_env_context_for_condition` (multi-line `if:` parser asserting no `secrets.*` ever appears in any `if:` block, step-level or job-level), `test_ci_import_gates_on_full_secret_set`, `test_ci_cleanup_keychain_step_present` (asserts the `Cleanup keychain` step runs `if: always() && matrix.os == 'macos-latest' && env.BUILD_CERTIFICATE_BASE64 != ''` so the bash-only `security delete-keychain` invocation never fires on Linux/Windows shards), `test_build_sh_signing_identity_env_override`, `test_build_sh_notarization_optional`, and `test_build_sh_stapler_failure_is_soft` (regression guard: `xcrun stapler staple` must be wrapped in `if/then/else` or paired with `\|\|` so a transient stapler failure under `set -e` becomes a warning instead of dropping the macOS DMG from the release); `tests/test_provider_integration.py` is added new with six tuple-aware tests (OpenRouter / OpenAI / Anthropic × {basic, isolation}) that handle the post-v4.44.0 `LLMClient.chat()` `(msg, usage)` return tuple plus Anthropic's list-of-blocks `content`. (7) **Branch consolidation**: `ouroboros-three-layer` is retired as a dev branch — `ouroboros` is now the single dev branch. `.github/workflows/ci.yml` (Tier 1 quick-test trigger + path-filter `branches:` list + build job's `OUROBOROS_MANAGED_SOURCE_BRANCH` default), `build.sh` / `build_linux.sh` / `build_windows.ps1` (each script's `${OUROBOROS_MANAGED_SOURCE_BRANCH:-...}` default), and the four affected test files (`tests/test_release_workflow.py`, `tests/test_launcher_sync.py`, `tests/test_git_ops_recovery.py`, `tests/test_build_repo_bundle.py` — 21 occurrences total) all switch from `ouroboros-three-layer` to `ouroboros`. Historical references in older changelog rows (v4.50.0-rc.7) and in `ouroboros/*` module comments about the *Phase 2/3 three-layer architecture refactor* are intentionally preserved — those describe the architectural refactor, not the dev branch name. The remote `managed/ouroboros-three-layer` branch is deleted in the same release; local `ouroboros` is re-tracked to `managed/ouroboros`. **Note on changelog rolloff**: the v4.50.0-rc.2 minor entry was rolled off proactively in this release to keep one slot below the P7 5-minor-row cap (with v5.1.0 added the table would have been at exactly 5 minors — at the cap, no warning, but no headroom for the next minor either). Its full body remains at git tag `v4.50.0-rc.2`. |
 | 5.0.0 | 2026-04-25 | **MAJOR — three-layer architecture + ClawHub Marketplace + visual skill widgets + direct pro core-patch lane.** Closes the four-month v4.50 RC chain (rc.1 through rc.9) as a single major release. **Three-layer skill architecture**: `ouroboros/contracts/` carries schema-versioned, runtime-checkable Protocols for `ToolContextProtocol`, `SkillManifest`, `PluginAPI` v1, `VALID_SKILL_PERMISSIONS` (`net`/`fs`/`subprocess`/`tool`/`route`/`ws_handler`/`widget`/`read_settings`), `VALID_EXTENSION_ROUTE_METHODS`, and `FORBIDDEN_SKILL_SETTINGS` (case-insensitive). External `type: script` skills load from `data/skills/{native,external}/`, run through `skill_exec` (sandboxed subprocess), and are gated on a fresh PASS verdict from tri-model `skill_review`. `type: extension` skills run in-process via `register(api)` with namespaced `register_tool`/`register_route`/`register_ws_handler`/`register_ui_tab`. **Runtime mode**: `OUROBOROS_RUNTIME_MODE=light` blocks every repo-mutation tool plus pattern-matched `run_shell` repo-mutating commands; `advanced` preserves normal evolutionary self-modification while blocking protected core/contract/release surfaces (`BIBLE.md`, safety files, `ouroboros/contracts/`, `.github/workflows/ci.yml`, build scripts, `scripts/build_repo_bundle.py`, `ouroboros/launcher_bootstrap.py`, `supervisor/git_ops.py`) via the shared `ouroboros/runtime_mode_policy.py` policy; `pro` can edit those protected paths on disk, but `repo_commit` still uses the normal triad + scope review before the protected diff lands. `claude_code_edit`, `repo_write`, `str_replace_editor`, and staged commit paths all use the same policy and emit `CORE_PATCH_NOTICE` for pro protected edits. **Review defaults**: commit triad default and scope review default move to `openai/gpt-5.5`; deep self-review uses `openai/gpt-5.5-pro`; UI placeholders/docs/tests synchronized. Review context hygiene: `build_full_repo_pack` redacts inline secret-shaped values, scope review injects canonical docs (`BIBLE.md`, `DEVELOPMENT.md`, `ARCHITECTURE.md`, `CHECKLISTS.md`) exactly once. Managed-repo safety blocks `rescue_and_reset` when snapshot/diff capture fails. **ClawHub Marketplace** (new in v5): Skills page → Marketplace sub-tab with debounced search, sort, filters (Official only / OS list), result cards with installed/update/official/plugin badges, detail modal with version-pin select + provenance strip + translated-manifest table + adapter blockers/warnings + original SKILL.md rendered through vendored marked@12.0.2 + DOMPurify@3.1.0 (no scripts/iframes/forms, http(s) only). Install / update / uninstall pipeline at `ouroboros/marketplace/{clawhub,fetcher,adapter,install,provenance}.py` with hostname allowlist (clawhub.ai + localhost), redirect refusal, 4 MB JSON cap, 50 MB archive cap, text-only allowlist, sensitive-filename refuse, loadable-binary refuse, symlink refuse, path-traversal refuse, zip-bomb defense (bounded `src.read(cap+1)`), refusal of OpenClaw `metadata.openclaw.install` specs and Node/TypeScript plugins, case-insensitive env-key denylist. Original `SKILL.md` preserved as `SKILL.openclaw.md`; provenance written atomically at `data/state/skills/<name>/clawhub.json` (slug, sha256, registry_url, license, homepage, primary_env, adapter warnings). Auto tri-model review fires immediately after install. Path-traversal hardening on uninstall (HTTP-boundary `_validate_path_param_name` + `_sanitize_skill_name` round-trip + `target.relative_to(root)` containment + required `.clawhub.json` provenance gate). Same-FS staging via `<clawhub-root>/.staging/` for atomic rename. Settings → Behavior → ClawHub Marketplace opt-in checkbox + registry URL field; default off (HTTP surface 403 until enabled). **Visual skill widgets** (new in v5): `weather` is now `type: extension` with a real visual widget that renders inline on the Skills tab — city input + temperature + humidity + wind, fetched live via the extension's own `register_route("forecast")` against `wttr.in` (host allowlist + cross-host redirect refusal + `asyncio.to_thread` to keep the event loop responsive), with the result also exposed to the agent as `ext.weather.fetch`. Permissions `[net, tool, route, widget]`. Inline-widget host pattern via `web/modules/skills.js::registerWidgetRenderer(name, fn)` + `mountSkillWidgets(root)` lets the launcher ship per-skill JS that renders into `data-skill-widget` mount-points. **Native-skill upgrade migration banner** (operator-facing): `_record_skill_upgrade_migration` + `GET /api/migrations` + `POST /api/migrations/<key>/dismiss` + Skills-tab banner explain when the launcher silently rewrites a seeded skill type. **Interface updates**: Skills tab split into Installed / Marketplace tabs; Installed cards show `source` badge (clawhub / native / external / user repo), provenance strip (slug / sha256 / license / homepage / registry, gated split into always-safe + registry-controlled), adapter-warning collapsibles, version-drift warn badge, Update / Uninstall buttons for clawhub-installed skills. Chat top header and bottom input scrim gradients now fade fully to transparent at the inner edge with `mask-image` masking the blur in step (no visible step against the transcript); the 24px ambient halo around `#chat-input` was removed (focus ring preserved). Mobile responsive layout for narrow viewports (Android/iOS) — `@media (max-width: 640px)` block converts `#nav-rail` to bottom bar, switches `.chat-page-header` to static positioning, collapses Costs/Evolution/Settings multi-column grids, routes `--vvh` through Evolution to handle iOS soft-keyboard shrink. Onboarding wizard copy reflects `data/skills/` layout. Owner `/restart` writes one-shot `owner_restart_no_resume.flag`; Settings keeps lightweight draft continuity with `Unsaved changes.` indicator; `/api/model-catalog` uses native async `httpx.AsyncClient`. **Bug fixes** (rolled in from rc.2 → rc.9): three-layer refactor compatibility (Windows CI, sandbox, skill_exec, PEP 440 pre-release tags), CI build-job tag-object fetch (annotated tag materialisation via `fetch-tags: true` + `git fetch --tags --force`), bundle-purge of accidentally-vendored payloads (Python.framework/, webview/, jsonschema_specifications/, etc. — total reduction ~14 MB, 37 files), per-skill version-aware bootstrap resync (deletion-sticky), pyyaml frontmatter parser upgrade for nested `metadata.openclaw.*`. **Adversarial review**: three cycles of multi-model adversarial review (Gemini + GPT + Opus critics) plus contract tests; cycle 1 surfaced 21 findings (incl. critical XSS via marked, critical path traversal in uninstall, critical zip-bomb DoS), cycle 2 surfaced 4 follow-ups (incl. high `{ once: true }` listener bug + high test-pollution), cycle 3 verified clean. **Migration**: weather skill changed from `type: script` (subprocess) to `type: extension` (in-process); manifest version bumped 0.1.0 → 0.2.0; the launcher's per-skill version-aware resync replaces the data-plane copy on first launch (durable enabled / review state preserved); a one-shot Skills-tab banner surfaces the change. Custom user edits to `data/skills/native/weather/` are overwritten because native skills are launcher-owned (`.seed-origin` is the explicit ownership signal); custom alternatives belong in `data/skills/external/`. Marketplace surface is opt-in via `OUROBOROS_CLAWHUB_ENABLED=true`; unchanged for users who don't want it. **Note on changelog rolloff**: the entire v4.50 RC chain (rc.1 → rc.9) is collapsed into this v5.0.0 row; their full bodies remain at git tags `v4.50.0-rc.{1..7}`. |
 | 4.50.0-rc.8 | 2026-04-24 | **fix(ui): mobile responsive layout for narrow viewports (Android/iOS).** `web/style.css` + `web/settings.css` gain a `@media (max-width: 640px)` breakpoint that fixes multiple mobile issues without touching desktop layout. (1) `#nav-rail` converts from an 80px left sidebar to a horizontal bottom bar (`position: fixed; bottom: 0; flex-direction: row`) with `padding-bottom: calc(6px + env(safe-area-inset-bottom, 0px))` for the iOS home-indicator, `overflow-x: auto` horizontal scroll for many nav items, and `backdrop-filter: blur(12px)` glassmorphism matching the existing design system. `#content` correspondingly drops its `padding-left: 84px` and gains `padding-bottom: calc(62px + env(safe-area-inset-bottom, 0px))` to clear the bar. (2) `.chat-page-header` switches from `position: absolute` overlay to `position: static` on mobile — this was the root cause of the first chat message being hidden behind the semi-transparent gradient once the action-button row wraps to 2+ rows at narrow widths; the `#chat-messages` top padding is reduced from the desktop 56px (absolute-header clearance) to 12px since the header now takes its own vertical space. (3) Multi-column grids collapse to single-column: `.costs-stats-grid` (3→1), `.costs-tables-grid` (2→1), `.costs-budget-fields` (2→1), `.evo-versions-cols` (flex-row→flex-column). (4) `.evolution-container` height changes from `calc(100vh - 120px)` to `calc(var(--vvh) - 120px)` — previously it used `100vh` which on iOS/Android ignored the soft-keyboard viewport shrink; `app.js` already maintains `--vvh` via `visualViewport`, so the fix is routing the same contract through Evolution. (5) Base rule `.form-field input, .form-field select` gains `max-width: 100%` so the hardcoded `width: 320px` never overflows narrow containers. (6) Minor tightening: `#page-skills`, `.logs-filters`, `#log-entries`, `.costs-scroll` get reduced padding; `.settings-shell`, `.settings-tabs`, `.settings-provider-card` summary/body get a 640px-specific padding reduction in `settings.css`. `.chat-header-btn` padding drops 7px/14px → 5px/10px and font 12px → 11px on mobile. CSS is intentionally split into two `@media (max-width: 640px)` blocks — one placed early in `style.css` for selectors whose base rule appears before it, one appended at the end for selectors defined later. This pattern avoids `!important` since media-query rules have the same specificity as base rules and must come later in source order to win; a comment in `style.css` documents the rationale. The split incidentally fixes a latent bug in the previous single mobile block: the old `#chat-input-area { padding-bottom: env(safe-area-inset-bottom) }` override lived before the base `#chat-input-area` definition in the same file and was silently overridden on desktop browsers — the rule now lives in the late block and takes effect. Tested manually in a browser harness at `390×844` (iPhone 12 Pro) and `360×740` (small Android) across all 8 pages. Scope review (Claude Opus 4.6) passed all 8 items PASS. Triad blocked initially on `version_bump` (all three models) and `self_consistency` (gpt-5.4 only) — this rc.8 pre-release addresses both: VERSION bump + `pyproject.toml` PEP-440 rename + README badge + Version History row + `docs/ARCHITECTURE.md` header version bump + §3 (navigation description) and §3.1 (chat header + mobile-keyboard-safety bullet) mobile notes so the whitelisted Behavioural Documentation surface stays truthful for the mobile case. No JS, HTML, server, or tool changes; no new files; no VERSION-gated feature additions — just the mobile polish described above. **Note on changelog rolloff**: the v4.48.0 minor entry is rolled off in this release to respect the P7 5-minor-row cap. Its full body remains at git tag `v4.48.0`. |
 | 4.50.0-rc.7 | 2026-04-21 | **chore(repo): purge accidentally vendored payloads and scrub stale skip-list references.** Removes seven path groups that were accidentally committed from an `.app` / site-packages dump on the initial `Initial commit from app bundle` seed (both on `main` and on `ouroboros-three-layer`, via the Phase-5 `import build artifacts from main` commit) and carried through every subsequent RC without ever being consumed: top-level `Python` Mach-O binary; `Python.framework/` (8 files — all three `Python` Mach-O copies byte-identical, SHA256 `f38037091bec48d8bc18b87a5b2d127f83f6fed980182a635d148bbda565578f`); `jsonschema/benchmarks/issue232/issue.json` (lone benchmark fixture, not a vendored package); `jsonschema_specifications/` (20 upstream-`jsonschema-specifications` metaschemas that pip would materialize under `python-standalone/site-packages/` anyway); `certifi/py.typed` (empty PEP 561 marker with no accompanying package); `webview/` (5 pywebview internal JS helpers — `api.js`, `customize.js`, `finish.js`, `lib/dom_json.js`, `lib/polyfill.js` — that only live at runtime inside `_MEIPASS/webview/lib/` via PyInstaller's collected pywebview and never in the source tree); and the byte-identical duplicate `assets/logo.jpg` (SHA256 `0d7d43ef596d27e72f9b18feb175f8aaebc945137ab87e796606d9a2170e5b3d`, same as `web/logo.jpg`, which is the single source of truth for the `/static/logo.jpg` mount via `server.py::Mount("/static", NoCacheStaticFiles(directory=web_dir))` and is consumed by `web/modules/about.js`). Total working-tree reduction: ~14 MB, 37 files, 6595 lines. Every removed path was independently audited against `Ouroboros.spec` (not in `datas`/`binaries`/`hiddenimports`/`collect_all`), `build.sh`/`build_linux.sh`/`build_windows.ps1`/`Dockerfile`, `scripts/download_python_standalone.{sh,ps1}` (these produce `python-standalone/` only — never `Python.framework` at repo root), `launcher.py::_find_embedded_python`, `ouroboros/platform_layer.py::embedded_python_candidates` (resolves only under `python-standalone/`), `ouroboros/launcher_bootstrap.py`, `server.py`, and the full `tests/` tree — zero consumers found beyond the skip-list strings themselves. Defensive skip-list entries are also dropped: `ouroboros/tools/review_helpers.py::_FULL_REPO_SKIP_DIR_PREFIXES` (removed: `webview/`, `jsonschema/`, `jsonschema_specifications/`, `Python.framework/`, `certifi/`, plus the hardcoded bare-`Python` special case in the same file), `ouroboros/deep_self_review.py::_SKIP_DIR_PREFIXES` (removed: same five prefixes), `tests/test_max_tokens_constants.py::test_full_repo_pack_excludes_junk_dirs` (asserts only `assets/` + `tests/` now), `tests/test_deep_self_review.py::TestSkipDirPrefixes::test_webview_dir_excluded` (removed). `docs/ARCHITECTURE.md` excludes-list sections updated to match. No runtime behaviour change; no feature added or removed; the packaged app continues to bundle the embedded CPython via `python-standalone/` at build time exactly as before. `.gitignore` additionally guards against recurrence of the same dump-into-source-tree bug: `/Python`, `/Python.framework/`, `/webview/`, `/jsonschema/`, `/jsonschema_specifications/`, `/certifi/` are now root-anchored ignore entries, plus the `.review_*.py` pattern for standalone review-runner scripts. The v4.50.0-rc.6 Version History row is also repaired: two embedded pipe separators inside the description cell (concatenating rc.5 + rc.4 + rc.3 bodies) were interpreted by Markdown as table-column delimiters and rendered the row with extra cells; they are now `\|`-escaped so the row is a single valid three-column entry. Both extra tweaks were surfaced as scope-review advisory findings and are addressed in-place. **Note on changelog rolloff**: the v4.47.0 minor entry is rolled off in this release to respect the P7 5-minor-row cap. Its full body remains at git tag `v4.47.0`. |
 | 4.50.0-rc.6 | 2026-04-24 | **fix(ci): rc.5 + CI build-job tag-object fetch.** Same body as rc.5 plus a `.github/workflows/ci.yml` fix. rc.5's CI run got all 3 OS full-test green and release-preflight green, then failed at the build step's annotated-tag guard with `ERROR: packaging requires annotated git tag v4.50.0-rc.5 (got 'commit')`. Root cause: `actions/checkout@v4` on the build job fetched the tag ref but resolved it as a lightweight pointer to the commit, not the annotated tag object. `fetch-depth: 0` alone was insufficient on v4. Fix adds `fetch-tags: true` to the build-job checkout and a defense-in-depth `git fetch origin --tags --force` step immediately after, so the annotated tag object is guaranteed materialized before `build.sh` / `build_linux.sh` / `build_windows.ps1` run `git cat-file -t refs/tags/<tag>`. No production code change. rc.5's tag remains on origin as another failed / un-released tag-reference. **Note on changelog rolloff**: the prior rc.5 Version History row collapses into this rc.6 entry because rc.5 never produced a public pre-release. \| Same body as rc.4 plus `ouroboros/review.py::MAX_TOTAL_FUNCTIONS` raised 1350 → 1450 and `server.py` added to `GRANDFATHERED_OVERSIZED_MODULES` (currently 1659 lines, 59 over the 1600 cap). Phases 3–6 actually shipped a lot of code that rc.2 never carried: new `ouroboros/contracts/plugin_api.py`, new `extensions_api.py` + `extension_loader.py`, new `scripts/build_repo_bundle.py` with tag-verification helpers, new staging logic, onboarding/settings/runtime-mode route expansion in `server.py`. rc.4's tag-push CI run broke on `tests/test_smoke.py::test_no_oversized_modules` + `::test_function_count_reasonable` because those counts grew past the previous ceilings. The ceiling bump is consistent with the v4.40→v4.47 pattern where each phase raised `MAX_TOTAL_FUNCTIONS` by ~50-100 as scope landed. A split of `server.py` (candidate: extract onboarding/settings HTTP leg into `ouroboros/server_ui.py`) is deferred to a dedicated structural refactor. rc.4's tag remains on origin as another failed / un-released tag-reference. **Note on changelog rolloff**: the prior rc.4 Version History row collapses into this rc.5 entry because rc.4 never produced a public pre-release. \| Carries the full rc.3 re-audit scope (extension runtime SSOT, staged-import + symlink-confinement, annotated-release-tag guards in `build.sh`/`build_linux.sh`/`build_windows.ps1` and `scripts/build_repo_bundle.py`, PEP-440 canonical alpha/beta spelling, onboarding preservation of `OPENAI_BASE_URL`/`OPENAI_COMPATIBLE_*`/`CLOUDRU_FOUNDATION_MODELS_BASE_URL`, `list_non_core_tools()` ext.* merge, workers.init pulling branch names from `_runtime_branch_defaults()`, instruction-skill body-only `---` tolerance, `__extension_imports/` and release-tag-prereq docs, `VALID_EXTENSION_ROUTE_METHODS` added to the frozen contract table in `docs/ARCHITECTURE.md`, BIBLE.md / `prompts/SYSTEM.md` release invariant now splitting author-facing spelling from PEP 440 canonical form, and `prompts/SYSTEM.md` Immutable Safety Files list mirroring `SAFETY_CRITICAL_PATHS` exactly). The rc.3 tag CI run failed because the tag-push job inherited `GITHUB_REF_NAME=v4.50.0-rc.3` / `GITHUB_REF_TYPE=tag` globally, and `tests/test_build_repo_bundle.py` + `tests/test_launcher_sync.py` subprocessed `scripts/build_repo_bundle.py` without scrubbing those env vars — `_resolve_release_tag` then saw both the env-bled tag and the temp repo's local tag and refused with `Multiple release tags point at HEAD`. rc.4 fixes that by scrubbing `OUROBOROS_RELEASE_TAG`, `GITHUB_REF`, `GITHUB_REF_TYPE`, `GITHUB_REF_NAME` via a shared `_scrubbed_env()` helper in both test modules (production code unchanged; a real CI tag-push on the real checkout still correctly resolves the tag because HEAD matches). rc.3's tag remains on origin as a failed/un-released tag-reference with no artifacts attached; the full pre-release ships under `v4.50.0-rc.4`. **Note on changelog rolloff**: the v4.50.0-rc.3 entry collapses into this rc.4 entry because rc.3 never produced a public pre-release. |
-| 4.50.0-rc.2 | 2026-04-21 | **feat(runtime-mode): Phase 6 of the three-layer refactor — light-mode blanket sandbox.** `ouroboros/tools/registry.py::ToolRegistry.execute` reads `ouroboros.config.get_runtime_mode()` on every call and gates repo-mutation tools on the value: `light` → blanket block on every repo-mutation tool (`repo_write`, `repo_write_commit`, `repo_commit`, `str_replace_editor`, `claude_code_edit`, `revert_commit`, `pull_from_remote`, `restore_to_head`, `rollback_to_target`, `promote_to_stable`) with a `LIGHT_MODE_BLOCKED` sentinel, PLUS a pattern-matched block on `run_shell` commands that look like repo mutations (`git commit`/`git add`/`git push`/…, file redirection `>` `>>`, `rm -`, `mv `, `mkdir `, `python …open(…,'w')…`, etc.) so the `light` mode stays consistent even for the shell tool which is not a pure-mutation surface; `advanced` → current behaviour (safety-critical paths still blocked by the hardcoded sandbox); `pro` → accepted as a forward-compatible value but currently behaves identically to `advanced` at the enforcement gate. **Pro mode intent vs. ship status**: a consistent pro-mode core-patch lane requires plumbing `runtime_mode` through every enforcement layer (`ToolRegistry.execute` + per-handler sandbox in `ouroboros/tools/git.py` + the post-`claude_code_edit` safety-critical revert in the same file), which would expand the reviewed patch surface well beyond what Phase 6 could safely land. The opt-in stays documented in Settings → Behavior → Runtime Mode so future phases can relax the gate; actual core-file changes today still flow through the operator-driven `git_pr.py` workflow, not an auto-PR lane. `tests/test_runtime_mode_gating.py` pins the enforcement: every repo-mutation tool returns `LIGHT_MODE_BLOCKED` under `light`; read-only tools and `git status`-style shell invocations are unaffected; `advanced` still blocks safety-critical writes; `pro` behaves like `advanced` at the sandbox gate until the full pro lane arrives. This closes the three-layer refactor as scoped: Phase 1 froze the ABI, Phase 2 plumbed the `OUROBOROS_RUNTIME_MODE` axis, Phases 3–5 built the external skill surface + extensions + UI, and Phase 6 wires `light` into the runtime enforcement point so switching the axis to `light` has real teeth. **Note on changelog rolloff**: the v4.45.0 minor entry (Phase 1 — frozen contracts) was rolled off in this release to respect the P7 5-minor-row cap. Its full body remains at git tag `v4.45.0`. |
 | 4.42.4 | 2026-04-20 | **fix: CI always-red + post-commit CI status reporting.** `tests/test_phase7_pipeline.py::TestBypassPathTestsRun::test_non_bypass_path_does_not_run_preflight_here` was failing on CI because the test didn't mock `ANTHROPIC_API_KEY` — CI machines have no key, causing the auto-bypass path to fire and `assert preflight_count == 0` to fail. Fix: `monkeypatch.setenv("ANTHROPIC_API_KEY", "sk-ant-test-sentinel")`. Also adds `_check_ci_status_after_push` in `git.py`: after every successful push (when `GITHUB_TOKEN` + `GITHUB_REPO` are configured), queries GitHub Actions API **filtered by `head_sha` of the just-pushed commit** and appends a CI status note — ✅ passed / ⏳ not yet registered or in progress / ⚠️ FAILED with job+step name and URL. SHA filtering prevents reporting stale results from a previous push during the GitHub registration window. 14 new tests: 10 in `tests/test_ci_tool.py::TestCheckCiStatusAfterPush` (server-side `head_sha=` API param verified, stale-SHA defense-in-depth, cancelled surfaces as ⚠️, jobs-fetch error still warns, network error, no-token) + 4 in `TestCiStatusWiring` (wiring for both `_repo_commit_push` and `_repo_write_commit`). |
 | 4.42.3 | 2026-04-20 | **fix: increase post-commit test timeout from 30s to 180s.** `ouroboros/tools/git.py::_run_pre_push_tests` was timing out at 30s on the full ~2100-test suite (which takes ~2 min), producing false `TESTS_FAILED` reports after every successful commit. Timeout raised to 180s. Regression guard added: `tests/test_smoke.py::TestPrePushGate::test_pre_push_tests_timeout_is_sufficient` (AST-based, asserts timeout ≥ 180s). |
 | 4.42.2 | 2026-04-20 | **docs: process checklists for coupled-surface propagation.** `docs/CHECKLISTS.md` Pre-Commit Self-Check gains rows 9–12: build-script/browser cross-surface doc sync, `commit_gate.py` coupled surfaces, VERSION+pyproject update ordering, JS inline-style ban with grep recipe. `prompts/SYSTEM.md` "Pre-advisory sanity check" updated to 12-row count; "Coupled-surface rules" added as a brief SSOT reference. `docs/DEVELOPMENT.md` "No inline styles in JS" explicitly marks `.style.*` assignments as a REVIEW_BLOCKED finding and adds a pre-staging grep recipe. No runtime code changes. |
diff --git a/VERSION b/VERSION
index 0062ac971..831446cbd 100644
--- a/VERSION
+++ b/VERSION
@@ -1 +1 @@
-5.0.0
+5.1.0
diff --git a/build.sh b/build.sh
index 218179481..06e66b24a 100644
--- a/build.sh
+++ b/build.sh
@@ -1,11 +1,14 @@
 #!/bin/bash
 set -e
 
-SIGN_IDENTITY="Developer ID Application: Ian Mironov (WHY6PAKA5V)"
-NOTARYTOOL_PROFILE="ouroboros-notarize"
+# Signing identity: env override wins so CI runners (which import a temporary
+# Developer ID via `security import` + `security set-key-partition-list`) can
+# point at whatever identity matches their imported certificate without
+# editing this file. Local dev keeps the historical default identity.
+SIGN_IDENTITY="${SIGN_IDENTITY:-Developer ID Application: Ian Mironov (WHY6PAKA5V)}"
 ENTITLEMENTS="entitlements.plist"
 SIGN_MODE="${OUROBOROS_SIGN:-1}"
-MANAGED_SOURCE_BRANCH="${OUROBOROS_MANAGED_SOURCE_BRANCH:-ouroboros-three-layer}"
+MANAGED_SOURCE_BRANCH="${OUROBOROS_MANAGED_SOURCE_BRANCH:-ouroboros}"
 RELEASE_TAG="v$(tr -d '[:space:]' < VERSION)"
 
 APP_PATH="dist/Ouroboros.app"
@@ -125,6 +128,55 @@ if [ "$SIGN_MODE" != "0" ]; then
     codesign -s "$SIGN_IDENTITY" --timestamp "$DMG_PATH"
 fi
 
+# Optional notarization: only fires when codesign already ran AND the three
+# notarytool credentials are present in env. This way unsigned builds skip
+# the whole notarization path, and signed-but-unconfigured builds (no Apple
+# ID configured for notarization) still ship cleanly — they just need
+# right-click → Open on first launch on receiver machines.
+#
+# A single enum tracks the outcome so the final summary cascade can
+# distinguish all four cases without contradiction:
+#   * success         — notarytool submit AND stapler staple both succeeded
+#   * staple_failed   — notarytool submit OK; stapler failed (Gatekeeper
+#                       fetches the ticket online; DMG is genuinely notarized)
+#   * submit_failed   — notarytool submit failed (DMG is signed only)
+#   * unconfigured    — Apple credentials not set (signed-only OR unsigned)
+NOTARIZE_OUTCOME="unconfigured"
+if [ "$SIGN_MODE" != "0" ] \
+        && [ -n "${APPLE_ID:-}" ] \
+        && [ -n "${APPLE_TEAM_ID:-}" ] \
+        && [ -n "${APPLE_APP_SPECIFIC_PASSWORD:-}" ]; then
+    echo ""
+    echo "=== Notarizing DMG (Apple ID: $APPLE_ID) ==="
+    # `--wait` blocks until Apple finishes the notarization scan so the
+    # subsequent `xcrun stapler staple` always operates on a finalized ticket.
+    # A submit failure is treated as a soft warning (DMG is signed; release
+    # ships with a clear log line) rather than a hard build abort, so an
+    # Apple-side outage / wrong-credential typo never silently drops the
+    # macOS artifact from the GitHub Release.
+    if xcrun notarytool submit "$DMG_PATH" \
+            --apple-id "$APPLE_ID" \
+            --team-id "$APPLE_TEAM_ID" \
+            --password "$APPLE_APP_SPECIFIC_PASSWORD" \
+            --wait; then
+        echo "--- Stapling notarization ticket ---"
+        # Stapler hits Apple's CDN separately and can fail transiently after
+        # a successful notarytool submission. Treat that as a soft warning
+        # too: the DMG is still signed + notarized, Gatekeeper will fetch
+        # the ticket online on first launch (slower but functional). Without
+        # this guard `set -e` would abort the script.
+        if xcrun stapler staple "$DMG_PATH"; then
+            NOTARIZE_OUTCOME="success"
+        else
+            NOTARIZE_OUTCOME="staple_failed"
+            echo "WARNING: stapler staple failed — DMG is notarized but ticket not embedded; receivers may briefly need right-click → Open until Apple's ticket propagates."
+        fi
+    else
+        NOTARIZE_OUTCOME="submit_failed"
+        echo "WARNING: notarytool submit failed — DMG is signed but not notarized; verify APPLE_ID / APPLE_TEAM_ID / APPLE_APP_SPECIFIC_PASSWORD are correct or check the notarytool log above."
+    fi
+fi
+
 echo ""
 echo "=== Done ==="
 if [ "$SIGN_MODE" != "0" ]; then
@@ -134,4 +186,27 @@ else
     echo "Unsigned app: $APP_PATH"
     echo "Unsigned DMG: $DMG_PATH"
 fi
-echo "(Not notarized — users need right-click → Open on first launch)"
+case "$NOTARIZE_OUTCOME" in
+    success)
+        echo "(Notarized + stapled — no right-click → Open required on first launch)"
+        ;;
+    staple_failed)
+        echo "(Notarized but ticket not stapled — Gatekeeper will fetch the ticket online; receivers need internet on first launch)"
+        ;;
+    submit_failed)
+        echo "(Signed but notarytool submit failed — DMG was not accepted by Apple; check the WARNING above for details)"
+        ;;
+    unconfigured)
+        if [ "$SIGN_MODE" != "0" ]; then
+            echo "(Signed but not notarized — set APPLE_ID / APPLE_TEAM_ID / APPLE_APP_SPECIFIC_PASSWORD to enable notarization)"
+        else
+            echo "(Not notarized — users need right-click → Open on first launch)"
+        fi
+        ;;
+    *)
+        # Defensive default: a future enum value added to NOTARIZE_OUTCOME
+        # without a matching arm would otherwise silently print no summary
+        # line. Surface it loudly so the bug is easy to find.
+        echo "(Unknown notarization outcome: '$NOTARIZE_OUTCOME' — please report; likely a missing case arm in build.sh)"
+        ;;
+esac
diff --git a/build_linux.sh b/build_linux.sh
index 7c91fdcef..fb3771ace 100644
--- a/build_linux.sh
+++ b/build_linux.sh
@@ -3,7 +3,7 @@ set -e
 
 VERSION=$(tr -d '[:space:]' < VERSION)
 ARCHIVE_NAME="Ouroboros-${VERSION}-linux-$(uname -m).tar.gz"
-MANAGED_SOURCE_BRANCH="${OUROBOROS_MANAGED_SOURCE_BRANCH:-ouroboros-three-layer}"
+MANAGED_SOURCE_BRANCH="${OUROBOROS_MANAGED_SOURCE_BRANCH:-ouroboros}"
 RELEASE_TAG="v${VERSION}"
 
 PYTHON_CMD="${PYTHON_CMD:-python3}"
diff --git a/build_windows.ps1 b/build_windows.ps1
index 1c955d1da..18235af5c 100644
--- a/build_windows.ps1
+++ b/build_windows.ps1
@@ -5,7 +5,7 @@ $ErrorActionPreference = "Stop"
 
 $Version = (Get-Content VERSION).Trim()
 $ArchiveName = "Ouroboros-${Version}-windows-x64.zip"
-$ManagedSourceBranch = if ($env:OUROBOROS_MANAGED_SOURCE_BRANCH) { $env:OUROBOROS_MANAGED_SOURCE_BRANCH } else { "ouroboros-three-layer" }
+$ManagedSourceBranch = if ($env:OUROBOROS_MANAGED_SOURCE_BRANCH) { $env:OUROBOROS_MANAGED_SOURCE_BRANCH } else { "ouroboros" }
 $ReleaseTag = "v$Version"
 
 Write-Host "=== Building Ouroboros for Windows (v${Version}) ==="
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index bcdb60e91..82f6127a4 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -1,4 +1,4 @@
-# Ouroboros v5.0.0 — Architecture & Reference
+# Ouroboros v5.1.0 — Architecture & Reference
 
 This document describes every component, page, button, API endpoint, and data flow.
 It is the single source of truth for how the system works. Keep it updated.
@@ -109,7 +109,7 @@ server.py (Starlette+uvicorn) ← HTTP + WebSocket on configurable host:port (de
       └── platform_layer.py    ← Cross-platform process/path/locking helpers
 
 # Build & CI (not part of runtime)
-.github/workflows/ci.yml     ← Three-tier CI (quick/full/release)
+.github/workflows/ci.yml     ← Four-tier CI (quick / full / integration / build+release)
 build.sh                      ← macOS build (PyInstaller → .dmg)
 build_linux.sh                ← Linux build (PyInstaller → .tar.gz)
 build_windows.ps1             ← Windows build (PyInstaller → .zip)
@@ -316,7 +316,8 @@ Navigation is a left sidebar with 8 pages (Chat, Files, Logs, Costs, Evolution,
   Driven by WebSocket connection state, typing events, and live task state.
 - **Header controls**: compact buttons for `/evolve`, `/bg`, `/review`, `/restart`, `/panic` — the canonical location for runtime controls. The chat header is a floating transparent overlay (`position: absolute`, gradient fade with a non-zero opacity floor plus backdrop blur) so messages scroll beneath it on desktop without text reading through the header labels. On narrow viewports (`@media (max-width: 640px)`) `.chat-page-header` switches to `position: static` with a transparent background so it claims its own vertical space — a wrapped row of action buttons never hides the first chat message under the gradient; the `#chat-messages` top padding is correspondingly reduced from `56px` (absolute-header clearance) to `12px`.
 - **Budget pill**: compact amber pill in the header showing `$spent / $limit` with a mini progress bar, updated from `/api/state` polling every 3 seconds.
-- **Message input**: absolute-positioned frosted-glass overlay anchored to the bottom of the chat page (`position: absolute; bottom: 0`). Contains a paperclip attachment button (positioned as an absolute overlay inside the textarea on the left; opens a file picker; selected file is staged locally in JS memory and shown as a removable filename preview badge — the file is uploaded to `data/uploads/` only when Send/Enter is triggered; if the WebSocket is offline at send time, upload is blocked with an error (no upload happens when disconnected, preventing orphan files). If the WebSocket drops after upload completes but before message delivery, the queued message references a durable server-side file that persists until explicitly deleted), a textarea (grows up to 120px; `padding-left: 42px` and `padding-right: 76px` leave space for both overlay controls), and a **send group** (`.chat-send-group`) positioned as an absolute overlay inside the textarea on the right, vertically centered inside the textarea (`top: 50%; transform: translateY(-50%)`). The paperclip attachment button is similarly centered (`top: 50%; transform: translateY(-50%)`), so both controls stay at the visual center of the textarea regardless of whether it is single-line or expanded to its max height. The send group contains a Send/Plan button (`.chat-send-inline`) and a chevron button (`.chat-send-chevron`) with a subtle divider. The send group has a **two-click send model**: the chevron opens a glassmorphism dropdown (`.chat-send-dropdown`) with **Send** and **Plan** items that *switch the active send mode* — they do NOT immediately send. The main button label, colour, and chevron tint reflect the active mode: crimson for Send (default), amber (`var(--amber)`) for Plan. Once the mode is set, clicking the main button or pressing Enter sends in that mode. Mode state is stored as `data-send-mode` on `.chat-send-group` (DOM-backed, CSS-readable single source of truth); `setSendMode(mode)` synchronises button text, title, and `data-mode-active` markers on dropdown items. The chevron is always visible (tappable on touchscreens). The dropdown closes on outside click, item selection, or Escape key. `sendMessage(planMode)` is the shared send function; both the sendBtn click listener and the Enter keydown handler derive `planMode` from `sendGroup.dataset.sendMode === 'plan'` using explicit arrow functions to avoid `MouseEvent` truthy-arg bug. Slash commands bypass the plan prefix regardless of mode. The `#chat-input` textarea has `backdrop-filter: blur(16px)` + semi-transparent background (frosted glass). The `#chat-input-area` wrapper uses a gradient fade overlay with a non-zero top opacity, and the attachment badge has its own blurred glass backing, so message bubbles still scroll underneath without filename/text double exposure. `#chat-messages` `padding-bottom` is set dynamically via `updateMessagesPadding()` in chat.js (real overlay height + 16px buffer), called on page connect, textarea resize, and attachment preview toggle. The CSS default is `84px` (covers min-height state); JS adjusts up to ~160px when the textarea is fully expanded. Shift+Enter for newline, Enter to send.
+- **Message input**: absolute-positioned frosted-glass overlay anchored to the bottom of the chat page (`position: absolute; bottom: 0`). Contains a paperclip attachment button (positioned as an absolute overlay inside the textarea on the left; opens a file picker; selected file is staged locally in JS memory and shown as a removable filename preview badge — the file is uploaded to `data/uploads/` only when Send/Enter is triggered; if the WebSocket is offline at send time, upload is blocked with an error (no upload happens when disconnected, preventing orphan files). If the WebSocket drops after upload completes but before message delivery, the queued message references a durable server-side file that persists until explicitly deleted), a textarea (grows up to 120px; `padding-left: 42px` and `padding-right: 76px` leave space for both overlay controls), and a **send group** (`.chat-send-group`) positioned as an absolute overlay inside the textarea on the right, vertically centered inside the textarea (`top: 50%; transform: translateY(-50%)`). The paperclip attachment button is similarly centered (`top: 50%; transform: translateY(-50%)`), so both controls stay at the visual center of the textarea regardless of whether it is single-line or expanded to its max height. The send group contains a Send/Plan button (`.chat-send-inline`) and a chevron button (`.chat-send-chevron`) with a subtle divider. The send group has a **two-click send model**: the chevron opens a glassmorphism dropdown (`.chat-send-dropdown`) with **Send** and **Plan** items that *switch the active send mode* — they do NOT immediately send. The main button label, colour, and chevron tint reflect the active mode: crimson for Send (default), amber (`var(--amber)`) for Plan. Once the mode is set, clicking the main button or pressing Enter sends in that mode. Mode state is stored as `data-send-mode` on `.chat-send-group` (DOM-backed, CSS-readable single source of truth); `setSendMode(mode)` synchronises button text, title, and `data-mode-active` markers on dropdown items. The chevron is always visible (tappable on touchscreens). The dropdown closes on outside click, item selection, or Escape key. `sendMessage(planMode)` is the shared send function; both the sendBtn click listener and the Enter keydown handler derive `planMode` from `sendGroup.dataset.sendMode === 'plan'` using explicit arrow functions to avoid `MouseEvent` truthy-arg bug. Slash commands bypass the plan prefix regardless of mode. The `#chat-input` textarea has `backdrop-filter: blur(16px)` + semi-transparent background (frosted glass) and explicitly disables browser-level autocorrect / autocapitalize / spellcheck (`autocorrect="off" autocapitalize="off" spellcheck="false"`) so code, identifiers, and slash-commands are not silently mangled. Bottom scroll-under fade is rendered by a **dedicated sibling layer** `<div class="chat-bottom-fade" aria-hidden="true">` (`position: absolute; bottom: 0; pointer-events: none; z-index: 4`) so it always sits **below** `#chat-input-area` (`z-index: 5`) and never optically swallows the textarea or the attachment badge — earlier versions painted the gradient as `#chat-input-area`'s own background, which made the lower part of the textarea visually dissolve into the dense end of the gradient. `#chat-messages` `padding-bottom` is set dynamically via `updateMessagesPadding()` in chat.js (real overlay height + 16px buffer), called on page connect, textarea resize, and attachment preview toggle. The CSS default is `84px` (covers min-height state); JS adjusts up to ~160px when the textarea is fully expanded. Shift+Enter for newline, Enter to send.
+- **Clipboard image paste**: `#chat-input` registers a `paste` listener that scans `e.clipboardData.items` for `image/*` MIME types, calls `getAsFile()` on the first match, wraps the blob as a `File` named `clipboard-<unix-ts>.<ext>` (extension derived from the MIME), and stages it through the **same** `pendingAttachment` slot used by the paperclip button (the badge / removal UI / upload-on-Send path are all reused — no inline upload happens until Send/Enter, mirroring the paperclip semantics including the offline-WS guard). Non-image clipboard payloads fall through to native paste (text / formatted text). When an image is staged this way, `e.preventDefault()` suppresses the browser's default paste so a giant base64 string is not also inserted into the textarea.
 - **Input recall**: ArrowUp / ArrowDown cycles through recent submitted messages without leaving the textarea. On the **first** successful `syncHistory` call of this page lifetime, it seeds `inputHistory` from server-side user messages (including Telegram and other-session messages that never went through the local `rememberInput()` path). Merge strategy: server messages (older) prepend before local session entries (newer); deduped from the end so most-recent entries always win; capped at 50 via `slice(-50)`. `PLAN_PREFIX` preambles are stripped before storage. Seeding is gated on a dedicated one-shot `inputHistorySeededFromServer` flag (not `historyLoaded`) so it fires on the first successful server sync even when the initial fetch failed and `historyLoaded` was already set true by the sessionStorage-fallback bootstrap path. Subsequent WebSocket reconnects deliberately do NOT re-seed (that would reset `inputHistoryIndex` mid-scrub), so Telegram/other-session messages that arrive while this tab stays open only surface in recall after the next full page reload.
 - **Messages**: user bubbles (right, steel-blue-tinted), assistant bubbles (left, crimson), and system-summary bubbles (left, amber). Non-user bubbles render markdown. Live task card uses crimson accent glass matching the assistant palette.
 - **Multi-user visibility**: user messages are now session-aware. The current browser session stays labeled as `You`; other Web UI sessions render as `WebUI (<session>)`; Telegram-origin messages render with their Telegram sender label.
@@ -1586,19 +1587,70 @@ Uncommitted changes are rescued to `~/Ouroboros/data/archive/rescue/` before res
 
 ## 8.1 CI/CD Pipeline (`.github/workflows/ci.yml`)
 
-Three-tier GitHub Actions workflow:
+Four-tier GitHub Actions workflow:
 
 | Tier | Trigger | What runs | Time |
 |------|---------|-----------|------|
-| Quick | Push to `ouroboros` or `ouroboros-three-layer` (code paths only) | Ubuntu-only: `pytest` | ~1 min |
+| Quick | Push to `ouroboros` (code paths only) | Ubuntu-only: `pytest` | ~1 min |
 | Full | Push to `ouroboros-stable`, manual (`workflow_dispatch`), or tag `v*` | Matrix: Ubuntu + Windows + macOS: `pytest` | ~5 min |
-| Build | Tag `v*` (after full-test passes) | Matrix: PyInstaller build → `.dmg` / `.tar.gz` / `.zip` + GitHub Release | ~15 min |
+| Integration | Push to `main`, `ouroboros`, or `ouroboros-stable`, manual (`workflow_dispatch`), or tag `v*` | Ubuntu-only: `pytest tests/test_provider_integration.py -m integration` against real OpenRouter / OpenAI / Anthropic keys (skipped per-provider when its key is unset) | ~2 min |
+| Build + Release | Tag `v*` (after full-test passes) | Matrix: PyInstaller build → `.dmg` / `.tar.gz` / `.zip` (macOS optionally codesigned + notarized when Apple secrets are configured) + GitHub Release | ~15 min |
 
 Path filters for branch pushes: `ouroboros/**`, `supervisor/**`, `server.py`, `launcher.py`,
 `tests/**`, `web/**`, `requirements.txt`, `pyproject.toml`, `.github/workflows/**`, `build.sh`,
 `build_linux.sh`, `build_windows.ps1`, `Dockerfile`, `scripts/**`, `VERSION`, `README.md`.
 Tag pushes (`v*`) always fire regardless of paths.
 
+**macOS code signing & notarization (Build tier).** When the build job has access to
+`BUILD_CERTIFICATE_BASE64`, `P12_PASSWORD`, `KEYCHAIN_PASSWORD`, and `APPLE_TEAM_ID` as
+GitHub Actions repository secrets, the build job creates a temporary keychain, imports
+the Developer ID certificate, and runs `bash build.sh` (which then signs the `.app` and
+the `.dmg`); when `APPLE_ID` and `APPLE_APP_SPECIFIC_PASSWORD` are also present,
+`build.sh` additionally runs `xcrun notarytool submit ... --wait` followed by
+`xcrun stapler staple` to staple the notarization ticket to the DMG. A transient
+stapler failure (Apple CDN propagation lag) after a successful notarytool submission
+is treated as a soft warning — the DMG is genuinely notarized and Gatekeeper validates
+it online; without that guard `set -e` would abort the build and silently drop the
+macOS artifact from the release. A `notarytool submit` failure (Apple-side outage,
+wrong credential) is handled the same way — the DMG ships signed-but-not-notarized
+with a clear `WARNING` log line rather than aborting, so an Apple outage never
+silently removes the macOS artifact from the GitHub Release. The four observable
+notarization outcomes (`success` / `staple_failed` / `submit_failed` / `unconfigured`)
+each render a distinct summary line at the end of the build, plus a defensive
+`Unknown notarization outcome` arm so future enum drift is loud rather than silent. With no Apple secrets configured, the macOS build
+falls back to the unsigned path (`OUROBOROS_SIGN=0 bash build.sh`) — users still need
+right-click → **Open** on first launch. Forks enable signing by configuring all four
+required secrets above; `SIGN_IDENTITY` is an additional optional secret for forks
+whose Developer ID differs from the upstream default. **The signing secrets are mapped
+at the build job's `env:` block, not at step level, because GitHub Actions rejects
+`secrets.*` references inside step-level `if:` expressions ("Unrecognized named-value:
+'secrets'") — step `if:` conditions read `env.*` instead.** Each mapping is additionally
+guarded by `${{ matrix.os == 'macos-latest' && secrets.X || '' }}` so the Apple
+credentials are scoped to the macOS matrix shard only — Linux and Windows sibling
+shards (which run `build_linux.sh` / `build_windows.ps1`, neither of which needs Apple
+creds) receive empty strings, so the signing material is never exposed to non-macOS
+build subprocesses. A `Cleanup keychain` step with
+`if: always() && matrix.os == 'macos-latest' && env.BUILD_CERTIFICATE_BASE64 != ''`
+deletes the temporary keychain regardless of build outcome — the `matrix.os` gate keeps
+the bash-only `security` invocation off Linux/Windows shards, and the env guard skips
+when no keychain was ever created. Signing material never persists on the runner. See
+`docs/DEVELOPMENT.md::GitHub Actions: secrets in step-level if conditions` for the
+rationale.
+
+**Integration tier credentials.** The integration job consumes
+`OPENROUTER_API_KEY`, `OPENAI_API_KEY`, and `ANTHROPIC_API_KEY` from repository secrets
+and exposes them as `env:` to a single `pytest` invocation; tests gated on missing keys
+skip cleanly via per-test `@pytest.mark.skipif(not os.environ.get(KEY))` decorators
+inside the test file. Locally the same tests are excluded by default through the
+`integration` pytest marker plus `addopts = "-m 'not integration'"` in `pyproject.toml`,
+so contributors do not accidentally burn provider tokens on every `pytest` run. Opt in
+with `pytest -m integration` (the whole file) or
+`pytest -m integration tests/test_provider_integration.py::test_openrouter_basic_chat`
+(specific test). A bare `pytest tests/test_provider_integration.py::test_X` without
+`-m integration` is **deselected** by `addopts -m 'not integration'` and exits 5
+("no tests collected"); use the explicit `-m integration` form, or override the
+default with `pytest -o addopts='' tests/test_provider_integration.py::test_X`.
+
 ### Build scripts
 
 | Script | Platform | Output |
diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md
index 5d7c8fb5e..18f185704 100644
--- a/docs/DEVELOPMENT.md
+++ b/docs/DEVELOPMENT.md
@@ -340,3 +340,86 @@ Existing classes (`.stat-card`, `.page-header`, `.about-*`, `.costs-*`) cover co
 Add new classes to `web/style.css` when needed.
 Before staging any `web/modules/*.js` file: `grep -n "\.style\." web/modules/*.js`
 and fix any hits.
+
+---
+
+## Build & CI
+
+### GitHub Actions: secrets in step-level `if:` conditions
+
+GitHub Actions **rejects** `secrets.*` references inside step-level `if:`
+expressions with `Unrecognized named-value: 'secrets'`. The workflow file
+fails to parse and the job never runs. Step-level `env:` blocks **are also
+not visible to that step's own `if:`** — only job-level `env:` is.
+
+When a step needs to gate on whether a secret is configured, **map the
+secret into the build job's `env:` block, then reference `env.*` in the
+step `if:`**. The step itself can then either use the env var directly
+(it inherits from the job) or assume it is present.
+
+```yaml
+jobs:
+  build:
+    runs-on: macos-latest
+    env:
+      # job-level: visible to step-level `if:` via env.*
+      BUILD_CERTIFICATE_BASE64: ${{ secrets.BUILD_CERTIFICATE_BASE64 }}
+      P12_PASSWORD: ${{ secrets.P12_PASSWORD }}
+    steps:
+      - name: Import Apple signing certificate
+        # ✅ env.* — visible inside step-level if
+        if: env.BUILD_CERTIFICATE_BASE64 != '' && env.P12_PASSWORD != ''
+        run: |
+          echo "${BUILD_CERTIFICATE_BASE64}" | base64 -d > cert.p12
+          security import cert.p12 -P "${P12_PASSWORD}" ...
+      - name: Cleanup keychain
+        if: always() && env.BUILD_CERTIFICATE_BASE64 != ''
+        run: security delete-keychain ...
+```
+
+```yaml
+# ❌ WRONG — workflow fails to parse
+- name: Bad
+  if: secrets.BUILD_CERTIFICATE_BASE64 != ''   # parse error
+  env:                                          # not visible to this step's if:
+    P12_PASSWORD: ${{ secrets.P12_PASSWORD }}
+```
+
+This pattern is enforced by `tests/test_build_scripts.py::TestMacOSSigning::
+test_ci_uses_env_context_for_condition`, which parses every `if:` block in
+`.github/workflows/ci.yml` (including multi-line continuations) and asserts
+no occurrence of `secrets.` ever appears inside one.
+
+### Apple signing & notarization (macOS Build job)
+
+When `BUILD_CERTIFICATE_BASE64`, `P12_PASSWORD`, `KEYCHAIN_PASSWORD`, and
+`APPLE_TEAM_ID` are configured as repository secrets, the macOS build job
+imports the Developer ID certificate into a temporary keychain and runs
+`bash build.sh` — `build.sh` then signs the `.app` and the `.dmg` using
+the env-overridable `SIGN_IDENTITY`. Each Apple secret is mapped at the
+build job's `env:` block with a `${{ matrix.os == 'macos-latest' && secrets.X || '' }}`
+guard so the Apple credentials reach the macOS matrix shard only; Linux
+and Windows sibling shards (running `build_linux.sh` / `build_windows.ps1`,
+neither of which needs Apple creds) receive empty strings. When `APPLE_ID` and
+`APPLE_APP_SPECIFIC_PASSWORD` are also present, `build.sh` runs
+`xcrun notarytool submit ... --wait` followed by `xcrun stapler staple` to
+attach the notarization ticket; otherwise the entire notarization block is
+skipped and the DMG ships **signed but not notarized** (users still need
+right-click → **Open** on first launch). The stapler call is wrapped in
+its own guard so a transient stapler failure after a successful notarytool
+submission becomes a soft warning rather than a hard build failure (the
+DMG is genuinely notarized — Gatekeeper just fetches the ticket online on
+first launch instead of from the embedded staple). The `notarytool submit`
+call is wrapped the same way: an Apple-side outage / wrong-credential typo
+prints a `WARNING` and lets the DMG ship signed-but-not-notarized, instead
+of aborting the build under `set -e` and silently dropping the macOS
+artifact from the release. A single `NOTARIZE_OUTCOME` enum (`success` /
+`staple_failed` / `submit_failed` / `unconfigured`) drives the build's
+final summary line so the WARN message and the summary always agree on
+the actual artifact state, plus a defensive `*)` arm so any future enum
+drift is loud. The `Cleanup keychain`
+step runs with `if: always() && matrix.os == 'macos-latest' && env.BUILD_CERTIFICATE_BASE64 != ''`
+— `always()` ensures cleanup fires on build failures too, the `matrix.os`
+gate keeps the bash-only `security` invocation off Linux/Windows shards,
+and the env guard skips when no keychain was created (no signing secrets).
+Signing material never persists across runs.
diff --git a/pyproject.toml b/pyproject.toml
index 7210c020e..5159ce226 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ouroboros"
-version = "5.0.0"
+version = "5.1.0"
 description = "Self-creating AI agent with constitution, background consciousness, and persistent identity"
 readme = "README.md"
 license = {text = "MIT"}
@@ -64,7 +64,13 @@ all = ["claude-agent-sdk>=0.1.60", "a2a-sdk[http-server]>=0.3.20", "playwright",
 testpaths = ["tests"]
 python_files = ["test_*.py"]
 python_functions = ["test_*"]
-addopts = "-q --tb=short"
+# Default local runs exclude the `integration` marker so contributors do not
+# accidentally burn provider tokens on every `pytest`. CI Tier 2.5 opts in
+# explicitly with `pytest -m integration` (the CLI -m overrides addopts -m).
+addopts = "-q --tb=short -m 'not integration'"
+markers = [
+    "integration: requires real provider API keys (OPENROUTER_API_KEY / OPENAI_API_KEY / ANTHROPIC_API_KEY); excluded from default local runs, opt in via `pytest -m integration`",
+]
 
 [tool.setuptools]
 py-modules = ["server"]
diff --git a/tests/test_build_repo_bundle.py b/tests/test_build_repo_bundle.py
index 05c9f50a0..c724e99d4 100644
--- a/tests/test_build_repo_bundle.py
+++ b/tests/test_build_repo_bundle.py
@@ -56,7 +56,7 @@ def _make_repo(tmp_path):
     _run(["git", "init"], cwd=repo)
     _run(["git", "config", "user.name", "Test"], cwd=repo)
     _run(["git", "config", "user.email", "test@example.com"], cwd=repo)
-    _run(["git", "checkout", "-b", "ouroboros-three-layer"], cwd=repo)
+    _run(["git", "checkout", "-b", "ouroboros"], cwd=repo)
     _run(["git", "remote", "add", "origin", "git@github.com:joi-lab/ouroboros-desktop.git"], cwd=repo)
     (repo / "VERSION").write_text("4.50.0-rc.2\n", encoding="utf-8")
     (repo / "server.py").write_text("print('ok')\n", encoding="utf-8")
@@ -80,7 +80,7 @@ def test_build_repo_bundle_accepts_explicit_source_branch_on_detached_head(tmp_p
             "--repo-root",
             str(repo),
             "--source-branch",
-            "ouroboros-three-layer",
+            "ouroboros",
             "--output-bundle",
             str(bundle),
             "--output-manifest",
@@ -94,7 +94,7 @@ def test_build_repo_bundle_accepts_explicit_source_branch_on_detached_head(tmp_p
     assert payload["source_sha"] == sha
     assert payload["release_tag"] == "v4.50.0-rc.2"
     assert payload["bundle_sha256"]
-    assert payload["managed_remote_branch"] == "ouroboros-three-layer"
+    assert payload["managed_remote_branch"] == "ouroboros"
     assert payload["managed_remote_url"] == "https://github.com/joi-lab/ouroboros-desktop.git"
 
 
@@ -115,7 +115,7 @@ def test_build_repo_bundle_uses_checked_out_head_not_branch_tip(tmp_path):
             "--repo-root",
             str(repo),
             "--source-branch",
-            "ouroboros-three-layer",
+            "ouroboros",
             "--output-bundle",
             str(bundle),
             "--output-manifest",
@@ -142,7 +142,7 @@ def test_build_repo_bundle_refuses_dirty_worktree(tmp_path):
             "--repo-root",
             str(repo),
             "--source-branch",
-            "ouroboros-three-layer",
+            "ouroboros",
             "--output-bundle",
             str(bundle),
             "--output-manifest",
@@ -168,7 +168,7 @@ def test_build_repo_bundle_rejects_reserved_origin_remote_name(tmp_path):
             "--repo-root",
             str(repo),
             "--source-branch",
-            "ouroboros-three-layer",
+            "ouroboros",
             "--managed-remote-name",
             "origin",
             "--output-bundle",
@@ -197,7 +197,7 @@ def test_build_repo_bundle_preserves_https_remote_ports(tmp_path):
             "--repo-root",
             str(repo),
             "--source-branch",
-            "ouroboros-three-layer",
+            "ouroboros",
             "--output-bundle",
             str(bundle),
             "--output-manifest",
@@ -250,7 +250,7 @@ def test_build_repo_bundle_rejects_release_tag_mismatch(tmp_path):
             "--repo-root",
             str(repo),
             "--source-branch",
-            "ouroboros-three-layer",
+            "ouroboros",
             "--output-bundle",
             str(bundle),
             "--output-manifest",
@@ -280,7 +280,7 @@ def test_build_repo_bundle_requires_release_tag(tmp_path):
             "--repo-root",
             str(repo),
             "--source-branch",
-            "ouroboros-three-layer",
+            "ouroboros",
             "--output-bundle",
             str(bundle),
             "--output-manifest",
@@ -326,7 +326,7 @@ def test_build_repo_bundle_rejects_head_outside_source_branch(tmp_path):
             "--repo-root",
             str(repo),
             "--source-branch",
-            "ouroboros-three-layer",
+            "ouroboros",
             "--output-bundle",
             str(bundle),
             "--output-manifest",
@@ -362,7 +362,7 @@ def test_build_repo_bundle_rejects_lightweight_tag(tmp_path):
             "--repo-root",
             str(repo),
             "--source-branch",
-            "ouroboros-three-layer",
+            "ouroboros",
             "--output-bundle",
             str(bundle),
             "--output-manifest",
@@ -434,7 +434,7 @@ def test_build_repo_bundle_rejects_env_tag_not_on_head(tmp_path):
             "--repo-root",
             str(repo),
             "--source-branch",
-            "ouroboros-three-layer",
+            "ouroboros",
             "--output-bundle",
             str(bundle),
             "--output-manifest",
diff --git a/tests/test_build_scripts.py b/tests/test_build_scripts.py
index 42b15b5a1..d01ef7306 100644
--- a/tests/test_build_scripts.py
+++ b/tests/test_build_scripts.py
@@ -278,3 +278,270 @@ class TestDockerfile:
             f"Found {len(playwright_invocations)} playwright invocation(s) at positions: "
             f"{playwright_invocations}"
         )
+
+
+# ---------------------------------------------------------------------------
+# .github/workflows/ci.yml + build.sh — macOS code signing & notarization
+# ---------------------------------------------------------------------------
+
+class TestMacOSSigning:
+    """The CI build job and build.sh together implement optional macOS code
+    signing and notarization. Seven contracts are pinned here to prevent
+    regression of the GitHub Actions `secrets.*`-in-step-`if:` pitfall, the
+    build-script env override / optional-notarytool gate, the keychain
+    cleanup guard, and the stapler-failure-as-soft-warning behaviour.
+
+    See docs/DEVELOPMENT.md::"GitHub Actions: secrets in step-level if
+    conditions" for the rationale.
+    """
+
+    _CI_PATH = ".github/workflows/ci.yml"
+    _SIGNING_SECRETS = (
+        "BUILD_CERTIFICATE_BASE64",
+        "P12_PASSWORD",
+        "KEYCHAIN_PASSWORD",
+        "APPLE_TEAM_ID",
+    )
+    _NOTARIZE_SECRETS = (
+        "APPLE_ID",
+        "APPLE_APP_SPECIFIC_PASSWORD",
+    )
+
+    @staticmethod
+    def _build_job_header(src: str) -> str:
+        """Slice the build job header (everything between `  build:` and the
+        first `    steps:` underneath it) so signing-secret env mappings can
+        be located without false positives from later step-level env blocks."""
+        build_idx = src.find("\n  build:\n")
+        assert build_idx != -1, "build job not found in ci.yml"
+        steps_idx = src.find("\n    steps:", build_idx)
+        assert steps_idx != -1, "build.steps: not found in ci.yml"
+        return src[build_idx:steps_idx]
+
+    @staticmethod
+    def _iter_step_if_blocks(src: str):
+        """Yield every `if:` expression in the workflow as a flat string.
+
+        Catches BOTH step-level and job-level `if:` blocks (the
+        `Unrecognized named-value: 'secrets'` rejection applies at every
+        level, so checking job-level too is strictly more conservative).
+
+        Heuristic: collect lines starting from `if:` until the next YAML
+        key starts (a line whose first non-space char is `-` or whose
+        stripped form contains a `:`). Known limitation: a future `if:`
+        whose continuation lines legitimately contain `:` (string literals,
+        nested expressions) would be split prematurely; the current ci.yml
+        has no such case. If that pattern is added, switch to a real YAML
+        parser walking each step's `if` field.
+        """
+        lines = src.splitlines()
+        in_if = False
+        block: list[str] = []
+        for line in lines:
+            stripped = line.strip()
+            if stripped.startswith("if:"):
+                if in_if and block:
+                    yield " ".join(block)
+                in_if = True
+                block = [stripped]
+                continue
+            if in_if:
+                # Continuation: indented, not a new YAML key, not a step start.
+                if stripped and not stripped.startswith("- ") and ":" not in stripped:
+                    block.append(stripped)
+                else:
+                    yield " ".join(block)
+                    in_if = False
+                    block = []
+        if in_if and block:
+            yield " ".join(block)
+
+    def test_ci_signing_secrets_at_job_level(self):
+        """All four required signing secrets MUST be mapped at the build job's
+        env: block (not at step level), so step-level `if:` conditions can
+        read `env.*`. Step-level env blocks are NOT visible to that step's
+        own `if:` — only job-level env is.
+
+        Each mapping must ALSO be guarded by `matrix.os == 'macos-latest'`
+        so the Apple credentials are scoped to the macOS matrix shard only;
+        Linux and Windows sibling shards receive empty strings. This avoids
+        exposing the signing material to `build_linux.sh` / `build_windows.ps1`
+        subprocesses that have no use for it.
+        """
+        src = _read(self._CI_PATH)
+        header = self._build_job_header(src)
+        # Required form (per secret): `<NAME>: ${{ matrix.os == 'macos-latest' && secrets.<NAME> || '' }}`
+        for secret in self._SIGNING_SECRETS:
+            expected = (
+                f"{secret}: ${{{{ matrix.os == 'macos-latest' "
+                f"&& secrets.{secret} || '' }}}}"
+            )
+            assert expected in header, (
+                f"build job env: must map {secret} at job level with a "
+                f"matrix.os == 'macos-latest' guard so non-macOS shards "
+                f"receive empty strings. Expected line: {expected!r}"
+            )
+        # Optional notarization secrets must also be mapped at job level
+        # (so build.sh inherits them as env vars when it runs), with the
+        # same matrix-shard guard.
+        for secret in self._NOTARIZE_SECRETS:
+            expected = (
+                f"{secret}: ${{{{ matrix.os == 'macos-latest' "
+                f"&& secrets.{secret} || '' }}}}"
+            )
+            assert expected in header, (
+                f"build job env: must also map {secret} (with matrix.os "
+                f"guard) so build.sh can run `xcrun notarytool` when it is "
+                f"configured. Expected line: {expected!r}"
+            )
+
+    def test_ci_uses_env_context_for_condition(self):
+        """No `if:` expression in ci.yml (step-level OR job-level) may
+        reference `secrets.*`.
+
+        GitHub Actions rejects `secrets.*` in `if:` with
+        `Unrecognized named-value: 'secrets'`. Always use `env.*` instead
+        (see the job-level env block test above). The parser used here
+        catches both step-level and job-level `if:` blocks deliberately —
+        the rejection applies at every level, so a job-level violation
+        would also break the workflow.
+        """
+        src = _read(self._CI_PATH)
+        offending = [
+            block for block in self._iter_step_if_blocks(src)
+            if "secrets." in block
+        ]
+        assert not offending, (
+            "secrets.* must not appear in any step-level if-condition "
+            "(promote to job-level env: and reference env.* instead). "
+            f"Offenders: {offending}"
+        )
+
+    def test_ci_import_gates_on_full_secret_set(self):
+        """The Import-Apple-signing-certificate step MUST gate on ALL four
+        required signing secrets via env.*, not just the certificate."""
+        src = _read(self._CI_PATH)
+        import_idx = src.find("Import Apple signing certificate")
+        assert import_idx != -1, (
+            "Apple signing-certificate Import step not found in ci.yml — "
+            "the macOS signing path is missing"
+        )
+        # Take a generous slice around the Import step's `if:` line.
+        region = src[import_idx:import_idx + 800]
+        for env_var in self._SIGNING_SECRETS:
+            assert f"env.{env_var}" in region, (
+                f"Import step if-condition must gate on env.{env_var} to "
+                f"prevent partial-secret runs from importing nothing"
+            )
+
+    def test_ci_cleanup_keychain_step_present(self):
+        """A `Cleanup keychain` step must run with `if: always() &&
+        matrix.os == 'macos-latest' && env.BUILD_CERTIFICATE_BASE64 != ''`
+        so signing material never persists across runs even when the build
+        itself fails, and the bash-only `security` invocation never fires
+        on Linux/Windows shards."""
+        src = _read(self._CI_PATH)
+        # Match the actual STEP definition (`- name: Cleanup keychain`), not
+        # any prose mentioning the step elsewhere in the workflow file (e.g.
+        # an explanatory comment in the Import step that references the later
+        # Cleanup step would match a bare substring search). The `- name:`
+        # anchor pins the assertion to the real step header.
+        cleanup_anchor = "- name: Cleanup keychain"
+        assert cleanup_anchor in src, (
+            "ci.yml must include a `- name: Cleanup keychain` step that "
+            "deletes the temporary signing keychain after every macOS build"
+        )
+        cleanup_idx = src.find(cleanup_anchor)
+        cleanup_region = src[cleanup_idx:cleanup_idx + 500]
+        assert "always()" in cleanup_region, (
+            "Cleanup keychain must run with `if: always()` so it fires on "
+            "build failures too"
+        )
+        assert "matrix.os == 'macos-latest'" in cleanup_region, (
+            "Cleanup keychain must gate on matrix.os == 'macos-latest' so "
+            "the bash-only `security delete-keychain` invocation does not "
+            "fire on Linux/Windows shards (where the secret env var would "
+            "still be set as job-level env)"
+        )
+        assert "env.BUILD_CERTIFICATE_BASE64 != ''" in cleanup_region, (
+            "Cleanup keychain must gate on env.BUILD_CERTIFICATE_BASE64 so "
+            "it does not try to delete a keychain that was never created"
+        )
+
+    def test_build_sh_signing_identity_env_override(self):
+        """build.sh must allow the signing identity to be overridden via env
+        (CI runners import a temporary Developer ID and need to point at
+        whatever identity matches their imported certificate)."""
+        src = _read("build.sh")
+        # Accept either ${SIGN_IDENTITY:-...} or ${SIGN_IDENTITY-...}
+        # (POSIX parameter expansion). We require the explicit `:-` form
+        # so an empty-string env var still falls back to the default.
+        assert re.search(
+            r'SIGN_IDENTITY=\s*"\$\{SIGN_IDENTITY:-[^"]+"',
+            src,
+        ), (
+            "build.sh must set SIGN_IDENTITY=\"${SIGN_IDENTITY:-...}\" "
+            "so the env var wins when present and the default kicks in "
+            "when it is unset or empty"
+        )
+
+    def test_build_sh_notarization_optional(self):
+        """build.sh must include an optional notarization block guarded on
+        APPLE_ID + APPLE_TEAM_ID + APPLE_APP_SPECIFIC_PASSWORD, calling
+        `xcrun notarytool submit` followed by `xcrun stapler staple`."""
+        src = _read("build.sh")
+        assert "xcrun notarytool submit" in src, (
+            "build.sh must call `xcrun notarytool submit` to upload the "
+            "DMG for Apple notarization when credentials are configured"
+        )
+        assert "xcrun stapler staple" in src, (
+            "build.sh must call `xcrun stapler staple` after a successful "
+            "notarytool submission so the ticket is attached to the DMG"
+        )
+        # The notarization block must be guarded on the three notarytool
+        # credential env vars, otherwise builds without an Apple ID hard-fail.
+        for var in ("APPLE_ID", "APPLE_TEAM_ID", "APPLE_APP_SPECIFIC_PASSWORD"):
+            assert var in src, (
+                f"build.sh notarization block must reference {var} so it "
+                f"is gated on the full credential set"
+            )
+
+    def test_build_sh_stapler_failure_is_soft(self):
+        """`xcrun stapler staple` must be wrapped in an `if/then/else`
+        (or paired with `||`) so a transient stapler failure becomes a
+        warning instead of aborting the build under `set -e`.
+
+        Apple's stapler service can fail intermittently after a successful
+        `notarytool submit` (CDN propagation lag, transient 5xx). A
+        signed-and-notarized-but-unstapled DMG is still functional —
+        Gatekeeper fetches the ticket online on first launch — so a
+        stapler hiccup must not delete the macOS artifact from the
+        release.
+        """
+        src = _read("build.sh")
+        # Find the stapler invocation and check it is inside an `if` head
+        # (i.e. `if xcrun stapler staple ...; then`) OR followed by `||`.
+        # The simplest robust check: locate the line, then verify either
+        # (a) it begins with `if ` after stripping leading whitespace, or
+        # (b) it ends with ` || ...` style continuation.
+        # Only inspect actual code lines — strip both whole-line bash comments
+        # (`# …`) and inline trailing comments (`code # …`) before testing.
+        stapler_lines = []
+        for raw in src.splitlines():
+            code = raw.split("#", 1)[0]
+            if "xcrun stapler staple" in code:
+                stapler_lines.append(code)
+        assert stapler_lines, (
+            "build.sh must call `xcrun stapler staple` (notarization step)"
+        )
+        for line in stapler_lines:
+            stripped = line.strip()
+            wrapped_in_if = stripped.startswith("if ") and stripped.endswith("; then")
+            soft_or = "||" in stripped
+            assert wrapped_in_if or soft_or, (
+                "build.sh `xcrun stapler staple` invocation must be guarded "
+                "(`if xcrun stapler staple ...; then ... else WARN ... fi` "
+                "or `xcrun stapler staple ... || echo WARN`) so a transient "
+                "stapler failure does not abort the build under `set -e` and "
+                f"silently drop the macOS DMG. Offending line: {stripped!r}"
+            )
diff --git a/tests/test_chat_logs_ui.py b/tests/test_chat_logs_ui.py
index 7a7ad5eaa..2b27423cb 100644
--- a/tests/test_chat_logs_ui.py
+++ b/tests/test_chat_logs_ui.py
@@ -114,15 +114,24 @@ def test_styles_cover_chat_header_controls_and_grouped_cards():
 def test_chat_floating_overlays_have_readable_glass_backing():
     """v5: floating overlays at the top and bottom of the chat fade
     fully to transparent at the inner edge (no visible step). The
-    blur is masked in lockstep so the glass effect does not create
-    its own hard border. Status badge and attachment badge keep
+    top header still paints its own gradient + mask in step with
+    the blur (one layer with blur). The bottom fade-to-zero contract
+    moved out of `#chat-input-area`'s background and onto a dedicated
+    sibling `.chat-bottom-fade` layer (z-index < input dock) so the
+    textarea is no longer optically swallowed by the dense end of the
+    gradient — see test_chat_bottom_fade_is_separate_layer below for
+    the layering invariant. Status badge and attachment badge keep
     their solid backings (those are inline pills, not scrim layers).
     """
     css = _read("web/style.css")
 
     header = re.search(r"\.chat-page-header\s*\{(?P<body>[^}]+)\}", css, re.S).group("body")
     status = re.search(r"\.status-badge\s*\{(?P<body>[^}]+)\}", css, re.S).group("body")
-    input_area = re.search(r"#chat-input-area\s*\{(?P<body>[^}]+)\}", css, re.S).group("body")
+    # There may be multiple `.chat-bottom-fade { … }` rules (base + mobile
+    # @media override). The base rule is the first match and is the one
+    # that owns the gradient; the mobile rule only adjusts height.
+    fade = re.search(r"\.chat-bottom-fade\s*\{(?P<body>[^}]+)\}", css, re.S).group("body")
+    fade_all_bodies = re.findall(r"\.chat-bottom-fade\s*\{([^}]+)\}", css, re.S)
     attach = re.search(r"\.attach-badge\s*\{(?P<body>[^}]+)\}", css, re.S).group("body")
 
     # Header: glass blur active, gradient ENDS at fully-transparent
@@ -132,12 +141,31 @@ def test_chat_floating_overlays_have_readable_glass_backing():
     assert "rgba(13, 11, 15, 0.00) 100%" in header
     assert "mask-image:" in header
 
-    # Bottom input dock: same fade-to-zero contract.
-    assert "rgba(13, 11, 15, 0.00) 100%" in input_area
-    assert "mask-image:" in input_area
+    # Bottom fade layer (base rule): same fade-to-zero contract on a
+    # dedicated layer.
+    assert "rgba(13, 11, 15, 0.00) 100%" in fade
+    assert "linear-gradient" in fade
+
+    # No `mask-image` is needed because this layer is intentionally
+    # blur-less — it is a plain pointer-events:none gradient that sits below
+    # the input dock. The no-blur invariant is asserted on EVERY captured
+    # `.chat-bottom-fade { … }` rule (base + any `@media` overrides) so a
+    # regression that adds `backdrop-filter` only inside the mobile media
+    # block (and would silently slip past a base-only assertion) is caught.
+    # If a future edit needs blur on this layer, also add a coordinating
+    # mask-image so the blur fades in step with the gradient — see the
+    # .chat-page-header pattern for the canonical idiom.
+    assert fade_all_bodies, ".chat-bottom-fade rule must exist"
+    for idx, body in enumerate(fade_all_bodies):
+        assert "backdrop-filter" not in body, (
+            f".chat-bottom-fade rule #{idx} (counting base + @media overrides) "
+            f"must remain blur-less. If a future edit needs blur on this "
+            f"layer, also add a coordinating mask-image (see "
+            f".chat-page-header). Offending rule body: {body.strip()[:200]!r}"
+        )
 
     # Inline pills keep their solid backings — the test only enforces
-    # the fade-to-zero invariant on the scrim layers (header / dock).
+    # the fade-to-zero invariant on the scrim layers (header / fade).
     assert "backdrop-filter: blur(8px)" in status
     assert "rgba(26, 21, 32, 0.78)" in status
     assert "backdrop-filter: blur(8px)" in attach
@@ -1054,3 +1082,115 @@ def test_sync_history_sweep_skips_invisible_completed_cards():
         "The final sweep guard must also check ts.completed so in-progress tasks "
         "without cardVisible are still appended"
     )
+
+
+# ─── Autocorrect / spellcheck suppression on #chat-input ────────────────
+
+def test_chat_input_disables_autocorrect():
+    """#chat-input textarea must disable browser autocorrect/spellcheck/autocapitalize.
+
+    These attributes prevent the browser from silently rewriting code,
+    identifiers, slash-commands, and other technical input. Test asserts
+    each attribute by literal substring match against the textarea template
+    string in chat.js (no JSDOM — chat.js builds its own template at runtime).
+    """
+    source = _read("web/modules/chat.js")
+    assert 'id="chat-input"' in source, "chat-input textarea must exist"
+    assert 'autocorrect="off"' in source, (
+        "chat-input textarea must set autocorrect='off'"
+    )
+    assert 'autocapitalize="off"' in source, (
+        "chat-input textarea must set autocapitalize='off'"
+    )
+    assert 'spellcheck="false"' in source, (
+        "chat-input textarea must set spellcheck='false'"
+    )
+
+
+# ─── Clipboard image paste handler ──────────────────────────────────────
+
+def test_clipboard_paste_handler_exists():
+    """chat.js must register a `paste` listener that intercepts image/* clipboard
+    items and routes them through the same staging path the paperclip uses.
+
+    Verified by literal substring assertions: the listener registration, the
+    image/* MIME guard, the `pendingAttachment` set, and the `clipboard-`
+    filename prefix. No DOM execution — these strings are stable contract
+    surface for the feature.
+    """
+    source = _read("web/modules/chat.js")
+    assert (
+        "addEventListener('paste'" in source
+        or 'addEventListener("paste"' in source
+    ), (
+        "chat.js must register a paste event listener for clipboard image support"
+    )
+    assert "image/" in source, (
+        "paste handler must guard on image/* MIME type"
+    )
+    assert "pendingAttachment" in source, (
+        "paste handler must set pendingAttachment for the staged image"
+    )
+    assert "clipboard-" in source, (
+        "paste handler must generate a clipboard-prefixed filename"
+    )
+
+
+# ─── Bottom-fade gradient layer is separate from #chat-input-area ───────
+
+def test_chat_bottom_fade_is_separate_layer():
+    """Bottom scroll-under fade must live on a dedicated `.chat-bottom-fade`
+    layer with `pointer-events: none` and a z-index strictly below
+    `#chat-input-area` (which is z-index 5). This ensures the textarea is
+    never optically swallowed by the dense bottom of the gradient.
+
+    Verified at the CSS source level (no rendered-DOM check) so the test is
+    deterministic and robust to layout changes that don't affect z-order.
+    """
+    css = _read("web/style.css")
+
+    # The dedicated layer must be defined.
+    assert ".chat-bottom-fade {" in css, (
+        ".chat-bottom-fade rule must exist as a dedicated layer (not painted "
+        "as a background on #chat-input-area)"
+    )
+
+    # Extract the .chat-bottom-fade rule body and assert pointer-events:none + z-index < 5.
+    fade_match = re.search(
+        r"\.chat-bottom-fade\s*\{([^}]*)\}",
+        css,
+    )
+    assert fade_match, ".chat-bottom-fade rule body must be parseable"
+    fade_body = fade_match.group(1)
+    assert "pointer-events" in fade_body and "none" in fade_body, (
+        ".chat-bottom-fade must set pointer-events: none so it never blocks input"
+    )
+    z_match = re.search(r"z-index\s*:\s*(\d+)", fade_body)
+    assert z_match, ".chat-bottom-fade must declare an explicit z-index"
+    z_index = int(z_match.group(1))
+    assert z_index < 5, (
+        f".chat-bottom-fade z-index must be < 5 (got {z_index}) so it sits below "
+        f"#chat-input-area (z-index 5)"
+    )
+
+    # #chat-input-area must NOT carry the gradient background anymore.
+    input_area_match = re.search(
+        r"#chat-input-area\s*\{([^}]*)\}",
+        css,
+    )
+    assert input_area_match, "#chat-input-area rule must be parseable"
+    input_area_body = input_area_match.group(1)
+    # We tolerate other `background:` properties (none expected today) but
+    # specifically forbid linear-gradient bleeding through the input dock.
+    assert "linear-gradient" not in input_area_body, (
+        "#chat-input-area must not paint the bottom-fade gradient as its own "
+        "background — that is what made the textarea optically sink. Move the "
+        "gradient to the dedicated .chat-bottom-fade layer."
+    )
+
+    # And the DOM template in chat.js must include the dedicated fade element.
+    chat_js = _read("web/modules/chat.js")
+    assert 'class="chat-bottom-fade"' in chat_js, (
+        "chat.js page-chat template must include <div class=\"chat-bottom-fade\"> "
+        "as a sibling of #chat-input-area"
+    )
diff --git a/tests/test_git_ops_recovery.py b/tests/test_git_ops_recovery.py
index 8c981b6fc..275c0991b 100644
--- a/tests/test_git_ops_recovery.py
+++ b/tests/test_git_ops_recovery.py
@@ -244,7 +244,7 @@ def test_checkout_and_reset_prefers_managed_remote_ref(monkeypatch, tmp_path):
         "_read_managed_repo_meta",
         lambda: {
             "managed_remote_name": "managed",
-            "managed_remote_branch": "ouroboros-three-layer",
+            "managed_remote_branch": "ouroboros",
             "managed_remote_stable_branch": "ouroboros-stable",
         },
     )
@@ -264,7 +264,7 @@ def test_checkout_and_reset_prefers_managed_remote_ref(monkeypatch, tmp_path):
 
     def fake_run(cmd, cwd=None, capture_output=False, text=False, check=False):
         calls.append(cmd)
-        if cmd == ["git", "rev-parse", "--verify", "managed/ouroboros-three-layer"]:
+        if cmd == ["git", "rev-parse", "--verify", "managed/ouroboros"]:
             return subprocess.CompletedProcess(cmd, 0, stdout="remote-sha\n", stderr="")
         if cmd[:4] == ["git", "checkout", "-B", "ouroboros"]:
             return subprocess.CompletedProcess(cmd, 0, stdout="", stderr="")
@@ -280,7 +280,7 @@ def test_checkout_and_reset_prefers_managed_remote_ref(monkeypatch, tmp_path):
 
     assert ok
     assert message == "ok"
-    assert ["git", "checkout", "-B", "ouroboros", "managed/ouroboros-three-layer"] in calls
+    assert ["git", "checkout", "-B", "ouroboros", "managed/ouroboros"] in calls
     assert saved_state["current_branch"] == "ouroboros"
     assert saved_state["current_sha"] == "fedcba"
 
@@ -313,7 +313,7 @@ def test_collect_repo_sync_state_prefers_managed_remote(monkeypatch):
         "_read_managed_repo_meta",
         lambda: {
             "managed_remote_name": "managed",
-            "managed_remote_branch": "ouroboros-three-layer",
+            "managed_remote_branch": "ouroboros",
         },
     )
     monkeypatch.setattr(git_ops, "_has_remote", lambda name=None: name in (None, "managed"))
@@ -323,7 +323,7 @@ def test_collect_repo_sync_state_prefers_managed_remote(monkeypatch):
             return 0, "ouroboros", ""
         if cmd == ["git", "status", "--porcelain"]:
             return 0, "", ""
-        if cmd == ["git", "log", "--oneline", "managed/ouroboros-three-layer..HEAD"]:
+        if cmd == ["git", "log", "--oneline", "managed/ouroboros..HEAD"]:
             return 0, "abc123 local commit\n", ""
         raise AssertionError(cmd)
 
@@ -347,7 +347,7 @@ def test_checkout_and_reset_keeps_bundled_sha_on_first_managed_bootstrap(monkeyp
         "_read_managed_repo_meta",
         lambda: {
             "managed_remote_name": "managed",
-            "managed_remote_branch": "ouroboros-three-layer",
+            "managed_remote_branch": "ouroboros",
             "source_sha": "bundle123",
         },
     )
diff --git a/tests/test_launcher_sync.py b/tests/test_launcher_sync.py
index bda21d651..3df0e571e 100644
--- a/tests/test_launcher_sync.py
+++ b/tests/test_launcher_sync.py
@@ -78,7 +78,7 @@ def _make_bundle_source(tmp_path):
     _run(["git", "init"], cwd=src)
     _run(["git", "config", "user.name", "Test"], cwd=src)
     _run(["git", "config", "user.email", "test@example.com"], cwd=src)
-    _run(["git", "checkout", "-b", "ouroboros-three-layer"], cwd=src)
+    _run(["git", "checkout", "-b", "ouroboros"], cwd=src)
     _run(["git", "remote", "add", "origin", "https://github.com/joi-lab/ouroboros-desktop.git"], cwd=src)
     (src / "VERSION").write_text("4.50.0-rc.2\n", encoding="utf-8")
     (src / "server.py").write_text("print('bundle-v1')\n", encoding="utf-8")
@@ -123,7 +123,7 @@ def test_ensure_managed_repo_clones_from_embedded_bundle(tmp_path):
     assert (repo_dir / "server.py").read_text(encoding="utf-8") == "print('bundle-v1')\n"
     assert _git_output(repo_dir, "branch", "--show-current") == "ouroboros"
     meta = bootstrap.load_repo_manifest(repo_dir)
-    assert meta["managed_remote_branch"] == "ouroboros-three-layer"
+    assert meta["managed_remote_branch"] == "ouroboros"
     assert meta["managed_local_branch"] == "ouroboros"
     assert meta["release_tag"] == "v4.50.0-rc.2"
     assert meta["bundle_sha256"]
diff --git a/tests/test_provider_integration.py b/tests/test_provider_integration.py
new file mode 100644
index 000000000..1fd718c2b
--- /dev/null
+++ b/tests/test_provider_integration.py
@@ -0,0 +1,175 @@
+"""
+Provider integration tests — real API calls to verify each LLM provider works.
+
+These tests are marked with @pytest.mark.integration and excluded from the
+default pytest run via pyproject.toml addopts. They run only on:
+  - main / ouroboros / ouroboros-stable push (CI Tier 2.5)
+  - workflow_dispatch (manual)
+  - tag push (v*)
+
+Each test is individually skipped when its API key is absent, so the job
+stays green even if only a subset of keys is configured.
+
+`LLMClient.chat()` returns a `(msg_dict, usage_dict)` tuple since v4.44.0.
+The shared assertion below also handles the legacy flat-dict shape so tests
+do not need to track the underlying client refactor.
+"""
+
+import os
+import pytest
+
+# Skip the entire module during routine pytest runs that use addopts -m "not integration".
+# The mark also works as a per-test filter.
+integration = pytest.mark.integration
+
+
+def _get_llm_client():
+    """Lazy import to avoid breaking collection when ouroboros is not installed."""
+    from ouroboros.llm import LLMClient
+    return LLMClient()
+
+
+def _assert_basic_response(result, expected_provider=None):
+    """Shared assertion: non-empty reply, token usage present.
+
+    In v4.44.0+ LLMClient.chat() returns a (msg_dict, usage_dict) tuple,
+    not a flat dict. Handle both shapes for forward compatibility.
+    """
+    if isinstance(result, tuple):
+        msg, usage = result
+    else:
+        msg, usage = result, result.get("usage", {}) if isinstance(result, dict) else {}
+
+    text = ""
+    if isinstance(msg, dict):
+        text = msg.get("content", "") or ""
+        # Anthropic returns content as a list of typed blocks instead of a string.
+        if isinstance(text, list):
+            text = " ".join(
+                b.get("text", "") for b in text if isinstance(b, dict)
+            )
+    assert text, f"Empty response from LLM: {result}"
+
+    assert isinstance(usage, dict), f"Usage is not a dict: {type(usage)}"
+    assert usage.get("prompt_tokens", 0) > 0, f"No prompt_tokens in usage: {usage}"
+    assert usage.get("completion_tokens", 0) > 0, f"No completion_tokens in usage: {usage}"
+
+    if expected_provider:
+        resolved = usage.get("provider", "") or usage.get("resolved_model", "") or ""
+        assert expected_provider.lower() in resolved.lower(), (
+            f"Expected provider '{expected_provider}' in resolved model, "
+            f"got '{resolved}'"
+        )
+
+
+@integration
+@pytest.mark.skipif(
+    not os.environ.get("OPENROUTER_API_KEY"),
+    reason="OPENROUTER_API_KEY not set",
+)
+def test_openrouter_basic_chat():
+    """Verify OpenRouter responds to a minimal chat request."""
+    client = _get_llm_client()
+    result = client.chat(
+        messages=[{"role": "user", "content": "Respond with exactly: OK"}],
+        model="anthropic/claude-sonnet-4.6",
+    )
+    _assert_basic_response(result, expected_provider="openrouter")
+
+
+@integration
+@pytest.mark.skipif(
+    not os.environ.get("OPENAI_API_KEY"),
+    reason="OPENAI_API_KEY not set",
+)
+def test_openai_direct_basic_chat():
+    """Verify official OpenAI direct routing works."""
+    client = _get_llm_client()
+    result = client.chat(
+        messages=[{"role": "user", "content": "Respond with exactly: OK"}],
+        model="openai::gpt-4o-mini",
+    )
+    _assert_basic_response(result, expected_provider="openai")
+
+
+@integration
+@pytest.mark.skipif(
+    not os.environ.get("ANTHROPIC_API_KEY"),
+    reason="ANTHROPIC_API_KEY not set",
+)
+def test_anthropic_direct_basic_chat():
+    """Verify direct Anthropic routing works."""
+    client = _get_llm_client()
+    result = client.chat(
+        messages=[{"role": "user", "content": "Respond with exactly: OK"}],
+        model="anthropic::claude-sonnet-4-6",
+    )
+    _assert_basic_response(result, expected_provider="anthropic")
+
+
+# Isolation tests: clear competing provider keys so LLMClient can only route
+# through the single provider under test.
+
+_COMPETING_KEYS = [
+    "OPENROUTER_API_KEY",
+    "OPENAI_API_KEY",
+    "OPENAI_BASE_URL",
+    "OPENAI_COMPATIBLE_API_KEY",
+    "OPENAI_COMPATIBLE_BASE_URL",
+    "CLOUDRU_FOUNDATION_MODELS_API_KEY",
+    "ANTHROPIC_API_KEY",
+]
+
+
+@integration
+@pytest.mark.skipif(
+    not os.environ.get("OPENROUTER_API_KEY"),
+    reason="OPENROUTER_API_KEY not set",
+)
+def test_openrouter_isolation(monkeypatch):
+    """OpenRouter works when it is the only configured provider."""
+    for key in _COMPETING_KEYS:
+        if key != "OPENROUTER_API_KEY":
+            monkeypatch.delenv(key, raising=False)
+    client = _get_llm_client()
+    result = client.chat(
+        messages=[{"role": "user", "content": "Say hello"}],
+        model="anthropic/claude-sonnet-4.6",
+    )
+    _assert_basic_response(result)
+
+
+@integration
+@pytest.mark.skipif(
+    not os.environ.get("OPENAI_API_KEY"),
+    reason="OPENAI_API_KEY not set",
+)
+def test_openai_direct_isolation(monkeypatch):
+    """OpenAI direct works when it is the only configured provider."""
+    for key in _COMPETING_KEYS:
+        if key != "OPENAI_API_KEY":
+            monkeypatch.delenv(key, raising=False)
+    client = _get_llm_client()
+    result = client.chat(
+        messages=[{"role": "user", "content": "Say hello"}],
+        model="openai::gpt-4o-mini",
+    )
+    _assert_basic_response(result)
+
+
+@integration
+@pytest.mark.skipif(
+    not os.environ.get("ANTHROPIC_API_KEY"),
+    reason="ANTHROPIC_API_KEY not set",
+)
+def test_anthropic_direct_isolation(monkeypatch):
+    """Anthropic direct works when it is the only configured provider."""
+    for key in _COMPETING_KEYS:
+        if key != "ANTHROPIC_API_KEY":
+            monkeypatch.delenv(key, raising=False)
+    client = _get_llm_client()
+    result = client.chat(
+        messages=[{"role": "user", "content": "Say hello"}],
+        model="anthropic::claude-sonnet-4-6",
+    )
+    _assert_basic_response(result)
diff --git a/tests/test_release_workflow.py b/tests/test_release_workflow.py
index 342b47981..7f1a0d5b9 100644
--- a/tests/test_release_workflow.py
+++ b/tests/test_release_workflow.py
@@ -30,5 +30,5 @@ def test_ci_build_job_exports_release_tag_and_fetches_full_history():
     workflow = _workflow()
 
     assert "OUROBOROS_RELEASE_TAG: ${{ github.ref_name }}" in workflow
-    assert "OUROBOROS_MANAGED_SOURCE_BRANCH: ouroboros-three-layer" in workflow
+    assert "OUROBOROS_MANAGED_SOURCE_BRANCH: ouroboros" in workflow
     assert "fetch-depth: 0" in workflow
diff --git a/web/modules/chat.js b/web/modules/chat.js
index 5e90b4622..1139a7ded 100644
--- a/web/modules/chat.js
+++ b/web/modules/chat.js
@@ -68,6 +68,7 @@ export function initChat({ ws, state, updateUnreadBadge }) {
             <span id="chat-status" class="status-badge offline">Connecting...</span>
         </div>
         <div id="chat-messages"></div>
+        <div class="chat-bottom-fade" aria-hidden="true"></div>
         <div id="chat-input-area">
             <div id="chat-attachment-preview" class="chat-attachment-preview"></div>
             <div class="chat-input-wrap">
@@ -75,7 +76,7 @@ export function initChat({ ws, state, updateUnreadBadge }) {
                     <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M21.44 11.05l-9.19 9.19a6 6 0 0 1-8.49-8.49l9.19-9.19a4 4 0 0 1 5.66 5.66l-9.2 9.19a2 2 0 0 1-2.83-2.83l8.49-8.48"/></svg>
                 </button>
                 <input type="file" id="chat-file-input" class="chat-file-input-hidden" accept="*/*">
-                <textarea id="chat-input" placeholder="Message Ouroboros..." rows="1"></textarea>
+                <textarea id="chat-input" placeholder="Message Ouroboros..." rows="1" autocorrect="off" autocapitalize="off" spellcheck="false"></textarea>
                 <div class="chat-send-group">
                     <button class="chat-send-inline" id="chat-send" title="Send message">Send</button>
                     <button class="chat-send-chevron" id="chat-send-chevron" type="button" title="More send options" aria-label="More send options">
@@ -111,14 +112,10 @@ export function initChat({ ws, state, updateUnreadBadge }) {
     const attachmentPreview = document.getElementById('chat-attachment-preview');
     let pendingAttachment = null;
 
-    attachBtn.addEventListener('click', () => fileInput.click());
-
-    // Stage the selected File object locally — no server upload until sendMessage().
-    // This avoids orphan files, race conditions with fast-send, and network usage for unsent files.
-    fileInput.addEventListener('change', () => {
-        const file = fileInput.files[0];
+    // Shared stager: paperclip change handler AND clipboard paste both go through here
+    // so the attachment badge / removal UI / upload-on-Send semantics are identical.
+    function stagePendingFile(file) {
         if (!file) return;
-        fileInput.value = '';
         pendingAttachment = { file, display_name: file.name };
         attachmentPreview.classList.add('visible');
         attachmentPreview.innerHTML = `
@@ -135,6 +132,43 @@ export function initChat({ ws, state, updateUnreadBadge }) {
             attachmentPreview.innerHTML = '';
             requestAnimationFrame(() => updateMessagesPadding());
         });
+    }
+
+    attachBtn.addEventListener('click', () => fileInput.click());
+
+    // Stage the selected File object locally — no server upload until sendMessage().
+    // This avoids orphan files, race conditions with fast-send, and network usage for unsent files.
+    fileInput.addEventListener('change', () => {
+        const file = fileInput.files[0];
+        if (!file) return;
+        fileInput.value = '';
+        stagePendingFile(file);
+    });
+
+    // Clipboard image paste: scan clipboardData.items for image/*, wrap as File via
+    // getAsFile(), and route through the same stagePendingFile() path the paperclip
+    // uses. preventDefault() runs ONLY when an image is matched so non-image clipboard
+    // payloads (text, formatted text) still paste natively into the textarea. The
+    // generated filename uses a unix timestamp + the MIME-derived extension so each
+    // paste is a distinct attachment if the user pastes several in a row.
+    input.addEventListener('paste', (e) => {
+        const items = e.clipboardData && e.clipboardData.items;
+        if (!items) return;
+        for (let i = 0; i < items.length; i += 1) {
+            const item = items[i];
+            if (item && item.kind === 'file' && typeof item.type === 'string' && item.type.startsWith('image/')) {
+                const blob = item.getAsFile();
+                if (!blob) continue;
+                e.preventDefault();
+                const ext = (item.type.split('/')[1] || 'png').split(';')[0].trim() || 'png';
+                const ts = Date.now();
+                const safeBlob = blob instanceof File
+                    ? new File([blob], `clipboard-${ts}.${ext}`, { type: blob.type })
+                    : new File([blob], `clipboard-${ts}.${ext}`, { type: item.type });
+                stagePendingFile(safeBlob);
+                return;
+            }
+        }
     });
 
     // Set to true during syncHistory pass 1 to suppress premature DOM insertion of
diff --git a/web/style.css b/web/style.css
index 29bb537ee..ef86a7902 100644
--- a/web/style.css
+++ b/web/style.css
@@ -1425,6 +1425,32 @@ body {
     }
 }
 
+/* Bottom scroll-under fade rendered by a DEDICATED sibling layer so it sits
+   visually BELOW #chat-input-area (which is z-index: 5) and never optically
+   swallows the textarea or the attachment badge. Earlier versions painted
+   this gradient as #chat-input-area's own background, which made the lower
+   edge of the input visually dissolve into the dense end of the gradient
+   (rgba(13, 11, 15, 0.92)). Now the gradient is on its own pointer-events:none
+   layer at z-index: 4. Height is 200px so it always covers the tallest
+   `#chat-input-area` state (attachment badge ~30px + fully-expanded textarea
+   ~120px + padding 24px ≈ 174px) with a buffer. */
+.chat-bottom-fade {
+    position: absolute;
+    left: 0;
+    right: 0;
+    bottom: 0;
+    height: 200px;
+    pointer-events: none;
+    z-index: 4;
+    background: linear-gradient(
+        0deg,
+        rgba(13, 11, 15, 0.92) 0%,
+        rgba(13, 11, 15, 0.74) 35%,
+        rgba(13, 11, 15, 0.30) 78%,
+        rgba(13, 11, 15, 0.00) 100%
+    );
+}
+
 #chat-input-area {
     display: flex;
     flex-direction: column;
@@ -1436,20 +1462,10 @@ body {
     left: 0;
     right: 0;
     z-index: 5;
-    /* Bottom scroll-under fade. Reaches a fully-transparent stop at the
-       upper edge so the transcript blends into the input dock without a
-       hard border. Previous gradient bottomed at 0.26 alpha and made a
-       visible step against the page background. */
-    background: linear-gradient(
-        0deg,
-        rgba(13, 11, 15, 0.92) 0%,
-        rgba(13, 11, 15, 0.74) 35%,
-        rgba(13, 11, 15, 0.30) 78%,
-        rgba(13, 11, 15, 0.00) 100%
-    );
-    /* Mask the blur (when used) to fade in step with the gradient. */
-    -webkit-mask-image: linear-gradient(0deg, black 0%, black 60%, transparent 100%);
-            mask-image: linear-gradient(0deg, black 0%, black 60%, transparent 100%);
+    /* No background here on purpose. The bottom scroll-under fade is rendered
+       by .chat-bottom-fade (z-index: 4) which sits visually below this dock,
+       so the textarea's own frosted-glass background reads cleanly without
+       the gradient bleeding through it. */
 }
 
 .chat-input-wrap {
@@ -3086,6 +3102,13 @@ body {
         padding-bottom: max(16px, env(safe-area-inset-bottom, 0px));
     }
 
+    /* Bottom-fade layer grows by the safe-area inset so the gradient still
+       fully covers the tallest expanded textarea state on iOS where the
+       home-indicator pushes the input area up. */
+    .chat-bottom-fade {
+        height: calc(200px + env(safe-area-inset-bottom, 0px));
+    }
+
     /* Header is now in normal flow on mobile — remove the desktop 56px top
        padding that was meant to clear the absolute-positioned header. */
     #chat-messages {