deploy: full-stack Render blueprint (Qdrant + Ollama embed + token-gated MCP)

The "Deploy to Render" button now provisions the whole backend, not just the
demo deck. render.yaml grows from one service to four:

- ats-qdrant (pserv + disk)  — vector search memory, private
- ats-ollama (pserv + disk)  — nomic-embed-text embedding engine, private
- ats-mcp (web, Docker)      — public, bearer-token-gated MCP over /mcp + /sse
- ats-operator-backend       — unchanged demo deck

Safety: deploy/mcp/auth-gateway.mjs is the only public port; every request
needs Authorization: Bearer <ATS_MCP_TOKEN> (generateValue), /healthz open.
It fronts mcp-proxy@6.5.1 (stdio -> HTTP/SSE, localhost only). Qdrant and
Ollama have no public address; ats-mcp reaches them via fromService host refs
over the private network. start.sh materializes ~/.config/ats from
TICKTICK_ACCESS_TOKEN (the adapter has no env-token path).

Also: deploy/README.md operator guide, README "Deploy it yourself" rewritten
for the multi-service stack, and the operator-deck demo card swapped off a
real-looking ticket scheme to a clearly fictional one.

Author: renezander030

README.md

@@ -158,9 +158,9 @@ flowchart TB
     deck["Operator deck — the swipe UI"]
   end
 
-  subgraph HOST["VPS or Render · the part you deploy"]
-    agent["AI agent + ATS core<br/>MCP server · CLI · suggestion engine"]
-    search["Qdrant + Ollama<br/>optional semantic search"]
+  subgraph HOST["Render · the part you deploy (one click)"]
+    mcp["MCP server<br/>your agent connects here · token-gated"]
+    search["Search memory + embedding engine<br/>Qdrant + Ollama (nomic-embed)"]
   end
 
   subgraph TASKS["Your tools · already in the cloud"]
@@ -171,27 +171,28 @@ flowchart TB
   end
 
   user --> deck
