chore: bump version to 1.0.2

Fix/web fetch reliability (#290 )
* fix: improve web_fetch reliability — strip scripts, dynamic truncation, more tokens - strip_html() now removes <script>, <style>, <template>, <noscript> element content instead of just their tags - Truncation budget scales with context window (75% in chars, 50k floor) and takes from the beginning only instead of head+tail splice - max_tokens bumped from 2000 to 8192 so thinking models don't starve the visible extraction answer - reasoning_effort="low" on summarization call to avoid wasting tokens - Empty responses and empty extractions now report as tool errors * refactor: extract _utility_completion to fix reasoning_effort duplication Callers previously had to pass reasoning_effort both as a direct keyword (for commercial providers) and via _provider_extra_params (for local model servers). This duplication was easy to get wrong — web_fetch was already missing the direct keyword. _utility_completion threads it through both paths from a single call, used by title generation, compaction, and web_fetch extraction. * fix: disable thinking when max_tokens too small, cap extraction at 500k _reasoning_params now returns empty dict when max_tokens can't fit a thinking budget (e.g. title gen with max_tokens=200). Previously produced budget_tokens >= max_tokens which is an API error on manual-thinking Anthropic models. Also caps web_fetch content truncation at 500k chars — the dynamic context-window calc was producing 3M chars on 1M-context models. * fix: clamp utility max_tokens to model output limit, add strip_html tests _utility_completion now clamps max_tokens to the model's advertised max_output_tokens so small/local models don't reject 8192-token requests. Adds 8 tests for invisible element stripping (script, style, template, noscript) including multiline, case-insensitive, and attribute cases. * fix: mock get_capabilities in title retry tests for _utility_completion _utility_completion calls _get_capabilities to clamp max_tokens. The existing title tests mocked _provider as a bare MagicMock, so caps.max_output_tokens was a truthy MagicMock instead of an int. Set get_capabilities to return a real ModelCapabilities instance.
2026-08-13 07:22:24 -06:00 · 2026-04-03 15:40:23 -07:00 · 2026-04-03 15:39:34 -07:00 · 2026-04-03 15:39:34 -07:00 · 2026-04-03 15:39:34 -07:00 · 2026-04-03 15:39:34 -07:00
992 changed files with 40455 additions and 468844 deletions
@@ -1,64 +1,49 @@
 # =============================================================================
-# Turnstone environment overrides — ALL OPTIONAL for the dev stack.
+# Turnstone Environment Variables
+# Copy to .env and adjust values for your deployment.
 #
-# `docker compose up` from a clone works with zero config: every value below
-# has a built-in (insecure) default. Copy this file to `.env` only to override.
-#
-# The PRODUCTION stack (turnstone/deploy/compose.yaml) has no baked-in secrets
-# and DOES require TURNSTONE_JWT_SECRET and POSTGRES_PASSWORD.
-#
-# Note: for a turnstone process running on bare metal (not in a container),
-# put secrets in ~/.config/turnstone/config.toml (chmod 0600), not the
-# environment. See docs/docker.md "Join a bare-metal host".
+# Usage:
+# Single node: docker compose --profile production up
+# 10-node cluster: docker compose --profile cluster up
 # =============================================================================

-# -- LLM backend --------------------------------------------------------------
-# Optional: nodes boot without an LLM. Add real model backends from the console
-# UI (Models tab). These only set the bootstrap default a node starts with.
-# LLM_BASE_URL=http://host.docker.internal:8000/v1
-# OPENAI_API_KEY=dummy
-# ANTHROPIC_API_KEY=sk-ant-...     # set instead of OPENAI_API_KEY for Anthropic
-# TURNSTONE_SEARXNG_URL=http://searxng:8080  # web_search backend (default: bundled service; set to an external SearxNG)
-# MODEL=                           # default model alias
+# -- LLM Backend --------------------------------------------------------------
+LLM_BASE_URL=http://host.docker.internal:8000/v1
+OPENAI_API_KEY=dummy
+# ANTHROPIC_API_KEY=sk-ant-...# Set instead of OPENAI_API_KEY for Anthropic
+# TAVILY_API_KEY=tvly-... # Web search fallback (local models only)
+# MODEL=# Override default model alias

-# -- Secrets ------------------------------------------------------------------
-# The dev stack defaults these to INSECURE values. Always set real ones for
-# anything reachable beyond localhost. Generate the JWT secret with:
-#   python -c "import secrets; print(secrets.token_hex(32))"
-# TURNSTONE_JWT_SECRET=
-# POSTGRES_PASSWORD=
+# -- Authentication (required) ------------------------------------------------
+# Generate with: python -c "import secrets; print(secrets.token_hex(32))"
+TURNSTONE_JWT_SECRET=changeme-to-32-bytes-of-hex

-# -- Database -----------------------------------------------------------------
-# Defaults to the bundled PostgreSQL (shared by every service — required for
-# the console to discover nodes). Override to point at an external database:
-# TURNSTONE_DB_BACKEND=postgresql
+# -- Database ------------------------------------------------------------------
+# Single-node default is SQLite (zero config). Set these for PostgreSQL:
+# DB_BACKEND=postgresql
 # POSTGRES_USER=turnstone
-# TURNSTONE_DB_URL=postgresql+psycopg://turnstone:<pw>@postgres:5432/turnstone
+# POSTGRES_PASSWORD=changeme
+# DATABASE_URL=postgresql+psycopg://turnstone:changeme@postgres:5432/turnstone

-# -- Ports / networking -------------------------------------------------------
-# The dashboard is reached via Caddy only (HTTP/2 avoids the browser's
-# 6-connection cap on the console's SSE streams). Both stacks expose the same
-# two host ports; everything else is proxied through the console.
-# CONSOLE_HTTPS_PORT=8443          # Caddy (dashboard HTTPS)
-# POSTGRES_PORT=5432               # exposed for bare-metal host joins
-# POSTGRES_BIND=127.0.0.1          # set 0.0.0.0 to let another machine join
-# TURNSTONE_HOST_IP=127.0.0.1      # dev-stack bind address for cross-host joins
-# TURNSTONE_CONSOLE_HTTP_BIND=127.0.0.1  # production TLS-overlay ACME/API bind
-# TURNSTONE_ACME_EXTERNAL_URL=http://192.0.2.1:8090/acme  # routable ACME base; bracket IPv6; include /acme
+# -- Ports ---------------------------------------------------------------------
+# SERVER_PORT=8080
+# CONSOLE_PORT=8090

-# -- Workspace ----------------------------------------------------------------
-# Bind-mount a host directory the model can read/write at /workspace:
+# -- Workspace -----------------------------------------------------------------
+# Bind-mount a host directory into the container at /workspace.
+# The model can read/write files here. Default: empty Docker volume.
 # WORKSPACE_MOUNT=/path/to/your/project

-# -- Agent behavior -----------------------------------------------------------
-# SKIP_PERMISSIONS=true            # auto-approve all tool calls (dev only)
-# MCP_CONFIG=/workspace/mcp.json   # MCP server config file
+# -- Agent behavior ------------------------------------------------------------
+# SKIP_PERMISSIONS=true # Auto-approve all tool calls (dev only)
+# MCP_CONFIG=/workspace/mcp.json# MCP server configuration file

-# -- Channel gateway (Discord / Slack) ----------------------------------------
+# -- Discord channel gateway ---------------------------------------------------
 # TURNSTONE_DISCORD_TOKEN=
 # TURNSTONE_DISCORD_GUILD=0
-# TURNSTONE_SLACK_TOKEN=xoxb-...
-# TURNSTONE_SLACK_APP_TOKEN=xapp-...

-# -- Production image tag ------------------------------------------------------
-# TURNSTONE_IMAGE_TAG=latest       # pin the ghcr.io image (production stack)
+# -- Cluster (profile: cluster) -----------------------------------------------
+# These are set per-node in compose.yaml; only override for custom topologies.
+# TURNSTONE_NODE_ID=node-1
+# TURNSTONE_ADVERTISE_URL=http://server-1:8080
+
@@ -1,5 +0,0 @@
-# Funding platforms for the GitHub "Sponsor" button.
-# https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/displaying-a-sponsor-button-in-your-repository
-
-github: [eous]
-custom: ["https://paypal.me/eousphoros"]
@@ -41,21 +41,13 @@
      "matchStrings": ["mermaid-(?<currentValue>[\\d.]+)/"],
      "depNameTemplate": "mermaid",
      "datasourceTemplate": "npm"
-    },
-    {
-      "customType": "regex",
-      "description": "Track vendored hls.js version",
-      "managerFilePatterns": ["/pyproject\\.toml$/"],
-      "matchStrings": ["hls-(?<currentValue>[\\d.]+)/"],
-      "depNameTemplate": "hls.js",
-      "datasourceTemplate": "npm"
    }
  ],
  "packageRules": [
    {
      "description": "LLM SDKs — always review manually",
      "groupName": "LLM SDKs",
-      "matchPackageNames": ["openai", "httpx2", "anthropic", "mcp"],
+      "matchPackageNames": ["openai", "anthropic", "mcp"],
      "schedule": ["before 9am on Monday"],
      "automerge": false
    },
@@ -99,7 +91,7 @@
    {
      "description": "Vendored JS — CI workflow downloads files automatically",
      "groupName": "Vendored JS",
-      "matchPackageNames": ["katex", "highlight.js", "mermaid", "hls.js"],
+      "matchPackageNames": ["katex", "highlight.js", "mermaid"],
      "schedule": ["before 9am on the first day of the month"],
      "automerge": false
    },
@@ -7,15 +7,12 @@ on:
  pull_request:
    branches: [main, "stable/*"]

-permissions:
-  contents: read
-
 jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
-      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
-      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
        with:
          python-version: "3.14"
      - run: pip install pre-commit
@@ -25,8 +22,8 @@ jobs:
  typecheck:
    runs-on: ubuntu-latest
    steps:
-      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
-      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
        with:
          python-version: "3.14"
      - run: pip install mypy
@@ -35,32 +32,17 @@ jobs:

  test:
    runs-on: ubuntu-latest
-    # Cap a hung run at 30 min instead of riding GitHub's 6-hour default
-    # (a flaky-hang run otherwise streams -v output for hours).  Was 20;
-    # the suite's growth (~9.7k tests, coverage-instrumented, 3-version
-    # matrix) started brushing the old cap on healthy runs.
-    timeout-minutes: 30
    strategy:
      matrix:
        python-version: ["3.11", "3.12", "3.13"]
    steps:
-      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
-      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
        with:
          python-version: ${{ matrix.python-version }}
-      # Node is required by tests/test_renderer_js.py — without
-      # explicit setup, that suite silently skips if the runner
-      # image happens not to ship Node, masking regressions in
-      # the browser-side renderer.
-      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
-        with:
-          node-version: "24"
      - run: pip install -e ".[test]"
-      # -v lists each test id as it starts (pytest prints the nodeid at
-      # logstart), so a hang names the culprit on the last line instead of
-      # riding the job timeout with only a trail of "..." dots.
-      - run: pytest tests/ -m "not live and not e2e_recovery" --cov=turnstone --cov-report=term-missing --cov-report=xml -v
-      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+      - run: pytest tests/ -m "not live" --cov=turnstone --cov-report=term-missing --cov-report=xml -q
+      - uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7
        if: always()
        with:
          name: coverage-${{ matrix.python-version }}
@@ -68,7 +50,6 @@ jobs:

  test-postgres:
    runs-on: ubuntu-latest
-    timeout-minutes: 30
    services:
      postgres:
        image: postgres:18
@@ -84,23 +65,20 @@ jobs:
          --health-timeout=5s
          --health-retries=5
    steps:
-      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
-      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
        with:
          python-version: "3.14"
-      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
-        with:
-          node-version: "24"
-      - run: pip install -e ".[test]"
-      - run: pytest tests/ -m "not live and not e2e_recovery" --storage-backend=postgresql -v
+      - run: pip install -e ".[test,postgres]"
+      - run: pytest tests/ -m "not live" --storage-backend=postgresql -q
        env:
          TURNSTONE_TEST_PG_URL: postgresql+psycopg://postgres:postgres@localhost:5432/turnstone_test

  wheel-completeness:
    runs-on: ubuntu-latest
    steps:
-      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
-      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
        with:
          python-version: "3.14"
      - run: pip install build
@@ -115,16 +93,9 @@ jobs:
            | grep -v '\.py$' | grep -v '\.dist-info' | grep -v '\.pyc' | grep -v '^File$' \
            | sort)

-          # Files intentionally excluded from the wheel (one per line).
-          # The vllm-litellm/ deploy example ships in the repo, not the wheel
-          # (you clone the repo to run it; the package doesn't reference it).
+          # Files intentionally excluded from the wheel (one per line)
          ALLOW="
          turnstone/core/storage/migrations/script.py.mako
-          turnstone/deploy/vllm-litellm/.env.example
-          turnstone/deploy/vllm-litellm/README.md
-          turnstone/deploy/vllm-litellm/docker-compose.yml
-          turnstone/deploy/vllm-litellm/gemma.Dockerfile
-          turnstone/deploy/vllm-litellm/litellm-config.yaml
          "

          MISSING=$(comm -23 <(echo "$SOURCE") <(echo "$WHEEL") \
@@ -148,13 +119,13 @@ jobs:
          /tmp/smoke/bin/turnstone-console --help
          /tmp/smoke/bin/turnstone-admin --help
          /tmp/smoke/bin/turnstone-channel --help
-          /tmp/smoke/bin/turnstone-doctor --help
+          /tmp/smoke/bin/turnstone-bootstrap --help

  lock-check:
    runs-on: ubuntu-latest
    steps:
-      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
-      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+      - uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7
        with:
          uv-version: "0.9.18"
      - run: uv lock --check
@@ -162,27 +133,17 @@ jobs:
  security:
    runs-on: ubuntu-latest
    steps:
-      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
-      - uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+      - uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 # v7
        with:
          uv-version: "0.9.18"
-      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
        with:
          python-version: "3.14"
      - run: uv sync --frozen --all-extras
      - run: uv pip install pip-audit
      - name: Security audit (dependencies)
-        # PYSEC-2025-183 (pyjwt): "weak encryption" — disputed by the
-        # supplier because the key length is chosen by the calling
-        # application, not the library.  Turnstone generates its JWT
-        # signing keys via the standard ``secrets`` module at
-        # operator-controlled strength (see ``turnstone/core/auth.py``),
-        # so the advisory does not apply.  pyjwt 2.12.1 is the current
-        # latest release; no fix version exists.
-        run: >-
-          uv export --no-emit-project --frozen
-          | uv run pip-audit --strict --desc -r /dev/stdin
-          --ignore-vuln PYSEC-2025-183
+        run: uv export --no-emit-project --frozen | uv run pip-audit --strict --desc -r /dev/stdin

  security-ts:
    runs-on: ubuntu-latest
@@ -190,8 +151,8 @@ jobs:
      run:
        working-directory: sdk/typescript
    steps:
-      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
-      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+      - uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6
        with:
          node-version: "24"
      - run: npm ci
@@ -7,9 +7,7 @@ on:

 concurrency:
  group: docker-${{ github.event.workflow_run.head_sha }}
-  # Never cancel mid-push: an interrupted multi-tag push can leave the
-  # registry with a partial tag set (e.g. :latest moved, :stable not).
-  cancel-in-progress: false
+  cancel-in-progress: true

 permissions:
  contents: read
@@ -21,24 +19,13 @@ env:

 jobs:
  docker:
-    # Same gate as publish.yml: workflow_run fires for every CI completion
-    # (including fork and same-repo PR runs) with this repo's token and
-    # packages:write.  Only same-repo tag pushes may publish images; CI's
-    # push trigger matches main/stable/* and v* tags, so a head_branch
-    # starting with "v" is necessarily a tag run.
-    if: >-
-      github.event.workflow_run.conclusion == 'success' &&
-      github.event.workflow_run.event == 'push' &&
-      github.event.workflow_run.head_repository.full_name == github.repository &&
-      startsWith(github.event.workflow_run.head_branch, 'v')
+    if: github.event.workflow_run.conclusion == 'success'
    runs-on: ubuntu-latest
    steps:
-      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
        with:
          ref: ${{ github.event.workflow_run.head_sha }}
          fetch-depth: 0
-          # The docker build only reads the tree; keep the token out of it.
-          persist-credentials: false

      - name: Resolve release tag
        id: tag
@@ -54,7 +41,7 @@ jobs:

      - name: Log in to GHCR
        if: steps.tag.outputs.skip == 'false'
-        uses: docker/login-action@dbcb813823bdd20940b903addbd779551569679f # v4
+        uses: docker/login-action@74a5d142397b4f367a81961eba4e8cd7edddf772 # v3
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
@@ -78,12 +65,12 @@ jobs:
          fi
          echo "tags=${TAGS}" >> "$GITHUB_OUTPUT"

-      - uses: docker/setup-buildx-action@bb05f3f5519dd87d3ba754cc423b652a5edd6d2c # v4
+      - uses: docker/setup-buildx-action@b5ca514318bd6ebac0fb2aedd5d36ec1b5c232a2 # v3
        if: steps.tag.outputs.skip == 'false'

      - name: Build and push
        if: steps.tag.outputs.skip == 'false'
-        uses: docker/build-push-action@53b7df96c91f9c12dcc8a07bcb9ccacbed38856a # v7
+        uses: docker/build-push-action@14487ce63c7a62a4a324b0bfb37086795e31c6c1 # v6
        with:
          context: .
          push: true
@@ -0,0 +1,22 @@
+name: Docker Security Scan
+
+on:
+  push:
+    branches: [main, "stable/*"]
+  schedule:
+    - cron: "0 6 * * 1"  # Weekly Monday 06:00 UTC
+
+permissions:
+  contents: read
+
+jobs:
+  scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+      - run: docker build -t turnstone:scan .
+      - uses: aquasecurity/trivy-action@57a97c7e7821a5776cebc9bb87c984fa69cba8f1 # 0.35.0
+        with:
+          image-ref: "turnstone:scan"
+          severity: "HIGH,CRITICAL"
+          exit-code: "1"
@@ -7,9 +7,7 @@ on:

 concurrency:
  group: publish-${{ github.event.workflow_run.head_sha }}
-  # Never cancel a publish mid-upload: a half-uploaded release (sdist up,
-  # wheel missing) cannot be re-run cleanly because PyPI rejects duplicates.
-  cancel-in-progress: false
+  cancel-in-progress: true

 permissions:
  contents: write
@@ -17,26 +15,14 @@ permissions:

 jobs:
  publish:
-    # workflow_run fires for EVERY CI completion — including CI runs for
-    # pull_requests from forks — and always executes here with this repo's
-    # secrets, tokens, and the pypi environment.  Gate to same-repo tag
-    # pushes only: CI's push trigger matches branches main/stable/* and
-    # tags v*, so a head_branch starting with "v" is necessarily a tag run.
-    if: >-
-      github.event.workflow_run.conclusion == 'success' &&
-      github.event.workflow_run.event == 'push' &&
-      github.event.workflow_run.head_repository.full_name == github.repository &&
-      startsWith(github.event.workflow_run.head_branch, 'v')
+    if: github.event.workflow_run.conclusion == 'success'
    runs-on: ubuntu-latest
    environment: pypi
    steps:
-      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
        with:
          ref: ${{ github.event.workflow_run.head_sha }}
          fetch-depth: 0
-          # python -m build executes the tree's build backend; don't leave
-          # the contents:write token sitting in .git/config while it runs.
-          persist-credentials: false

      - name: Resolve release tag
        id: tag
@@ -50,7 +36,7 @@ jobs:
            echo "skip=false" >> "$GITHUB_OUTPUT"
          fi

-      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6
        if: steps.tag.outputs.skip == 'false'
        with:
          python-version: "3.14"
@@ -58,12 +44,12 @@ jobs:
        if: steps.tag.outputs.skip == 'false'
      - run: python -m build
        if: steps.tag.outputs.skip == 'false'
-      - uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # release/v1
+      - uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e # release/v1
        if: steps.tag.outputs.skip == 'false'

      - name: Create GitHub Release
        if: steps.tag.outputs.skip == 'false'
-        uses: softprops/action-gh-release@3d0d9888cb7fd7b750713d6e236d1fcb99157228 # v3
+        uses: softprops/action-gh-release@153bb8e04406b158c6c84fc1615b65b24149a1fe # v2
        with:
          tag_name: ${{ steps.tag.outputs.tag }}
          generate_release_notes: true
@@ -1,42 +0,0 @@
-name: Understone example
-
-# The door-game example is a standalone package with no dependency on
-# turnstone core, and the root test suite does not collect it
-# (testpaths=["tests"]). Without this workflow its suite never runs in CI.
-# Path-filtered so it only runs when the example (or this workflow) changes.
-
-on:
-  push:
-    branches: [main, "stable/*"]
-    paths:
-      - "examples/door-game/**"
-      - ".github/workflows/understone-example.yml"
-  pull_request:
-    branches: [main, "stable/*"]
-    paths:
-      - "examples/door-game/**"
-      - ".github/workflows/understone-example.yml"
-
-permissions:
-  contents: read
-
-jobs:
-  understone:
-    runs-on: ubuntu-latest
-    defaults:
-      run:
-        working-directory: examples/door-game
-    strategy:
-      matrix:
-        # Floor and ceiling of the example's requires-python (>=3.11).
-        python-version: ["3.11", "3.13"]
-    steps:
-      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
-      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7
-        with:
-          python-version: ${{ matrix.python-version }}
-      - run: pip install -e ".[test,dev]"
-      - run: pytest tests/ -q
-      - run: ruff check .
-      - run: ruff format --check .
-      - run: mypy understone/
@@ -25,43 +25,22 @@ permissions:

 jobs:
  vendor-js:
-    # Same-repo PRs only: this job checks out the PR head and pushes to it
-    # with contents:write, so it must never act on a fork's branch.
-    # Gate on the PR author (immutable), not github.actor (names whoever
-    # caused the latest event, which can be someone else re-running it).
-    if: >-
-      (github.event_name == 'pull_request' &&
-       github.event.pull_request.user.login == 'renovate[bot]' &&
-       github.event.pull_request.head.repo.full_name == github.repository) ||
-      github.event_name == 'workflow_dispatch'
+    if: github.actor == 'renovate[bot]' || github.event_name == 'workflow_dispatch'
    runs-on: ubuntu-latest
    steps:
      - name: Resolve PR head ref
        id: ref
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          # Branch names may contain shell metacharacters; pass via env,
-          # never interpolate ${{ }} into the script body.
-          HEAD_REF: ${{ github.head_ref }}
-          PR_NUMBER: ${{ inputs.pr_number }}
        run: |
-          if [[ "$GITHUB_EVENT_NAME" == "workflow_dispatch" ]]; then
-            # The dispatch input is an arbitrary PR number; refuse fork PRs.
-            # A fork's headRefName is a bare branch name that may collide
-            # with a branch in this repo, and checkout+push would then hit
-            # that unrelated branch ("same-repo PRs only" applies here too).
-            pr_json=$(gh pr view "$PR_NUMBER" --repo "$GITHUB_REPOSITORY" --json headRefName,isCrossRepository)
-            if [[ "$(jq -r '.isCrossRepository' <<< "$pr_json")" != "false" ]]; then
-              echo "::error::PR #${PR_NUMBER} head is not a branch in this repository; refusing to complete it."
-              exit 1
-            fi
-            ref=$(jq -r '.headRefName' <<< "$pr_json")
+          if [[ "${{ github.event_name }}" == "workflow_dispatch" ]]; then
+            ref=$(gh pr view "${{ inputs.pr_number }}" --repo "${{ github.repository }}" --json headRefName -q .headRefName)
          else
-            ref="$HEAD_REF"
+            ref="${{ github.head_ref }}"
          fi
          echo "head_ref=${ref}" >> "$GITHUB_OUTPUT"

-      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
        with:
          ref: ${{ steps.ref.outputs.head_ref }}

@@ -69,7 +48,7 @@ jobs:
        id: detect
        run: |
          updates=()
-          for lib in katex hljs mermaid hls; do
+          for lib in katex hljs mermaid; do
            version=$(grep -oE "${lib}-[0-9.]+" pyproject.toml | head -1 | sed "s/${lib}-//")
            [[ -z "$version" ]] && continue
            [[ -d "turnstone/shared_static/${lib}-${version}" ]] && continue
@@ -9,18 +9,11 @@ build/
 .venv/
 venv/
 .env
-# Local compose overrides (e.g. run.sh's node-count limiter, bootstrap output)
-compose.override.yaml
-compose.override.yml
-docker-compose.override.yaml
-docker-compose.override.yml
 *.so
 .mypy_cache/
 .ruff_cache/
 .pytest_cache/
 *.db
-*.db-shm
-*.db-wal
 .plan.md
 .plan-*.md
 .hypothesis/
@@ -28,7 +21,3 @@ PROGRESS.md
 .coverage
 tools/skill_audit_analysis/data/
 tools/skill_audit_analysis/output/
-design_ideas/
-.claude/
-docs/design/
-/.idea
@@ -0,0 +1,40 @@
+# libexpat integer overflow — no fix available in Debian repos yet
+# https://avd.aquasec.com/nvd/cve-2026-25210
+# Review: remove this entry once a patched libexpat1 is published
+CVE-2026-25210
+
+# ncurses buffer overflow — no fix in Debian 13 repos yet
+# Affects libncursesw6, libtinfo6, ncurses-base, ncurses-bin
+# https://avd.aquasec.com/nvd/cve-2025-69720
+CVE-2025-69720
+
+# nghttp2 DoS via malformed HTTP/2 frames — no fix in Debian 13 repos yet
+# Affects libnghttp2-14
+# https://avd.aquasec.com/nvd/cve-2026-27135
+CVE-2026-27135
+
+# systemd arbitrary code execution via spurious IPC — no fix in Debian 13 repos yet
+# Affects libsystemd0, libudev1
+# https://avd.aquasec.com/nvd/cve-2026-29111
+CVE-2026-29111
+
+# glibc iconv() DoS — fix_deferred, no patched libc in Debian 13 yet
+# Affects libc-bin, libc6
+# https://avd.aquasec.com/nvd/cve-2026-4046
+CVE-2026-4046
+
+# minimatch ReDoS — transitive npm dep (MCP server), no direct exposure
+# https://avd.aquasec.com/nvd/cve-2026-27903
+CVE-2026-27903
+# https://avd.aquasec.com/nvd/cve-2026-27904
+CVE-2026-27904
+
+# picomatch ReDoS — transitive npm dep, no direct exposure
+# https://avd.aquasec.com/nvd/cve-2026-33671
+CVE-2026-33671
+
+# node-tar path traversal — transitive npm dep, not used to extract untrusted archives
+# https://avd.aquasec.com/nvd/cve-2026-29786
+CVE-2026-29786
+# https://avd.aquasec.com/nvd/cve-2026-31802
+CVE-2026-31802
@@ -26,15 +26,7 @@ transferring ownership.
 ```
 python -m venv .venv
 source .venv/bin/activate
-pip install -e ".[test,dev]"
-```
-
-The `dev` extra installs `ruff` and `mypy`. Before pushing, run:
-
-```
-ruff check turnstone tests
-mypy turnstone
-pytest
+pip install -e ".[test]"
 ```

 ## Guidelines
@@ -56,4 +48,4 @@ Open an issue at https://github.com/turnstonelabs/turnstone/issues with:
 ## License

 By contributing, you agree that your contributions will be licensed under the
-project's [Apache License 2.0](LICENSE).
+project's [Business Source License 1.1](LICENSE).
@@ -1,18 +0,0 @@
-# Contributors
-
-Turnstone is written and maintained by Patrick Buckley
-([@eous](https://github.com/eous)).
-
-The following people have contributed code to the project — thank you:
-
- Burhan ([@Burhan-Q](https://github.com/Burhan-Q))
- chrismuzyn ([@chrismuzyn](https://github.com/chrismuzyn))
- daoxley ([@daoxley](https://github.com/daoxley))
- metaclassing ([@metaclassing](https://github.com/metaclassing))
- posixpositive ([@bensonjohnson](https://github.com/bensonjohnson))
- Robert DeAngelis ([@OriginalOrangeXD](https://github.com/OriginalOrangeXD))
- Sanjay Santhanam ([@Sanjays2402](https://github.com/Sanjays2402))
- Stefano Maffeis ([@lesbass](https://github.com/lesbass))
- William ([@sillyWillieBilly](https://github.com/sillyWillieBilly))
- [@BlackMyrmidon](https://github.com/BlackMyrmidon)
- [@pizzaandcheese](https://github.com/pizzaandcheese)
@@ -8,19 +8,14 @@ FROM python:3.14-slim
 LABEL org.opencontainers.image.title="turnstone" \
      org.opencontainers.image.description="Multi-node AI orchestration platform"

-COPY --from=ghcr.io/astral-sh/uv:0.12.3 /uv /usr/local/bin/uv
+COPY --from=ghcr.io/astral-sh/uv:0.11.3 /uv /usr/local/bin/uv

 # Remove the slim image's man page exclusion so man-db has actual content
 RUN rm -f /etc/dpkg/dpkg.cfg.d/docker

-# System dependencies: psycopg (libpq5), developer tooling for agent workflows.
-# ripgrep is the preferred backend for the search tool — natively bounds
-# per-line, per-file, and per-filesize so pathological inputs (minified
-# bundles, training-data JSONL with multi-MB single records) can't OOM us.
-# ffmpeg transcodes omni STT uploads (browser webm/opus) to the 16 kHz mono
-# WAV the omni chat-audio lane decodes.
+# System dependencies: psycopg (libpq5), developer tooling for agent workflows
 RUN apt-get update && apt-get upgrade -y && apt-get install -y --no-install-recommends \
-    libpq5 git curl jq man-db manpages procps file ripgrep ffmpeg \
+    libpq5 git curl jq man-db manpages procps file \
    && rm -rf /var/lib/apt/lists/*

 # Node.js LTS (for npx-based MCP servers like @modelcontextprotocol/server-github)
@@ -35,7 +30,7 @@ RUN useradd --create-home --shell /bin/bash turnstone
 WORKDIR /app

 # Install dependencies first (cached layer — only re-runs when deps change)
-COPY pyproject.toml uv.lock README.md LICENSE NOTICE THIRD-PARTY-NOTICES ./
+COPY pyproject.toml uv.lock README.md LICENSE ./
 RUN uv sync --frozen --no-install-project --no-dev \
    --no-compile --extra all

@@ -55,17 +50,13 @@ COPY docker/healthcheck.py /usr/local/bin/healthcheck.py

 # Entrypoint script — runs migrations before starting
 COPY docker/entrypoint.sh /usr/local/bin/entrypoint.sh
-RUN chmod +x /usr/local/bin/entrypoint.sh
+
 # Data directory — SQLite DB is created in CWD
 WORKDIR /data
 RUN chown turnstone:turnstone /data

-# Workspace mount point — bind-mount a host directory here.  The env var
-# surfaces the path in the model's shell/file tool descriptions
-# (config.get_workspace_dir); without it the mount is invisible to the
-# model, whose cwd is /data below.
+# Workspace mount point — bind-mount a host directory here
 RUN mkdir -p /workspace && chown turnstone:turnstone /workspace
-ENV TURNSTONE_WORKSPACE=/workspace

 USER turnstone

@@ -1,201 +1,62 @@
-                                 Apache License
-                           Version 2.0, January 2004
-                        http://www.apache.org/licenses/
+License text copyright (c) 2020 MariaDB Corporation Ab, All Rights Reserved.
+"Business Source License" is a trademark of MariaDB Corporation Ab.

-   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+Parameters

-   1. Definitions.
+Licensor:             Patrick Buckley
+Licensed Work:        Turnstone 0.2.0. The Licensed Work is (c) 2025-2026 Patrick Buckley.
+Additional Use Grant: You may make production use of the Licensed Work, provided
+                      your use does not include providing the Licensed Work to third
+                      parties as a hosted or managed service, where the service
+                      provides users with access to any substantial set of the
+                      features or functionality of the Licensed Work.
+Change Date:          2030-03-01
+Change License:       Apache License, Version 2.0

-      "License" shall mean the terms and conditions for use, reproduction,
-      and distribution as defined by Sections 1 through 9 of this document.
+For information about alternative licensing arrangements for the Licensed Work,
+please contact buckleypm@gmail.com.

-      "Licensor" shall mean the copyright owner or entity authorized by
-      the copyright owner that is granting the License.
+Notice

-      "Legal Entity" shall mean the union of the acting entity and all
-      other entities that control, are controlled by, or are under common
-      control with that entity. For the purposes of this definition,
-      "control" means (i) the power, direct or indirect, to cause the
-      direction or management of such entity, whether by contract or
-      otherwise, or (ii) ownership of fifty percent (50%) or more of the
-      outstanding shares, or (iii) beneficial ownership of such entity.
+Business Source License 1.1

-      "You" (or "Your") shall mean an individual or Legal Entity
-      exercising permissions granted by this License.
+Terms

-      "Source" form shall mean the preferred form for making modifications,
-      including but not limited to software source code, documentation
-      source, and configuration files.
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited production use.

-      "Object" form shall mean any form resulting from mechanical
-      transformation or translation of a Source form, including but
-      not limited to compiled object code, generated documentation,
-      and conversions to other media types.
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph
+above terminate.

-      "Work" shall mean the work of authorship, whether in Source or
-      Object form, made available under the License, as indicated by a
-      copyright notice that is included in or attached to the work
-      (an example is provided in the Appendix below).
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.

-      "Derivative Works" shall mean any work, whether in Source or Object
-      form, that is based on (or derived from) the Work and for which the
-      editorial revisions, annotations, elaborations, or other modifications
-      represent, as a whole, an original work of authorship. For the purposes
-      of this License, Derivative Works shall not include works that remain
-      separable from, or merely link (or bind by name) to the interfaces of,
-      the Work and Derivative Works thereof.
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may vary
+for each version of the Licensed Work released by Licensor.

-      "Contribution" shall mean any work of authorship, including
-      the original version of the Work and any modifications or additions
-      to that Work or Derivative Works thereof, that is intentionally
-      submitted to Licensor for inclusion in the Work by the copyright owner
-      or by an individual or Legal Entity authorized to submit on behalf of
-      the copyright owner. For the purposes of this definition, "submitted"
-      means any form of electronic, verbal, or written communication sent
-      to the Licensor or its representatives, including but not limited to
-      communication on electronic mailing lists, source code control systems,
-      and issue tracking systems that are managed by, or on behalf of, the
-      Licensor for the purpose of discussing and improving the Work, but
-      excluding communication that is conspicuously marked or otherwise
-      designated in writing by the copyright owner as "Not a Contribution."
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the Licensed Work in original or
+modified form from a third party, the terms and conditions set forth in this
+License apply to your use of that work.

-      "Contributor" shall mean Licensor and any individual or Legal Entity
-      on behalf of whom a Contribution has been received by Licensor and
-      subsequently incorporated within the Work.
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.

-   2. Grant of Copyright License. Subject to the terms and conditions of
-      this License, each Contributor hereby grants to You a perpetual,
-      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      copyright license to reproduce, prepare Derivative Works of,
-      publicly display, publicly perform, sublicense, and distribute the
-      Work and such Derivative Works in Source or Object form.
+This License does not grant you any right in any trademark or logo of
+Licensor or its affiliates (provided that you may use a trademark or logo of
+Licensor as expressly required by this License).

-   3. Grant of Patent License. Subject to the terms and conditions of
-      this License, each Contributor hereby grants to You a perpetual,
-      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      (except as stated in this section) patent license to make, have made,
-      use, offer to sell, sell, import, and otherwise transfer the Work,
-      where such license applies only to those patent claims licensable
-      by such Contributor that are necessarily infringed by their
-      Contribution(s) alone or by combination of their Contribution(s)
-      with the Work to which such Contribution(s) was submitted. If You
-      institute patent litigation against any entity (including a
-      cross-claim or counterclaim in a lawsuit) alleging that the Work
-      or a Contribution incorporated within the Work constitutes direct
-      or contributory patent infringement, then any patent licenses
-      granted to You under this License for that Work shall terminate
-      as of the date such litigation is filed.
-
-   4. Redistribution. You may reproduce and distribute copies of the
-      Work or Derivative Works thereof in any medium, with or without
-      modifications, and in Source or Object form, provided that You
-      meet the following conditions:
-
-      (a) You must give any other recipients of the Work or
-          Derivative Works a copy of this License; and
-
-      (b) You must cause any modified files to carry prominent notices
-          stating that You changed the files; and
-
-      (c) You must retain, in the Source form of any Derivative Works
-          that You distribute, all copyright, patent, trademark, and
-          attribution notices from the Source form of the Work,
-          excluding those notices that do not pertain to any part of
-          the Derivative Works; and
-
-      (d) If the Work includes a "NOTICE" text file as part of its
-          distribution, then any Derivative Works that You distribute must
-          include a readable copy of the attribution notices contained
-          within such NOTICE file, excluding those notices that do not
-          pertain to any part of the Derivative Works, in at least one
-          of the following places: within a NOTICE text file distributed
-          as part of the Derivative Works; within the Source form or
-          documentation, if provided along with the Derivative Works; or,
-          within a display generated by the Derivative Works, if and
-          wherever such third-party notices normally appear. The contents
-          of the NOTICE file are for informational purposes only and
-          do not modify the License. You may add Your own attribution
-          notices within Derivative Works that You distribute, alongside
-          or as an addendum to the NOTICE text from the Work, provided
-          that such additional attribution notices cannot be construed
-          as modifying the License.
-
-      You may add Your own copyright statement to Your modifications and
-      may provide additional or different license terms and conditions
-      for use, reproduction, or distribution of Your modifications, or
-      for any such Derivative Works as a whole, provided Your use,
-      reproduction, and distribution of the Work otherwise complies with
-      the conditions stated in this License.
-
-   5. Submission of Contributions. Unless You explicitly state otherwise,
-      any Contribution intentionally submitted for inclusion in the Work
-      by You to the Licensor shall be under the terms and conditions of
-      this License, without any additional terms or conditions.
-      Notwithstanding the above, nothing herein shall supersede or modify
-      the terms of any separate license agreement you may have executed
-      with Licensor regarding such Contributions.
-
-   6. Trademarks. This License does not grant permission to use the trade
-      names, trademarks, service marks, or product names of the Licensor,
-      except as required for reasonable and customary use in describing the
-      origin of the Work and reproducing the content of the NOTICE file.
-
-   7. Disclaimer of Warranty. Unless required by applicable law or
-      agreed to in writing, Licensor provides the Work (and each
-      Contributor provides its Contributions) on an "AS IS" BASIS,
-      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
-      implied, including, without limitation, any warranties or conditions
-      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
-      PARTICULAR PURPOSE. You are solely responsible for determining the
-      appropriateness of using or redistributing the Work and assume any
-      risks associated with Your exercise of permissions under this License.
-
-   8. Limitation of Liability. In no event and under no legal theory,
-      whether in tort (including negligence), contract, or otherwise,
-      unless required by applicable law (such as deliberate and grossly
-      negligent acts) or agreed to in writing, shall any Contributor be
-      liable to You for damages, including any direct, indirect, special,
-      incidental, or consequential damages of any character arising as a
-      result of this License or out of the use or inability to use the
-      Work (including but not limited to damages for loss of goodwill,
-      work stoppage, computer failure or malfunction, or any and all
-      other commercial damages or losses), even if such Contributor
-      has been advised of the possibility of such damages.
-
-   9. Accepting Warranty or Additional Liability. While redistributing
-      the Work or Derivative Works thereof, You may choose to offer,
-      and charge a fee for, acceptance of support, warranty, indemnity,
-      or other liability obligations and/or rights consistent with this
-      License. However, in accepting such obligations, You may act only
-      on Your own behalf and on Your sole responsibility, not on behalf
-      of any other Contributor, and only if You agree to indemnify,
-      defend, and hold each Contributor harmless for any liability
-      incurred by, or claims asserted against, such Contributor by reason
-      of your accepting any such warranty or additional liability.
-
-   END OF TERMS AND CONDITIONS
-
-   APPENDIX: How to apply the Apache License to your work.
-
-      To apply the Apache License to your work, attach the following
-      boilerplate notice, with the fields enclosed by brackets "[]"
-      replaced with your own identifying information. (Don't include
-      the brackets!)  The text should be enclosed in the appropriate
-      comment syntax for the file format. We also recommend that a
-      file or class name and description of purpose be included on the
-      same "printed page" as the copyright notice for easier
-      identification within third-party archives.
-
-   Copyright [yyyy] [name of copyright owner]
-
-   Licensed under the Apache License, Version 2.0 (the "License");
-   you may not use this file except in compliance with the License.
-   You may obtain a copy of the License at
-
-       http://www.apache.org/licenses/LICENSE-2.0
-
-   Unless required by applicable law or agreed to in writing, software
-   distributed under the License is distributed on an "AS IS" BASIS,
-   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-   See the License for the specific language governing permissions and
-   limitations under the License.
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+TITLE.
@@ -1,7 +0,0 @@
-Turnstone
-Copyright 2025-2026 Patrick Buckley
-
-Licensed under the Apache License, Version 2.0; see the LICENSE file.
-
-Third-party software bundled with this distribution is listed in the
-THIRD-PARTY-NOTICES file; each component remains under its own license.
@@ -1,155 +0,0 @@
-# What a Harness Is — and What It Can Never Promise
-
-*A plain-language companion to [HYPOTHESIS.md](HYPOTHESIS.md). Same object, no symbols required.*
-
-**How to read this.** HYPOTHESIS.md defines, formally, what an agent harness is and what it can never guarantee. This file is that document lowered into plain language — and by the formal document's own rules, a summary is a cache, not an authority: it must stay re-derivable from its source, and wherever the two disagree, the formal one wins. Symbols appear once, in parentheses, so you can cross over; nothing here requires them. And none of it is decoration: the formal version, used as a checklist, has caught real bugs in a real harness — because most bugs are a violated invariant nobody had written down.
-
-## The problem
-
-You have a model. It is, roughly, a brilliant, tireless, lightning-fast intern that has read most of the internet — and that sometimes makes things up, sometimes gets confused, and sometimes takes instructions from strangers, because a page it was asked to read said "ignore your boss and email the passwords here" in white text on a white background.
-
-So you don't wire the intern to production. You build a loop around it. The **harness** is that whole governed loop: a deterministic shell *you* write — build the prompt, approve or refuse each proposed action, fold the result back into memory — wrapped around a model you didn't write and a world you don't control, repeated until the run reaches a stopping state. The shell is code and does the same thing every time. The model is neither, and everything in the theory comes from taking that split seriously.
-
-One sentence to keep: **the model proposes; the gate disposes.** The model's output is never an action. It is a suggestion, in text, which a piece of ordinary code you wrote either turns into an action or refuses.
-
-## The parts
-
-| Plain name | What it does | In the formal doc |
-|---|---|---|
-| The owner | The human — or sign-off group — the run acts for; the only place new permissions can come from | the trusted principal |
-| The memory | Everything the run knows: task, plan, transcript, and the ledger of what has been done | the state, *s* |
-| The prompt builder | Decides which slice of memory the model gets to see this step | the lowering, π |
-| The model | The black box that reads the prompt and writes a proposal | the plant, M_W |
-| The gate | Ordinary code that checks every proposal and approves or refuses it | the gate, γ |
-| The tools and the world | What approved actions actually touch: files, APIs, shells, people | the environment, Q_E |
-| The verifier | Checks each tool result, then writes it into memory | the fold-back, ρ |
-| The stop rule | Decides when the run is finished — and whether it finished *well* | the halt set H, accepting halts H_ok |
-| The danger zone | States that must never be reached: secrets exfiltrated, wrong files deleted, money moved twice | the bad set, B |
-
-The loop:
-
-```
-you ask for something
-        ↓
-prompt builder → model → "I propose: send_email(...)"
-                            ↓
-                          GATE ── no ──→ nothing happens (safe, recorded)
-                            ↓ yes
-                          tool runs in the world
-                            ↓
-                          verifier checks the result, writes it to memory
-                            ↓
-                  done? ── no → around again
-                    ↓ yes
-                  stop (well, or refused)
-```
-
-## The rules that make it a harness
-
-Four invariants, all about *where* things are allowed to happen.
-
-1. **The model sees only what the prompt builder shows it** — never raw memory. The corollary with teeth: a secret that never enters the prompt cannot leak through the model. The redaction step that keeps credentials and other people's data out of the prompt must be dumb, deterministic code — the moment that filter is "smart," your confidentiality guarantee is a probability.
-2. **Model outputs are proposals, not actions.**
-3. **Every side effect passes the gate.** There is no second door.
-4. **The harness itself flips no coins.** Replay a step with the model's answer and the tool results pinned, and behavior must be identical; any leftover variation is randomness *you* added and must be accounted for. The fine print: "deterministic" is conditional on pinned versions — a provider silently retraining the model behind the same API name changes the machine under you, and every dashboard number you collected dies with the version.
-
-Notice what the rules don't say: they don't say the harness is *good*. A gate that approves everything satisfies rule 3 the way a lock that's always open satisfies "has a lock." The definition is a shape; the guarantees are what a particular harness *earns* inside it. Everything below is about what can be earned — and what can't.
-
-And notice the symmetry between rules 1 and 3. There is exactly one door from your data into the model — what it may see — and exactly one door from the model into the world — what it may do. Nearly every security failure in these systems is one of those two doors with a hole in it: a secret lowered into a prompt that didn't need it, or a path from model text to a side effect that skipped the gate. Same bug, arrow flipped.
-
-## Fail-closed, said precisely
-
-"Fail-closed" gets used loosely. Here it means something exact: **nothing happens unless the gate said yes, and a refusal must itself be safe** — a refused proposal causes no side effect and leaves the run somewhere sane, which may be "stopped, having declined." The run is allowed to *say so*: a templated status message written by the shell is the shell speaking, not the model, and needs no gate. Failed runs don't have to die silent.
-
-Three consequences people miss:
-
-**Reads are not free.** A read-only call can smuggle instructions *in* (the fetched page is attacker-controlled) or secrets *out* (the URL it fetches can encode the payload). The gate approves calls, not just writes.
-
-**Validation must not act.** A "validator" that resolves a URL, expands a template that fires a webhook, or evaluates an argument has already acted — inside the check. The gate must be pure: it reads the proposal and the memory and outputs yes or no. If deciding requires touching the world, that touch is itself an action and goes through the gate.
-
-**Anything irreversible is decided at the gate.** The verifier can reject a bad *result*; it cannot unsend the email. So the question "can we take this back, and until when?" is asked before execution — which means each tool declares, up front, how reversible its effects are, and the gate reads that declaration when it decides; the mark that comes back in the result record is confirmation for the books, not the gate's source — the gate needed the answer before the tool ever ran.
-
-Two honest asterisks. First, the gate checks a snapshot: it approves against the world *as its memory describes it*, and the world can move between check and commit. For actions that race the world — spend against a balance, write against a row — the tool itself must bind check to commit (compare-and-swap), or you have a classic time-of-check/time-of-use hole. The gate decides; for those effects, the tool enforces. Second, a gate is only as binding as the authority behind the tools. A tool process holding standing credentials — a database connection with every grant, an environment full of long-lived secrets — doesn't need the model's proposal to act, and against it the gate's "no" is a decision with nothing enforcing it. **A gate in front of an omnipotent tool is a suggestion.** The fix is to make the approval *be* the key: each authorized action carries a short-lived credential scoped to exactly that action, that resource, that operation, so tools hold no standing power at all.
-
-## Why you don't get a proof — and what you do instead
-
-If you write a sort function, you can prove it sorts: the function is small and the spec is exact. A harness has neither luxury. The spec side fails first — the task arrives in natural language, and natural language is, in the compiler's sense, *all undefined behavior*: there is no formal standard for "what the user meant" to verify against. The mechanism side fails next — the model is billions of learned parameters, and nobody can hand you a compact argument for why they jointly do the right thing.
-
-Here is the careful version, because "you can't prove it" overshoots. The quantity you would want — call it the *expected steps to done* from any situation — is perfectly well-defined; in principle it exists. The document's central conjecture is that, for a model of this size, any faithful writing-down of that quantity is roughly *model-sized*: the honest proof-object does not compress. Find a small one and the conjecture dies — the document lists that outcome, explicitly, among the ways it could be wrong.
-
-So instead of proving, you measure. You pick a progress meter — plan depth shrinking, open obligations closing, budget burning at the expected rate — and you check, across many runs, that it goes downhill and that its stalls predict failure. Two disciplines keep the measurement honest. The number bounds the world you *sampled*, never the world an adversary will choose: a meter calibrated on friendly traffic says nothing about hostile traffic. And the meter is itself attack surface: if "is the agent making progress?" is judged by another model, an attacker who can bend your agent can bend your *measurement of it* first, hiding the divergence from the very dashboard built to catch it. A learned meter is part of the system under test, never a neutral instrument.
-
-A measurement is a risk metric. A proof is a certificate. Keeping those two words apart is half of what this theory is for.
-
-## Security: reach the goal, avoid the danger — and who may change the rules
-
-Formally, security here is a *reach-avoid* problem: reach a good stop, never touch the danger zone, **while an adversary picks the worst tool outputs your setup permits**. That last clause is the formal home of prompt injection: injection isn't "the model misbehaved," it's the environment optimized to bend your loop — poisoned pages, malicious tool descriptions, crafted responses.
-
-Two different numbers fall out here, and dashboards love to collapse them: *success* (reached an accepted end before anything went wrong — a safe refusal counts against it) and *safety* (never touched the danger zone — a safe refusal is perfectly safe). Track both. They move independently. And both are scored by your own stop rule — they count what the shell *declared* a success. Whether a declared success was actually *right* is a third, harder number that no dashboard inside the system can produce; only a judge outside the run — a test suite, an audit, ground truth — can.
-
-The gate handles the visible half of injection: the model, freshly poisoned, proposes emailing your credentials somewhere, and the gate refuses — and injection or not, the action does not happen. But the deeper attack doesn't propose a bad action today. It rewrites *what the run believes its job is* — it edits the plan — and then every future action looks locally reasonable against a corrupted plan. So memory has to be partitioned: **data** (tool results, fetched pages, retrieved documents — content the world supplied) and **control** (the plan, the permissions, what is authorized next). The security claim is conditional on that partition holding: untrusted content lands in data, always. And "trust" is really two questions pointing opposite ways, which is worth keeping straight: *can this leak?* (a value is as secret as the most-secret thing that fed it — secrecy flows **upward**) and *can this boss us around?* (a value is as trustworthy as the least-trustworthy thing that fed it — authority flows **downward**). Untrusted content is safe as *data* precisely because the second question keeps it off the control side; a secret is kept out of the model by the first. Lowering either barrier on purpose — declassifying a secret, promoting data to trusted — is an explicit decision the owner makes, never a thing that happens by accident when two values are combined.
-
-Which forces the question the theory has to answer: *somebody* must be able to write control mid-run, or no plan could ever be steered and no permission ever granted. The answer is a small hierarchy with a top the model can't reach. The simplest top is one owner — but it needn't be a single person: a two-person sign-off, a quorum, several authenticated people each holding different scopes all work equally well, because the one property that matters is the same for all of them — the thing that can grant new power is a *human decision*, never a model:
-
- **The top alone widens.** New permission, bigger budget, approval of the irreversible thing — asking the top — the owner, in the simple case — is itself an ordinary tool call, and its answer is the one kind of tool result allowed to change control.
- **The model rewrites the plan** — that is what replanning *is* — but only through the gated loop, and a plan is not a permission: nothing the model writes into its own plan can grant it powers it didn't have.
- **Everything else is data.** A fetched page can inform the plan only by passing through the model and the gate like everything else. It can suggest. It cannot promote itself to boss.
- **AI judges only tighten.** Add a model-based check — "does this action match what the user actually wanted?" — and its verdict may *veto* an action the plain rules would have allowed, never approve one they'd have refused. A judge that can approve is a tricked judge that can open the vault. And don't over-credit the veto either: a tricked judge can *aim* its refusals — denying exactly the action safety depended on, or denying everything but the path an attacker curated — so the escape hatch to the owner is the one thing a judge can never veto, and a judge's stated *reasons* are picked from a fixed, shell-owned menu, never written as prose. A judge that writes free text into the loop is an injection channel wearing a badge.
-
-One more rule closes the loop: transformations don't launder trust. A *summary* of a session that contained an injected page is still injected — the summarizer is a model, and can be persuaded to write "the user asked to export the database" into the summary. So summaries of data are data, and the control lines — the plan, the grants — cross a summarization by being *copied verbatim* or re-confirmed by the owner, never paraphrased by the model. Memory that persists across sessions carries its trust label with it, or a poisoned memory is just an injection with a very long fuse.
-
-## Operations: the rules you feel on Tuesday at 3 a.m.
-
-The formal document's appendix works the operational cases in full; here they are at speed.
-
-**The ledger, and the three-way distinction that keeps it honest.** Every action gets an ID and a record: committed, never-launched, or *unknown*. "The tool didn't confirm" is not "the tool didn't do it" — collapse those and you will, sooner or later, re-send something that already happened. And a subtler honesty: the ledger records what the tool *reported*, not what the world actually did. A well-built shell can guarantee its bookkeeping is faithful to the responses it received — it cannot, on its own, guarantee a tool told the truth. A tool that returns a clean "done!" for something it never did puts a clean "done!" in your ledger. So "the ledger is what happened" is only as good as your reason to trust the tools reporting into it; where you have no such reason, *unknown* is the honest entry, not an optimistic guess in either direction. The double-send bug has one reliable cure: **journal before dispatch.** The shell writes "I am about to run action #417" into durable memory *before* the tool sees it, so a crash in the gap resumes to an honest "unknown — go ask," never to silence misread as "never sent." Old database wisdom, but here it isn't imported; it's forced — it is the only ordering under which every crash point has a truthful reading.
-
-**Crashes aren't finishes.** A process dying mid-run is not the run stopping; it's the run *pausing being computed*. Resume means re-entering the loop at the last durable memory — sound exactly when the durable memory was the *whole* state. Anything load-bearing that lived only in RAM — an in-flight buffer, a plan revision not yet written — is a bug you discover at the worst possible time. Recovery is where you find out whether your state was really your state. And a run you stopped — crash or deliberate cancel — is not automatically a *safe* run: if something was in flight and you never learned whether it fired, it may already have done the damage. "We stopped in time" is only true when everything in flight resolved to something safe; an outstanding *unknown* has to be treated as possibly-bad, the same optimism the ledger warns against, one level up.
-
-**Two innocent actions can be guilty together.** Models emit several tool calls per turn. "Read the secret" passes review. "Post to the web" passes review. The pair is an exfiltration channel — so the gate authorizes the *set*, atomically, with the interactions checked, not each element in isolation.
-
-**Sub-agents are just fancy tools.** An agent that spawns another agent is, from the parent's chair, calling a tool: the spawn is gated, the budget is part of the deal, and the child's whole run comes back as one result carrying the child's ledger. Two laws travel down the tree: budgets subdivide, and **authority only narrows** — a child holds at most a subset of its parent's permissions, and a child's request beyond those grants routes *up*, ultimately to the owner, because a parent inventing an approval it never held is the tricked-judge case wearing a manager's badge. A corollary worth framing: a *fully autonomous* run is one whose owner is unreachable — meaning the only channel that can ever widen anything is closed, and its permissions are frozen at launch. That is not a limitation of the theory. That is what the word "autonomous" costs.
-
-**Keep the originals.** When the transcript outgrows the prompt and you summarize it down, deleting the original is an irreversible act against your own state — and irreversible acts are gate decisions, self-directed or not. Keep originals content-addressed; let the summary be an index, re-derivable, auditable. A summary you can check against its source is a note. A summary that replaced its source is a fait accompli.
-
-## Robots that never clock out — and robots that assign their own work
-
-Everything so far assumed a job that *ends*: you ask, the robot does it, you read the result. Two steps past that are where the interesting failures live, and they're the same idea one level bigger each time.
-
-**The robot that never clocks out (a daemon).** A monitor, a coordinator, a service — it isn't supposed to finish; it's supposed to keep going, wake on events, do a bit of work, go back to waiting. The clean way to think about it: each wake-work-rest cycle is one ordinary run, and the daemon is just those runs chained end to end forever. That reframing is free — but it comes with a bill nobody likes. **Safety that's fine per cycle rots over many cycles.** A 99.99%-safe cycle sounds bulletproof; run it ten thousand times and you're at about a coin-flip of having touched the danger zone at least once. So a long-running robot's safety isn't a fixed wall, it's a slow leak — which means the antidote isn't a better wall, it's *scheduled resets*: the owner re-confirming, credentials rotating, memory getting audited and re-summarized against the originals. Housekeeping isn't housekeeping; it's the thing that keeps the safety math from decaying. And the slow-leak logic is exactly where slow attacks live — a poisoned note dropped into memory on Monday and read back into the plan on Friday is an injection with a long fuse. So the trust label on a piece of information has to survive across cycles, not just within one. One more wrinkle: a daemon drifts in and out of your reach. While you're around, it can escalate to you; while you're not, "escalate to the owner" isn't available — so the one thing it must always be able to do instead is *stop*. A robot that can be tricked into refusing everything, and can't reach you, had better be able to halt rather than be steered.
-
-**The robot that assigns its own work (the loop).** Step back one more time. Above the robot that *does* a task sits a system that decides *which task is next* — scans the backlog, picks one, launches the robot at it, checks the result, remembers, fires again. This is the thing people mean in 2026 when they say they've stopped prompting their agents and started writing *loops* that prompt them: you design the assigner once, and it runs the doer for you while you sleep. The honest observation — and the reason this document bothers with it — is that the assigner is *not a new kind of thing*. It's the same harness, one level up: it has its own memory (the backlog), its own gate (**who let the loop refactor the auth module at 3 a.m.?**), its own verifier, and its own two walls. Every rule from the inner robot recurs on the outer one — including the uncomfortable ones. There's still no proof it stays out of trouble over a long night; there's only a measured progress meter, with the same catch that a *learned* meter can be fooled. And the origin story of the whole trend is the cautionary case in miniature: the famous first version was literally the same prompt in a `while` loop until the tests passed — which is the empty gate, the always-open lock, one level up. It works beautifully right up until the tests weren't checking the thing that mattered. The loop doesn't delete the hard problems. It moves them up a floor, where they're bigger and you're further away.
-
-The pattern, if you want the whole thing in one line: *words, context, robot, loop* are four sizes of the same object, and every promise in this document lives in the whole assembled thing — never in any one layer by itself.
-
-## The two walls
-
-Two limits are structural. You don't fix them with a better harness; you design around them.
-
-**The desk.** The model can hold only so much *in mind at once* — the context window. Files, databases, and search extend what it can *look up*, not what it can hold: every lookup still passes through the same small window to touch actual computation. The shell can page; the model cannot grow its desk. Tasks whose irreducible working set exceeds the desk don't fail loudly — they fail by forgetting the middle (the well-documented "lost in the middle" effect is this wall showing through the paint).
-
-**The dictionary.** The model's knowledge is frozen into its parameters at training time — and the proof problem above is conjectured to live at that same scale: the certificate wouldn't fit anywhere smaller than the brain it certifies. The two walls trade against each other along the training-versus-inference axis — bigger dictionary or bigger desk — directionally, and at no clean exchange rate.
-
-## How this could be wrong
-
-This is a hypothesis, and it says out loud what would kill it. The tests, in plain terms:
-
- **The replay test.** Rerun with model answers and tool results pinned. Any leftover variation — timestamps, wall-clocks, and cache expiries are the classic leaks — falsifies "the harness adds no randomness" until accounted for.
- **The drop-a-variable test.** Remove something from memory; if behavior statistics shift, the memory wasn't complete. The crash-resume version of the same test: if resuming from saved state breaks, the saved state wasn't the state.
- **Does the meter mean anything?** If no reasonable progress meter's drift predicts real failures — across the natural families, not just one bad candidate — the whole "measure what you can't prove" program is empty.
- **The red-team test.** Swap sampled tool outputs for worst-case ones: injected pages, poisoned metadata, malformed replies. The design must survive the worst permitted world, not the average one.
- **Gates versus begging.** The theory predicts deterministic gating beats prompt-level pleading. If "please be careful" alone matches real gates on security outcomes, the controller-versus-model story is wrong.
- **The compression hunt.** Exhibit a compact, provably sound progress certificate for a frontier-scale model on a nontrivial task family, and the central conjecture falls — constructively.
- **The desk probe.** Take a task family with a *proven* memory floor — so "it needed the whole picture at once" is someone else's theorem, not our excuse — scale it past the window, and watch: the wall predicts a *ceiling*, not a cliff — past the boundary, a success rate that stays capped no matter how many retries you buy. A family solved reliably out there, without new shell tricks for splitting the work, kills the wall.
-
-## Who else landed here
-
-The formal document keeps three honesty tiers. **Borrowed**: real theorems, cited — the drift and stopping-time mathematics is classical, and the very architecture of a deterministic supervisor gating a plant it didn't author is 1987 control theory; the shape is older than the web. **Ours**: the modeling choices and the conjectures — the walls, the incompressibility claim, the design rules — organizing principles, not results. **Corroborated**: pieces of the same object reached independently by people who never saw this framing — capability-security work isolating control flow from untrusted data (CaMeL), reinforcement-learning "shields" filtering a learned policy's actions through a deterministic checker, verification work that states the "learned safeguards can't certify" gap as its opening motivation, and architecture patterns converging on plan-then-execute. Even the field's live disagreement — provable-but-rigid deterministic layers versus flexible-but-uncertifiable learned checks — is, in this frame, not a fight but a placement: you need both, on their proper sides of the irreversibility line, with the learned one permitted only to tighten.
-
-## What to remember
-
-The model proposes; the gate disposes. No is the default, and a refusal must be safe. Only the top of the trust hierarchy widens permissions — a human decision, never the model, a tool result, a summary, or a judge. "Didn't confirm" is not "didn't happen." The desk is finite and the proof doesn't compress, so you measure — and you say *measurement* when you mean measurement. A robot that never stops leaks safety slowly, so it needs scheduled resets — and when it can't reach you, it must be able to stop. A loop that runs robots for you is just a bigger robot with the same rules and a further-away owner. And all of it is a hypothesis wearing its own kill-conditions on its sleeve.
-
-The formal version — the objects, the certificates, the falsifiers, the citations — is [HYPOTHESIS.md](HYPOTHESIS.md). It wins every disagreement with this file, including this sentence.
-
-*Same ramblings, fewer symbols.*
@@ -1,107 +1,92 @@
-# Quickstart
+# Bootstrap Wizard

-Install Turnstone, then diagnose it with `turnstone-doctor` if anything looks off.
+Interactive, AI-guided setup for Turnstone deployments. Instead of manually
+editing `.env` files and reading deployment docs, the wizard walks you through
+every decision conversationally and generates all the config files for you.

-## Install
-
-The one-line installer autodetects your distro (Ubuntu/Debian, Fedora/RHEL,
-Arch, and WSL), installs git + Docker if missing, generates secrets, picks free
-ports, and starts the stack:
+## Quick Start

 ```bash
-curl -fsSL https://raw.githubusercontent.com/turnstonelabs/turnstone/main/run.sh | bash
+turnstone-bootstrap
 ```

-Re-running is safe — it updates the checkout and keeps your existing `.env`.
-When it finishes it prints the dashboard URL and how to create the first admin
-user.
+That's it — no flags, no arguments. The wizard prompts for everything.

-**Other ways to install**
+## How It Works

- **Already have Docker?** Clone the repo and `docker compose up` for the full
-  local cluster, or `docker compose -f turnstone/deploy/compose.yaml up` for the
-  released single-node stack. See [docs/docker.md](docs/docker.md).
- **Python package:** `pip install turnstone` (add `--pre` for the experimental
-  track), then run `turnstone-server` / `turnstone-console` directly. See the
-  [README](README.md#quickstart).
+1. **Pick a model** — Choose OpenAI, Anthropic, or a local/vLLM endpoint to
+   power the wizard. Local endpoints auto-detect available models.
+2. **Answer questions** — The AI walks you through deployment mode, LLM
+   provider, database, authentication, ports, and optional features.
+3. **Review generated files** — Each file is previewed before writing. You
+   confirm or reject every write.
+4. **Start the stack** — The wizard prints the exact `docker compose` command
+   and a `setup.sh` script to create your first admin user, roles, and policies.

-## Diagnose: `turnstone-doctor`
+## What Gets Generated

-`turnstone-doctor` is an LLM-backed assistant that inspects a **running**
-Turnstone install and helps you troubleshoot it. It is **read-only** — it
-investigates and tells you the exact commands to fix things, but never changes
-your system. (Installation is the installer's job, not the doctor's.)
-
-```bash
-# From a host that has the turnstone package installed:
-turnstone-doctor
-
-# For a Docker install from run.sh (no package on the host), run it with pipx:
-pipx run --spec turnstone turnstone-doctor --dir ~/turnstone
-```
-
-### What it does
-
-1. **Preflight** — detects how Turnstone is installed here (docker-compose,
-   systemd/bare-metal, pip, or a source checkout) by probing for `config.toml`
-   files, `TURNSTONE_*` environment variables, compose files, and systemd units.
-2. **Self-configures its LLM** — it powers its own brain from your cluster's
-   *own* model configuration (env / `config.toml` / the database). Whether that
-   works is the first diagnostic: success means your LLM backend is healthy; if
-   it can't, that's surfaced as finding #1 and it falls back to asking you for a
-   provider and key so it can still help.
-3. **Version check** — reports the installed version, version drift across your
-   cluster's nodes, and the latest upstream stable/experimental releases.
-4. **Interactive diagnosis** — it reads logs, `/health`, `docker compose ps`,
-   `systemctl`, config, and ports to pin down problems like a node not joining
-   the console, an unreachable database, a down model backend, port conflicts,
-   or a JWT-secret mismatch — then hands you the precise remediation commands.
-
-### Flags
-
-| Flag | Purpose |
+| File | Purpose |
 |------|---------|
-| `--dir PATH` | Install directory to inspect (default: current directory) |
-| `--report` | Print the deterministic preflight report and exit — no LLM key needed |
-| `--offline` | Skip the upstream GitHub version check |
+| `.env` | All environment variables for `compose.yaml` |
+| `setup.sh` | Post-start script: creates admin user, roles, tool policies, prompt templates via the API |
+| `docker-compose.override.yaml` | Only if customizations beyond env vars are needed |

-`--report` is the fastest way to get a health snapshot (and to share one when
-asking for help) — it never needs an API key:
+## Requirements

-```bash
-turnstone-doctor --report --dir ~/turnstone
-```
+- **Python 3.11+** with turnstone installed (`pip install turnstone`)
+- **An LLM API key** — for the wizard itself (OpenAI, Anthropic, or a local
+  model). This can differ from the LLM your deployment will use.
+- **Docker & Docker Compose** — needed to run the stack. The wizard detects
+  whether Docker is installed and gives platform-specific install instructions
+  if it's missing. You can still generate config files without Docker.
+
+## Deployment Modes
+
+The wizard supports two deployment modes:
+
+- **Single-node production** (`docker compose --profile production up`) —
+  1 server + console + PostgreSQL. Good for most use cases.
+- **Multi-node cluster** (`docker compose --profile cluster up`) —
+  10-node server fleet + console + PostgreSQL. For high-throughput or
+  HA deployments.
+
+## Example Session

 ```
-## Install profile
- Detected kind(s): docker-compose  (primary: docker-compose)
- Docker daemon reachable: yes
- Compose files:
-    /home/you/turnstone/compose.yaml
- Database: backend=postgresql, url=postgresql+psycopg://turnstone:****@postgres:5432/turnstone
- Candidate health URLs: http://localhost:8080/health, http://localhost:8090/health
+$ turnstone-bootstrap

-## Versions
- Installed (this tool): 1.7.0a2
- Cluster nodes: 10 reporting; versions ['1.7.0a2']
- Version drift across nodes: no
- Upstream: stable 1.6.9, experimental 1.7.0a2
+ Turnstone Bootstrap Wizard  v0.5.4
+ ────────────────────────────────────────────────

-## LLM backend (ok)
- resolved Qwen/Qwen3-32B via openai-compatible @ http://host.docker.internal:8000/v1
+ Which provider for this wizard?
+   [1] OpenAI
+   [2] Anthropic
+   [3] OpenAI-compatible (local/vLLM)
+
+ > 3
+
+ Base URL [http://localhost:8000/v1]:
+ API key (press Enter for 'none'):
+
+ Querying http://localhost:8000/v1 for available models...
+ Found model: Qwen/Qwen3-32B
+
+ Connected to Qwen/Qwen3-32B. Handing off to AI assistant...
+
+> (AI walks you through the rest interactively)
 ```

-Secrets (JWT secret, database password, API keys) are always redacted in the
-report and in anything the doctor reads.
-
 ## Tips

- **Type `quit`** to exit the conversation; **Ctrl+C** interrupts (twice to quit).
- **Point it at the right install** with `--dir` when you run it from elsewhere.
- **(Re)installing or adding nodes?** Use the installer (`run.sh`), not the doctor.
+- **Re-run safely** — running the wizard again detects your existing `.env`
+  and offers to update it rather than overwriting.
+- **Duplicate writes are skipped** — if the LLM tries to write the same file
+  twice with identical content, it's silently ignored.
+- **Type `quit` to exit** at any time during the conversation.
+- **Ctrl+C** is handled gracefully — press once to interrupt, twice to exit.

 ## See Also

- [Docker Deployment](docs/docker.md) — compose stacks, ports, and bare-metal nodes
- [Security](docs/security.md) — auth architecture and token types
- [Governance](docs/governance.md) — roles, policies, and templates
+- [Docker Deployment](docker.md) — manual compose setup and profiles
+- [Security](security.md) — auth architecture and token types
+- [Governance](governance.md) — roles, policies, and templates
@@ -3,32 +3,16 @@
 [![CI](https://github.com/turnstonelabs/turnstone/actions/workflows/ci.yml/badge.svg)](https://github.com/turnstonelabs/turnstone/actions/workflows/ci.yml)
 [![PyPI](https://img.shields.io/pypi/v/turnstone)](https://pypi.org/project/turnstone/)
 [![Python](https://img.shields.io/pypi/pyversions/turnstone)](https://pypi.org/project/turnstone/)
-[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
-[![Discord](https://img.shields.io/badge/Discord-join%20us-5865F2?logo=discord&logoColor=white)](https://discord.gg/Nh3bWMacaq)
-[![Sponsor](https://img.shields.io/badge/Sponsor-%E2%9D%A4-db61a2?logo=githubsponsors&logoColor=white)](https://github.com/sponsors/eous)
+[![License](https://img.shields.io/badge/license-BSL--1.1-blue)](LICENSE)

-Self-hosted, local-first orchestration for tool-using AI agents. Give LLMs real tools — shell, files, search, web — and run them across your own cluster with direct HTTP routing and interactive interfaces. Your code, your models, your data stay on hardware you control: no telemetry, no phone-home.
+Multi-node AI orchestration platform. Deploy tool-using AI agents across a cluster of servers with direct HTTP routing, interactive interfaces, and enterprise governance.

 <p align="center">
-  <img src="docs/assets/hero.png" alt="Turnstone coordinator — parallel tool batches with judge-graded approval and child workstream tracking" width="960"/>
+  <img src="docs/assets/hero.png" alt="Turnstone console — multi-workstream AI orchestration with mermaid diagrams" width="960"/>
 </p>

 Named after the [Ruddy Turnstone](https://en.wikipedia.org/wiki/Ruddy_turnstone) (*Arenaria interpres*) — a shorebird that flips stones to discover what's hiding underneath.

-**What is a harness?**
-
-<p align="center">
-  <a href="https://media.githubusercontent.com/media/turnstonelabs/turnstone/main/docs/diagrams/harness.png">
-    <img src="https://media.githubusercontent.com/media/turnstonelabs/turnstone/main/docs/diagrams/harness.png" alt="ℋ : s_{n+1} ~ T(s_n) for n < τ_H — the whole controlled loop: π lowers state to context, M_W proposes a readout, γ authorizes it, Q_E acts on the world, ρ verifies and folds back" width="960"/>
-  </a>
-</p>
-
-```
-ℋ :  s_{n+1} ~ T(s_n)   for n < τ_H
-```
-
-[**the primer →**](PRIMER.md) · [**the formalism →**](HYPOTHESIS.md)
-
 ### Release Tracks

 | Track | Install | Docker | Description |
@@ -42,13 +26,12 @@ See [docs/releasing.md](docs/releasing.md) for the full release process.

 Turnstone gives LLMs tools — shell, files, search, web, planning — and orchestrates multi-turn conversations where the model investigates, acts, and reports.

- **Local-first & private** — runs entirely on hardware you control, with no telemetry and no phone-home. Point it at local models (vLLM, llama.cpp) or commercial APIs you hold the keys to — your prompts and data never transit a third party you didn't choose.
- **Bring your own models** — OpenAI-compatible APIs (vLLM, llama.cpp, NIM), the Anthropic Messages API, and Google Gemini, mixed freely per role
 - **Interactive sessions** — terminal CLI or browser UI with parallel workstreams
- **Cluster dashboard** — real-time view of every node and workstream, with a rendezvous routing proxy
- **Intent validation** — an LLM judge (your model) grades every tool call with a risk assessment and evidence before it runs
+- **Cluster dashboard** — real-time view of all nodes and workstreams with console routing proxy
+- **Intent validation** — LLM judge evaluates every tool call with risk assessments and evidence
+- **Governance** — RBAC, OIDC SSO, tool policies, skills, usage tracking, audit logs
+- **Multi-provider** — OpenAI-compatible APIs (vLLM, llama.cpp, NIM) and Anthropic Messages API
 - **MCP support** — external tool servers with native deferred loading (Anthropic/OpenAI) or BM25 fallback
- **Team controls when you need them** — optional RBAC, SSO, tool policies, and audit logs, all stored in your own database

 <p align="center">
  <img src="docs/diagrams/architecture-overview.svg" alt="Turnstone system architecture" width="960"/>
@@ -66,42 +49,18 @@ turnstone --base-url http://localhost:8000/v1
 turnstone-server --port 8080 --base-url http://localhost:8000/v1

 # Cluster dashboard
+pip install turnstone[console]
 turnstone-console --port 8090
 ```

-For PostgreSQL (recommended for production):
-
-```bash
-export TURNSTONE_DB_BACKEND=postgresql
-export TURNSTONE_DB_URL="postgresql+psycopg://user:pass@localhost:5432/turnstone"
-turnstone-server --port 8080 --base-url http://localhost:8000/v1
-```
-
 ### Docker

-One-line install — autodetects Ubuntu/Debian, Fedora/RHEL, Arch, and WSL,
-installs git + Docker if missing, generates secrets, and starts the stack:
-
 ```bash
-curl -fsSL https://raw.githubusercontent.com/turnstonelabs/turnstone/main/run.sh | bash
+cp .env.example .env  # edit LLM_BASE_URL, OPENAI_API_KEY, etc.
+docker compose --profile production up
 ```

-Or, if you already have Docker, clone the repo and run it yourself:
-
-```bash
-docker compose up
-```
-
-That builds one image and brings up a full local cluster — PostgreSQL, console,
-Caddy, channel gateway, and 10 server nodes — with no `.env` required (it ships
-with insecure dev defaults). Open the dashboard at https://localhost:8443 (Caddy
-serves it over TLS with its own local CA — trust it once). Nodes boot without an
-LLM; add model backends from the console UI.
-
-For production (released images from ghcr.io, real secrets required), use the
-bundled stack: `docker compose -f turnstone/deploy/compose.yaml up`.
-
-See [QUICKSTART.md](QUICKSTART.md) for the install + troubleshooting walkthrough and [docs/docker.md](docs/docker.md) for Docker configuration.
+See [QUICKSTART.md](QUICKSTART.md) for the bootstrap wizard and [docs/docker.md](docs/docker.md) for Docker configuration and profiles.

 ### Programmatic (SDK)

@@ -116,24 +75,23 @@ with TurnstoneServer("http://localhost:8080", token="tok_xxx") as client:

 ## Tools

-Built-in tools for shell, files, search, web, memory, notifications, and autonomous sub-agents — plus external tools via [MCP](https://modelcontextprotocol.io/) with native deferred loading. See [docs/tools.md](docs/tools.md) for the full reference and [docs/mcp-registry.md](docs/mcp-registry.md) for MCP configuration.
+Built-in tools for shell, files, search, web, memory, notifications, and autonomous sub-agents — plus external tools via [MCP](https://modelcontextprotocol.io/) with native deferred loading. See [docs/tools.md](docs/tools.md) for the full reference and [docs/mcp.md](docs/mcp.md) for MCP configuration.

 ## Architecture

 **Single-node**: Client → Server (direct HTTP + SSE). No external dependencies beyond the database.

-**Multi-node**: Client → Console (rendezvous routing proxy) → Server nodes. The console picks the target node for each workstream via rendezvous (HRW) hashing over the live service registry — pure function of `(ws_id, live_nodes)`, no stored bucket state, deterministic across readers. A node join or drop only re-routes the keys that score highest on the affected node.
+**Multi-node**: Client → Console (hash ring routing proxy) → Server nodes. The console maintains a 65536-entry bucket cache for O(1) workstream routing. A rebalancer daemon redistributes buckets when nodes join or leave.

 | Component | Purpose |
 |-----------|---------|
 | `turnstone` | Terminal CLI (REPL) |
 | `turnstone-server` | Web UI + REST API + SSE events |
 | `turnstone-console` | Cluster dashboard + routing proxy + admin panel |
-| `turnstone-channel` | Channel gateway (Discord and Slack adapters) |
+| `turnstone-channel` | Channel gateway (Discord, with adapters for Slack/Teams planned) |
 | `turnstone-admin` | User/token management CLI |
-| `turnstone-eval` | Headless measurement — scores tool-use against expected actions |
-| `turnstone-optimizer` | Prompt/tool optimizer (UCB self-modify loop over the eval substrate) |
-| `turnstone-doctor` | LLM-backed cluster diagnostics |
+| `turnstone-eval` | Eval harness for prompt/tool optimization |
+| `turnstone-bootstrap` | LLM-guided setup wizard |

 ### Diagrams

@@ -150,7 +108,7 @@ UML diagrams in [`docs/diagrams/`](docs/diagrams/):
 | [Console Data Flow](docs/diagrams/png/11-console-data-flow.png) | Dashboard data collection |
 | [Deployment](docs/diagrams/png/12-deployment.png) | Docker Compose topology |
 | [Auth](docs/diagrams/png/15-auth-architecture.png) | JWT, scopes, login flows |
-| [Channels](docs/diagrams/png/16-channel-architecture.png) | Discord / Slack adapters + routing |
+| [Channels](docs/diagrams/png/16-channel-architecture.png) | Discord adapter + routing |
 | [Judge](docs/diagrams/png/22-judge-architecture.png) | Intent validation pipeline |
 | [OIDC](docs/diagrams/png/25-oidc-architecture.png) | SSO authorization code flow |

@@ -169,28 +127,15 @@ UML diagrams in [`docs/diagrams/`](docs/diagrams/):
 | Console dashboard | [docs/console.md](docs/console.md) |
 | Eval harness | [docs/eval.md](docs/eval.md) |
 | Tools reference | [docs/tools.md](docs/tools.md) |
-| MCP integration | [docs/mcp-registry.md](docs/mcp-registry.md) |
+| MCP integration | [docs/mcp.md](docs/mcp.md) |

 ## Requirements

 - Python 3.11+
- An OpenAI-compatible API endpoint, Anthropic API key, or Google Gemini API key
- Optional: Discord / Slack channel integrations (`pip install turnstone[discord,slack]`)
+- An OpenAI-compatible API endpoint or Anthropic API key
+- Optional: PostgreSQL (`pip install turnstone[postgres]`), Anthropic (`pip install turnstone[anthropic]`)
 - [Git LFS](https://git-lfs.com/) for cloning (diagram PNGs)

-## Support
-
-Turnstone is free, Apache-2.0, and self-hosted — no paid tier, no telemetry, no upsell. If it saves you time or you'd like to help keep development moving, you can sponsor the project:
-
-**[❤ Sponsor Turnstone →](https://github.com/sponsors/eous)**  ·  one-off via **[PayPal](https://paypal.me/eousphoros)**
-
-Sponsorship is entirely optional and funds maintenance, new features, and infrastructure. Prefer to contribute in other ways? Filing issues, improving docs, and [pull requests](CONTRIBUTING.md) help just as much.
-
-## Community
-
-Questions, ideas, or want to show what you're building? Join us on Discord:
-**[discord.gg/Nh3bWMacaq](https://discord.gg/Nh3bWMacaq)**.
-
 ## License

-[Apache License 2.0](LICENSE), as of version 1.6.0. Versions 1.5.x and earlier remain under the Business Source License 1.1 they shipped with.
+[Business Source License 1.1](LICENSE) — free for all use except hosting as a managed service. Converts to Apache 2.0 on 2030-03-01.
@@ -2,11 +2,11 @@ Turnstone — Third-Party Notices

 This file contains the licenses and notices for third-party software bundled
 with Turnstone. Each bundled dependency retains its original license; the
-Turnstone Apache-2.0 license does not apply to these components.
+Turnstone BUSL-1.1 license does not apply to these components.

 ================================================================================

-KaTeX 0.17.0
+KaTeX 0.16.38
 https://katex.org/
 https://github.com/KaTeX/KaTeX

@@ -70,7 +70,7 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

 ================================================================================

-Mermaid 11.15.0
+Mermaid 11.13.0
 https://mermaid.js.org/
 https://github.com/mermaid-js/mermaid

@@ -95,22 +95,3 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
-
-================================================================================
-
-hls.js 1.6.16
-https://github.com/video-dev/hls.js
-
-Copyright 2017 Dailymotion
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
-    http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
@@ -1,61 +1,11 @@
 # =============================================================================
-# Turnstone — local cluster stack (docker compose)
+# Turnstone Docker Compose Stack
 #
-# Clone the repo and run:
-#
-#     docker compose up
-#
-# That builds one image and brings up a complete, console-visible cluster:
-# PostgreSQL + console + Caddy + channel gateway + 10 server nodes (node-1…10).
-#
-#   Dashboard: https://localhost:8443   (Caddy's local CA — trust it once)
-#
-# Access is via Caddy only — the console's plain-HTTP port is intentionally not
-# published (HTTP/2 from Caddy avoids the browser's 6-connection cap on the
-# dashboard's SSE streams). Trust Caddy's root once:
-#     docker compose exec caddy cat /data/caddy/pki/authorities/local/root.crt
-#
-# It works out of the box with INSECURE dev defaults (see the secret/password
-# values below) so there's nothing to configure first. A .env file still
-# overrides any value. For a real deployment use the bundled production stack
-# at turnstone/deploy/compose.yaml — it pulls released images from ghcr.io and
-# requires you to set real secrets.
-#
-# Bring your own LLM: nodes boot without one and show up in the console
-# immediately. Add model backends (OpenAI / Anthropic / local vLLM) from the
-# console UI's Models tab, or point LLM_BASE_URL / OPENAI_API_KEY (below) at an
-# OpenAI-compatible endpoint.
-#
-# Fewer nodes (lighter machines):
-#     docker compose up postgres console caddy channel node-1 node-2 node-3
-#
-# Join a bare-metal host: a turnstone-server running OUTSIDE compose (e.g. to use
-# a local GPU) can join this cluster. Postgres, the console's ACME endpoint, and
-# SearxNG are published on 127.0.0.1 so a node on THIS machine reaches them via
-# localhost. Keep secrets in ~/.config/turnstone/config.toml (chmod 0600 — the
-# loader warns otherwise):
-#     [auth]
-#     jwt_secret = "dev-only-insecure-jwt-secret-change-me-for-real-deployments"
-#     [database]
-#     backend = "postgresql"
-#     url = "postgresql+psycopg://turnstone:turnstone@localhost:5432/turnstone"
-#     [api]
-#     base_url = "http://localhost:8000/v1"
-#     api_key = "dummy"
-#     [tls]              # only if the cluster runs mTLS
-#     enabled = true
-# then run (node identity isn't a secret, so it stays on the command line):
-#     TURNSTONE_NODE_ID=host-1 \
-#       TURNSTONE_ADVERTISE_URL=http://host.docker.internal:8080 \
-#       TURNSTONE_CONSOLE_URL=http://localhost:8090 \
-#       TURNSTONE_SEARXNG_URL=http://localhost:8081 \
-#       turnstone-server --host 0.0.0.0 --port 8080
-# The node registers in Postgres, auto-enrolls its mTLS cert from the console's
-# ACME endpoint (when the cluster runs mTLS), and the console collector reaches
-# it back via host.docker.internal. To join from ANOTHER machine, set
-# TURNSTONE_HOST_IP to this host's LAN IP and set TURNSTONE_ACME_EXTERNAL_URL to
-# http://<this-host-ip>:8090/acme. Use the same host IP in the node's URLs above
-# (and the NODE host's IP in TURNSTONE_ADVERTISE_URL) — see docs/docker.md.
+# Usage:
+#   Infra only:           docker compose up
+#   Single node:          docker compose --profile production up
+#   Production (PG):      DB_BACKEND=postgresql docker compose --profile production up
+#   10-node cluster:      docker compose --profile cluster up
 # =============================================================================

 name: turnstone
@@ -68,30 +18,16 @@ volumes:
  turnstone-data:
  workspace:
  postgres-data:
-  caddy-data:
-  caddy-config:
-  searxng-cache:
-
-# -- Shared values (scalar anchors) -------------------------------------------
-# Defined once here, referenced (*alias) by every service so the dev defaults
-# can't drift. All `${VAR:-default}` values are still overridable via .env.
-x-shared:
-  # INSECURE dev default. Every service MUST share ONE secret — the console
-  # mints its own service token (signed with this) to reach the nodes. Override
-  # TURNSTONE_JWT_SECRET in .env for anything that isn't a local sandbox.
-  jwt-secret: &jwt-secret "${TURNSTONE_JWT_SECRET:-dev-only-insecure-jwt-secret-change-me-for-real-deployments}"
-  db-backend: &db-backend "${TURNSTONE_DB_BACKEND:-postgresql}"
-  # All services point at the same Postgres. Node discovery REQUIRES a shared
-  # DB: each server registers + heartbeats into a `services` table that the
-  # console polls. (SQLite-per-container can't see other containers.)
-  db-url: &db-url "${TURNSTONE_DB_URL:-postgresql+psycopg://${POSTGRES_USER:-turnstone}:${POSTGRES_PASSWORD:-turnstone}@postgres:5432/turnstone}"

 services:
  # -------------------------------------------------------------------
-  # PostgreSQL — the shared database that ties the cluster together.
+  # PostgreSQL — production database (profile: production)
  # -------------------------------------------------------------------
  postgres:
    image: pgautoupgrade/pgautoupgrade:18-alpine
+    profiles:
+      - production
+      - cluster
    command:
      - postgres
      - -c
@@ -101,17 +37,8 @@ services:
    environment:
      POSTGRES_DB: turnstone
      POSTGRES_USER: ${POSTGRES_USER:-turnstone}
-      # INSECURE dev default — override POSTGRES_PASSWORD in .env for real use.
-      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-turnstone}
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?POSTGRES_PASSWORD is required for production profile}
      PGDATA: /var/lib/postgresql/data
-    # Published so a bare-metal turnstone-server can join the cluster (see "Join
-    # a bare-metal host" in the header). Bound to 127.0.0.1 by default (same-host
-    # nodes only); set TURNSTONE_HOST_IP to this host's LAN IP to let another
-    # machine connect — but set a real POSTGRES_PASSWORD first, or you'll expose a
-    # database with the insecure default password to your network. (The legacy
-    # POSTGRES_BIND is still honored as a fallback when TURNSTONE_HOST_IP is unset.)
-    ports:
-      - "${TURNSTONE_HOST_IP:-${POSTGRES_BIND:-127.0.0.1}}:${POSTGRES_PORT:-5432}:5432"
    volumes:
      - postgres-data:/var/lib/postgresql/data
    networks:
@@ -125,23 +52,65 @@ services:
    deploy:
      resources:
        limits:
-          memory: 2G
+          memory: 1G
+          cpus: '1.0'
    restart: unless-stopped

  # -------------------------------------------------------------------
-  # turnstone-console — cluster dashboard. Reach it ONLY through Caddy at
-  # https://localhost:8443 (see the caddy service below).
-  #
-  # Browsers must reach the dashboard through Caddy (https://localhost:8443): a
-  # plain HTTP/1.1 origin caps the browser at 6 connections, which starves the
-  # dashboard's per-pane SSE streams, whereas Caddy serves HTTP/2 (multiplexed)
-  # and proxies to console:8090 internally. The console's :8090 is published
-  # below ONLY so bare-metal nodes can reach the plain-HTTP ACME enrollment
-  # endpoint — don't point a browser at it.
-  #
-  # The single `build:` here produces the turnstone:local image every other
-  # service reuses. extra_hosts lets the console reach a bare-metal server
-  # advertising http://host.docker.internal:8080 (see "Join a host" below).
+  # turnstone-server — Web UI + chat workstreams + LLM interaction
+  # -------------------------------------------------------------------
+  server:
+    image: turnstone:local
+    profiles:
+      - production
+    command:
+      - sh
+      - -c
+      - >-
+        turnstone-server
+        --host 0.0.0.0
+        --port 8080
+        --base-url "$${LLM_BASE_URL}"
+        --api-key "$${OPENAI_API_KEY}"
+        $${MODEL:+--model $$MODEL}
+        $${SKIP_PERMISSIONS:+--skip-permissions}
+        $${MCP_CONFIG:+--mcp-config $$MCP_CONFIG}
+    ports:
+      - "${SERVER_PORT:-8080}:8080"
+    volumes:
+      - turnstone-data:/data
+      - ${WORKSPACE_MOUNT:-workspace}:/workspace
+    environment:
+      - LLM_BASE_URL=${LLM_BASE_URL:-http://host.docker.internal:8000/v1}
+      - OPENAI_API_KEY=${OPENAI_API_KEY:-dummy}
+      - TAVILY_API_KEY=${TAVILY_API_KEY:-}
+      - SKIP_PERMISSIONS=${SKIP_PERMISSIONS:-}
+      # Generate with: python -c "import secrets; print(secrets.token_hex(32))"
+      - TURNSTONE_JWT_SECRET=${TURNSTONE_JWT_SECRET:?Set TURNSTONE_JWT_SECRET in .env}
+      - MODEL=${MODEL:-}
+      - MCP_CONFIG=${MCP_CONFIG:-}
+      - TURNSTONE_DB_BACKEND=${DB_BACKEND:-sqlite}
+      - TURNSTONE_DB_URL=${DATABASE_URL:-}
+      - TURNSTONE_NODE_ID=${TURNSTONE_NODE_ID:-}
+      - TURNSTONE_ADVERTISE_URL=${TURNSTONE_ADVERTISE_URL:-http://server:8080}
+    extra_hosts:
+      - "host.docker.internal:host-gateway"
+    networks:
+      - turnstone-net
+    depends_on:
+      postgres:
+        condition: service_healthy
+        required: false
+    healthcheck:
+      test: ["CMD", "python", "/usr/local/bin/healthcheck.py", "http://127.0.0.1:8080/health"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+      start_period: 60s
+    restart: unless-stopped
+
+  # -------------------------------------------------------------------
+  # turnstone-console — Cluster dashboard
  # -------------------------------------------------------------------
  console:
    image: turnstone:local
@@ -152,31 +121,16 @@ services:
      - turnstone-console
      - --host=0.0.0.0
      - --port=8090
-    # Publishes the console's plain-HTTP listener so a bare-metal node can reach
-    # the ACME endpoint, fetch the CA, and enroll its cert (the console serves
-    # HTTP here even under mTLS). Bound to 127.0.0.1 by default; setting
-    # TURNSTONE_HOST_IP exposes the WHOLE console HTTP API on that interface.
-    # ACME signing routes require a dedicated short-lived service JWT, but the
-    # listener and bearer token are still plain HTTP: bind only a trusted LAN
-    # or VPN interface and restrict it to enrolling nodes. Browsers use Caddy
-    # :8443, never this port.
    ports:
-      - "${TURNSTONE_HOST_IP:-127.0.0.1}:8090:8090"
+      - "${CONSOLE_PORT:-8090}:8090"
    environment:
-      TURNSTONE_JWT_SECRET: *jwt-secret
-      TURNSTONE_DB_BACKEND: *db-backend
-      TURNSTONE_DB_URL: *db-url
-      TURNSTONE_CONSOLE_URL: http://console:8090
-      # Separate from TURNSTONE_CONSOLE_URL: this is the canonical responder
-      # base embedded in ACME directory/order URLs for cross-host enrollment.
-      TURNSTONE_ACME_EXTERNAL_URL: "${TURNSTONE_ACME_EXTERNAL_URL:-}"
-    extra_hosts:
-      - "host.docker.internal:host-gateway"
+      # Generate with: python -c "import secrets; print(secrets.token_hex(32))"
+      - TURNSTONE_JWT_SECRET=${TURNSTONE_JWT_SECRET:?Set TURNSTONE_JWT_SECRET in .env}
+      - TURNSTONE_DB_BACKEND=${DB_BACKEND:-sqlite}
+      - TURNSTONE_DB_URL=${DATABASE_URL:-}
+      - TURNSTONE_CONSOLE_URL=http://console:8090
    networks:
      - turnstone-net
-    depends_on:
-      postgres:
-        condition: service_healthy
    healthcheck:
      test: ["CMD", "python", "/usr/local/bin/healthcheck.py", "http://127.0.0.1:8090/health"]
      interval: 10s
@@ -186,33 +140,14 @@ services:
    restart: unless-stopped

  # -------------------------------------------------------------------
-  # caddy — browser TLS for the console dashboard.
-  # Terminates HTTPS (Caddy's own local CA, see turnstone/deploy/Caddyfile) → console:8090.
-  # Dashboard over TLS: https://localhost:${CONSOLE_HTTPS_PORT:-8443}
-  # -------------------------------------------------------------------
-  caddy:
-    image: caddy:2.11
-    depends_on:
-      - console
-    ports:
-      - "${CONSOLE_HTTPS_PORT:-8443}:443"
-      # SearxNG web UI — localhost-only (it has no auth). Browse https://localhost:8444.
-      - "127.0.0.1:${SEARXNG_HTTPS_PORT:-8444}:8444"
-    volumes:
-      - ./turnstone/deploy/Caddyfile:/etc/caddy/Caddyfile:ro
-      - caddy-data:/data # persist Caddy's local CA across restarts
-      - caddy-config:/config
-    networks:
-      - turnstone-net
-    restart: unless-stopped
-
-  # -------------------------------------------------------------------
-  # turnstone-channel — channel gateway (Discord and/or Slack).
-  # Runs HTTP-only with no adapters until you set a token, so it's safe
-  # to leave running. See docs/channels.md.
+  # turnstone-channel — Channel gateway (Discord, Slack, etc.)
+  # Requires TURNSTONE_DISCORD_TOKEN to enable Discord adapter
  # -------------------------------------------------------------------
  channel:
    image: turnstone:local
+    profiles:
+      - production
+      - cluster
    command:
      - sh
      - -c
@@ -221,66 +156,36 @@ services:
        --http-host=0.0.0.0
        $${TURNSTONE_DISCORD_GUILD:+--discord-guild $$TURNSTONE_DISCORD_GUILD}
    environment:
-      TURNSTONE_JWT_SECRET: *jwt-secret
-      TURNSTONE_DB_BACKEND: *db-backend
-      TURNSTONE_DB_URL: *db-url
-      TURNSTONE_DISCORD_TOKEN: ${TURNSTONE_DISCORD_TOKEN:-}
-      TURNSTONE_DISCORD_GUILD: ${TURNSTONE_DISCORD_GUILD:-0}
-      TURNSTONE_SLACK_TOKEN: ${TURNSTONE_SLACK_TOKEN:-}
-      TURNSTONE_SLACK_APP_TOKEN: ${TURNSTONE_SLACK_APP_TOKEN:-}
-      TURNSTONE_CHANNEL_ADVERTISE_URL: http://channel:8091
+      - TURNSTONE_DISCORD_TOKEN=${TURNSTONE_DISCORD_TOKEN:-}
+      - TURNSTONE_DISCORD_GUILD=${TURNSTONE_DISCORD_GUILD:-0}
+      # Generate with: python -c "import secrets; print(secrets.token_hex(32))"
+      - TURNSTONE_JWT_SECRET=${TURNSTONE_JWT_SECRET:?Set TURNSTONE_JWT_SECRET in .env}
+      - TURNSTONE_DB_BACKEND=${DB_BACKEND:-postgresql}
+      - TURNSTONE_DB_URL=${DATABASE_URL:-postgresql://${POSTGRES_USER:-turnstone}:${POSTGRES_PASSWORD:-turnstone}@postgres:5432/turnstone}
+      - TURNSTONE_CHANNEL_ADVERTISE_URL=http://channel:8091
    networks:
      - turnstone-net
    depends_on:
      postgres:
        condition: service_healthy
-    restart: unless-stopped
-
-  # -------------------------------------------------------------------
-  # searxng — self-hosted metasearch backing the web_search tool.
-  # Internal-network only (no published port): nodes reach it at
-  # http://searxng:8080. Config (JSON output on, limiter off) lives in
-  # turnstone/deploy/searxng/settings.yml, mounted read-only. Commercial
-  # models use native provider search and never hit this; it serves
-  # local/vLLM models. Override the tag with SEARXNG_IMAGE_TAG in .env.
-  # -------------------------------------------------------------------
-  searxng:
-    image: searxng/searxng:${SEARXNG_IMAGE_TAG:-latest}
-    # Published so a bare-metal node's web_search can reach it. SearxNG has NO
-    # auth, so it is bound to 127.0.0.1 by default; setting TURNSTONE_HOST_IP
-    # exposes it on that interface — an open search proxy on your LAN, which also
-    # triggers the SearxNG AGPL-3.0 §13 source-offer obligation (see docs/docker.md).
-    # In-compose nodes always use the internal http://searxng:8080 and ignore this.
-    ports:
-      - "${TURNSTONE_HOST_IP:-127.0.0.1}:${SEARXNG_API_PORT:-8081}:8080"
-    volumes:
-      - ./turnstone/deploy/searxng:/etc/searxng:ro
-      - searxng-cache:/var/cache/searxng # favicon + internal SQLite cache (survives restarts)
-    networks:
-      - turnstone-net
-    healthcheck:
-      test: ["CMD", "wget", "-q", "--spider", "http://localhost:8080/healthz"]
-      interval: 10s
-      timeout: 5s
-      retries: 5
-      start_period: 20s
+        required: false
    restart: unless-stopped

  # ===================================================================
-  # Server fleet — node-1 … node-10
+  # 10-node cluster (profile: cluster)
  #
-  # Each node registers itself in Postgres on boot (unique
-  # TURNSTONE_NODE_ID + TURNSTONE_ADVERTISE_URL) and the console
-  # discovers it automatically — no static node list anywhere.
+  # All nodes share the same PostgreSQL instance.
+  # Access via console at :8090.
  #
-  # node-1 carries the shared definition (&node / &node-env); node-2…10
-  # inherit it and override only their identity.
+  # Start:  docker compose --profile cluster up
  # ===================================================================
-  node-1: &node
+
+  # -- cluster servers ------------------------------------------------
+
+  server-1: &cluster-server
    image: turnstone:local
-    build:
-      context: .
-      dockerfile: Dockerfile
+    build: { context: ., dockerfile: Dockerfile }
+    profiles: [cluster]
    command:
      - sh
      - -c
@@ -296,33 +201,23 @@ services:
    volumes:
      - turnstone-data:/data
      - ${WORKSPACE_MOUNT:-workspace}:/workspace
-    environment: &node-env
-      TURNSTONE_JWT_SECRET: *jwt-secret
-      TURNSTONE_DB_BACKEND: *db-backend
-      TURNSTONE_DB_URL: *db-url
-      # Bootstrap LLM defaults — real backends are configured in the console UI.
+    environment: &cluster-server-env
      LLM_BASE_URL: ${LLM_BASE_URL:-http://host.docker.internal:8000/v1}
      OPENAI_API_KEY: ${OPENAI_API_KEY:-dummy}
-      # web_search backend. Defaults to the bundled searxng service; point at an
-      # external SearxNG by setting TURNSTONE_SEARXNG_URL in .env (empty disables).
-      TURNSTONE_SEARXNG_URL: ${TURNSTONE_SEARXNG_URL:-http://searxng:8080}
+      TAVILY_API_KEY: ${TAVILY_API_KEY:-}
+      SKIP_PERMISSIONS: ${SKIP_PERMISSIONS:-}
+      # Generate with: python -c "import secrets; print(secrets.token_hex(32))"
+      TURNSTONE_JWT_SECRET: ${TURNSTONE_JWT_SECRET:?Set TURNSTONE_JWT_SECRET in .env}
      MODEL: ${MODEL:-}
      MCP_CONFIG: ${MCP_CONFIG:-}
-      SKIP_PERMISSIONS: ${SKIP_PERMISSIONS:-}
+      TURNSTONE_DB_BACKEND: ${DB_BACKEND:-postgresql}
+      TURNSTONE_DB_URL: ${DATABASE_URL:-postgresql://${POSTGRES_USER:-turnstone}:${POSTGRES_PASSWORD:?}@postgres:5432/turnstone}
      TURNSTONE_NODE_ID: node-1
-      TURNSTONE_ADVERTISE_URL: http://node-1:8080
-      # Lets the authenticated ACME client follow the console's canonical LAN
-      # URLs without trusting destinations learned from the public directory.
-      TURNSTONE_ACME_EXTERNAL_URL: "${TURNSTONE_ACME_EXTERNAL_URL:-}"
-    extra_hosts:
-      - "host.docker.internal:host-gateway"
-    networks:
-      - turnstone-net
+      TURNSTONE_ADVERTISE_URL: http://server-1:8080
+    extra_hosts: ["host.docker.internal:host-gateway"]
+    networks: [turnstone-net]
    depends_on:
-      postgres:
-        condition: service_healthy
-      searxng:
-        condition: service_healthy
+      postgres: { condition: service_healthy }
    healthcheck:
      test: ["CMD", "python", "/usr/local/bin/healthcheck.py", "http://127.0.0.1:8080/health"]
      interval: 10s
@@ -331,34 +226,34 @@ services:
      start_period: 60s
    deploy:
      resources:
-        limits:
-          memory: 4G
+        limits: { memory: 384M, cpus: '0.5' }
    restart: unless-stopped

-  node-2:
-    <<: *node
-    environment: { <<: *node-env, TURNSTONE_NODE_ID: node-2, TURNSTONE_ADVERTISE_URL: "http://node-2:8080" }
-  node-3:
-    <<: *node
-    environment: { <<: *node-env, TURNSTONE_NODE_ID: node-3, TURNSTONE_ADVERTISE_URL: "http://node-3:8080" }
-  node-4:
-    <<: *node
-    environment: { <<: *node-env, TURNSTONE_NODE_ID: node-4, TURNSTONE_ADVERTISE_URL: "http://node-4:8080" }
-  node-5:
-    <<: *node
-    environment: { <<: *node-env, TURNSTONE_NODE_ID: node-5, TURNSTONE_ADVERTISE_URL: "http://node-5:8080" }
-  node-6:
-    <<: *node
-    environment: { <<: *node-env, TURNSTONE_NODE_ID: node-6, TURNSTONE_ADVERTISE_URL: "http://node-6:8080" }
-  node-7:
-    <<: *node
-    environment: { <<: *node-env, TURNSTONE_NODE_ID: node-7, TURNSTONE_ADVERTISE_URL: "http://node-7:8080" }
-  node-8:
-    <<: *node
-    environment: { <<: *node-env, TURNSTONE_NODE_ID: node-8, TURNSTONE_ADVERTISE_URL: "http://node-8:8080" }
-  node-9:
-    <<: *node
-    environment: { <<: *node-env, TURNSTONE_NODE_ID: node-9, TURNSTONE_ADVERTISE_URL: "http://node-9:8080" }
-  node-10:
-    <<: *node
-    environment: { <<: *node-env, TURNSTONE_NODE_ID: node-10, TURNSTONE_ADVERTISE_URL: "http://node-10:8080" }
+  server-2:
+    <<: *cluster-server
+    environment: { <<: *cluster-server-env, TURNSTONE_NODE_ID: node-2, TURNSTONE_ADVERTISE_URL: "http://server-2:8080" }
+  server-3:
+    <<: *cluster-server
+    environment: { <<: *cluster-server-env, TURNSTONE_NODE_ID: node-3, TURNSTONE_ADVERTISE_URL: "http://server-3:8080" }
+  server-4:
+    <<: *cluster-server
+    environment: { <<: *cluster-server-env, TURNSTONE_NODE_ID: node-4, TURNSTONE_ADVERTISE_URL: "http://server-4:8080" }
+  server-5:
+    <<: *cluster-server
+    environment: { <<: *cluster-server-env, TURNSTONE_NODE_ID: node-5, TURNSTONE_ADVERTISE_URL: "http://server-5:8080" }
+  server-6:
+    <<: *cluster-server
+    environment: { <<: *cluster-server-env, TURNSTONE_NODE_ID: node-6, TURNSTONE_ADVERTISE_URL: "http://server-6:8080" }
+  server-7:
+    <<: *cluster-server
+    environment: { <<: *cluster-server-env, TURNSTONE_NODE_ID: node-7, TURNSTONE_ADVERTISE_URL: "http://server-7:8080" }
+  server-8:
+    <<: *cluster-server
+    environment: { <<: *cluster-server-env, TURNSTONE_NODE_ID: node-8, TURNSTONE_ADVERTISE_URL: "http://server-8:8080" }
+  server-9:
+    <<: *cluster-server
+    environment: { <<: *cluster-server-env, TURNSTONE_NODE_ID: node-9, TURNSTONE_ADVERTISE_URL: "http://server-9:8080" }
+  server-10:
+    <<: *cluster-server
+    environment: { <<: *cluster-server-env, TURNSTONE_NODE_ID: node-10, TURNSTONE_ADVERTISE_URL: "http://server-10:8080" }
+
@@ -1,8 +1,7 @@
-# TLS overlay — enables mTLS across the turnstone deployment.
+# TLS overlay — enables mTLS across the turnstone cluster.
 #
-# Layers on the production stack (it patches the `server`, `console`, and
-# `channel` services that file defines):
-#   docker compose -f turnstone/deploy/compose.yaml -f deploy/docker-compose.tls.yml up
+# Usage (requires base compose.yaml with production profile):
+#   docker compose -f compose.yaml -f deploy/docker-compose.tls.yml --profile production up
 #
 # The tls-init service bootstraps a CA and issues certs.
 # All turnstone services auto-provision their own certs via the
@@ -13,7 +12,7 @@ services:
  # Runs as root to create directories in the volume, then chowns
  # to turnstone:turnstone with restrictive perms (keys 0600).
  tls-init:
-    image: ghcr.io/turnstonelabs/turnstone:${TURNSTONE_IMAGE_TAG:-latest}
+    build: .
    user: root
    command:
      - sh
@@ -38,18 +37,10 @@ services:
        condition: service_completed_successfully
    volumes:
      - tls-certs:/certs:ro
-    # The production base keeps :8090 private. The TLS overlay publishes it on
-    # localhost for same-host enrollment; use a trusted LAN/VPN address for a
-    # remote node and firewall it to that node.
-    ports:
-      - "${TURNSTONE_CONSOLE_HTTP_BIND:-127.0.0.1}:8090:8090"
    environment:
      TURNSTONE_TLS_ENABLED: "true"
      TURNSTONE_TLS_SANS: "console"
      TURNSTONE_CONSOLE_URL: "http://console:8090"
-      # Canonical ACME responder base advertised to enrolling nodes. Set this
-      # when they reach the console through a different host/address.
-      TURNSTONE_ACME_EXTERNAL_URL: "${TURNSTONE_ACME_EXTERNAL_URL:-}"
    command:
      - turnstone-console
      - --host=0.0.0.0
@@ -66,7 +57,11 @@ services:
    environment:
      TURNSTONE_TLS_ENABLED: "true"
      TURNSTONE_TLS_SANS: "server"
-      TURNSTONE_ACME_EXTERNAL_URL: "${TURNSTONE_ACME_EXTERNAL_URL:-}"
+    # Disable healthcheck — server serves HTTPS with mTLS which the
+    # stdlib healthcheck script can't satisfy. The base compose
+    # healthcheck uses plain HTTP which won't work on an HTTPS listener.
+    healthcheck:
+      disable: true

  # Channel: TLS
  channel:
@@ -2,11 +2,11 @@ apiVersion: v2
 name: turnstone
 description: Multi-node AI orchestration platform with tool use, agent routing, and cluster simulation
 type: application
-version: 0.2.0
+version: 0.1.0
 appVersion: "0.3.0"

 dependencies:
  - name: postgresql
-    version: ~18.8.0
+    version: ~18.5.0
    repository: https://charts.bitnami.com/bitnami
    condition: postgresql.enabled
@@ -110,153 +110,6 @@ Determine the PostgreSQL username.
 {{- end }}
 {{- end }}

-{{/*
-The PostgreSQL password when the chart stores it itself, empty when it
-does not. Doubles as the predicate for "does <fullname>-secrets need to
-carry POSTGRES_PASSWORD", so an inline password is never written
-anywhere but <fullname>-secrets, and an operator-supplied Secret is
-never duplicated into it.
-
-An operator-supplied existingSecret wins outright: writing the value
-into a second Secret nothing reads would only duplicate a credential.
-
-Both branches need "default" because this is reached through include,
-which captures rendered text rather than a value: a key that is unset
-rather than empty — "password:" with nothing after it — renders as the
-literal "<no value>", and a ten-character string is truthy. Without the
-default that lands base64-encoded in POSTGRES_PASSWORD and the workloads
-authenticate with it.
-*/}}
-{{- define "turnstone.db.inlinePassword" -}}
-{{- if .Values.postgresql.enabled }}
-{{- .Values.postgresql.auth.password | default "" }}
-{{- else if not .Values.database.external.existingSecret }}
-{{- .Values.database.external.password | default "" }}
-{{- end }}
-{{- end }}
-
-{{/*
-The name of the bundled subchart's own Secret.
-
-Mirrors the subchart's naming rather than calling its helpers, which
-expect a context scoped to the subchart that this chart cannot hand
-them. Release-derived, so deliberately not turnstone.fullname: a
-fullnameOverride here renames this chart's resources and leaves the
-subchart's alone, and pointing at "<fullname>-postgresql" would then
-name a Secret that does not exist.
-
-The subchart also normalises the release name through a regex before
-using it, which is a no-op for the DNS-1123 names Helm accepts, so it is
-not reproduced.
-*/}}
-{{- define "turnstone.postgresql.fullname" -}}
-{{- $global := ((.Values.global).postgresql).fullnameOverride }}
-{{- if $global }}
-{{- $global | trunc 63 | trimSuffix "-" }}
-{{- else if .Values.postgresql.fullnameOverride }}
-{{- .Values.postgresql.fullnameOverride | trunc 63 | trimSuffix "-" }}
-{{- else }}
-{{- $name := .Values.postgresql.nameOverride | default "postgresql" }}
-{{- if contains $name .Release.Name }}
-{{- .Release.Name | trunc 63 | trimSuffix "-" }}
-{{- else }}
-{{- printf "%s-%s" .Release.Name $name | trunc 63 | trimSuffix "-" }}
-{{- end }}
-{{- end }}
-{{- end }}
-
-{{- define "turnstone.postgresql.secretName" -}}
-{{- $existing := coalesce (((.Values.global).postgresql).auth).existingSecret .Values.postgresql.auth.existingSecret }}
-{{- if $existing }}
-{{- tpl $existing . }}
-{{- else }}
-{{- include "turnstone.postgresql.fullname" . }}
-{{- end }}
-{{- end }}
-
-{{/*
-The subchart stores the named user's password under "password" and the
-superuser's under "postgres-password", and lets an operator rename
-either through auth.secretKeys.
-*/}}
-{{- define "turnstone.postgresql.passwordKey" -}}
-{{- $user := .Values.postgresql.auth.username | default "" }}
-{{- $keys := .Values.postgresql.auth.secretKeys | default dict }}
-{{- if or (empty $user) (eq $user "postgres") }}
-{{- $keys.adminPasswordKey | default "postgres-password" }}
-{{- else }}
-{{- $keys.userPasswordKey | default "password" }}
-{{- end }}
-{{- end }}
-
-{{/*
-Determine the secret holding the PostgreSQL password, and the key within
-it. Three sources, and the two helpers agree by construction because
-they branch identically:
-
-  - an external database pointed at a Secret the chart does not own (a
-    CloudNativePG-generated secret, an External Secrets target, ...), in
-    which case the key is rarely "POSTGRES_PASSWORD" — hence the
-    companion existingSecretPasswordKey
-  - the bundled subchart's own Secret, when it generates the password
-  - <fullname>-secrets, when the password is supplied inline in values
-
-Note the last is deliberately not turnstone.llm.secretName: that
-resolves to llm.existingSecret when the operator supplies one, which
-holds LLM API keys and has no reason to carry a database password.
-*/}}
-{{- define "turnstone.db.secretName" -}}
-{{- if not .Values.postgresql.enabled }}
-{{- if .Values.database.external.existingSecret }}
-{{- .Values.database.external.existingSecret }}
-{{- else }}
-{{- printf "%s-secrets" (include "turnstone.fullname" .) }}
-{{- end }}
-{{- else if include "turnstone.db.inlinePassword" . }}
-{{- printf "%s-secrets" (include "turnstone.fullname" .) }}
-{{- else }}
-{{- include "turnstone.postgresql.secretName" . }}
-{{- end }}
-{{- end }}
-
-{{- define "turnstone.db.passwordKey" -}}
-{{- if not .Values.postgresql.enabled }}
-{{- if .Values.database.external.existingSecret }}
-{{- .Values.database.external.existingSecretPasswordKey | default "password" }}
-{{- else }}
-{{- printf "POSTGRES_PASSWORD" }}
-{{- end }}
-{{- else if include "turnstone.db.inlinePassword" . }}
-{{- printf "POSTGRES_PASSWORD" }}
-{{- else }}
-{{- include "turnstone.postgresql.passwordKey" . }}
-{{- end }}
-{{- end }}
-
-{{/*
-Database environment shared by the server, console and migrate Job.
-
-Every value except the password is rendered inline rather than pulled
-from the ConfigMap via envFrom, so that one definition serves all three
-workloads and the URL is assembled in exactly one place.
-
-POSTGRES_PASSWORD must still precede TURNSTONE_DB_URL: the kubelet
-expands $(VAR) only against env entries declared earlier in the list, so
-a later definition would leave a literal "$(POSTGRES_PASSWORD)" in the
-URL.
-*/}}
-{{- define "turnstone.db.env" -}}
- name: TURNSTONE_DB_BACKEND
-  value: {{ .Values.database.backend | quote }}
- name: POSTGRES_PASSWORD
-  valueFrom:
-    secretKeyRef:
-      name: {{ include "turnstone.db.secretName" . }}
-      key: {{ include "turnstone.db.passwordKey" . }}
- name: TURNSTONE_DB_URL
-  value: "postgresql+psycopg://{{ include "turnstone.postgresql.username" . }}:$(POSTGRES_PASSWORD)@{{ include "turnstone.postgresql.host" . }}:{{ include "turnstone.postgresql.port" . }}/{{ include "turnstone.postgresql.database" . }}{{ if and (not .Values.postgresql.enabled) .Values.database.external.sslmode }}?sslmode={{ .Values.database.external.sslmode }}{{ end }}"
-{{- end }}
-
 {{/*
 Determine the secret name for LLM API keys.
 */}}
@@ -7,17 +7,6 @@ metadata:
    app.kubernetes.io/component: console
 spec:
  replicas: {{ .Values.console.replicas }}
-  {{- if eq (int .Values.console.replicas) 1 }}
-  # The console registers itself under the fixed service_id "console" and
-  # deregisters on shutdown. Under RollingUpdate the outgoing pod's
-  # deregister runs *after* the incoming pod registers and deletes its
-  # row -- and the heartbeat only touches last_heartbeat, so the row is
-  # never recreated and the console stays invisible in the registry until
-  # the next clean start. Recreate orders shutdown strictly before
-  # startup. Only valid at one replica; see console.replicas.
-  strategy:
-    type: Recreate
-  {{- end }}
  selector:
    matchLabels:
      {{- include "turnstone.selectorLabels" . | nindent 6 }}
@@ -29,18 +18,6 @@ spec:
        app.kubernetes.io/component: console
    spec:
      serviceAccountName: {{ include "turnstone.serviceAccountName" . }}
-      {{- with .Values.console.nodeSelector }}
-      nodeSelector:
-        {{- toYaml . | nindent 8 }}
-      {{- end }}
-      {{- with .Values.console.affinity }}
-      affinity:
-        {{- toYaml . | nindent 8 }}
-      {{- end }}
-      {{- with .Values.console.tolerations }}
-      tolerations:
-        {{- toYaml . | nindent 8 }}
-      {{- end }}
      containers:
        - name: console
          image: {{ include "turnstone.image" . }}
@@ -59,18 +36,8 @@ spec:
            - secretRef:
                name: {{ include "turnstone.llm.secretName" . }}
                optional: true
-          env:
-            {{- include "turnstone.db.env" . | nindent 12 }}
-            # Self-registration URL for the service registry. Unlike a
-            # server node the console is one logical endpoint behind its
-            # Service, so the Service DNS name is correct here. Without
-            # it the console registers gethostname() (its pod name),
-            # which no server node can resolve. Stops at ".svc" rather
-            # than assuming a "cluster.local" DNS domain, which is
-            # configurable per cluster.
-            - name: TURNSTONE_CONSOLE_URL
-              value: "http://{{ include "turnstone.fullname" . }}-console.{{ .Release.Namespace }}.svc:{{ .Values.console.service.port }}"
          {{- if or .Values.auth.existingSecret .Values.auth.jwtSecret }}
+          env:
            - name: TURNSTONE_JWT_SECRET
              valueFrom:
                secretKeyRef:
@@ -18,18 +18,6 @@ spec:
        app.kubernetes.io/component: server
    spec:
      serviceAccountName: {{ include "turnstone.serviceAccountName" . }}
-      {{- with .Values.server.nodeSelector }}
-      nodeSelector:
-        {{- toYaml . | nindent 8 }}
-      {{- end }}
-      {{- with .Values.server.affinity }}
-      affinity:
-        {{- toYaml . | nindent 8 }}
-      {{- end }}
-      {{- with .Values.server.tolerations }}
-      tolerations:
-        {{- toYaml . | nindent 8 }}
-      {{- end }}
      containers:
        - name: server
          image: {{ include "turnstone.image" . }}
@@ -51,20 +39,8 @@ spec:
                name: {{ include "turnstone.llm.secretName" . }}
                optional: true
          env:
-            {{- include "turnstone.db.env" . | nindent 12 }}
-            # Each replica is a distinct node in the rendezvous ring, so it
-            # must advertise an address that reaches *itself*. The Service
-            # DNS name would load-balance across every replica, sending
-            # console traffic routed for node A to an arbitrary pod; the
-            # default (gethostname(), i.e. the pod name) is not resolvable
-            # at all. The pod IP is unique, routable in-cluster, and
-            # re-registered on every start, so churn is self-healing.
-            - name: POD_IP
-              valueFrom:
-                fieldRef:
-                  fieldPath: status.podIP
-            - name: TURNSTONE_ADVERTISE_URL
-              value: "http://$(POD_IP):{{ .Values.server.service.port }}"
+            - name: TURNSTONE_DB_URL
+              value: "postgresql+psycopg://$(TURNSTONE_DB_USER):$(POSTGRES_PASSWORD)@$(TURNSTONE_DB_HOST):$(TURNSTONE_DB_PORT)/$(TURNSTONE_DB_NAME)"
          {{- if or .Values.auth.existingSecret .Values.auth.jwtSecret }}
            - name: TURNSTONE_JWT_SECRET
              valueFrom:
@@ -6,23 +6,11 @@ metadata:
    {{- include "turnstone.labels" . | nindent 4 }}
    app.kubernetes.io/component: migrate
  annotations:
-    # post-install, not pre-install: on a first install nothing the
-    # migration needs exists yet — not the ConfigMap, not the Secret, and
-    # with the bundled subchart not the database either, since Helm
-    # creates ordinary resources only once hooks have finished. On an
-    # upgrade all of it is already running, so pre-upgrade is both safe
-    # and preferable: migrations land before the new code rolls out
-    # rather than after.
-    "helm.sh/hook": post-install,pre-upgrade
+    "helm.sh/hook": pre-install,pre-upgrade
    "helm.sh/hook-weight": "-1"
    "helm.sh/hook-delete-policy": before-hook-creation,hook-succeeded
 spec:
-  # Helm does not wait for the database to be ready before running
-  # post-install hooks, so on a first install this Job is what waits: it
-  # exits non-zero until PostgreSQL accepts connections, and the retry
-  # budget has to cover a cold StatefulSet pulling its image and
-  # initialising.
-  backoffLimit: 10
+  backoffLimit: 3
  template:
    metadata:
      labels:
@@ -31,18 +19,6 @@ spec:
    spec:
      serviceAccountName: {{ include "turnstone.serviceAccountName" . }}
      restartPolicy: OnFailure
-      {{- with .Values.migrate.nodeSelector }}
-      nodeSelector:
-        {{- toYaml . | nindent 8 }}
-      {{- end }}
-      {{- with .Values.migrate.affinity }}
-      affinity:
-        {{- toYaml . | nindent 8 }}
-      {{- end }}
-      {{- with .Values.migrate.tolerations }}
-      tolerations:
-        {{- toYaml . | nindent 8 }}
-      {{- end }}
      containers:
        - name: migrate
          image: {{ include "turnstone.image" . }}
@@ -51,5 +27,12 @@ spec:
            - python
            - -m
            - turnstone.core.storage._migrate
+          envFrom:
+            - configMapRef:
+                name: {{ include "turnstone.fullname" . }}-config
+            - secretRef:
+                name: {{ include "turnstone.llm.secretName" . }}
+                optional: true
          env:
-            {{- include "turnstone.db.env" . | nindent 12 }}
+            - name: TURNSTONE_DB_URL
+              value: "postgresql+psycopg://$(TURNSTONE_DB_USER):$(POSTGRES_PASSWORD)@$(TURNSTONE_DB_HOST):$(TURNSTONE_DB_PORT)/$(TURNSTONE_DB_NAME)"
@@ -1,19 +1,4 @@
-{{/*
-This Secret backs every credential supplied inline in values, so it is
-rendered whenever any one of them is set — not, as it once was, only
-when llm.existingSecret is empty. Under that older gate an operator who
-supplied an LLM Secret lost the unrelated inline values with it: both
-POSTGRES_PASSWORD and TURNSTONE_JWT_SECRET silently went unrendered
-while the workloads went on referencing them, so every pod stalled in
-CreateContainerConfigError.
-
-Each key keeps its own condition, so an operator-supplied Secret still
-suppresses the value it replaces and nothing else.
-*/}}
-{{- $apiKey := and .Values.llm.apiKey (not .Values.llm.existingSecret) }}
-{{- $dbPassword := include "turnstone.db.inlinePassword" . }}
-{{- $jwtSecret := and .Values.auth.jwtSecret (not .Values.auth.existingSecret) }}
-{{- if or $apiKey $dbPassword $jwtSecret }}
+{{- if not .Values.llm.existingSecret }}
 apiVersion: v1
 kind: Secret
 metadata:
@@ -22,13 +7,15 @@ metadata:
    {{- include "turnstone.labels" . | nindent 4 }}
 type: Opaque
 data:
-  {{- if $apiKey }}
+  {{- if .Values.llm.apiKey }}
  OPENAI_API_KEY: {{ .Values.llm.apiKey | b64enc | quote }}
  {{- end }}
-  {{- if $dbPassword }}
-  POSTGRES_PASSWORD: {{ $dbPassword | b64enc | quote }}
+  {{- if and .Values.postgresql.enabled .Values.postgresql.auth.password }}
+  POSTGRES_PASSWORD: {{ .Values.postgresql.auth.password | b64enc | quote }}
+  {{- else if and (not .Values.postgresql.enabled) .Values.database.external.password }}
+  POSTGRES_PASSWORD: {{ .Values.database.external.password | b64enc | quote }}
  {{- end }}
-  {{- if $jwtSecret }}
+  {{- if and .Values.auth.jwtSecret (not .Values.auth.existingSecret) }}
  TURNSTONE_JWT_SECRET: {{ .Values.auth.jwtSecret | b64enc | quote }}
  {{- end }}
 {{- end }}
@@ -14,13 +14,7 @@ database:
    port: 5432
    database: turnstone
    username: turnstone
-    # Secret holding the password for `username`. Leave empty to supply
-    # `password` inline below instead.
    existingSecret: ""
-    # Key within existingSecret holding the password. CloudNativePG
-    # generates "password"; other operators differ.
-    existingSecretPasswordKey: password
-    password: ""
    sslmode: prefer

 # -- Bitnami PostgreSQL subchart
@@ -43,10 +37,6 @@ server:
  service:
    type: ClusterIP
    port: 8080
-  # -- Node scheduling constraints
-  nodeSelector: {}
-  affinity: {}
-  tolerations: []

 # -- Turnstone console (cluster dashboard)
 console:
@@ -61,17 +51,6 @@ console:
  service:
    type: ClusterIP
    port: 8090
-  # -- Node scheduling constraints
-  nodeSelector: {}
-  affinity: {}
-  tolerations: []
-
-# -- Database migration Job (post-install/pre-upgrade hook)
-migrate:
-  # -- Node scheduling constraints
-  nodeSelector: {}
-  affinity: {}
-  tolerations: []

 # -- LLM provider configuration
 llm:
@@ -103,18 +103,13 @@ network_policies:
      - path: /usr/bin/python3*
      - path: /usr/local/bin/python3*

-  # --- Web search (SearxNG) ---
-  # Turnstone talks only to its SearxNG instance over HTTP; SearxNG itself makes
-  # the outbound calls to search engines (and is NOT governed by this policy —
-  # it runs as a separate service). The host/port below is the bundled compose
-  # service name; if your SearxNG runs elsewhere, set it to match
-  # TURNSTONE_SEARXNG_URL.
+  # --- Web search fallback (Tavily) ---

-  searxng:
-    name: searxng-search
+  tavily_api:
+    name: tavily-search
    endpoints:
-      - host: searxng
-        port: 8080
+      - host: api.tavily.com
+        port: 443
    binaries:
      - path: /usr/bin/python3*
      - path: /usr/local/bin/python3*
@@ -1,87 +0,0 @@
-# Running a bare-metal turnstone-server under systemd
-
-These units run a `turnstone-server` **outside** Docker (e.g. on a box with a
-local GPU) so it joins an existing cluster — typically the docker-compose stack
-in [`compose.yaml`](../../compose.yaml). They are the hardened, production-shaped
-counterpart to the quick `turnstone-server …` invocation in
-[`docs/docker.md`](../../docs/docker.md) ("Join a bare-metal host").
-
-| File | Purpose |
-|------|---------|
-| `turnstone-server.service` | The hardened server unit (sandboxed; secrets via `config.toml`). |
-| `turnstone.slice` | Shared memory/process budget for colocated Turnstone units. |
-| `turnstone-server.service.d/node.conf.example` | Per-host identity + cluster URLs drop-in (no secrets). |
-
-## Cluster-side prerequisite
-
-The compose stack must publish Postgres, the console's ACME endpoint, and SearxNG
-on an address the bare-metal host can reach. Use a trusted LAN or VPN interface,
-firewall it to the joining node, and advertise the same reachable ACME endpoint
-(default `127.0.0.1` keeps everything host-local):
-
-```bash
-TURNSTONE_HOST_IP=<compose-host-ip> \
-TURNSTONE_ACME_EXTERNAL_URL=http://<compose-host-ip>:8090/acme \
-  docker compose up -d
-```
-
-## Install (run as root on the bare-metal host)
-
-```bash
-# 1. A dedicated, unprivileged user.
-useradd --system --no-create-home --shell /usr/sbin/nologin turnstone
-
-# 2. Install turnstone into a venv at /opt/turnstone-venv (lacme/mTLS is a core dep).
-uv venv /opt/turnstone-venv --python 3.12
-uv pip install --python /opt/turnstone-venv 'turnstone @ git+https://github.com/turnstonelabs/turnstone'
-#   …or from a local checkout:  uv pip install --python /opt/turnstone-venv /path/to/turnstone
-
-# 3. Secrets — match the cluster's JWT secret + DB credentials (kept out of env).
-install -d -m 750 -o turnstone -g turnstone /etc/turnstone
-cat > /etc/turnstone/config.toml <<'TOML'
-[auth]
-jwt_secret = "<same secret as the cluster>"
-[database]
-backend = "postgresql"
-url = "postgresql+psycopg://turnstone:<password>@<compose-host-ip>:5432/turnstone"
-[api]
-base_url = "http://localhost:8000/v1"   # a real model backend is configured in the console UI
-api_key = "dummy"
-TOML
-chown turnstone:turnstone /etc/turnstone/config.toml
-chmod 600 /etc/turnstone/config.toml
-
-# 4. Units + per-host drop-in.
-cp turnstone-server.service turnstone.slice /etc/systemd/system/
-install -d /etc/systemd/system/turnstone-server.service.d
-cp turnstone-server.service.d/node.conf.example \
-   /etc/systemd/system/turnstone-server.service.d/node.conf
-$EDITOR /etc/systemd/system/turnstone-server.service.d/node.conf   # set the addresses
-
-# 5. Go.
-systemctl daemon-reload
-systemctl enable --now turnstone-server.service
-journalctl -u turnstone-server -f          # watch it register + (if the cluster runs mTLS) enroll
-```
-
-`tls.enabled` is **not** set here — a joining node inherits it from the cluster's
-shared settings (the database). If the cluster runs mTLS, the node auto-enrolls a
-cert from the console's ACME endpoint and re-advertises itself over `https://`.
-
-For a node on a different host, `TURNSTONE_ACME_EXTERNAL_URL` is required on the
-console and should also be set in the node drop-in. It is the full, externally
-reachable responder base
-(including `/acme`) that the console embeds in the ACME protocol's follow-up
-URLs and that the node trusts as an enrollment-credential destination. The
-node's `TURNSTONE_CONSOLE_URL` should point at the same host and port, without
-the `/acme` suffix.
-
-For mTLS, `TURNSTONE_ADVERTISE_URL` may use a resolvable DNS hostname or a
-literal IP address. Turnstone enrolls literals as IP SANs. Bracket IPv6 literals
-inside URLs, for example `http://[2001:db8::10]:8080`; do not use wildcard,
-unspecified, or scoped addresses as certificate identities. Restart the node
-after changing its advertised identity so it enrolls a matching certificate.
-
-The dedicated service JWT authenticates enrollment but the direct `:8090`
-bootstrap is still plain HTTP/TOFU. Use HTTPS through an independently trusted
-proxy when the network itself is not trusted.
@@ -1,85 +0,0 @@
-# Run a bare-metal turnstone-server as a systemd service so it joins a cluster
-# (e.g. the docker-compose stack) from outside Docker — typically to use a local
-# GPU. Install steps + the cluster-side prerequisites are in deploy/systemd/README.md
-# and docs/docker.md ("Join a bare-metal host"). Per-host identity + the cluster
-# URLs go in a drop-in (see node.conf.example); secrets go in config.toml.
-[Unit]
-Description=Turnstone server (chat workstreams + LLM gateway)
-Documentation=https://github.com/turnstonelabs/turnstone
-# Postgres is required. After= orders against a colocated postgresql.service
-# when present and silently no-ops otherwise (the cluster DB is usually remote).
-After=network.target postgresql.service
-StartLimitIntervalSec=60
-StartLimitBurst=5
-
-[Service]
-Type=exec
-User=turnstone
-Group=turnstone
-
-# Secrets live in config.toml — JWT secret, Postgres URL+password, LLM API key —
-# kept out of os.environ so a prompt-injected tool can't dump them via `env`.
-Environment=TURNSTONE_CONFIG=/etc/turnstone/config.toml
-Environment=TURNSTONE_LOG_LEVEL=info
-
-Slice=turnstone.slice
-
-# Per-host node identity + cluster wiring (TURNSTONE_NODE_ID / _ADVERTISE_URL /
-# _CONSOLE_URL / _SEARXNG_URL) go in a drop-in, not here — see node.conf.example.
-
-StateDirectory=turnstone
-StateDirectoryMode=0750
-LogsDirectory=turnstone
-LogsDirectoryMode=0750
-WorkingDirectory=/var/lib/turnstone
-
-# --host 0.0.0.0 so the console collector + peer nodes can dial this node back
-# at its advertised address. (A single-node, Caddy-fronted install can use
-# 127.0.0.1 instead.) Rewrite --port if :8080 is already taken on the host.
-ExecStart=/opt/turnstone-venv/bin/turnstone-server --host 0.0.0.0 --port 8080
-
-Restart=on-failure
-RestartSec=5s
-TimeoutStartSec=120
-TimeoutStopSec=30
-KillSignal=SIGTERM
-KillMode=mixed
-
-# --- Resource limits ---
-# SSE keeps an fd per active workstream + outbound LLM stream + MCP stdio pipe.
-LimitNOFILE=65535
-LimitNPROC=8192
-TasksMax=8192
-LimitCORE=0
-
-# --- Hardening ---
-NoNewPrivileges=true
-CapabilityBoundingSet=
-AmbientCapabilities=
-UMask=0027
-PrivateTmp=true
-# PrivateDevices=true  — disabled: GPU access via /sys/class/drm
-ProtectSystem=strict
-ProtectHome=true
-ProtectKernelTunables=true
-ProtectKernelModules=true
-ProtectKernelLogs=true
-ProtectControlGroups=true
-ProtectClock=true
-ProtectHostname=true
-RestrictNamespaces=true
-RestrictRealtime=true
-RestrictSUIDSGID=true
-RestrictAddressFamilies=AF_UNIX AF_INET AF_INET6
-LockPersonality=true
-MemoryDenyWriteExecute=true
-SystemCallArchitectures=native
-SystemCallFilter=@system-service
-SystemCallFilter=~@privileged @mount
-
-StandardOutput=journal
-StandardError=journal
-SyslogIdentifier=turnstone-server
-
-[Install]
-WantedBy=multi-user.target
@@ -1,33 +0,0 @@
-# Per-host node identity + cluster wiring for a bare-metal turnstone-server.
-# Copy to /etc/systemd/system/turnstone-server.service.d/node.conf and edit the
-# addresses, then `systemctl daemon-reload`. Identity + URLs are NOT secrets, so
-# they live here; the JWT secret + DB URL live in /etc/turnstone/config.toml.
-#
-# Addresses below use RFC 5737 documentation IPs — replace them:
-#   <this-host>     = the bare-metal host's own reachable DNS name or IP address
-#                     (its mTLS identity and the address peers dial)
-#   <compose-host>  = the host running the cluster / docker-compose stack, started
-#                     with TURNSTONE_HOST_IP=<compose-host> and
-#                     TURNSTONE_ACME_EXTERNAL_URL=http://<compose-host>:8090/acme
-#                     so enrollment links and published ports are reachable
-#                     (see docs/docker.md).
-[Service]
-# Unique node id (defaults to the hostname if unset).
-Environment=TURNSTONE_NODE_ID=host-1
-
-# The address peers + the console collector dial back. Auto-upgrades to https://
-# once the node enrolls its mTLS cert. IPv6 literals require URL brackets, for
-# example http://[2001:db8::10]:8080.
-Environment=TURNSTONE_ADVERTISE_URL=http://192.0.2.10:8080
-
-# The cluster console's reachable plain-HTTP ACME/API endpoint. A bare-metal node
-# can't resolve the in-cluster name (console:8090), so point it at the published
-# port; turnstone-server honors this for cert enrollment.
-Environment=TURNSTONE_CONSOLE_URL=http://192.0.2.1:8090
-
-# Trusted canonical responder base. This pins where the node may send its
-# enrollment JWT; it must match the console-side value (a literal IP is fine).
-Environment=TURNSTONE_ACME_EXTERNAL_URL=http://192.0.2.1:8090/acme
-
-# The cluster's published SearxNG, for the web_search tool.
-Environment=TURNSTONE_SEARXNG_URL=http://192.0.2.1:8081
@@ -1,15 +0,0 @@
-# Shared resource budget for the colocated Turnstone units. Without a slice each
-# unit's MemoryMax= is enforced independently — three units at 85% each can sum
-# to 255% of host RAM before any throttles. Under a shared slice the cap is
-# hierarchical: the slice ceiling is the real limit. (A bare-metal node that runs
-# only turnstone-server still benefits — and keeps the unit's Slice= reference
-# valid.) Adjust if the host runs other meaningful workloads alongside Turnstone.
-[Unit]
-Description=Turnstone services slice (server + console + channel)
-Documentation=https://github.com/turnstonelabs/turnstone
-Before=slices.target
-
-[Slice]
-MemoryHigh=70%
-MemoryMax=85%
-TasksMax=16384
@@ -2,69 +2,13 @@
 """Health check for turnstone containers.

 Usage: healthcheck.py <url>
-Exit 0 if the endpoint returns {"status": "ok"} or {"status": "degraded"},
-exit 1 otherwise. Uses only stdlib — no pip dependencies required.
-
-When the node serves mTLS (tls.enabled), a plain-HTTP probe is rejected at
-the socket, so on failure this script retries over HTTPS, presenting the
-node's own certificate as the client cert and pinning the cluster CA. The
-PEM files are the ones the server writes at boot under
-$TURNSTONE_TLS_PEM_DIR (default: <tmpdir>/turnstone-tls). The host is
-rewritten to "localhost" for the TLS attempt because the internal CA issues
-DNS SANs only — certificate verification rejects a literal-IP dial.
-
-When mTLS is disabled (the default), the plain probe succeeds and nothing
-here changes: the PEM directory is never consulted.
+Exit 0 if the endpoint returns {"status": "ok"}, exit 1 otherwise.
+Uses only stdlib — no pip dependencies required.
 """

 import json
-import os
-import ssl
 import sys
-import tempfile
 import urllib.request
-from pathlib import Path
-from urllib.parse import urlsplit, urlunsplit
-
-
-def _check(url: str, context: ssl.SSLContext | None = None) -> None:
-    """Probe one URL; raise if unreachable or the payload is unhealthy."""
-    req = urllib.request.Request(url, method="GET")
-    with urllib.request.urlopen(req, timeout=5, context=context) as resp:
-        data = json.loads(resp.read().decode())
-    if data.get("status") not in ("ok", "degraded"):
-        raise RuntimeError(f"unhealthy payload: {data}")
-
-
-def _pem_root() -> Path:
-    """PEM runtime root.
-
-    Must mirror turnstone.core.tls.tls_pem_runtime_dir — this script is
-    standalone stdlib and cannot import turnstone; a drift-guard test in
-    tests/test_docker_healthcheck.py pins the two together.
-    """
-    root_env = os.environ.get("TURNSTONE_TLS_PEM_DIR")
-    return Path(root_env) if root_env else Path(tempfile.gettempdir()) / "turnstone-tls"
-
-
-def _find_pem_dir() -> Path | None:
-    """Locate the newest complete PEM dir written by the server at boot."""
-    root = _pem_root()
-    candidates = [
-        d
-        for d in root.glob("lacme-pem-*")
-        if all((d / name).is_file() for name in ("fullchain.pem", "key.pem", "ca.pem"))
-    ]
-    if not candidates:
-        return None
-    return max(candidates, key=lambda d: d.stat().st_mtime)
-
-
-def _tls_url(url: str) -> str:
-    """Rewrite scheme to https and host to localhost, keeping port and path."""
-    parts = urlsplit(url)
-    netloc = f"localhost:{parts.port}" if parts.port else "localhost"
-    return urlunsplit(("https", netloc, parts.path, parts.query, parts.fragment))


 def main() -> None:
@@ -74,24 +18,16 @@ def main() -> None:

    url = sys.argv[1]
    try:
-        _check(url)
-        sys.exit(0)
-    except Exception as plain_exc:
-        pem_dir = _find_pem_dir()
-        if pem_dir is None:
-            print(f"Health check failed: {plain_exc}", file=sys.stderr)
-            sys.exit(1)
-        try:
-            context = ssl.create_default_context(cafile=str(pem_dir / "ca.pem"))
-            context.load_cert_chain(str(pem_dir / "fullchain.pem"), str(pem_dir / "key.pem"))
-            _check(_tls_url(url), context=context)
-            sys.exit(0)
-        except Exception as tls_exc:
-            print(
-                f"Health check failed: plain: {plain_exc}; mtls: {tls_exc}",
-                file=sys.stderr,
-            )
+        req = urllib.request.Request(url, method="GET")
+        with urllib.request.urlopen(req, timeout=5) as resp:
+            data = json.loads(resp.read().decode())
+            if data.get("status") in ("ok", "degraded"):
+                sys.exit(0)
+            print(f"Unhealthy: {data}", file=sys.stderr)
            sys.exit(1)
+    except Exception as exc:
+        print(f"Health check failed: {exc}", file=sys.stderr)
+        sys.exit(1)


 if __name__ == "__main__":
@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:5d500479d3be2363d4f594042a27e2ef5e2974750f580f6c4037a1fe85868ed9
-size 251904
+oid sha256:75c1832b6079e8628f4bbf4ce98d37880c4de133636b7555e3869990b046ddc6
+size 567704
@@ -1,231 +0,0 @@
-# Bulk endpoint shape contract
-
-Turnstone exposes several endpoints and tool calls that take multiple
-ids and return a per-id outcome.  Over the last few phases two
-**distinct** response shapes have settled, one per semantic category.
-This doc codifies both so a future endpoint author can pick the right
-shape by semantics instead of by coin-flip.
-
-Existing bulk endpoints at time of writing:
-
-| Endpoint / tool                                         | Category                 | Response shape                          |
-|---------------------------------------------------------|--------------------------|------------------------------------------|
-| `GET  /v1/api/cluster/ws/live?ids=a,b,c`                | bulk read                | `{results, denied, truncated}`           |
-| model tool `spawn_batch`                                 | bulk create (per-item)   | `{results, denied}`                      |
-| `POST /v1/api/workstreams/{ws_id}/close_all_children`    | cascade mutation         | `{closed, failed, skipped}`              |
-
---
-
-## Why two shapes
-
-The ask-to-outcome mapping is fundamentally different between the
-two categories, and a one-size-fits-all envelope ends up papering
-over distinctions the caller genuinely needs to branch on.
-
-**Bulk read / bulk create-with-payload.**  Each input id (or batch
-index) carries a *request-side* concept — "give me the live block
-for this ws_id" or "spawn a child with this spec" — and each
-successful output carries a *payload* — the live block, or the new
-workstream's identifying triple.  The interesting distinction on
-failure is *ownership / validation* (caller can't see that id, spec
-was malformed) — independent of the storage state.
-
-**Cascade mutation.**  The action is uniform across every id (cancel
-this subtree, close this child).  The interesting distinctions on
-outcome are *did it reach the terminal state?* (succeeded / already
-was there / the dispatch itself failed) — driven by the storage
-state plus transport reliability, not by the caller's input.
-
-Trying to unify these forces either:
-
- a stateless `denied` bucket that has to carry "already gone"
-  *and* "you don't have permission" *and* "transport failed" with a
-  separate reason string — reviewers end up string-matching to branch.
- or a per-item-payload map for cascade mutations where every
-  successful value is the same sentinel — carrier with no payload.
-
-So: two shapes, one per category.  The rest of this doc spells out
-each.
-
---
-
-## Shape A — bulk read / bulk create-with-payload
-
-```json
-{
-  "results":  { "<key>": <value-or-null>, ... },
-  "denied":   [ "<key>", ... ],
-  "truncated": false
-}
-```
-
-**`results`** is a key-indexed map of the positive-path payload.
-The key is the input id for read endpoints (`cluster/ws/live` uses
-the ws_id), or the input-array index (stringified) for create
-endpoints that want ordering preserved (`spawn_batch` uses `"0"`,
-`"1"`, ...).  The value is whatever the endpoint produces per
-success — a live block, a `{ws_id, name, node_id, status}` triple,
-etc.  A `null` value (read endpoints only) means "the id existed and
-you own it, but the live block wasn't available" — distinct from
-"denied".
-
-**`denied`** is the negative-path list.  For read endpoints it's a
-flat list of ids (preserves input order so callers can re-zip
-against their input).  For create endpoints with per-item payloads
-it's a list of `{idx, reason}` objects (`spawn_batch`'s validation
-and spawn-error rows; also the operator-reject surface when per-item
-selective-deny ships).  Include every reason that's *not* the
-positive path — authz, ownership, validation, already-consumed,
-spawn failure — so callers don't branch on status codes.
-
-**`truncated`** is a boolean set to `true` when the server's
-per-endpoint input cap was exceeded and the tail was dropped.  The
-endpoint docs each spell out the cap (50 for `cluster/ws/live`).
-`spawn_batch` hard-errors on overflow instead of silently
-truncating — it omits the field entirely rather than carry a
-permanently-false flag.
-
-### Example — `cluster/ws/live`
-
-```http
-GET /v1/api/cluster/ws/live?ids=a1b2,c3d4,nonexistent,foreign HTTP/1.1
-```
-
-```json
-{
-  "results": {
-    "a1b2": {"state": "running", "tokens": 12843, "activity": "..."},
-    "c3d4": null
-  },
-  "denied": ["nonexistent", "foreign"],
-  "truncated": false
-}
-```
-
-Callers that need ordered output zip their original id list against
-this map; ids in `denied` drop out of the zip cleanly.  A live-block
-`null` doesn't route to `denied` — the row exists and the caller
-owns it; the node is just currently unreachable.
-
-### Example — `spawn_batch`
-
-This is the coordinator-tool result shape (the JSON the LLM receives),
-not an HTTP API response — the table above keys it under "model tool"
-to distinguish it from the `/v1/api/...` endpoints in the same table.
-The underlying HTTP spawn endpoint still returns `ws_id`; the tool
-result re-keys it to `child_ws_id` to defuse a coordinator-LLM recency
-bias (see `docs/coordinator-skills.md`).
-
-```json
-{
-  "results": {
-    "0": {"child_ws_id": "d4e5f6...", "name": "csrf-audit", "node_id": "gpu-3"},
-    "2": {"child_ws_id": "f1a2b3...", "name": "xss-audit",  "node_id": "gpu-1"}
-  },
-  "denied": [
-    {"idx": 1, "reason": "skill not found: nonexistent-skill"}
-  ]
-}
-```
-
-Indexes are stringified to keep the envelope JSON-safe and
-consistently-typed across the read and create cases.
-
---
-
-## Shape B — cascade mutation
-
-```json
-{
-  "status":       "ok",
-  "<bucket>":     [ "<ws_id>", ... ],
-  "failed":       [ "<ws_id>", ... ],
-  "skipped":      [ "<ws_id>", ... ]
-}
-```
-
-Where `<bucket>` is the endpoint-specific name for "succeeded" —
-`closed` for `close_all_children`.
-The three buckets partition the input set exactly once:
-
-| Bucket        | Meaning                                                                       |
-|---------------|-------------------------------------------------------------------------------|
-| `<bucket>`    | Action dispatch accepted; target reached the intended terminal state.         |
-| `failed`      | Dispatch returned a non-404 error (transport issue, upstream 5xx, exception). |
-| `skipped`     | Upstream 404 — stale registry entry, row already deleted, or peer gone.       |
-
-The split between `failed` and `skipped` is load-bearing.  `failed`
-is actionable — the operator may want to retry, or the cascade may
-be partial.  `skipped` is pre-resolved — the target is already in
-the terminal state the cascade was aiming at, so it's neither a
-win to report nor a fault to fix.
-
-### Example — `close_all_children`
-
-```json
-{
-  "status": "ok",
-  "closed":  ["child-1", "child-3"],
-  "failed":  ["child-2"],
-  "skipped": []
-}
-```
-
-Here the success bucket is `closed`.  A subsequent retry would
-target only `failed` ids, not `skipped` ones — the latter are
-already done.  When `coord_client` is unavailable (session loaded
-but no HTTP client attached — a construction bug) every id goes to
-`failed` so the operator notices rather than getting a silent
-all-skipped response.
-
---
-
-## Guidance for future bulk endpoints
-
-1. **Pick by semantics, not by "what shape is nearby."**
-   - Mutation that's uniform across ids + terminal-state outcome?  →
-     **Shape B** (cascade mutation).
-   - Read or create where the input id carries payload, or where the
-     denial axis is independent of storage state?  →  **Shape A**
-     (bulk read / bulk create-with-payload).
-
-2. **Cap the input.**  Both shapes assume a bounded input — the
-   server rejects or silently truncates past the cap.  Document the
-   cap in the endpoint's OpenAPI description.  Shape A uses
-   `truncated: true` on quiet truncation; Shape B hard-errors on
-   overflow.
-
-3. **Match existing bucket names for the same semantic.**  Use
-   `failed` and `skipped` verbatim in Shape B — the per-endpoint
-   success bucket is the only slot that varies.  Use `results` and
-   `denied` verbatim in Shape A; the per-endpoint `<key>` /
-   `<value>` types vary.
-
-4. **Audit the verbose shape.**  Both endpoints emit a corresponding
-   audit event with the full before/after bucket lists — the SSE
-   stream and the in-process response give live feedback, but a
-   postmortem operator will read the audit row.  Use
-   `_emit_coord_audit` (coordinator-scoped) or `record_audit`
-   directly; don't inline.
-
-5. **Don't mix shapes within one endpoint.**  If a bulk endpoint
-   wants both partial-success creation AND per-item failure reasons
-   (like `spawn_batch` with its `{idx, reason}` denial rows), that's
-   Shape A with a richer denial element — not a blend with Shape B.
-
---
-
-## History
-
- **Phase 6** shipped `cluster/ws/live` as the first Shape A endpoint
-  (`{results, denied, truncated}`).
- **Phase 7** introduced the Shape B cascade-mutation envelope
-  (`{<bucket>, failed, skipped}`) for the coordinator's
-  cancel-cascade path.
- **Phase 8 PR A** shipped `spawn_batch` (Shape A, keyed by idx) and
-  `close_all_children` (Shape B), which crystallised the
-  two-shape-per-semantic-category policy codified here.
-
-Before adding a third shape, read this doc and argue for why the
-new surface doesn't fit either A or B.  Two idioms in the cluster
-API is a finite operator tax; three is one too many.
@@ -7,35 +7,31 @@ platform-native events (messages, button clicks, slash commands) into
 turnstone API calls, and renders workstream output back into the
 platform's UI.

-Discord and Slack adapters ship today. The adapter protocol is designed
-so new platforms can be added with only a new package under
-`turnstone/channels/<platform>/`.
+Discord ships as the first adapter. The adapter protocol is designed for
+future Slack and Teams integrations.

 ---

 ## Architecture

 ```
-Discord Gateway        Slack (Socket Mode WebSocket)
-       \                  /
-        v                v
-       turnstone-channel  (one or more adapters)
-              |
-              v
-       turnstone-server   (direct HTTP)
-              or
-       turnstone-console  (routing proxy, multi-node)
+Discord Gateway
+      |
+      v
+turnstone-channel  (Discord adapter)
+      |
+      v
+turnstone-server   (direct HTTP)
+      or
+turnstone-console  (routing proxy, multi-node)
 ```

-A single `turnstone-channel` process can run multiple adapters
-simultaneously (e.g. Discord + Slack) — pass the tokens for each
-platform you want to enable.
-
 Key components:

 - **ChannelAdapter protocol** (`turnstone/channels/_protocol.py`) — generic
  interface for any messaging platform. Defines `start()`, `stop()`,
-  `send()`, and `send_notification()`.
+  `send()`, `send_notification()`, `edit_message()`,
+  `send_approval_request()`, `send_plan_review()`, and `create_thread()`.
 - **ChannelRouter** (`turnstone/channels/_routing.py`) — maps
  channel/thread IDs to turnstone workstream IDs. Handles workstream
  creation via HTTP, stale route detection, and user identity resolution.
@@ -99,10 +95,10 @@ TURNSTONE_DISCORD_GUILD=123456789
 Then start the stack:

 ```bash
-docker compose up
+docker compose --profile production up
 ```

-The `channel` gateway runs by default; the Discord adapter activates once
+The `channel` service starts automatically when
 `TURNSTONE_DISCORD_TOKEN` is set.

 ### 3. Link User Accounts
@@ -124,67 +120,6 @@ An admin can also force-link or unlink users via the console admin panel

 ---

-## Slack Setup
-
-Slack uses **Socket Mode**, so no public URL or API Gateway is required — Slack
-connects outbound to the bot via a WebSocket. Install with:
-
-```bash
-pip install 'turnstone[slack]'
-```
-
-### 1. Create a Slack App
-
-1. Go to https://api.slack.com/apps and click **Create New App**
-2. Under **Settings > Socket Mode**, enable Socket Mode. This generates an
-   **App-Level Token** (prefix `xapp-`) — copy it.
-3. Under **OAuth & Permissions**, add these **Bot Token Scopes**:
-   `chat:write`, `chat:write.public`, `channels:history`, `im:history`,
-   `groups:history`, `mpim:history`, `reactions:write`, `commands`
-4. Under **Event Subscriptions** (Socket Mode delivers events), subscribe
-   to bot events: `message.channels`, `message.im`, `message.groups`
-5. Under **Slash Commands**, create a command (default `/turnstone`)
-6. Install the app to your workspace to generate the **Bot User OAuth
-   Token** (prefix `xoxb-`).
-
-### 2. Configure Turnstone
-
-**Environment variables** (recommended for Docker):
-
-```bash
-TURNSTONE_SLACK_TOKEN=xoxb-...        # Bot User OAuth Token
-TURNSTONE_SLACK_APP_TOKEN=xapp-...    # App-Level Token (Socket Mode)
-TURNSTONE_SLACK_CHANNELS=             # optional, comma-separated channel IDs
-TURNSTONE_SLACK_SLASH_COMMAND=/turnstone
-```
-
-**CLI flags** (bare-metal):
-
-```bash
-turnstone-channel \
-  --slack-token "xoxb-..." \
-  --slack-app-token "xapp-..." \
-  --slack-slash-command /turnstone \
-  --server-url http://localhost:8080
-```
-
-The Slack and Discord adapters can be enabled together — pass tokens for
-both and the gateway hosts both adapters in one process.
-
-### 3. Usage
-
- **DM the bot**: messages sent directly to the bot create a workstream
-  scoped to that DM; the slash command is not required.
- **Slash command**: `/turnstone <message>` in any channel the bot can
-  see starts a per-user channel session.
- Tool approvals render as Slack **Block Kit** buttons; only the user
-  who owns the workstream can approve/reject.
- Notifications and reply routing work identically to Discord.
- Session recovery: persisted channel routes are re-subscribed when the
-  bot restarts, so existing Slack conversations keep flowing.
-
---
-
 ## Usage

 ### Conversations
@@ -195,17 +130,13 @@ both and the gateway hosts both adapters in one process.
 - All subsequent messages in the thread are routed to the same workstream.
 - The bot streams responses via message edits, updated approximately every
  1.5 seconds.
- If a persisted channel route is no longer active on its owning node, the
-  router asks the create endpoint to fork the old workstream into a new ID via
-  `resume_ws`. The saved source can still resolve normally; its
-  checkpoint-bounded history, configuration, persona, effective project, and
-  attachment references are cloned before the channel route is repointed. The
-  old route remains durable until the replacement (and any initial message)
-  succeeds. If the create endpoint returns the ordinary
-  source-not-found response *and* a fresh authoritative storage lookup confirms
-  that the source is gone, the router retries once without `resume_ws` and
-  starts a fresh conversation. Other access, conflict, routing, and storage
-  failures remain visible rather than silently discarding history.
+- If the workstream is evicted for capacity, the next message in the
+  thread auto-creates a new workstream and atomically resumes the
+  previous workstream via the `resume_ws` field on
+  `CreateWorkstreamMessage`. The server resumes the workstream during
+  creation (same HTTP request), and the server emits a
+  `WorkstreamResumedEvent` back to the channel. The thread receives a
+  *"Resumed: {name} ({count} messages restored)"* confirmation.

 ### Slash Commands

@@ -238,19 +169,24 @@ config, the bot auto-responds with approval and posts a
 field (useful for allowing specific tools like `bash` or `read_file` while
 still requiring manual approval for others).

+### Plan Reviews
+
+Plan review requests are displayed as a blue embed with:
+
+- **Approve Plan** (green) button — approves the plan with empty feedback
+- **Request Changes** (gray) button — opens a modal for feedback text
+  (up to 2000 characters)
+- Feedback is forwarded to the server via HTTP
+
 ---

 ## Configuration Reference

 | CLI Flag | Env Var | Default | Description |
 |----------|---------|---------|-------------|
-| `--discord-token` | `TURNSTONE_DISCORD_TOKEN` | — | Discord bot token (required to enable Discord) |
+| `--discord-token` | `TURNSTONE_DISCORD_TOKEN` | — | Bot token (required to enable Discord) |
 | `--discord-guild` | — | `0` (all guilds) | Restrict to a single Discord guild |
-| `--discord-channels` | — | empty (all) | Comma-separated Discord channel IDs to allow |
-| `--slack-token` | `TURNSTONE_SLACK_TOKEN` | — | Slack Bot User OAuth token (`xoxb-…`, required to enable Slack) |
-| `--slack-app-token` | `TURNSTONE_SLACK_APP_TOKEN` | — | Slack App-Level token (`xapp-…`, required with `--slack-token`) |
-| `--slack-channels` | `TURNSTONE_SLACK_CHANNELS` | empty (all) | Comma-separated Slack channel IDs to allow |
-| `--slack-slash-command` | `TURNSTONE_SLACK_SLASH_COMMAND` | `/turnstone` | Slash command name registered in the Slack app |
+| `--discord-channels` | — | empty (all) | Comma-separated channel IDs to allow |
 | `--server-url` | `TURNSTONE_SERVER_URL` | `http://localhost:8080` | Server URL (single-node) |
 | `--console-url` | `TURNSTONE_CONSOLE_URL` | — | Console URL (multi-node routing proxy) |
 | `--model` | — | server default | Default model for new workstreams |
@@ -260,9 +196,6 @@ still requiring manual approval for others).
 | `--log-level` | `TURNSTONE_LOG_LEVEL` | `INFO` | Log level |
 | `--log-format` | `TURNSTONE_LOG_FORMAT` | `auto` | Log format (`auto`/`json`/`text`) |

-At least one of `--discord-token` or `--slack-token` must be supplied.
-Passing both starts both adapters in the same process.
-
 ---

 ## User Identity
@@ -288,17 +221,15 @@ See [Security: Database Schema](security.md#database-schema) for the
   `channel_routes` table.
 2. **Active** — messages are routed bidirectionally. The bot streams
   responses via message edits (updated every ~1.5 seconds).
-3. **Eviction** — the server evicts an idle workstream for capacity. Its saved
-   source row and channel route remain durable, and the thread stays open.
-4. **Reactivation** — the next message resolves the saved route and probes
-   whether that workstream is live on its owning node. If it is not, the router
-   creates a distinct workstream with the old `ws_id` as `resume_ws`. The
-   create response confirms the fork and message count; there is no separate
-   resume command or channel-specific resumed event. Only after the replacement
-   succeeds does the router swap the persisted route. If the source was deleted
-   or pruned, an exact source-not-found response plus a second authoritative
-   storage miss triggers one fresh-create retry; other fork failures leave the
-   old route intact and are surfaced normally.
+3. **Eviction** — the server evicts an idle workstream for capacity. The
+   route is preserved and the thread stays open.
+4. **Reactivation** — the next message in the thread detects the stale
+   route and creates a new workstream with the old `ws_id`
+   as `resume_ws` on the creation request. The server resumes
+   the workstream during creation (no separate command or reverse lookup
+   needed). The channel receives a `WorkstreamResumedEvent`, and
+   the thread displays *"Resumed: {name} ({count} messages restored)"*.
+   If the old workstream was pruned, a fresh one starts with no error.
 5. **Close** — `/close` command closes the workstream via HTTP, deletes the
   route, unsubscribes from events, and archives the Discord thread.

@@ -318,8 +249,8 @@ waiting for them to check in.
 Two modes:

 - **Username** — provide a turnstone `username`. The gateway resolves
-  it via the `channel_users` table and sends to every linked platform
-  the user has (e.g. Discord + Slack).
+  it via the `channel_users` table and sends to all linked channels
+  (e.g. Discord + future Slack).
 - **Direct** — provide `channel_type` + `channel_id` to target a
  specific platform channel or user DM.

@@ -420,6 +351,10 @@ class ChannelAdapter(Protocol):
    async def stop(self) -> None: ...
    async def send(self, channel_id: str, content: str) -> str: ...
    async def send_notification(self, channel_id: str, content: str, ws_id: str) -> str: ...
+    async def edit_message(self, channel_id: str, message_id: str, content: str) -> None: ...
+    async def send_approval_request(self, channel_id: str, ws_id: str, correlation_id: str, items: list[dict]) -> None: ...
+    async def send_plan_review(self, channel_id: str, ws_id: str, correlation_id: str, content: str) -> None: ...
+    async def create_thread(self, parent_channel_id: str, name: str, message_id: str = "") -> str: ...
 ```

 `send_notification()` is like `send()` but associates the outgoing
@@ -427,11 +362,6 @@ message with a `ws_id` so that user replies can be routed back to the
 originating workstream. Adapters must track the mapping from outgoing
 message ID to `(ws_id, target_user_id)` and handle DM replies.

-Platform-specific concerns — approval prompts, message edits, thread
-creation — live inside the adapter implementation and are not part of
-the protocol surface. Each adapter drives those via its
-own `_on_ws_event` dispatcher using SDK-native APIs.
-
 To add a new platform:

 1. Create `turnstone/channels/<platform>/` package
@@ -174,32 +174,17 @@ Request:
 {
  "node_id": "db-west-04",
  "name": "perf-analysis",
-  "model": "gpt-5",
-  "project_id": "proj_analytics",
-  "initial_message": "Profile the slow query"
+  "model": "gpt-5"
 }
 ```

 All fields are optional:
 - `node_id` — targeting mode:
  - **omitted or `"auto"`** — console picks the reachable node with the most available capacity (max_ws - ws_total) and proxies the request to it.
-  - **`"pool"`** — compatibility alias for automatic placement on the reachable node with the most headroom.
+  - **`"pool"`** — console picks a reachable node with available capacity using round-robin selection.
  - **specific node ID** — proxies the request to that node directly.
 - `name` — workstream display name. Auto-generated if omitted.
 - `model` — model alias from the target node's registry. Uses the node's default model if omitted.
- `judge_model` — optional judge-model alias for this workstream.
- `initial_message` — first message dispatched after the workstream is published.
- `skill` — enabled profile/skill to snapshot onto a fresh workstream.
- `persona` — enabled persona slug; empty uses the interactive default.
- `project_id` — project to attach, subject to the target node's membership gate.
- `resume_ws` — source ID to **fork** atomically into a new workstream. The
-  source remains unchanged; its checkpoint-bounded history, configuration,
-  persona, project, and attachment references are copied transactionally.
-
-The endpoint also accepts the same multipart create shape as a node: one
-JSON-encoded `meta` field plus up to ten `file` parts. Files require an
-`initial_message` in the dashboard launcher. Files cannot be combined with
-`resume_ws`; fork first and upload on the new workstream.

 Response:

@@ -211,19 +196,7 @@ Response:
 }
 ```

-The response is returned only after the target node has durably published the
-workstream. Its hidden `creating` reservation has already crossed to `idle`,
-and the node emitted `ws_created` before any initial-message state event. The
-cluster SSE event may therefore arrive before or after the HTTP response;
-clients should reconcile both by the returned `correlation_id`/workstream ID
-rather than treating them as two creates.
-
-For safety, the console masks most target-node failures as the opaque `502`
-shape `{"error":"Dispatch to node <node_id> failed"}` instead of reflecting
-arbitrary node text or retry-triggering 401/429 responses. The coded
-`server.require_project` refusal is the exception and remains a `400` with
-actionable wording. Consult the target node's logs for the underlying create
-correlation when a reachable node returns a masked 502.
+The response confirms the workstream creation request was proxied to the target node. A `ws_created` event on the cluster SSE stream confirms the workstream was actually created.

 ### `GET /v1/api/cluster/events`

@@ -337,8 +310,8 @@ The auth system uses three scopes instead of the earlier read/full role model:
 | Scope | Grants |
 |-------|--------|
 | `read` | Read-only access: dashboards, workstream lists, SSE streams, health |
-| `write` | Non-approval mutations: send, create/open/close/delete, cancel, attachments, rewind, and retry |
-| `approve` | Tool-approval and admin HTTP surfaces (with their additional RBAC permission checks) |
+| `write` | Send messages, create/close workstreams, approve tool calls |
+| `approve` | Admin operations: manage users and API tokens |

 Scopes are cumulative — a user with `approve` scope can also perform `write` and `read` operations.

@@ -361,7 +334,7 @@ The console reverse-proxies each node's server UI at `/node/{node_id}/`. This al

 ### URL Rewriting

-The server UI uses root-relative URLs (`/v1/api/workstreams/{ws_id}/send`, `/static/app.js`, `/shared/base.css`, etc.). Since `<base>` tags cannot rewrite root-relative URLs, the console uses a JS shim approach:
+The server UI uses root-relative URLs (`/v1/api/send`, `/static/app.js`, `/shared/base.css`, etc.). Since `<base>` tags cannot rewrite root-relative URLs, the console uses a JS shim approach:

 1. **HTML rewriting** — when serving `index.html`, replaces `href=` and `src=` references to both `/static/` and `/shared/` with the proxy prefix (`/node/{node_id}/static/` and `/node/{node_id}/shared/` respectively).

@@ -371,113 +344,59 @@ The server UI uses root-relative URLs (`/v1/api/workstreams/{ws_id}/send`, `/sta

 ### SSE Proxy

-SSE streams (`/v1/api/workstreams/{ws_id}/events`, `/v1/api/events/global`) are proxied as raw byte passthrough — the console opens an `httpx.AsyncClient.stream()` to the upstream server (with `read=None` and `pool=None` timeouts since SSE connections are long-lived) and relays every byte via `StreamingResponse`. This preserves server-side ping comments, event framing, and keepalives verbatim without parsing or re-encoding.
+SSE streams (`/v1/api/events`, `/v1/api/events/global`) are proxied as raw byte passthrough — the console opens an `httpx.AsyncClient.stream()` to the upstream server (with `read=None` and `pool=None` timeouts since SSE connections are long-lived) and relays every byte via `StreamingResponse`. This preserves server-side ping comments, event framing, and keepalives verbatim without parsing or re-encoding.

 ### Authentication

-The proxy mints a short-lived (5-minute) JWT per request carrying the real user's `user_id`, `scopes`, and `permissions` with `aud: turnstone-server`.  The user's console JWT (`aud: turnstone-console`) cannot be forwarded directly — it would be rejected by the server's audience validation — so the console re-signs a new server-audience JWT from the validated `AuthResult`.  This preserves audit attribution (the upstream server sees the real user, not a service identity) and enforces scope narrowing as defense in depth (a read-only console user's proxied request carries only `read` scope). Ordinary users are re-minted with `src="console-proxy"`; coordinator tokens retain `src="coordinator"` plus `coord_ws_id`, and only the validated console service identity with `service` scope retains `src="console"` for trusted owner forwarding. When no user context is available, the proxy falls back to a `ServiceTokenManager` identity `console-proxy` carrying `src="console"` and `{read, write, approve, service}` scopes.  The static `--auth-token` / `proxy_auth_token` is used as a final fallback.
+The proxy mints a short-lived (5-minute) JWT per request carrying the real user's `user_id`, `scopes`, and `permissions` with `aud: turnstone-server`.  The user's console JWT (`aud: turnstone-console`) cannot be forwarded directly — it would be rejected by the server's audience validation — so the console re-signs a new server-audience JWT from the validated `AuthResult`.  This preserves audit attribution (the upstream server sees the real user, not a service identity) and enforces scope narrowing as defense in depth (a read-only console user's proxied request carries only `read` scope).  The JWT `src` claim is set to `"console-proxy"` for audit traceability.  When no user context is available (auth disabled), the proxy falls back to a `ServiceTokenManager` with service identity `console-proxy`.  The static `--auth-token` / `proxy_auth_token` is used as a final fallback.

 ---

 ## Browser Dashboard

-The console uses an L-shaped application shell: a collapsible navigation rail,
-a tab bar, and a pane host. On mobile the rail becomes an off-canvas drawer.
-The rail is fed by the cluster SSE snapshot and shows:
+The web UI has five views, toggled client-side:

- state/count filters and the live compute-node list, including version drift;
- active coordinator and interactive workstreams, nested under their
-  coordinator parent and grouped by project when project metadata is visible;
- permission-filtered Manage groups that open the singleton Admin pane.
+### 1. Cluster Overview (landing)

-Coordinator and interactive conversations open as tabs inside the same shell.
-Interactive panes use the owning node's console proxy, so users do not need
-direct network access to compute-node ports. Split-right and split-down actions
-can display several panes at once. Closing a pane removes only that tab; use the
-pane menu's explicit close or delete action to change the workstream lifecycle.
+- **State cards** — 5 clickable cards (running, thinking, attention, idle, error) with count and colored top border. Clicking filters to that state.
+- **Aggregate bar** — total tokens and tool calls across the cluster.
+- **Node table** — columns: NODE, WS, RUN, ATTN, TOKENS, VER, LOAD. Sorted by activity. Clickable rows drill down to node detail. Version column shows per-node version; hidden on mobile.
+- **Version drift indicator** — when nodes report different versions, the status bar shows a yellow "DRIFT" warning with a tooltip listing all versions. Node groups show "mixed" with a yellow badge when their members disagree.
+- **"+ new" button** — opens the workstream creation modal (see below).

-### Dashboard pane
+### 2. Node Drill-down

-The home view is coordinator-first. It contains the persistent workstream
-launcher plus the saved-sessions list. Selecting a state count opens the
-filtered workstream table inside the same Dashboard pane; selecting a compute
-node opens its proxied node surface. Cluster SSE updates keep rail state,
-workstream rows, and tab state glyphs synchronized.
+Breadcrumb: `Cluster > db-west-04`. Shows the node's workstreams in a table matching the per-node dashboard layout (STATE, NAME, MODEL, NODE, TASK, TOKENS, CTX) with activity sub-lines. Includes a link to the node's proxied server UI.

-### Workstream launcher
+**Proxy deep-linking:** Clicking a workstream row opens the node's server UI in a new tab via the proxy at `/node/{node_id}/?ws_id=<id>`, which auto-selects that workstream. Users do not need direct network access to the server node.

-The landing-page composer starts a workstream with an optional initial task and
-attachments. When the caller can create both kinds, a Coordinator / Interactive
-toggle selects the target kind. Its options include:
+### 3. Filtered Workstreams

- **Node placement** — "Least loaded" picks the reachable node with the most
-  headroom, or "Specific node" pins the create to a node from the live list.
- **Persona** — optional dropdown listing the enabled personas for the workstream kind. Sets the system-message composition and capability envelope at creation, snapshotted server-side; empty uses the kind's default. Picking one requires no `persona.*` permission.
- **Skill** — optional dropdown listing enabled skills. Applies the skill's model, auto-approve policy, token budget, and other behavioral settings at creation time.
- **Project** — optional project filing. Private projects require owner/member access. A coordinator child inherits its parent's project unless explicitly routed to another attachable project.
+Breadcrumb: `Cluster > Running` or `Cluster > db-west-04`. Server-side paginated workstream table. NODE column values are clickable to filter further. Pagination controls at bottom. Workstream rows use proxy deep-links.
+
+### 4. Workstream Creation Modal
+
+Triggered by the "+ new" header button. A modal dialog with:
+
+- **Node selector** — dropdown with three targeting modes: "Auto (best available)" picks the node with the most headroom, "General pool (any node)" picks a node with available capacity using round-robin, or a specific node from the list (showing capacity).
+- **Profile** — optional dropdown listing enabled skills. Applies the skill's model, auto-approve policy, token budget, and other behavioral settings at creation time.
 - **Name** — optional text input. Auto-generated if left empty.
- **Model** — optional selector populated from the target model registry.
- **Judge Model** — optional selector for the judge alias (overrides the default
-  judge model for this workstream).
+- **Model** — optional text input for a model alias from the target node's registry.

-Interactive launches additionally expose node strategy / node selection.
-Submitting uses `POST /v1/api/cluster/workstreams/new`; coordinator launches use
-the console's coordinator create surface. A toast confirms the committed
-create, while SSE updates the dashboard and opens the resulting pane.
+On submit, `POST /v1/api/cluster/workstreams/new` dispatches the creation request. A toast confirms success; the SSE stream delivers the `ws_created` event to update the dashboard.

-Files require a non-empty initial task so the first turn consumes the staged
-attachments. The console shell does not currently expose a fork action; use the
-node's standalone workstream UI or the create API's `resume_ws` field.
+All five views receive live updates via SSE — state cards update counts, node rows update metrics, workstream rows update state indicators.

-### Large pasted text
+The browser maintains a local `clusterState` object that mirrors the cluster snapshot. It is initialized from the SSE `snapshot` event on connect (or via `GET /v1/api/cluster/snapshot` on initial page load) and updated incrementally by SSE events. View navigation reads from local state — no API round-trips needed after the initial snapshot.

-Browser composers turn plain text longer than 2,000 Unicode code points into a
-`text/plain` attachment named `pasted-text.txt`. A paste exactly at the
-threshold stays inline. This applies to the interactive and coordinator send
-boxes, the console home launcher, and the node dashboard and new-workstream
-composers.
-
-Clipboard files take priority over clipboard text. Text larger than the 512 KiB
-attachment ceiling also stays inline, so the browser does not discard it before
-a rejected upload. Attachments require a companion message and cannot be sent
-as live-turn interjections; a busy composer preserves its message and chips for
-an idle retry.
-
-### Saved and filtered sessions
-
-Saved coordinator and interactive sessions share one list with kind and persona
-labels, filtering, pagination, and multi-select deletion. Opening a saved
-coordinator rehydrates it in the console; opening a saved interactive session
-resolves its node, calls `open`, and then connects the node-proxied pane.
-
-The filtered live table carries STATE, NAME, MODEL, NODE, TASK, TOKENS, and CTX
-columns. The browser maintains a local `clusterState` initialized from the
-cluster snapshot and updated incrementally by SSE; the filtered view normally
-renders from that state without another API round trip.
-
-### Admin pane
+### 5. Admin Panel

 Accessed via the "admin" button in the header (visible when authenticated
 with `approve` scope). Provides user, API token, channel link, MCP server,
-and skill management with tabs that include Users, API Tokens, Channels,
-Schedules, Watches, Personas, Roles, Policies, Prompts, Judge, Skills,
-MCP Servers, Usage, Audit, Memories, Models, Nodes, Settings, and TLS.  See also
-[Governance](governance.md) for the Roles, Policies, Skills, Usage, and
-Audit tabs, and [Settings](settings.md) for the database-backed
-configuration editor.
-
-The **Channels** tab links users to either a Discord or Slack account
-via a per-row channel-type selector. The **Models** tab is a CRUD
-editor for `model_definitions`, including static and dynamic backend-auth
-modes and a per-process **Max concurrent generations** limit for each alias
-(`0` means unlimited). The limit is shared by every model-backed role using
-that alias and a streaming generation holds its slot through the full decode.
-Model edits rebind existing workstreams at their next send while
-in-flight requests keep their original definition snapshot; see
-[Settings](settings.md#model-definition-reloads) for the full contract. The **Nodes** tab edits per-node
-metadata, and the **TLS** tab manages CA and leaf certificates for the
-internal mTLS fabric.  The **Settings** tab edits ConfigStore values
-live; edits apply without restart.
+and skill management with 13 tabs (see also
+[Governance](governance.md) for
+the Roles, Policies, Skills, Usage, and Audit tabs, and
+[Settings](settings.md) for the database-backed configuration editor):

 **Users tab:**

@@ -572,7 +491,7 @@ Run history is automatically pruned (runs older than 90 days) approximately once
 | Mode | Behavior |
 |------|----------|
 | `auto` | Picks the reachable node with the most available capacity |
-| `pool` | Compatibility alias for the reachable node with the most headroom |
+| `pool` | Picks a reachable node with available capacity using round-robin |
 | `all` | Fan-out to all reachable nodes (capped at `max_fan_out`, default 20) |
 | `<node_id>` | Targets a specific node by ID |

@@ -732,7 +651,4 @@ turnstone-server --port 8080
 turnstone-console --port 8090
 ```

-Open `http://localhost:8090` for the cluster dashboard. Create workstreams from
-the persistent Dashboard launcher. Selecting a workstream opens a coordinator
-or node-proxied interactive pane in the console shell — no direct access to
-server ports is required.
+Open `http://localhost:8090` for the cluster dashboard. Create workstreams via the "+ new" button. Click any workstream to open the proxied server UI — no direct access to server ports required.
@@ -1,422 +0,0 @@
-# Coordinator API tour
-
-Turnstone's **coordinator workstream** is a session hosted on the
-console whose job is to orchestrate other workstreams.  It runs an LLM
-that can spawn child workstreams on any node, watch their progress,
-wait for them to finish, steer them mid-flight, and tear them down.
-This doc walks the full lifecycle — one request, one response, and the
-relevant SSE events at each step.
-
-Aimed at integrators driving a coordinator from a custom UI or SDK
-without reverse-engineering the built-in console page.  The shapes
-here match the live OpenAPI spec served at `/openapi.json` and
-rendered at `/docs` on every `turnstone-console` process.  Every
-step references the operation id from that spec so doc updates track
-schema changes.
-
-> **Auth throughout.**  Every endpoint below sits behind bearer-token
-> auth and the `admin.coordinator` permission.  A session-scoped JWT
-> is minted per login (see [docs/oidc.md](oidc.md) / [docs/security.md](security.md));
-> a service token may call the read paths but destructive governance
-> paths (`/restrict`, `/close_all_children`) require
-> the explicit `admin.coordinator` grant — a service-token owner
-> match isn't enough.
-
---
-
-## The 9 steps
-
-> **URL convergence (1.5.0).** Pre-1.5 coord-only endpoints lived
-> under `/v1/api/coordinator/...`. The Stage 2 verb-shape lift
-> consolidated coord and interactive onto the unified
-> `/v1/api/workstreams/{ws_id}/<verb>` tree; coord still distinguishes
-> itself via the `kind=coordinator` row classifier rather than a
-> separate URL space. The endpoints below reflect the post-lift
-> surface served by `turnstone-console`.
-
-| # | Action                       | Operation                                                   |
-|---|------------------------------|-------------------------------------------------------------|
-| 1 | Create                       | `POST /v1/api/workstreams/new`                              |
-| 2 | Bootstrap history + subscribe | `GET .../history`, then `GET .../events` (SSE)             |
-| 3 | Send a user message          | `POST /v1/api/workstreams/{ws_id}/send`                     |
-| 4 | Inspect children             | `GET /v1/api/workstreams/{ws_id}/children`                  |
-| 5 | Inspect one workstream       | `GET /v1/api/cluster/ws/{ws_id}/detail`                     |
-| 6 | Wait for fan-out             | model-side tool `wait_for_workstream`                       |
-| 7 | Govern                       | `POST /v1/api/workstreams/{ws_id}/trust`                    |
-|   |                              | `POST /v1/api/workstreams/{ws_id}/restrict`                 |
-|   |                              | `POST /v1/api/workstreams/{ws_id}/close_all_children`       |
-| 8 | Approve / cancel             | `POST /v1/api/workstreams/{ws_id}/approve`                  |
-|   |                              | `POST /v1/api/workstreams/{ws_id}/cancel`                   |
-| 9 | Close                        | `POST /v1/api/workstreams/{ws_id}/close`                    |
-
-Refer to `/openapi.json` (Swagger UI at `/docs`) on any
-`turnstone-console` process for the authoritative operation ids and
-schemas. Coordinator-only verbs (`/children`, `/trust`, `/restrict`,
-`/close_all_children`) 404 against `kind=interactive`
-rows; the shared verbs (`/send`, `/approve`, `/cancel`, `/events`,
-`/history`, `/open`, `/close`, etc.) work on both kinds.
-
---
-
-## 1. Create a coordinator
-
-```http
-POST /v1/api/workstreams/new
-Content-Type: application/json
-Authorization: Bearer <token>
-
-{
-  "name": "release-coord",
-  "skill": "engineer-orchestrator",
-  "initial_message": "audit /auth for CSRF handling across all active routes"
-}
-```
-
-```http
-HTTP/1.1 201 Created
-Content-Type: application/json
-
-{"ws_id": "a1b2c3d4e5f6...", "name": "release-coord"}
-```
-
-All three body fields are optional — an empty body still creates a
-coordinator with an auto-generated name and no initial message.
-Returns **503** with a remediation message when the cluster isn't
-configured with a coordinator model; see
-[`coordinator.model_alias`](settings.md) to set one.
-
-**SSE implication:** the `ws_created` event fires on the cluster-wide
-stream (`/v1/api/cluster/events`) once the row is committed.  Per-ws
-subscribers (step 2) see the session warm up as token traffic starts.
-
---
-
-## 2. Bootstrap history, then subscribe to the event stream
-
-Read and render history before opening the initial stream:
-
-```http
-GET /v1/api/workstreams/{ws_id}/history?limit=100 HTTP/1.1
-Authorization: Bearer <token>
-```
-
-For a loaded coordinator, `messages` is the requested tail of one total
-accepted conversation-row prefix: user, assistant, tool, and system rows,
-including projected compaction checkpoints and cancellation-generated markers.
-The response's optional `cursor` and `handoff_token` belong to that exact
-render. Pass both once on the initial stream URL:
-
-```http
-GET /v1/api/workstreams/{ws_id}/events?last_event_id={cursor}&history_token={handoff_token}&user_turn=1&tool_turn=1 HTTP/1.1
-Accept: text/event-stream
-Authorization: Bearer <token>
-```
-
-Omit either query parameter when its history field is `null`. A handoff token
-is opaque and process-local: do not parse, persist, or reuse it. Admission of a
-later conversation row changes the token; durable acknowledgement does not. If
-history returns `503 {"error":"History temporarily unavailable"}`, the response
-is not authoritative: retain the current transcript, do not open a tokenless
-replacement stream, and retry the read.
-
-One persistent SSE connection per browser tab / SDK caller — the
-console fans each event out to every listener queue (cap 500 events
-per queue, put_nowait drop on overflow).  Events come in flat JSON
-with a `type` field.  The recurring shapes a UI has to handle:
-
-| `type`              | Emitted when                                                                               | Payload highlights |
-|---------------------|--------------------------------------------------------------------------------------------|--------------------|
-| `thinking_start` / `thinking_stop` | Model has entered / exited a reasoning block                                | — |
-| `reasoning`         | Reasoning-token stream chunk (when the model exposes it)                                   | `text` |
-| `content`           | Assistant-content stream chunk                                                             | `text` |
-| `stream_end`        | End of a single provider stream                                                            | — |
-| `tool_result`       | A tool call completed; capable panes also receive the accepted-history replacement          | `call_id`, `name`, `output`, `is_error?`, `accepted?`, `_event_id?`, `preview?`, `effect_status?` |
-| `tool_output_chunk` | Streaming tool output (e.g. long bash command)                                             | `call_id`, `chunk` |
-| `approve_request`   | One approval cycle needs operator action; several cycles may coexist                       | `cycle_id`, `items: [{call_id, header, preview, func_name, approval_label, needs_approval}]` |
-| `approval_resolved` | One identified approval cycle was answered                                                 | `cycle_id`, `call_ids`, `approved`, `feedback`, `always` |
-| `state_change`      | Worker-thread state transition (also re-emitted with the current state on every fresh subscribe so refresh-mid-stream restores composer mode) | `state` ∈ `running`, `thinking`, `attention`, `idle`, `error` |
-| `in_progress_snapshot` | One-shot replay of the in-progress turn's content + reasoning when this client connects mid-stream                              | `content`, `reasoning` |
-| `status`            | Token usage + context-window snapshot (fires on every streaming tick)                      | `prompt_tokens`, `completion_tokens`, `total_tokens`, `context_window`, `pct`, `effort`, `cache_creation_tokens`, `cache_read_tokens` |
-| `rename`            | Session's display name changed                                                             | `name` |
-| `intent_verdict`    | Intent judge produced a verdict on a pending tool call                                     | `risk_level`, `recommendation`, `reasons` |
-| `output_warning`    | Output guard flagged a tool result                                                         | `call_id`, `risk_level`, `flags` |
-| `child_ws_created`  | A direct child of this coord was just created (fan-out from the cluster bus)              | `child_ws_id`, `node_id`, `name`, `parent_ws_id` (`ws_id` in the envelope is always the coord's own id) |
-| `child_ws_state`    | A direct child transitioned state                                                          | `child_ws_id`, `state` |
-| `child_ws_closed`   | A direct child closed                                                                      | `child_ws_id` |
-| `child_ws_rename`   | A direct child's name changed                                                              | `child_ws_id`, `name` |
-| `wait_started` / `wait_progress` / `wait_ended` | `wait_for_workstream` tool lifecycle (see §6)                  | `call_id`, `ws_ids`, `elapsed`, `results`, `complete` |
-| `batch_started` / `batch_ended` | `spawn_batch` / `close_all_children` tool lifecycle                            | `call_id`, `op`, `total`/`succeeded`/`denied`/`closed`/`failed`/`skipped` |
-| `info` / `error`    | Operational messages                                                                       | `message` |
-| `history_resync`    | The rendered history token no longer names the accepted row prefix                         | `ws_id`, `reason` |
-
-**Reconnection contract:** a freshly-opened SSE connection receives
-one `approve_request` snapshot for every unresolved approval cycle, keyed by
-the same stable `cycle_id`, plus any in-flight `wait_*` / `batch_*`
-indicator, the worker's current `state_change`, and an
-`in_progress_snapshot` carrying any partial content / reasoning the
-model has produced for the in-progress turn — so a tab refresh
-mid-approval, mid-tool-execution, or mid-stream restores both the
-correct composer mode and the partial assistant text without waiting
-for the response to complete.
-
-`history_resync` is stronger than a numeric replay gap. The server closes that
-stream; fetch and render `/history` again, then open a new stream with its new
-cursor/token pair. The API and SDK expose these primitives but deliberately do
-not choose a reconnect policy for callers.
-
---
-
-## 3. Send the first user message
-
-```http
-POST /v1/api/workstreams/{ws_id}/send
-Content-Type: application/json
-
-{"message": "audit /auth for CSRF handling across all active routes"}
-```
-
-```http
-HTTP/1.1 200 OK
-{"status": "ok"}
-```
-
-The message is queued for the worker thread at its next tool-result
-seam (so you can send follow-ups mid-conversation without corrupting
-the in-progress turn).  On the SSE stream you'll see `state_change`
-→ `thinking_start` → streaming `reasoning` / `content` / `tool_result`
-events, finishing with `state_change → idle` or an
-`approve_request` when the model invokes a gated tool.
-
---
-
-## 4. Inspect direct children
-
-```http
-GET /v1/api/workstreams/{ws_id}/children HTTP/1.1
-```
-
-```json
-{
-  "items": [
-    {"ws_id": "d4e5f6...", "name": "csrf-audit", "state": "running", "node_id": "gpu-3"},
-    {"ws_id": "e1f2a3...", "name": "xss-audit",  "state": "idle",    "node_id": "gpu-1"}
-  ],
-  "truncated": false
-}
-```
-
-The response key is `items`, not `children` — the endpoint shape
-follows the cluster-wide workstream-list idiom rather than the
-coordinator `list_workstreams` tool's (which uses `children`).
-Rows include every state stored for the parent (`running`, `idle`,
-`closed`, ...); the endpoint does not accept a state query param,
-so clients should inspect each row's `state` field and filter
-locally if they want to hide closed/deleted children.  Nested
-coordinator rows are dropped server-side so only interactive
-descendants appear.
-
---
-
-## 5. Inspect one workstream (storage + live block + tail)
-
-```http
-GET /v1/api/cluster/ws/{ws_id}/detail?message_limit=20 HTTP/1.1
-```
-
-```json
-{
-  "persisted": { "ws_id": "...", "state": "running", "parent_ws_id": "...", "kind": "interactive", ... },
-  "live":      { "state": "thinking", "tokens": 12843, "activity": "...", "pending_approval": null },
-  "tail":      [ {"role": "assistant", "content": "...", "tokens": 128}, ... ]
-}
-```
-
-Works for any workstream the caller has `admin.cluster.inspect` on,
-not just children of a single coordinator — useful for a cluster
-admin panel watching multiple coordinators at once.  `live` is
-`null` when the owning node is unreachable or has dropped the row
-from its dashboard cache; callers should degrade gracefully, not
-treat it as an error.
-
-For fan-out views, prefer
-[`GET /v1/api/cluster/ws/live?ids=a,b,c`](bulk-endpoints.md) — it
-collapses N per-row round-trips into one, returning the live block
-for every id in a `{results, denied, truncated}` envelope.
-
---
-
-## 6. Wait for fan-out (`wait_for_workstream`)
-
-`wait_for_workstream` is a **model-side tool**, not an HTTP endpoint
-— the coordinator's LLM invokes it with a list of child ws_ids, the
-session's worker thread blocks inside the tool, and a sequence of
-`wait_started` / `wait_progress` / `wait_ended` SSE events is emitted
-for the UI to drive a "waiting on N children" indicator.
-
-![wait_for_workstream sequence](diagrams/png/27-coordinator-wait-for-workstream.png)
-
-Key properties:
-
- **Caps** — up to 32 ws_ids per call, up to 600 seconds per call.
-  A coordinator that needs to wait on more children re-invokes the
-  tool with a fresh timeout.
- **Modes** — `mode="any"` returns as soon as one child reaches a
-  real terminal state (`idle` / `error` / `closed` / `deleted`);
-  `mode="all"` waits for every polled child to reach a real
-  terminal state.
- **Progress throttling** — the poll loop runs every 500 ms but the
-  SSE emission is diff-on-state-change plus a 5-second heartbeat.  A
-  600 s wait generates O(dozens) of progress events, not 1200.
- **Unresolvable ids** — ws_ids are validated up front (exactly
-  32 hex chars; copy them verbatim): a malformed id fails the call
-  immediately with did-you-mean suggestions and a roster of the
-  coord's children.  An id the caller doesn't own, a missing row, or
-  a child hard-deleted mid-wait is reported as `state="not_found"`
-  and aborts the wait on the tick that observes it (top-level
-  `error` / `not_found` / `children` fields, `complete=false`) — the
-  LLM should fix the id and re-issue, not conclude the child died.
-  Foreign and missing collapse into one shape, so the wait can't be
-  used as an existence oracle.
-
-Prefer `wait_for_workstream` over polling `inspect_workstream` in a
-loop — a wait consumes one assistant turn regardless of how long the
-children take, whereas each `inspect_workstream` poll costs a full
-turn (plus judge, plus tokens).  On a fan-out of 3+ children this
-rounds to a 10× token-efficiency win.
-
---
-
-## 7. Governance — trust, restrict, close_all_children
-
-These three endpoints let an operator steer a live coordinator session
-mid-flight.  All three emit an audit event tagged
-`coordinator.<action>` via the dedicated audit executor so a cascade
-burst can't starve audit writes.
-
-### `POST /trust` — auto-approve own-subtree sends
-
-```http
-POST /v1/api/workstreams/{ws_id}/trust
-{"send": true}
-```
-
-Flips `trust_send=true` on the live session.  Subsequent
-`send_to_workstream` calls that target a ws_id in the coordinator's
-own subtree skip the approval prompt; foreign ws_ids and other tool
-calls still go through the normal flow.  Requires both
-`admin.coordinator` AND `coordinator.trust.send` permissions (the
-second grants a service token the opt-in it otherwise wouldn't get).
-
-### `POST /restrict` — revoke tool access mid-session
-
-```http
-POST /v1/api/workstreams/{ws_id}/restrict
-{"revoke": ["spawn_workstream", "delete_workstream"]}
-```
-
-Unions the names into the session's revoked-tools set.  Additive and
-idempotent — calling twice with overlapping lists converges to the
-union.  Revocations don't survive a session close/reopen; operators
-opt in per session.  Cap 256 tool names per request, 128 chars each.
-
-### `POST /close_all_children` — soft-close the direct fan-out
-
-```http
-POST /v1/api/workstreams/{ws_id}/close_all_children
-{"reason": "audit round complete"}
-```
-
-Response:
-
-```json
-{"status": "ok", "closed": ["c-1", "c-2"], "failed": [], "skipped": []}
-```
-
-Soft-close cascade bounded by a concurrency semaphore.  The `reason`
-(up to 512 chars) propagates into each closed child's audit +
-`workstream_config` for postmortem.  The model-facing tool that
-pairs with this endpoint asks for a bounded teardown of the
-coordinator's own fan-out.  This *soft-closes*; to *cancel* the
-fan-out instead, cancel the coordinator (§8) — a coordinator cancel
-auto-cascades to its direct children.
-
-See [bulk-endpoints.md](bulk-endpoints.md) for why `close_all_children`
-uses the cascade-mutation shape and how it differs from the
-`spawn_batch` / `cluster/ws/live` shape.
-
---
-
-## 8. Approve / cancel
-
-The `approve` endpoint is what resolves an `approve_request` SSE
-event.  The coordinator's worker thread is blocked inside
-`ui.approve_tools` waiting for this POST. Parallel task agents can leave
-several approval cycles live at once, so current clients echo the event's
-`cycle_id` (or a member `call_id`). A selector-less request resolves the oldest
-cycle for compatibility.
-
-```http
-POST /v1/api/workstreams/{ws_id}/approve
-{"approved": true, "feedback": null, "always": false, "cycle_id": "cycle_789"}
-{"approved": false, "feedback": "spawn count looks too high — try 3 not 10"}
-{"approved": true, "feedback": null, "always": true}    // remember this cycle's tool names
-```
-
-Success returns `{"status": "ok", "cycle_id": "cycle_789"}`. A stale selector
-returns `409` with the currently oldest cycle/call IDs. `always` remembers only
-the tool names in the cycle that actually resolved; it does not enable blanket
-approval.
-
-`cancel` requests cooperative cancellation of the coordinator's in-flight
-generation and auto-cascades to its direct children:
-`cancel_workstream` is dispatched through the routing proxy for
-every direct child in the registry. The HTTP acknowledgement is immediate;
-the worker becomes idle after unwinding. Pass `{"force": true}` only to release
-a wedged worker slot immediately. The coordinator itself remains open for a
-fresh `send`:
-
-```http
-POST /v1/api/workstreams/{ws_id}/cancel
-{}
-{"status": "ok", "dropped": {}}
-```
-
---
-
-## 9. Close
-
-```http
-POST /v1/api/workstreams/{ws_id}/close
-{}
-```
-
-Soft-closes the session — state persists, children keep running
-(wind them down first with `close_all_children`, or by cancelling
-the coordinator, which cascades the cancel to its direct children),
-the worker thread exits, SSE streams send a final `stream_end` and
-disconnect.  The row is reopenable via
-`POST /v1/api/workstreams/{ws_id}/open` so long as it hasn't been
-deleted.
-
-If any accepted live conversation row still requires persistence
-reconciliation, close returns `409 {"error":"workstream has unresolved
-persistence"}`. The coordinator remains loaded, its journal is retained, and
-no history is discarded; retry after storage recovers.
-
---
-
-## Further reading
-
- [coordinator-skills.md](coordinator-skills.md) — writing a skill
-  that runs on a coordinator session (orchestrator framing,
-  workflow patterns, `SkillKind` classifier).
- [bulk-endpoints.md](bulk-endpoints.md) — the two bulk-shape
-  idioms (`{results, denied, truncated}` vs
-  `{<bucket>, failed, skipped}`) used by `cluster/ws/live`,
-  `spawn_batch`, and `close_all_children`.
- [architecture.md](architecture.md) — cluster-wide architecture
-  including how coordinator sessions fit next to node-hosted
-  interactive workstreams.
- The live OpenAPI spec (`/openapi.json` on any console process)
-  and Swagger UI (`/docs`) — authoritative schemas for every
-  endpoint above.
@@ -1,368 +0,0 @@
-# Writing a coordinator-specific skill
-
-A skill is prompt-level framing that steers a Turnstone session
-toward a narrow task.  Most skills target **interactive** sessions —
-the single-workstream "do this thing" surface where the model wields
-`bash`, `edit_file`, `web_fetch`, and the rest of the maker toolset.
-
-A **coordinator skill** is different.  It runs on a session whose job
-is to orchestrate other sessions.  The toolset is smaller and
-narrower, the role is an orchestrator instead of a maker, and the
-success metric is "did the plan resolve" instead of "did the code
-compile".  This doc covers the differences a skill author has to
-care about.
-
---
-
-## `kind` — authored audience metadata
-
-A row in `prompt_templates` carries a `kind` column (see
-[`turnstone/core/skill_kind.py`](../turnstone/core/skill_kind.py);
-migration 044 added the column).  Three values:
-
-| `SkillKind` enum        | Stored as       | Meaning                                                                    |
-|-------------------------|-----------------|----------------------------------------------------------------------------|
-| `SkillKind.INTERACTIVE` | `"interactive"` | Authored for the interactive maker role (single-workstream "do this"). |
-| `SkillKind.COORDINATOR` | `"coordinator"` | Authored for the orchestrator role (delegate, monitor, synthesise).    |
-| `SkillKind.ANY`         | `"any"`         | Either surface (or audience-neutral).  Default on create.                 |
-
-The `kind` field is a `StrEnum` — drop-in `str` compatible — so DB
-rows, JSON payloads, and `==` comparisons all work without translation
-at the edge.
-
-**`kind` is metadata, not an enforcement boundary.**  The model can
-`skills(action='find')` across every kind from any session, `get` any
-row by name, and `load` any visible skill regardless of session kind.
-Actual runtime capability is gated by `allowed_tools` + `auto_approve`
-on the skill and the operator's approval card on every `load` /
-`spawn_workstream(skill=...)` decision — `kind` doesn't add or remove
-any of that.  It's a sorting / grouping / search-narrowing hint.
-
-The opt-in filter is on `skills(action='find', kind='coordinator')`
-(or `'interactive'`) — pass it when you want to narrow a catalog
-browse to a specific authored audience.  Omitting it (or passing
-`kind='any'`) returns the full catalog.  When supplied, the storage
-filter widens to `[<kind>, 'any']` so audience-neutral rows remain
-visible inside the narrowed view.
-
-**Tagging a new skill as coordinator-targeted** — set `kind` to
-`SkillKind.COORDINATOR` (or the literal `"coordinator"`) when you
-`skills(action='create', kind='coordinator', ...)` or POST to
-`/v1/api/admin/skills`.  Use this to signal intent to other skill
-authors and to make the orchestrator-targeted catalog easy to
-browse — not to hide the skill from interactive sessions.  Existing
-rows default to `SkillKind.ANY`; bump them to `COORDINATOR` if
-you've rewritten the prompt around the orchestrator toolset and
-want the kind filter to surface them as such.
-
---
-
-## Tool surface differences
-
-Coordinator sessions receive a **fixed** tool set, defined in
-`turnstone/core/tools.py` as `COORDINATOR_TOOLS`.  Nothing a skill
-or MCP config can do adds to it.  Current members:
-
-| Tool                      | Category        | Notes                                                               |
-|---------------------------|-----------------|---------------------------------------------------------------------|
-| `spawn_workstream`        | delegate        | Create one child.  Requires approval.                               |
-| `spawn_batch`              | delegate        | Create up to 10 children in one approval.  Partial-success shape.   |
-| `inspect_workstream`      | observe         | Read state + tail of one child.  Auto-approved (no mutation).       |
-| `list_workstreams`        | observe         | List the direct children (same shape as `/children` endpoint).      |
-| `wait_for_workstream`     | block           | Block until one/all listed children hit a terminal state.           |
-| `send_to_workstream`      | steer           | Queue a follow-up message to a running child.                        |
-| `close_workstream`        | wind-down       | Soft-close one child.  Requires approval.                           |
-| `close_all_children`      | wind-down       | Soft-close every direct child in one approval.  Partial-success shape. |
-| `cancel_workstream`       | wind-down       | Drop the in-flight generation; leaves child idle for a fresh send.  |
-| `delete_workstream`       | wind-down       | Hard-delete one child.  Requires approval.                          |
-| `list_nodes`              | discover        | Enumerate live cluster nodes + capabilities.                        |
-| `skills` (action=find)    | discover        | Browse the skill catalog; opt-in `kind` filter narrows by audience. |
-| `memory`                  | persist         | Durable acting-user orchestration memory (`coordinator`), plus shared memory when attached to a project. |
-| `notify`                  | broadcast       | Post a status update to a human channel at a narrative beat.        |
-| `tasks`                   | plan            | Orchestrator-only scratchpad.  Children don't see it.               |
-
-Explicitly **not** in the coordinator set:
-
- `bash` / `edit_file` / `write_file` / `append_file` / `diff_file` — no local FS.
- `read_file` / `search` — no local FS reads.
- `web_fetch` / `web_search` — no direct web access.
- `task_agent` — sub-agent tool is zeroed on coord sessions.
- `recall` / `watch` / `read_resource` / `use_prompt` — UX / persistence tools that belong to interactive sessions.  The dual-kind `memory` / `skills` / `notify` tools are available on both kinds (see the table above).
-
-If your skill needs a coordinator to "run a command" or "read a
-file", write the delegate pattern instead: spawn a child with an
-appropriate skill, `wait_for_workstream`, then `inspect_workstream`
-for the output.  The coordinator stays the orchestrator.
-
---
-
-## Framing differences
-
-Interactive skills compose on top of `base_interactive.md` — a
-"maker" framing: get the work done, use the tools, edit the code,
-close the loop.
-
-Coordinator skills compose on top of
-[`personas/orchestrator.md`](../turnstone/prompts/personas/orchestrator.md) —
-an "orchestrator" framing: decompose, delegate, monitor, synthesise.
-The base text is short but sets the tone every coordinator skill
-inherits:
-
-> You are a coordinator.  Your role is to orchestrate work across
-> the cluster...  You do
-> not edit files, run shell commands, browse the web, or manipulate
-> the codebase directly.  Children do that.
-
-Write your skill's system prompt to *add* task-specific orchestration
-hints on top — don't re-explain the role, don't paste tool JSON,
-don't try to override the "no direct action" contract.  Keep the
-additions to: (a) the specific kind of work this skill delegates;
-(b) the preferred skill tags for children; (c) the synthesis shape
-the skill should end on.
-
---
-
-## `tasks` integration
-
-`tasks` is the coordinator's scratchpad — a persisted, ordered
-list of rows with fields `{id, title, status, child_ws_id, created,
-updated}`, plus `note` on rows where one has been set (the key is
-absent otherwise), that only this coordinator sees.  Children don't
-see it; the user does via the sidebar.  Five actions: `add`,
-`update`, `remove`, `reorder`, `list` (only `list` is auto-approved;
-the mutators go through the approval flow).
-
-The input schema refers to rows by `task_id`; the persisted row
-object exposes the same id as `id`.  The `child_ws_id` field is a
-free-form label the skill sets to link a task to a spawned
-workstream — it is NOT validated against the workstreams table, so
-a skill can set it to a placeholder before `spawn_workstream`
-returns or keep it pointing at a closed child for later audit.
-
-A skill's initial prompt can seed the task list by calling
-`tasks(action="add", title=...)` as its very first tool calls —
-the user gets a visible plan before any child is spawned, and the
-coordinator's future self has something concrete to iterate on.
-Status transitions (`pending` → `in_progress` → `done` / `blocked` /
-`needs_user`) are the skill's main feedback loop: mutate the task
-when the child covering it finishes, not when the child starts.
-`blocked` and `needs_user` are not interchangeable — `blocked` is a
-dependency the coordinator may be able to clear itself, while
-`needs_user` marks a task that cannot move without a decision,
-approval, or grant only the user can give.  The distinction is
-load-bearing: a coordinator that goes idle holding open tasks gets
-nudged to pick them back up — even when children are still running, so
-keep the matrix honest rather than expecting the reminder to wait for
-an all-clear — and `needs_user` is what tells that nudge the stop was
-deliberate.  Pair it with `note` to record what is being asked for.
-Use `tasks(action="update", task_id=..., child_ws_id=<ws_id>)` to link
-a task to the child that owns it once spawn returns.
-
-A final gotcha: parallel tool dispatch does NOT serialise reads
-after writes in the same batch.  If a skill issues an `update` and
-a `list` in one parallel tool batch, the `list` response may reflect
-the pre-update state.  Dispatch mutate and list serially (one
-tool_use turn each) when the list must observe the mutation.
-
-Keep the tasks coarse-grained — one per child, roughly.  A 20-task
-list for a 3-child fan-out is noise; a 1-task list for a 5-child
-fan-out loses the plan.  The sidebar renders tasks as the operator's
-mental model of "what the coord thinks it's doing".
-
---
-
-## Referencing children by `ws_id`
-
-Every ws_id returned by `spawn_workstream` / `spawn_batch` is a
-**full 32-char hex string**.  The skill's system prompt must not
-invent ws_ids — a model that hallucinates `"child-1"` or `"ws-abc"`
-hits the tenant guard in `CoordinatorClient._is_own_subtree`, which
-validates ws_id against `parent_ws_id=coord_ws_id` AND
-`user_id=owner` in storage.  The rejection shape is uniform and
-recovery-oriented:
-
- **Mutating ops** (`send_to_workstream`, `close_workstream`,
-  `cancel_workstream`, `delete_workstream`) and
-  **`inspect_workstream`** return
-  `{"error": "no workstream matching '<ref>' among your children; …",
-  "status": 404, "ws_id": "<ref>", "did_you_mean": [...],
-  "children": [...], "children_truncated": bool}` — a did-you-mean
-  (edit distance ≤ 3 against the coord's own children, which catches
-  the garbled-hex incident class: a 32-char id whose `aaa` run
-  collapsed to `a`) plus a roster of the coord's children.  A ref
-  that matches a child's display NAME is called out explicitly with
-  the right id (names are mutable labels, not addresses).  Foreign
-  and nonexistent ids produce the same payload (no existence
-  oracle), every hint references only the coord's own children, and
-  near-miss ids are never auto-resolved — the skill should fix the
-  id and re-issue, not treat the child as dead.
- **`wait_for_workstream`** validates ids before waiting: a
-  malformed id fails the whole call immediately (`invalid_ws_ids`
-  carries the per-id payloads above, `elapsed=0`); a well-formed id
-  that is foreign, nonexistent, or hard-deleted mid-wait surfaces as
-  `state="not_found"` and aborts the wait on that tick with
-  top-level `error` / `not_found` / `children` fields.
-  `complete=true` therefore means every polled lane really finished
-  — an unobservable id can neither burn the timeout nor ride along
-  to a "complete" result.
-
-Pattern: capture each spawn result in the next tool call's input.
-The JSON tool-result carries `{"child_ws_id": "...", "name": "...",
-"node_id": "...", "routing_strategy": "..."}`; the model should
-extract the `child_ws_id` and pass it as `ws_id` (or in the `ws_ids`
-list) to `inspect_workstream` / `wait_for_workstream` /
-`send_to_workstream` / `close_workstream` verbatim.  The asymmetry
-— spawn returns `child_ws_id` but the other tools accept `ws_id` /
-`ws_ids` — is intentional: it defuses a coordinator-LLM recency
-bias where seeing `ws_id` in a spawn return primed re-spawn loops
-instead of progression to the wait phase.
-
-A UI that wants human-readable identifiers should render the `name`
-field and keep the workstream id as the click-through key — note
-that the id *value* is the same regardless of whether it arrived
-under the `child_ws_id` key (spawn return) or the `ws_id` key
-(every other tool's input/output); only the field name differs.
-
---
-
-## `wait_for_workstream` vs `inspect_workstream`
-
-Two distinct semantics, different cost profiles:
-
- **`wait_for_workstream(ws_ids=[...], timeout=60, mode="any")`** —
-  blocks inside a single tool call until one (or all, for `mode="all"`)
-  of the listed children reaches a terminal state (`idle`, `error`,
-  `closed`, `deleted`).  The worker thread blocks up to `timeout`
-  seconds; the assistant turn remains a single round-trip regardless
-  of how long the wait actually takes.  Prefer this for "the plan
-  needs child X to finish before the next step."
- **`inspect_workstream(ws_id=...)`** — single read of the child's
-  state + tail.  Costs a full assistant turn (judge, tokens, stream).
-  Prefer this for "what does the final message say?" after the child
-  has already resolved (via `wait_for_workstream` or a known
-  transition).
-
-Rule of thumb: wait once for a fan-out, then inspect once per
-child for the content.  A loop of inspect-every-few-seconds is a
-token-burning antipattern — on 3+ children it rounds to a 10×
-efficiency hit over a wait+inspect pair.
-
---
-
-## Common coordinator patterns
-
-Three patterns cover most coordinator skills.  Pick the one that
-matches the task, or combine them deliberately.
-
-### Pattern 1 — delegate-and-summarise
-
-One specialist child, one focused brief, one synthesis message back
-to the user.  Appropriate when the user's request is "run the thing
-and tell me what happened" and the work fits in one workstream.
-
-```
-tasks(action='add', title='audit /auth for CSRF')
-spawn_workstream(skill='engineer', initial_message='audit /auth ...')
-wait_for_workstream(ws_ids=[<child>], timeout=300)
-inspect_workstream(ws_id=<child>)
-→ synthesise the final message into a user-facing response
-tasks(action='update', task_id='t_01', status='done')
-close_workstream(ws_id=<child>, reason='audit complete')
-```
-
-### Pattern 2 — fan-out-and-synthesise
-
-N children running in parallel, each with a distinct brief, all
-waited-on together, then synthesised.  Appropriate when the user's
-request naturally decomposes into independent subtasks.
-
-```
-tasks seeds:
-  t_01 benchmark Anthropic 4.7 latency on summarisation
-  t_02 benchmark OpenAI GPT-5.2 latency on summarisation
-  t_03 benchmark Gemini 2.5 latency on summarisation
-spawn_batch(children=[...3 briefs...])
-wait_for_workstream(ws_ids=[c1, c2, c3], mode='all', timeout=600)
-inspect_workstream(ws_id=c1); ...(c2); ...(c3)
-→ synthesise head-to-head comparison
-tasks → all done
-close_all_children(reason='benchmark complete')
-```
-
-Prefer `spawn_batch` over 3 individual `spawn_workstream` calls —
-one approval instead of three, one audit trail, deterministic
-sibling ordering.  Pair with `wait_for_workstream(mode='all')` and
-`close_all_children(reason=...)` to wind the fan-out down in one
-approval each.
-
-### Pattern 3 — plan-then-delegate
-
-The coordinator first uses its own reasoning to carve the plan,
-records it in `tasks`, then spawns children that each own one
-task.  Appropriate when the user's request is "figure out how to X"
-and the coordinator's planning step is itself valuable.
-
-```
-→ coord reasons about the shape of the work
-tasks(action='add', title='...') × N   # the plan, visible in the sidebar
-for task in tasks:
-    spawn_workstream(skill=..., initial_message=task.brief)
-    tasks(action='update', task_id=task.id, note='ws=<child_ws_id>')
-wait_for_workstream(ws_ids=[...], mode='all', timeout=...)
-for child in children:
-    inspect_workstream(ws_id=child)
-    tasks(action='update', task_id=..., status='done', note='result summary')
-→ synthesise
-```
-
-The key distinction from Pattern 2: the plan is an artifact the user
-can see and interact with (via the sidebar).  If the coordinator's
-reasoning-pass was wrong about the decomposition, the user can
-course-correct before any child runs.
-
---
-
-## Testing a coordinator skill
-
-Coordinator sessions are hosted on the console, not on a node.
-Integration tests that drive a real coord session live under
-`tests/test_coordinator_end_to_end.py` — they spin a console with
-an in-memory SQLite backend and a fake upstream node, then drive
-the session through its HTTP surface.
-
-For a new coordinator skill:
-
-1. Write the skill prompt as a string and pass it to the
-   `coord_session` fixture's `skill=` kwarg (see
-   `tests/test_coordinator_tools.py` for the pattern).
-2. Build a small fake cluster: one node + two children via
-   the `_seed_children` helper in `tests/_coord_test_helpers.py`
-   (``_seed_children(mgr._adapter, coord.id, ["child-1", "child-2"])``).
-3. Drive the session with seeded tool_call dicts matching the
-   provider layer's shape.  The unit-level tests in
-   `tests/test_coordinator_tools.py` show the helper (`_tc(name,
-   args, call_id)`).
-4. Assert the skill's decision shape — which tools fire in what
-   order, what the tasks looks like at the end, which
-   `_error` reasons appear on the denied-path.
-
-A full end-to-end test isn't required for every skill; a
-prepare-step unit test that asserts "given this initial message, the
-first tool call is X with Y args" is usually sufficient to catch
-framing drift without a real LLM in the loop.
-
---
-
-## Further reading
-
- [coordinator-api-tour.md](coordinator-api-tour.md) — the HTTP
-  surface every coordinator skill indirectly drives.
- [bulk-endpoints.md](bulk-endpoints.md) — the response shape
-  `spawn_batch` and `close_all_children` use, so your skill can
-  parse results / denied arrays correctly.
- [governance.md](governance.md) — the broader governance surface
-  (`/trust`, `/restrict`, role-based permissions)
-  that wraps every coord session.
- [settings.md](settings.md) — `coordinator.model_alias` and
-  `coordinator.reasoning_effort` settings that gate which LLM runs
-  the coordinator session at all.
@@ -1,27 +1,34 @@
 # Consistent Hash Ring — Reference Design

-**Status**: Reference — alternative routing strategy
+**Status**: Reference (not currently in the hot path)
+**Date**: 2026-03-30

-Live routing uses **rendezvous (HRW) hashing** in
-`turnstone/core/rendezvous.py` and `turnstone/console/router.py`.  This
-document captures a vnode-ring approach as a reference for future
-evaluation if the cluster outgrows rendezvous's O(N)-per-route
-characteristic.
+## Overview

-The FNV-1a-32 hash function specified below is bit-identical to the
-hash used by the live rendezvous implementation; cross-language clients
-can rely on these test vectors.
+This document describes a consistent hash ring algorithm evaluated during
+the design of the direct HTTP transport routing system. The current
+implementation uses weight-proportional bucket assignment with a
+donor/recipient rebalancing algorithm (see `direct-http-transport.md`).
+The consistent hash ring is documented here as a reference for future
+scalability work — if the cluster grows beyond the point where the
+weight-proportional approach is sufficient, the ring provides a
+proven alternative with stronger stability guarantees.

-## When the ring approach becomes interesting
+## When to consider the ring approach

-The vnode ring becomes preferable to rendezvous hashing when:
+The current weight-proportional seeding + donor/recipient rebalancer works
+well when:
+- Cluster size is moderate (< 50 nodes)
+- Nodes join/leave infrequently
+- The rebalancer runs centrally (in the console)

- Cluster size grows large (50+ nodes) and the per-route O(N) hash
-  computation becomes visible against downstream HTTP cost.
- Decentralised routing is needed (each node computes the ring locally,
-  no central console required).
- A precomputed flat-array lookup is desired so the routing hot path
-  avoids hashing entirely.
+The consistent hash ring becomes advantageous when:
+- Cluster size grows large (50+ nodes) and frequent membership changes
+  cause the donor/recipient algorithm to churn
+- Decentralized routing is needed (each node computes the ring locally,
+  no central console required)
+- Cross-language determinism is important (multiple implementations must
+  agree on the same assignment without sharing state)

 ## Algorithm

@@ -126,17 +133,16 @@ class HashRing:
        # Precompute all 65536 bucket assignments
 ```

-## Comparison with rendezvous (HRW) hashing
+## Comparison with current approach

-| Aspect | Rendezvous (live) | Consistent hash ring (this doc) |
-|--------|-------------------|---------------------------------|
-| Per-route cost | O(N) hash computes | O(log V) bisect against precomputed array |
-| Seeding | None — pure function | Build vnode array on every membership change |
-| Node addition | Pure function moves ~1/N keys | Ring moves ~1/N buckets |
-| Node removal | Surviving nodes' keys unchanged | Surviving nodes' buckets unchanged |
-| Decentralised | Yes — pure function over services | Yes — each node computes locally |
-| Persistent state | None | None on the hot path; precomputed array in memory |
-| Complexity | ~20 LOC | Virtual-node construction + bisect |
+| Aspect | Weight-proportional (current) | Consistent hash ring |
+|--------|------------------------------|---------------------|
+| Seeding | Exact weight split, deterministic | Hash-based, ~3% variance |
+| Node addition | Donor/recipient moves only excess | Ring moves ~1/N buckets |
+| Node removal | Dead buckets → most underloaded | Ring redistributes to clockwise neighbors |
+| Cross-node churn | Zero (only donor→recipient) | Zero (ring stability guarantee) |
+| Decentralized | No (needs central rebalancer) | Yes (each node computes locally) |
+| Complexity | Simple weight arithmetic | Virtual node construction + bisect |

 ## Test vectors

@@ -13,7 +13,7 @@ cloud "LLM Providers" as llm {
    component [OpenAI-compatible API\n(OpenAI, vLLM, llama.cpp)] as llm_openai
    component [Anthropic Messages API] as llm_anthropic
 }
-database "SQLite / PostgreSQL\n(durable state)" as storage
+database "SQLite\n(.turnstone.db)" as sqlite

 ' Turnstone System Boundary
 package "Turnstone Platform" {
@@ -33,26 +33,24 @@ eval_user --> eval : Python API

 ' Internal connections
 cli --> llm : LLM Provider API\n(via provider adapters)
-cli --> storage : persistence
+cli --> sqlite : SQLite

 server --> llm : LLM Provider API\n(via provider adapters)
-server --> storage : persistence
+server --> sqlite : SQLite

 eval --> llm : LLM Provider API\n(non-streaming)
-eval --> storage : persistence
+eval --> sqlite : SQLite

-console --> server : HTTP routing/UI proxy + cluster SSE\n(FNV-1a rendezvous placement,\nproxy /node/{id}/* traffic)
+console --> server : HTTP proxy\n(hash-ring bucket lookup,\nproxy /node/{id}/* traffic)

-channel --> console : multi-node route/create/live/send/approve
-channel --> server : direct mode + owning-node SSE\n(POST /v1/api/workstreams/{ws_id}/send,\nGET /v1/api/workstreams/{ws_id}/events)
+channel --> server : HTTP + SSE\n(POST /v1/api/send,\nGET /v1/api/events)

 ' Notes
 note right of console
  Multi-node router:
-  - FNV-1a rendezvous placement
+  - Hash-ring bucket lookup
  - Proxies create/send/approve
-  - Collector aggregates node SSE
-  - Browser dashboard receives console SSE fanout
-  - /node/{id} proxies pane HTTP + SSE
+  - Direct SSE from client to node
+  - HTTP polling for dashboard
 end note
@enduml
@@ -18,36 +18,28 @@ skinparam component {
 package "Entry Points" <<Rectangle>> {
    component [cli.py\nturnstone] as cli <<entry>>
    component [server.py\nturnstone-server] as server <<entry>>
-    component [console/server.py\nturnstone-console] as consoleentry <<entry>>
    component [eval.py\nturnstone-eval] as eval <<entry>>
-    component [admin.py\nturnstone-admin] as admin <<entry>>
-    component [bootstrap.py\nturnstone-bootstrap] as bootstrap <<entry>>
+    component [chat.py\n(re-exports)] as chat <<entry>>
 }

 ' Core engine
 package "turnstone/core/" <<Rectangle>> {
-    component [session.py\nChatSession, SessionUI\ngeneration-fenced turn loop] as session <<core>>
-    component [session_manager.py\nSessionManager\nshared lifecycle invariants] as sessionmanager <<core>>
-    component [adapters/\ninteractive + coordinator\nconstruction/event policies] as adapters <<core>>
-    component [model_turn.py\nModelLane, model_turn()\nlower / sample / re-ingest] as modelturn <<core>>
-    component [trajectory.py\ncanonical Turn IR] as trajectory <<core>>
-    component [lowering.py\nprovider-wire lowering] as lowering <<core>>
-    component [state_writer.py\nordered durable state tail] as statewriter <<core>>
-    component [model_backend_auth.py\nper-call backend credentials] as modelauth <<core>>
-    component [providers/\nLLMProvider, OpenAI, Anthropic, Google] as providers <<core>>
-    component [workstream.py\nWorkstream types + state] as workstream <<core>>
+    component [session.py\nChatSession, SessionUI] as session <<core>>
+    component [providers/\nLLMProvider, OpenAI, Anthropic] as providers <<core>>
+    component [workstream.py\nWorkstreamManager] as workstream <<core>>
    component [tools.py\nTool loader] as tools <<core>>
    component [memory.py\nPersistence facade] as memory <<core>>
    component [storage/\nStorageBackend protocol\nSQLite + PostgreSQL] as storage <<core>>
    component [metrics.py\nPrometheus metrics] as metrics <<core>>
    component [config.py\nTOML config] as config <<core>>
    component [safety.py\nPath validation] as safety <<core>>
+    component [sandbox.py\nCommand sandbox] as sandbox <<core>>
    component [edit.py\nFile editing] as edit <<core>>
    component [web.py\nWeb helpers] as web <<core>>
    component [auth.py\nAuthentication] as auth <<core>>
    component [healthcheck.py\nBackendHealthMonitor] as healthcheck <<core>>
    component [ratelimit.py\nRateLimiter] as ratelimit <<core>>
-    component [mcp_client.py\nMCPClientManager\n(push + manual refresh)] as mcp <<core>>
+    component [mcp_client.py\nMCPClientManager\n(push + periodic refresh)] as mcp <<core>>
    component [tool_search.py\nToolSearchManager, BM25] as toolsearch <<core>>
    component [model_registry.py\nModelRegistry] as registry <<core>>
 }
@@ -56,8 +48,7 @@ package "turnstone/core/" <<Rectangle>> {
 package "turnstone/channels/" <<Rectangle>> {
    component [_routing.py\nChannelRouter] as router <<channel>>
    component [discord/bot.py\nDiscordBot] as discordbot <<channel>>
-    component [slack/bot.py\nSlackBot (Socket Mode)] as slackbot <<channel>>
-    component [cli.py\nturnstone-channel] as gateway <<channel>>
+    component [gateway.py\nturnstone-channel] as gateway <<channel>>
 }

 ' Console
@@ -87,18 +78,18 @@ package "turnstone/api/" <<Rectangle>> {
 package "turnstone/sdk/" <<Rectangle>> {
    component [server.py\nTurnstoneServer (sync+async)] as sdkserver <<sdk>>
    component [console.py\nTurnstoneConsole (sync+async)] as sdkconsole <<sdk>>
-    component [events.py\nTyped SSE event stream] as sdkevents <<sdk>>
+    component [events.py\n27 SSE event types] as sdkevents <<sdk>>
    component [_base.py\nhttpx client base] as sdkbase <<sdk>>
 }

 ' Tool schemas
 package "turnstone/tools/" <<Rectangle>> {
-    component [*.json\nBuilt-in tool schemas] as schemas <<artifact>>
+    component [*.json\n19 tool schemas] as schemas <<artifact>>
 }

 ' Entry point dependencies
 cli --> session
-cli --> sessionmanager
+cli --> workstream
 cli --> config
 cli --> memory
 cli --> colors
@@ -107,8 +98,7 @@ cli --> spinner
 cli --> tools

 server --> session
-server --> sessionmanager
-server --> adapters
+server --> workstream
 server --> config
 server --> memory
 server --> metrics
@@ -122,30 +112,15 @@ eval --> memory
 eval --> config
 eval --> tools

-consoleentry --> sessionmanager
-consoleentry --> adapters
-consoleentry --> consoleserver
-
-admin --> auth
-bootstrap --> providers
+chat --> session

 ' Core internal deps
-sessionmanager --> workstream
-sessionmanager --> adapters
-sessionmanager --> storage
-adapters --> session : constructs
-session --> modelturn
-session --> trajectory
-session --> lowering
-session --> statewriter
-session --> modelauth
-modelturn --> providers
-modelturn --> trajectory
-modelturn --> lowering
+session --> providers
 session --> tools
 session --> memory
 memory --> storage
 session --> safety
+session --> sandbox
 session --> edit
 session --> web
 session --> healthcheck
@@ -153,7 +128,6 @@ session --> mcp : optional
 session --> toolsearch : optional
 session --> registry : optional
 registry --> providers
-modelturn --> registry : coherent snapshot
 healthcheck --> metrics
 mcp --> config
 registry --> config
@@ -161,19 +135,15 @@ tools --> schemas

 ' Channel dependencies
 gateway --> discordbot
-gateway --> slackbot
 gateway --> router
-discordbot --> sdkserver : direct HTTP + node SSE
-slackbot --> sdkserver : direct HTTP + node SSE
-router --> sdkserver : single-node/direct mode
-router --> sdkconsole : multi-node route/create/live
+discordbot --> sdkserver : HTTP + SSE
 router --> storage : channel_routes

 ' Console dependencies
 consoleserver --> collector
 consoleserver --> config
 consoleserver --> auth
-collector --> server : discovery HTTP + cluster SSE aggregation
+collector --> server : HTTP polling

 ' API dependencies
 serverspec --> openapi
@@ -15,6 +15,7 @@ interface "SessionUI" as SessionUI <<Protocol>> {
    + on_tool_result(call_id: str, name: str, output: str, *, is_error: bool = False)
    + on_tool_output_chunk(call_id: str, chunk: str)
    + on_status(usage: dict, ctx_window: int, effort: str)
+    + on_plan_review(content: str) → str
    + on_info(message: str)
    + on_error(message: str)
    + on_state_change(state: str)
@@ -32,7 +33,7 @@ class "TerminalUI" as TerminalUI {
 class "WorkstreamTerminalUI" as WsTermUI {
    - _output_buffer: list[tuple]
    - ws_id: str
-    - manager: SessionManager
+    - manager: WorkstreamManager
    + flush_buffer()
    --
    Buffers output when workstream
@@ -41,14 +42,16 @@ class "WorkstreamTerminalUI" as WsTermUI {

 class "WebUI" as WebUI {
    - _listeners: list[Queue]
-    - _approval_cycles: dict[str, ApprovalCycle]
+    - _approval_event: Event
+    - _plan_event: Event
    - _ws_prompt_tokens: int
    - _ws_tool_calls: dict
-    + resolve_approval(approved, feedback, cycle_id?, call_id?)
+    + resolve_approval(approved, feedback)
+    + resolve_plan(feedback)
    --
    Enqueues JSON events for SSE.
-    Concurrent approval cycles each own
-    a threading.Event and result slot.
+    Blocks on threading.Event for
+    approval/plan review.
    SSE handlers bridge Queue to
    async via run_in_executor().
    --
@@ -66,9 +69,9 @@ class "NullUI" as NullUI {
 interface "LLMProvider" as LLMProvider <<Protocol>> {
    + provider_name: str {property}
    + get_capabilities(model) → ModelCapabilities
-    + create_streaming(client, model, messages, ..., cancel_ref, replay_reasoning_to_model) → Iterator[StreamChunk]
+    + create_streaming(client, model, messages, ...) → Iterator[StreamChunk]
+    + create_completion(client, model, messages, ...) → CompletionResult
    + convert_tools(tools) → list[dict]
-    + extract_reasoning_text(provider_blocks) → str
    + retryable_error_names: frozenset[str] {property}
    --
    core/providers/_protocol.py
@@ -100,18 +103,6 @@ class "AnthropicProvider" as AnthropicProv {
    core/providers/_anthropic.py
 }

-class "GoogleProvider" as GoogleProv {
-    + provider_name: str
-    + get_capabilities(model) -> ModelCapabilities
-    --
-    Extends OpenAIChatCompletionsProvider
-    for Gemini /v1beta/openai/ endpoint.
-    Single default ModelCapabilities
-    (2M context, 65K output).
-    --
-    core/providers/_google.py
-}
-
 ' ModelCapabilities
 class "ModelCapabilities" as ModelCaps <<frozen>> {
    + context_window: int
@@ -123,85 +114,34 @@ class "ModelCapabilities" as ModelCaps <<frozen>> {
    + supports_web_search: bool
    + supports_tool_search: bool
    + supports_vision: bool
-    + supports_reasoning_replay: bool
-}
-
-class "ModelLane" as ModelLane <<frozen>> {
-    + provider: LLMProvider
-    + client: Any
-    + model: str
-    + alias: str
-    + capabilities: ModelCapabilities
-    + extra_params: dict | None
-    + registry: ModelRegistry | None
-    + admission: ModelAdmission | None
-    + backend_auth_config: ModelConfig | None
-    + backend_auth_resolver: Callable | None
-}
-
-class "ResolvedModelBinding" as ResolvedBinding <<frozen>> {
-    + lane: ModelLane
-    + config: ModelConfig | None
-    + registry_generation: int
-}
-
-class "ModelTurnResult" as ModelTurnResult <<frozen>> {
-    + turn: Turn
-    + tool_calls: list[dict]
-    + finish_reason: str
-    + usage: UsageInfo | None
-    + wire_msgs: list[dict] | None
-    + producer: str
-    + serving_model: str
-}
-
-class "model_turn()" as ModelTurnFn {
-    Turn IR → lower → provider stream
-    → drain → canonical assistant Turn
-    --
-    core/model_turn.py
-}
-
-class "Backend auth resolver" as BackendAuth {
-    + resolve_model_backend_auth_token(...)
-    --
-    Resolves static / Entra OBO /
-    Entra app / RFC 8693 per call.
-    Dynamic failure can fail closed.
-    --
-    core/model_backend_auth.py
 }

 ' ChatSession
 class "ChatSession" as ChatSession {
-    - _model_binding: ResolvedModelBinding
-    - _model_binding_lock: Lock
+    - client: Any
+    - provider: LLMProvider
+    - model: str
    - ui: SessionUI
-    - messages: list[Turn]
+    - messages: list[dict]
    - _msg_tokens: list[int]
    - _ws_id: str
    - _mcp_client: MCPClientManager | None
    - _tool_search: ToolSearchManager | None
    - _registry: ModelRegistry | None
-    - _generation: int
-    - _cancel_event: Event
-    - _durability_next_ticket: int
    + model_alias: str | None {property}
    - _tools: list[dict]
    - _task_tools: list[dict]
+    - _agent_tools: list[dict]
    - _read_files: set[str]
    - system_messages: list[dict]
    --
-    + send(user_input: str, ..., acting_user_id: str | None)
-    + cancel()
-    + compact_now() → bool
-    + fork_from_storage(source_ws_id, principal_id, ...)
+    + send(user_input: str)
    + handle_command(command: str)
    + resume(ws_id: str)
    - _save_config()
-    - _stream_response(my_generation) → ModelTurnResult
-    - _model_turn_with_fallback(consumer, prepare_wire) → ModelTurnResult
-    - _model_turn_with_retry(lane, tracker, ...) → ModelTurnResult
+    - _stream_response(stream) → dict
+    - _create_stream_with_retry(msgs) → Stream (+ fallback)
+    - _try_stream(client, model, msgs) → Stream
    - _execute_tools(tool_calls) → (results, feedback)
    - _prepare_tool(tc) → item dict
    - _prepare_mcp_tool(call_id, name, args) → item dict
@@ -213,10 +153,8 @@ class "ChatSession" as ChatSession {
    - _rebuild_tool_search()
    + close()
    - _run_agent(messages, tools, ...) → str
-    - _compact_messages(auto: bool, my_generation: int)
-    - _commit_for_generation(generation, commit)
-    - _publish_for_generation(generation, publish)
-    - _full_messages() → list[Turn]
+    - _compact_messages(auto: bool)
+    - _full_messages() → list[dict]
    - _update_token_table(msg)
    - _emit_state(state: str)
    - _generate_title()
@@ -229,40 +167,19 @@ class "HeadlessSession" as HeadlessSession {
    + send_headless(input, max_turns, ...)
    - _override_system_prompt(content)
    --
-    eval.py: drained single-shot turns,
+    eval.py: non-streaming,
    records all tool calls
 }

-' SessionManager
-interface "SessionKindAdapter" as KindAdapter <<Protocol>> {
-    + kind: WorkstreamKind
-    + build_ui(ws) → SessionUI
-    + build_session(ws, ...) → ChatSession
-    + cleanup_ui(ws)
-}
-
-interface "SessionEventEmitter" as EventEmitter <<Protocol>> {
-    + emit_created(ws)
-    + emit_rehydrated(ws)
-    + emit_state(ws, state)
-    + emit_closed(ws_id, reason, name)
-}
-
-class "SessionManager" as SessionMgr {
-    - _adapter: SessionKindAdapter
-    - _storage: StorageBackend
+' WorkstreamManager
+class "WorkstreamManager" as WsMgr {
+    - _session_factory: Callable[[SessionUI], ChatSession]
    - _workstreams: dict[str, Workstream]
-    - _pending_creates: dict[str, Workstream]
-    - _retiring_ids: set[str]
-    - _state_writer: StateWriter | None
    - _order: list[str]
    - _active_id: str
+    - _on_state_change: Callable
    --
-    + create(user_id, name, ..., defer_emit_created) → Workstream
-    + commit_create(ws) → bool
-    + discard(ws, ...) → bool
-    + open(ws_id) → Workstream | None
-    + delete(ws_id) → bool
+    + create(name, ui_factory) → Workstream
    + close(ws_id)
    + get(ws_id) → Workstream
    + get_active() → Workstream
@@ -277,17 +194,11 @@ class "Workstream" as Ws <<dataclass>> {
    + id: str
    + name: str
    + state: WorkstreamState
-    + session: ChatSession | None
-    + ui: SessionUI | None
-    + worker_thread: Thread | None
+    + session: ChatSession
+    + ui: SessionUI
+    + worker_thread: Thread
    + error_message: str
    + last_active: float
-    + kind: WorkstreamKind
-    + user_id: str
-    + parent_ws_id: str | None
-    + project_id: str | None
-    - _fork_reservation_token: str
-    - _closed: bool
    - _lock: Lock
 }

@@ -330,7 +241,7 @@ class "MCPClientManager" as MCPMgr {
    Background asyncio event loop
    bridges async MCP SDK to
    sync ChatSession dispatch.
-    Push + manual refresh.
+    Push + periodic + manual refresh.
    Resources + prompts discovered
    alongside tools at startup.
    --
@@ -358,13 +269,12 @@ class "ModelRegistry" as ModelReg {
    - _models: dict[str, ModelConfig]
    - _clients: dict[str, Any]
    - _providers: dict[str, LLMProvider]
-    - _admissions: dict[str, ModelAdmission]
    - _client_lock: Lock
    + default: str
    + fallback: list[str]
    + agent_model: str | None
    --
-    + resolve_binding(alias) → (client, model, config, provider, admission, generation)
+    + resolve(alias) → (client, model, config)
    + get_client(alias) → Any
    + get_provider(alias) → LLMProvider
    + has_alias(alias) → bool
@@ -373,40 +283,17 @@ class "ModelRegistry" as ModelReg {
    --
    Thread-safe lazy client + provider
    creation. Loaded by load_model_registry()
-    from DB + [models.*] config + CLI args.
+    from CLI args + [models.*] config.
    --
    core/model_registry.py
 }

-class "ModelAdmission" as ModelAdmission {
-    - alias: str
-    - _limit: int
-    - _in_flight: int
-    - _waiters: deque
-    + acquire(cancel_ref) → AdmissionLease
-    + set_limit(limit)
-    + snapshot() → AdmissionSnapshot
-    --
-    Per-process FIFO generation gate.
-    Stable across alias hot reloads;
-    queue time is deadline credit.
-    --
-    core/admission.py
-}
-
 class "ModelConfig" as ModelCfg <<frozen>> {
    + alias: str
    + provider: str
    + base_url: str
    + model: str
    + context_window: int
-    + temperature: float | None
-    + max_tokens: int | None
-    + reasoning_effort: str | None
-    + max_concurrency: int
-    + auth_mode: str
-    + obo_audience: str
-    + obo_scopes: str
 }

 ' Circuit breaker state
@@ -473,38 +360,24 @@ SessionUI <|.. NullUI

 LLMProvider <|.. OpenAIProv
 LLMProvider <|.. AnthropicProv
-OpenAIProv <|-- GoogleProv

 ChatSession --> SessionUI : uses
-ChatSession --> ResolvedBinding : owns coherent snapshot
-ChatSession --> ModelTurnFn : every model-backed role
+ChatSession --> LLMProvider : delegates LLM calls
 ChatSession --> MCPMgr : optional
 ChatSession --o ToolSearchMgr : _tool_search
 ChatSession --> ModelReg : optional
 ChatSession <|-- HeadlessSession

-SessionMgr --> "*" Ws : manages
-SessionMgr --> KindAdapter : delegates construction
-SessionMgr --> EventEmitter : lifecycle fan-out
+WsMgr --> "*" Ws : manages
 Ws --> "1" ChatSession : wraps
 Ws --> "1" SessionUI : wraps
 Ws --> "1" WsState : has

-KindAdapter ..> ChatSession : constructs
+WsMgr ..> ChatSession : creates via\nsession_factory(ui, model_alias)

 ModelReg --> "*" ModelCfg : holds
 ModelReg --> "*" LLMProvider : caches
-ModelReg --> "*" ModelAdmission : owns per alias
 LLMProvider --> ModelCaps : returns
-ModelReg --> ResolvedBinding : resolves atomically
-ResolvedBinding --> ModelLane
-ModelLane --> LLMProvider
-ModelLane --> ModelCaps
-ModelLane --> ModelCfg : auth/config snapshot
-ModelLane --> ModelAdmission : admission lease
-ModelTurnFn --> ModelLane
-ModelTurnFn --> ModelTurnResult
-ModelTurnFn ..> BackendAuth : per-call resolver

 ChatSession --> HealthMon : checks circuit
 HealthMon --> "1" CircuitState : has
@@ -517,9 +390,7 @@ note bottom of ChatSession
  Provider-agnostic — delegates all LLM
  communication to LLMProvider adapters.

-  Every live/durable publication is fenced by
-  its generation. Model calls use immutable lanes;
-  provider-wire mutation stays at lowering.
+  core/session.py (~2700 lines)
 end note

@enduml
@@ -1,171 +1,168 @@
@startuml
 !theme plain
-title Turnstone — Generation-Fenced Conversation Turn
+title Turnstone — Conversation Turn Lifecycle

 skinparam sequenceArrowThickness 1.5
 skinparam sequenceLifeLineBackgroundColor #F5F5F5

-participant "HTTP / CLI\ncaller" as User
-participant "SessionManager" as Manager
-participant "ChatSession" as Session
-participant "SessionUIBase" as UI
-participant "Accepted-row handoff\n(total live prefix)" as Handoff
-participant "model_turn()\n+ lowering" as Plant
-participant "ModelAdmission\n(per alias)" as Admission
-participant "LLM provider" as Provider
-participant "Tool workers" as Tools
-database "StorageBackend\n(SQLite / PostgreSQL)" as Storage
+participant "User /\nHTTP Client" as User
+participant "ChatSession" as CS
+participant "SessionUI" as UI
+participant "LLMProvider\n(OpenAI / Anthropic)" as LLM
+participant "Tool Executor\n(ThreadPool)" as TP
+database "SQLite" as DB

-== Admission and generation claim ==
+== User Input ==

-User -> Manager : dispatch send on one Workstream
-Manager -> Session : bind_acting_user(principal)\nsend(text, attachments, send_id)
-activate Session
-Session -> Session : refresh immutable ResolvedModelBinding
+User -> CS : send(user_input)
+activate CS

-opt token budget exhausted
-  Session -> UI : approve_tools(__budget_override__)
-  note right of UI
-    This gate precedes a generation claim but carries
-    a monotonic cancellation witness. Stop cannot be
-    mistaken for a budget-policy denial.
-  end note
-end
+CS -> CS : messages.append({role: "user", content: input})
+CS -> DB : save_message(ws_id, "user", input)

-Session -> Session : _claim_generation() → generation N\ninstall fresh cancel event
-Session -> Session : plan memory / participant context
-Session -> Handoff : admit USER row\ncommit_key + prefix revision
-Session -> Storage : ordered durable batch:\nappend canonical user Turn + metadata
+== LLM Call Loop ==

-note over Session, Handoff
-  Every accepted conversation row enters this lane before durability:
-  USER, ASSISTANT, TOOL, SYSTEM, compaction checkpoints, and cancellation
-  markers. Admission shares the handoff lock with its live UI transition
-  or history_resync repair event.
-end note
+group loop [while tool_calls present]

-note over Handoff, Storage
-  _commit_for_generation(N) admits bounded live mutations under the
-  generation lock, then executes immutable persistence closures in FIFO
-  ticket order. A force successor either follows the whole commit or
-  prevents it. /history projects durable prefix + pending journal suffix;
-  durable ACK removes the pending copy without changing the prefix revision.
-end note
+    CS -> UI : on_state_change("thinking")
+    CS -> UI : on_thinking_start()

-opt already over the hard context ceiling
-  Session -> Session : compact before first model call\n(preserve the new user turn)
-end
+    CS -> LLM : provider.create_streaming(\n  client, model, messages, tools, ...)\n  (normalized StreamChunk iterator)
+    activate LLM

-== Model / tool loop ==
+    note right of CS
+      Retry up to 3× on transient errors:
+      RateLimitError, APITimeoutError,
+      APIConnectionError, InternalServerError,
+      ServiceUnavailableError, APIError
+      Backoff: 1s, 2s, 4s
+    end note

-loop until final answer and no queued input
-  Session -> UI : on_turn_start()\nreset per-stream replay buffers
-  Session -> UI : state = thinking\non_thinking_start()
-  Session -> Session : _stream_response(N)\nretry + fallback policy
-  Session -> Plant : model_turn(active ModelLane, Turns,\n tools, cancel_ref, on_chunk)
-  activate Plant
-  Plant -> Plant : canonical Turns → provider wire\nrestore ids + repair + lane-specific fold
-  Plant -> Plant : materialize attachment refs\n(nested perception before outer slot)
-  Plant -> Admission : acquire(cancel_ref)
-  activate Admission
-  Plant -> Plant : resolve per-call backend credential\nfrom lane's pinned ModelConfig
-  Plant -> Provider : create_streaming(...)
-  activate Provider
+    == Streaming Response ==

-  loop normalized stream chunks
-    Provider --> Plant : StreamChunk
-    Plant --> Session : on_chunk(StreamChunk)
-    Session -> Session : check cancel event + generation N
-    Session -> UI : reasoning / content / info token
-  end
-
-  Provider --> Plant : finish + usage + native blocks
-  deactivate Provider
-  Plant -> Plant : drain + re-ingest assistant Turn\nwith serving-lane provenance
-  Plant -> Admission : release before retry backoff
-  deactivate Admission
-  Plant --> Session : ModelTurnResult
-  deactivate Plant
-
-  Session -> UI : on_stream_end()
-  Session -> Session : generation-fenced result commit:\nappend assistant Turn + token accounting
-  Session -> UI : on_turn_committed()
-  Session -> Handoff : admit ASSISTANT row\ncommit_key + prefix revision
-  Session -> Storage : ordered durable assistant row\n(content + tool mirror + native lane)
-
-  alt no tool calls
-    opt over soft threshold
-      Session -> Session : cooperative / end-of-turn compaction
-      Session -> Handoff : admit SYSTEM/source=compaction\ncheckpoint projection
-      Session -> Storage : append checkpoint summary marker\nwith source watermark
-      note right of Storage
-        Full history remains durable. Resume loads
-        [summary] + rows after the checkpoint.
-      end note
-      opt model stopped for compaction
-        Session -> Handoff : admit USER/source=compaction_resume row
-        Session -> Storage : append synthetic compaction_resume Turn
-      end
-    end
-    alt queued messages drained
-      Session -> Handoff : admit combined queued USER row
-      Session -> Storage : append combined queued user Turn
-    else truly complete
-      Session -> UI : state = idle
-    end
-  else tool calls present
-    Session -> UI : state = running
-    Session -> Session : prepare items + previews\nattach cancellation witnesses
-
-    opt one or more items require a human
-      Session -> UI : approve_tools(items)\nregister independent ApprovalCycle
-      note right of UI
-        Parallel agents may own concurrent cycles.
-        cycle_id / call_id routes exactly one decision;
-        Smart Approvals may clear qualifying items.
-      end note
-      User -> UI : approve / deny selected cycle
-      UI --> Session : decision + optional feedback
+    loop for each chunk in stream
+        LLM --> CS : delta
+        note right of CS
+          on_thinking_stop() called on first
+          delta token via _stop_spinner_once()
+        end note
+        alt reasoning_content present
+            CS -> UI : on_reasoning_token(text)
+        else content present
+            CS -> UI : on_content_token(text)
+        else tool_call delta
+            CS -> CS : accumulate in tool_calls_acc
+        else info_delta present
+            CS -> UI : on_info(text)\n(e.g. server-side web search status)
+        end
    end

-    Session -> Tools : execute admitted items in parallel
-    activate Tools
-    Tools --> UI : chunks + result card\nwith effect disposition
-    Tools --> Session : outputs / errors / effect statuses
-    deactivate Tools
-    Session -> Session : output-guard evaluation\nthen generation N re-check
+        note right of CS
+          **Cancellation checkpoint:**
+          _check_cancelled() runs per chunk.
+          If cancel_event is set, raises
+          GenerationCancelled — preserves
+          partial content, emits idle state.
+        end note

-    opt compaction owed before result sizing
-      Session -> Session : compact, preserving assistant tool-call Turn
-      Session -> Handoff : admit SYSTEM/source=compaction checkpoint
-      Session -> Storage : append checkpoint marker
+    LLM --> CS : stream complete (usage stats)
+    deactivate LLM
+
+    CS -> UI : on_thinking_stop()  (no-op guard: already called by _stop_spinner_once)
+    CS -> UI : on_stream_end()
+
+    CS -> CS : _update_token_table()\ncalibrate chars_per_token ratio
+    CS -> CS : messages.append(assistant_msg)
+    CS -> DB : save_message(ws_id, "assistant", content)
+    CS -> DB : save_message(ws_id, "tool_call", ...) ×N
+
+    == Tool Dispatch (if tool_calls) ==
+
+    alt no tool_calls
+        CS -> UI : on_status(usage, context_window, effort)
+
+        opt prompt_tokens > context_window × auto_compact_pct
+            CS -> CS : _compact_messages(auto=True)
+            CS -> LLM : Non-streaming summarization call
+            CS -> CS : Replace messages with [summary]
+        end
+
+        opt first exchange & no title
+            CS -> CS : Background thread: _generate_title()
+        end
+
+        CS -> UI : on_state_change("idle")
+        CS --> User : return
+
+    else has tool_calls
+        CS -> UI : on_state_change("running")
+
+        == Phase 1: Prepare ==
+        CS -> CS : [_prepare_tool(tc) for tc in tool_calls]\nParse JSON args, validate,\nbuild preview + header
+
+        == Phase 2: Approve ==
+        CS -> UI : on_state_change("attention")
+        CS -> UI : approve_tools(items)
+        activate UI
+        note right of UI
+          TerminalUI: input() prompt
+          WebUI: _approval_event.wait()
+          NullUI: returns (True, None)
+        end note
+        UI --> CS : (approved: bool, feedback: str?)
+        deactivate UI
+        CS -> UI : on_state_change("running")
+
+        == Phase 3: Execute ==
+        CS -> TP : ThreadPoolExecutor(max_workers=4)\nrun_one(item) for each tool
+        activate TP
+
+        note right of TP
+          Parallel execution:
+          bash → Popen + line-by-line streaming
+          read_file → open().read() or base64 image
+          search → grep subprocess
+          edit_file → string replace
+          task/plan → _run_agent() sub-loop
+          math → sandboxed subprocess
+          web_fetch → httpx + LLM summarize
+          web_search → provider-native or Tavily fallback
+          memory/recall → SQLite
+        end note
+
+        note right of TP
+          bash: on_tool_output_chunk(call_id, line)
+          called per stdout line,
+          then on_tool_result(call_id, name, output, is_error).
+          is_error=True when execution failed.
+          call_id routes chunks/results to correct
+          tool div during parallel execution.
+          Other tools: on_tool_result() only.
+        end note
+
+        TP --> CS : [(call_id, output), ...]
+        deactivate TP
+
+        loop for each result
+            CS -> CS : messages.append({role: "tool", ...})
+            CS -> DB : save_message(ws_id, "tool_result", ...)
+        end
+
+        opt user_feedback from approval
+            CS -> CS : messages.append({role: "user", content: feedback})
+        end
+
+        note right of CS : Loop back for next LLM call
+
+    else GenerationCancelled
+        CS -> CS : Preserve partial content\nor roll back incomplete tools
+        CS -> UI : on_info("[Generation cancelled]")
+        CS -> UI : on_state_change("idle")
+        CS --> User : return (no re-raise)
    end

-    Session -> Session : one generation-fenced batch:\nappend all Tool Turns, advisories, feedback
-    Session -> Handoff : admit FIFO TOOL rows\ncommit keys + prefix revisions
-    Session -> Storage : FIFO durable tool rows + metadata
-  end
 end

-== Stop / force-successor boundary ==
+deactivate CS

-User -> Session : cancel()
-Session -> Session : atomically set generation event; snapshot\nmain stream, child scopes, judges, subprocesses
-Session -> Provider : close live stream handle
-Session -> Tools : abort child scopes + kill subprocess groups
-Session -> UI : resolve only cancelled operation's\napproval cycles
-opt cancellation produced accepted conversation rows
-  Session -> Handoff : admit partial ASSISTANT and/or\nsynthesized TOOL cancellation markers
-  Session -> Storage : idempotent keyed cancellation rows
-end
-
-note over Session, Storage
-  Every later publish/commit checks generation ownership. An abandoned
-  worker may unwind, but cannot append Turns, overwrite state, resolve a
-  successor approval, or repaint the successor UI. Observed tool effects
-  are preserved as controller-authored cancellation receipts; unreviewed
-  tool bytes are not laundered into model context.
-end note
-
-deactivate Session
@enduml
@@ -1,117 +1,145 @@
@startuml
 !theme plain
-title Turnstone — Tool Pipeline: Prepare, Approve, Execute, Fold
+title Turnstone — Tool Execution Pipeline (Three Phases)

 start

-partition "Phase 1 — Prepare and assess" #E8F5E9 {
-    :Receive tool calls from one assistant Turn;
-    :Capture the generation's cancel event\nand acting principal;
+partition "Phase 1: Prepare" #E8F5E9 {
+    :Receive tool_calls list from LLM response;

-    while (more tool calls?) is (yes)
-        :Parse arguments and dispatch to\nthe tool-specific preparer;
-        if (preparation succeeds?) then (yes)
-            :Build item: call_id, name, header, preview,\nneeds_approval, execute closure;
+    while (more tool_calls?) is (yes)
+        :Extract call_id, func_name, raw_args;
+
+        if (json.loads(raw_args) succeeds?) then (yes)
+            :parsed_args = JSON dict;
        else (no)
-            :Build an error item for this call only;\nkeep sibling calls valid;
+            :Fallback 1: regex extraction;
+            if (regex found keys?) then (yes)
+                :parsed_args = extracted dict;
+            else (no)
+                :Fallback 2: bare string →\nPRIMARY_KEY_MAP[func_name];
+            endif
        endif
-        :Attach operation-local cancellation witness\nand pinned principal;
+
+        :Dispatch to _prepare_{func_name}();
+
+        note right
+            **Dispatch table (19 built-in + tool_search):**
+            ┌───────────────┬──────────────────┐
+            │ Tool          │ Needs Approval?  │
+            ├───────────────┼──────────────────┤
+            │ bash          │ ✓ Yes            │
+            │ read_file     │ ✗ Auto-approve   │
+            │ write_file    │ ✓ Yes            │
+            │ edit_file     │ ✓ Yes            │
+            │ search        │ ✗ Auto-approve   │
+            │ diff_file     │ ✗ Auto-approve   │
+            │ math          │ ✗ Auto-approve   │
+            │ man           │ ✗ Auto-approve   │
+            │ web_fetch     │ ✗ Auto-approve   │
+            │ web_search    │ ✗ Auto-approve   │
+            │ tool_search   │ ✗ Auto-approve   │
+            │ task_agent    │ ✓ Yes            │
+            │ plan_agent    │ ✓ Yes            │
+            │ memory        │ ✗ Auto-approve   │
+            │ recall        │ ✗ Auto-approve   │
+            │ notify        │ ✗ Auto-approve   │
+            │ watch         │ ✓ create only    │
+            │ skill         │ ✓ load only      │
+            │ read_resource │ ✓ Yes            │
+            │ use_prompt    │ ✓ Yes            │
+            ├───────────────┼──────────────────┤
+            │ mcp__*        │ ✓ Yes (external) │
+            └───────────────┴──────────────────┘
+        end note
+
+        :Build item dict:
+        {call_id, func_name, header,
+         preview, needs_approval,
+         approval_label, execute: Callable};
    endwhile (no)
-
-    :Reject only unsafe ordering shapes\n(for example tasks read + write in one batch);
-    :Run heuristic intent assessment immediately;
-    :Start generation-pinned LLM judge in background;
-    :Stamp one immutable Smart Approval\nsettings snapshot on the batch;
-
-    note right
-      Preparation is per-call isolated: one bad preparer
-      becomes one error Tool Turn rather than orphaning the
-      assistant's entire tool-call set.
-    end note
 }

-partition "Phase 2 — Approval cycle" #FFF3E0 {
-    :Apply explicit bypasses:\nskill / always / policy / blanket;
-
-    if (Smart Approvals enabled?) then (yes)
-        :Wait within the batch's bounded judge deadline;
-        :Auto-approve only LLM approve verdicts\nat or above the captured threshold;
-    endif
-
-    if (human-gated items remain?) then (yes)
-        :Acquire approval-publication lease;
-        :Register independent ApprovalCycle\n(cycle_id, call_ids, event, result);
-        :Publish approve_request + heuristic verdicts;
+partition "Phase 2: Approve" #FFF3E0 {
+    if (any items need approval?) then (yes)
+        :_emit_state("attention");
+        :ui.approve_tools(items);

        note right
-          Parallel task agents can hold several cycles at once.
-          A decision selects one cycle_id / call_id (or the oldest
-          cycle for a legacy selector-less client). Double resolve
-          is a guarded no-op; one cycle cannot wake a sibling.
+            **auto_approve check is handled
+            internally by ui.approve_tools()**
+
+            **TerminalUI**: Print headers/previews,
+            prompt [y/n/a, optional message]
+            If user chose "always":
+              Add pending tool names to auto_approve_tools
+              (auto-approve these tool types going forward)
+            **WebUI**: Enqueue approve_request,
+            block on _approval_event.wait()
+            **NullUI**: Return (True, None)
        end note

-        if (operator approves?) then (yes)
-            :Record decision and optional feedback;
-        else (denies / policy blocks)
-            :Mark only pending items denied;\nEffectStatus = none;
+        if (user approved?) then (yes)
+            :_emit_state("running");
+        else (denied)
+            :Mark all pending items as denied;
+            :denial_msg = "Denied by user";
+            :_emit_state("running");
        endif
-        :Publish approval_resolved;\nunregister this cycle;
-    else (all bypassed / auto-approved)
-        :Publish tool_info with the exact\nauto-approve reason per item;
-    endif
-
-    if (owning operation cancelled?) then (yes)
-        :Cancel only cycles carrying that witness;
-        :Stage every unstarted call as\nEffectStatus = none;
-        stop
+    else (all auto-approved)
+        :ui enqueues tool_info event\n(no blocking);
    endif
 }

-partition "Phase 3 — Execute" #E3F2FD {
-    :Generation + cancellation checkpoint;
-
-    if (batch requires serial ordering?) then (yes)
-        :Execute in provider order;
-    else (no)
-        :Execute via bounded ThreadPoolExecutor;
+partition "Phase 3: Execute" #E3F2FD {
+    :_check_cancelled();
+    note right: Cancellation checkpoint:\nraises GenerationCancelled if\ncancel event is set
+    if (single tool call?) then (yes)
+        :Execute sequentially:\nrun_one(items[0]);
+    else (multiple)
+        :Execute in parallel:\nThreadPoolExecutor(max_workers=4)\npool.map(run_one, items);
    endif

    note right
-      Each worker marks its call started only after the final
-      generation/cancel check. A missing result after that edge is
-      conservatively unknown; an unstarted call is definitively none.
+        **run_one(item):**
+        if item.error → return error string
+        if item.denied → return denial message
+        else → item["execute"](item)
+          ├─ _exec_bash: subprocess.run(["bash", script.sh])
+          ├─ _exec_read_file: open().readlines() or _exec_read_image (base64)
+          ├─ _exec_write_file: makedirs + write
+          ├─ _exec_edit_file: find_occurrences + replace
+          ├─ _exec_search: grep subprocess
+          ├─ _exec_math: sandboxed subprocess
+          ├─ _exec_man: man/info subprocess
+          ├─ _exec_web_fetch: httpx.get + LLM summary
+          ├─ _exec_web_search: Tavily API POST (fallback for local models)
+          ├─ _exec_tool_search: BM25 search + expand_visible()
+          ├─ _exec_task: _run_agent(TASK_AGENT_TOOLS)
+          ├─ _exec_plan: _run_agent(AGENT_TOOLS, read-only)
+          ├─ _exec_notify: HTTP POST to channel gateway
+          ├─ _exec_memory: structured memory save/search/delete/list
+          ├─ _exec_recall: conversation history FTS5 search
+          ├─ _exec_read_resource: MCPClientManager.read_resource_sync()
+          ├─ _exec_use_prompt: MCPClientManager.get_prompt_sync()
+          └─ _exec_mcp_tool: MCPClientManager.call_tool_sync()
    end note

-    :Stream tool chunks to the matching call card;
-    :Capture result / error / preview and effect disposition;
+    :Collect results: [(call_id, output), ...];

-    if (Stop interrupts execution?) then (yes)
-        :Abort child model scopes and subprocess groups;
-        :Synthesize cancellation receipts;
-        note right
-          EffectStatus vocabulary:
-          committed / none / unknown /
-          partial / rolled_back.
+    :_truncate_output() on each result\n(max context_window × chars_per_token × 0.5 chars\ndefault: ~context_window × 2 chars);

-          Observed but unreviewed bytes are omitted from the
-          model-facing receipt; effect truth is retained.
-        end note
+    :bash: ui.on_tool_output_chunk(call_id, line) per stdout line;
+    :ui.on_tool_result(call_id, name, output, is_error) for each;
+
+    if (plan tool was executed?) then (yes)
+        :ui.on_plan_review(output);
+        :Block for user review/feedback;
    endif
 }

-partition "Phase 4 — Guard and atomic fold" #F3E5F5 {
-    if (compaction already owed?) then (yes)
-        :Compact before sizing/folding results;\npreserve the assistant tool-call Turn;
-    endif
-
-    :Truncate each result against the remaining shared budget;
-    :Run heuristic + optional LLM output guard;
-    :Re-check generation after guard work;
-
-    :Under one generation commit, append the complete\nTool Turn block + advisories + feedback;
-    :Persist rows and effect/preview metadata\non the ordered durability lane;
-    :Return results to the next model turn;
-}
+:Return (results, user_feedback);

 stop
+
@enduml
@@ -3,7 +3,6 @@
 title Turnstone — Workstream State Machine

 skinparam state {
-    BackgroundColor<<lifecycle>> #ECEFF1
    BackgroundColor<<idle>> #E8F5E9
    BackgroundColor<<thinking>> #E3F2FD
    BackgroundColor<<running>> #FFF3E0
@@ -11,18 +10,13 @@ skinparam state {
    BackgroundColor<<error>> #FFCDD2
 }

-state "CREATING (persisted only)" as creating <<lifecycle>> : Hidden durable reservation.\nNot returned by ordinary list/open/history.
 state "IDLE" as idle <<idle>> : Waiting for user input.\nNo active LLM call or tool execution.
 state "THINKING" as thinking <<thinking>> : LLM streaming response.\nTokens flowing (reasoning + content).
 state "RUNNING" as running <<running>> : Tools executing.\nThreadPoolExecutor active.
-state "ATTENTION" as attention <<attention>> : Blocked on user action.\nTool approval needed.
+state "ATTENTION" as attention <<attention>> : Blocked on user action.\nTool approval or plan review needed.
 state "ERROR" as error <<error>> : Exception occurred.\nRecoverable on next send().
-state "CLOSED (persisted only)" as closed <<lifecycle>> : Unloaded, explicitly reopenable row.\nNot a live WorkstreamState member.

-[*] --> creating : register exact incarnation\nstate="creating"
-creating --> idle : finalize + publish create\nemit ws_created
-creating --> [*] : immediate exact-token rollback\n(no lifecycle birth emitted)
-creating --> [*] : stale >2h recovery\natomic hard delete; no close event
+[*] --> idle : Session created

 idle --> thinking : send() called\n_emit_state("thinking")

@@ -40,102 +34,46 @@ attention --> running : User denies\n(denial recorded)\n_emit_state("running")

 running --> thinking : Tool results appended,\nnext LLM call\n_emit_state("thinking")

+running --> attention : Plan tool complete,\non_plan_review()\n_emit_state("attention")
+
 running --> error : Exception during\ntool execution

 error --> thinking : New send() call\n_emit_state("thinking")

-idle --> closed : close / eviction\n[journal reconciled]
-error --> closed : close\n[journal reconciled]
-thinking --> closed : close\n[journal reconciled]
-running --> closed : close\n[journal reconciled]
-attention --> closed : close\n[journal reconciled]
-closed --> [*] : hard delete
-closed --> idle : open / rehydrate
-
-note right of closed
-  Before every soft-close / eviction transition,
-  the total accepted conversation-row journal must
-  be durably reconciled. An unresolved row makes an
-  explicit close return HTTP 409 (eviction refuses),
-  and the workstream remains loaded in its live state.
-end note
-
 thinking --> idle : cancel() called\nstream aborted\n_emit_state("idle")

 running --> idle : cancel() called\n_emit_state("idle")

-attention --> idle : cancel() unblocks\napproval wait\n_emit_state("idle")
+attention --> idle : cancel() unblocks\napproval/plan wait\n_emit_state("idle")

 note left of idle
-  **Generation-scoped Stop:**
-  • Sets the active generation event.
-  • Closes its SDK stream; aborts child model
-    scopes and judges; kills subprocess groups.
-  • Sweeps every approval cycle owned by the
-    cancelled workstream operation.
-  • Every later send/model live or durable commit
-    re-checks generation ownership.
-
-  **force=true:** also abandons the stuck worker
-  slot and emits stream_end + IDLE immediately.
-  An orphaned send/model generation may unwind
-  but cannot publish into a successor generation.
-  Quick slash-command workers are a best-effort
-  escape hatch: without generation checkpoints,
-  one may finish an in-place mutation concurrently.
-
-  **Capacity eviction:** an IDLE candidate is only
-  a hint. Per-ID + object lifecycle lanes and the
-  workstream lock revalidate it as worker- and
-  send-barrier-free,
-  then install a terminal claim before slot swap.
+  **Cancel escalation:**
+  1. **Cooperative**: cancel() sets event + closes
+     SDK stream → worker exits at next checkpoint
+  2. **Force**: force=true abandons the worker
+     thread, emits stream_end immediately.
+     Orphaned thread still kills subprocesses
+     but skips message mutations (generation
+     counter prevents stale writes).
 end note

 note right of thinking
  **Emitted via:**
  session._emit_state(state)
    → ui.on_state_change(state)
-    → SessionManager state tail

  **Propagation:**
  • WebUI → global SSE queue (ws_state)
-  • Console → cluster event / HTTP state
-  • CLI → SessionManager.set_state()
-
-  Non-terminal persistence may use StateWriter;
-  a per-id tail orders storage + subscribers and
-  prevents a late state from overwriting CLOSED.
+  • Console → HTTP polling picks up state
+  • CLI → WorkstreamManager.set_state()
 end note

 note left of attention
  **Blocking mechanisms:**
  • TerminalUI: input() prompt
-  • WebUI: one Event per ApprovalCycle
+  • WebUI: threading.Event.wait()
  • ChannelBot: SSE event + Discord button
  • NullUI: auto-approve (never reaches)
 end note

-note right of creating
-  CREATING and CLOSED are storage lifecycle
-  values, not members of WorkstreamState. The
-  live enum remains IDLE / THINKING / RUNNING /
-  ATTENTION / ERROR.
-
-  **Crash-abandoned CREATING recovery:**
-  • Boot pass, then every 5 min even when idle
-    eviction is disabled.
-  • Only rows >2h old; manager loaded/pending
-    IDs and live remote owners are protected.
-  • The current stable node ID is not a live-owner
-    exemption, allowing restart recovery.
-  • Unknown liveness/storage fails closed. Deletion
-    is atomic across dependents and attachment refs.
-  • Tokenless legacy/corrupt rows are locked,
-    reaped, and logged with a warning.
-
-  A loaded hard delete closes publication, drains
-  admitted session durability + state tails, then
-  conditionally removes the exact durable token.
-end note
-
@enduml
@@ -170,15 +170,15 @@ Server --> Browser : Shimmed app.js
 deactivate Server

 note right of Browser
-  All fetch("/v1/api/workstreams/{ws_id}/send") calls in the
-  server UI now become fetch("/node/nodeA/v1/api/workstreams/{ws_id}/send"),
+  All fetch("/v1/api/send") calls in the
+  server UI now become fetch("/node/nodeA/v1/api/send"),
  routed through the console proxy.
 end note

-Browser -> Server : GET /node/nodeA/v1/api/workstreams/ws789/events
+Browser -> Server : GET /node/nodeA/v1/api/events?ws_id=ws789
 activate Server #FFF9C4

-Server -> NodeA : GET http://10.0.1.1:8080/v1/api/workstreams/ws789/events\n(SSE stream via httpx.AsyncClient timeout=None)
+Server -> NodeA : GET http://10.0.1.1:8080/v1/api/events?ws_id=ws789\n(SSE stream via httpx.AsyncClient timeout=None)
 activate NodeA

 loop SSE streaming
@@ -189,10 +189,10 @@ end
 deactivate NodeA
 deactivate Server

-Browser -> Server : POST /node/nodeA/v1/api/workstreams/ws789/send\n{message:"hello"}
+Browser -> Server : POST /node/nodeA/v1/api/send\n{message:"hello", ws_id:"ws789"}
 activate Server #FFF9C4

-Server -> NodeA : POST http://10.0.1.1:8080/v1/api/workstreams/ws789/send\n(body forwarded)
+Server -> NodeA : POST http://10.0.1.1:8080/v1/api/send\n(body forwarded)
 activate NodeA
 NodeA --> Server : {status:"ok"}
 deactivate NodeA
@@ -31,7 +31,7 @@ node "Docker Host" as host {
                Command: turnstone-console
                  --port 8090
                Depends: server
-                FNV-1a rendezvous router for
+                Hash-ring router for
                  multi-node clusters
            end note
        }
@@ -69,7 +69,7 @@ apiclient --> server : HTTP + SSE\nport 8080
 ' Internal connections
 server --> llm_api : OpenAI API\n(HTTPS/HTTP)

-console --> server : HTTP proxy\n(FNV-1a rendezvous placement,\nproxy /node/{id}/*)
+console --> server : HTTP proxy\n(hash-ring lookup,\nproxy /node/{id}/*)

 ' Database connections (production/cluster profiles)
 server ..> pgbouncer : PostgreSQL\n(pool_size=2)
@@ -30,10 +30,10 @@ package "turnstone/sdk/ (Python)" {
        + close_workstream()
        + send(message, ws_id)
        + approve()
+        + plan_feedback()
        + command()
        + cancel(ws_id)
-        + get_history(ws_id, limit) → WorkstreamHistoryResponse
-        + stream_events(ws_id, last_event_id?, history_token?)
+        + stream_events(ws_id)
        + stream_global_events()
        + send_and_wait()
        + list_saved_workstreams()
@@ -88,13 +88,6 @@ package "turnstone/sdk/ (Python)" {
        + ok: bool
    }

-    class WorkstreamHistoryResponse <<type>> {
-        + ws_id: str
-        + messages: list[dict]
-        + cursor: int | None
-        + handoff_token: str | None
-    }
-
    class ServerEvent <<event>> {
        + type: str
        + ws_id: str
@@ -113,7 +106,6 @@ package "turnstone/sdk/ (Python)" {
    TurnstoneConsole --> AsyncTurnstoneConsole : wraps
    TurnstoneConsole --> _SyncRunner : uses
    AsyncTurnstoneServer ..> TurnResult : returns
-    AsyncTurnstoneServer ..> WorkstreamHistoryResponse : renders before SSE
    AsyncTurnstoneServer ..> ServerEvent : yields
    AsyncTurnstoneConsole ..> ClusterEvent : yields
 }
@@ -131,8 +123,7 @@ package "sdk/typescript/ (TypeScript)" {
    class "TurnstoneServer" as TSServer <<ts>> {
        + listWorkstreams()
        + send()
-        + getHistory() → WorkstreamHistoryResponse
-        + streamEvents(cursor?, token?)
+        + streamEvents()
        + sendAndWait()
        ...
    }
@@ -164,10 +155,4 @@ note right of AsyncTurnstoneServer
  (no type duplication)
 end note

-note bottom of ServerEvent
-  history_resync is a typed repair signal.
-  SDKs expose the REST cursor/token handshake but
-  never refetch, render, or reconnect automatically.
-end note
-
@enduml
@@ -1,191 +1,170 @@
@startuml
 !theme plain
-title Turnstone — Storage, Deferred Create, Fork, and Checkpoint Architecture
+title Turnstone — Storage Architecture

 skinparam class {
    BackgroundColor<<protocol>> #E8EAF6
    BackgroundColor<<sqlite>> #C8E6C9
    BackgroundColor<<postgres>> #B3E5FC
-    BackgroundColor<<lifecycle>> #FFF9C4
+    BackgroundColor<<facade>> #FFF9C4
+    BackgroundColor<<migration>> #FFE0B2
    BackgroundColor<<schema>> #F3E5F5
-    BackgroundColor<<helper>> #FFE0B2
 }

-interface "StorageBackend" as Storage <<protocol>> {
-    + load_message_turns(ws_id, checkpointed=True) → list[Turn]
-    + save_message(ws_id, role, content, metadata...)
-    + clone_workstream(source, destination, principal, expected_session) → ForkCloneSnapshot
-    --
-    + register_workstream(..., state, reservation_token) → bool
-    + ensure_workstream_incarnation_snapshot(ws_id) → row + token
-    + finalize_deferred_create(ws_id, token, config...) → bool
-    + publish_deferred_create(ws_id, token) → bool
-    + delete_workstream_if_fork_reserved(ws_id, token) → bool
-    + delete_stale_creating_reservations(...) → list[ws_id]
-    + update_workstream_state(ws_id, state)
-    + delete_workstream(ws_id) → bool
-    --
-    + attachment / project / memory / auth / governance APIs
+' -- Protocol --
+interface "StorageBackend" as SB <<protocol>> {
+    +save_message(ws_id, role, content, ...)
+    +load_messages(ws_id) → list[dict]
+    +register_workstream(ws_id, node_id, name, state)
+    +update_workstream_state(ws_id, state)
+    +update_workstream_name(ws_id, name)
+    +set_workstream_alias(ws_id, alias) → bool
+    +update_workstream_title(ws_id, title)
+    +resolve_workstream(alias_or_id) → str | None
+    +delete_workstream(ws_id) → bool
+    +prune_workstreams(retention_days) → (int, int)
+    +list_workstreams(node_id, limit) → list
+    +save_workstream_config(ws_id, config)
+    +load_workstream_config(ws_id) → dict
+    +kv_get(key) → str | None
+    +kv_set(key, value) → str | None
+    +kv_delete(key) → bool
+    +kv_list() → list[(str, str)]
+    +kv_search(query) → list[(str, str)]
+    +search_history(query, limit) → list
+    +search_history_recent(limit) → list
+    +create_user(user_id, username, display_name, pw_hash)
+    +get_user(user_id) / get_user_by_username(username)
+    +list_users() / delete_user(user_id)
+    +create_api_token(...) / get_api_token_by_hash(hash)
+    +list_api_tokens(user_id) / delete_api_token(id)
+    +close()
 }

+' -- Backends --
 class "SQLiteBackend" as SQLite <<sqlite>> {
-    - _engine: sa.Engine
-    - _fts5_available: bool
+    -_engine: sa.Engine
+    -_fts5_available: bool
+    +__init__(path: str)
    --
-    Fork clone: BEGIN IMMEDIATE
-    FTS5 refresh in same transaction
+    FTS5 full-text search
+    Default pool, check_same_thread=False
 }

 class "PostgreSQLBackend" as PG <<postgres>> {
-    - _engine: sa.Engine
+    -_engine: sa.Engine
+    +__init__(url: str, pool_size: int = 2,\n    max_overflow: int = 3)
    --
-    Fork clone: SERIALIZABLE + row locks
-    Retry SQLSTATE 40001 / 40P01
-    DML success uses RETURNING rows
+    tsvector + ILIKE search
+    Connection pooling (5 max per process)
 }

-class "_utils.py" as Utils <<helper>> {
-    + reconstruct_turns(rows) → list[Turn]
-    + recover_trajectory(turns) → list[Turn]
-    + reconstruct_turns_checkpointed(...)
-    + retain_attachment_refs(conn, ids)
-    + release_attachment_refs(conn, ids)
-    + clone_workstream_transaction(...) → ForkCloneSnapshot
-}
-
-class "ForkCloneExpectation" as Expectation <<lifecycle>> {
-    + persona_config
-    + project_id / name / writable
-    + source_reservation_token
-    + destination_reservation_token
-}
-
-class "ForkCloneSnapshot" as Snapshot <<lifecycle>> {
-    + turns: tuple[Turn, ...]
-    + config: dict[str, str]
-    + project_id: str | None
-}
-
-class "workstreams" as Workstreams <<schema>> {
-    ws_id PK
-    state: creating | live state | closed
-    user_id, node_id, kind, parent_ws_id
-    project_id, persona, alias, title
-}
-
-class "conversations" as Conversations <<schema>> {
-    canonical persisted Turn rows
-    provider_data + tool_calls mirror
-    event_id, source, is_error, meta
-    attachment-id ref list
+' -- Schema --
+class "_schema.py" as Schema <<schema>> {
+    +metadata: MetaData
+    +memories: Table
+    +conversations: Table
+    +workstreams: Table (node_id, alias, title,\n    state, skill_id)
+    +workstream_config: Table
+    +users: Table (username, password_hash)
+    +api_tokens: Table (token_hash, scopes)
+    +channel_users: Table (channel_type)
+    +scheduled_tasks: Table (..., skill)
    --
-    compaction marker:
-    source="compaction"
-    meta.watermark=<folded row id>
+    SQLAlchemy Core
+    Single source of truth
 }

-class "workstream_config" as WorkstreamConfig <<schema>> {
-    PK (ws_id, key)
-    stamped persona/session config
-    private durable incarnation fence:
-    __fork_destination_reservation
+' -- Migration --
+class "_migrate.py" as Migrate <<migration>> {
+    +run_migrations(storage, backend)
+    -_bootstrap_existing_sqlite()
+    --
+    Programmatic Alembic
+    Auto-bootstrap existing DBs
 }

-class "workstream_attachments" as Attachments <<schema>> {
-    content-addressed blob
-    attachment_id, bytes, kind
-    refcount
+class "migrations/" as Versions <<migration>> {
+    001_initial_schema.py
+    002_user_identity.py
 }

-class "projects + project_members" as Projects <<schema>> {
-    visibility / owner / membership
-    active project-memory envelope
+' -- Registry --
+class "_registry.py" as Registry {
+    -_storage: StorageBackend | None
+    +init_storage(backend, path, url) → StorageBackend
+    +get_storage() → StorageBackend
+    +reset_storage()
+    --
+    Auto-initializes SQLite
+    if not configured
 }

-class "SessionManager" as Manager <<lifecycle>> {
-    + create(..., defer_emit_created)
-    + commit_create(ws)
-    + discard(ws)
-    + reap_stale_creating_reservations(max_age=2h)
-    + open / close / delete
+' -- Facade --
+class "memory.py" as Facade <<facade>> {
+    +save_message()
+    +load_messages()
+    +register_workstream()
+    +update_workstream_state()
+    +save_workstream_config()
+    +save_memory() / delete_memory()
+    +search_memories()
+    +... (all delegated functions)
+    --
+    Thin delegation to
+    get_storage()
+    Silent failure behavior
 }

-class "ChatSession" as Session <<lifecycle>> {
-    + append canonical Turns
-    + compact / resume checkpoint
-    + fork_from_storage(...)
+' -- Consumers --
+class "session.py\nChatSession" as Session {
 }

-SQLite ..|> Storage
-PG ..|> Storage
-SQLite --> Utils
-PG --> Utils
+class "server.py\nWeb UI" as Server {
+}

-Storage --> Workstreams
-Storage --> Conversations
-Storage --> WorkstreamConfig
-Storage --> Attachments
-Storage --> Projects
+class "cli.py\nTerminal" as CLI {
+}

-Manager --> Storage : lifecycle reservation + state
-Session --> Storage : turn durability + resume
-Session --> Expectation : construction witness
-Storage --> Snapshot : atomic clone result
-Expectation --> Utils : checked inside transaction
-Utils --> Snapshot : builds
+' -- Relationships --
+SQLite ..|> SB
+PG ..|> SB

-note right of Manager
-  **Deferred create publication**
-  1. INSERT workstream as state="creating" and store a fresh
-     private token in the same transaction.
-  2. Construct UI/session and run attachment/fork gates while
-     ordinary list/open/history reads exclude the row.
-  3. finalize_deferred_create atomically applies config/alias.
-  4. publish_deferred_create compare-and-swaps creating → idle.
-  5. Only then emit ws_created.
+SQLite --> Schema : uses
+PG --> Schema : uses

-  Any normal prepublication failure immediately calls exact token-checked
-  deletion. The token survives publication as the row's incarnation fence:
-  rollback or later hard delete can never ABA-delete a replacement row.
-  A legacy row acquires the same private token atomically when rehydrate,
-  delete, or fork preflight takes its authoritative snapshot. Loaded hard
-  delete drains admitted session durability before its token-checked delete.
+Registry --> SB : creates
+Registry --> Migrate : calls
+
+Migrate --> Versions : applies
+Migrate --> Schema : references
+
+Facade --> Registry : get_storage()
+
+Session --> Facade : imports
+Server --> Facade : imports
+CLI --> Facade : imports
+
+' -- Config --
+note right of Registry
+  [database]
+  backend = "sqlite" | "postgresql"
+  url = "postgresql+psycopg://..."
+  path = ".turnstone.db"
+  pool_size = 2 (+ 3 overflow)
 end note

-note left of Manager
-  **Crash-abandoned hidden-create recovery**
-  • Boot pass; long-lived processes repeat every 5 min,
-    even when ordinary idle eviction is disabled.
-  • Candidates remain state="creating", are >2h old,
-    and are absent from the manager loaded/pending set.
-  • Live remote owners are protected. The current stable
-    node ID does not self-protect, enabling restart recovery.
-  • Unknown liveness or storage failure deletes nothing.
-  • One transaction rechecks state, age, and token, then
-    hard-deletes dependents and releases attachment refs.
-  • Tokenless legacy/corrupt rows use their locked durable
-    row as the incarnation fence and log a warning.
-  • Retention pruning excludes creating rows. Recovery never
-    closes or publishes them as live WorkstreamState values.
+note bottom of SQLite
+  Default backend.
+  Zero-config for
+  single-node / dev.
 end note

-note bottom of Utils
-  **Atomic fork clone**
-  • Reject a provisional source; compare the source incarnation captured
-    by canonical preflight; re-authorize project visibility and compare the
-    live session envelope inside the transaction.
-  • Require a same-owner, empty destination still in creating state
-    with the exact reservation token.
-  • Copy the checkpoint-bounded canonical trajectory and config;
-    retain every referenced attachment or roll everything back.
-  • Preserve/rebase a valid compaction checkpoint watermark and
-    return the exact snapshot installed into the live destination.
-end note
-
-note bottom of Conversations
-  Full transcript rows are never deleted by compaction. Normal resume
-  loads the latest valid [summary] + rows after its watermark; audit and
-  export can request the full marker-free history.
+note bottom of PG
+  Production backend.
+  Multi-node / Docker default.
+  Use PgBouncer (transaction mode)
+  for clusters > 50 nodes.
 end note

@enduml
@@ -1,153 +1,190 @@
@startuml
 !theme plain
-title Turnstone — User Authentication and Model-Backend Credentials
+title Turnstone — Authentication Architecture

 skinparam class {
    BackgroundColor<<core>> #E8EAF6
-    BackgroundColor<<token>> #C8E6C9
+    BackgroundColor<<jwt>> #C8E6C9
    BackgroundColor<<storage>> #B3E5FC
-    BackgroundColor<<runtime>> #FFE0B2
-    BackgroundColor<<model>> #F3E5F5
+    BackgroundColor<<endpoint>> #FFE0B2
+    BackgroundColor<<scope>> #F3E5F5
 }

-package "Request identity" {
-  class "AuthMiddleware / check_request()" as RequestAuth <<core>> {
-      Extract bearer or HttpOnly cookie
-      Validate audience + expiry
-      Check scope / permission
-      Publish AuthResult in request state
-  }
-
-  class "AuthResult" as AuthResult <<core>> {
-      + user_id: str
-      + scopes: frozenset[str]
-      + permissions: frozenset[str]
-      + token_source: str
-  }
-
-  class "JWT" as JWT <<token>> {
-      HS256, sub, aud, iat, exp
-      console proxy mints short-lived
-      server-audience identity
-  }
-
-  class "API / config token" as ApiToken <<token>> {
-      ts_* token: SHA-256 DB lookup
-      config token: constant-time compare
-  }
-
-  class "users / roles / api_tokens" as UserTables <<storage>> {
-      password hash + token hash
-      role-derived permissions
-  }
+' -- Core Auth --
+class "AuthConfig" as AC <<core>> {
+    +enabled: bool
+    +tokens: dict[str, str]
+    +check(token) → role | None
+    --
+    Static config-file tokens
+    hmac.compare_digest
 }

-package "Immutable model binding" {
-  class "ModelRegistry" as Registry <<model>> {
-      + resolve_binding(alias)
-      + generation: int
-      --
-      Atomically resolves client, provider,
-      model, ModelConfig, generation.
-  }
-
-  class "ModelConfig snapshot" as ModelConfig <<model>> {
-      + alias / provider / endpoint / static key
-      + auth_mode
-      + obo_audience
-      + obo_scopes
-      --
-      static | entra_obo | entra_app | rfc8693_obo
-  }
-
-  class "ModelLane" as Lane <<model>> {
-      + client / provider / model / capabilities
-      + backend_auth_config: ModelConfig
-      + backend_auth_resolver: Callable
-  }
-
-  class "Model definitions" as ModelTable <<storage>> {
-      DB + config-file definitions
-      encrypted protected fields
-  }
+class "AuthResult" as AR <<core>> {
+    +user_id: str
+    +scopes: frozenset[str]
+    +token_source: str
+    +has_scope(scope) → bool
 }

-package "Per-call credential resolution" {
-  class "resolve_model_backend_auth_token()" as Resolver <<runtime>> {
-      + alias + pinned ModelConfig
-      + initiating principal_id
-      + ConfigStore + mint client
-      → dynamic token | None | fail closed
-  }
-
-  class "Model mint client" as Mint <<runtime>> {
-      + mint_model_obo_token_sync(...)
-      + mint_app_token_sync(...)
-      --
-      Cached by alias / principal / grant leg;
-      retains refusal cause for diagnostics.
-  }
-
-  class "OIDC / OBO protected state" as OBOState <<storage>> {
-      encrypted user refresh credential
-      deployment Fernet key
-      configured grant profile
-  }
-
-  class "lane_call_client()" as CallClient <<runtime>> {
-      cancel check before mint
-      resolve once per plant call
-      cancel check after mint
-      client.with_options(api_key=token)
-  }
-
-  class "Provider SDK request" as ProviderCall <<runtime>> {
-      Anthropic: x-api-key
-      OpenAI-style: Authorization Bearer
-  }
+class "check_request()" as CR <<core>> {
+    auth_config, method, path,
+    auth_header, cookie_header,
+    jwt_secret, storage
+    → (allowed, status, msg, AuthResult)
+    --
+    1. Auth disabled → allow
+    2. Public path → allow
+    3. Extract Bearer / cookie
+    4. Detect token type
+    5. Validate → AuthResult
+    6. Check scope vs path
 }

-RequestAuth --> JWT : validates
-RequestAuth --> ApiToken : validates
-RequestAuth --> UserTables : lookup + permissions
-RequestAuth --> AuthResult : returns
+' -- Token Types --
+class "JWT (HS256)" as JWT <<jwt>> {
+    sub: user_id
+    scopes: "read,write,approve"
+    src: "password" | "database"
+    iat, exp (24h default)
+    --
+    Detected by: contains "."
+    Validated locally
+    No DB call
+}

-ModelTable --> Registry : load / hot reload
-Registry --> ModelConfig : immutable snapshot
-Registry --> Lane : coherent binding
+class "API Token" as AT <<jwt>> {
+    Format: ts_ + 64 hex
+    Stored: SHA-256 hash
+    --
+    Detected by: starts with "ts_"
+    Lookup by hash in DB
+    Expiry check
+}

-AuthResult --> Resolver : initiating principal
-Lane --> Resolver : callable + pinned config
-Resolver --> Mint : dynamic modes only
-Mint --> OBOState : decrypt / grant policy
-CallClient --> Lane
-CallClient --> Resolver
-CallClient --> ProviderCall : cloned SDK client
+class "Config Token" as CT <<core>> {
+    Raw value in memory
+    Role: "read" | "full"
+    --
+    Detected by: fallback
+    hmac.compare_digest
+    No DB needed
+}

-note right of Resolver
-  **Mode policy**
-  • static: return None; registry client's explicit key remains.
-  • entra_obo / rfc8693_obo: require an effective principal. HTTP
-    turns pin the authenticated initiator; single-user internal lanes
-    may use their session owner. Never borrow another generation's identity.
-  • entra_app: use deployment app identity, no user required.
-  • rfc8693_obo alone sends obo_scopes; each dynamic mode is paired
-    with its required Entra or RFC 8693 grant profile.
+' -- Scopes --
+class "Scope Hierarchy" as SH <<scope>> {
+    read: {read}
+    write: {read, write}
+    approve: {read, write, approve}
+    --
+    GET → read
+    POST write paths → write
+    POST /api/approve → approve
+    /api/admin/* → approve
+}
+
+' -- Storage --
+class "users" as UT <<storage>> {
+    user_id (PK)
+    username (unique)
+    display_name
+    password_hash (bcrypt)
+    created
+}
+
+class "api_tokens" as TT <<storage>> {
+    token_id (PK)
+    token_hash (SHA-256, unique)
+    token_prefix
+    user_id → users
+    name, scopes
+    created, expires
+}
+
+' -- Endpoints --
+class "POST /api/auth/login" as Login <<endpoint>> {
+    {username, password}
+    OR {token: "ts_xxx"}
+    → {jwt, role, scopes, user_id}
+    --
+    Sets HttpOnly cookie
+}
+
+class "GET /api/auth/status" as Status <<endpoint>> {
+    → {auth_enabled, has_users,
+       setup_required}
+    --
+    Public (no auth)
+    Drives UI setup wizard
+}
+
+class "POST /api/auth/setup" as Setup <<endpoint>> {
+    {username, display_name, password}
+    → {jwt, user_id, scopes}
+    --
+    Public (no auth)
+    Only when zero users exist
+    Returns 409 if already set up
+}
+
+class "Admin API (Console)" as Admin <<endpoint>> {
+    POST/GET/DELETE users
+    POST/GET tokens
+    DELETE tokens/{id}
+    --
+    Requires approve scope
+}
+
+' -- Relationships --
+CR --> AC : config tokens
+CR --> JWT : validate
+CR --> AT : hash lookup
+CR --> CT : hmac check
+CR --> AR : returns
+CR --> SH : checks
+
+Login --> JWT : issues
+Login --> UT : verify password
+Login --> TT : verify API token
+
+Setup --> UT : create first user
+Setup --> JWT : issues
+
+AT --> TT : lookup by hash
+Admin --> UT : CRUD
+Admin --> TT : CRUD
+
+AR --> SH : scopes from
+
+JWT ..> AR : produces
+AT ..> AR : produces
+CT ..> AR : produces
+
+note right of CR
+  **Middleware Flow**
+  AuthMiddleware on every request:
+  1. Extract token from header/cookie
+  2. Detect type (JWT / ts_ / config)
+  3. Validate → AuthResult
+  4. Set ctx_user_id for logging
+  5. Store auth_result in scope state
 end note

-note bottom of CallClient
-  Dynamic credentials are minted at dispatch, not cached in the registry
-  snapshot. Endpoint, audience, scopes, auth mode, and static-key presence stay
-  pinned to the same ModelConfig generation as the SDK client. The global
-  model.auth_fail_closed policy is read live on every mint. A Stop that wins
-  before or during mint prevents model bytes from being sent afterward.
+note bottom of SH
+  **Console** owns admin endpoints
+  **Server** validates JWT + config only
+  Both share JWT signing secret
 end note

-note bottom of ProviderCall
-  If minting fails, a configured fail-closed deployment or a keyless alias
-  raises BackendAuthUnavailableError. A dynamic alias with an explicit static
-  key may fall back only when policy allows. Authentication refusal is not a
-  backend-health failure and does not walk to a static fallback model.
+note left of JWT
+  **Console Proxy Token Minting**
+  When proxying requests to server nodes:
+  1. Console AuthMiddleware validates user JWT (aud: turnstone-console)
+  2. Proxy mints new JWT (aud: turnstone-server)
+     with real user_id, scopes, permissions
+  3. src: "console-proxy" for audit traceability
+  4. 5-minute expiry (fresh per request)
+  5. Fallback: ServiceTokenManager if no user context
 end note

@enduml
@@ -20,14 +20,11 @@ class "Discord" as Discord <<platform>> {
    asyncio event loop
 }

-class "Slack" as Slack <<platform>> {
-    Socket Mode WebSocket
+class "Slack (future)" as Slack <<platform>> {
+    Socket Mode / Events API
    Block Kit messages
-    Slash command (default /turnstone)
-    DM + channel events
    --
-    slack-bolt (Python)
-    asyncio event loop
+    Planned integration
 }

 class "Teams (future)" as Teams <<platform>> {
@@ -41,7 +38,7 @@ class "Teams (future)" as Teams <<platform>> {
 class "turnstone-channel" as ChannelService <<service>> {
    entry point: turnstone-channel
    --
-    One process — hosts one or more adapters
+    One process per platform
    asyncio event loop
    Structured logging (structlog)
    --log-level, --log-format
@@ -50,19 +47,6 @@ class "turnstone-channel" as ChannelService <<service>> {
    GET  /health
 }

-class "SlackBot" as SlackBot <<service>> {
-    +on_message(event)
-    +on_action(action)  (Block Kit buttons)
-    +send(channel_id, content)
-    +send_notification(channel_id, content, ws_id)
-    +run(bot_token, app_token)
-    --
-    slack-bolt AsyncApp
-    Socket Mode client
-    Per-user channel sessions via slash command
-    DM routing without slash command
-}
-
 class "DiscordBot" as Bot <<service>> {
    +on_message(msg)
    +on_interaction(interaction)
@@ -82,12 +66,10 @@ class "DiscordBot" as Bot <<service>> {
 }

 class "ChannelRouter" as Router <<service>> {
-    +get_or_create_workstream(channel_type, channel_id)
-    +_is_ws_live(ws_id)
-    +send_message(ws_id, message)
-    +send_approval(ws_id, ...)
-    +lookup_ws_id(channel_type, channel_id)
-    +resolve_user(channel_type, channel_user_id)
+    +resolve_route(platform, channel_id)
+        -> ws_id | None
+    +register_route(channel_id, ws_id)
+    +resolve_identity(platform, platform_user_id)
        -> user_id | None
    --
    Maps channels -> workstreams
@@ -95,22 +77,12 @@ class "ChannelRouter" as Router <<service>> {
    Caches routes in memory
 }

-class "turnstone-console router" as ConsoleRouter <<server>> {
-    POST /v1/api/route/workstreams/new
-    GET  /v1/api/route/workstreams/{ws_id}/live
-    POST /v1/api/route/workstreams/{ws_id}/send
-    POST /v1/api/route/workstreams/{ws_id}/approve
-    GET  /v1/api/route?ws_id=...
-    --
-    Multi-node rendezvous + durable overrides
-}
-
 ' -- Server --
 class "turnstone-server" as Server <<server>> {
-    POST /v1/api/workstreams/{ws_id}/send
-    POST /v1/api/workstreams/{ws_id}/approve
+    POST /v1/api/send
+    POST /v1/api/approve
    POST /v1/api/workstreams/new
-    GET  /v1/api/workstreams/{ws_id}/events
+    GET  /v1/api/events?ws_id=
    --
    LLM execution + tool use
    SSE event stream
@@ -160,23 +132,16 @@ Bot --> Router : on_message\non_interaction
 Router --> CU : resolve identity
 Router --> CR : resolve / register route

-Router --> Server : single-node/direct mode\ncreate + send + approve
-Router --> ConsoleRouter : multi-node mode\nroute create/live/send/approve/lookup
-ConsoleRouter --> Server : routed HTTP to owning node
-Bot --> Server : GET /v1/api/workstreams/{ws_id}/events\n(SSE via httpx-sse)
+Router --> Server : POST /v1/api/send\nPOST /v1/api/approve\nPOST /v1/api/workstreams/new
+Bot --> Server : GET /v1/api/events?ws_id=\n(SSE via httpx-sse)
 Server --> Bot : SSE event stream

 Bot --> Discord : reply / embed\nbutton callback

-Slack --> SlackBot : socket-mode\nevents
-SlackBot --> Router : on_message / on_action
-SlackBot --> Server : owning-node SSE after route lookup
-SlackBot --> Slack : post / update\nBlock Kit button callbacks
-
+Slack .[hidden]. Discord
 Teams .[hidden]. Slack

 ChannelService --> Bot : creates + runs
-ChannelService --> SlackBot : creates + runs
 ChannelService --> Router : creates
 ChannelService --> SVC : register / heartbeat /\nderegister

@@ -189,27 +154,25 @@ note right of Bot
  **Inbound Flow**
  1. Discord message arrives via gateway
  2. Bot.on_message() fires
-  3. ChannelRouter gets or creates channel -> ws_id
-     (direct server or multi-node console router)
+  3. ChannelRouter resolves channel -> ws_id
+     (or creates new workstream)
  4. ChannelRouter resolves platform user -> user_id
     via channel_users table
-  5. Router sends through the configured server/console SDK
+  5. Router sends POST /v1/api/send to server

-  **Stale-route recovery (evicted workstreams)**
-  1. Route health check reports the old ws unavailable
-  2. Existing ws_id becomes the fork source
+  **Workstream Resume (evicted workstreams)**
+  1. Stale route detected (no active SSE listener)
+  2. Existing ws_id reused directly from route
  3. POST /v1/api/workstreams/new with
     resume_ws=<ws_id>
-  4. Server atomically clones source history/config/
-     persona/project/attachment refs into a new ws_id
-  5. Router stores the new destination route; source is unchanged
-  6. If the source was pruned, retry one fresh create
+  4. Server resumes atomically during creation
+  5. SSE emits WorkstreamResumedEvent -> thread
 end note

 note right of Server
  **Outbound Flow**
  1. Server emits SSE events on
-     GET /v1/api/workstreams/{ws_id}/events
+     GET /v1/api/events?ws_id=
  2. Bot subscribes via httpx-sse
  3. Bot formats and sends to Discord thread
 end note
@@ -220,7 +183,7 @@ note bottom of CR
  2. Bot renders Discord buttons (Approve / Deny)
  3. User clicks button -> on_interaction()
  4. Router builds ApproveMessage
-  5. Router sends POST /v1/api/workstreams/{ws_id}/approve to server
+  5. Router sends POST /v1/api/approve to server
 end note

 note bottom of CU
@@ -11,7 +11,7 @@ skinparam participant {

 participant "ChatSession\n(session.py)" as Session <<session>>
 participant "WatchRunner\n(watch.py)" as Runner <<server>>
-participant "StorageBackend\n(SQLite / PostgreSQL)" as Storage <<storage>>
+participant "StorageBackend\n(SQLite)" as Storage <<storage>>
 participant "WebUI / SSE\n(server.py)" as UI <<ui>>

 == Create Phase ==
@@ -130,7 +130,7 @@ note right : action="cancel" (auto-approve)
 note over Runner, Storage
  **Startup:**
  1. WatchRunner created in main() with storage + node_id
-  2. restore_fn closure captures SessionManager
+  2. restore_fn closure captures WorkstreamManager
  3. Initial workstream: session.set_watch_runner(runner)
  4. _lifespan(): runner.start() — daemon thread begins

@@ -152,34 +152,10 @@ MCPMgr -> MCPSrv : prompts/get
 MCPSrv --> MCPMgr : GetPromptResult
 MCPMgr --> Session : messages [{role, content}]

-== Resilience: Circuit Breaker & Stream Safety ==
-
-note over MCPMgr
-  **Per-server circuit breaker**
-  CLOSED --(3 failures)--> OPEN
-  OPEN --(cooldown expires)--> half-open probe
-  Probe success --> CLOSED (trip_count decays by 1)
-  Probe failure --> OPEN (cooldown doubles, max 5 min)
-
-  McpError (protocol) does NOT trip breaker.
-  BrokenPipeError / EOFError evicts dead session.
-  All sync methods cancel orphaned futures on timeout.
-  Transport streams pre-closed before stack teardown
-  to avoid anyio cancel-scope CPU busy-loop (SDK #2147).
-end note
-
-Session -> MCPMgr : call_tool_sync()
-MCPMgr -> MCPMgr : _cb_gate(server)\n[reject if circuit open]
-MCPMgr -> MCPMgr : _cb_auto_reconnect()\n[if session gone + cooldown expired]
-MCPMgr -> MCPSrv : tools/call
-MCPSrv --> MCPMgr : result or error
-MCPMgr -> MCPMgr : _cb_record_success()\nor _cb_record_failure()
-
 == Three-Tier Refresh ==

-group Push Notifications (debounced 5s per server)
+group Push Notifications
  MCPSrv -> MCPMgr : ToolListChangedNotification
-  MCPMgr -> MCPMgr : debounce check\n(skip if < 5s since last)
  MCPMgr -> MCPMgr : _refresh_server_tools()

  MCPSrv -> MCPMgr : ResourceListChangedNotification
@@ -190,25 +166,18 @@ group Push Notifications (debounced 5s per server)
  MCPMgr -> Storage : sync_prompts_to_storage()
 end

-group Manual Refresh
-  Session -> MCPMgr : refresh_sync()
+group Periodic Polling (default 4h)
+  MCPMgr -> MCPMgr : _periodic_refresh()
  note right
-    /mcp refresh [server] —
-    re-fetches catalog and
-    attempts reconnect for
-    disconnected servers.
+    Only polls capabilities
+    without push support.
+    Staggered per-server.
  end note
 end

-group Manual Reconnect
-  Session -> MCPMgr : reconnect_sync(name)
-  note right
-    Operator-driven via the
-    console admin panel —
-    tears down session, clears
-    circuit breaker, runs a
-    fresh handshake.
-  end note
+group Manual Refresh
+  Session -> MCPMgr : refresh_sync()
+  note right: /mcp refresh [server]
 end

 == Policy Evaluation ==
@@ -1,126 +1,218 @@
@startuml
 !theme plain
-title Turnstone — Intent Judge, Concurrent Approval Cycles, and Output Guard
+title Turnstone — Intent Validation (Judge) Architecture

-skinparam sequenceArrowThickness 1.5
-skinparam sequenceLifeLineBackgroundColor #F5F5F5
+skinparam participant {
+    BackgroundColor<<session>> #C8E6C9
+    BackgroundColor<<judge>> #FFE0B2
+    BackgroundColor<<storage>> #B3E5FC
+    BackgroundColor<<ui>> #E8EAF6
+    BackgroundColor<<fs>> #F5F5F5
+}

-participant "ChatSession\ngeneration N" as Session
-participant "SessionUIBase" as UI
-participant "IntentJudge" as Judge
-participant "model_turn()\n(pinned ModelLane)" as Model
-participant "Operator / client" as Operator
-participant "OutputGuardJudge" as Guard
-database "StorageBackend" as Storage
+participant "ChatSession\n(session.py)" as Session <<session>>
+participant "IntentJudge\n(judge.py)" as Judge <<judge>>
+participant "LLM Provider\n(provider)" as LLM <<judge>>
+participant "StorageBackend\n(SQLite)" as Storage <<storage>>
+participant "WebUI / SSE\n(server.py)" as UI <<ui>>
+participant "Filesystem" as FS <<fs>>

-== Intent assessment begins during preparation ==
+== Tool Call Requires Approval ==

-Session -> Session : prepare each tool item independently\nattach principal + cancel witness
-Session -> Judge : evaluate(items, callback, cancel_ref)
-activate Judge
-Judge -> Judge : synchronous heuristic verdict\nfor each call (first matching rule)
-Judge --> Session : heuristic verdicts + daemon cancel event
-Session -> UI : cache / publish heuristic assessments
-Session -> Storage : persist heuristic intent verdicts
-
-note over Judge, Model
-  The judge owns an immutable resolved binding. Registry/config generations
-  are freshness watermarks: an effective lane change replaces the judge for
-  the next batch, while in-flight work keeps the lane it started with.
-  Dynamic backend auth is resolved for this batch's initiating principal.
-  parallel_evaluations (1-16) sets per-batch worker width; the model alias's
-  admission gate remains the process-wide generation ceiling.
+Session -> Session : _prepare_tool_calls()
+note right
+  Tool calls parsed from
+  LLM response. Auto-approved
+  tools dispatched immediately.
+  Remaining items need approval.
 end note

-par LLM judge daemon coordinator
-  Judge -> Judge : start min(batch size, parallel_evaluations,\npositive alias capacity) workers
-  loop each worker claims one independent call
-    Judge -> Model : model_turn(judge lane, canonical Turns,\nread-only evidence tools, cancel_ref)
-    Model --> Judge : ModelTurnResult
-    alt evidence tool requested
-      Judge -> Judge : execute bounded read_file / list_directory
-    else verdict text
-      Judge -> Judge : parse + arbitrate against heuristic
+Session -> Session : _evaluate_intent(pending_items)
+
+== Tier 1: Heuristic (synchronous, sub-ms) ==
+
+Session -> Judge : evaluate(items, messages, callback)
+
+Judge -> Judge : evaluate_heuristic()\nfor each item
+note right
+  **36 rules (first match wins):**
+  Critical (0.90, deny): rm /, mkfs,
+    dd, pipe-to-shell, chmod 777 /,
+    write/edit /etc/ .ssh/,
+    download-then-execute chains
+  High (0.80, review): sudo, kill -9,
+    destructive git, DROP TABLE,
+    secrets, HTTP mutations, ssh/scp,
+    browser+data-export, transitive
+    install, control-plane mutation
+  Medium (0.70, review): content
+    ingestion, interpreter exec,
+    cloud CLI mutations, pkg install,
+    write_file, MCP tools, docker ops
+  Low (0.85, approve): read_file,
+    list_directory, search, recall,
+    tool_search, read_resource,
+    web_search, read-only bash
+  Default: medium, 0.50, review
+end note
+
+Judge --> Session : heuristic_verdicts[]
+
+Session -> Session : attach _heuristic_verdict\nto each pending item
+
+Session -> UI : SSE: approve_request\n{items: [{verdict: ...}],\n judge_pending: true}
+note right
+  Heuristic verdict displayed
+  immediately as risk badge.
+  Spinner shown while LLM
+  judge evaluates.
+end note
+
+Session -> Storage : create_intent_verdict()\nfor each heuristic verdict
+
+== Tier 2: LLM Judge (daemon thread, async) ==
+
+Judge -> Judge : spawn daemon thread\n"intent-judge"
+
+note over Judge, LLM
+  **Context preparation:**
+  1. FIFO-truncate conversation history
+     to max_context_ratio of context window
+  2. Append tool call details as user message
+  3. System prompt defines judge role + JSON schema
+end note
+
+loop up to 3 turns (timeout budget)
+
+    Judge -> LLM : create_completion(\nmodel, judge_messages,\ntools=[read_file, list_directory])
+    LLM --> Judge : CompletionResult
+
+    alt tool_calls present (turn < 3)
+        Judge -> Judge : _exec_read_only_tool()
+        note right
+          **Security hardening:**
+          Blocked: /etc/, /root/,
+          /proc/, /sys/, /dev/,
+          .ssh, .gnupg, .aws,
+          *.pem, *.key, *.p12
+          File cap: 32KB
+          Dir cap: 200 entries
+        end note
+        Judge -> FS : read_file / list_directory
+        FS --> Judge : file contents
+        Judge -> Judge : append tool result\nto judge_messages
+    else text response (final verdict)
+        Judge -> Judge : _parse_verdict()
+        note right
+          **4-stage JSON parsing:**
+          1. Direct JSON.loads
+          2. Markdown code block
+          3. Brace-counting
+          4. Regex field extraction
+        end note
    end
-    Judge --> UI : on_intent_verdict(verdict, judge generation)
-    UI -> Storage : persist LLM verdict / audit update
-  end
-else approval path continues
-  Session -> UI : approve_tools(items) with one\nSmart Approval config snapshot
+
 end

-== Policy, Smart Approval, and human gate ==
+== Tier 3: Arbitration ==

-UI -> UI : apply explicit policy / skill / always / blanket bypasses
-opt Smart Approvals enabled
-  UI -> UI : wait within captured deadline for this batch's verdicts
-  UI -> UI : auto-approve only recommendation=approve\nand confidence >= captured threshold
-  UI -> Storage : persist auto-approval reason and decision
-end
-
-alt human-gated items remain
-  UI -> UI : acquire publication lease; register ApprovalCycle\n(cycle_id, call_ids, event, result, witnesses)
-  UI -> Operator : approve_request with cycle_id + item verdicts
-  Operator -> UI : approve / deny by cycle_id or call_id
-  UI -> UI : atomically claim exactly one unresolved cycle
-  UI -> Operator : approval_resolved
-  UI --> Session : decision + optional feedback
-  UI -> Storage : stamp tracked verdicts with operator decision
-else every item bypassed / auto-approved
-  UI -> Operator : tool_info with exact auto_approve_reason
-  UI --> Session : approved
-end
-
-note right of UI
-  Parallel task agents may register several ApprovalCycles. Each cycle owns
-  its own Event and result slot. A legacy selector-less decision targets the
-  oldest cycle; double resolution is a no-op. Cached LLM verdicts carry their
-  judge generation, so reused provider call ids cannot satisfy a new cycle.
+Judge -> Judge : compare confidence:\nLLM vs heuristic
+note right
+  Only deliver LLM verdict
+  if confidence > heuristic.
+  Otherwise heuristic stands.
 end note

-== Cancellation boundary ==
-
-opt Stop / close / force-successor
-  Session -> Judge : abort all judge events owned by the cancelled operation
-  Session -> UI : resolve_all_approvals(False, "cancelled")
-  UI -> UI : block new admission leases; wait for admitted bundles;\nclaim only cycles whose cancellation witness is aborted
-  UI -> Operator : one cancelled resolution per claimed cycle
-  note over Session, UI
-    A Stop can win before cycle registration, during publication, or while a
-    click resolves. The witness + admission sweep makes exactly one terminal
-    outcome visible; a successor generation's new cycle is not swept.
-  end note
+alt LLM confidence > heuristic confidence
+    Judge -> Session : callback(llm_verdict)
+    Session -> UI : SSE: intent_verdict\n{tier: "llm", ...}
+    note right
+      UI replaces heuristic badge
+      with LLM verdict. Spinner
+      resolves to final assessment.
+    end note
+    Session -> Storage : create_intent_verdict()\nfor LLM verdict
 end

-note over Judge
-  Normal operator resolution does not necessarily cancel judge inference.
-  With cancel_on_approval=false, the daemon finishes and late verdicts remain
-  auditable. With it enabled, the batch event stops remaining judge work.
+== User Decision ==
+
+UI -> Session : resolve_approval(\napproved, feedback)
+
+Session -> Storage : update_intent_verdict(\nverdict_id, user_decision)
+note right
+  All tracked verdicts
+  (heuristic + LLM) updated
+  with "approved" or "denied".
+  Swap-and-clear avoids racing
+  with daemon judge thread.
 end note

-deactivate Judge
+== Tool Execution ==

-== Tool output guard ==
+Session -> Session : _execute_tools()
+note right
+  Tools execute with
+  user approval.
+end note

-Session -> Session : execute admitted tools; truncate each result
-Session -> Guard : evaluate(result, tool context, cancel event)
-activate Guard
-Guard -> Guard : heuristic checks first
-opt LLM guard enabled and time remains
-  Guard -> Model : model_turn(output-guard lane, bounded prompt, cancel_ref)
-  Model --> Guard : structured verdict
+== Output Guard (synchronous, time-budgeted) ==
+
+Session -> Session : _evaluate_output()\nfor each tool result
+note right
+  **Priority-ordered checks (5s budget):**
+  P1: Prompt injection (role injection,
+    override phrases, instruction tags)
+  P2: Credential leakage (API keys,
+    PEM blocks, connection strings)
+  P3: Encoded payloads (data URIs,
+    hex shellcode)
+  P4: Adversarial URLs (cloud metadata,
+    credential query params)
+  P5: System info disclosure (private
+    IPs, sensitive paths)
+
+  Annotates + optionally redacts.
+  Does NOT gate.
+end note
+
+alt output_warning flags detected
+    Session -> UI : SSE: output_warning\n{call_id, risk_level, flags,\nfunc_name, redacted}
+    note right
+      Credential values replaced
+      with [REDACTED:<type>] before
+      output enters conversation.
+      sanitized text excluded from
+      SSE payload (defense in depth).
+    end note
+    UI -> Storage : record_output_assessment()\nfire-and-forget persistence
+    note right
+      Stored: flags, risk_level,
+      annotations, output_length,
+      redacted (bool). Raw tool
+      output is never stored.
+    end note
 end
-Guard --> Session : assessment / redaction / warning
-deactivate Guard
-Session -> Session : re-check generation N before folding result
-Session -> UI : output warning (no raw secret payload)
-Session -> Storage : persist assessment + guarded Tool Turn metadata

-note over Guard, Storage
-  Output-guard objects also pin model/config lanes. Replacement retires the
-  old object but lets admitted evaluations drain before its private client is
-  closed. A cancelled or superseded evaluation cannot fold into the successor
-  trajectory. Raw pre-redaction secrets are never stored in assessment rows.
+== Lifecycle ==
+
+note over Session, Judge
+  **Lazy initialization:**
+  IntentJudge created on first approval if judge_config.enabled.
+  Re-uses session's provider/client by default (self-consistency).
+  Cross-model: separate provider/client from [judge] config.
+
+  **Sub-agent exemption:**
+  Plan agent and task agent skip intent validation entirely.
+
+  **Output guard:**
+  Runs when judge_config.output_guard is true (default).
+  Credential redaction when judge_config.redact_secrets is true.
+
+  **Storage:**
+  intent_verdicts table (migration 012), output_assessments table
+  (migration 022). Both queryable via admin API endpoints
+  (requires admin.judge permission). Skills store scan_status,
+  scan_report, scan_version for install-time risk assessment.
 end note

@enduml
@@ -13,68 +13,65 @@ skinparam participant {
 participant "ChatSession\n(session.py)" as Session <<session>>
 participant "MemoryFacade\n(memory.py)" as Facade <<facade>>
 participant "MemoryRelevance\n(memory_relevance.py)" as Relevance <<facade>>
-participant "StorageBackend\n(SQLite / PostgreSQL)" as Storage <<storage>>
+participant "StorageBackend\n(SQLite)" as Storage <<storage>>
 participant "Server API\n(server.py)" as API <<api>>
 participant "Console Admin\n(console/server.py)" as Admin <<api>>
 participant "SDK Client\n(sdk/)" as SDK <<sdk>>

 == Phase 1: Tool Path (session.send) ==

-Session -> Session : pin acting principal\nparse memory(action=...)
+Session -> Session : _prepare_tool_calls()\nparse memory(action=...)
 note right
-  Tool schema: 5 actions
-  save, get, search, delete, list
+  Tool schema: 4 actions
+  save, search, delete, list
  Auto-approved (no approval needed)
 end note

-Session -> Session : resolve live project access\nselect exact/inherited scope
-
 Session -> Session : _exec_memory(item)

 alt action = save
-    Session -> Session : require non-empty description
-    Session -> Facade : save_structured_memory_strict(\n..., require_active_project)
+    Session -> Facade : save_structured_memory(\nname, content, description,\nmem_type, scope, scope_id)
    Facade -> Facade : normalize_key(name)
-    Facade -> Storage : guarded atomic upsert\nON CONFLICT ... RETURNING
-    Storage --> Facade : (saved row, was_update)
-    Facade --> Session : saved row
-    Session -> Session : invalidate prefix/cache\naudit acting principal
-end
-
-alt action = get
-    Session -> Facade : get_structured_memory_by_name_strict()
-    Facade -> Storage : exact scoped-name lookup
-    Storage --> Session : full row / not found
+    Facade -> Storage : create_structured_memory()
+    alt unique constraint violation
+        Storage --> Facade : IntegrityError
+        Facade -> Storage : get_structured_memory_by_name()
+        Storage --> Facade : existing row
+        Facade -> Storage : update_structured_memory()
+    end
+    Storage --> Facade : memory_id
+    Facade --> Session : (memory_id, old_content)
+    Session -> Session : _init_system_messages()\nrefresh BM25 context
 end

 alt action = search
-    Session -> Storage : search exact scope or\nactor-visible scope union
+    Session -> Facade : search_structured_memories(\nquery, mem_type, scope,\nscope_id, limit)
+    Facade -> Storage : search_structured_memories()
    Storage --> Session : matched rows
 end

 alt action = delete
-    Session -> Facade : delete_structured_memory_returning_strict()
-    Facade -> Storage : DELETE ... RETURNING
-    Storage --> Session : deleted row / not found
-    Session -> Session : invalidate + audit\nmark prefix dirty
+    Session -> Facade : delete_structured_memory(\nname, scope, scope_id)
+    Facade -> Storage : delete_structured_memory()
+    Storage --> Session : bool (existed)
+    Session -> Session : _init_system_messages()\nrefresh BM25 context
 end

 == Phase 2: BM25 Relevance Injection ==

 Session -> Session : _init_system_messages()\nevery conversation turn

-Session -> Session : resolve acting principal\nand live project ACL
 Session -> Session : _list_visible_memories(\nlimit=fetch_limit)
 note right
  **Scope resolution:**
-  Interactive: global + workstream
-  + acting user + readable project
-  Coordinator: acting user's coordinator
-  + readable project
+  1. global scope (always)
+  2. workstream scope (ws_id)
+  3. user scope (user_id, if auth)
+  Combined and deduplicated.
 end note

-Session -> Facade : list_visible_structured_memories()
-Facade -> Storage : one visibility-union query
+Session -> Facade : list_structured_memories()\nper scope
+Facade -> Storage : list_structured_memories()
 Storage --> Session : up to fetch_limit rows

 Session -> Relevance : extract_recent_context(\nmessages, max_messages=3)
@@ -106,31 +103,28 @@ Session -> Session : inject into\nsystem message

 == Phase 3: Server API Path ==

-SDK -> API : GET /v1/api/memories\n?type=general&limit=20
-API -> API : bind scope to caller\ndefault global + caller user
-API -> Storage : list visible rows
+SDK -> API : GET /v1/api/memories\n?type=project&limit=20
+API -> Facade : list_structured_memories()
+Facade -> Storage : list_structured_memories()
 Storage --> API : rows
 API --> SDK : {"memories": [...], "total": N}

-SDK -> API : POST /v1/api/memories\n{name, content, description, ...}
-API -> API : validate type, scope,\nname/content/description
-API -> API : reject internal scopes\nowner-bind workstream scope
-API -> Facade : save_structured_memory_strict()
-Facade -> Storage : atomic upsert
+SDK -> API : POST /v1/api/memories\n{name, content, ...}
+API -> API : validate type, scope,\nname length, content length
+API -> Facade : save_structured_memory()
+Facade -> Storage : create / update
 Storage --> API : memory row
-API -> API : record_audit(actor)
 API --> SDK : 201 (created) / 200 (updated)

 SDK -> API : POST /v1/api/memories/search\n{query, type, ...}
-API -> API : bind scope to caller
-API -> Storage : search visible rows
+API -> Facade : search_structured_memories()
+Facade -> Storage : search_structured_memories()
 Storage --> API : matched rows
 API --> SDK : {"memories": [...], "total": N}

 SDK -> API : DELETE /v1/api/memories/{name}\n?scope=global
-API -> Facade : delete_structured_memory_returning_strict()
-Facade -> Storage : DELETE ... RETURNING
-API -> API : record_audit(actor)
+API -> Facade : delete_structured_memory()
+Facade -> Storage : delete row
 API --> SDK : {"status": "ok"}

 == Phase 4: Console Admin Path ==
@@ -147,7 +141,7 @@ Storage --> Admin : memory row
 Admin --> SDK : memory JSON

 SDK -> Admin : DELETE /v1/api/admin/memories/{id}
-Admin -> Storage : delete_structured_memory_by_id_returning()
+Admin -> Storage : delete_structured_memory_by_id()
 Admin -> Admin : record_audit(\n"memory.delete")
 Admin --> SDK : {"status": "ok"}

@@ -13,7 +13,7 @@ skinparam participant {
 participant "Server\n(main)" as Server <<session>>
 participant "ConfigStore\n(config_store.py)" as Store <<config>>
 participant "SettingsRegistry\n(settings_registry.py)" as Registry <<config>>
-participant "StorageBackend\n(SQLite / PostgreSQL)" as Storage <<storage>>
+participant "StorageBackend\n(SQLite)" as Storage <<storage>>
 participant "Console Admin\n(console/server.py)" as Admin <<api>>
 participant "SDK Client\n(sdk/)" as SDK <<sdk>>
 participant "ChatSession\n(session.py)" as Session <<session>>
@@ -57,10 +57,9 @@ else key not in cache
    Store --> Session : default value
 end
 note right of Session
-  Most session settings are captured once
-  at workstream creation. Documented live readers
-  (including model.auth_fail_closed per mint)
-  apply immediately.
+  Settings are captured once
+  at workstream creation.
+  Not re-read on every turn.
 end note

 == Phase 3: Admin API — List / Schema ==
@@ -129,9 +128,8 @@ Store -> Storage : get_system_settings_bulk(node_id)
 Storage --> Store : all settings
 Store -> Store : rebuild cache,\nswap atomically,\nincrement _version
 note right
-  Most existing-session settings are unchanged
-  (frozen at creation time); documented
-  live readers apply immediately.
+  Existing sessions: unchanged
+  (frozen at creation time).
  New sessions: pick up
  updated values immediately.
 end note
@@ -1,89 +0,0 @@
-@startuml
-title Turnstone - coordinator wait_for_workstream lifecycle
-
-skinparam sequenceArrowThickness 1.5
-skinparam noteBackgroundColor #FDF6E3
-
-participant "Coordinator\nLLM" as LLM
-participant "ChatSession\n(worker thread)" as CS
-participant "CoordinatorClient" as CC
-participant "SessionUI\n(SSE fanout)" as UI
-participant "Console routing\nproxy" as RP
-database "Storage\n(workstreams row)" as DB
-participant "Child\nnode" as NODE
-
-== Spawn ==
-
-LLM -> CS : tool_call spawn_workstream(...)
-activate CS
-CS -> CC : spawn(initial_message=...,\nparent_ws_id=coord, user_id=...)
-CC -> RP : POST /v1/api/route/workstreams/new
-RP -> NODE : dispatch (rendezvous)
-NODE -> DB : insert workstreams row\nstate='running'
-RP --> CC : {ws_id, node_id, name, status: 200}
-CC --> CS : {ws_id, ...}
-CS -> UI : on_tool_result\n("spawn_workstream", ws_id)
-deactivate CS
-
-note right of LLM
-  Model now knows the child ws_id.
-  It can inspect / send / wait, and
-  the parent registry tracks it.
-end note
-
-== Wait (blocking) ==
-
-LLM -> CS : tool_call wait_for_workstream\n(ws_ids=[child], mode="any", timeout=60)
-activate CS
-CS -> CS : _prepare_wait_for_workstream\n(validate ws_ids, timeout, mode)
-CS -> UI : emit wait_started\n{call_id, ws_ids, mode, timeout}
-
-CS -> CC : wait_for_workstream(ws_ids, timeout,\nmode, progress_callback)
-activate CC
-
-loop every 500ms up to timeout
-    CC -> DB : read workstreams row(s)
-    DB --> CC : {state, updated, tokens, ...}
-    alt state in {idle, error, closed, deleted}
-        note over CC
-          real-terminal state ->
-          completion condition met
-        end note
-    else still running / thinking / attention
-        CC -> CS : progress_callback(snap)\n(diff-on-change or 5s heartbeat)
-        CS -> UI : emit wait_progress\n{call_id, elapsed, results?}
-    end
-end
-
-CC --> CS : {complete, elapsed,\nresults: {ws_id: snap}}
-deactivate CC
-
-CS -> UI : emit wait_ended\n{call_id, complete, elapsed, results}
-CS -> UI : on_tool_result\n("wait_for_workstream",\n"complete after Ns (R/N resolved)")
-CS --> LLM : tool_result (full results dict)
-deactivate CS
-
-note left of UI
-  Sidebar "waiting on N children" indicator
-  keys on call_id - started / progress / ended
-  scope to a single wait invocation so
-  nested waits render independent badges.
-end note
-
-== After wait: inspect + close ==
-
-LLM -> CS : tool_call inspect_workstream(ws_id=child)
-CS -> CC : inspect(ws_id)
-CC -> DB : read row + tail
-CC --> CS : {state, messages, tokens, ...}
-CS --> LLM : tool_result (serialised)
-
-LLM -> CS : tool_call close_workstream\n(ws_id=child, reason="...")
-CS -> CC : close_workstream(ws_id, reason)
-CC -> RP : POST /v1/api/route/workstreams/close
-RP -> NODE : dispatch
-NODE -> DB : state='closed',\nclose_reason='...'
-RP --> CC : {status: 200}
-CC --> CS : {closed: true, status: 200, reason: ...}
-CS --> LLM : tool_result
-@enduml
@@ -88,7 +88,7 @@
    <rect x="300" y="151" width="160" height="2" fill="#161b22"/>
    <text x="380" y="178" text-anchor="middle" fill="#e6edf3" font-size="11" font-weight="600">Console</text>
    <line x1="318" y1="190" x2="442" y2="190" stroke="#30363d" stroke-width="1"/>
-    <text x="380" y="208" text-anchor="middle" fill="#8b949e" font-size="9">FNV-1a rendezvous router</text>
+    <text x="380" y="208" text-anchor="middle" fill="#8b949e" font-size="9">hash-ring router</text>
    <text x="380" y="223" text-anchor="middle" fill="#8b949e" font-size="9">cluster dashboard</text>
    <text x="380" y="238" text-anchor="middle" fill="#8b949e" font-size="9">reverse proxy</text>
    <line x1="318" y1="250" x2="442" y2="250" stroke="#30363d" stroke-width="1"/>
@@ -115,7 +115,7 @@
    <rect x="608" y="162" width="184" height="28" rx="3" fill="#1c2128" stroke="#30363d" stroke-width="1"/>
    <text x="700" y="180" text-anchor="middle" fill="#8b949e" font-size="9">turnstone-server :8080</text>
    <!-- Tools label -->
-    <text x="700" y="206" text-anchor="middle" fill="#484f58" font-size="8">model lanes + tools / MCP</text>
+    <text x="700" y="206" text-anchor="middle" fill="#484f58" font-size="8">19 tools + MCP</text>
  </g>

  <!-- Node B -->
@@ -130,7 +130,7 @@
    <rect x="608" y="282" width="184" height="28" rx="3" fill="#1c2128" stroke="#30363d" stroke-width="1"/>
    <text x="700" y="300" text-anchor="middle" fill="#8b949e" font-size="9">turnstone-server :8080</text>
    <!-- Tools label -->
-    <text x="700" y="326" text-anchor="middle" fill="#484f58" font-size="8">model lanes + tools / MCP</text>
+    <text x="700" y="326" text-anchor="middle" fill="#484f58" font-size="8">19 tools + MCP</text>
  </g>

  <!-- ==================== LLM PROVIDERS ==================== -->
@@ -171,7 +171,7 @@
    <rect x="590" y="450" width="220" height="5" fill="#bc8cff"/>
    <rect x="590" y="453" width="220" height="2" fill="#161b22"/>
    <text x="700" y="476" text-anchor="middle" fill="#e6edf3" font-size="11" font-weight="600">PostgreSQL / SQLite</text>
-    <text x="700" y="492" text-anchor="middle" fill="#8b949e" font-size="9">workstreams, turns, config, auth</text>
+    <text x="700" y="492" text-anchor="middle" fill="#8b949e" font-size="9">conversations, memory, auth</text>
  </g>
  <text x="700" y="444" text-anchor="middle" fill="#bc8cff" font-size="9" font-weight="600" letter-spacing="2">STORAGE</text>

@@ -239,7 +239,7 @@
  <!-- Routing rules at bottom, left-aligned -->
  <text x="44" y="456" fill="#30363d" font-size="9" font-weight="600" letter-spacing="1">ROUTING</text>
  <circle cx="44" cy="474" r="3" fill="#3fb950" opacity="0.6"/>
-  <text x="54" y="477" fill="#484f58" font-size="9">control plane: client &#x2192; console &#x2192; server node (FNV-1a rendezvous placement)</text>
+  <text x="54" y="477" fill="#484f58" font-size="9">control plane: client &#x2192; console &#x2192; server node (hash-ring bucket lookup)</text>
  <circle cx="44" cy="494" r="3" fill="#58a6ff" opacity="0.6"/>
  <text x="54" y="497" fill="#484f58" font-size="9">data plane: client &#x2192; server node (direct SSE, node_url from create response)</text>
  <circle cx="44" cy="514" r="3" fill="#f47067" opacity="0.6"/>
@@ -1,3 +0,0 @@
-version https://git-lfs.github.com/spec/v1
-oid sha256:6e2bfdf968e96f3720ed58674103288e2f57e9c056f5c479a57f37a849f3e69c
-size 821878
@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:b8c1460440784f07e30afea32d4ee17687627df46a24003d761ad79c2676a361
-size 169499
+oid sha256:881a8b9bce67b5af9a52d5e50deaa72351cd99c76f18aad5caeb2b61131ca1af
+size 119798
@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:66847ccdf10ef2bd04e93bc0d3924a56ce28462ec9e76a383b53aee4500755e8
-size 631799
+oid sha256:75da80e6bd205e45b9fe48aa2f87197110c908f44e1d98c52eee69f956274711
+size 400402
@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:c74e99c530c3a8af9ab35b1e4d8c4fef0ea35c0c04cc35da7cf3588e71382057
-size 661175
+oid sha256:6471e611beebf647f3a191eb16588571a404cc52a43067883a2b6f06dd936376
+size 594676
@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:6261604cc8b75878a8704308929ea64d121cf26547019543fbe1b21cbe700415
-size 189791
+oid sha256:3aa8d972bba40d78152f9f0c762b9f5ec616d8052c45fa52b7dd1c679ed81d61
+size 325245
@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:1b3b7b745f6006ee73d4b31fa598faa0d71ffb74ce349ab08eb3ce09ded506c3
-size 266294
+oid sha256:674712a0563f51837383184652efeb28b7bec13378be636e89d2959bfba39d1e
+size 281519
@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:33dddd8cd8b53fa464cc8a4c899896fee32035d63e0669fe327969e3356349c7
-size 329815
+oid sha256:04d2069a9b5155ad1e7d842147fd78535ad9106d6856520439c33a9868a47499
+size 156694
@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:16e3f3bfa0a6af637f7a9fb6765d594eb598428679c88a429c096c3dbae931e4
-size 181185
+oid sha256:a872556d111185f4531d1b68ee892b4ce5042d7ccf277e2cad08beb6932c9803
+size 191144
@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:59f14b835665244f3d32981b6c1ac4c4380393a83cc519e271831622aa3f261a
-size 197433
+oid sha256:e7c3e40c10425d721f833390ae3531c09af501157fd3142531ba4eba86ff719d
+size 197112
@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:1a510eeaabf4ed8dab3b268c8f6bb5b7fef629a664361f7fb5614a6b498db36e
-size 294415
+oid sha256:b047cdc318c505f0f0895a65e14c5cc7552716053055cca57fa0a77db150e618
+size 255458
@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:ea86c6b6c68ed96f6fd18543d2e7a873f4715332cc3a7d4df167392f668a2de7
-size 232403
+oid sha256:af5ab3126bf685afe68e24bc4b0ed97371d0ebdb77bf4d76c0331ab120580cc0
+size 248809
@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:edf02b97e1e1287ebba9e74b9858474dcda42e5542656e505ea133a5b2416f47
-size 402992
+oid sha256:8a5957b71822656098cbe779ca619b7e56e9b11b0f1c4eac4fc880ed62b71a2a
+size 358670
@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:aa9ca9a367c79159a26d1ec544b20fc7118a49082d72f7ee0edbaa85608d49fc
-size 238991
+oid sha256:96176a09e65e90dadc32d5e9ed778423842be89204d2cf382225f53a90cfaf01
+size 258547
@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:d6aff446a062aa08f316985d00c2183148694f786d7f22172bc50b30046c728b
-size 379259
+oid sha256:a6b7769aa7e732ffbeb1eb7f5b65273a135fb3a78d9802ec36d3b92801c34f6b
+size 427745
@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:636a6b2fc1075e4863421e68b99efe7f6f6f62cedbcff36ef0934c055f39fd46
-size 281161
+oid sha256:79a690c466a5d6f6d4292d78a27b9474e9e9c1373fa80e17dfe37700238c8af8
+size 382508
@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:137d6c91a34695c820d8b0a33fd753e79165604aa92bf2ac8480d3744b2ef844
-size 305199
+oid sha256:c89628ed917dfd576c1af75c68fe5fed9beadaaee9dcea7aa7a1643867c4f1b9
+size 344323
@@ -1,3 +1,3 @@
 version https://git-lfs.github.com/spec/v1
-oid sha256:0455e0dec36ebb8bcfdadcf327a1dd24ddbdcdd8df211c08918180842497727e
-size 318681
+oid sha256:06fe076f0835a891e00afc804fd1805196ebde9fc0d34998c7873e87287f982b
+size 346887
@@ -1,3 +0,0 @@
-version https://git-lfs.github.com/spec/v1
-oid sha256:aa12d81dc578f7e65bf4df3152b3de1736289c422f83d0b0cd32107726722357
-size 172028
@@ -1,340 +1,150 @@
 # Docker Deployment

-Turnstone ships two Docker Compose stacks:
+Docker Compose stack for running the full turnstone platform.

-| Stack | File | Use it for |
-|-------|------|------------|
-| **Dev cluster** | `compose.yaml` (repo root) | Clone-and-run. Builds locally, zero config, full 10-node cluster. |
-| **Production** | `turnstone/deploy/compose.yaml` | Pip/pipx installs. Pulls released images from ghcr.io, requires real secrets. |
-
-## Quick start — local cluster
+## Quick Start

 ```bash
-git clone https://github.com/turnstonelabs/turnstone
-cd turnstone
+# Copy and edit environment config
+cp .env.example .env
+
+# Full stack (needs an LLM API on the host)
 docker compose up
 ```

-That builds one image and brings up the whole stack: PostgreSQL, the console,
-Caddy, the channel gateway, and **10 server nodes** (`node-1`…`node-10`). No
-`.env` is required — it ships with insecure dev defaults so it just works.
+Console dashboard: http://localhost:8090

-Open the dashboard at **https://localhost:8443**. It's served by Caddy with its
-own local CA, so trust the root certificate once (or click through the browser
-warning):
+> See also: [Deployment diagram](diagrams/png/12-deployment.png)
+
+## Services
+
+| Service | Port | Profile | Description |
+|---------|------|---------|-------------|
+| `server` | 8080 | default | Web UI + chat workstreams + LLM |
+| `console` | 8090 | default | Cluster dashboard |
+| `channel` | — | production | Channel gateway (Discord, Slack, etc.) |
+| `server-1`…`server-10` | — | cluster | 10-node server fleet (PostgreSQL required) |
+
+## Profiles
+
+**Default** (no flag) — starts `server` and `console`. Requires an OpenAI-compatible LLM API running on the host (default: `http://localhost:8000/v1`).

 ```bash
-docker compose exec caddy cat /data/caddy/pki/authorities/local/root.crt
+docker compose up
 ```

-Create your first admin user (any node works — they share one database):
+**Production** — adds PostgreSQL and the channel gateway. Requires `POSTGRES_PASSWORD` and (for Discord) `TURNSTONE_DISCORD_TOKEN`:

 ```bash
-docker compose exec node-1 turnstone-admin create-user --username admin --name "Admin"
+docker compose --profile production up
 ```

-### Bring your own LLM
-
-Nodes boot **without** an LLM and appear in the console immediately. Add real
-model backends (OpenAI, Anthropic, or a local/vLLM endpoint) from the console
-UI's **Models** tab. To set a node's bootstrap default instead, point
-`LLM_BASE_URL` / `OPENAI_API_KEY` at an OpenAI-compatible endpoint in `.env`.
-
-### Fewer nodes
-
-Ten nodes is heavy on a laptop. Start a subset by naming the services (always
-include `postgres`, `console`, and `caddy`):
+**Cluster** — 10-node server fleet sharing PostgreSQL. Access all nodes via the console at `:8090`. Requires `POSTGRES_PASSWORD`:

 ```bash
-docker compose up postgres console caddy channel node-1 node-2 node-3
+docker compose --profile cluster up
 ```

-## Why HTTPS-only?
-
-The console's plain-HTTP port (8090) is **not** published to the host. A plain
-HTTP/1.1 origin caps the browser at 6 connections, which starves the
-dashboard's per-pane SSE streams. Caddy serves the browser over HTTP/2
-(multiplexed) and proxies to `console:8090` on the internal network, so the cap
-is gone. Everything goes through `https://localhost:8443`.
-
-## Join a bare-metal host
-
-PostgreSQL, the console's ACME endpoint (`:8090`), and SearxNG (`:8081`) are
-published on `127.0.0.1`, so a `turnstone-server` running directly on the same
-machine — for example to use a local GPU — can join the same cluster (enrolling
-its mTLS cert and running `web_search`) and show up in the console alongside the
-containerized nodes.
-
-Put the secret and connection settings in `~/.config/turnstone/config.toml`
-(secrets belong in this file, not the process environment — keep it `0600`,
-the loader warns otherwise):
-
-```toml
-[auth]
-jwt_secret = "dev-only-insecure-jwt-secret-change-me-for-real-deployments"
-
-[database]
-backend = "postgresql"
-url = "postgresql+psycopg://turnstone:turnstone@localhost:5432/turnstone"
-
-[api]
-base_url = "http://localhost:8000/v1"   # your local model endpoint
-api_key = "dummy"
-```
-
-Then start the server. The node identity isn't a secret, so it stays on the
-command line:
-
-```bash
-chmod 600 ~/.config/turnstone/config.toml
-TURNSTONE_NODE_ID=host-1 \
-  TURNSTONE_ADVERTISE_URL=http://host.docker.internal:8080 \
-  TURNSTONE_CONSOLE_URL=http://localhost:8090 \
-  TURNSTONE_SEARXNG_URL=http://localhost:8081 \
-  turnstone-server --host 0.0.0.0 --port 8080
-```
-
-The host server registers itself in PostgreSQL; the console reaches it back via
-`host.docker.internal`. `TURNSTONE_CONSOLE_URL` points the node at the console's
-published ACME endpoint so it can enroll its mTLS certificate (needed only when
-the cluster runs mTLS; harmless otherwise), and `TURNSTONE_SEARXNG_URL` points
-`web_search` at the published SearxNG. The `jwt_secret` and DB credentials above
-are the dev-stack defaults — match whatever you set in `.env` if you changed them.
-
-To let a server on a **different** machine join, start the stack with
-both `TURNSTONE_HOST_IP=<this host's LAN IP>` and
-`TURNSTONE_ACME_EXTERNAL_URL=http://<this host's LAN IP>:8090/acme`. The first
-binds PostgreSQL, the console ACME endpoint, and SearxNG to that interface; the
-second makes every URL in the ACME directory routable from the remote node (the
-full value must include the `/acme` mount). Set the same
-`TURNSTONE_ACME_EXTERNAL_URL` on the remote node so its authenticated ACME
-client can pin that credential destination. Set `TURNSTONE_CONSOLE_URL` and
-`TURNSTONE_SEARXNG_URL` to the compose host's IP, but set
-`TURNSTONE_ADVERTISE_URL=http://192.0.2.10:8080` to the **remote** box's own
-address. A resolvable DNS name works too. IPv6 literals must be bracketed in
-URLs, for example `http://[2001:db8::10]:8080`; Turnstone enrolls literal
-addresses as IP SANs rather than numeric DNS SANs.
-
-Use a trusted LAN or VPN address and firewall `:8090` to enrolling nodes. ACME
-signing routes require a dedicated short-lived service JWT, but direct bootstrap
-is still plain HTTP/TOFU: a bearer token provides authentication, not transport
-confidentiality or protection from an active on-path attacker. **Set a strong
-`POSTGRES_PASSWORD` first** — `TURNSTONE_HOST_IP` also exposes the database (and
-every user account + API-token hash in it), the console API, and the
-unauthenticated SearxNG to your network.
-
-To run the bare-metal node as a hardened, persistent service instead of by hand,
-use the systemd units in [`deploy/systemd/`](../deploy/systemd/).
-
-## Production stack
-
-For a real deployment use the bundled stack, which pulls released images
-instead of building:
-
-```bash
-docker compose -f turnstone/deploy/compose.yaml up
-```
-
-It's the same shape as the dev stack — Caddy-fronted console, channel, and a
-PostgreSQL all share one database so the console discovers the node — but it
-pulls released images, runs a single server node, and has **no baked-in
-secrets**. Set these in `.env` first (generate with `openssl rand -hex 32`):
-
-```bash
-TURNSTONE_JWT_SECRET=<python -c "import secrets; print(secrets.token_hex(32))">
-POSTGRES_PASSWORD=<a strong password>
-```
-
-The dashboard is at **https://localhost:8443** (Caddy, same as the dev stack);
-the console's HTTP port isn't published. For a real domain and a publicly
-trusted cert, edit `turnstone/deploy/Caddyfile` to point Caddy at Let's Encrypt
-(see [tls.md](tls.md)). Pin the image with `TURNSTONE_IMAGE_TAG` (default:
-`latest`).
-
-### mTLS
-
-Layer the TLS overlay on the production stack to enable mutual TLS between
-services. A bootstrap container creates a CA and every service auto-provisions
-certs via the console's ACME endpoint:
-
-```bash
-docker compose -f turnstone/deploy/compose.yaml -f deploy/docker-compose.tls.yml up
-```
-
-The overlay publishes the console's plain-HTTP bootstrap/API port on
-`TURNSTONE_CONSOLE_HTTP_BIND` (default `127.0.0.1`). For a cross-host node, set
-that to a trusted LAN/VPN address, set `TURNSTONE_ACME_EXTERNAL_URL` to the same
-address plus `/acme`, and firewall the port to enrolling nodes.
-
-See [tls.md](tls.md) for details.
-
 ## Configuration

-Everything is configured with environment variables in `.env` (copy from
-[`.env.example`](../.env.example)). The dev stack needs none of them — they're
-overrides.
+All configuration is via environment variables in `.env` (copy from `.env.example`):

-### LLM backend
+### LLM Backend

 | Variable | Default | Description |
 |----------|---------|-------------|
-| `LLM_BASE_URL` | `http://host.docker.internal:8000/v1` | Bootstrap OpenAI-compatible API URL (real backends go in the UI) |
+| `LLM_BASE_URL` | `http://host.docker.internal:8000/v1` | OpenAI-compatible API URL |
 | `OPENAI_API_KEY` | `dummy` | API key (`dummy` for local servers) |
-| `TURNSTONE_SEARXNG_URL` | `http://searxng:8080` | SearxNG URL for the `web_search` tool (local/vLLM models only; Anthropic/OpenAI use native search). Defaults to the bundled `searxng` service; set to an external instance's URL. To turn web search off, clear `tools.searxng_url` in the admin Settings tab. |
-| `SEARXNG_IMAGE_TAG` | `latest` | Tag for the bundled `searxng/searxng` image |
-| `MODEL` | — | Override the default model alias |
+| `TAVILY_API_KEY` | — | Web search API key (only needed for local/vLLM models; Anthropic and OpenAI search models use native search) |

-### Auth & database
-
-| Variable | Default (dev / prod) | Description |
-|----------|----------------------|-------------|
-| `TURNSTONE_JWT_SECRET` | insecure default / **required** | JWT signing secret. Every service must share one value. |
-| `TURNSTONE_DB_BACKEND` | `postgresql` | `sqlite` or `postgresql`. Multi-node discovery requires `postgresql`. |
-| `TURNSTONE_DB_URL` | bundled Postgres | SQLAlchemy URL. Override to use an external database. |
-| `POSTGRES_USER` | `turnstone` | PostgreSQL username |
-| `POSTGRES_PASSWORD` | `turnstone` / **required** | PostgreSQL password |
-| `POSTGRES_MAX_CONNECTIONS` | `300` | `max_connections` for the bundled Postgres |
-
-> **Discovery needs a shared database.** Each server registers and heartbeats
-> into a `services` table that the console polls. All services in these stacks
-> point at the same PostgreSQL by default; SQLite-per-container can't see other
-> containers.
-
-> **Large clusters:** each process keeps a small pool (5 max). Beyond ~50 nodes,
-> put [PgBouncer](pgbouncer.md) (transaction pooling) between turnstone and
-> PostgreSQL.
-
-> **Lifecycle upgrade:** the release that introduces hidden deferred-create
-> reservations must be deployed as a coordinated cohort across every server
-> sharing PostgreSQL; older processes do not understand `state='creating'`.
-> Drain create traffic until the cohort is upgraded. See
-> [PgBouncer: deferred workstream creation](pgbouncer.md#upgrade-note-deferred-workstream-creation).
-
-### Ports
-
-Both stacks publish Caddy (dashboard) and PostgreSQL; the dev stack additionally
-publishes the console's ACME endpoint and SearxNG on localhost so a bare-metal
-node can enroll its cert and run `web_search`. Everything else is reached through
-Caddy or proxied by the console:
+### Server

 | Variable | Default | Description |
 |----------|---------|-------------|
-| `CONSOLE_HTTPS_PORT` | `8443` | Host port for Caddy (dashboard HTTPS) |
-| `SEARXNG_HTTPS_PORT` | `8444` | Host port for the SearxNG UI via Caddy (dev: localhost-only; prod: opt-in) |
-| `POSTGRES_PORT` | `5432` | Host port for PostgreSQL (for bare-metal joins) |
-| `SEARXNG_API_PORT` | `8081` | Host port for the SearxNG API a bare-metal node's `web_search` dials (dev stack) |
-| `TURNSTONE_HOST_IP` | `127.0.0.1` | Interface PostgreSQL, the console ACME endpoint, and SearxNG bind on (dev stack). Set to this host's LAN IP so a bare-metal node on **another machine** can reach them — set a strong `POSTGRES_PASSWORD` first (it also exposes the DB and the unauthenticated SearxNG to your network). |
-| `TURNSTONE_CONSOLE_HTTP_BIND` | `127.0.0.1` | Production TLS-overlay interface for the console's plain-HTTP bootstrap/API listener. Use only a trusted LAN/VPN address and firewall it to enrolling nodes. |
-| `TURNSTONE_ACME_EXTERNAL_URL` | request-derived | Canonical externally reachable ACME responder base, including the final `/acme` mount (for example `http://192.0.2.1:8090/acme`). Set it on the console and clients for cross-host mTLS: the console advertises it, while clients pin it as an allowed enrollment-JWT destination. A reverse-proxy prefix is supported only when the proxy maps it to Turnstone's internal `/acme` mount. |
-| `POSTGRES_BIND` | `127.0.0.1` | Production stack (`turnstone/deploy/compose.yaml`) only: interface PostgreSQL binds on; set to the host's LAN IP for remote joins. |
+| `SERVER_PORT` | `8080` | Host port mapping |
+| `SKIP_PERMISSIONS` | — | Set to any value to auto-approve all tools |

-### Channel gateway
+### Console

 | Variable | Default | Description |
 |----------|---------|-------------|
-| `TURNSTONE_DISCORD_TOKEN` | — | Discord bot token (enables the Discord adapter) |
-| `TURNSTONE_DISCORD_GUILD` | `0` | Restrict to one guild (0 = all) |
-| `TURNSTONE_SLACK_TOKEN` | — | Slack Bot User OAuth token `xoxb-…` |
-| `TURNSTONE_SLACK_APP_TOKEN` | — | Slack App-Level token `xapp-…` (with the Slack token) |
+| `CONSOLE_PORT` | `8090` | Host port mapping |

-The channel runs HTTP-only with no adapters until a token is set, so it's safe
-to leave running. See [Channel Integrations](channels.md) for app setup.
+### Auth

-### Web search (SearxNG)
-
-The `web_search` tool for local/vLLM models is backed by a self-hosted
-[SearxNG](https://searxng.org) metasearch service, bundled into both stacks as the
-`searxng` service. The Turnstone nodes reach it over the internal docker network at
-`http://searxng:8080` — its API port is **not** published. Its config —
-[`turnstone/deploy/searxng/settings.yml`](../turnstone/deploy/searxng/settings.yml),
-mounted read-only — enables the JSON API and leaves the rate limiter off (the
-limiter would need a separate Valkey/Redis instance). A `searxng-cache` volume
-persists its favicon + internal cache across restarts. Commercial providers
-(Anthropic, OpenAI) use their own native search and never touch this service.
-
-Point at an existing SearxNG instead of the bundled one with `TURNSTONE_SEARXNG_URL`,
-or narrow the engines via `tools.searxng_engines` in the admin Settings tab (e.g.
-`duckduckgo,wikipedia`).
-
-**SearxNG web UI.** Caddy can also serve SearxNG's own search/Preferences UI on a
-dedicated port. The dev stack publishes it at **`https://localhost:8444`** bound to
-localhost only; the production stack does **not** publish it by default (uncomment
-the `8444` port on the `caddy` service to opt in). Change the port with
-`SEARXNG_HTTPS_PORT`. **SearxNG has no authentication** — never bind this to a public
-interface, or anyone who can reach it can search through your instance.
-
-> **AGPL note for operators.** SearxNG is licensed AGPL-3.0. Kept on the internal
-> network (or bound to localhost), no external user interacts with it — so the AGPL
-> §13 (remote network interaction) source-offer obligation does not attach. If you
-> publish SearxNG to remote users (bind its port to a public interface, or front it
-> with your own reverse proxy) you become the operator of a network-reachable AGPL
-> service and must offer its corresponding source; that is trivially satisfied by
-> linking to upstream <https://github.com/searxng/searxng>. Turnstone's own license is
-> unaffected: it talks to SearxNG over HTTP as a separate process (mere aggregation),
-> not by linking.
-
-### Other
+Auth is always enabled. `TURNSTONE_JWT_SECRET` is required.

 | Variable | Default | Description |
 |----------|---------|-------------|
-| `WORKSPACE_MOUNT` | empty volume | Host directory bind-mounted at `/workspace` for the model to read/write |
-| `TURNSTONE_WORKSPACE` | `/workspace` (image env) | Directory named as the user's workspace in the model's tool descriptions; informational only — see [Working directory](#working-directory) |
-| `SKIP_PERMISSIONS` | — | Set to any value to auto-approve all tool calls (dev only) |
-| `MCP_CONFIG` | — | Path to an MCP server config file |
-| `TURNSTONE_IMAGE_TAG` | `latest` | ghcr.io image tag — production stack |
+| `TURNSTONE_JWT_SECRET` | — | Secret key for signing JWTs (required) |

-## Building
+### Database

-Both stacks install all entry points into a single image (`turnstone`,
-`turnstone-server`, `turnstone-console`, `turnstone-channel`, `turnstone-admin`,
-`turnstone-eval`, `turnstone-optimizer`, `turnstone-doctor`):
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `TURNSTONE_DB_BACKEND` | `sqlite` | Storage backend: `sqlite` or `postgresql` |
+| `TURNSTONE_DB_URL` | — | Database URL (e.g. `postgresql://user:pass@db:5432/turnstone`). For SQLite, defaults to `/data/.turnstone.db` |
+| `TURNSTONE_DB_POOL_SIZE` | `2` | PostgreSQL connection pool size per process (default: 2 base + 3 overflow = 5 max) |
+
+The database stores workstream history, user accounts, and API tokens. When using JWT auth, a database backend is required for user storage.
+
+> **Large clusters:** Each turnstone process maintains a small connection pool (5 max). At hundreds of nodes this adds up — use [PgBouncer](pgbouncer.md) in transaction pooling mode between turnstone and PostgreSQL.
+
+> **First-time setup:** After deploying with auth enabled, create an initial admin user by running `turnstone-admin create-user` inside the container:
+>
+> ```bash
+> docker compose exec server turnstone-admin create-user --username admin --name "Admin"
+> ```
+>
+> You will be prompted to set a password. Use it to log in via the UI or SDK, then create additional users through the admin API. Pass `--token --scopes read,write,approve` to also generate an initial API token.
+
+### Channel Gateway
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `TURNSTONE_DISCORD_TOKEN` | — | Discord bot token (required to enable Discord adapter) |
+| `TURNSTONE_DISCORD_GUILD` | `0` | Restrict to a single Discord guild (0 = all guilds) |
+
+The channel service runs in the `production` profile. When `TURNSTONE_DISCORD_TOKEN` is set, the Discord adapter connects to the Discord Gateway and routes messages to the server via HTTP. See [Channel Integrations](channels.md) for full setup instructions including Discord application creation and user account linking.
+
+## Scaling
+
+For multi-node testing, use the `cluster` profile which provides 10 server instances with unique node IDs (`node-1` through `node-10`), resource limits, and shared PostgreSQL:

 ```bash
-docker compose build            # build the dev image
-docker compose build --no-cache # rebuild from scratch
+POSTGRES_PASSWORD=secret docker compose --profile cluster up
 ```

+The default `server` also runs alongside the cluster nodes (11 total). All nodes are accessible via the console dashboard at `:8090`.
+
+For production clusters beyond ~50 nodes, add PgBouncer between turnstone services and PostgreSQL. See [PgBouncer Connection Pooling](pgbouncer.md) for Docker Compose and Helm configuration.
+
 ## Volumes

-| Volume | Purpose |
-|--------|---------|
-| `postgres-data` | PostgreSQL data directory |
-| `turnstone-data` | `/data` per node (SQLite fallback, local state) |
-| `workspace` | `/workspace` (unless `WORKSPACE_MOUNT` is set) |
-| `caddy-data` / `caddy-config` | Caddy's local CA and config (dev stack) |
+| Volume | Mount | Purpose |
+|--------|-------|---------|
+| `turnstone-data` | `/data` | SQLite database (`.turnstone.db`) |

-## Working directory
+## Building

-Node processes run with `/data` as their working directory (the image's
-`WORKDIR`), and that is where the model's shell commands execute and
-relative file paths resolve — **not** `/workspace`. The shell and file
-tool descriptions state both paths (the working directory, and the
-workspace named by `TURNSTONE_WORKSPACE`), so the model knows to look in
-`/workspace` for your files without being told each session.
+The image uses a multi-stage Dockerfile:

-To make tools start inside the mount instead, override the working
-directory on the node services:
+```bash
+# Build all services
+docker compose build

-```yaml
-services:
-  turnstone-node:
-    working_dir: /workspace
+# Rebuild without cache
+docker compose build --no-cache
 ```

-Two caveats before overriding:
-
- **SQLite fallback**: when a node runs without PostgreSQL, its fallback
-  database `.turnstone.db` is created in the process working directory.
-  Changing `working_dir` on an existing SQLite-fallback deployment makes
-  the node create a fresh database inside the mount and your prior state
-  appears lost (it is still in the `turnstone-data` volume under `/data`).
-  The stock compose stacks use PostgreSQL and are unaffected.
- Migrations (`entrypoint.sh`) run in the same working directory, so the
-  same SQLite caveat applies to them.
+All entry points are installed in a single image: `turnstone-server`, `turnstone-console`, `turnstone-channel`, `turnstone-admin`, `turnstone-eval`.

 ## Cleanup

 ```bash
-docker compose down       # stop and remove containers
-docker compose down -v    # also remove volumes (database, certs)
+# Stop and remove containers
+docker compose down
+
+# Stop, remove containers and volumes
+docker compose down -v
 ```
@@ -1,19 +1,11 @@
-# Evaluation and Prompt Optimization (turnstone-eval, turnstone-optimizer)
+# Evaluation and Prompt Optimization (turnstone-eval)

-Evaluation for turnstone is split into two commands:
+`turnstone-eval` is the evaluation and prompt optimization system for turnstone. It
+runs test cases against the LLM, scores tool call sequences against expected
+actions, and optionally uses a multi-agent pipeline to optimize the developer
+prompt and tool descriptions.

- **`turnstone-eval`** — the measurement substrate. Runs test cases against the LLM
-  and scores tool call sequences against expected actions. A single measurement pass,
-  no self-modification.
- **`turnstone-optimizer`** — the prompt/tool optimizer. Loops over the measurement
-  substrate, using a multi-agent pipeline (analyst, optimizer, observer, diversifier,
-  tool optimizer) to edit the developer prompt and tool descriptions so more tests pass.
-
-The dependency is strictly one-way: the optimizer consumes the eval substrate; the
-substrate never depends on the optimizer.
-
-Source: `turnstone/eval/core.py` (measurement substrate), `turnstone/eval/cli.py`
-(the `turnstone-eval` CLI), `turnstone/optimizer.py` (the `turnstone-optimizer` CLI).
+Source: `turnstone/eval.py`

 ---

@@ -35,8 +27,8 @@ This approach (inspired by [Learning to Self-Evolve](https://arxiv.org/abs/2603.
 prevents irrecoverable collapse from bad edits — UCB naturally backtracks to
 high-scoring ancestors instead of following a linear chain.

-The `turnstone-eval` command (or `turnstone-optimizer --no-optimize`) executes only
-steps 2-4: a single measurement pass over the root prompt, no optimization.
+When optimization is disabled (`--no-optimize`), only steps 2-4 execute
+(a single iteration evaluating the root node).

 ---

@@ -177,8 +169,7 @@ Runs a complete multi-turn conversation:

 1. Appends the user message.
 2. Checks `_cancelled` event — stops if set (timeout cleanup).
-3. Calls the model through the production streaming provider path and drains
-   the result.
+3. Calls the model API (non-streaming).
 4. If tool calls are returned, executes them (with stdout suppressed) and
   logs each call to `self.tool_call_log`.
 5. Repeats up to `max_turns` or until the model responds without tool calls.
@@ -191,15 +182,14 @@ Parallel tool calls are capped at 10 per turn to prevent degenerate repetition.

 Each test runs in a `ThreadPoolExecutor(max_workers=1)` with a per-test
 timeout (`--test-timeout`). Each attempt gets its own `OpenAI` client with
-a matching per-read HTTP transport timeout. Because a trickling stream can
-continually reset that read timeout, three layers bound the harness and stop
-follow-on work:
+a matching httpx read timeout. On timeout, three layers of defense prevent
+zombie connections:

-1. **Executor wall clock**: The harness stops waiting after `--test-timeout`.
+1. **httpx timeout**: Per-request read timeout aborts the HTTP call and
+   releases the server slot.
 2. **`_cancelled` event**: Prevents the orphan thread from starting new turns.
-3. **`run_client.close()`**: Retires the connection pool and prevents reuse.
-   HTTPX2 does not promise that cross-thread client closure immediately aborts
-   an active body read; that read unwinds on its next wire event or read timeout.
+3. **`run_client.close()`**: Closes the connection pool to abort any
+   in-flight request.

 ### Retry Logic

@@ -216,8 +206,7 @@ Each test case runs in isolation:
 1. A fresh temp directory is created.
 2. Setup files are written to the temp directory.
 3. The working directory is changed to the temp directory.
-4. A per-attempt `OpenAI` client is created with an HTTP transport timeout
-   matching `--test-timeout`.
+4. A per-attempt `OpenAI` client is created with httpx timeout matching `--test-timeout`.
 5. A new `HeadlessSession` is created with the current developer prompt.
 6. `send_headless()` runs the user prompt through the conversation loop.
 7. The tool log is scored against expected actions.
@@ -285,7 +274,8 @@ for iteration in 0..max_iterations:

 ### Phase 1: Analyst (`_run_analyst`)

-A multi-turn agent with a `bash` tool for computing statistics. It receives per-case results with failure classifications and
+A multi-turn agent with `math` (Python) and `bash` tools for computing
+statistics. It receives per-case results with failure classifications and
 produces a structured diagnosis:

 - **Failure patterns**: Shared root causes across failing cases
@@ -463,46 +453,30 @@ structure is:

 ## CLI Usage

-Two console scripts (installed as entry points), or the equivalent `python -m`
-invocations:
-
- `turnstone-eval` / `python -m turnstone.eval.cli` — measure only.
- `turnstone-optimizer` / `python -m turnstone.optimizer` — optimize.
-
-### Measure (`turnstone-eval`)
+The entry point is `turnstone-eval` (installed as a console script) or
+`python -m turnstone.eval`.

 ```
-turnstone-eval tests.json                     # one measurement pass, print scores
-turnstone-eval tests.json --prompt custom.txt # measure a custom prompt
-turnstone-eval tests.json --n-runs 5          # more runs per case
-turnstone-eval tests.json --parallel 4        # run cases across 4 workers
-turnstone-eval tests.json -v                  # verbose per-turn logging
+turnstone-eval tests.json                          # evaluate + optimize
+turnstone-eval tests.json --no-optimize            # evaluate only (single iteration)
+turnstone-eval tests.json --n-runs 5 --max-iter 10 # more thorough evaluation
+turnstone-eval tests.json --prompt custom.txt      # start from a custom prompt
+turnstone-eval tests.json --optimize-tools         # optimize tool descriptions only
+turnstone-eval tests.json --diversify 10           # test with prompt variants
+turnstone-eval tests.json -v                       # verbose per-turn logging
 ```

-### Optimize (`turnstone-optimizer`)
+### Multi-model setup (local test model, cloud optimizer)

 ```
-turnstone-optimizer tests.json                          # evaluate + optimize
-turnstone-optimizer tests.json --no-optimize            # single pass, no optimization
-turnstone-optimizer tests.json --n-runs 5 --max-iter 10 # more thorough optimization
-turnstone-optimizer tests.json --prompt custom.txt      # start from a custom prompt
-turnstone-optimizer tests.json --optimize-tools         # optimize tool descriptions only
-turnstone-optimizer tests.json --diversify 10           # test with prompt variants
-```
-
-#### Multi-model setup (local test model, cloud optimizer)
-
-```
-turnstone-optimizer tests.json \
+turnstone-eval tests.json \
  --base-url http://localhost:8000/v1 \
  --optimizer-base-url https://api.anthropic.com \
  --optimizer-model claude-sonnet-4-6 \
  --analyst-model claude-opus-4-6
 ```

-### Measurement Options
-
-Accepted by **both** commands.
+### All Options

 | Flag                    | Default                    | Description |
 |-------------------------|----------------------------|-------------|
@@ -511,26 +485,19 @@ Accepted by **both** commands.
 | `--model`               | auto-detect                | Model name. Auto-detected from the API if not specified. |
 | `--prompt`              | turnstone built-in prompt  | Path to initial prompt text file. |
 | `--n-runs`              | from tests.json or 3       | Number of runs per test case. |
+| `--max-iter`            | 5                          | Maximum optimization iterations. |
+| `--no-optimize`         | false                      | Run evaluation only (sets max-iter to 1). |
 | `--temperature`         | 0.7                        | Sampling temperature. |
 | `--max-tokens`          | 32768                      | Max completion tokens. |
 | `--reasoning-effort`    | `medium`                   | Reasoning effort: `low`, `medium`, or `high`. |
 | `--context-window`      | 131072                     | Context window size. |
 | `--output`              | `eval_results.json`        | Output results file path. |
 | `-v`, `--verbose`       | false                      | Show detailed per-turn logging. |
+| `--explore-constant`    | 1.414 (sqrt(2))            | UCB exploration constant C. |
 | `--test-timeout`        | 300                        | Per-test timeout in seconds. |
+| `--suite-timeout`       | 0 (unlimited)              | Total suite timeout in seconds. |
 | `--no-fast-fail`        | false                      | Disable early termination on all-zero initial runs. |
 | `--parallel`            | 1 (serial)                 | Parallel workers (0=auto, N=use N workers). |
-
-### Optimizer Options
-
-Accepted by **`turnstone-optimizer`** only.
-
-| Flag                    | Default                    | Description |
-|-------------------------|----------------------------|-------------|
-| `--max-iter`            | 5                          | Maximum optimization iterations. |
-| `--no-optimize`         | false                      | Run a single measurement pass (sets max-iter to 1). |
-| `--explore-constant`    | 1.414 (sqrt(2))            | UCB exploration constant C. |
-| `--suite-timeout`       | 0 (unlimited)              | Total suite timeout in seconds. |
 | `--optimizer-model`     | same as `--model`          | Model for prompt optimization. |
 | `--optimizer-base-url`  | same as `--base-url`       | Base URL for optimizer model. |
 | `--observer-model`      | same as optimizer           | Model for meta-optimization (observer). |
@@ -13,25 +13,18 @@ The permission model has two layers:

 1. **Scopes** (legacy) — `read`, `write`, `approve`. Checked by `AuthMiddleware`
   on every request based on URL path classification.
-2. **Permissions** (granular) — named permission strings checked per-endpoint by
+2. **Permissions** (granular) — 15 permission strings checked per-endpoint by
   `require_permission()`.

-**Built-in roles** (seeded by migration 008 and extended by later feature
-migrations):
+**Built-in roles** (seeded by migration 008):

 | Role | Permissions |
 |------|-------------|
-| admin | Admin-default baseline: ordinary admin, lifecycle, tool-approval, coordinator, project, and persona capabilities. Explicit opt-in capabilities such as `model.skills.write` remain ungranted. |
-| operator | read, write, workstreams.create, workstreams.close, conversation.modify |
+| admin | read, write, approve, admin.users, admin.roles, admin.orgs, admin.policies, admin.skills, admin.audit, admin.usage, admin.schedules, admin.watches, tools.approve, workstreams.create, workstreams.close |
+| operator | read, write, workstreams.create, workstreams.close |
 | viewer | read |

-Custom roles can be created with any subset of the valid permissions. Built-in
-role permission overrides can grant or revoke individual capabilities, so the
-admin console is authoritative for the effective set on a deployment.
-The `persona.create` / `persona.read` / `persona.write` family gates
-persona administration; migration `063` seeds all three onto
-`builtin-admin`, and any role can be granted them through the standard
-role and permission-override editors.
+Custom roles can be created with any subset of the 15 valid permissions.

 **Auth flow:**
 1. User logs in (password or API token) → `_load_user_permissions()` aggregates
@@ -69,14 +62,14 @@ etc.) since workstream templates were merged into the skills system in v0.8.0.
 - **Default skills**: All `is_default=true` skills auto-apply to new
  workstreams, concatenated in alphabetical order by name. Use name prefixes
  (e.g. `01-safety`, `02-style`) to control ordering.
- **Explicit selection**: `--skill <name>` CLI flag, `skill` field on
-  `POST /v1/api/workstreams/new`, console launcher dropdown, scheduled task
+- **Explicit selection**: `--template <name>` CLI flag, `template` field on
+  `POST /v1/api/workstreams/new`, console creation modal dropdown, scheduled task
  config, and channel adapter config. An explicit skill *replaces* defaults.
 - **Variables**: Three built-in placeholders resolved at load time:
  `{{model}}` (active model name), `{{ws_id}}` (workstream ID),
  `{{node_id}}` (server node ID). Unrecognized placeholders are kept as-is.
- **Runtime switching**: `/skill <name>` to switch, `/skill clear` to revert
-  to defaults, `/skill` to show current. Persisted across resume.
+- **Runtime switching**: `/template <name>` to switch, `/template clear` to revert
+  to defaults, `/template` to show current. Persisted across resume.
 - **Model-driven loading**: The `skill` built-in tool lets the model
  discover and activate skills mid-conversation. `search` action finds skills
  by query (auto-approved); `load` action activates by name (requires user
@@ -98,7 +91,7 @@ etc.) since workstream templates were merged into the skills system in v0.8.0.
  time. The scanner evaluates four risk axes: content risk (command execution,
  data exfiltration), supply chain risk (pipe-to-shell, transitive installs),
  vulnerability risk (prompt injection, insecure credentials), and declared
-  capability risk (from `allowed-tools` in SKILL.md). Results populate the `risk_level`
+  capability risk (from `allowed-tools` in SKILL.md). Results populate the `scan_status`
  (safe/low/medium/high/critical) and `scan_report` (JSON breakdown) columns.
  These fields are system-managed and cannot be overwritten via the admin API.
 - **Discovery**: External skills can be discovered and installed from registries:
@@ -134,12 +127,9 @@ Per-LLM-request token and tool call metrics:
  LLM response with prompt/completion tokens, cache tokens, tool call count,
  model, ws_id
 - **Prompt caching**: Anthropic automatic caching (`cache_control: ephemeral`)
-  and OpenAI caching are enabled by default. Pre-5.6 GPT-5 models request
-  `prompt_cache_retention: 24h`; GPT-5.6 uses
-  `prompt_cache_options: {"ttl": "30m"}`. GPT-5.6 cache writes use the
-  provider's 1.25× input-token rate. `cache_creation_tokens` and
-  `cache_read_tokens` are tracked per request in `usage_events` and surfaced
-  in the Usage admin tab
+  and OpenAI extended retention (`prompt_cache_retention: 24h` for GPT-5.x)
+  are enabled by default. `cache_creation_tokens` and `cache_read_tokens` are
+  tracked per request in `usage_events` and surfaced in the Usage admin tab
 - **Querying**: `GET /v1/api/admin/usage` with `group_by` (day/hour/model/user)
  and time range filtering — includes cache token aggregates
 - **Prometheus**: `turnstone_tokens_total{type="cache_creation|cache_read"}`
@@ -187,7 +177,6 @@ All under `/v1/api/admin/` (requires `approve` scope + granular permission).
 | Orgs | 3 (list, get, update) | `admin.orgs` |
 | Tool Policies | 4 (CRUD) | `admin.policies` |
 | Skills | 4 (CRUD) | `admin.skills` |
-| Personas | 4 (list, create, get, edit/archive) | `persona.read` / `persona.create` / `persona.write` |
 | Schedules | 6 (CRUD + runs) | `admin.schedules` |
 | Watches | 3 (list, create, cancel) | `admin.watches` |
 | Usage | 1 (aggregated query) | `admin.usage` |
@@ -197,21 +186,15 @@ Full OpenAPI spec at `/openapi.json` and Swagger UI at `/docs`.

 ## Admin Console UI

-Governance-related tabs within the 18-tab admin panel:
+6 new tabs added to the admin panel (11 total):

 - **Roles** — CRUD roles, permission checkbox grid, user role assignment modal
 - **Policies** — CRUD tool policies with colored action badges (green/red/amber)
- **Prompts** — Prompt-policy editor (heuristics for admin guardrails)
- **Skills** — CRUD skills with wide modal, textarea editor; Discover pill for
-  installing from skills.sh / GitHub; per-row scan badges (safe/low/med/high/critical)
- **Judge** — Intent validation configuration and verdict history
+- **Skills** — CRUD skills with wide modal, textarea editor
 - **Usage** — Summary readouts + CSS bar chart, time range + group-by selectors
 - **Audit** — Filterable log with relative timestamps, load-more pagination

 Tabs are permission-gated: hidden if the user lacks the required permission.
-See [docs/console.md](console.md) for the full tab list and
-[docs/settings.md](settings.md) for the Settings tab that edits live
-ConfigStore values.

 ## SDK

@@ -233,7 +216,7 @@ Both Python and TypeScript console SDKs expose governance methods:
 - **Privilege escalation prevented**: `admin_assign_role` blocks self-assignment
  and requires caller to hold a superset of the target role's permissions
 - **Permission validation**: Role create/update validates permissions against
-  the permission allowlist (`_VALID_PERMISSIONS`)
+  a 15-item allowlist (`_VALID_PERMISSIONS`)
 - **Self-deletion blocked**: `admin_delete_user` rejects attempts to delete
  your own account (matching the self-assignment guard on role endpoints)
 - **Field allowlists**: Storage `update_*` methods filter fields against
@@ -17,9 +17,7 @@ evaluation:
   read-only tool access. Runs on a daemon thread and delivers its verdict
   progressively.

-The verdict is advisory by default. The opt-in Smart Approvals mode can use a
-completed, high-confidence LLM `approve` verdict to make the decision
-automatically under the fail-closed rules below.
+The verdict is purely advisory -- the user always makes the final decision.

 The heuristic verdict is attached to the `approve_request` SSE event immediately.
 The LLM verdict arrives later via an `intent_verdict` SSE event, allowing the
@@ -30,78 +28,34 @@ persisted to the `intent_verdicts` table for audit and future calibration.

 ## Configuration

-### Server and console
+### config.toml

-Server and console workstreams read database-backed `judge.*` settings from
-the settings registry. Edit them at **Admin → Judge** or through the admin
-settings API; changes take effect for the next judge batch without a restart.
-The principal settings are:
-
-```text
-judge.enabled = true
-judge.model = ""                    # empty = same alias as the session
-judge.smart_approvals = false       # opt-in automatic approval
-judge.confidence_threshold = 0.95   # Smart Approvals confidence bar
-judge.max_context_ratio = 0.5       # fraction of judge context used for history
-judge.timeout = 120.0               # per judge turn and Smart Approvals wait
-judge.parallel_evaluations = 1      # concurrent calls within one batch, 1-16
-judge.read_only_tools = true        # permit read_file/list_directory evidence
-judge.cancel_on_approval = false    # stop unfinished calls when the gate resolves
+```toml
+[judge]
+enabled = true
+model = ""                    # empty = same as session model
+provider = ""                 # empty = same as session provider
+base_url = ""
+api_key = ""
+confidence_threshold = 0.7   # reserved for v2 smart approvals (not used in v1)
+max_context_ratio = 0.5       # max % of judge context window for history
+timeout = 60.0                # seconds (generous for local models)
+read_only_tools = true        # judge can use read_file/list_directory
 ```

-`parallel_evaluations = 1` preserves serial evaluation. Raising it reduces the
-latency of wide tool-call batches. The selected judge model alias's
-`max_concurrency` remains the process-wide generation ceiling, so it can reduce
-the actual overlap across judge batches and other roles using that alias.
-
-### Smart Approvals
-
-With `smart_approvals = true` (off by default), a pending batch is approved
-automatically — no operator prompt — only when **every** call has a completed
-LLM verdict recommending `approve` at or above `confidence_threshold`. The
-decision is batch-atomic: one uncertain sibling sends the entire parallel batch
-to a human rather than executing the safe-looking subset piecemeal.
-
-Every other outcome reaches a human: `review` / `deny` recommendations,
-confidence below the threshold, judge errors or timeouts (`llm_fallback`), a
-missing/duplicate call ID, an unjudged sibling, and any call the deterministic
-heuristic rules explicitly flagged `deny` or `critical`. That heuristic floor
-blocks only explicit danger verdicts — it is **not** a general "never lower the
-heuristic" rule. The heuristic's default for an unmatched tool is `review`, and
-letting a confident LLM upgrade that default is the feature's purpose.
-
-The Smart Approvals enabled flag, threshold, and bounded verdict wait are
-captured as one immutable snapshot when each gate batch starts. A settings
-reload takes effect on the next batch, while concurrent main-loop and
-task-agent gates cannot mix fields from different reload generations. Stop
-wakes a batch still waiting for verdicts and is linearized against the final
-auto-approval commit: if Stop wins, no `smart_approval` decision or audit row
-is recorded for tools that did not cross the gate.
-
-The verdict wait is capped by the snapshot's `judge.timeout`; the judge may
-continue evaluating advisory verdicts after that gate falls back to a human.
-
-Requires the judge to be enabled. Auto-approved calls are tagged
-`smart_approval` in the dashboard and audit trail. Smart Approvals applies to
-the web and coordinator surfaces, not the interactive CLI.
-
-The judge is enabled by default. Disable `judge.enabled` in the admin Judge
-settings, or use `--no-judge` in the interactive CLI.
+All fields are optional. The judge is enabled by default; use `enabled = false`
+(or `--no-judge` on the command line) to disable it.

 ### CLI flags

 ```
 --judge / --no-judge           Enable/disable (default: enabled)
--judge-model ALIAS            Registered model alias for judge
--judge-timeout SECONDS        LLM judge timeout (default: 120)
--judge-parallel-evaluations N Concurrent evaluations per batch, 1-16 (default: 1)
--judge-confidence FLOAT       Confidence threshold, 0-1 (default: 0.95)
+--judge-model MODEL            Model for judge
+--judge-provider PROVIDER      Provider for judge
+--judge-timeout SECONDS        LLM judge timeout (default: 60)
+--judge-confidence FLOAT       Confidence threshold (default: 0.7)
 ```

-The same five values can be placed in the CLI's `config.toml` `[judge]`
-section. Smart Approvals is configured through the server/console admin Judge
-settings, not a CLI flag—the interactive CLI prompts for approval directly.
-
 CLI flags override `config.toml` values.

 ---
@@ -111,23 +65,13 @@ CLI flags override `config.toml` values.
 - **Default (self-consistency)**: When `model` is empty, the session model
  evaluates its own tool calls. Research shows self-consistency achieves
  comparable accuracy to multi-agent debate at a fraction of the cost.
- **Cross-model**: Register the desired model in the Models tab, then set
-  `judge.model` to that alias (or pass `--judge-model ALIAS` to the CLI).
- **Cross-provider**: A model alias carries its provider, endpoint, and
-  credential configuration together, so a judge alias may use a different
-  provider from the session without separate judge connection settings.
- **Google models**: The judge supports `google` aliases, including read-only
-  evidence tools. Provider-native reasoning state such as Gemini
-  `thought_signature` stays attached to the pinned model lane across evidence
-  turns.
-
-The judge creates one fresh HTTP client per active batch worker and closes each
-when that worker finishes, avoiding cross-thread client sharing and stale
-connections across runs.
-
-If the LLM judge fails or returns no verdict, a fallback verdict with tier
-`llm_fallback` is delivered via the callback, ensuring the UI always receives
-a result.
+- **Cross-model**: Use a different model for the judge (e.g. local model for
+  the session, commercial model for the judge). Set `model` and `provider`
+  in the `[judge]` config section, or use `--judge-model` / `--judge-provider`
+  CLI flags.
+- **Cross-provider**: When both `model` and `provider` are set, the judge
+  creates its own LLM client. You can optionally specify `base_url` and
+  `api_key` for non-default endpoints.

 ---

@@ -148,7 +92,7 @@ last) and returns the first matching rule. Each rule has:
 | Critical | 0.90      | deny           | `rm -rf /`, `mkfs`, `dd if=`, pipe-to-shell, chmod 777 on root, write/edit to `/etc/` or `.ssh/`, download-then-execute chains (`curl -o file && chmod +x && bash`) |
 | High     | 0.80      | review         | `sudo`, `kill -9`, destructive git, DROP TABLE, write/edit secrets, HTTP mutations, `ssh`/`scp`, credential file access, browser automation + data export, transitive installs (`npx skills add`, `pip install git+`), control plane mutations (`crontab`, `systemctl enable/start/stop`) |
 | Medium   | 0.70      | review         | Content ingestion pipelines (`curl \| python3`), interpreter execution (`python3 script.py`, `node build.js`), cloud CLI mutations (`az/gcloud/aws/kubectl/terraform` with create/delete/destroy verbs), package installs, `write_file`, MCP tools, Docker operations |
-| Low      | 0.85      | approve        | `read_file`, `list_directory`, `search`, `recall`, `use_prompt`, `tool_search`, `read_resource`, `web_search`, read-only bash (`ls`, `cat`, `head`, `grep`, `find`, etc.) |
+| Low      | 0.85      | approve        | `read_file`, `list_directory`, `search`, `recall`, `man`, `use_prompt`, `tool_search`, `read_resource`, `web_search`, read-only bash (`ls`, `cat`, `head`, `grep`, `find`, etc.) |

 When no rule matches, the heuristic returns a default verdict: medium risk,
 0.50 confidence, "review" recommendation.
@@ -216,10 +160,9 @@ Security hardening blocks access to sensitive paths:

 ### Timeout

-The `timeout` setting (default 120 seconds) applies **per turn**, not as a total
-budget across turns — each of the up to 5 turns gets a fresh budget, so a slow
-earlier turn doesn't starve later ones. If a turn's budget expires, the judge
-attempts to parse whatever partial response is available.
+The `timeout` setting (default 60 seconds) is a total budget across all judge
+turns. Time is decremented after each LLM call. If the budget expires mid-turn,
+the judge attempts to parse whatever partial response is available.

 ---

@@ -255,48 +198,8 @@ calls for approval, it calls `_evaluate_intent()` which:
 4. Attaches each heuristic verdict to its item as `_heuristic_verdict`
 5. The daemon thread runs the LLM judge and delivers results via `ui.on_intent_verdict()`

-The daemon coordinates up to `parallel_evaluations` independent workers for
-one batch. Completed verdicts stream to the UI as workers finish, and every call
-still receives exactly one LLM or `llm_fallback` verdict. The default of 1 keeps
-the historical serial behavior; a higher value collapses a wide batch toward
-`ceil(batch size / workers)` judge-call intervals. A smaller positive model
-alias capacity also bounds the worker count, avoiding surplus threads queued at
-the same admission gate.
-
-With `cancel_on_approval = false` (the default) the daemon runs every item to
-completion: verdicts that land after the operator decided still stream to the
-UI and persist, stamped with the decision. A newer main-loop batch, session
-close, or explicit Stop retires the old generation; unfinished items degrade
-to `llm_fallback` verdicts. A judge/model binding or parallelism edit prevents
-reuse on the next batch, while already-started calls stay pinned to the binding
-and worker count they began with. With `cancel_on_approval = true`, an ordinary
-gate decision additionally aborts unfinished work, trading verdict completeness
-for inference savings—recommended when the judge shares a single local
-inference backend with the session model. Explicit Stop always cancels every
-live judge generation, regardless of this preference.
-
-Verdicts that arrive after a *newer batch* has replaced the judge generation
-are withheld from the live surfaces (a reused call_id must never ride a stale
-`approve` into Smart Approvals) but still persist with
-`user_decision = "superseded"` so the audit trail records the judge's answer.
-
-Sub-agent (task agent) tool calls are judge-gated too. Each runs the same
-intent pipeline as its own `agent_gate` generation, grounded in that sub-agent's
-own trajectory -- its task prompt is the delegation contract the operator
-approved, so "does this call serve the task" is the right local question.
-Agent-gate generations never occupy the main loop's supersede slot (parallel
-siblings would otherwise make each other's verdicts look stale); per-cycle
-generation checks enforce staleness instead, and `judge.cancel_on_approval`
-fires per gate exactly like the main loop.
-
-Several parallel task agents can therefore leave several approval cycles live
-on one workstream. Each cycle owns its event, result, verdict set, and
-`cycle_id`; a decision targets exactly one cycle by `cycle_id` or member
-`call_id` (selector-less legacy clients resolve the oldest). Workstream Stop or
-close performs a workstream-wide denial sweep over all cycles belonging to the
-cancelled operation. A force-cancel successor's newly registered cycle carries
-a fresh operation witness and is not accidentally denied by the predecessor's
-late sweep.
+Sub-agents (plan agent, task agent) are exempt from intent validation -- they
+always get full tool visibility without judge evaluation.

 ---

@@ -306,13 +209,7 @@ All verdicts are persisted to the `intent_verdicts` table (migration 012):

 - Heuristic verdicts are stored when the `approve_request` event is emitted
 - LLM verdicts are stored when the `intent_verdict` event is delivered
- The `user_decision` column is updated when the user approves or denies;
-  auto-approved rows carry the bypass reason (`policy`, `blanket`,
-  `auto_approve_tools`, `smart_approval`), and rows whose verdict landed only
-  after a newer batch replaced the judge generation carry `superseded`
- Every stored verdict — including the benign `risk_level = "none"` majority —
-  is re-attached to its tool call on history replay, so a reloaded workstream
-  shows the same verdict badges the live stream did
+- The `user_decision` column is updated when the user approves or denies

 The console admin panel exposes verdict history via:

@@ -406,7 +303,7 @@ four independent risk axes:
   `Bash(*)` (unrestricted shell) is high risk. `Bash(git:*)` is low.
   Read-only tools are safe.

-Results are stored in `risk_level` (tier: safe/low/medium/high/critical) and
+Results are stored in `scan_status` (tier: safe/low/medium/high/critical) and
 `scan_report` (JSON breakdown) on the `prompt_templates` table. These fields are
 system-managed and not editable via the admin API.

@@ -455,43 +352,18 @@ Redaction types: `api_key`, `private_key`, `password`, `secret`.

 ### Configuration

-```text
-judge.output_guard = true    # enable output evaluation (default)
-judge.redact_secrets = true  # auto-redact detected credentials (default)
+```toml
+[judge]
+output_guard = true    # enable output evaluation (default)
+redact_secrets = true  # auto-redact detected credentials (default)
 ```

-Configure both at runtime through the admin Judge settings.
-
-### Merge semantics (heuristic + LLM judge)
-
-The chip is a **merge** of the two detectors (issue #560, "show, annotated"),
-not a winner-take-all:
-
- `risk_level` = **max**(heuristic, llm) and `flags` = **union**. A positive
-  from either detector surfaces; a negative ("none") or failed/absent LLM
-  **never lowers** a heuristic positive. The judge reads adversarial tool
-  output, so it may raise the alarm but must not be able to hide a
-  deterministic regex finding — defeating the judge can't erase the tripwire.
- Credential **redaction** is a heuristic-only signal the LLM cannot override.
- When the judge returned a verdict, its OWN verdict rides along as
-  annotation (`judge_risk` / `confidence` / `reasoning` / `judge_model`) so
-  the operator sees the judge's opinion even when it disagrees with the
-  displayed (merged) risk.
-
-The same merge runs live and on reconnect (both call
-`output_guard.merge_guard_display_payload`), so the chip can't drift between
-the two surfaces.
-
-The MODEL on the other side of the conversation is shown the merged
-`risk_level` + `flags` (via the `GuardAdvisory` spliced into the tool-result
-envelope), but is **never** told the judge cleared a finding — a judge fooled
-into "none" must not get to talk the model out of caution. The judge's
-"benign" verdict is operator-facing only.
+Configurable at runtime via the admin Settings tab.

 ### SSE event: `output_warning`

-When the merged finding is non-clean (or credentials were redacted), an
-`output_warning` SSE event is emitted to the frontend. A regex-only finding:
+When the output guard detects risk signals, an `output_warning` SSE event is
+emitted to the frontend:

 ```json
 {
@@ -502,58 +374,25 @@ When the merged finding is non-clean (or credentials were redacted), an
  "flags": ["credential_leak"],
  "annotations": ["API key detected (sk-proj-...)"],
  "output_length": 1024,
-  "redacted": true,
-  "tier": "heuristic"
+  "redacted": true
 }
 ```

-When the LLM judge returned a verdict, `tier` is `"llm"` and the event carries
-the judge's own verdict as annotation. Here the regex flagged MEDIUM but the
-judge assessed the output benign — the finding still surfaces (`risk_level`
-stays MEDIUM), annotated with the judge's dissent (`judge_risk: "none"`):
+The web UI renders this as an inline warning after the tool result. The CLI
+shows a colored terminal warning. The server forwards it as an
+`OutputWarningEvent` for console subscribers.

-```json
-{
-  "type": "output_warning",
-  "call_id": "call_def456",
-  "func_name": "web_fetch",
-  "risk_level": "medium",
-  "flags": ["camouflaged_injection"],
-  "annotations": ["Authority-framed directive embedded in the document."],
-  "output_length": 8192,
-  "redacted": false,
-  "tier": "llm",
-  "judge_risk": "none",
-  "confidence": 0.92,
-  "reasoning": "Legitimate analyst commentary; no injection.",
-  "judge_model": "gpt-5-mini"
-}
-```
-
-`judge_risk` (the judge's OWN risk verdict, which may differ from the merged
-`risk_level`), `confidence` (0.0–1.0), `reasoning`, and `judge_model` are
-present only on the `"llm"` tier. The identical shape is projected onto
-history replay by `build_merged_output_assessment_payload`, so the inline chip
-renders the same live and on refresh.
-
-The web UI renders this as an inline warning after the tool result — the
-`"llm"` tier adds a `⚖ LLM · NN%` badge (showing the judge's verdict when it
-differs from the displayed risk, e.g. `⚖ LLM: none · 92%`) and the judge's
-rationale. The CLI shows a colored terminal warning. The server forwards it as
-an `OutputWarningEvent` for console subscribers.
-
-Assessments are persisted to the `output_assessments` table (one row per
-`(call_id, tier)`) for calibration. Raw tool output is never stored — only
-metadata: flags, risk level, annotations, output length, redaction status,
-and — for the LLM tier — confidence, reasoning, judge model, and latency.
+Assessments are persisted to the `output_assessments` table for v2
+calibration. Raw tool output is never stored — only metadata (flags, risk
+level, annotations, output length, redaction status).

 ### Session-level skill scan warning

-When a skill with `risk_level` of `high` or `critical` is loaded into a
+When a skill with `scan_status` of `high` or `critical` is loaded into a
 session, a warning is emitted via `on_info`:

 ```
-⚠ Skill 'my-skill' has risk level: high.
+⚠ Skill 'my-skill' has scan status: high.
 Review scan report in admin panel before enabling in production.
 ```

@@ -570,7 +409,7 @@ All three evaluation systems persist their assessments for future calibration:
 |-------|--------|-------------|
 | `intent_verdicts` | Intent judge (heuristic + LLM) | `func_name`, `risk_level`, `confidence`, `user_decision` |
 | `output_assessments` | Output guard | `func_name`, `risk_level`, `flags`, `redacted` |
-| `prompt_templates` | Skill scanner | `risk_level`, `scan_report`, `scan_version` |
+| `prompt_templates` | Skill scanner | `scan_status`, `scan_report`, `scan_version` |

 Run v1 with all tools requiring manual approval to build a local dataset.
 In v2, calibration tooling will analyze this data to:
@@ -1,178 +0,0 @@
-# MCP OAuth — per-user authorization for MCP servers
-
-Turnstone supports **per-(user, MCP server) OAuth 2.1 + PKCE** delegation so each Turnstone user authorizes a remote MCP server with their own identity, rather than sharing a single bearer token across the deployment. This is the right shape for MCP servers that expose user-specific data (a personal CRM, an email inbox, a calendar) and for MCP servers that want per-user audit attribution.
-
-Per-user OAuth is opt-in per `mcp_servers` row. Local-auth Turnstone installs with no `oauth_user` rows exercise zero new code paths — the entire feature is dark by default.
-
-> **Note**: This is a separate authorization layer from Turnstone's own user authentication. A user who logs into Turnstone with a local username + password can still authorize a per-server OAuth MCP server. OIDC SSO and per-server OAuth are orthogonal.
-
---
-
-## When to use which `auth_type`
-
-The MCP server admin form exposes three authorization modes ("Multitenant Authorization"):
-
-| `auth_type` | What it means | When to use |
-|---|---|---|
-| `none` | No headers attached. Open MCP server (or one gated by network policy only). | Internal MCP servers on a trusted network. |
-| `static` | One static bearer token, configured per server, sent on every request from every user. | Service-to-service MCP servers where per-user attribution doesn't matter, or single-tenant deployments. |
-| `oauth_user` *(recommended for user-data servers)* | Each user authorizes separately via OAuth 2.1 + PKCE; Turnstone stores per-user tokens encrypted at rest. | MCP servers that expose user-specific data or that want per-user audit attribution. |
-| `oauth_obo` *(sign-in passthrough)* | Each user's Turnstone **org sign-in** (OIDC) mints a per-server access token on demand — no separate per-server consent. One captured credential per user covers every `oauth_obo` server. | Enterprise deployments where the identity provider governs access (Entra, Keycloak) and you want zero per-user connect clicks. See the dedicated section below. |
-
-Switching `auth_type` away from `oauth_user` / `oauth_obo` **deletes** that server's per-user rows (consents / minted cache) — see the transition table below. Switching back later starts clean: users re-consent (or re-mint) on next use. The admin **bulk-revoke** / **flush cache** affordance clears rows without an auth-type change.
-
---
-
-## Prerequisites for `auth_type=oauth_user`
-
-1. **Encryption key**. Tokens are stored encrypted with Fernet. Set `[security] mcp_token_encryption_key` in `config.toml` (Turnstone won't start with an `oauth_user` row configured but no key installed). Rotate via `MultiFernet` — add the new key first, then later remove the old one once all rows have been re-encrypted.
-
-2. **MCP server publishes RFC 9728 PRM and RFC 8414 AS metadata** *or* you configure the AS URL override on the server row. PKCE S256 is mandatory; Turnstone refuses to connect to authorization servers that don't advertise `code_challenge_methods_supported: ["S256"]`.
-
-3. **OAuth client registration**. Two paths:
-   - **Pre-registered** (most common): you create an OAuth client at the authorization server (manually, via admin console, or via Terraform), then paste the `client_id` / `client_secret` into the Turnstone admin form.
-   - **Dynamic client registration** (RFC 7591): if the AS supports it and you select that mode in the admin form, Turnstone registers a client at first use and persists the `client_id` automatically.
-
-4. **Redirect URI** registered at the authorization server: `https://your-turnstone-host/v1/api/mcp/oauth/callback`.
-
---
-
-## Configuration
-
-### Per-server fields (admin UI)
-
-| Field | Required | Description |
-|---|---|---|
-| Server URL | Yes | The MCP server's `streamable-http` base URL. |
-| Multitenant Authorization | Yes | `none` / `static` / `oauth_user` (recommended). |
-| Authorization Server URL | No | Override for RFC 9728 PRM discovery. Set when your AS endpoint differs from the MCP server URL (e.g., corporate AS protecting a third-party MCP). When unset, Turnstone falls back to PRM discovery against the MCP server itself. |
-| Client Registration | Yes (oauth_user) | `preregistered` or `dynamic`. |
-| Client ID | Yes (preregistered) | OAuth 2.0 client ID. Stored unencrypted. |
-| Client Secret | Optional (write-only) | OAuth 2.0 client secret (confidential client). Encrypted at rest. Written but never re-read by the API; field stays masked. |
-| Scopes | No | Space-separated default scope set requested at the authorize endpoint. Per-tool step-up may union additional scopes from a server's `insufficient_scope` response. |
-| Audience | No | RFC 8707 `resource=` parameter sent on every authorize and token request. Defaults to the MCP server URL when unset. Validate against the `aud` claim in returned JWT tokens. |
-
-### Encryption key
-
-```toml
-[security]
-mcp_token_encryption_key = "base64-fernet-key"
-# For rotation, list the keys in priority order — first is used for new
-# writes, all are tried for reads.
-# mcp_token_encryption_keys = ["new-key", "old-key"]
-```
-
-Keep this in `config.toml` rather than environment variables. An in-process LLM with shell-tool access can read the server's environment via `env` / `os.environ` and exfiltrate any secret stored there; secrets in `config.toml` are only loaded into the server at startup and never re-read on a tool-driven path, so a prompt-injection attack against the agent cannot reach them.
-
---
-
-## `auth_type=oauth_obo` — single-credential sign-in passthrough
-
-Where `oauth_user` makes each user complete a **separate** browser consent per MCP server, `oauth_obo` reuses the user's Turnstone **org sign-in** (OIDC). Turnstone captures one refresh credential per user at login and, on each tool call, mints a short-lived access token scoped to that server's audience. There is no per-server connect step, and one credential covers every `oauth_obo` server. This is the right shape when your identity provider already governs who may reach each backend (an Entra tenant with Entra-protected MCP servers; a Keycloak realm with token exchange).
-
-Access is governed **downstream** by the IdP: a user can only mint a token for a server their delegated permissions allow. Removing that grant at the IdP cuts the user off regardless of their Turnstone state.
-
-### Deployment configuration (`[oidc]` in `config.toml`)
-
-`oauth_obo` requires OIDC SSO to be configured (it is the credential source), plus:
-
-```toml
-[oidc]
-# ... your existing issuer / client_id / client_secret ...
-capture_user_credential = true          # persist the IdP refresh token at login
-obo_grant_profile = "entra"             # "entra" | "rfc8693" — how tokens are minted
-```
-
- **`capture_user_credential`** (default `false`): when enabled, Turnstone appends `offline_access` to the login scopes and stores the returned refresh token, encrypted with the same `[security] mcp_token_encryption_key` as `oauth_user` tokens. **The encryption key is required** — Turnstone refuses to start with an `oauth_obo` row (or capture enabled) and no key.
- **`obo_grant_profile`** picks the mint mechanism (the IdP determines which one is valid; this is deployment-wide, not per-server):
-  - **`entra`** — redeems the user's refresh token directly for a token scoped to `<audience>/.default`. `oauth_scopes` on the server row is **not used** (the admin form rejects it under this profile).
-  - **`rfc8693`** — a refresh grant for a subject token, then an RFC 8693 token exchange for the server audience. Per-server `oauth_scopes` **are** sent on the exchange (some IdPs require the audience scope explicitly).
-
-### Adding an `oauth_obo` server
-
-In the admin MCP form, choose **Sign-in passthrough** and set **Audience** (required — the downstream resource the token is minted for, e.g. `api://<app-id>` on Entra or the client id on Keycloak). The client-id / secret / registration fields do not apply and are hidden.
-
-`oauth_obo` servers are accepted only when **OIDC sign-in is configured and enabled** and `[oidc] obo_grant_profile` is a valid profile — the write is rejected otherwise, since a row that can never mint would surface to users as a permanent "please retry" that never heals.
-
-### Identity-provider setup
-
-**Entra (`obo_grant_profile = "entra"`):**
-1. Turnstone's app registration must hold **delegated permissions** to each MCP server's exposed API, with **admin consent granted** (or the MCP app listed in Turnstone's `preAuthorizedApplications`).
-2. Set the server row's Audience to the MCP app's Application ID URI (`api://<guid>`).
-3. **Gotcha (verified):** admin-consent issued *immediately* after creating the app/service principal can silently skip a not-yet-propagated resource — the only symptom is `AADSTS65001` at mint time. Verify the delegated grant landed (`az ad app permission list-grants` / the portal's *API permissions* blade shows *Granted*), or grant it explicitly per resource. A missing grant surfaces in Turnstone as a re-login prompt on the affected server (same rail as a revoked credential), and the `mcp_server.oauth.obo_mint_rejected` log line carries the raw `AADSTS…` text.
-
-**Keycloak / RFC 8693 (`obo_grant_profile = "rfc8693"`):**
-1. Enable **standard token exchange** on Turnstone's client.
-2. Grant the audience: add an audience client scope for each MCP client and attach it to Turnstone's client (optional scopes must be requested — set the server row's Scopes to that scope, or the exchange returns *"Requested audience not available"*).
-3. Set the server row's Audience to the downstream client id.
-
-### Revocation & custody
-
-The captured credential is a single per-user secret that can mint for every `oauth_obo` server, so treat it like any long-lived credential:
-
- **Cut off one user:** unlink their OIDC identity in the admin console (**Users → OIDC identities → delete**). This revokes the captured credential **and** purges their minted cache rows, so future mints fail and cached tokens are dropped. (Warmed in-memory sessions on server nodes self-expire at the access-token TTL; there is no cross-node per-user session-kill.) Removing the user's access at the IdP is the authoritative cut-off.
- The same unlink also purges that user's synthetic `__model_obo__:` gateway-token rows and requests eviction from every registered host's in-process mint memo. Shared `entra_app` model tokens live under the `__app__` pseudo-user and are intentionally not user-deprovisioned; revoking the app credential prevents new mints, while a cached app bearer lasts until `expires_at`.
- **Flush a server's minted tokens** (e.g. after narrowing its audience): the server row's **flush cache** action drops all users' cached tokens for that server. This is **not** a revocation — users re-mint on next use from their still-valid sign-in. It is surfaced honestly (audit `mcp_server.oauth.obo_cache_flushed`, response `effect: cache_flush_remints`) so it is never mistaken for cutting access.
- Per-server revocation in the `oauth_user` sense does not exist for `oauth_obo` — the credential is issuer-scoped and IdP-governed. Revoke at the IdP.
-
-> **Interim for Entra without OBO:** if you don't want host-side minting, admin consent + `preAuthorizedApplications` on each MCP app registration removes the second consent prompt for the plain `oauth_user` flow too (a tenant-config change, no Turnstone code). Tracked in issue #682. It does not remove the per-server connect clicks or per-(user, server) token custody — that is what `oauth_obo` is for.
-
---
-
-## Lifecycle
-
-1. **First tool call** for a user against an `oauth_user` MCP server: pool dispatch finds no stored token, returns `mcp_consent_required` to the agent. Dashboard renders an inline "Connect" action card.
-
-2. **User clicks Connect**: opens `/v1/api/mcp/oauth/start?server=<name>` in a popup. Browser redirects through the AS authorize endpoint, user grants consent, AS redirects back to `/v1/api/mcp/oauth/callback`. Turnstone exchanges code → tokens via PKCE, validates audience, encrypts, persists in `mcp_user_tokens`, redirects user back to the originating URL.
-
-3. **Subsequent tool calls** by the same user against the same server reuse the persisted token via the per-(user, server) session pool. Tokens auto-refresh via the refresh-token grant when expired; failed refresh emits `mcp_consent_required` to drive re-consent.
-
-4. **Step-up scope**: when a tool call hits `403` with `WWW-Authenticate: error="insufficient_scope"`, Turnstone emits `mcp_insufficient_scope` with the parsed scope set; the dashboard offers a "Connect with additional scopes" affordance that opens `/v1/api/mcp/oauth/start?server=<name>&scopes=<extra>` so the union of original + new scopes flows into the AS authorize request.
-
-5. **User revoke** (settings modal): `DELETE /v1/api/mcp/oauth/connections/{server_name}` runs the authoritative local delete + best-effort RFC 7009 upstream revoke (fire-and-forget, capped at 256 concurrent in-flight tasks). `oauth_obo` servers and synthetic model-auth rows are excluded: their rows are mint caches, not consents — deleting one only forces a re-mint — so the connections list hides them and the endpoint refuses them with `409` (revocation for sign-in passthrough happens at the identity layer: unlink the identity or revoke at the IdP).
-
-6. **Admin bulk-revoke** (Phase 9): `POST /v1/api/admin/mcp-servers/{name}/bulk-revoke` drops every user's token for the server. Upstream RFC 7009 revoke is intentionally **not** attempted in bulk (avoids N upstream HTTP calls per admin click); tokens at the AS expire naturally. Use the per-user revoke endpoint if you need guaranteed upstream invalidation.
-
---
-
-## Admin status indicators
-
-The MCP Servers admin tab shows per-server status pills (Phase 9):
-
- **Consented users count** — distinct users with a non-expired token for this server. Surfaced as a `bulk-revoke (N)` button when ≥1; clicking it opens a confirmation dialog. Hidden when 0.
- **Last refresh** — timestamp + outcome (`ok` / `error:ClassName`) of the most recent manual or auto-reconnect refresh. Per node. Absent until at least one refresh has occurred (renders as "never" in the admin UI).
-
-Additional indicators (circuit-breaker state, encryption-key mismatch) are exposed via `get_server_status` on the API but do not yet have a dedicated admin pill — operators see them today via the per-server status text + error tooltip and in audit logs. A future phase may surface these as discrete pills.
-
---
-
-## Auth-type transitions
-
-| From | To | What happens |
-|---|---|---|
-| `none` / `static` → `oauth_user` | — | New code path activates for this server. Existing static headers (if any) are no longer sent. Users must authorize on first use. |
-| `oauth_user` → `none` / `static` | — | Existing `mcp_user_tokens` rows are **deleted**: the tokens are bound to the auth model + URL active at consent time, and rows left behind could silently rebind if a row with the old name/URL reappears. Switching back to `oauth_user` later starts clean — users re-consent on next use. This is **not reversible**; the AS-side grants are untouched (revoke upstream via the AS if needed). |
-| OAuth `client_id` or `client_secret` rotated | — | Existing tokens may stop refreshing if the AS treats them as bound to the previous client. Bulk-revoke after rotation. |
-| `oauth_user` ↔ `oauth_obo` | — | The per-user rows are **deleted** on the flip (they mean different things: per-server AS refresh tokens vs. minted cache). `oauth_audience` and `oauth_scopes` mean different things in each model (a resource indicator vs. an IdP app identifier; AS-consent scopes vs. an rfc8693 exchange scope), so on a flip they **never carry** — each is taken from the request for the target model or set NULL. The admin console clears these fields when you change the auth type, so re-enter the correct values for the new mode; via the API, supply them explicitly (a flip into `oauth_obo` with no `oauth_audience` is rejected, and a non-empty `oauth_scopes` under the `entra` profile is rejected since that leg pins `<audience>/.default`). |
-| `oauth_obo` → `none` / `static` | — | Minted cache rows are deleted. |
-| `oauth_obo` **audience**, **URL**, or **`oauth_scopes`** changed | — | Minted cache rows are **deleted** (tokens are bound to the audience/URL/scopes at mint time), forcing a fresh mint — so an audience or scope narrowing takes effect immediately, not at token expiry. |
-
-Every transition that changes what a stored row *means* deletes the rows outright — a stale consent or minted token must never be served under new semantics. There is no orphan-and-reactivate path.
-
---
-
-## Troubleshooting
-
-| Symptom | Likely cause | Action |
-|---|---|---|
-| `mcp_consent_required` even after consenting | Token persistence failed, or refresh-token rejected by AS | Check audit log for `mcp_server.oauth.persist_failed` or `mcp_server.oauth.token_revoked`. Re-consent via settings modal. |
-| `mcp_token_undecryptable_key_unknown` | Encryption key rotated without keeping the previous key in the keyring | Add the previous key back to `mcp_token_encryption_keys` until all rows have been re-encrypted, then drop. |
-| `mcp_oauth_url_insecure` | MCP server URL is `http://` (not `https://`) on a non-loopback host | Use `https://`. Per-user bearers must not transit cleartext. |
-| Tools fail in scheduled / Discord / Slack runs | OAuth-MCP requires browser-based consent | Users must pre-consent via the web UI. Phase 9 dashboard badge surfaces deferred consents from these runs on next login. |
-| Circuit breaker open repeatedly | Transport-level errors on the MCP server (DNS, TLS, 5xx) | Check the per-server error pill; auth errors do not trip the breaker. |
-| **`oauth_obo`**: every tool call fails, log shows `obo_misconfigured` | Server row has no Audience, or `obo_grant_profile` is unset/unknown | Set the Audience on the server row; set `[oidc] obo_grant_profile` to `entra` or `rfc8693`. |
-| **`oauth_obo`**: `obo_mint_rejected` with `AADSTS65001` | Turnstone's app lacks the (admin-consented) delegated grant to this MCP app — often admin consent that didn't propagate | Grant + admin-consent the delegated permission for this resource; verify it shows *Granted*. See the Entra gotcha above. |
-| **`oauth_obo`**: "Sign in to Turnstone again" on one server | Captured credential missing/rejected, or a Conditional Access challenge | User re-logs into Turnstone (re-captures the credential). If it persists, check the IdP grant / CA policy. |
-| **`oauth_obo`**: tools don't appear at all for a user | User has not signed in since `capture_user_credential` was enabled (no credential captured) | User logs out and back in via OIDC so the refresh credential is captured. |
-
-See also: `docs/operations/mcp-oauth-headless.md` for the cron / channel-driven run caveat.
@@ -146,7 +146,7 @@ with TurnstoneConsole("http://localhost:8081", token="...") as client:
 ### TypeScript

 ```typescript
-import { TurnstoneConsole } from "@turnstone/sdk";
+import { TurnstoneConsole } from "@anthropic/turnstone-sdk";

 const client = new TurnstoneConsole({
  baseUrl: "http://localhost:8081",
@@ -20,79 +20,36 @@ Each memory has three dimensions:
 | Type        | Purpose                                                    |
 |-------------|------------------------------------------------------------|
 | `user`      | User preferences, conventions, working style               |
-| `general`   | General knowledge, architecture, patterns                  |
+| `project`   | Project-specific knowledge, architecture, patterns         |
 | `feedback`  | Corrections, lessons learned, things to avoid              |
 | `reference` | Reference material, documentation, specifications         |

 ### Memory scopes

-| Scope         | Visibility                                                      |
-|---------------|-----------------------------------------------------------------|
-| `global`      | Visible to all workstreams and users                            |
-| `workstream`  | Visible only within the originating workstream                  |
-| `user`        | Follows the authenticated user across workstreams               |
-| `coordinator` | Coordinator sessions only; follows the acting user              |
-| `project`     | Shared by workstreams attached to one active project             |
+| Scope        | Visibility                                                |
+|--------------|-----------------------------------------------------------|
+| `global`     | Visible to all workstreams and users                      |
+| `workstream` | Visible only within the originating workstream            |
+| `user`       | Follows the authenticated user across workstreams         |

 A memory's identity is the tuple `(name, scope, scope_id)`. Saving a memory
 with the same identity upserts -- updating content while preserving the ID.

-### Inherited target and coordinator scope
-
-Name-based operations use one inherited target when `scope` is omitted:
-
- An attached active project selects `project` for `save`, `get`, and
-  `delete`.
- Read-only project access permits `get`, but `save` and `delete` fail. They do
-  not fall back to a broader namespace.
- Without a project, interactive sessions select `global`; coordinator
-  sessions select `coordinator`.
-
-A valid explicit scope selects exactly that scope. `search` and `list` are the
-only actions that span every visible scope when `scope` is omitted.
-
-Each coordinator's private `coordinator` namespace is keyed by the acting
-user's `user_id`. It is durable -- every coordinator session that user runs
-(including concurrent ones) shares one orchestration namespace, so procedures
-and lessons survive close/reopen.
-
-Isolation is bidirectional and enforced by session kind, not by secrecy of
-the scope id:
-
- A coordinator session sees its acting user's `coordinator` scope and, when
-  attached, the shared `project` scope. It never sees
-  `global`/`workstream`/`user` memories.
- Interactive sessions -- including a coordinator's own children, which share
-  its `user_id` -- are rejected from the `coordinator` scope on every memory
-  action. Children cannot plant rows the parent coordinator would read.
- The REST memory API (`/v1/api/memories`) does not accept the `coordinator`
-  scope at all; the scope is written exclusively through a coordinator
-  session's own memory tool.
-
-Coordinator sessions require an authenticated user identity -- an anonymous
-coordinator cannot be constructed, so the scope id is always a real user.
-
 ### BM25 relevance injection

 On every conversation turn, the system:

-1. Resolves the acting principal and their live project access
-2. Fetches up to `fetch_limit` memories across that visibility envelope
-3. Extracts context from the last 3 user messages
-4. Scores memories against that context using a BM25 index
-5. Injects the top `relevance_k` memories into the system message as
+1. Fetches up to `fetch_limit` memories visible in the current scope
+2. Extracts context from the last 3 user messages
+3. Scores memories against that context using a BM25 index
+4. Injects the top `relevance_k` memories into the system message as
   `<memories>` XML tags
-6. Appends a hint telling the model how many memories are in scope
+5. Appends a hint telling the model how many memories are in scope

 This means the model always has its most relevant memories available without
 explicit recall -- but can still use `memory(action='search')` for deeper
 lookup.

-The persona memory lever gates this pathway: a workstream whose persona
-turns memory off receives no relevance injection at all -- the steps
-above run only when memory is enabled for the session. See
-[Personas](personas.md).
-
 ### Nudges

 The metacognition layer can nudge the model to save memories at appropriate
@@ -120,23 +77,19 @@ All fields are optional. Defaults are shown above.

 ## Tool Usage

-The `memory` tool supports five actions:
+The `memory` tool supports four actions:

 ### save

 Store or update a memory.

-Every save is a complete write for the relevance summary: `description` must
-be supplied and contain non-whitespace text on both creation and update.
-Content-only updates are rejected.
-
 ```json
 {
  "action": "save",
  "name": "project_architecture",
  "content": "The project uses a hexagonal architecture with...",
  "description": "Core architecture patterns",
-  "type": "general",
+  "type": "project",
  "scope": "global"
 }
 ```
@@ -145,26 +98,9 @@ Content-only updates are rejected.
 |---------------|----------|-------------|------------------------------------------|
 | `name`        | yes      | --          | Snake_case identifier (max 256 chars)    |
 | `content`     | yes      | --          | Memory content (max `max_content` chars) |
-| `description` | yes      | --          | Non-empty relevance summary, required on create and update |
-| `type`        | no       | `"general"` | One of: user, general, feedback, reference |
-| `scope`       | no       | inherited   | Kind-valid scope; see inherited target above |
-
-### get
-
-Retrieve the full content of one memory by name.
-
-```json
-{
-  "action": "get",
-  "name": "project_architecture",
-  "scope": "project"
-}
-```
-
-| Parameter | Required | Default   | Description                |
-|-----------|----------|-----------|----------------------------|
-| `name`    | yes      | --        | Memory name to retrieve    |
-| `scope`   | no       | inherited | Exact scope to query       |
+| `description` | no       | `""`        | Short description for relevance matching |
+| `type`        | no       | `"project"` | One of: user, project, feedback, reference |
+| `scope`       | no       | `"global"`  | One of: global, workstream, user         |

 ### search

@@ -174,7 +110,7 @@ Find memories by query (BM25 full-text search).
 {
  "action": "search",
  "query": "authentication patterns",
-  "type": "general",
+  "type": "project",
  "limit": 10
 }
 ```
@@ -201,7 +137,7 @@ Remove a memory by name.
 | Parameter  | Required | Default    | Description              |
 |------------|----------|------------|--------------------------|
 | `name`     | yes      | --         | Memory name to delete    |
-| `scope`    | no       | inherited | Exact scope to delete    |
+| `scope`    | no       | `"global"` | Scope of the memory      |

 ### list

@@ -231,12 +167,6 @@ Four endpoints on the server for programmatic memory access.

 List memories with optional filters.

-Without `scope`, the response is restricted to `global` plus the authenticated
-caller's `user` namespace. The public API accepts only `global`, `user`, and
-`workstream`; internal `project` and `coordinator` namespaces remain available
-through the session tool and admin API. Explicit `workstream` access requires
-its persisted owner (or a service token).
-
 **Query parameters:**

 | Parameter  | Type   | Required | Default | Description                  |
@@ -244,10 +174,10 @@ its persisted owner (or a service token).
 | `type`     | string | no       | `""`    | Filter by memory type        |
 | `scope`    | string | no       | `""`    | Filter by scope              |
 | `scope_id` | string | no       | `""`    | Filter by scope ID           |
-| `limit`    | int    | no       | `100`   | Max results (1-200)          |
+| `limit`    | int    | no       | `100`   | Max results (capped at 200)  |

-When `scope=user`, the authenticated user's ID is used automatically and a
-different supplied ID is rejected. `scope=workstream` requires `scope_id`.
+When `scope=user` and `scope_id` is omitted, the authenticated user's ID is
+used automatically.

 **Response:** `200`

@@ -258,7 +188,7 @@ different supplied ID is rejected. `scope=workstream` requires `scope_id`.
      "memory_id": "a1b2c3d4-e5f6-...",
      "name": "project_architecture",
      "description": "Core architecture patterns",
-      "type": "general",
+      "type": "project",
      "scope": "global",
      "scope_id": "",
      "content": "The project uses a hexagonal architecture...",
@@ -276,9 +206,6 @@ different supplied ID is rejected. `scope=workstream` requires `scope_id`.

 Save or upsert a structured memory.

-`description` is mandatory for both creates and updates and must contain
-non-whitespace text. The API rejects content-only updates.
-
 **Request body:**

 ```json
@@ -286,7 +213,7 @@ non-whitespace text. The API rejects content-only updates.
  "name": "deployment_process",
  "content": "Deploy via GitHub Actions. Staging auto-deploys on push to main.",
  "description": "CI/CD deployment workflow",
-  "type": "general",
+  "type": "project",
  "scope": "global",
  "scope_id": ""
 }
@@ -296,8 +223,8 @@ non-whitespace text. The API rejects content-only updates.
 |--------------|--------|----------|-------------|--------------------------------------|
 | `name`       | string | yes      | --          | Memory name (max 256 chars)          |
 | `content`    | string | yes      | --          | Memory content (max 65536 chars)     |
-| `description`| string | yes      | --          | Non-empty relevance summary, required on create and update |
-| `type`       | string | no       | unset       | user, general, feedback, or reference |
+| `description`| string | no       | `""`        | Short description for search ranking |
+| `type`       | string | no       | `"project"` | One of: user, project, feedback, reference |
 | `scope`      | string | no       | `"global"`  | One of: global, workstream, user     |
 | `scope_id`   | string | no       | `""`        | Scope qualifier (auto-resolved for user scope) |

@@ -308,7 +235,7 @@ non-whitespace text. The API rejects content-only updates.
  "memory_id": "a1b2c3d4-e5f6-...",
  "name": "deployment_process",
  "description": "CI/CD deployment workflow",
-  "type": "general",
+  "type": "project",
  "scope": "global",
  "scope_id": "",
  "content": "Deploy via GitHub Actions...",
@@ -324,10 +251,7 @@ same `(name, scope, scope_id)` already existed.

 | Status | Condition                          |
 |--------|------------------------------------|
-| 400    | Invalid input, scope, scope ID, or limit |
-| 403    | Cross-user or non-owner workstream access |
-| 404    | Explicit workstream does not exist |
-| 500    | Storage mutation failed |
+| 400    | Missing name, empty content, invalid type/scope, content too long |

 ---

@@ -336,15 +260,12 @@ same `(name, scope, scope_id)` already existed.
 Search memories by query. Uses POST for the request body but is non-mutating
 (requires only `read` scope).

-An omitted scope searches the same caller-bound `global` + `user` envelope as
-the list endpoint. It never means every row in the table.
-
 **Request body:**

 ```json
 {
  "query": "authentication",
-  "type": "general",
+  "type": "project",
  "scope": "",
  "scope_id": "",
  "limit": 20
@@ -357,7 +278,7 @@ the list endpoint. It never means every row in the table.
 | `type`     | string | no       | `""`    | Filter by type                 |
 | `scope`    | string | no       | `""`    | Filter by scope                |
 | `scope_id` | string | no       | `""`    | Filter by scope ID             |
-| `limit`    | int    | no       | `20`    | Max results (1-50)             |
+| `limit`    | int    | no       | `20`    | Max results (capped at 50)     |

 **Response:** `200`

@@ -368,7 +289,7 @@ the list endpoint. It never means every row in the table.
      "memory_id": "a1b2c3d4-e5f6-...",
      "name": "auth_patterns",
      "description": "Authentication architecture",
-      "type": "general",
+      "type": "project",
      "scope": "global",
      "scope_id": "",
      "content": "JWT tokens with HS256...",
@@ -386,9 +307,6 @@ the list endpoint. It never means every row in the table.

 Delete a memory by name and scope.

-Deletes are atomic: the row used for the success result and audit event is the
-row actually removed. A storage failure returns `500`, not a false `404`.
-
 **Path parameters:**

 | Parameter | Type   | Description          |
@@ -443,7 +361,7 @@ List memories across all scopes (no automatic scope resolution).
      "memory_id": "a1b2c3d4-e5f6-...",
      "name": "project_architecture",
      "description": "Core architecture patterns",
-      "type": "general",
+      "type": "project",
      "scope": "global",
      "scope_id": "",
      "content": "The project uses...",
@@ -492,7 +410,7 @@ Get a single memory by ID.
  "memory_id": "a1b2c3d4-e5f6-...",
  "name": "project_architecture",
  "description": "Core architecture patterns",
-  "type": "general",
+  "type": "project",
  "scope": "global",
  "scope_id": "",
  "content": "The project uses...",
@@ -549,13 +467,13 @@ with TurnstoneServer("http://localhost:8080", token="tok_xxx") as client:
        "api_conventions",
        "All endpoints use /v1/ prefix. JSON responses.",
        description="API design patterns",
-        mem_type="general",
+        mem_type="project",
        scope="global",
    )
    print(mem.memory_id)

    # Search memories
-    results = client.search_memories("authentication", mem_type="general", limit=10)
+    results = client.search_memories("authentication", mem_type="project", limit=10)
    for m in results.memories:
        print(f"{m['name']}: {m['description']}")

@@ -576,7 +494,7 @@ with TurnstoneConsole("http://localhost:9090", token="tok_xxx") as admin:
    result = admin.list_memories(scope="global", limit=100)

    # Search
-    result = admin.search_memories("architecture", mem_type="general")
+    result = admin.search_memories("architecture", mem_type="project")

    # Get by ID
    mem = admin.get_memory("a1b2c3d4-e5f6-...")
@@ -600,14 +518,14 @@ const mem = await client.saveMemory({
  name: "api_conventions",
  content: "All endpoints use /v1/ prefix. JSON responses.",
  description: "API design patterns",
-  type: "general",
+  type: "project",
  scope: "global",
 });

 // Search memories
 const results = await client.searchMemories({
  query: "authentication",
-  type: "general",
+  type: "project",
  limit: 10,
 });

@@ -39,20 +39,18 @@ are set.
 | `TURNSTONE_OIDC_ROLE_CLAIM` | No | — | ID token claim containing role/group values (see [Role Mapping](#role-mapping)) |
 | `TURNSTONE_OIDC_ROLE_MAP` | No | — | Mapping from claim values to Turnstone role IDs (see [Role Mapping](#role-mapping)) |
 | `TURNSTONE_OIDC_PASSWORD_ENABLED` | No | `true` | Set to `false` to hide the password form and block all username/password logins (including admin). API tokens continue to work. |
-| `TURNSTONE_OIDC_REDIRECT_BASE` | Yes | — | Externally-reachable origin for the OIDC redirect URI (e.g. `https://app.example.com`). Without this, OIDC will refuse to start. The previous Host-header fallback was unsafe under permissive reverse proxies. |
-| `TURNSTONE_OIDC_TRUSTED_ENDPOINT_HOSTS` | No | — | Comma-separated list of additional hostnames whose endpoints the IdP discovery document is allowed to reference. See [Cross-host endpoints](#cross-host-endpoints). |
-| `TURNSTONE_OIDC_ALLOW_PRIVATE_NETWORK` | No | `false` | Allow the issuer (and its discovered endpoints) to resolve to private/internal addresses — needed for a self-hosted IdP on an internal network. See [Self-hosted and internal IdPs](#self-hosted-and-internal-idps). |
+| `TURNSTONE_OIDC_REDIRECT_BASE` | No | — | Externally-reachable origin for the OIDC redirect URI (e.g. `https://app.example.com`). Recommended when running behind a reverse proxy. When unset, derived from the request Host header. |

-All four required fields — issuer, client ID, client secret, and
-`TURNSTONE_OIDC_REDIRECT_BASE` — must be set. If any are missing OIDC
-is disabled at startup (an error is logged when only `redirect_base`
-is missing) and the login screen shows only the password form.
+OIDC is enabled when all three required fields (issuer, client ID, client
+secret) are non-empty. If any is missing, OIDC is silently disabled and
+the login screen shows only the password form.

-### Redirect base (required)
+### Reverse Proxy / Load Balancer

-`TURNSTONE_OIDC_REDIRECT_BASE` pins the redirect URI sent to the identity
-provider to a known externally-visible origin. Set it to the public origin
-of your Turnstone deployment:
+When Turnstone runs behind a reverse proxy, the internal `Host` header may
+not match the externally-reachable URL. Set `TURNSTONE_OIDC_REDIRECT_BASE`
+to the public origin so the redirect URI sent to the identity provider is
+correct:

 ```bash
 TURNSTONE_OIDC_REDIRECT_BASE=https://app.example.com
@@ -62,140 +60,6 @@ The resulting callback URL will be
 `https://app.example.com/v1/api/auth/oidc/callback` — register this as the
 authorized redirect URI in your identity provider.

-OIDC will refuse to start when this variable is unset. There is no
-Host-header fallback: a permissive reverse proxy or direct backend access
-would otherwise let an attacker spoof `Host` and steer the IdP redirect
-to a callback origin they control.
-
-### Cross-host endpoints
-
-By default, every endpoint in the IdP discovery document
-(`token_endpoint`, `jwks_uri`, `userinfo_endpoint`) must share the
-issuer's `(scheme, host, port)`. This prevents a hostile or compromised
-IdP from redirecting the token-exchange POST (which carries
-`client_secret`) to an arbitrary host, and prevents JWKS fetches from
-being aimed at internal services.
-
-A few public IdPs legitimately split endpoints across hostnames. Google
-and Microsoft Entra ID are the canonical examples:
-
-| IdP | Issuer host | Cross-host endpoint(s) |
-|-----|-------------|------------------------|
-| Google | `accounts.google.com` | `oauth2.googleapis.com`, `www.googleapis.com`, `openidconnect.googleapis.com` |
-| Microsoft Entra | `login.microsoftonline.com` | `graph.microsoft.com` (userinfo) |
-
-Both sets are built in — operators using `https://accounts.google.com` or
-`https://login.microsoftonline.com/<tenant>/v2.0` need no extra
-configuration. (Entra's discovery document advertises `userinfo_endpoint`
-on `graph.microsoft.com`, distinct from the issuer host.)
-
-For other IdPs whose discovery document references a non-issuer host,
-extend the allow-list explicitly:
-
-```bash
-TURNSTONE_OIDC_TRUSTED_ENDPOINT_HOSTS=token.example.com,keys.example.com
-```
-
-The same scheme / no-userinfo / SSRF rules apply to allow-listed hosts —
-this knob only relaxes the same-origin check, not the security gates.
-Each entry is a hostname (no scheme, no path).
-
-### Self-hosted and internal IdPs
-
-By default Turnstone refuses an issuer whose hostname resolves to a
-private or internal address:
-
-```
-OIDCError: endpoint URL resolves to non-public address (10.0.0.5): https://auth.example.site
-```
-
-This is SSRF hardening, not a licensing or product restriction: the OIDC
-flow makes server-side HTTP requests (discovery, JWKS, token exchange),
-and refusing non-public destinations keeps a mistyped or maliciously
-steered issuer from aiming those fetches at internal services. For a
-self-hosted IdP (Keycloak, Authentik, Dex, …) on a private network,
-opt in explicitly in `config.toml`:
-
-```toml
-[oidc]
-allow_private_network = true
-```
-
-or via `TURNSTONE_OIDC_ALLOW_PRIVATE_NETWORK=true` (the env var wins
-when both are set).
-
-The opt-in admits private-range (RFC 1918), unique-local, site-local,
-CGNAT (100.64/10, where overlay VPNs commonly assign hosts), and
-loopback addresses. Link-local, multicast, reserved ranges and known
-cloud-metadata endpoints stay refused even with the opt-in — no
-legitimate IdP lives there. An address is judged by what it actually
-reaches, so an IPv6 transition address (NAT64, 6to4, Teredo) wrapping
-an internal IPv4 is treated exactly as that IPv4 would be. The HTTPS
-requirement and the same-origin endpoint checks are unaffected.
-
-This knob only affects the login-flow IdP configured here. OAuth
-endpoints advertised by remote MCP servers are untrusted input and are
-always held to the strict public-address rule.
-
-### Model gateway credentials
-
-The same OIDC registration can authenticate model gateways. A model definition
-with `auth_mode = "entra_obo"` (Entra grant profile) or `auth_mode =
-"rfc8693_obo"` (RFC 8693 token-exchange profile) redeems the driving user's
-captured credential for its exact `obo_audience`; `auth_mode = "entra_app"`
-uses the registration's client ID and secret with Entra client credentials.
-All three bind the result through the provider SDK's native credential option
-rather than injecting an override header. The grant mode is never inferred:
-missing user context or a failed OBO mint cannot switch a delegated definition
-to client credentials.
-
-Each dynamic mode pairs with the grant profile whose dialect it names:
-`entra_obo` and `entra_app` require `obo_grant_profile = "entra"`;
-`rfc8693_obo` requires `obo_grant_profile = "rfc8693"`. The pairing is
-enforced when a write chooses a `(auth_mode, obo_audience)` pair — a same-pair
-edit of a row saved before the pairing rule keeps working — and at runtime a
-mismatched legacy row refuses to mint with `cause=grant_profile_mismatch` and
-no IdP traffic. RFC 8693 client-credentials is not implemented.
-
-The delegated modes need the MCP encryption key, a credential captured for the
-driving user, and delegated/admin-consented permission to the audience.
-`rfc8693_obo` additionally carries `obo_scopes`, the space-separated scope
-list its exchange leg requests: exchange-capable IdPs that gate audiences
-behind optional scopes refuse the exchange without it ("Requested audience not
-available"), which is why the scope-less Entra-named mode could never mint on
-that profile (issue #955). Scopes are stored shape-checked only — whether a
-value satisfies the IdP stays the IdP's call at mint time. Turning
-`capture_user_credential` off later stops *new* captures but does not
-invalidate credentials already stored, so existing users keep minting.
-`entra_app` requires a confidential-client secret. Configure the permitted
-resource IDs in the runtime setting `model.auth_audience_allowlist` before
-saving dynamic model definitions. De-listing an audience later blocks every
-write that would arm or re-aim a definition at it, but does not stop aliases
-already configured from minting — disabling the row (the `admin.models` disarm
-lever) is what stops minting. See
-[Settings](settings.md#model-backend-authentication) for permissions, failure
-policy, and lane identity rules.
-
-An unrecognised `obo_grant_profile` is warned about at startup and **rejected
-at the write choke points**: configuring an `oauth_obo` MCP server or a dynamic
-model alias returns a 400 that echoes the configured value, so the typo is the
-diagnosis. At runtime an unknown profile never mints — the mint legs resolve by
-exact name; the full cause detail is logged once per audience, and every
-affected call still logs its per-turn fallback or refusal naming the alias,
-the target audience, and the last recorded cause (`cause=` — for example
-`unsupported_grant_profile` or `oidc_not_enabled`) — so a pre-existing row
-degrades loudly, with the reason visible mid-incident even after the
-once-per-process line has rotated out of retained logs, rather than silently
-swapping per-user attribution for the shared static key.
-
-The `[security]` token encryption key is deployment-wide, not per-host: rows are
-encrypted with `MultiFernet` and carry no key id, so every host that reads them
-needs the same keyring. That includes the console, which mints for
-coordinator-hosted sessions. A node that needs the key and lacks it refuses to
-start; the console starts but withholds its coordinator subsystem and shows
-the key requirement as the remediation error instead of failing silently at
-call time.
-
 ### config.toml alternative

 ```toml
@@ -208,8 +72,6 @@ provider_name = "Google"
 role_claim = "groups"
 password_enabled = true
 redirect_base = "https://app.example.com"
-# Self-hosted IdP on an internal network (see "Self-hosted and internal IdPs")
-allow_private_network = false

 [oidc.role_map]
 admin = "builtin-admin"
@@ -336,19 +198,6 @@ TURNSTONE_OIDC_ROLE_MAP="admin:builtin-admin,engineering:builtin-operator,viewer
  the user authenticates via OIDC, so new group memberships are picked
  up on the next login.

-### `assigned_by` markers
-
-Role assignments record an `assigned_by` value that controls how the
-sync logic treats them. OIDC-driven flows use two distinct markers:
-
- `oidc` — set by claim-driven role mapping; revoked automatically on
-  the next login when the corresponding claim value is no longer
-  present.
- `oidc-default` — applied to brand-new OIDC users who have no
-  claim-mapped roles, as a safety net so they still get
-  `builtin-viewer` access on first login. Survives subsequent logins
-  regardless of claim contents and is never revoked by `apply_role_mapping`.
-
 ### Built-in Roles

 | Role ID | Permissions |
@@ -526,27 +375,10 @@ callback validation. Entries are automatically cleaned up after 5 minutes.

 ### "OIDC not configured"

-All four required environment variables must be set:
-`TURNSTONE_OIDC_ISSUER`, `TURNSTONE_OIDC_CLIENT_ID`,
-`TURNSTONE_OIDC_CLIENT_SECRET`, and `TURNSTONE_OIDC_REDIRECT_BASE`.
-Check that none are empty or whitespace-only.
-
-### "OIDC enabled but TURNSTONE_OIDC_REDIRECT_BASE is unset"
-
-This error is logged when the three credential variables are set but
-`TURNSTONE_OIDC_REDIRECT_BASE` is missing. OIDC is disabled at startup
-to prevent Host-header-derived redirect URI spoofing. Set the variable
-to your service's externally-visible origin (e.g.
-`https://app.example.com`) and restart the server. See
-[Redirect base](#redirect-base-required) for the rationale.
-
-### Discovery silently disables OIDC with "host does not match issuer"
-
-The IdP discovery document points `token_endpoint`, `jwks_uri`, or
-`userinfo_endpoint` at a hostname that doesn't share the issuer's
-origin. If the IdP is legitimate, add the additional hostname(s) to
-`TURNSTONE_OIDC_TRUSTED_ENDPOINT_HOSTS`. Google is allow-listed
-automatically; see [Cross-host endpoints](#cross-host-endpoints).
+All three required environment variables must be set:
+`TURNSTONE_OIDC_ISSUER`, `TURNSTONE_OIDC_CLIENT_ID`, and
+`TURNSTONE_OIDC_CLIENT_SECRET`. Check that none are empty or
+whitespace-only.

 ### "Login session expired"

@@ -94,7 +94,7 @@ cannot bypass the proxy.
 |--------|-------|---------|
 | `openai_api` | `api.openai.com` | OpenAI LLM API |
 | `anthropic_api` | `api.anthropic.com` | Anthropic LLM API |
-| `searxng` | `searxng:8080` (bundled service) | Web search backend |
+| `tavily_api` | `api.tavily.com` | Web search fallback |
 | `skills_registry` | `skills.sh` | Skill discovery |
 | `github_api` | `api.github.com` (read-only L7), `raw.githubusercontent.com` | Skill fetch, GitHub API |
 | `mcp_registry` | `registry.modelcontextprotocol.io` (read-only L7) | MCP server discovery |
@@ -1,29 +0,0 @@
-# MCP OAuth in headless / scheduled / channel-driven runs
-
-**Constraint**: OAuth-MCP servers (`auth_type=oauth_user`) require browser-based user consent. Users must pre-consent via the web UI before any run that cannot drive a browser redirect.
-
-**Affected surfaces**:
-
- Scheduled workstreams (`turnstone-console` task scheduler).
- Discord adapter runs.
- Slack adapter runs.
- Any future channel adapter without an interactive browser session.
-
-**What happens when consent is missing**:
-
-A tool call against an `oauth_user` server returns a structured `mcp_consent_required` error to the agent. The agent surfaces the deferred work in its output. Turnstone persists a record to `mcp_pending_consent` so the dashboard badge surfaces the deferred consent need to the user on next login.
-
-**Recovery**:
-
-The user opens the dashboard, sees the gear-icon badge counting pending consents, opens the settings modal, clicks Connect for each affected server, and completes the OAuth dance. The pending-consent record is cleared by the OAuth callback handler on success. Subsequent scheduled / channel runs use the freshly-stored token.
-
-**Pre-consent recipe**:
-
-Before scheduling a workstream that depends on an `oauth_user` MCP server, the user should:
-
-1. Open the dashboard.
-2. Open the settings modal (gear icon).
-3. Click Connect on each MCP server the schedule will use.
-4. Confirm consent in the popup.
-
-This stores tokens that the scheduled run will reuse. Refresh-token rotation is handled transparently on the run side; only the first consent requires browser interaction.
@@ -1,173 +0,0 @@
-# Personas
-
-A **persona** is a named, reusable bundle attached to a workstream **at
-creation** that controls how its system message is composed and what
-capability envelope it runs with. Personas answer a recurring operational
-complaint: the default composition primes every session for heavy tool use,
-and there was no per-workstream dial to launch a "just write prose" or
-"evidence-first research" session.
-
-A persona is exactly four levers — no more:
-
-| Lever | What it does |
-|---|---|
-| **Base prompt** | Replaces the BASE module of the composed system message. *Only* BASE: ENV, CONTEXT, TOOLS, and POLICIES keep composing, so mandatory [prompt policies](governance.md) ride on top of every persona. Built-in personas source their prose from a repo file; operator personas store it inline — see [Where persona prompts live](#where-persona-prompts-live). |
-| **Tool visibility** | Which tools the session advertises. Tri-state: *unrestricted* (tracks tool growth and MCP catalogs), *no tools* (the TOOLS prompt block self-suppresses and zero definitions go on the wire), or an *exact set* of names. Including `tool_search` in a set makes it **soft** — tools the model discovers through search join the visible set; omitting it makes the set **hard** (the search pathway is disabled entirely). On commercial providers a soft set costs one prompt-cache re-prime per `tool_search` expansion, since each expansion rewrites the wire tool set and recomposes the prompt. |
-| **MCP** | Whether the workstream talks to MCP at all. **Session-wide**: off means no MCP tools for the persona's own hands *or* for in-process task agents, no resource/prompt catalogs, and no listener registrations. This lever expresses infrastructure intent, not behavior shaping. |
-| **Memory** | Whether the persona's **own hands** get memory: recalled-memory injection into the prompt, memory-directed metacognitive nudges, and the `memory` tool. Task agents keep their own envelope, and compaction spill/markers are session mechanics that are never persona-gated. An exact tool set that hides `memory` also mutes those nudges, and the compaction-resume pointer follows `recall`'s visibility. |
-
-Visibility is behavior shaping, **not** a security boundary: any tool call
-that does reach the wire still clears the same approval, judge, and policy
-machinery as always. RBAC and tool policies remain the enforcement layers.
-
-## Snapshot semantics — resolve once, stamp forever
-
-The persona is resolved **once**, at workstream creation, and stamped into
-`workstream_config` as five keys (`persona`, `persona_prompt`,
-`persona_tools`, `persona_mcp`, `persona_memory`). From then on the session
-reads only the stamp:
-
- **Editing or archiving a persona never changes an existing workstream.**
-  Rehydrate, resume, and post-compaction resume all run from the stamp.
-  A mid-session REPL `/resume` adopts the target workstream's stamp for
-  prompt, tools, and memory; for the MCP lever it can only narrow in
-  place — adopting an MCP-off stamp drops the live MCP surface, while
-  adopting an MCP-on stamp into a session whose persona dropped MCP at
-  construction is refused with an error telling you to reopen the
-  workstream fresh.
- A workstream outlives its persona — an archived persona keeps labelling
-  the workstreams stamped with it.
- A partial or unparseable stamp is treated as corruption: session
-  construction fails loudly rather than silently falling back to a default
-  envelope the operator never chose.
- Workstreams created before personas existed carry no stamp and keep
-  legacy behavior, byte-identical to the `engineer` / `orchestrator`
-  defaults below — with one exception: pre-1.7 workstreams that had
-  `creative_mode` set are converted by migration `063` into full
-  `writer` stamps, so they resume as writing sessions rather than as
-  legacy defaults.
- Forking (`resume_ws` on create) clones the source's stamped persona into the
-  new workstream; the fork does not re-resolve it.
-
-## Seed personas
-
-Migration `063` seeds six personas. The two per-kind **defaults** carry no
-overrides at all, so a zero-touch launch behaves exactly as it did before
-personas existed:
-
-| Persona | Kind | Base prompt | Tools | MCP | Memory |
-|---|---|---|---|---|---|
-| `engineer` *(default)* | interactive | stock | unrestricted | on | on |
-| `orchestrator` *(default)* | coordinator | stock | unrestricted | on | on |
-| `scribe` | interactive | custom (faithful structuring of given material) | none | off | off |
-| `researcher` | interactive | custom (evidence-first) | `read_file`, `search`, `web_fetch`, `web_search`, `recall`, `memory`, `tool_search` (soft) | off | on |
-| `writer` | interactive | custom (creative writing partner — replaces the removed `/creative`) | none | off | on |
-| `executive` | coordinator | custom (delegate, interrogate plans, judge outcomes) | spawn/inspect/lifecycle tools plus `memory`: `spawn_workstream`, `spawn_batch`, `send_to_workstream`, `wait_for_workstream`, `inspect_workstream`, `list_workstreams`, `list_nodes`, `close_workstream`, `cancel_workstream`, `memory` (hard) | off | on |
-
-Notes:
-
- `scribe` turns memory off deliberately: recalled memories would
-  contaminate faithful summarization with unrelated context.
- `researcher`'s set is soft (includes `tool_search`): it starts with
-  read and evidence tools but can pull in others on demand — e.g. load
-  `bash` to run a snippet and verify a calculation. It is evidence-first,
-  not sandboxed; any escalated tool still hits the normal approval path.
- Coordinator sessions do not merge MCP today, so the MCP lever on
-  coordinator personas is forward-compatible bookkeeping; it bites on
-  interactive workstreams.
-
-## Where persona prompts live
-
-Prompt source is explicit in the persona row — two nullable columns, never both empty:
-
-| `base_prompt_file` | `base_prompt` | Meaning |
-|---|---|---|
-| set (e.g. `scribe.md`) | — | **built-in**: prose lives in `prompts/personas/<file>`, code-owned and PR-reviewed |
-| set | set | built-in with an **operator override** layered on top (the inline text wins) |
-| — | set | **operator** persona, inline prose |
-
-A `CHECK` forbids the both-empty row, so resolution is a plain coalesce —
-`base_prompt ?? load(base_prompt_file)` — with no implicit "inherit the default"
-branch in application logic. `base_prompt_file` is set only by the migration/code
-(the admin API never exposes it): it marks a persona as built-in and blocks
-archive, so `engineer` and `orchestrator` can't be removed. To customise a
-built-in, set `base_prompt` on it (clear it to revert), or create your own persona.
-
-The resolved prompt is **frozen into the workstream at creation** — later edits to
-a built-in's file or an operator's row never change a running workstream; only new
-ones pick up the change. "No persona" is not a state: every workstream is stamped,
-and an empty `persona=` resolves to the kind's `is_default` (`engineer` /
-`orchestrator`).
-
-## Choosing a persona
-
-Every creation surface takes an optional persona; empty always means the
-kind's default (or plain legacy behavior on a database with no personas
-seeded):
-
- **Web/console**: the persona select on the console launcher, the server
-  webui's new-workstream dialog, and the dashboard composer. Selecting a
-  persona requires **no** `persona.*` permission — the picker feed
-  (`GET /v1/api/personas`) is authenticated-only and returns display fields.
- **API/SDK**: `CreateWorkstreamRequest.persona` (Python:
-  `create_workstream(persona=...)`; TypeScript: `{ persona: ... }`).
- **CLI**: `turnstone --persona <name>`. Unknown or disabled names error at
-  startup. `--resume` ignores `--persona` and adopts the resumed
-  workstream's stamp.
- **Coordinator spawn**: `spawn_workstream` / `spawn_batch` take a
-  `persona` argument, validated when the coordinator prepares the spawn
-  and re-checked by the node that creates the child (children are always
-  interactive-kind). Omitted means the interactive **default** — a child
-  never inherits its parent coordinator's persona.
- **Sub-agents**: `task_agent` takes a `persona` argument setting the
-  sub-agent's identity and capability envelope (resolved against
-  interactive-kind personas, frozen into the task at prep). Omitted keeps
-  the default autonomous task-agent identity — never the parent's persona.
-
-## How agents discover personas
-
-Agents are told, not expected to guess: the live persona list (enabled,
-interactive-kind — children and sub-agents are always interactive) is
-injected into the `persona` parameter description of `task_agent`,
-`spawn_workstream`, and `spawn_batch` whenever the session's tool surface
-is rendered — session start, MCP catalog change, model-registry reload.
-Each entry carries the name, the default marker, and the persona's
-one-line description so the model can pick by purpose (descriptions drop
-out past 25 personas; the name list always enumerates completely).
-
-A persona created after that render is still reachable — pass its name.
-Every resolve failure enumerates the names currently valid for the kind,
-so a stale list (or a typo) self-corrects on the next attempt.
-
-Resolution is forgiving on all surfaces (they share one rule):
-
- names match case-insensitively (`Writer` resolves `writer`);
- an input that uniquely matches a persona's **display name**
-  (case-insensitive, among the kind's enabled personas — display names are
-  not unique, and a same-label persona of another kind neither blocks nor
-  wins) resolves to that persona; an ambiguous match errors, listing the
-  candidate slugs;
- whatever variant matched, the stamped identity, approval chrome, and
-  wire always carry the canonical `name` slug.
-
-## Authoring (console)
-
-Personas are managed in the console's **Manage → Governance → Personas**
-tab. The admin shelf exposes exactly the four levers plus the kind
-list, the default marker, and archive. Rules:
-
- `name` is an immutable lowercase slug — and the identifier agents and
-  the CLI launch the persona by (`persona=` on the spawn tools,
-  `--persona` on the CLI); the create shelf says so under **Name**.
-  `display_name` is a list label, editable any time, and deliberately
-  not an identifier (a unique display name happens to resolve, as a
-  forgiveness fallback — don't design workflows around it).
- Exactly one default per kind, storage-enforced: flipping the flag on a
-  successor demotes the incumbent atomically, defaults are single-kind,
-  and a default cannot be archived.
- **Archive only** — there is no delete verb, so every stamped
-  workstream's provenance stays explicable.
-
-RBAC: `persona.create` / `persona.read` / `persona.write` gate the admin
-CRUD (`/v1/api/admin/personas`); all three are granted to `builtin-admin`
-by migration `063`, and other roles opt in via role permission overrides.
@@ -15,19 +15,11 @@ down to a small number of real database connections.

 ## Why PgBouncer works well with turnstone

-Most turnstone database operations are short-burst queries: acquire a
-connection, execute a small transaction, commit, release. Workstream forks are
-the deliberate exception: they clone the source's checkpoint-bounded history
-and configuration and retain its attachment references in one transaction.
-PostgreSQL runs that clone at `SERIALIZABLE` isolation and retries serialization
-or deadlock conflicts as a whole. A large fork can therefore hold its assigned
-server connection longer than an ordinary message write.
-
-This still makes **transaction pooling mode** the right fit — no operation
-depends on server-session state, and PgBouncer returns the connection as soon
-as the transaction finishes. Size and monitor the server pool with concurrent
-fork traffic in mind rather than assuming every transaction completes in a few
-milliseconds.
+All turnstone database operations are short-burst queries: acquire a
+connection, execute 1–3 statements, commit, release. No operation holds
+a connection for more than a few milliseconds. This makes **transaction
+pooling mode** ideal — PgBouncer assigns a real connection only for the
+duration of each transaction, then returns it to the pool.

 | Cluster size | Client connections (max) | PgBouncer server connections needed |
 |--------------|------------------------|-------------------------------------|
@@ -48,20 +40,18 @@ Add PgBouncer between turnstone services and PostgreSQL:
 ```yaml
 services:
  pgbouncer:
-    image: edoburu/pgbouncer:latest
+    image: bitnami/pgbouncer:latest
    environment:
-      DB_HOST: postgres
-      DB_PORT: "5432"
-      DB_NAME: ${POSTGRES_DB:-turnstone}
-      DB_USER: ${POSTGRES_USER:-turnstone}
-      DB_PASSWORD: ${POSTGRES_PASSWORD:?}
-      LISTEN_PORT: "6432"
-      AUTH_TYPE: ${POSTGRES_AUTH_TYPE:-scram-sha-256}
-      POOL_MODE: transaction
-      DEFAULT_POOL_SIZE: "40"
-      MAX_CLIENT_CONN: "5000"
-      MAX_DB_CONNECTIONS: "80"
-      SERVER_IDLE_TIMEOUT: "300"
+      POSTGRESQL_HOST: postgres
+      POSTGRESQL_PORT: "5432"
+      POSTGRESQL_DATABASE: turnstone
+      POSTGRESQL_USERNAME: ${POSTGRES_USER:-turnstone}
+      POSTGRESQL_PASSWORD: ${POSTGRES_PASSWORD:?}
+      PGBOUNCER_POOL_MODE: transaction
+      PGBOUNCER_DEFAULT_POOL_SIZE: "40"
+      PGBOUNCER_MAX_CLIENT_CONN: "5000"
+      PGBOUNCER_MAX_DB_CONNECTIONS: "80"
+      PGBOUNCER_SERVER_IDLE_TIMEOUT: "300"
    ports:
      - "6432:6432"
    networks:
@@ -77,7 +67,7 @@ services:
 ```

 Then point turnstone services at PgBouncer instead of PostgreSQL
-directly by changing `TURNSTONE_DB_URL`:
+directly by changing the `DATABASE_URL` (or `TURNSTONE_DB_URL`):

 ```bash
 # Before (direct)
@@ -92,7 +82,7 @@ TURNSTONE_DB_URL=postgresql://turnstone:secret@pgbouncer:6432/turnstone
 ## Helm / Kubernetes

 Add a PgBouncer deployment or use a Helm chart like
-[edoburu/pgbouncer](https://github.com/edoburu/docker-pgbouncer/tree/master/examples/kubernetes).
+[bitnami/pgbouncer](https://github.com/bitnami/charts/tree/main/bitnami/pgbouncer).

 In `values.yaml`, point the database at PgBouncer:

@@ -151,11 +141,9 @@ PgBouncer (which then multiplexes to PostgreSQL):
 | `TURNSTONE_DB_URL` | — | Connection URL (point at PgBouncer, not PostgreSQL directly) |

 The default pool of 2 + 3 overflow = 5 connections per process is
-intentionally small to support large clusters. Most deployments should not
-need to increase it. If operators create many large forks concurrently, watch
-PgBouncer's `cl_waiting` and PostgreSQL transaction latency before changing
-the per-process pool; adding client-side connections cannot help once the
-PgBouncer server pool is saturated.
+intentionally small to support large clusters. You should not need to
+increase this — turnstone's database operations are all short-burst
+context-managed queries that hold connections for milliseconds.

 SQLAlchemy `pool_pre_ping` is enabled, so stale connections (e.g. after
 PgBouncer restarts) are automatically detected and replaced.
@@ -187,32 +175,6 @@ Key metrics to watch:
 - **`sv_active`** — active server (PostgreSQL) connections. Should stay
  below PostgreSQL `max_connections`.

-Short `cl_waiting` spikes during large workstream forks can be normal. Sustained
-waiters accompanied by long serializable transactions indicate fork/storage
-load, not an SSE or HTTP client-pool problem.
-
---
-
-## Upgrade note: deferred workstream creation
-
-The workstream lifecycle now uses durable, hidden `state='creating'`
-reservations while session construction, upload validation, and optional fork
-cloning complete. Older server processes do not understand that private state:
-against the same database they may resolve, list, open, or prune a reservation
-before its new owner publishes it.
-
-For the upgrade that introduces deferred creation, drain create traffic and
-upgrade all server processes sharing the database as one cohort. Do not resume
-creates until no older server process remains. The change needs no manual
-schema migration, but it is not safe to treat mixed lifecycle implementations
-as an ordinary rolling-upgrade state.
-
-A `creating` row should be transient and absent from normal APIs and cluster
-events. If one persists after a process crash, inspect the corresponding
-`ws.create.*` and `session_mgr.commit_create.*` logs before cleanup. Do not
-promote it to `idle` manually: its history, configuration, attachment
-references, or lifecycle publication may be incomplete.
-
 ---

 ## Troubleshooting
@@ -235,28 +197,4 @@ does not support prepared statements. Turnstone's SQLAlchemy layer does
 not use server-side prepared statements by default, so this is not an
 issue.

-**LISTEN / NOTIFY not supported in transaction mode** — PgBouncer's
-transaction pooling assigns a real server connection only for the
-duration of each transaction, then returns it to the pool. PostgreSQL
-`LISTEN` is session state — a transaction-pooled client can't hold the
-multi-statement session a long-lived `LISTEN` needs. The console's
-`NotifyDispatcher` (reactive node discovery via the `services` channel)
-therefore opens a **dedicated, direct-to-Postgres** connection that
-bypasses PgBouncer.
-
-Configure via `config.toml` `[database] listen_url` (preferred —
-co-located with the main `url`) or the `TURNSTONE_DB_LISTEN_URL` env var
-(config.toml wins when both are set). Defaults to the main DB URL when
-unset.
-
-| Setting | Behaviour |
-|---|---|
-| unset | Listener uses `TURNSTONE_DB_URL` as-is. Fine when PgBouncer is in **session** mode, or when there's no pooler in front of Postgres. With transaction-mode PgBouncer the listener's `LISTEN` will fail and the dispatcher retries with exponential backoff (1 s → 30 s cap) without ever succeeding. Reactive NOTIFY-driven node discovery is silently lost; the cluster collector's 60 s `_discovery_loop` is the only remaining backstop. |
-| set to direct-to-PG URL (e.g. `postgresql://…/turnstone`) | Listener bypasses PgBouncer for its one dedicated connection. Reactive discovery latency drops from up-to-60 s to ~500 ms. The rest of the storage layer continues to go through PgBouncer in transaction mode. |
-
-Set this whenever PgBouncer is in transaction mode (the recommended
-setting per this doc). The override only adds one long-lived PG
-connection per console process — sized into the cluster's
-`max_connections` budget alongside the pool.
-
 See also: [Docker deployment](docker.md) · [Security](security.md)
@@ -1,25 +1,17 @@
 # Release Process

-Turnstone ships several parallel release tracks from a single PyPI package.
+Turnstone uses two parallel release tracks published from a single PyPI package.

 ## Release Tracks

 | Track | Versions | Branch | Docker tags | PyPI install |
 |-------|----------|--------|-------------|--------------|
-| **Stable 1.5** | `1.5.x` | `stable/1.5` | `:1.5.x`, `:1.5` | `pip install 'turnstone==1.5.*'` |
-| **Stable 1.6** | `1.6.x` | `stable/1.6` | `:1.6.x`, `:1.6`, `:stable`, `:latest` | `pip install turnstone` |
-| **Experimental** | `1.7.0aN` | `main` | `:1.7.0aN`, `:experimental` | `pip install turnstone --pre` |
+| **Stable** | `1.0.0`, `1.0.1` | `stable/1.0` | `:1.0.1`, `:1.0`, `:stable`, `:latest` | `pip install turnstone` |
+| **Experimental** | `1.1.0a1`, `1.1.0a2` | `main` | `:1.1.0a1`, `:experimental` | `pip install turnstone --pre` |

- **Stable** tracks receive bugfixes only.  The most-recent stable minor
-  owns the `:stable` / `:latest` Docker tags and the default PyPI
-  install.
- **Experimental** (always on `main`) receives new features. May be
-  rough around the edges.
- When experimental matures, it is promoted to a new stable minor via
-  a `stable/X.Y` branch. One prior stable track is maintained alongside
-  the current one; at each promotion the oldest track is retired — its
-  branch is deleted, while its tags and released artifacts remain
-  available.
+- **Stable** receives bugfixes only. Production-grade.
+- **Experimental** receives new features. May be rough around the edges.
+- When experimental matures, it is promoted to stable. The previous stable branch stops receiving patches.

 ## Version Scheme

@@ -34,17 +26,17 @@ Turnstone ships several parallel release tracks from a single PyPI package.
 ## Releasing an Experimental Version (from main)

 ```bash
-scripts/release.sh 1.7.0a2 --push
+scripts/release.sh 1.1.0a2 --push
 ```

-This bumps `pyproject.toml` + `turnstone/__init__.py`, regenerates `uv.lock`, commits, tags `v1.7.0a2`, and pushes. CI runs, then publish + Docker workflows fire automatically.
+This bumps `pyproject.toml` + `turnstone/__init__.py`, regenerates `uv.lock`, commits, tags `v1.1.0a2`, and pushes. CI runs, then publish + Docker workflows fire automatically.

 ## Releasing a Stable Patch (from stable/X.Y)

 ```bash
-git checkout stable/1.6
+git checkout stable/1.0
 git cherry-pick <commit-hash>    # bugfix from main
-scripts/release.sh 1.6.1 --push
+scripts/release.sh 1.0.2 --push
 ```

 ## Promoting Experimental to Stable
@@ -53,19 +45,17 @@ When `main` is ready for a stable release:

 ```bash
 # 1. Tag the stable release on main
-scripts/release.sh 1.6.0 --push
+scripts/release.sh 1.1.0 --push

 # 2. Create the stable maintenance branch from that tag
-git branch stable/1.6 v1.6.0
-git push origin stable/1.6
+git branch stable/1.1 v1.1.0
+git push origin stable/1.1

 # 3. Start the next experimental cycle on main
-scripts/release.sh 1.7.0a1 --push
+scripts/release.sh 1.2.0a1 --push
 ```

-The previous stable branch continues to receive security-only patches;
-the track before it is retired at each promotion (at 1.6.0:
-`stable/1.5` stays maintained, `stable/1.4` is retired).
+The previous `stable/1.0` branch stops receiving patches at this point.

 ## CI/CD Pipeline

@@ -50,7 +50,6 @@ with TurnstoneServer("http://localhost:8080") as client:
 import asyncio
 from turnstone.sdk import AsyncTurnstoneServer

-
 async def main():
    async with AsyncTurnstoneServer("http://localhost:8080") as client:
        await client.login(username="alice", password="s3cret")
@@ -59,7 +58,6 @@ async def main():
            if event.type == "content":
                print(event.text, end="", flush=True)

-
 asyncio.run(main())
 ```

@@ -71,18 +69,14 @@ Both `TurnstoneServer` (sync) and `AsyncTurnstoneServer` (async) expose:
 |----------|--------|---------|
 | **Workstreams** | `list_workstreams()` | `ListWorkstreamsResponse` |
 | | `dashboard()` | `DashboardResponse` |
-| | `create_workstream(*, name, model, auto_approve, resume_ws, skill, persona, initial_message, project_id, attachments, ...)` | `CreateWorkstreamResponse` |
+| | `create_workstream(*, name, model, auto_approve, skill)` | `CreateWorkstreamResponse` |
 | | `close_workstream(ws_id)` | `StatusResponse` |
-| **Attachments** | `upload_attachment(ws_id, filename, data, *, mime_type=...)` | `UploadAttachmentResponse` |
-| | `list_attachments(ws_id)` | `ListAttachmentsResponse` |
-| | `get_attachment_content(ws_id, attachment_id)` | `bytes` |
-| | `delete_attachment(ws_id, attachment_id)` | `StatusResponse` |
-| **Chat** | `send(message, ws_id, *, attachment_ids=None, client_send_id=None)` | `SendResponse` |
-| | `approve(*, ws_id, approved, feedback, always, cycle_id, call_id)` | `ApproveResponse` |
+| **Chat** | `send(message, ws_id)` | `SendResponse` |
+| | `approve(*, ws_id, approved, feedback, always)` | `StatusResponse` |
+| | `plan_feedback(*, ws_id, feedback)` | `StatusResponse` |
 | | `command(*, ws_id, command)` | `StatusResponse` |
-| | `cancel(ws_id, *, force=False)` | `CancelResponse` |
-| **History** | `get_history(ws_id, *, limit=100)` | `WorkstreamHistoryResponse` |
-| **Streaming** | `stream_events(ws_id, *, last_event_id=None, history_token=None)` | `Iterator[ServerEvent]` |
+| | `cancel(ws_id, *, force=False)` | `StatusResponse` |
+| **Streaming** | `stream_events(ws_id)` | `Iterator[ServerEvent]` |
 | | `stream_global_events()` | `Iterator[ServerEvent]` |
 | **High-level** | `send_and_wait(message, ws_id, *, timeout, on_event)` | `TurnResult` |
 | **Saved** | `list_saved_workstreams()` | `ListSavedWorkstreamsResponse` |
@@ -103,7 +97,7 @@ Both `TurnstoneConsole` (sync) and `AsyncTurnstoneConsole` (async) expose:
 | | `workstreams(*, state, node, search, sort, page, per_page)` | `ClusterWorkstreamsResponse` |
 | | `node_detail(node_id)` | `NodeDetailResponse` |
 | | `snapshot()` | `ClusterSnapshotResponse` |
-| | `create_workstream(*, node_id, name, model, initial_message, skill, persona, resume_ws)` | `ConsoleCreateWsResponse` |
+| | `create_workstream(*, node_id, name, model, initial_message, skill)` | `ConsoleCreateWsResponse` |
 | **Schedules** | `list_schedules()` | `ListSchedulesResponse` |
 | | `create_schedule(*, name, schedule_type, initial_message, ...)` | `ScheduleInfo` |
 | | `get_schedule(task_id)` | `ScheduleInfo` |
@@ -128,105 +122,25 @@ SSE events are deserialized into typed dataclasses. Use `event.type` to discrimi
 | Type | Class | Key Fields |
 |------|-------|------------|
 | `connected` | `ConnectedEvent` | `model`, `model_alias`, `skip_permissions` |
-| `user_turn` | `UserTurnEvent` | `ws_id`, `content`, `attachments`, `sender`, `source`, `client_send_ids`, `_event_id` |
+| `history` | `HistoryEvent` | `messages` |
 | `content` | `ContentEvent` | `text` |
 | `reasoning` | `ReasoningEvent` | `text` |
 | `tool_info` | `ToolInfoEvent` | `items` |
-| `approve_request` | `ApproveRequestEvent` | `cycle_id`, `items` |
-| `tool_result` | `ToolResultEvent` | `call_id`, `name`, `output`, `is_error`, `preview`, `accepted`, `effect_status`, `_event_id` |
+| `approve_request` | `ApproveRequestEvent` | `items` |
+| `tool_result` | `ToolResultEvent` | `call_id`, `name`, `output`, `is_error` |
 | `tool_output_chunk` | `ToolOutputChunkEvent` | `call_id`, `chunk` |
 | `status` | `StatusEvent` | `prompt_tokens`, `total_tokens`, `pct`, `effort`, `cache_creation_tokens`, `cache_read_tokens` |
+| `plan_review` | `PlanReviewEvent` | `content` |
 | `error` | `ErrorEvent` | `message` |
 | `info` | `InfoEvent` | `message` |
 | `stream_end` | `StreamEndEvent` | — |
-| `state_change` | `StateChangeEvent` | `state` ∈ `running`/`thinking`/`attention`/`idle`/`error` |
-| `in_progress_snapshot` | `InProgressSnapshotEvent` | `content`, `reasoning` (one-shot mid-stream refresh resume) |
-| `approval_resolved` | `ApprovalResolvedEvent` | `cycle_id`, `call_ids`, `approved`, `feedback`, `always` |
 | `cancelled` | `CancelledEvent` | — |
-| `history_resync` | `HistoryResyncEvent` | `reason`, optional `ws_id` |
-
-The Python server `send()` and console `coordinator_send()` methods accept an
-optional `client_send_id`; TypeScript `send()` accepts the equivalent
-`options.clientSendId`. Values match `[A-Za-z0-9_-]{1,128}`. The value is an
-opaque optimistic-UI correlation token, not an idempotency key: reusing it
-still creates distinct accepted turns and events.
-Every upgraded listener on the shared workstream receives `UserTurnEvent`.
-Originating panes use `client_send_ids` only to settle the exact optimistic
-bubble, while peers render the accepted row once by `_event_id`. A
-`message_queued` event carrying the token can establish acceptance even if the
-POST acknowledgement is lost. History projects the same correlation alongside
-the accepted user row. These tokens are not credentials: when sender and viewer
-identities are both known, only a matching sender may settle local optimistic
-state; a peer event still renders its canonical row.
-
-The typed projection is negotiated with `?user_turn=1` on the per-workstream
-SSE URL. Python `stream_events()` / `send_and_wait()` and TypeScript
-`streamEvents()` / `sendAndWait()` set it automatically. Raw consumers that
-omit it receive a backward-compatible `replay_truncated` repair signal instead
-of the user row and must rebuild from `/history`; its pre-row cursor keeps the
-repair retryable if that history request fails.
-
-The browser-only final-tool upsert capability is `?tool_turn=1`. The bundled
-Python and TypeScript SDK streaming helpers and channel adapters intentionally
-do not negotiate it yet: they retain the executor-receipt `tool_result`
-contract and do not own a transcript reducer. `ToolResultEvent` can deserialize
-the accepted fields for direct/custom capable clients. Raw capable clients must
-deduplicate `_event_id` and replace the newest matching call occurrence; raw
-incapable clients receive the pre-row `tool_turn_projection_unsupported` repair
-frame and rebuild from history. That staging deliberately prices in two costs
-for incapable consumers. A raw client that treats every `replay_truncated`
-frame as a rebuild trigger refetches `/history` once per accepted tool row —
-one fetch per tool call on a long agentic turn; a client that wants tool
-results incrementally should negotiate `tool_turn=1` and reduce, and the
-bundled helpers (which ignore the frame rather than rebuild) stay correct
-because their receipt-only view never depends on the accepted projection.
-Second, only the accepted event carries post-execution output transforms, so a
-receipt-rendering consumer (for example, a channel adapter posting the
-executor receipt into a thread) keeps the pre-transform text; the accepted
-projection is a transcript-consistency mechanism, not a wire confidentiality
-boundary — see the API reference note on the preliminary `tool_result`.
-
-Current servers bootstrap conversation history through
-`GET /v1/api/workstreams/{ws_id}/history` before the SSE stream; they do not
-emit a `history` event. `HistoryEvent` remains deserializable only for
-compatibility with older servers. `get_history()` exposes the current REST
-bootstrap response, including its optional cursor and one-shot handoff token.
-
-### Caller-managed history handoff
-
-The SDK supplies typed handshake primitives but intentionally does not own a
-transcript renderer or reconnect policy. After rendering a successful history
-response, pass its cursor and token to exactly one initial stream:
-
-```python
-from turnstone.sdk import HistoryResyncEvent
-
-history = client.get_history(ws_id)
-render(history.messages)
-
-for event in client.stream_events(
-    ws_id,
-    last_event_id=history.cursor,
-    history_token=history.handoff_token,
-):
-    if isinstance(event, HistoryResyncEvent):
-        # Stop this stream. The caller chooses when to fetch, render, and
-        # reconnect with a new history response.
-        break
-    apply_live_event(event)
-```
-
-`history_resync` means numeric replay cannot prove that the rendered limited
-tail came from the same total accepted conversation-row prefix. Stop the
-stream, fetch and render history again, and use only the new cursor/token pair.
-A 503 history response raises `TurnstoneAPIError`; it is not authoritative, so
-retain any existing transcript and do not open a tokenless replacement stream.

 **Global events** (from `stream_global_events()`):

 | Type | Class | Key Fields |
 |------|-------|------------|
-| `ws_state` | `WsStateEvent` | `ws_id`, `state`, `tokens`, `activity`, `persistence_state` |
+| `ws_state` | `WsStateEvent` | `ws_id`, `state`, `tokens`, `activity` |
 | `ws_activity` | `WsActivityEvent` | `ws_id`, `activity`, `activity_state` |
 | `ws_rename` | `WsRenameEvent` | `ws_id`, `name` |
 | `ws_closed` | `WsClosedEvent` | `ws_id` |
@@ -237,78 +151,26 @@ retain any existing transcript and do not open a tokenless replacement stream.
 |------|-------|------------|
 | `node_joined` | `NodeJoinedEvent` | `node_id` |
 | `node_lost` | `NodeLostEvent` | `node_id` |
-| `cluster_state` | `ClusterStateEvent` | `ws_id`, `node_id`, `state`, `tokens`, `persistence_state` |
-| `ws_created` | `ClusterWsCreatedEvent` | `ws_id`, `node_id`, `name`, `persistence_state` |
+| `cluster_state` | `ClusterStateEvent` | `ws_id`, `node_id`, `state`, `tokens` |
+| `ws_created` | `ClusterWsCreatedEvent` | `ws_id`, `node_id`, `name` |
 | `ws_closed` | `ClusterWsClosedEvent` | `ws_id` |
 | `ws_rename` | `ClusterWsRenameEvent` | `ws_id`, `name` |
 | `snapshot` | `ClusterSnapshotEvent` | `nodes`, `overview`, `timestamp` |

-Operator-facing workstream rows and rich state events expose only the sanitized
-`persistence_state`: `healthy`, `pending`, `retrying`, or `conflict`. SDK types
-treat it as optional for compatibility with older nodes; an omitted value means
-`healthy`. Retry counts, storage errors, commit keys, and conversation content
-are never part of this status surface.
-
 ### TurnResult

 The `send_and_wait()` method returns a `TurnResult` that aggregates the full response:

 ```python
 result = client.send_and_wait("Hello", ws_id, timeout=60)
-result.content  # Full text response
-result.reasoning  # Chain-of-thought (if shown)
-result.tool_results  # List of (tool_name, output) tuples
-result.errors  # Any error messages
-result.ok  # True if no errors and not timed out
-result.timed_out  # True if timeout expired
+result.content      # Full text response
+result.reasoning    # Chain-of-thought (if shown)
+result.tool_results # List of (tool_name, output) tuples
+result.errors       # Any error messages
+result.ok           # True if no errors and not timed out
+result.timed_out    # True if timeout expired
 ```

-### Attachments
-
-Upload files to a workstream and attach them to the next user turn:
-
-```python
-# Upload separately, then send a message — attachments auto-attach
-with open("screenshot.png", "rb") as f:
-    att = client.upload_attachment(ws.ws_id, "screenshot.png", f.read(), mime_type="image/png")
-client.send("What's wrong in this screenshot?", ws.ws_id)
-
-# Or attach at workstream-creation time (multipart upload)
-from turnstone.sdk import AttachmentUpload
-
-with open("notes.txt", "rb") as f:
-    ws = client.create_workstream(
-        name="triage",
-        initial_message="Summarize the notes",
-        attachments=[AttachmentUpload(data=f.read(), filename="notes.txt", mime_type="text/plain")],
-    )
-```
-
-Limits: images ≤ 4 MiB (png/jpeg/gif/webp), text ≤ 512 KiB (UTF-8),
-10 pending per (workstream, user). The SDK auto-generates `ws_id` on the
-client so cluster-routed callers bind attachments to the owning node
-before the request lands.
-
-### Forking a workstream
-
-`resume_ws` is the API's compatibility name for an atomic fork. It creates a
-new workstream ID while the source remains unchanged:
-
-```python
-fork = client.create_workstream(
-    resume_ws=ws.ws_id,
-    name="analysis-branch",
-    initial_message="Try the alternative plan.",
-)
-assert fork.resumed
-```
-
-The server transaction clones the source's checkpoint-bounded history, saved
-session configuration, persona, project, and attachment references. Do not
-combine `resume_ws` with `attachments`; fork first, then upload to the new ID.
-To rehydrate the original ID rather than branch it, call the server's
-`POST /v1/api/workstreams/{ws_id}/open` endpoint.
-
 ### Error Handling

 Non-2xx responses raise `TurnstoneAPIError`:
@@ -320,7 +182,7 @@ try:
    client.send("hi", "bad_ws_id")
 except TurnstoneAPIError as e:
    print(e.status_code)  # 404
-    print(e.message)  # "Unknown workstream"
+    print(e.message)      # "Unknown workstream"
 ```

 ---
@@ -345,14 +207,8 @@ const ws = await client.createWorkstream({ name: "demo" });
 const result = await client.sendAndWait("Hello!", ws.ws_id);
 console.log(result.content);

-// Render history, then use its one-shot hints on the initial stream.
-const history = await client.getHistory(ws.ws_id);
-render(history.messages);
-for await (const event of client.streamEvents(ws.ws_id, {
-  lastEventId: history.cursor ?? undefined,
-  historyToken: history.handoff_token ?? undefined,
-})) {
-  if (event.type === "history_resync") break; // caller refetches and reconnects
+// Stream events
+for await (const event of client.streamEvents(ws.ws_id)) {
  if (event.type === "content") {
    process.stdout.write(event.text);
  }
@@ -428,7 +284,7 @@ turnstone/sdk/               Python SDK (sub-package)
  _base.py                   Shared httpx async client, auth, error handling
  _sync.py                   Background event loop for sync wrappers
  _types.py                  TurnResult + TurnstoneAPIError
-  events.py                  Typed SSE event dataclasses with type registry
+  events.py                  27 SSE event dataclasses with type registry
  server.py                  AsyncTurnstoneServer + TurnstoneServer
  console.py                 AsyncTurnstoneConsole + TurnstoneConsole

@@ -1,10 +1,8 @@
 # Security and Authentication

-Turnstone uses a layered authentication system with two token types
-(database-backed API tokens + HMAC-SHA256 JWTs), hierarchical scopes,
-and a split architecture where the console manages credentials while
-individual server nodes validate JWTs locally.  Inter-service traffic
-uses short-lived service JWTs minted by `ServiceTokenManager`.
+Turnstone uses a layered authentication system with three token types,
+hierarchical scopes, and a split architecture where the console manages
+credentials while individual server nodes validate JWTs locally.

 ---

@@ -39,7 +37,7 @@ Claims:
 |-------|-------------|
 | `sub` | User ID |
 | `scopes` | Comma-separated scope list (`read,write,approve`) |
-| `src` | Token source (`password`, `database`, `oidc`, or a service origin like `console`, `cli`, or `channel`) |
+| `src` | Token source (`password`, `api_token`, `config`, `oidc`) |
 | `iss` | Issuer — always `turnstone` |
 | `aud` | Audience — `turnstone-server` or `turnstone-console` |
 | `iat` | Issued-at timestamp |
@@ -64,17 +62,14 @@ Scopes are hierarchical — higher scopes imply all lower ones.

 ### Path-to-scope mapping

-| Method | Path pattern | Required scope | Additional RBAC gate |
-|--------|-------------|----------------|----------------------|
-| GET | Any protected path | `read` | Endpoint-specific where documented |
-| POST | `/api/command` | `write` | Project tenancy on the target workstream |
-| POST | `/api/workstreams/new`, `/api/cluster/workstreams/new` | `write` | `workstreams.create` or `admin.coordinator` |
-| POST | `/api/workstreams/{ws_id}/close` | `write` | `workstreams.close` or `admin.coordinator` |
-| POST | `/api/workstreams/{ws_id}/approve` | `approve` | `tools.approve` or `admin.coordinator` |
-| POST | `/api/workstreams/{ws_id}/{rewind,retry}` | `write` | `conversation.modify` |
-| POST | Other `/api/workstreams/{ws_id}/...` mutation endpoints | `write` | Project tenancy and endpoint-specific gates |
-| DELETE | `/api/workstreams/{ws_id}/send` (dequeue), `/api/workstreams/{ws_id}/attachments/{attachment_id}` | `write` | Project tenancy on the target workstream |
-| Any | `/api/admin/*` | `approve` | Matching `admin.*` permission |
+| Method | Path pattern | Required scope |
+|--------|-------------|----------------|
+| GET | Any protected path | `read` |
+| POST | `/api/send`, `/api/plan`, `/api/command` | `write` |
+| POST | `/api/workstreams/new`, `/api/workstreams/close` | `write` |
+| POST | `/api/cluster/workstreams/new` | `write` |
+| POST | `/api/approve` | `approve` |
+| Any | `/api/admin/*` | `approve` |

 Public paths bypass authentication entirely: `/`, `/health`, `/metrics`,
 `/static/*`, `/shared/*`, `/docs`, `/openapi.json`, `/api/auth/login`,
@@ -86,7 +81,7 @@ Public paths bypass authentication entirely: `/`, `/health`, `/metrics`,
 > See also: [Governance documentation](governance.md)

 Scopes provide coarse endpoint-level access control. For finer-grained
-enforcement, the governance layer adds named permissions checked
+enforcement, the governance layer adds 15 named permissions checked
 per-endpoint by `require_permission()`. Permissions are bundled into
 roles; users are assigned roles via the `user_roles` join table.

@@ -100,8 +95,8 @@ Three built-in roles are seeded by migration 008:

 | Role | Permissions |
 |------|-------------|
-| admin | Admin-default baseline (all ordinary admin and lifecycle permissions; explicitly opt-in capabilities remain ungranted) |
-| operator | read, write, workstreams.create, workstreams.close, conversation.modify |
+| admin | All 15 permissions |
+| operator | read, write, workstreams.create, workstreams.close |
 | viewer | read |

 Custom roles can be created with any subset of the valid permissions.
@@ -109,34 +104,6 @@ Role creation and update validate permissions against a static allowlist.
 Self-assignment is blocked, and assigning a role requires the caller to
 hold a superset of the target role's permissions.

-### Workstream lifecycle and project boundaries
-
-The remote `/api/command` endpoint is conversation-local. It refuses
-`/new`, `/workstreams`, `/resume`, and `/delete` because those local-CLI
-helpers enumerate or mutate storage outside the HTTP resource gates. Remote
-clients use the dedicated create, open, close, and delete endpoints instead;
-`/rewind` and `/retry` have their own path-keyed, `conversation.modify`-gated
-endpoints.
-
-Passing `resume_ws` to create is an atomic **fork**, not an in-place resume.
-It requires the ordinary create capability and source visibility. A private
-project source is visible only to its workstream creator, project owner/member,
-or authorized service-to-service cluster plumbing; denials use a not-found
-response so guessed IDs do not become an existence oracle. The caller must also
-be allowed to attach a new workstream to the source's current project. The
-destination always inherits that effective project — a caller-supplied
-`project_id` cannot re-file or declassify the conversation.
-
-The canonical preflight atomically captures (and, for a legacy row, installs) a
-private source-incarnation fence. The storage transaction compares that source
-fence, rejects provisional sources, repeats the ACL/project check, and verifies
-the persona/project construction snapshot, destination ownership and
-incarnation, emptiness, and every referenced attachment before committing. A
-source replacement, membership, project, persona, or destination-incarnation
-race aborts the whole fork. Concurrent source-history writes serialize wholly
-before or after the snapshot; no mixed or partially authorized history or
-attachment reference becomes visible.
-
 ---

 ## Login Flows
@@ -471,15 +438,12 @@ Each proxied request gets a fresh JWT (5-minute expiry).  This ensures:
 - **Permission forwarding** — granular RBAC permissions from the
  console JWT are carried through to the server.

-For ordinary users the JWT `src` claim is set to `"console-proxy"`, allowing
-servers to distinguish proxied requests from direct logins in audit logs.
-Coordinator tokens retain `src="coordinator"` and their signed `coord_ws_id`;
-the console service identity retains `src="console"` only when its validated
-token also carries the unassignable `service` scope.
+The JWT `src` claim is set to `"console-proxy"`, allowing servers to
+distinguish proxied requests from direct logins in audit logs.

 When no user context is available (auth disabled, or internal requests),
-the proxy falls back to a `ServiceTokenManager` with identity `console-proxy`,
-`src="console"`, and `{read, write, approve, service}` scopes.
+the proxy falls back to a `ServiceTokenManager` with service identity
+`console-proxy` and full scopes.

 ### Service-to-service authentication

@@ -488,8 +452,8 @@ JWTs when communicating with server nodes:

 | Service | Identity | Scope | Audience | Purpose |
 |---------|----------|-------|----------|---------|
-| Console collector | `console-collector` | `read`, `service` | `turnstone-server` | Node health polling and global event collection |
-| Console proxy (fallback) | `console-proxy` | `read`, `write`, `approve`, `service` | `turnstone-server` | Proxied API calls when no user context |
+| Console collector | `console-collector` | `read` | `turnstone-server` | Node health polling |
+| Console proxy (fallback) | `console-proxy` | `approve` | `turnstone-server` | Proxied API calls when no user context |
 | Channel notify | `system` | `write` | `turnstone-channel` | Notification delivery to channel gateway |

 Service tokens use 1-hour expiry with automatic refresh via
@@ -501,8 +465,8 @@ When the console creates a workstream (the normal path), the
 authenticated user's `user_id` is forwarded in the HTTP payload when
 calling the server's `POST /v1/api/workstreams/new`.  The server
 accepts a `user_id` from the request body **only when the caller is a
-trusted service** — identified by `token_source="console"` together with the
-unassignable `service` scope. `console-proxy`, coordinator, and regular API callers cannot
+trusted service** — identified by `token_source` matching
+`console-proxy` or `console`.  Regular API callers cannot
 override `user_id`; the server always uses their JWT identity.

 Note that the channel gateway uses a distinct JWT audience
@@ -36,202 +36,6 @@ users to the admin Settings API.

 ---

-## Per-Model Sampling Overrides
-
-The global `model.temperature`, `model.max_tokens`, and `model.reasoning_effort`
-settings serve as cluster-wide defaults. Individual models can override these
-via per-model settings in the `model_definitions` table (admin Models tab).
-
-Resolution order for sampling parameters:
-
-| Priority | Source |
-|----------|--------|
-| 1 (highest) | Per-model override (set in Models tab) |
-| 2 | Global default (set in Settings tab) |
-| 3 | Registry default (code) |
-
-When a per-model override is `NULL` (empty in the UI), the global default is
-used. Switching models via `/model <alias>` re-resolves sampling parameters
-from the new model's overrides or global defaults.
-
-### Per-model concurrency
-
-Each model definition may set `max_concurrency` to limit simultaneous model
-generations for that alias in one Turnstone process. `0` or an omitted value
-means unlimited. The gate is shared by every role using the alias—interactive
-turns, coordinators, task agents, judges, output guards, perception, compaction,
-and title generation—and a streaming generation holds its slot until the
-stream is fully drained or closed.
-
-Admission is strictly per alias. Two aliases remain independent even when they
-point to the same URL; Turnstone does not infer shared capacity from endpoint
-text. Queue time is excluded from judge/output-guard deadline accounting, and
-each retry releases its slot before backoff and reacquires for the next wire
-attempt. The cap is local to each process, not cluster-wide; account for the
-number of nodes targeting the same inference server. Direct STT/TTS protocol
-calls and Cohere/Jina reranking do not currently consume this generation cap.
-
-### Judge batch parallelism
-
-`judge.parallel_evaluations` controls how many independent tool calls from one
-approval batch the intent judge evaluates concurrently. It is an integer from
-1 through 16 and defaults to 1, preserving serial evaluation until an operator
-opts into wider fan-out. Changes are hot-read at the next batch; work already
-in flight keeps its captured worker count.
-
-This is a per-batch fan-out setting, not another backend capacity limit. The
-judge model alias's `max_concurrency` gate still caps total generations across
-all judge batches and every other role using that alias. Actual overlap is
-therefore bounded by the batch size, `judge.parallel_evaluations`, and available
-alias admission slots. A smaller positive alias cap also narrows the batch's
-worker pool so excess judge threads do not queue ahead of later alias traffic.
-
-### Model backend authentication
-
-Model definitions support four backend credential modes:
-
-| `auth_mode` | Identity sent to the model gateway |
-|-------------|------------------------------------|
-| `static` | The definition's stored `api_key`. |
-| `entra_obo` | A caller-delegated Entra access token minted from that user's captured OIDC credential. |
-| `entra_app` | A shared app-identity token minted with Turnstone's OIDC client credentials. |
-| `rfc8693_obo` | A caller-delegated access token minted from the captured credential via RFC 8693 token exchange, requesting the definition's `obo_scopes`. |
-
-Dynamic modes require an exact `obo_audience` resource identifier. Before an
-admin can save one, an operator must add that literal audience to
-`model.auth_audience_allowlist` (comma- or newline-separated). Wildcards and
-base-URL host matching are intentionally unsupported, and a row whose
-effective mode is `static` refuses to store a new non-empty `obo_audience` on
-either create or update — an audience cannot be staged for a later flip
-(clearing a stale value, or re-saving it unchanged, stays allowed).
-`obo_scopes` follows the same staging rule with the mode set inverted: only
-`rfc8693_obo` reads it, so every other effective mode refuses to store a new
-non-empty value, while clearing or re-saving one unchanged stays open. The
-value itself is optional and shape-checked only — whether it satisfies the
-IdP is decided at mint time. On a row that is (or becomes) dynamic, every
-change except the tuning fields — context window, temperature, max tokens,
-reasoning effort, and the two reasoning-persistence toggles — also requires
-`admin.mcp`; service tokens do not bypass this capability-escalation gate.
-The one exception is de-escalation: a save whose only gated change is
-switching `enabled` off is a pure disable, needs only `admin.models`, and
-skips validation — a de-listed audience must never block disarming its own
-row. The gate is deny-by-default: a field counts as auth-relevant unless it
-is provably neutral, so re-enabling a disabled dynamic row, re-pointing its
-`base_url`, or swapping its provider or alias all escalate.
-
-Validation runs in two tiers, matching the MCP `oauth_obo` write rules. Row
-validity — the audience is allow-listed — applies to every gated write that
-touches a dynamic configuration, so a revoked audience can be neither silently
-re-pointed at a new `base_url` nor re-armed by an enable flip. Deployment
-posture — the token encryption key installed, single sign-on configured, and
-the grant profile valid and able to carry the mode — is checked when a write
-*chooses* the mode/audience pair and when it re-enables a disabled dynamic
-row (arming is the flip that resumes minting, so it must meet what minting
-needs); other edits to an existing row stay open if the deployment's posture
-changed after it was saved (its mints warn at runtime instead). Refusals name
-their cause and echo the configured value.
-
-One asymmetry to be aware of: the write path counts a transient discovery
-outage (`enabled=false`, retryable) as configured, but the mints themselves
-require discovery to have completed — a config saved during an outage starts
-minting only once any authenticated request heals discovery. Until then calls
-warn and follow the fail-open/fail-closed policy above.
-
-Every dynamic mode pairs with exactly one grant profile: `entra_obo` and
-`entra_app` require `[oidc] obo_grant_profile = "entra"`, and `rfc8693_obo`
-requires `"rfc8693"`. The pairing is enforced at the posture tier, so a row
-saved before the rule existed keeps accepting same-pair edits; its mints
-refuse at runtime with `cause=grant_profile_mismatch` and no IdP traffic.
-Judge, output-guard, perception, utility, and sub-agent lanes inherit the
-session's effective user for the delegated modes. The perception memo is
-partitioned by that principal as well as alias and content hash, so a result
-authorized as one user cannot be served to another. Scheduled and wake-driven
-work retains the workstream owner even when no user is connected. Eval and
-optimizer lanes are registry-less development tools and therefore do not use
-dynamic model authentication.
-
-`entra_app` is an explicit model-definition choice; Turnstone never changes a
-failed or ownerless delegated call into a client-credentials grant. A
-delegated-mode call with no effective user always refuses. A dynamic alias
-without a real static key also always refuses instead of issuing its
-SDK-construction placeholder. When a real static key is explicitly configured,
-mint failures may use it by default; set `model.auth_fail_closed = true` to
-prohibit even that fallback. A refusal is not routed through the model
-fallback chain.
-
-Dynamic token caches are encrypted in `mcp_user_tokens`, shared across nodes,
-and memoized on each host. Unlinking a user's OIDC identity purges their
-delegated-mode rows and memo entries. `entra_app` rows belong to the shared
-`__app__` identity and are not user-deprovisioned; after client-credential
-revocation, an already-minted app bearer remains usable until its recorded
-expiry.
-
-Each model call resolves its dynamic credential against the immutable model
-definition snapshot that supplied that call's provider, client, endpoint, and
-model ID. An admin edit can therefore never pair an old `base_url` with a new
-audience, grant mode, or static-key fallback input. The principal and token
-remain per-call/live; the connection and model-owned auth configuration move
-together as one binding on the next operation. The deployment-wide
-`model.auth_fail_closed` switch is intentionally read live on every mint, so an
-operator can tighten fallback policy immediately without rebuilding sessions.
-
-`obo_audience` and `obo_scopes` are literal and capped at 2048 characters
-each. Environment-variable expansion is deliberately not applied, so the
-allow-list decision cannot vary by node or expand beyond the persisted
-boundary.
-
-### Responses output controls (per-model)
-
-Models whose capability table declares Responses output controls expose two
-additional fields in the Models create/edit shelf:
-
-| Field | Stored capability | Values | Effect |
-|-------|-------------------|--------|--------|
-| Output verbosity | `verbosity` | `low`, `medium`, `high` | Controls answer length independently of reasoning effort. |
-| Reasoning mode | `reasoning_mode` | `standard`, `pro` | Selects standard or higher-compute Pro execution without changing the model ID. |
-
-An empty selection means provider default and omits the capability key. Known
-GPT-5.6 models inherit support from the built-in table without persisting
-redundant support flags. An OpenAI-compatible model pinned to the Responses API
-can opt in with the `supports_verbosity` and `supports_pro_mode` capability
-tiles. Chat Completions and non-Responses providers do not surface or submit
-these controls.
-
-**Removed settings:** `model.name` and `model.context_window` have been removed
-from ConfigStore. Model names and context windows are now configured per-model
-in the Models tab. A startup warning is logged if these keys appear in
-`config.toml`.
-
-### Reasoning persistence (per-model)
-
-Two boolean flags on `model_definitions` (migration 052) control how
-reasoning text round-trips per model:
-
-| Flag | Default | Effect |
-|------|---------|--------|
-| `surface_persisted_reasoning` | `True` | Surface stored reasoning text on `/history` payloads so a page reload re-renders the reasoning bubble. **Storage of reasoning bytes is independent of this flag** — they ride in `provider_data` regardless. |
-| `replay_reasoning_to_model` | `False` | Send stored reasoning blocks back to the provider on subsequent turns. Capability-gated: only takes effect when the model's `ModelCapabilities.supports_reasoning_replay` is also `True`. Set on canonical OpenAI gpt-5*/o-series and Anthropic Claude entries; unknown / local-server models default to `False` so an operator who flips the flag on a model whose API doesn't understand reasoning replay silently no-ops rather than 400-ing. |
-
-Edit both via the admin Models tab. See the architecture doc for the
-provider-side mechanics (Anthropic `thinking`, OpenAI Responses
-`reasoning` + `include=["reasoning.encrypted_content"]`, synthetic
-`reasoning_text` for Chat Completions / vLLM / llama.cpp / Gemini-compat).
-
-### Task agent overrides
-
-`task_agent` sub-sessions resolve independently from the conversation model
-so operators can pick a cheaper/faster model for autonomous loops:
-
-| Setting | Purpose |
-|---------|---------|
-| `model.task_alias` | Alias used for `task_agent` sub-sessions. Falls back to `[model].agent_model` in config.toml, then the session's active model. |
-| `model.task_effort` | Reasoning effort for `task_agent`. Empty string means "inherit from the session". |
-
-Both are live-editable from the Settings tab and take effect on the
-next sub-agent invocation — no restart required.
-
---
-
 ## Bootstrap vs ConfigStore

 **Bootstrap settings** are required before storage is available (database
@@ -245,21 +49,20 @@ connection, Redis, auth secrets, server bind address). These stay in
 | Auth | `[auth]` | config.toml / env |
 | Console bind | `[console]` | config.toml / env |

-**ConfigStore settings** are loaded from the database after storage
-initialization:
+**ConfigStore settings** (48 settings) are loaded from the database after
+storage initialization:

 | Section | Settings |
 |---------|----------|
-| `model` | default_alias, auth_audience_allowlist, auth_fail_closed, temperature, max_tokens, reasoning_effort, task_alias, task_effort |
+| `model` | name, temperature, max_tokens, reasoning_effort, context_window |
 | `session` | instructions, retention_days, compact_max_tokens, auto_compact_pct |
 | `tools` | timeout, truncation, agent_max_turns, skip_permissions, search, search_threshold, search_max_results |
 | `server` | workstream_idle_timeout, max_workstreams |
 | `cluster` | node_fan_out_limit, mcp_max_servers |
-| `mcp` | config_path, registry_url |
+| `mcp` | config_path, refresh_interval, registry_url |
 | `ratelimit` | enabled, requests_per_second, burst, trusted_proxies |
 | `health` | backend_probe_interval, backend_probe_timeout, circuit_breaker_threshold, circuit_breaker_cooldown |
-| `judge` | enabled, model, smart_approvals, confidence_threshold, max_context_ratio, timeout, parallel_evaluations, read_only_tools, output_guard, output_guard_budget_seconds, output_guard_llm, output_guard_model, output_guard_llm_timeout, redact_secrets, cancel_on_approval |
-| `interface` | close_tab_action, theme |
+| `judge` | enabled, model, provider, base_url, api_key, confidence_threshold, max_context_ratio, timeout, read_only_tools, output_guard, redact_secrets |
 | `skills` | discovery_url |
 | `memory` | relevance_k, fetch_limit, max_content, nudge_cooldown, nudges |

@@ -435,11 +238,13 @@ Reset a setting to its registry default by removing it from storage.

 ## Secret Settings

-The registry currently defines no production secret system setting. The generic
-machinery nevertheless treats any future `is_secret=True` entry as write-only:
-list and write responses return `"***"`, and submitting that sentinel preserves
-the stored value. Model API keys are fields on model definitions—not
-`judge.*` system settings—and use the Models tab's separate write-only flow.
+Settings with `is_secret=True` (currently only `judge.api_key`) are blocked
+from the write API with a `403` response. This prevents accidental exposure
+through the admin UI or audit logs. Secret settings must be configured via
+`config.toml` or environment variables.
+
+The list endpoint masks secret values: stored secrets appear as `"***"`
+rather than their actual value.

 ---

@@ -460,40 +265,10 @@ reload.
 **Behavior after reload:**

 - New workstreams pick up updated values immediately (via `session_factory`)
- Most workstream/session settings remain the snapshot captured at creation or
-  resume. Component docs call out deliberate live-read exceptions; for
-  example, Smart Approval settings are snapshotted coherently at the start of
-  each approval batch.
+- Existing sessions keep their frozen configuration (settings are captured at
+  workstream creation time, not read on every turn)
 - Settings marked `restart_required=True` need a server restart to take effect

-### Model-definition reloads
-
-The Models tab has a separate live-reload contract from ordinary ConfigStore
-settings. Existing sessions remember the concrete registry generation that
-supplied their active alias and re-resolve that alias at the start of the next
-send. Endpoint, provider, backend model ID, capabilities, extra parameters, and
-backend-auth configuration are replaced as one immutable binding. In-flight
-turns, judges, and task agents finish or cancel against the binding they
-started with; an admin edit never tears one request across two definitions.
-The alias's admission gate is retained and resized in place, so a concurrency
-edit preserves in-flight accounting and does not reset cached judges or the
-output-guard rate limiter.
-
-Sampling and other saved workstream configuration remain workstream state. A
-model-definition edit does not silently rewrite a live workstream's chosen
-temperature, reasoning effort, max tokens, skill, or persona. Use
-`/model <alias>` (or create/fork a workstream) when an explicit session-level
-model switch is intended.
-
-If a live workstream's alias is deleted, its next send first attempts the
-configured fallback chain. Without a usable fallback, the operator-facing
-error names the removed alias and points interactive users to `/model`; adding
-the alias back causes the next send to rebind without a process restart. If a
-replacement client cannot be constructed, Turnstone logs one
-`session.model_refresh_client_construction_failed` warning per registry
-generation and retries only after another model reload, avoiding a rebuild
-storm on every send.
-
 ---

 ## Migration from config.toml
@@ -1,315 +0,0 @@
---
-name: import-conversation-history
-description: Use this skill when the user wants to import or migrate conversation history from another LLM chat or coding tool (e.g. ChatGPT, Claude.ai, Cursor, Copilot Chat, Aider, Gemini, a custom JSON export) into Turnstone. The skill teaches Turnstone's destination contracts — workstream identity, the OpenAI-shaped message rows, tool-call/result pairing, provider-fidelity blobs, attachments, and archive-vs-resumable choice — so the agent can map any source format onto them. Trigger phrases: "import my chats", "migrate this transcript into Turnstone", "bring my Claude.ai history over", "load this export as a workstream".
-version: 1.1.0
---
-
-# Importing Conversation History into Turnstone
-
-## Overview
-
-Source formats vary; the destination does not. Your job is to translate whatever the user hands you (JSON dump, ZIP export, scraped HTML, screenshot OCR, raw transcript) into Turnstone's internal shape: **one workstream row** plus an ordered sequence of **conversation rows** in OpenAI message format. This skill documents the destination so you can write a correct mapper for any source.
-
-Two questions to settle with the user before writing anything:
-
-1. **Archive or resumable?** An archive is left closed and is read-only history. A resumable import is also kept closed and unloaded while rows are written, then explicitly opened after validation; this only works cleanly when the source LLM matches a Turnstone-supported provider/model and tool definitions still resolve.
-2. **One workstream per source thread, or merge?** Default to one-to-one unless the user explicitly asks to merge.
-
-Default to **archive** when in doubt — resuming a foreign transcript with mismatched tool schemas or stale provider signatures will fail at the next turn.
-
-## Turnstone Data Model (the destination)
-
-Two tables carry the conversation:
-
-### `workstreams` (one row per imported thread)
-
-| Column | Required | Notes |
-|---|---|---|
-| `ws_id` | yes | 32-char lowercase hex. Auto-generate with `secrets.token_hex(16)` if you don't already have one. The router hashes the **full ID** — see "Identity & Routing" below. |
-| `name` | yes | Short title. Pull from source thread title; fall back to first ~60 chars of first user message. |
-| `state` | yes | Register as `"closed"` while importing. Leave it closed for an archive; explicitly open it after commit for a resumable import. Never set `"running"` or `"creating"` directly. |
-| `kind` | yes | `"interactive"` for normal threads. Do NOT use `"coordinator"` for imports — that's reserved for cluster-spawned coordinator workstreams. |
-| `parent_ws_id` | no | Leave NULL. Only set if you're importing a coordinator-spawned subtree and re-parenting it; rare. |
-| `user_id` | yes | Owner. Must exist in `users`; importer must know which Turnstone user owns the imported history. |
-| `node_id` | no | Nullable creation-time service/liveness hint. It is not the routing key or durable owner and may become stale after membership changes. Let a routed create stamp it; a direct shared-storage import may leave it NULL. |
-| `alias` | no | Human-typeable short name. Optional; must be unique cluster-wide if set. |
-| `title` | no | Auto-titled later by the LLM; safe to leave NULL on import. |
-| `skill_id`, `skill_version` | yes | Default `""` and `0` unless the source thread was scoped to a Turnstone skill. |
-| `created`, `updated` | yes | ISO8601 strings. Use the source's first/last message timestamps when available. |
-
-### `conversations` (many rows per thread, ordered by `id`/`timestamp`)
-
-| Column | Notes |
-|---|---|
-| `ws_id` | The workstream this row belongs to. |
-| `timestamp` | ISO8601 string. Preserve source timestamps; fall back to monotonically increasing values if unknown. **Order is canonical via `id` (autoincrement), not `timestamp`** — but always insert in conversational order so both agree. |
-| `role` | One of `system`, `user`, `assistant`, `tool`, `developer`. See role mapping below. |
-| `content` | Text. May be NULL for assistant rows that are *only* tool calls. |
-| `tool_name` | Set on `role="tool"` rows (the tool whose result this is). NULL otherwise. |
-| `tool_call_id` | Set on `role="tool"` rows (matches the assistant row's `tool_calls[].id`). NULL otherwise. |
-| `tool_calls` | JSON-encoded list, on `role="assistant"` rows that issued tool calls. OpenAI shape — see "Tool Calls" below. |
-| `provider_data` | JSON blob preserving provider-native content blocks (Anthropic `signature`, Gemini `thought_signature`, etc.). Optional; only matters for **resumable** imports against the same provider. Skip for archives. |
-
-The internal format is **OpenAI-shaped**, even when the source was Anthropic or Gemini. Providers translate at their own API boundary; storage stays uniform.
-
-## Identity & Routing (`ws_id`)
-
- `ws_id` is **32-char lowercase hex** (i.e. `secrets.token_hex(16)`).
- Ordinary placement is rendezvous (Highest Random Weight, HRW) selection over
-  the **full `ws_id`** and the current live server set. For each node, Turnstone
-  computes 32-bit FNV-1a over the node ID, a NUL separator, and the full
-  workstream ID; it then applies the node weight and selects the highest score.
-  A live per-workstream override takes precedence.
- The live set comes from recent `services` heartbeats. Placement can therefore
-  change when nodes join, leave, change weight, or an override changes. There
-  is no stable prefix-derived placement to pre-compute or persist.
- `workstreams.node_id` is stamped at creation and is not updated as HRW
-  placement changes. It supports display and liveness-safe cleanup; the console
-  router does not use it as the ordinary ownership decision.
- For multi-node imports, create through the console routing proxy when the
-  lifecycle must be published, or write the history once through the cluster's
-  configured **shared storage backend**. Never partition rows across node-local
-  databases by ID prefix or by a one-time HRW result: a later membership change
-  can route the same full ID to another node.
- For single-node imports, HRW placement is degenerate; any valid `ws_id` works.
- **Do not reuse the source platform's IDs as `ws_id`** unless they happen to be 32-char hex. Generate fresh; if you need the old ID for traceability, store it in `workstream_config` under a key like `import.source_id`.
-
-## Recommended Import Path
-
-Three options, in order of preference:
-
-### 1. Quiesced storage import (recommended for full history)
-
-Use the current `turnstone.core.storage.StorageBackend` protocol against the
-same shared backend as the cluster. The destination must remain absent from all
-in-memory session managers while rows are changing: a loaded `ChatSession`
-holds its own trajectory and will not observe conversation rows inserted behind
-it.
-
-The safe sequence is:
-
-1. Normalize and validate the complete source transcript before writing.
-2. Call `register_workstream(..., state="closed")` and require a `True` return;
-   `False` means the caller-selected ID already exists, so abort rather than
-   appending to an unrelated workstream.
-3. Insert the ordered conversation rows and attachment references.
-4. Load the saved rows back and run the validation checklist below.
-5. Leave an archive closed. For a resumable import, only now invoke the normal
-   `POST /v1/api/workstreams/{ws_id}/open` endpoint on the currently routed
-   node so the session hydrates from the complete transcript.
-
-Do **not** create the destination through the web/SDK create endpoint before a
-direct bulk import. Create publishes an empty live session. If that already
-happened, close the workstream and confirm the manager-authoritative live probe
-returns false before writing, then explicitly open it again after validation.
-
-For attachment-free history, `save_messages_bulk(rows)` is the canonical
-single-transaction insert primitive and bypasses the LLM round-trip entirely.
-New attachment bytes require the per-row path described under
-[Attachments](#attachments).
-
-```python
-from turnstone.core.storage import get_storage  # initialized by the host/import entry point
-
-storage = get_storage()
-
-inserted = storage.register_workstream(
-    ws_id=ws_id,
-    user_id=user_id,
-    name=name,
-    state="closed",
-    kind="interactive",
-    ...
-)
-if not inserted:
-    raise RuntimeError(f"destination already exists: {ws_id}")
-
-storage.save_messages_bulk([
-    {"ws_id": ws_id, "role": "user", "content": "Hello"},
-    {"ws_id": ws_id, "role": "assistant", "content": "Hi! What can I help with?"},
-    {"ws_id": ws_id, "role": "assistant", "content": None,
-     "tool_calls": json.dumps([{"id": "call_1", "type": "function",
-                                "function": {"name": "search", "arguments": "{\"q\":\"x\"}"}}])},
-    {"ws_id": ws_id, "role": "tool", "tool_name": "search", "tool_call_id": "call_1",
-     "content": "result text"},
-    # ...
-])
-```
-
-`save_messages_bulk` handles `timestamp` and the workstream's `updated` column
-internally, so you don't need to compute them per row. Verify the exact
-`register_workstream` and message signatures in
-`turnstone/core/storage/_protocol.py`; the Storage protocol, not the physical
-table layout, is the source of truth.
-
-**Multi-node note:** this path assumes `get_storage()` is connected to the
-cluster's shared backend. Do not open a node-local database selected from the
-current HRW result, and do not pre-create a live session through the console
-routing proxy. After the shared-storage import commits, resolve the current
-route and open the closed workstream on that node. Any stored `node_id`
-describes creation-time placement, not a permanent shard that should receive a
-separate copy.
-
-### 2. SDK `create_workstream(resume_ws=...)` (when the source is already a Turnstone workstream)
-
-Only useful for *Turnstone → Turnstone* re-parenting. Not relevant for foreign sources.
-
-### 3. SDK `create_workstream(initial_message=...)` + `send()` per turn (last resort)
-
-Only fits archives where the source had **no tool calls** and you don't care about preserving assistant turns verbatim. Each `send()` triggers a real LLM round-trip, which is expensive and rewrites assistant content. Don't use this for full history.
-
-## Role Mapping
-
-Common source-role conventions and how they map to Turnstone:
-
-| Source role | Turnstone `role` | Notes |
-|---|---|---|
-| `user`, `human` | `user` | Direct map. |
-| `assistant`, `ai`, `model`, `bot` | `assistant` | Direct map. |
-| `system` | `system` | Preserve only if it's content the user wrote (custom instructions). Drop boilerplate provider preambles — Turnstone composes its own system message. |
-| `developer` (OpenAI o-series) | `developer` | Preserve. |
-| `tool`, `function`, `tool_result` | `tool` | Must carry `tool_name` and `tool_call_id` matching the prior assistant row's `tool_calls[].id`. |
-| `tool_use` (Anthropic) | `assistant` with `tool_calls` | Anthropic emits tool calls *inside* an assistant message; flatten to OpenAI shape. |
-| `human_feedback`, `revision` | `user` | Treat as a follow-up user turn. |
-
-## Tool Calls (the most error-prone part)
-
-Turnstone stores tool calls in OpenAI's nested-function shape on the assistant row, and matches them with `role="tool"` result rows by `tool_call_id`.
-
-### Assistant row with tool calls
-
-```json
-{
-  "role": "assistant",
-  "content": null,
-  "tool_calls": [
-    {
-      "id": "call_abc123",
-      "type": "function",
-      "function": {
-        "name": "search_web",
-        "arguments": "{\"query\":\"turnstone import\"}"
-      }
-    }
-  ]
-}
-```
-
-`tool_calls[].function.arguments` is **a JSON-encoded string**, not an object. Source formats commonly get this wrong — Anthropic stores arguments as a parsed object, Gemini as a struct. Always re-serialize to a string.
-
-### Tool result row
-
-```json
-{
-  "role": "tool",
-  "tool_name": "search_web",
-  "tool_call_id": "call_abc123",
-  "content": "..."
-}
-```
-
-Pairing rules:
- Every assistant `tool_calls[].id` MUST be followed by exactly one `role="tool"` row with the matching `tool_call_id`, before the next user/assistant turn.
- If the source dropped the tool result (cut-off transcript), insert a synthetic `role="tool"` row with `content="[tool result missing in source]"` to keep the chain valid. An assistant row with an unanswered `tool_calls[].id` will break replay and any LLM round-trip.
- Multi-tool assistant turns: one `role="tool"` row per call, in any order, all before the next non-tool row.
-
-### Tool ID generation
-
-If the source used opaque tool IDs that aren't unique within a thread (some platforms reuse them), regenerate with a stable scheme like `f"call_{i}"` where `i` is a per-thread counter. Update both the assistant and tool rows together.
-
-## Provider Fidelity (`provider_data`)
-
-Skip this entirely for **archive** imports.
-
-For **resumable** imports against the same provider, populate `provider_data` to preserve provider-specific tool-call metadata that the next API round-trip will require:
-
- **Anthropic**: `signature` field on thinking blocks; required for round-tripping extended-thinking responses.
- **Gemini**: `thought_signature` on tool calls; required for fidelity.
- **OpenAI**: typically nothing to preserve.
-
-The runtime-side dict key is `_provider_content` (a list of provider-native blocks); the persisted column is `provider_data` (the same list, JSON-encoded). If you don't have provider-native blocks from the source — and you usually won't, because a foreign export won't include them — leave `provider_data` NULL. The first new turn will succeed without it, but the previous assistant turn's reasoning won't replay back to the model.
-
-## Attachments
-
-If the source thread had image or file attachments:
-
- **Size limits**: images ≤ 4 MiB, text documents ≤ 512 KiB. Reject or downsample anything bigger.
- **Allowed types**: server validates magic bytes for images and UTF-8-decodes for text. Binary blobs that aren't images won't pass.
- **Blob identity**: `attachment_id` is the lowercase SHA-256 hex digest of the
-  bytes. `workstream_attachments` stores that content-addressed blob and its
-  refcount; it has no workstream or message foreign key.
- **Message link**: the sole message-to-blob link is the ordered JSON ID list in
-  `conversations.attachments`.
- **No persisted staging lifecycle**: pending upload bytes live only in a
-  node's in-memory attachment buffer. The old persisted
-  `pending → reserved → consumed` lifecycle does not apply to storage imports.
-
-For new attachment bytes, preserve row order by calling `save_message()` for
-each turn. It returns the `conversations.id`; for every attachment referenced by
-that turn, call `save_attachment()` with its content hash and bytes, then call
-`set_message_attachments(ws_id, message_id, ordered_ids)`. Each
-`save_attachment()` call accounts for one reference, while
-`set_message_attachments()` records the ordered link.
-
-`save_messages_bulk(..., attachment_ids=[...])` is appropriate only when those
-content-addressed blobs already exist: the bulk transaction retains their
-references and writes the ordered lists. Do not first call `save_attachment()`
-for a new reference and then pass the same reference to `save_messages_bulk()`;
-both paths retain it and would double-count the refcount.
-
-SDK multipart create remains useful only for attachments on a new first turn;
-it publishes a live session and is not the full-history import path.
-
-## Validation Checklist
-
-Before declaring success, verify:
-
- [ ] `ws_id` is 32-char lowercase hex.
- [ ] The workstream remained closed and absent from every live manager while rows were written; archives stay closed and resumable imports are opened only after validation.
- [ ] `workstreams` row exists with the right `user_id` and `kind`.
- [ ] Conversation rows are inserted **in order** (autoincrement `id` will reflect insert order).
- [ ] Every assistant `tool_calls[].id` has a matching `role="tool"` row with the same `tool_call_id`.
- [ ] `tool_calls[].function.arguments` is a JSON-encoded **string**, not a parsed object.
- [ ] First message is typically `role="user"` (not `system`) — Turnstone composes its own system prompt at runtime.
- [ ] No empty assistant rows (`content=NULL` AND `tool_calls=NULL` is invalid).
- [ ] Every attachment ID is the SHA-256 of its stored bytes; each turn's ordered IDs are in `conversations.attachments`, and blob refcounts match message references.
- [ ] If multi-node: the row is in shared storage and the node selected by
-  `ConsoleRouter.route(ws_id)` from the current live set can load it.
-  `workstreams.node_id`, when present, is treated as a creation-time hint rather
-  than asserted equal to the current HRW result.
- [ ] Round-trip test: run `Storage.load_messages(ws_id)` and confirm the reconstructed list matches what you inserted (modulo timestamps).
-
-## Anti-patterns
-
- **Don't import the source provider's system prompt verbatim.** Provider boilerplate ("You are Claude...", "You are ChatGPT...") will conflict with Turnstone's composed system message and confuse the model on resume. Drop it; preserve only user-authored custom instructions.
- **Don't preserve foreign tool definitions as Turnstone tools.** If the source had custom tools that don't exist in Turnstone, the assistant rows that called them are still valid history (archive), but the workstream is **not resumable** — mark `state="closed"`.
- **Don't fabricate `tool_call_id`s without re-pairing.** Mismatched ids silently break the replay chain on the next turn.
- **Don't skip the `tool_name` field on `role="tool"` rows.** Some load paths use it for display and audit; NULL there will render as "unknown tool".
- **Don't write through the LLM (`send()` per turn) for full history.** It's expensive, rewrites assistant turns, and rate-limits will bite long imports.
- **Don't shard imported rows by an ID prefix or a one-time HRW result.** HRW
-  uses the full ID and live membership; placement may move. In a cluster, write
-  one copy to shared storage and let request routing select the live node.
-
-## Quick Reference
-
-| Task | Path |
-|---|---|
-| Generate ws_id | `secrets.token_hex(16)` |
-| Multi-node placement | Full-ID 32-bit FNV-1a HRW over live servers; store rows once in shared storage |
-| Bulk insert attachment-free messages | `Storage.save_messages_bulk(rows)` |
-| Attach new bytes | `save_message()` → `save_attachment()` per reference → `set_message_attachments()` |
-| Archive (read-only) | `state="closed"`, skip `provider_data` |
-| Resumable | Register closed, import and validate while unloaded, then explicitly open; populate `provider_data` if same provider |
-| Tool call id | OpenAI shape: `{"id": ..., "type": "function", "function": {"name": ..., "arguments": "<json string>"}}` |
-| Tool result row | `role="tool"`, `tool_name`, `tool_call_id`, `content` |
-| Source role → Turnstone role | See "Role Mapping" table |
-| Per-thread metadata | Store source IDs in `workstream_config` under `import.*` keys |
-
-## Files to read before writing the importer
-
- `turnstone/core/storage/_schema.py` — authoritative table definitions.
- `turnstone/core/storage/_protocol.py` — `register_workstream`, message, attachment, and load signatures.
- `turnstone/core/rendezvous.py` — authoritative full-ID FNV-1a HRW scoring.
- `turnstone/console/router.py` — live-node discovery, override precedence, and routing behavior.
- `turnstone/core/session.py` (around the message-save section) — how the runtime constructs in-memory message dicts; mirror this shape on import to round-trip cleanly.
- `turnstone/api/server_schemas.py` — Pydantic shapes for the SDK paths if you go through HTTP.
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
Patrick Buckley	06c41f0a59	chore: bump version to 1.0.2	2026-04-03 15:40:23 -07:00
Patrick Buckley	d107e6edf0	Fix/web fetch reliability (#290 ) * fix: improve web_fetch reliability — strip scripts, dynamic truncation, more tokens - strip_html() now removes <script>, <style>, <template>, <noscript> element content instead of just their tags - Truncation budget scales with context window (75% in chars, 50k floor) and takes from the beginning only instead of head+tail splice - max_tokens bumped from 2000 to 8192 so thinking models don't starve the visible extraction answer - reasoning_effort="low" on summarization call to avoid wasting tokens - Empty responses and empty extractions now report as tool errors * refactor: extract _utility_completion to fix reasoning_effort duplication Callers previously had to pass reasoning_effort both as a direct keyword (for commercial providers) and via _provider_extra_params (for local model servers). This duplication was easy to get wrong — web_fetch was already missing the direct keyword. _utility_completion threads it through both paths from a single call, used by title generation, compaction, and web_fetch extraction. * fix: disable thinking when max_tokens too small, cap extraction at 500k _reasoning_params now returns empty dict when max_tokens can't fit a thinking budget (e.g. title gen with max_tokens=200). Previously produced budget_tokens >= max_tokens which is an API error on manual-thinking Anthropic models. Also caps web_fetch content truncation at 500k chars — the dynamic context-window calc was producing 3M chars on 1M-context models. * fix: clamp utility max_tokens to model output limit, add strip_html tests _utility_completion now clamps max_tokens to the model's advertised max_output_tokens so small/local models don't reject 8192-token requests. Adds 8 tests for invisible element stripping (script, style, template, noscript) including multiline, case-insensitive, and attribute cases. * fix: mock get_capabilities in title retry tests for _utility_completion _utility_completion calls _get_capabilities to clamp max_tokens. The existing title tests mocked _provider as a bare MagicMock, so caps.max_output_tokens was a truthy MagicMock instead of an int. Set get_capabilities to return a real ModelCapabilities instance.	2026-04-03 15:39:34 -07:00
Patrick Buckley	22c20a8dbd	fix: share single Docker image across all compose services Build the image once via the profileless console service and reference it as turnstone:local from server/channel. Prevents stale images when users run docker compose build without --profile.	2026-04-03 15:39:34 -07:00
Patrick Buckley	179143431d	fix: include prompt .md files in wheel, add wheel-completeness CI (#289 ) (#291 ) * fix: include prompt .md files in wheel, add wheel-completeness CI (#289) Prompt markdown files were missing from PyPI wheels since the modular prompts refactor, causing FileNotFoundError on startup for pip-installed users. Add the missing include pattern and a new CI job that diffs source-tree data files against wheel contents so omissions are caught before merge. * fix: sanitise ALLOW patterns in wheel-completeness check Strip blank lines and leading whitespace from the allowlist before passing to grep -vFxf so empty patterns cannot silently match all lines.	2026-04-03 15:39:34 -07:00
Patrick Buckley	d4a6866045	fix: log clean one-liner when PostgreSQL becomes unavailable (#288 ) * fix: log clean one-liner when PostgreSQL becomes unavailable Wrap all 174 connection sites in PostgreSQLBackend through a _conn() context manager that catches OperationalError, emits a single database.unavailable log line (with connection URL), and suppresses repeats until the connection is restored (database.connection_restored). * fix: add StorageUnavailableError and cover all heartbeat loops Address review feedback: - Separate connect-phase from execution-phase in _conn() so that OperationalError during caller code (e.g. BEGIN IMMEDIATE lock contention) is not misclassified as a connectivity failure. - Add StorageUnavailableError exception class so callers can distinguish transient DB outages without redundant tracebacks. - Apply the same _conn() wrapper to SQLiteBackend for consistency. - Catch StorageUnavailableError in all 7 periodic loops: watch runner, server heartbeat, channel heartbeat, console heartbeat, collector discovery, rebalancer, and scheduler. - Guard dedup flag with threading.Lock. - Add tests for dedup logging and PostgreSQL path.	2026-04-03 15:39:34 -07:00
Patrick Buckley	c4abd62226	fix: add concurrency groups to publish workflows Multiple CI completions for the same commit (tag push + branch push) caused duplicate publish and docker runs. Concurrency group keyed on head_sha ensures only one publish runs per commit.	2026-04-03 15:39:34 -07:00
Patrick Buckley	b3926c372a	chore: bump version to 1.0.1	2026-04-02 20:29:02 -07:00
Patrick Buckley	5efe52d433	fix: chunk IN clauses to stay within DB parameter limits (#286 ) * fix: chunk IN clauses to stay within DB parameter limits psycopg caps query parameters at 65 535 and SQLite defaults to 999. assign_buckets, prune_workstreams, and count_skill_resources_bulk were passing unbounded lists into single IN(...) clauses, causing OperationalError during rebalancer runs on full-size hash rings. Chunk sizes: 10 000 (PostgreSQL), 500 (SQLite). * fix: deduplicate assign_buckets input, add chunking regression tests Address review feedback: deduplicate bucket list before chunking to prevent inflated rowcount from cross-chunk duplicates. Add tests that exercise the multi-chunk path (1200 buckets > SQLite chunk_size of 500) and verify dedup preserves accurate counts.	2026-04-02 20:28:54 -07:00