-  deck -->|"approve · reject · modify"| agent
-  agent --> tt & nt & ob & gg
-  agent -.->|"rank"| search
+  deck -->|"approve · reject · modify"| mcp
+  mcp --> tt & nt & ob & gg
+  mcp -.->|"rank"| search
 ```
 
 - **The operator deck (the app on your phone)** lives on **Cloudflare Pages** — free, always on, nothing to manage.
-- **The backend (the agent that reads your tasks and proposes the next action)** runs on a **VPS or Render**. This is the only part you deploy.
+- **The backend you deploy** runs on **Render**. One click gives you the whole thing: the **MCP server** your agent connects to, plus its own **search memory** (Qdrant) and **embedding engine** (Ollama) so it can find tasks by meaning, not just keywords.
 - **Your task systems** (TickTick, Notion, Obsidian, Gmail/Calendar) are already in the cloud — ATS just connects to them.
 
 ### Deploy the backend in one click
 
 No terminal needed:
 
-1. Click the button. It opens **Render** (a hosting service with a free tier).
-2. Sign in with GitHub and confirm — Render reads the blueprint in this repo and builds everything for you.
-3. In a few minutes you get a URL like `https://ats-operator-backend.onrender.com`. That's your backend.
-4. It starts in **demo mode** so you see it working right away. To connect your own tasks, open the service's **Environment** tab in Render, set `DECK_DEMO` to `0`, and add your task-system token (see [the operator-deck guide](examples/operator-deck/)).
+1. Click the button. It opens **Render** (a hosting service). Sign in with GitHub.
+2. Render reads the blueprint in this repo and builds **four pieces** for you: the MCP server (the door your agent knocks on), a search memory, an embedding engine, and the operator-deck backend. The search memory and embedding engine are kept **private** — only your own server can reach them.
+3. In a few minutes the MCP server is live at a URL like `https://ats-mcp.onrender.com`. Its tasks-by-meaning search works out of the box; you only add your own task-system token when you want it reading *your* tasks.
+4. **Connect your agent — safely.** Open the **ats-mcp** service's **Environment** tab in Render and copy the auto-generated **`ATS_MCP_TOKEN`**. That token is the lock on the door: every request must carry it. Point your MCP client at `https://<your-mcp-url>/mcp` and have it send the header `Authorization: Bearer <ATS_MCP_TOKEN>`. No token, no access.
+5. **Wire your own tasks (optional).** In the same tab, paste your task-system token into `TICKTICK_ACCESS_TOKEN`. The server restarts and now reads your real tasks.
 
 [![Deploy to Render](https://render.com/images/deploy-to-render-button.svg)](https://render.com/deploy?repo=https://github.com/renezander030/agentic-task-system)
 
-> Render's free tier sleeps after inactivity, so the first request after a quiet spell takes ~30s to wake. Any cheap VPS — or a paid Render instance — keeps it always on.
+> This stack runs on Render's paid instances (the search memory and embedding engine each need a little always-on RAM and a small disk), so it stays awake and answers instantly — no cold-start wait. Prefer to run it on your own machine or a VPS instead? The same pieces are plain Docker containers; see [the deploy guide](deploy/README.md).
 
 ## Architecture
 

deploy/README.md

@@ -0,0 +1,110 @@
+# Deploying the ATS backend
+
+The [`render.yaml`](../render.yaml) blueprint at the repo root deploys the whole
+ATS backend with one click (see the [Deploy it yourself](../README.md#deploy-it-yourself)
+section of the main README). This guide explains what gets created, how the
+security works, how to connect your agent, and how to run the same pieces on
+your own machine instead.
+
+## What the blueprint creates
+
+| Service | Type | Public? | What it is |
+| --- | --- | --- | --- |
+| `ats-qdrant` | private | no | **Search memory** — a [Qdrant](https://qdrant.tech) vector database holding task embeddings. |
+| `ats-ollama` | private | no | **Embedding engine** — [Ollama](https://ollama.com) serving `nomic-embed-text` (768-dim). Turns text into vectors for the search memory. |
+| `ats-mcp` | web | **yes, token-gated** | **MCP server** — the door your AI agent connects to. Speaks MCP over HTTP + SSE. |
+| `ats-operator-backend` | web | yes | **Operator deck backend** — the swipe-to-approve card UI's backend. Demo mode by default. |
+
+The search memory and embedding engine are **private services**: they have no
+public address and can only be reached by your other services over Render's
+internal network. The only thing exposed to the internet is the MCP server, and
+that is locked behind a bearer token.
+
+```
+  your AI agent
+       │  Authorization: Bearer <ATS_MCP_TOKEN>
+       ▼
+  ats-mcp  (public)  ──►  auth gateway  ──►  mcp-proxy  ──►  ATS stdio server
+       │                                                          │
+       │ private network                                          │
+       ├────────────────────────────►  ats-qdrant   (private, vectors)
+       └────────────────────────────►  ats-ollama   (private, embeddings)
+```
+
+## How "safely" works
+
+A Render web service exposes exactly one public port. For `ats-mcp` that port is
+a small **bearer-token gateway** ([`deploy/mcp/auth-gateway.mjs`](mcp/auth-gateway.mjs)):
+
+- Every request must carry `Authorization: Bearer <ATS_MCP_TOKEN>`. Without it
+  the gateway returns `401` and never touches the MCP server.
+- `ATS_MCP_TOKEN` is **auto-generated** by Render (`generateValue: true`), so each
+  deploy gets a strong, unique secret. You read it from the dashboard; it is
+  never committed to the repo.
+- The only unauthenticated route is `GET /healthz`, which returns a static `ok`
+  and proxies nothing.
+- Inside the container, `mcp-proxy` bridges the stdio MCP server to HTTP (`/mcp`,
+  streamable) and SSE (`/sse`) on localhost only — it is never publicly bound.
+
+## Connect your agent
+
+Point your MCP client at `https://<your-mcp-url>/mcp` and send the bearer token.
+
+**Claude Code / Desktop** (`~/.claude.json` or the desktop config), as a remote
+MCP server:
+
+```jsonc
+{
+  "mcpServers": {
+    "ats": {
+      "type": "http",
+      "url": "https://ats-mcp.onrender.com/mcp",
+      "headers": { "Authorization": "Bearer YOUR_ATS_MCP_TOKEN" }
+    }
+  }
+}
+```
+
+Quick liveness check (no token needed):
+
+```bash
+curl https://ats-mcp.onrender.com/healthz   # -> {"ok":true,"service":"ats-mcp"}
+```
+
+## Environment variables (`ats-mcp`)
+
+| Variable | Set by | Purpose |
+| --- | --- | --- |
+| `ATS_MCP_TOKEN` | Render (generated) | The bearer token your agent must send. |
+| `ATS_ADAPTER` | blueprint | Which task system to expose (default `@reneza/ats-adapter-ticktick`). |
+| `QDRANT_HOST` / `OLLAMA_HOST` | `fromService` | Private hostnames of the two backend services; the entrypoint composes `QDRANT_URL` / `OLLAMA_URL` from them. |
+| `TICKTICK_ACCESS_TOKEN` | you (optional) | Your task-system token. Paste it to make the server read your real tasks. |
+| `TICKTICK_CLIENT_ID` / `TICKTICK_CLIENT_SECRET` | you (optional) | Only needed if you want the token to auto-refresh. A long-lived Open API token does not. |
+
+Without a token the server still boots and `tools/list` works; tools that need
+credentials simply error until you add one.
+
+## Run it on your own machine instead
+
+The services are plain containers — the same images, no Render required:
+
+```bash
+# 1) Search memory + embedding engine
+docker run -d --name qdrant -p 6333:6333 -v qdrant_storage:/qdrant/storage qdrant/qdrant
+docker run -d --name ollama -p 11434:11434 -v ollama_models:/root/.ollama ollama/ollama
+docker exec ollama ollama pull nomic-embed-text
+
+# 2) MCP server (built from this repo's deploy/mcp/Dockerfile)
+docker build -f deploy/mcp/Dockerfile -t ats-mcp .
+docker run -d --name ats-mcp -p 8443:10000 \
+  -e PORT=10000 \
+  -e ATS_MCP_TOKEN="pick-a-long-secret" \
+  -e QDRANT_HOST=host.docker.internal \
+  -e OLLAMA_HOST=host.docker.internal \
+  -e TICKTICK_ACCESS_TOKEN="your-token" \
+  ats-mcp
+```
+
+Your agent then connects to `http://localhost:8443/mcp` with the same bearer
+token. For a no-container dev loop, the MCP server also runs straight over stdio
+(`npx @reneza/ats-mcp`) — see [`packages/mcp`](../packages/mcp/).

deploy/mcp/Dockerfile

@@ -0,0 +1,30 @@
+# ATS MCP server for Render — a public, bearer-token-gated HTTP/SSE endpoint.
+#
+# Builds the workspace from source (plain JS, no build step), installs mcp-proxy
+# to bridge the stdio MCP server to HTTP, and ships a tiny bearer-auth gateway
+# (deploy/mcp/auth-gateway.mjs) as the only public port. Build context is the
+# repo root (dockerContext: . in render.yaml).
+FROM node:22-alpine
+
+# mcp-proxy 6.5.1 — the version proven in the Glama deployment (3.0.3 crashes on
+# completions). It exposes /mcp (streamable HTTP) and /sse from a stdio server.
+RUN npm install -g mcp-proxy@6.5.1
+
+WORKDIR /app
+
+# Install workspace deps from source. --ignore-scripts skips the husky prepare
+# hook (no git in the build context).
+COPY package.json package-lock.json ./
+COPY packages ./packages
+RUN npm ci --ignore-scripts
+
+# Deploy entrypoint + gateway.
+COPY deploy/mcp ./deploy/mcp
+RUN chmod +x /app/deploy/mcp/start.sh
+
+# Default adapter (a workspace package). Override at runtime with ATS_ADAPTER.
+ENV ATS_ADAPTER=@reneza/ats-adapter-ticktick
+# Internal port mcp-proxy listens on; the gateway proxies to it and binds $PORT.
+ENV MCP_PROXY_PORT=8080
+
+CMD ["/bin/sh", "/app/deploy/mcp/start.sh"]

deploy/mcp/auth-gateway.mjs

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+/**
+ * Bearer-token auth gateway for the ATS MCP server on Render.
+ *
+ * A Render web service exposes exactly ONE public port. This gateway is that
+ * port: it checks `Authorization: Bearer <ATS_MCP_TOKEN>` on every request,
+ * then streams the request through to mcp-proxy on 127.0.0.1:<MCP_PROXY_PORT>
+ * (which speaks the MCP Streamable HTTP `/mcp` and SSE `/sse` transports over
+ * the stdio server). No token, no entry — so the user's agent can reach the
+ * MCP server safely over the public internet.
+ *
+ * Unauthenticated exception: GET /healthz (Render's health check + a liveness
+ * probe anyone can hit). It returns only a static ok and never proxies.
+ *
+ * Streaming matters: SSE responses must flow byte-for-byte without buffering,
+ * and the connection is long-lived — so we pipe raw and disable the HTTP
+ * server timeouts that would otherwise sever an idle stream.
+ */
+import http from 'node:http';
+
+const PORT = Number(process.env.PORT) || 10000;
+const UPSTREAM_HOST = '127.0.0.1';
+const UPSTREAM_PORT = Number(process.env.MCP_PROXY_PORT) || 8080;
+const TOKEN = process.env.ATS_MCP_TOKEN || '';
+
+if (!TOKEN) {
+  console.error(
+    '[ats-mcp-gateway] FATAL: ATS_MCP_TOKEN is not set — refusing to start an unauthenticated MCP endpoint.'
+  );
+  process.exit(1);
+}
+
+function unauthorized(res) {
+  res.writeHead(401, {
+    'content-type': 'application/json',
+    'www-authenticate': 'Bearer realm="ats-mcp"',
+  });
+  res.end(JSON.stringify({ error: 'unauthorized', detail: 'Send Authorization: Bearer <token>' }));
+}
+
+const server = http.createServer((req, res) => {
+  // Liveness probe — no token required, proxies nothing, reveals nothing.
+  if (req.method === 'GET' && req.url === '/healthz') {
+    res.writeHead(200, { 'content-type': 'application/json' });
+    res.end(JSON.stringify({ ok: true, service: 'ats-mcp' }));
+    return;
+  }
+
+  const auth = req.headers['authorization'] || '';
+  const expected = `Bearer ${TOKEN}`;
+  // Length check first so the constant string compare doesn't leak via early exit.
+  if (auth.length !== expected.length || auth !== expected) {
+    unauthorized(res);
+    return;
+  }
+
+  // Pass the request straight through to mcp-proxy. Piping (no buffering) is
+  // what keeps SSE working.
+  const upstream = http.request(
+    {
+      host: UPSTREAM_HOST,
+      port: UPSTREAM_PORT,
+      method: req.method,
+      path: req.url,
+      headers: { ...req.headers, host: `${UPSTREAM_HOST}:${UPSTREAM_PORT}` },
+    },
+    (upRes) => {
+      res.writeHead(upRes.statusCode || 502, upRes.headers);
+      upRes.pipe(res);
+    }
+  );
+  upstream.on('error', (err) => {
+    if (!res.headersSent) res.writeHead(502, { 'content-type': 'application/json' });
+    res.end(JSON.stringify({ error: 'bad_gateway', detail: String((err && err.message) || err) }));
+  });
+  req.pipe(upstream);
+});
+
+// SSE connections are long-lived — disable the timeouts that would sever them.
+server.requestTimeout = 0;
+server.headersTimeout = 0;
+server.timeout = 0;
+
+server.listen(PORT, () => {
+  console.error(
+    `[ats-mcp-gateway] listening on :${PORT} -> mcp-proxy ${UPSTREAM_HOST}:${UPSTREAM_PORT} (bearer-gated)`
+  );
+});

deploy/mcp/start.sh

@@ -0,0 +1,56 @@
+#!/bin/sh
+# Entrypoint for the ATS MCP web service on Render.
+#
+# 1. Materialize TickTick credentials from env (Render has no ~/.config).
+# 2. Compose QDRANT_URL / OLLAMA_URL from the private hostnames Render injects.
+# 3. Launch the stdio MCP server behind mcp-proxy (HTTP + SSE), then the
+#    bearer-token gateway that is the only public port.
+set -e
+
+# --- 1. Credentials ---------------------------------------------------------
+# The ticktick adapter reads ~/.config/ats/{tokens.json,config.json}. If the
+# operator pasted a token into the Render dashboard, write those files so the
+# adapter authenticates without an interactive OAuth flow. With no token set,
+# the server still boots and `tools/list` works — tools that need credentials
+# simply error until a token is added.
+CONFIG_DIR="${XDG_CONFIG_HOME:-$HOME/.config}/ats"
+if [ -n "$TICKTICK_ACCESS_TOKEN" ]; then
+  mkdir -p "$CONFIG_DIR"
+  # expiresAt is set far in the future (year 2100) so the adapter never tries to
+  # refresh — a long-lived TickTick Open API token does not expire on its own.
+  cat > "$CONFIG_DIR/tokens.json" <<EOF
+{"accessToken":"$TICKTICK_ACCESS_TOKEN","refreshToken":"${TICKTICK_REFRESH_TOKEN:-}","expiresAt":4102444800000,"tokenType":"bearer"}
+EOF
+  chmod 600 "$CONFIG_DIR/tokens.json"
+  cat > "$CONFIG_DIR/config.json" <<EOF
+{"clientId":"${TICKTICK_CLIENT_ID:-unused}","clientSecret":"${TICKTICK_CLIENT_SECRET:-unused}","region":"${TICKTICK_REGION:-global}"}
+EOF
+  chmod 600 "$CONFIG_DIR/config.json"
+  echo "[ats-mcp] wrote TickTick credentials to $CONFIG_DIR"
+fi
+
+# --- 2. Service URLs --------------------------------------------------------
+# QDRANT_HOST / OLLAMA_HOST come from fromService (host only); ports are fixed.
+if [ -n "$QDRANT_HOST" ]; then export QDRANT_URL="http://$QDRANT_HOST:6333"; fi
+if [ -n "$OLLAMA_HOST" ]; then export OLLAMA_URL="http://$OLLAMA_HOST:11434"; fi
+echo "[ats-mcp] QDRANT_URL=${QDRANT_URL:-unset} OLLAMA_URL=${OLLAMA_URL:-unset} adapter=${ATS_ADAPTER:-default}"
+
+# --- 3. Processes -----------------------------------------------------------
+MCP_PROXY_PORT="${MCP_PROXY_PORT:-8080}"
+export MCP_PROXY_PORT
+
+# mcp-proxy bridges our stdio MCP server to HTTP (/mcp) + SSE (/sse) on localhost.
+mcp-proxy --port "$MCP_PROXY_PORT" -- node /app/packages/mcp/server.js &
+PROXY_PID=$!
+
+# The gateway is the public port; it bearer-gates every request to mcp-proxy.
+node /app/deploy/mcp/auth-gateway.mjs &
+GATE_PID=$!
+
+# If either process exits, bring the container down so Render restarts it clean.
+while kill -0 "$PROXY_PID" 2>/dev/null && kill -0 "$GATE_PID" 2>/dev/null; do
+  sleep 5
+done
+echo "[ats-mcp] a child process exited — shutting down for a clean restart"
+kill "$PROXY_PID" "$GATE_PID" 2>/dev/null || true
+exit 1

deploy/ollama/Dockerfile

@@ -0,0 +1,14 @@
+# ATS embedding engine for Render — Ollama serving nomic-embed-text (768-dim),
+# the same model the ticktick adapter uses everywhere else. Private service:
+# only ats-mcp (and other backend services) reach it over Render's network.
+# Build context is the repo root (dockerContext: . in render.yaml).
+FROM ollama/ollama:latest
+
+ENV OLLAMA_HOST=0.0.0.0:11434
+
+COPY deploy/ollama/start.sh /start.sh
+RUN chmod +x /start.sh
+
+# The base image sets ENTRYPOINT ["/bin/ollama"]; clear it so our script runs.
+ENTRYPOINT []
+CMD ["/bin/sh", "/start.sh"]

deploy/ollama/start.sh

@@ -0,0 +1,24 @@
+#!/bin/sh
+# Entrypoint for the ATS embedding engine on Render.
+#
+# Starts Ollama, waits for it to accept connections, then pulls the embedding
+# model. The pull is idempotent and the model lives on a mounted disk
+# (/root/.ollama), so a restart reuses it instead of downloading again.
+set -e
+
+export OLLAMA_HOST="0.0.0.0:11434"
+MODEL="${EMBEDDING_MODEL:-nomic-embed-text}"
+
+ollama serve &
+SERVE_PID=$!
+
+echo "[ats-ollama] waiting for ollama to come up..."
+until ollama list >/dev/null 2>&1; do
+  sleep 1
+done
+
+echo "[ats-ollama] ensuring embedding model: $MODEL"
+ollama pull "$MODEL"
+echo "[ats-ollama] ready on :11434 (model: $MODEL)"
+
+wait "$SERVE_PID"

examples/operator-deck/demo-data.mjs

@@ -47,10 +47,10 @@ export const DEMO_SUGGESTIONS = [
     back: { heading: 'Why', body: 'No movement for 47 days and the queue decision already shipped. Archiving (reversible) stops dead context steering planning.' },
   },
   {
-    id: 'demo-merge-fde', kind: 'relate', score: 0.61,
+    id: 'demo-merge-roles', kind: 'relate', score: 0.61,
     items: [
-      { adapter: 'ticktick', title: 'FDE-044: AI Engineer (Python + React)' },
-      { adapter: 'ticktick', title: 'FDE-055: FullStack AI Developer' },
+      { adapter: 'ticktick', title: 'JOB-201: Senior Backend Engineer (Go)' },
+      { adapter: 'ticktick', title: 'JOB-214: Backend Engineer, Platform team' },
     ],
     action: 'Merge these duplicate role specs',
     back: { heading: 'Why', body: 'Near-duplicate role specs sitting apart. Linking them as the same search keeps them from drifting out of sync.' },