Return artifacts from YNAB budget, transaction and spending tools

Convert ynab_budget_summary, ynab_search_transactions, ynab_spending_report
and ynab_category_budget to content_and_artifact (ynab.summary,
ynab.transactions, ynab.spending_report, ynab.category_budget). The text
the LLM sees is unchanged. Not-synced, bad-input, empty and error paths
return no artifact; Decimals become floats and dates ISO strings.

ynab_search_transactions now fetches up to 500 rows in one query (with an
id tie-break so ordering is stable) and lists the first `limit` in the
text; the artifact carries all of them. ynab_account_balances,
ynab_recent_changes and ynab_sql stay text-only.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

.env.example

@@ -10,6 +10,12 @@ POSTGRES_DB=raggr
 # JWT Configuration
 JWT_SECRET_KEY=your-secret-key-here
 
+# Metrics Configuration
+# Bearer token for the /metrics endpoint (Prometheus scrape + app token gate).
+# Generate with: openssl rand -hex 32
+# Leave empty to keep /metrics returning 403 (fail-closed).
+METRICS_TOKEN=
+
 # Paperless Configuration
 PAPERLESS_TOKEN=your-paperless-token
 BASE_URL=192.168.1.5:8000
@@ -18,11 +24,13 @@ BASE_URL=192.168.1.5:8000
 # If set, uses llama-server as the primary LLM backend with OpenAI as fallback
 LLAMA_SERVER_URL=http://192.168.1.213:8080/v1
 LLAMA_MODEL_NAME=llama-3.1-8b-instruct
+TTFT_TIMEOUT_SECONDS=30
 
-# ChromaDB Configuration
-# For Docker: This is automatically set to /app/data/chromadb
-# For local development: Set to a local directory path
-CHROMADB_PATH=./data/chromadb
+# Embedding Server Configuration
+# If set, uses a custom OpenAI-compatible embedding server (e.g. llama-server)
+# Falls back to OpenAI embeddings if not set
+EMBEDDING_SERVER_URL=http://192.168.1.7:8086/v1
+EMBEDDING_MODEL_NAME=all-minilm
 
 # OpenAI Configuration
 OPENAI_API_KEY=your-openai-api-key
@@ -54,12 +62,16 @@ OIDC_USE_DISCOVERY=true
 YNAB_ACCESS_TOKEN=your-ynab-personal-access-token
 # Optional: Specify a budget ID, or leave empty to use the default/first budget
 YNAB_BUDGET_ID=
+# Seconds between background YNAB delta syncs (agent tools also sync on demand)
+YNAB_SYNC_INTERVAL=900
 
 # Mealie Configuration
 # Base URL for your Mealie instance (e.g., http://192.168.1.5:9000 or https://mealie.example.com)
 MEALIE_BASE_URL=http://192.168.1.5:9000
 # Get your API token from Mealie's user settings page
 MEALIE_API_TOKEN=your-mealie-api-token
+# Group slug used in recipe page links (/g/<slug>/r/<recipe>); defaults to "home"
+MEALIE_GROUP_SLUG=home
 
 # Email Integration
 # Email Encryption Key (32-byte URL-safe base64)
@@ -92,9 +104,61 @@ EMAIL_HMAC_SECRET=
 # Set to false to disable Mailgun signature validation in development
 MAILGUN_SIGNATURE_VALIDATION=true
 
+# SendBlue Configuration (iMessage)
+SENDBLUE_API_KEY=your-sendblue-api-key
+SENDBLUE_API_SECRET=your-sendblue-api-secret
+SENDBLUE_FROM_NUMBER=+1XXXXXXXXXX
+SENDBLUE_WEBHOOK_SECRET=your-sendblue-webhook-secret
+# Set to false to disable SendBlue signature validation in development
+SENDBLUE_SIGNATURE_VALIDATION=true
+# Comma-separated list of iMessage numbers allowed to use the service (E.164 format)
+# Use * to allow any number
+ALLOWED_IMESSAGE_NUMBERS=
+# Rate limiting: max messages per window (default: 10 messages per 60 seconds)
+# IMESSAGE_RATE_LIMIT_MAX=10
+# IMESSAGE_RATE_LIMIT_WINDOW=60
+
+# Google Calendar + Gmail Configuration (Python SDK)
+# Run scripts/google_auth.py to generate token.json from your OAuth2 credentials:
+#   python scripts/google_auth.py --credentials credentials.json --token token.json
+# Then mount token.json into the container (see docker-compose.yml).
+# If GOOGLE_TOKEN_FILE points to a valid token, both Calendar and Gmail are enabled.
+GOOGLE_TOKEN_FILE=/app/config/google-token.json
+
+# Cronicle Integration
+# Shared secret for Cronicle to authenticate cron job trigger requests.
+# Generate with: openssl rand -hex 32
+CRON_SECRET=
+# Cronicle server URL and API key (from Cronicle Admin → API Keys)
+# Used to auto-register scheduled jobs on startup.
+CRONICLE_URL=http://cronicle:3012
+CRONICLE_API_KEY=
+
+# SimbaKit / PetKit Configuration
+# PetKit account credentials (used by SimbaKit to poll device data)
+PETKIT_USERNAME=your-petkit-email
+PETKIT_PASSWORD=your-petkit-password
+PETKIT_REGION=US
+PETKIT_TIMEZONE=America/New_York
+# Internal URL for SimbaKit service (Docker network)
+SIMBAKIT_URL=http://simbakit:8585
+
+# Homebox inventory (admin-only agent tools via homebox-mcp, needs Homebox >= 0.26)
+# API key from Homebox Profile -> API Keys (starts with hb_). Leave empty to disable.
+HOMEBOX_URL=https://homebox.example.com
+HOMEBOX_TOKEN=
+
+# BookStack wiki (admin-only agent tools via bookstack-mcp: read, create, update; no deletes)
+# API token from BookStack Profile -> API Tokens (user needs the "Access System API" permission).
+# Leave empty to disable.
+BOOKSTACK_BASE_URL=https://bookstack.example.com
+BOOKSTACK_TOKEN_ID=
+BOOKSTACK_TOKEN_SECRET=
+
 # Obsidian Configuration (headless sync)
-# Auth token from Obsidian account (Settings → Account → API token)
-OBSIDIAN_AUTH_TOKEN=your-obsidian-auth-token
+# Obsidian account credentials (used for `ob login` on container startup)
+OBSIDIAN_EMAIL=your-obsidian-email
+OBSIDIAN_PASSWORD=your-obsidian-password
 # Vault ID to sync (found in Obsidian sync settings)
 OBSIDIAN_VAULT_ID=your-vault-id
 # End-to-end encryption password (if vault uses E2E encryption)
@@ -105,3 +169,13 @@ OBSIDIAN_DEVICE_NAME=simbarag
 OBSIDIAN_CONTINUOUS_SYNC=false
 # Local path to Obsidian vault (where files are synced)
 OBSIDIAN_VAULT_PATH=/app/data/obsidian
+# Vault name for obsidian://open links in the artifact panel (optional; no link if unset)
+OBSIDIAN_VAULT_NAME=
+
+# LangGraph checkpoint store (SQLite). Must be on a persistent volume.
+# Both blue and green containers share this volume via docker-compose.
+CHECKPOINT_DB_PATH=/app/checkpoints/checkpoints.db
+
+# Beli restaurant recommendations
+# Beli account credentials for each profile are stored encrypted in the database.
+# No additional env vars needed — auth is done via the Beli API at login time.

.gitignore

@@ -11,11 +11,10 @@ wheels/
 
 # Environment files
 .env
+credentials.json
+token.json
 
 # Database files
-chromadb/
-chromadb_openai/
-chroma_db/
 database/
 *.db
 

CLAUDE.md

@@ -4,33 +4,39 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Project Overview
 
-SimbaRAG is a RAG (Retrieval-Augmented Generation) conversational AI system for querying information about Simba (a cat). It ingests documents from Paperless-NGX, stores embeddings in ChromaDB, and uses LLMs (Ollama or OpenAI) to answer questions.
+SimbaRAG is a RAG (Retrieval-Augmented Generation) conversational AI system for querying information about Simba (a cat) and the household. It ingests documents from Paperless-NGX, Obsidian, and Immich, stores embeddings in PostgreSQL via pgvector (Chroma client), uses LLMs (Ollama or OpenAI) to answer questions with a tool-using LangChain agent, and exposes chat over web, iMessage, and WhatsApp.
 
 ## Commands
 
 ### Development
 
 ```bash
-# Start environment
-docker compose up --build
+# Start environment (raggr runs as raggr-blue/raggr-green behind compose profiles)
+docker compose --profile blue up --build
 
-# View logs
-docker compose logs -f raggr
+# View logs (Makefile resolves the active color)
+make logs
+
+# Reindex vector store (all sources / Obsidian only)
+make reindex
+make reindex-obsidian
 ```
 
 ### Database Migrations (Aerich/Tortoise ORM)
 
 ```bash
 # Generate migration (must run in Docker with DB access)
-docker compose exec raggr aerich migrate --name describe_change
+make migrate-new
 
 # Apply migrations (auto-runs on startup, manual if needed)
-docker compose exec raggr aerich upgrade
+make migrate
 
 # View migration history
-docker compose exec raggr aerich history
+make migrate-history
 ```
 
+Migrations must be backward-compatible: blue-green deploys run `aerich upgrade` in the new container while the old code still serves.
+
 ### Frontend
 
 ```bash
@@ -42,9 +48,10 @@ yarn dev        # Dev server (rarely needed, backend serves frontend)
 
 ### Production
 
+Zero-downtime blue-green deploy: `raggr-blue` (port 8080) and `raggr-green` (port 8081) alternate behind Caddy health checks. See `docs/deployment.md`.
+
 ```bash
-docker compose build raggr
-docker compose up -d
+make redeploy    # git pull + scripts/deploy.sh (build new color, wait healthy, stop old)
 ```
 
 ## Architecture
@@ -53,10 +60,11 @@ docker compose up -d
 ┌─────────────────────────────────────────────────────────────┐
 │                     Docker Compose                          │
 ├─────────────────────────────────────────────────────────────┤
-│  raggr (port 8080)              │  postgres (port 5432)    │
-│  ├── Quart backend              │  PostgreSQL 16           │
+│  raggr-blue/green (8080/8081)   │  postgres (port 5432)    │
+│  ├── Quart backend              │  PostgreSQL 16 + pgvector│
 │  ├── React frontend (served)    │                          │
-│  └── ChromaDB (volume)          │                          │
+│  └── Twilio webhooks (iMessage/ │                          │
+│      WhatsApp)                  │                          │
 └─────────────────────────────────────────────────────────────┘
 ```
 
@@ -64,33 +72,53 @@ docker compose up -d
 - `app.py` - Quart application entry, serves API and static frontend
 - `main.py` - RAG logic, document indexing, LLM interaction, LangChain agent
 - `llm.py` - LLM client with Ollama primary, OpenAI fallback
-- `aerich_config.py` - Database migration configuration
 - `blueprints/` - API routes organized as Quart blueprints
   - `users/` - OIDC auth, JWT tokens, RBAC with LDAP groups
-  - `conversation/` - Chat conversations and message history
-  - `rag/` - Document indexing endpoints (admin-only)
+  - `conversation/` - Chat conversations, message history, streamed answers
+  - `rag/` - Document indexing endpoints (admin-only); logic in `rag/logic.py`
+  - `email/` - Email integration (Mailgun webhooks, Fernet encryption, IMAP, parsing)
+  - `imessage/` - Twilio webhook receiver for iMessage (HMAC-validated, number allowlist)
+  - `whatsapp/` - Twilio webhook receiver for WhatsApp (TWIML replies, SendBlue send support)
+  - `scheduled_messages/` - Scheduled message delivery with background scheduler
+  - `ynab/` - Postgres mirror of the YNAB budget (`ynab_*` tables), delta-synced via `server_knowledge` (background loop + on-demand before each tool call, full resync daily that also marks rows missing from the download as deleted); `ynab_changes` is the edit history YNAB itself doesn't keep. Agent tools in `tools.py`; admin-only read-only `ynab_sql` in `sql_tool.py`. Manual sync: `make ynab-sync` / `make ynab-resync`
 - `config/` - Configuration modules
+  - `db.py` - Database setup
   - `oidc_config.py` - OIDC authentication configuration
-- `utils/` - Reusable utilities
+- `utils/` - Reusable utilities and household integrations
   - `chunker.py` - Document chunking for embeddings
   - `cleaner.py` - PDF cleaning and summarization
   - `image_process.py` - Image description with LLM
   - `request.py` - Paperless-NGX API client
+  - `obsidian_service.py`, `mealie_service.py`, `ynab_service.py`, `s3_client.py`, `simbakit_service.py` - integrations with Obsidian notes, Mealie recipes, YNAB budgets (API client for the `blueprints/ynab/` mirror), S3, and SimbaKit
+  - `homebox_mcp.py` - Homebox inventory tools via the `homebox-mcp` stdio MCP server; admin-only (compiled into `app.admin_agent`, picked per user by `get_agent_for`)
+  - `bookstack_mcp.py` - BookStack wiki tools (read/create/update, no deletes) via the `bookstack-mcp` npm stdio server; admin-only like Homebox
+  - `mcp_tools.py` - shared allowlist + admin-gate wrapping for stdio MCP integrations
 - `scripts/` - Administrative and utility scripts
   - `add_user.py` - Create users manually
   - `user_message_stats.py` - User message statistics
-  - `manage_vectorstore.py` - Vector store management CLI
-  - `inspect_vector_store.py` - Inspect ChromaDB contents
-  - `query.py` - Query generation utilities
+  - `manage_vectorstore.py` / `inspect_vector_store.py` - Vector store CLI
+  - `index_immich.py` - Index Immich photos into the vector store
+  - `link_imessage.py` - Link iMessage contacts to users
+  - `deploy.sh` - Blue-green deployment script
 - `migrations/` - Database migration files
+- `tests/` - pytest test suite (`tests/unit/` covers email/crypto, YNAB mirror, Obsidian, SimbaKit, rate limiting, user model)
+
+**simbakit/** (standalone subproject):
+- Self-hosted PetKit device poller + web dashboard for Simba's smart devices (feeder, litter box, fountain, purifier)
+- Own `pyproject.toml`, `uv.lock`, and Dockerfile; Python 3.14 + uv
+- Polls PetKit cloud API every 2 min into SQLite; Chart.js dashboard; docs in `simbakit/docs/`
+- Queried from the main app via `utils/simbakit_service.py`
 
 **Frontend** (`raggr-frontend/`):
 - React 19 with Rsbuild bundler
 - Tailwind CSS for styling
 - Built to `dist/`, served by backend at `/`
+- Key components: `ChatScreen`, `ConversationsPage`, `LoginScreen`, `AdminPanel`, `ScheduledMessagesPanel`, `ToolBubble` (agent tool-call display)
 
 **Auth Flow**: LLDAP → Authelia (OIDC) → Backend JWT → Frontend localStorage
 
+**Data Sources**: Paperless-NGX documents, Obsidian vault, Immich photos (indexed via `scripts/index_immich.py` / `make reindex`)
+
 ## Testing
 
 Always run `make test` before pushing code to ensure all tests pass.
@@ -100,12 +128,23 @@ make test       # Run tests
 make test-cov   # Run tests with coverage
 ```
 
+Note: `make test` may fail locally (no pytest on PATH); use `.venv/bin/pytest tests/ -q` instead.
+
+## Git Workflow
+
+- The host runs **Gitea** (`git.torrtle.co`), not GitHub, despite the remote name. Use the **`tea` CLI** for PRs (Gitea flavor: `tea pr create`, `tea pr list`, etc. — no `tea create`).
+- Typical flow: commit locally, `git push -u origin <branch>`, then `tea pr create -t "title" -d "body"`.
+- "kermit" is the user's slang for **commit** (e.g. "kermit and push" = commit and push). There is no kermit tool.
+- Keep one logical change per branch/PR; don't ride along on stale feature branches.
+- Don't commit `.DS_Store`, `chroma_db/`, `chromadb/`, `.planning/` (local artifacts).
+
 ## Key Patterns
 
 - All endpoints are async (`async def`)
 - Use `@jwt_refresh_token_required` for authenticated endpoints
 - Use `@admin_required` for admin-only endpoints (checks `lldap_admin` group)
 - Tortoise ORM models in `blueprints/*/models.py`
+- External integrations are service classes in `utils/*_service.py`
 - Frontend API services in `raggr-frontend/src/api/`
 
 ## Environment Variables
@@ -113,6 +152,15 @@ make test-cov   # Run tests with coverage
 See `.env.example`. Key ones:
 - `DATABASE_URL` - PostgreSQL connection
 - `OIDC_*` - Authelia OIDC configuration
-- `OLLAMA_URL` - Local LLM server
-- `OPENAI_API_KEY` - Fallback LLM
+- `LLAMA_SERVER_URL` / `LLAMA_MODEL_NAME` - Local Llama/Ollama LLM server
+- `EMBEDDING_SERVER_URL` / `EMBEDDING_MODEL_NAME` - Embedding model
+- `OPENAI_API_KEY` - Fallback LLM; `TAVILY_API_KEY` - web search tool
 - `PAPERLESS_TOKEN` / `BASE_URL` - Document source
+- `TWILIO_*`, `ALLOWED_IMESSAGE_NUMBERS`, `ALLOWED_WHATSAPP_NUMBERS` - iMessage/WhatsApp webhooks
+- `MAILGUN_*`, `EMAIL_HMAC_SECRET`, `FERNET_KEY` - email integration
+- `SENDBLUE_*` - SMS sending for scheduled messages
+- `YNAB_*`, `MEALIE_*`, `OBSIDIAN_*`, `IMMICH_*`, `SIMBAKIT_URL`, `HOMEBOX_URL`/`HOMEBOX_TOKEN`, `BOOKSTACK_BASE_URL`/`BOOKSTACK_TOKEN_ID`/`BOOKSTACK_TOKEN_SECRET` - household integrations
+
+## Documentation
+
+Project docs live in `docs/` (mkdocs): `deployment.md`, `development.md`, `authentication.md`, `MIGRATIONS.md`, `VECTORSTORE.md`, `TASKS.md`, `ynab_integration/`.

Dockerfile

@@ -8,13 +8,19 @@ RUN apt-get update && apt-get install -y \
     curl \
     && curl -fsSL https://deb.nodesource.com/setup_22.x | bash - \
     && apt-get install -y nodejs \
-    && npm install -g yarn obsidian-headless \
+    && npm install -g yarn obsidian-headless @googleworkspace/cli \
     && rm -rf /var/lib/apt/lists/* \
     && curl -LsSf https://astral.sh/uv/install.sh | sh
 
 # Add uv to PATH
 ENV PATH="/root/.local/bin:$PATH"
 
+# Homebox MCP server (stdio), pinned so the tool surface can't drift
+RUN uv tool install homebox-mcp==1.1.0
+
+# BookStack MCP server (stdio), pinned for the same reason
+RUN npm install -g bookstack-mcp@5.6.0
+
 # Copy dependency files
 COPY pyproject.toml ./
 
@@ -37,15 +43,14 @@ WORKDIR /app/raggr-frontend
 RUN yarn install && yarn build
 WORKDIR /app
 
-# Create ChromaDB and database directories
-RUN mkdir -p /app/chromadb /app/database
+# Create database directory
+RUN mkdir -p /app/database
 
 # Expose port
 EXPOSE 8080
 
 # Set environment variables
 ENV PYTHONPATH=/app
-ENV CHROMADB_PATH=/app/chromadb
 
 # Run the startup script
 CMD ["./startup.sh"]

Dockerfile.dev

@@ -34,16 +34,15 @@ COPY . .
 WORKDIR /app/raggr-frontend
 RUN yarn build
 
-# Create ChromaDB and database directories
+# Create database directory
 WORKDIR /app
-RUN mkdir -p /app/chromadb /app/database
+RUN mkdir -p /app/database
 
 # Make startup script executable
 RUN chmod +x /app/startup-dev.sh
 
 # Set environment variables
 ENV PYTHONPATH=/app
-ENV CHROMADB_PATH=/app/chromadb
 ENV PYTHONUNBUFFERED=1
 
 # Expose port

Makefile

@@ -1,33 +1,71 @@
-.PHONY: deploy build up down restart logs migrate migrate-new frontend test
+.PHONY: deploy redeploy build up down restart logs migrate migrate-new migrate-history frontend desktop desktop-dev test test-cov reindex reindex-obsidian ynab-sync ynab-resync
+
+# Blue-green: detect the running color (default blue when nothing is running)
+ACTIVE_COLOR := $(shell docker compose ps --status running --services 2>/dev/null | grep -oE 'raggr-(blue|green)' | head -1 | cut -d- -f2)
+ifeq ($(ACTIVE_COLOR),)
+ACTIVE_COLOR := blue
+endif
+RAGGR := raggr-$(ACTIVE_COLOR)
+# Both profiles enabled for commands that only touch existing containers
+# (never use this with `up`, which would start both colors)
+COMPOSE := docker compose --profile blue --profile green
 
 # Build and deploy
 deploy: build up
 
+# Zero-downtime blue-green swap (see scripts/deploy.sh)
+redeploy:
+	git pull && ./scripts/deploy.sh
+
 build:
-	docker compose build raggr
+	docker compose --profile $(ACTIVE_COLOR) build $(RAGGR)
 
 up:
-	docker compose up -d
+	docker compose --profile $(ACTIVE_COLOR) up -d
 
 down:
-	docker compose down
+	$(COMPOSE) down
 
 restart:
-	docker compose restart raggr
+	$(COMPOSE) restart $(RAGGR)
 
 logs:
-	docker compose logs -f raggr
+	$(COMPOSE) logs -f $(RAGGR)
+
+# Vector store reindexing
+reindex:
+	$(COMPOSE) exec $(RAGGR) python -c "\
+		import asyncio; \
+		from blueprints.rag.logic import delete_all_documents, index_documents, index_obsidian_documents; \
+		delete_all_documents(); \
+		asyncio.run(index_documents()); \
+		asyncio.run(index_obsidian_documents()); \
+		print('Reindex complete')"
+
+reindex-obsidian:
+	$(COMPOSE) exec $(RAGGR) python -c "\
+		import asyncio; \
+		from blueprints.rag.logic import delete_documents_by_metadata, index_obsidian_documents; \
+		delete_documents_by_metadata('source', 'obsidian'); \
+		asyncio.run(index_obsidian_documents()); \
+		print('Obsidian reindex complete')"
+
+# YNAB mirror: delta sync, or full re-download
+ynab-sync:
+	$(COMPOSE) exec $(RAGGR) python -m blueprints.ynab
+
+ynab-resync:
+	$(COMPOSE) exec $(RAGGR) python -m blueprints.ynab --full
 
 # Database migrations
 migrate:
-	docker compose exec raggr aerich upgrade
+	$(COMPOSE) exec $(RAGGR) aerich upgrade
 
 migrate-new:
-	@read -p "Migration name: " name; \
-	docker compose exec raggr aerich migrate --name $$name
+	@./scripts/migrate-new.sh
 
 migrate-history:
-	docker compose exec raggr aerich history
+	$(COMPOSE) exec $(RAGGR) aerich history
 
 # Tests
 test:
@@ -39,3 +77,14 @@ test-cov:
 # Frontend
 frontend:
 	cd raggr-frontend && yarn install && yarn build
+
+# Desktop app (Tauri). Point it at the server with SIMBA_URL, e.g.
+#   make desktop-dev SIMBA_URL=https://simba.example.com
+# SIMBA_URL is read at runtime and baked in at build time as the default.
+desktop-dev:
+	cd desktop && npm install && SIMBA_URL=$(SIMBA_URL) npx tauri dev
+
+desktop:
+	cd desktop && npm install && SIMBA_URL=$(SIMBA_URL) npx tauri build --bundles app
+	rm -rf /Applications/Simba.app
+	cp -R desktop/src-tauri/target/release/bundle/macos/Simba.app /Applications/

README.md

@@ -127,8 +127,8 @@ cp .env.example .env
 # Development (local PostgreSQL only)
 docker compose -f docker-compose.dev.yml up -d
 
-# Or full Docker deployment
-docker compose up -d
+# Or full Docker deployment (app runs as raggr-blue; see docs/deployment.md)
+docker compose --profile blue up -d
 ```
 
 4. **Access the application**

STREAMING_IMPLEMENTATION.md

@@ -0,0 +1,79 @@
+# Streaming Implementation Summary
+
+## Overview
+The `/stream-query` endpoint uses Server-Sent Events (SSE) to give real-time feedback
+during AI query processing: tool-execution status **and** token-by-token streaming of the
+assistant's answer.
+
+## Backend (`blueprints/conversation/__init__.py`)
+
+### `POST /api/conversation/stream-query`
+Streams SSE frames (`data: {json}\n\n`) by iterating `main_agent.astream_events(..., version="v2")`.
+Event types emitted to the client:
+
+- `tool_start` — a tool began (`{ "type": "tool_start", "tool": <name> }`), from `on_tool_start`.
+- `tool_end` — a tool finished, from `on_tool_end`.
+- `content` — an incremental answer chunk (`{ "type": "content", "delta": <text> }`), from
+  `on_chat_model_stream`. Chunks are accumulated server-side into `streamed`.
+- `response` — the final, authoritative message (`{ "type": "response", "message": <full text> }`).
+  Sourced from `on_chain_end` (falling back to the accumulated `streamed` tokens). This is the
+  text that is persisted to the DB via `add_message_to_conversation(..., speaker="simba")`.
+- `error` — an error message.
+- The stream terminates with `data: [DONE]`.
+
+The user's message is persisted before streaming begins; the assistant message is persisted once
+the stream completes.
+
+### `POST /api/conversation/query` (legacy, non-streaming)
+Backwards-compatible endpoint that returns the complete response in one JSON payload
+(`{ "response": <text> }`). Kept for compatibility; the frontend uses `/stream-query`.
+
+## Frontend
+
+### API service (`src/api/conversationService.ts`)
+- `streamQuery(query, conversation_id, onEvent, signal?, imageKey?)` — POSTs to `/stream-query`
+  and drives the response through `_readSSEStream()`.
+- `_readSSEStream()` — reads the `ReadableStream`, splits on `\n\n`, parses `data:` frames into
+  `SSEEvent` objects, and stops on `[DONE]`.
+- `SSEEvent` union: `tool_start | tool_end | content | response | error`.
+
+### Chat state (`src/hooks/useChat.ts`)
+`sendMessage()` consumes the stream and maintains a unified `messages` array:
+
+- `tool_start` → appends a `tool` bubble (mapped to a friendly label via `TOOL_MESSAGES`) and
+  resets the streaming pointer so any text after a tool call starts a fresh bubble.
+- `content` → on the first delta, appends a new `simba` bubble and flips `streamingActiveRef` /
+  `streaming`; subsequent deltas append to that bubble's text.
+- `response` → overwrites the live `simba` bubble with the authoritative message (guaranteeing
+  parity with what was persisted), or appends it if nothing streamed (e.g. an instant answer).
+- `error` → surfaces a user-facing error.
+
+A `streaming` boolean is exposed so the UI can hide the redundant loading indicator once tokens
+start arriving.
+
+### Components
+- `ChatScreen.tsx` — renders `messages` (`ToolBubble` / `AnswerBubble` / `QuestionBubble`) and
+  shows the standalone loading-dots `AnswerBubble` only before the first token
+  (`(isLoading && !streaming) || messagesLoading`).
+- `AnswerBubble.tsx` — renders the assistant message as markdown, or animated loading dots when
+  `loading` is set.
+- `ToolBubble.tsx` — renders tool-status messages as inline badges.
+
+## User Experience
+1. User sends a message.
+2. Loading dots appear.
+3. Tool status bubbles appear as tools run (e.g. "Searching Simba's records...").
+4. The answer streams in word-by-word into a single assistant bubble.
+5. On completion the bubble is reconciled with the persisted final text.
+
+## Testing
+```bash
+# Backend
+make test                       # or: .venv/bin/python -m pytest tests/
+
+# Frontend
+cd raggr-frontend && yarn build
+
+# Full stack (manual)
+docker compose up --build
+```

app.py

@@ -1,20 +1,41 @@
+import asyncio
+import hmac
 import logging
 import os
+from datetime import timedelta
 
 from dotenv import load_dotenv
-from quart import Quart, jsonify, render_template, request, send_from_directory
-from quart_jwt_extended import JWTManager, get_jwt_identity, jwt_refresh_token_required
+from quart import (
+    Quart,
+    Response,
+    jsonify,
+    render_template,
+    request,
+    send_from_directory,
+)
+from quart_jwt_extended import JWTManager, get_jwt_identity
 from tortoise import Tortoise
 
+import blueprints.artifacts
 import blueprints.conversation
 import blueprints.conversation.logic
 import blueprints.email
 import blueprints.rag
 import blueprints.users
 import blueprints.whatsapp
+import blueprints.imessage
+import blueprints.scheduled_messages
+import blueprints.cron
+import blueprints.beli
 import blueprints.users.models
+from blueprints.users.decorators import jwt_access_required
 from config.db import TORTOISE_CONFIG
-from main import consult_simba_oracle
+from metrics import render_metrics
+from blueprints.conversation.agents import build_agent
+from blueprints.ynab.sql_tool import ynab_sql
+from blueprints.ynab.sync import ynab_configured, ynab_sync_loop
+from utils.bookstack_mcp import load_bookstack_tools
+from utils.homebox_mcp import load_homebox_tools
 
 # Load environment variables
 load_dotenv()
@@ -27,7 +48,7 @@ logging.basicConfig(
 )
 
 # Ensure YNAB and Mealie loggers are visible
-logging.getLogger("utils.ynab_service").setLevel(logging.INFO)
+logging.getLogger("blueprints.ynab.sync").setLevel(logging.INFO)
 logging.getLogger("utils.mealie_service").setLevel(logging.INFO)
 logging.getLogger("blueprints.conversation.agents").setLevel(logging.INFO)
 
@@ -38,6 +59,8 @@ app = Quart(
 )
 
 app.config["JWT_SECRET_KEY"] = os.getenv("JWT_SECRET_KEY", "SECRET_KEY")
+app.config["JWT_ACCESS_TOKEN_EXPIRES"] = timedelta(hours=1)
+app.config["JWT_REFRESH_TOKEN_EXPIRES"] = timedelta(days=30)
 app.config["MAX_CONTENT_LENGTH"] = 10 * 1024 * 1024  # 10 MB upload limit
 jwt = JWTManager(app)
 
@@ -47,6 +70,32 @@ app.register_blueprint(blueprints.conversation.conversation_blueprint)
 app.register_blueprint(blueprints.email.email_blueprint)
 app.register_blueprint(blueprints.rag.rag_blueprint)
 app.register_blueprint(blueprints.whatsapp.whatsapp_blueprint)
+app.register_blueprint(blueprints.imessage.imessage_blueprint)
+app.register_blueprint(blueprints.scheduled_messages.scheduled_messages_blueprint)
+app.register_blueprint(blueprints.cron.cron_blueprint)
+app.register_blueprint(blueprints.beli.beli_blueprint)
+app.register_blueprint(blueprints.artifacts.artifacts_blueprint)
+
+
+async def _obsidian_sync_loop():
+    """Background task that incrementally syncs Obsidian documents to pgvector."""
+    from blueprints.rag.logic import sync_obsidian_documents
+
+    interval = int(os.getenv("OBSIDIAN_SYNC_INTERVAL", "60"))
+    logger = logging.getLogger("obsidian_sync")
+    logger.info(f"Obsidian sync watcher started (interval={interval}s)")
+
+    while True:
+        try:
+            result = await sync_obsidian_documents()
+            if result["added"] or result["updated"] or result["deleted"]:
+                logger.info(
+                    f"Obsidian sync: {result['added']} added, "
+                    f"{result['updated']} updated, {result['deleted']} deleted"
+                )
+        except Exception:
+            logger.exception("Obsidian sync error")
+        await asyncio.sleep(interval)
 
 
 # Initialize Tortoise ORM with lifecycle hooks
@@ -55,7 +104,38 @@ async def lifespan():
     logging.info("Initializing Tortoise ORM...")
     await Tortoise.init(config=TORTOISE_CONFIG)
     logging.info("Tortoise ORM initialized successfully")
-    yield
+
+    import aiosqlite
+    from langgraph.checkpoint.sqlite.aio import AsyncSqliteSaver
+
+    checkpoint_path = os.getenv("CHECKPOINT_DB_PATH", "/app/checkpoints/checkpoints.db")
+    async with aiosqlite.connect(checkpoint_path) as conn:
+        checkpointer = AsyncSqliteSaver(conn)
+        await checkpointer.setup()
+        app.main_agent = build_agent(checkpointer)
+        admin_tools = await load_homebox_tools() + await load_bookstack_tools()
+        if ynab_configured():
+            admin_tools.append(ynab_sql)
+        app.admin_agent = (
+            build_agent(checkpointer, admin_tools) if admin_tools else app.main_agent
+        )
+        logging.info(f"Agent checkpointer ready at {checkpoint_path}")
+
+        from utils.cronicle import ensure_beli_nightly_event
+
+        await ensure_beli_nightly_event()
+
+        background_tasks = []
+        if os.getenv("OBSIDIAN_CONTINUOUS_SYNC") == "true":
+            background_tasks.append(asyncio.create_task(_obsidian_sync_loop()))
+        if ynab_configured():
+            background_tasks.append(asyncio.create_task(ynab_sync_loop()))
+
+        yield
+
+        for task in background_tasks:
+            task.cancel()
+
     logging.info("Closing Tortoise ORM connections...")
     await Tortoise.close_connections()
 
@@ -66,50 +146,75 @@ async def static_files(filename):
     return await send_from_directory(app.static_folder, filename)
 
 
+# Allowed file extensions for static frontend assets
+ALLOWED_STATIC_EXTENSIONS = {
+    ".html",
+    ".css",
+    ".js",
+    ".svg",
+    ".png",
+    ".ico",
+    ".jpg",
+    ".jpeg",
+    ".webp",
+    ".woff",
+    ".woff2",
+    ".ttf",
+    ".txt",
+}
+
+# JSON files explicitly allowed to be served (e.g. PWA manifest)
+ALLOWED_JSON_FILES = {"manifest.json"}
+
+
+# Prometheus metrics endpoint. Fail-closed: 403 unless a valid bearer token
+# matching METRICS_TOKEN is presented. Registered before the catch-all SPA
+# route so it is never shadowed.
+@app.get("/metrics")
+async def metrics_endpoint():
+    expected = os.environ.get("METRICS_TOKEN", "")
+    if not expected:
+        return "unauthorized", 403
+    auth = request.headers.get("Authorization", "")
+    if not auth.startswith("Bearer "):
+        return "unauthorized", 403
+    provided = auth[len("Bearer ") :].strip()
+    if not hmac.compare_digest(provided.encode(), expected.encode()):
+        return "unauthorized", 403
+    return Response(
+        render_metrics(),
+        status=200,
+        content_type="text/plain; version=0.0.4",
+    )
+
+
 # Serve the React app for all routes (catch-all)
 @app.route("/", defaults={"path": ""})
 @app.route("/<path:path>")
 async def serve_react_app(path):
-    if path and os.path.exists(os.path.join(app.template_folder, path)):
-        return await send_from_directory(app.template_folder, path)
+    if path:
+        ext = os.path.splitext(path)[1].lower()
+        basename = os.path.basename(path)
+        allowed = ext in ALLOWED_STATIC_EXTENSIONS or (
+            ext == ".json" and basename in ALLOWED_JSON_FILES
+        )
+        if allowed and os.path.exists(os.path.join(app.template_folder, path)):
+            return await send_from_directory(app.template_folder, path)
     return await render_template("index.html")
 
 
-@app.route("/api/query", methods=["POST"])
-@jwt_refresh_token_required
-async def query():
-    current_user_uuid = get_jwt_identity()
-    user = await blueprints.users.models.User.get(id=current_user_uuid)
-    data = await request.get_json()
-    query = data.get("query")
-    conversation_id = data.get("conversation_id")
-    conversation = await blueprints.conversation.logic.get_conversation_by_id(
-        conversation_id
-    )
-    await conversation.fetch_related("messages")
-    await blueprints.conversation.logic.add_message_to_conversation(
-        conversation=conversation,
-        message=query,
-        speaker="user",
-        user=user,
-    )
-
-    transcript = await blueprints.conversation.logic.get_conversation_transcript(
-        user=user, conversation=conversation
-    )
-
-    response = consult_simba_oracle(input=query, transcript=transcript)
-    await blueprints.conversation.logic.add_message_to_conversation(
-        conversation=conversation,
-        message=response,
-        speaker="simba",
-        user=user,
-    )
-    return jsonify({"response": response})
+# Health check used by the Docker healthcheck and Caddy's active health checks
+@app.route("/api/health", methods=["GET"])
+async def health():
+    try:
+        await Tortoise.get_connection("default").execute_query("SELECT 1")
+    except Exception:
+        return jsonify({"status": "unhealthy"}), 503
+    return jsonify({"status": "ok"})
 
 
 @app.route("/api/messages", methods=["GET"])
-@jwt_refresh_token_required
+@jwt_access_required
 async def get_messages():
     current_user_uuid = get_jwt_identity()
     user = await blueprints.users.models.User.get(id=current_user_uuid)
@@ -132,17 +237,10 @@ async def get_messages():
             }
         )
 
-    name = conversation.name
-    if len(messages) > 8:
-        name = await blueprints.conversation.logic.rename_conversation(
-            user=user,
-            conversation=conversation,
-        )
-
     return jsonify(
         {
             "id": str(conversation.id),
-            "name": name,
+            "name": conversation.name,
             "messages": messages,
             "created_at": conversation.created_at.isoformat(),
             "updated_at": conversation.updated_at.isoformat(),

blueprints/artifacts/__init__.py

@@ -0,0 +1,56 @@
+import uuid
+
+from quart import Blueprint, jsonify, request
+from quart_jwt_extended import get_jwt_identity
+
+from blueprints.conversation.models import Conversation
+from blueprints.users.decorators import jwt_access_required
+
+from .logic import artifact_full, artifact_summary
+from .models import Artifact
+
+artifacts_blueprint = Blueprint("artifacts_api", __name__, url_prefix="/api/artifacts")
+
+
+def _parse_uuid(value: str) -> uuid.UUID | None:
+    """Validate ids before querying: asyncpg raises OperationalError on bad UUIDs."""
+    try:
+        return uuid.UUID(value)
+    except (ValueError, AttributeError, TypeError):
+        return None
+
+
+@artifacts_blueprint.get("")
+@jwt_access_required
+async def list_artifacts():
+    user_uuid = get_jwt_identity()
+    raw_conversation_id = request.args.get("conversation_id", "").strip()
+    if not raw_conversation_id:
+        return jsonify({"error": "conversation_id is required"}), 400
+    conversation_id = _parse_uuid(raw_conversation_id)
+    if conversation_id is None:
+        return jsonify({"error": "conversation_id must be a UUID"}), 400
+
+    conversation = await Conversation.get_or_none(id=conversation_id, user_id=user_uuid)
+    if conversation is None:
+        return jsonify({"error": "conversation not found"}), 404
+
+    artifacts = await Artifact.filter(
+        conversation_id=conversation.id, user_id=user_uuid
+    ).order_by("created_at")
+    return jsonify([artifact_summary(a) for a in artifacts])
+
+
+@artifacts_blueprint.get("/<artifact_id>")
+@jwt_access_required
+async def get_artifact(artifact_id: str):
+    user_uuid = get_jwt_identity()
+    parsed_id = _parse_uuid(artifact_id)
+    artifact = (
+        await Artifact.get_or_none(id=parsed_id, user_id=user_uuid)
+        if parsed_id is not None
+        else None
+    )
+    if artifact is None:
+        return jsonify({"error": "artifact not found"}), 404
+    return jsonify(artifact_full(artifact))

blueprints/artifacts/logic.py

@@ -0,0 +1,78 @@
+import json
+import logging
+
+from .models import Artifact
+
+logger = logging.getLogger(__name__)
+
+# Artifacts whose serialised `data` exceeds this are dropped (the tool text still persists).
+ARTIFACT_MAX_BYTES = 256 * 1024
+
+
+def artifact_ref(artifact: Artifact) -> dict:
+    """The lightweight reference sent in SSE events and the conversation payload."""
+    return {"id": str(artifact.id), "kind": artifact.kind, "title": artifact.title}
+
+
+def artifact_summary(artifact: Artifact) -> dict:
+    """ArtifactRef plus listing metadata, without `data`."""
+    return {
+        **artifact_ref(artifact),
+        "tool": artifact.tool,
+        "message_id": str(artifact.message_id) if artifact.message_id else None,
+        "created_at": artifact.created_at.isoformat(),
+    }
+
+
+def artifact_full(artifact: Artifact) -> dict:
+    return {
+        **artifact_summary(artifact),
+        "data": artifact.data,
+        "source_ref": artifact.source_ref,
+        "conversation_id": str(artifact.conversation_id),
+    }
+
+
+async def create_artifact_from_output(
+    *, output, tool: str, user, conversation, message=None
+) -> Artifact | None:
+    """Persist `output.artifact` if it is a ToolArtifact dict; otherwise return None.
+
+    Tools opt in via `@tool(response_format="content_and_artifact")`. Artifacts
+    without a `kind` (e.g. simba_search's raw Documents) are ignored, as are
+    ones whose `data` is not JSON-serialisable or over ARTIFACT_MAX_BYTES.
+    """
+    raw = getattr(output, "artifact", None)
+    if not isinstance(raw, dict) or not raw.get("kind"):
+        return None
+
+    data = raw.get("data") or {}
+    source_ref = raw.get("source_ref")
+    try:
+        size = len(json.dumps(data).encode("utf-8"))
+        json.dumps(source_ref)
+    except (TypeError, ValueError) as e:
+        logger.warning(
+            "Dropping %s artifact from %s: not serialisable (%s)", raw["kind"], tool, e
+        )
+        return None
+    if size > ARTIFACT_MAX_BYTES:
+        logger.warning(
+            "Dropping %s artifact from %s: %d bytes exceeds %d",
+            raw["kind"],
+            tool,
+            size,
+            ARTIFACT_MAX_BYTES,
+        )
+        return None
+
+    return await Artifact.create(
+        user=user,
+        conversation=conversation,
+        message=message,
+        tool=tool,
+        kind=str(raw["kind"])[:64],
+        title=str(raw.get("title") or "")[:255],
+        data=data,
+        source_ref=source_ref,
+    )

blueprints/artifacts/models.py

@@ -0,0 +1,29 @@
+from tortoise import fields
+from tortoise.models import Model
+
+
+class Artifact(Model):
+    """A structured tool result (recipe, budget, note…) rendered in the artifact panel."""
+
+    id = fields.UUIDField(primary_key=True)
+    user = fields.ForeignKeyField("models.User", related_name="artifacts")
+    conversation = fields.ForeignKeyField(
+        "models.Conversation", related_name="artifacts", on_delete=fields.CASCADE
+    )
+    message = fields.ForeignKeyField(
+        "models.ConversationMessage",
+        related_name="artifacts",
+        null=True,
+        on_delete=fields.SET_NULL,
+    )
+    tool = fields.CharField(max_length=255)
+    kind = fields.CharField(max_length=64)
+    title = fields.CharField(max_length=255)
+    data = fields.JSONField()
+    source_ref = fields.JSONField(null=True)
+    version = fields.IntField(default=1)
+    created_at = fields.DatetimeField(auto_now_add=True)
+    updated_at = fields.DatetimeField(auto_now=True)
+
+    class Meta:
+        table = "artifacts"

blueprints/beli/__init__.py

@@ -0,0 +1,187 @@
+import hmac
+import logging
+import os
+
+from quart import Blueprint, jsonify, request
+from quart_jwt_extended import get_jwt_identity
+
+from blueprints.users.decorators import jwt_access_required
+
+from .logic import (
+    MAX_PROFILES_PER_USER,
+    _get_access_token,
+    _refresh_friend_sample,
+    refresh_profile,
+    schedule_nightly_refresh,
+)
+from .models import BeliProfile, BeliRestaurant, BeliStatus
+
+beli_blueprint = Blueprint("beli", __name__, url_prefix="/api/beli")
+logger = logging.getLogger(__name__)
+
+
+def _check_cron_secret() -> bool:
+    expected = os.environ.get("CRON_SECRET", "")
+    if not expected:
+        return False
+    provided = request.headers.get("X-Cron-Secret", "")
+    return hmac.compare_digest(provided.encode(), expected.encode())
+
+
+def _serialize_profile(profile: BeliProfile) -> dict:
+    return {
+        "id": str(profile.id),
+        "beli_email": profile.beli_email,
+        "beli_user_id": profile.beli_user_id,
+        "enabled": profile.enabled,
+        "last_refreshed_at": (
+            profile.last_refreshed_at.isoformat() if profile.last_refreshed_at else None
+        ),
+        "last_error": profile.last_error,
+        "created_at": profile.created_at.isoformat(),
+    }
+
+
+def _serialize_restaurant(r: BeliRestaurant) -> dict:
+    return {
+        "id": str(r.id),
+        "profile_id": str(r.profile_id),
+        "beli_business_id": r.beli_business_id,
+        "name": r.name,
+        "city": r.city,
+        "neighborhood": r.neighborhood,
+        "cuisine": r.cuisine,
+        "price_range": r.price_range,
+        "status": r.status.value,
+        "rank_index": r.rank_index,
+        "score": float(r.score) if r.score is not None else None,
+        "notes": r.notes,
+        "tags": r.tags,
+        "fetched_at": r.fetched_at.isoformat(),
+    }
+
+
+@beli_blueprint.route("/profiles", methods=["GET"])
+@jwt_access_required
+async def list_profiles():
+    user_id = get_jwt_identity()
+    profiles = await BeliProfile.filter(user_id=user_id).order_by("created_at").all()
+    return jsonify([_serialize_profile(p) for p in profiles])
+
+
+@beli_blueprint.route("/profiles", methods=["POST"])
+@jwt_access_required
+async def create_profile():
+    user_id = get_jwt_identity()
+
+    count = await BeliProfile.filter(user_id=user_id).count()
+    if count >= MAX_PROFILES_PER_USER:
+        return (
+            jsonify(
+                {"error": f"Maximum {MAX_PROFILES_PER_USER} Beli profiles per user"}
+            ),
+            400,
+        )
+
+    data = await request.get_json()
+    if not data:
+        return jsonify({"error": "Invalid payload"}), 400
+
+    email = (data.get("beli_email") or "").strip()
+    password = (data.get("beli_password") or "").strip()
+    if not email or not password:
+        return jsonify({"error": "beli_email and beli_password are required"}), 400
+
+    if await BeliProfile.exists(user_id=user_id, beli_email=email):
+        return jsonify({"error": "A profile with this email already exists"}), 409
+
+    from utils.beli_service import authenticate
+
+    try:
+        session = await authenticate(email, password)
+    except Exception as e:
+        return jsonify({"error": f"Beli authentication failed: {e}"}), 400
+
+    profile = await BeliProfile.create(
+        user_id=user_id,
+        beli_email=email,
+        beli_password=password,
+        beli_user_id=session["user_id"],
+        beli_refresh_token=session["refresh_token"],
+        enabled=True,
+    )
+    return jsonify(_serialize_profile(profile)), 201
+
+
+@beli_blueprint.route("/profiles/<profile_id>", methods=["DELETE"])
+@jwt_access_required
+async def delete_profile(profile_id: str):
+    user_id = get_jwt_identity()
+    profile = await BeliProfile.get_or_none(id=profile_id, user_id=user_id)
+    if not profile:
+        return jsonify({"error": "Not found"}), 404
+
+    await BeliRestaurant.filter(profile=profile).delete()
+    await profile.delete()
+    return jsonify({"status": "deleted"})
+
+
+@beli_blueprint.route("/profiles/<profile_id>/refresh", methods=["POST"])
+@jwt_access_required
+async def refresh_profile_endpoint(profile_id: str):
+    user_id = get_jwt_identity()
+    profile = await BeliProfile.get_or_none(id=profile_id, user_id=user_id)
+    if not profile:
+        return jsonify({"error": "Not found"}), 404
+
+    result = await refresh_profile(str(profile.id))
+    return jsonify(result)
+
+
+@beli_blueprint.route("/restaurants", methods=["GET"])
+@jwt_access_required
+async def list_restaurants():
+    user_id = get_jwt_identity()
+    profile_ids = [
+        p.id for p in await BeliProfile.filter(user_id=user_id).only("id").all()
+    ]
+
+    qs = BeliRestaurant.filter(profile_id__in=profile_ids)
+
+    status_filter = request.args.get("status")
+    city_filter = request.args.get("city")
+    if status_filter:
+        try:
+            qs = qs.filter(status=BeliStatus(status_filter))
+        except ValueError:
+            return jsonify({"error": f"Invalid status: {status_filter}"}), 400
+    if city_filter:
+        qs = qs.filter(city__icontains=city_filter)
+
+    restaurants = await qs.order_by("rank_index", "name").all()
+    return jsonify([_serialize_restaurant(r) for r in restaurants])
+
+
+@beli_blueprint.route("/profiles/<profile_id>/refresh-friends", methods=["POST"])
+@jwt_access_required
+async def refresh_friends_endpoint(profile_id: str):
+    user_id = get_jwt_identity()
+    profile = await BeliProfile.get_or_none(id=profile_id, user_id=user_id)
+    if not profile:
+        return jsonify({"error": "Not found"}), 404
+
+    try:
+        access_token = await _get_access_token(profile)
+        upserted = await _refresh_friend_sample(profile, access_token)
+        return jsonify({"ok": True, "upserted": upserted})
+    except Exception as e:
+        return jsonify({"error": str(e)}), 500
+
+
+@beli_blueprint.route("/cron/refresh", methods=["POST"])
+async def cron_nightly_refresh():
+    if not _check_cron_secret():
+        return jsonify({"error": "Unauthorized"}), 401
+
+    result = await schedule_nightly_refresh()
+    return jsonify(result)

blueprints/beli/logic.py

@@ -0,0 +1,252 @@
+import asyncio
+import logging
+import random
+from datetime import datetime, timezone
+
+from utils.beli_service import (
+    RANKING_CATEGORIES,
+    REQUEST_SPACING,
+    authenticate,
+    extract_business,
+    fetch_bookmarks,
+    fetch_following,
+    fetch_user_rankings,
+    is_token_expired,
+    refresh_access_token,
+)
+
+from tortoise.functions import Max
+
+from .models import BeliProfile, BeliRestaurant, BeliStatus
+
+logger = logging.getLogger(__name__)
+
+MAX_PROFILES_PER_USER = 3
+NIGHTLY_BATCH_SIZE = 3
+NIGHTLY_WINDOW_SECONDS = 4 * 3600  # spread refreshes across a 4-hour window
+FRIEND_SAMPLE_SIZE = 5  # friends to randomly refresh per profile per night
+
+
+async def _get_access_token(profile: BeliProfile) -> str:
+    """Return a live access token, refreshing or re-authenticating as needed."""
+    if profile.beli_refresh_token and not is_token_expired(profile.beli_refresh_token):
+        try:
+            token = await refresh_access_token(profile.beli_refresh_token)
+            return token
+        except Exception:
+            logger.warning(
+                "Refresh token failed for profile %s, falling back to password",
+                profile.id,
+            )
+
+    session = await authenticate(profile.beli_email, profile.beli_password)
+    profile.beli_user_id = session["user_id"]
+    profile.beli_refresh_token = session["refresh_token"]
+    await profile.save()
+    return session["access_token"]
+
+
+async def _refresh_friend_sample(profile: BeliProfile, access_token: str) -> int:
+    """Fetch rankings for a random sample of followed users and upsert them."""
+    try:
+        following = await fetch_following(access_token, profile.beli_user_id)
+    except Exception as e:
+        logger.debug("Beli following fetch skipped for profile %s: %s", profile.id, e)
+        return 0
+
+    if not following:
+        return 0
+
+    # Pick the FRIEND_SAMPLE_SIZE stalest friends — never-fetched first, then oldest
+    fetched_rows = (
+        await BeliRestaurant.filter(profile=profile)
+        .exclude(friend_beli_user_id="")
+        .group_by("friend_beli_user_id")
+        .annotate(last_fetched=Max("fetched_at"))
+        .values("friend_beli_user_id", "last_fetched")
+    )
+    last_fetched: dict[str, datetime] = {
+        r["friend_beli_user_id"]: r["last_fetched"] for r in fetched_rows
+    }
+    _epoch = datetime.fromtimestamp(0, tz=timezone.utc)
+    sample = sorted(
+        following,
+        key=lambda f: last_fetched.get(str(f.get("id") or ""), _epoch),
+    )[:FRIEND_SAMPLE_SIZE]
+    upserted = 0
+
+    for friend in sample:
+        friend_id = str(friend.get("id") or "")
+        friend_name = friend.get("full_name") or friend.get("username") or friend_id
+        if not friend_id:
+            continue
+
+        for category in RANKING_CATEGORIES:
+            await asyncio.sleep(REQUEST_SPACING)
+            try:
+                results = await fetch_user_rankings(access_token, friend_id, category)
+            except Exception as e:
+                # 405 = private profile; log quietly and skip
+                logger.debug(
+                    "Beli friend ranking skipped (%s/%s): %s", friend_id, category, e
+                )
+                continue
+
+            for idx, item in enumerate(results):
+                biz = extract_business(item, rank_index=idx + 1)
+                if not biz:
+                    continue
+                await BeliRestaurant.update_or_create(
+                    profile=profile,
+                    beli_business_id=biz["beli_business_id"],
+                    status=BeliStatus.BEEN,
+                    friend_beli_user_id=friend_id,
+                    beli_category=category,
+                    defaults={
+                        "friend_name": friend_name,
+                        "name": biz["name"],
+                        "city": biz["city"],
+                        "neighborhood": biz["neighborhood"],
+                        "cuisine": biz["cuisine"],
+                        "price_range": biz["price_range"],
+                        "rank_index": biz["rank_index"],
+                        "score": biz["score"],
+                        "notes": None,
+                        "tags": biz["tags"],
+                    },
+                )
+                upserted += 1
+
+    if upserted:
+        logger.info(
+            "Beli profile %s: %d friend restaurants upserted from %d friends",
+            profile.id,
+            upserted,
+            len(sample),
+        )
+    return upserted
+
+
+async def refresh_profile(profile_id: str) -> dict:
+    """Fetch the latest rankings and bookmarks for a profile and upsert them."""
+    profile = await BeliProfile.get_or_none(id=profile_id)
+    if not profile or not profile.enabled:
+        return {"skipped": True}
+
+    try:
+        access_token = await _get_access_token(profile)
+
+        upserted = 0
+
+        # Fetch all ranking categories (restaurants the user has been to and ranked)
+        for category in RANKING_CATEGORIES:
+            await asyncio.sleep(REQUEST_SPACING)
+            results = await fetch_user_rankings(
+                access_token, profile.beli_user_id, category
+            )
+            for idx, item in enumerate(results):
+                biz = extract_business(item, rank_index=idx + 1)
+                if not biz:
+                    continue
+                await BeliRestaurant.update_or_create(
+                    profile=profile,
+                    beli_business_id=biz["beli_business_id"],
+                    status=BeliStatus.BEEN,
+                    friend_beli_user_id="",
+                    beli_category=category,
+                    defaults={
+                        "name": biz["name"],
+                        "city": biz["city"],
+                        "neighborhood": biz["neighborhood"],
+                        "cuisine": biz["cuisine"],
+                        "price_range": biz["price_range"],
+                        "rank_index": biz["rank_index"],
+                        "score": biz["score"],
+                        "notes": biz["notes"],
+                        "tags": biz["tags"],
+                    },
+                )
+                upserted += 1
+
+        # Fetch bookmarks (want-to-try list) — non-fatal if unavailable
+        await asyncio.sleep(REQUEST_SPACING)
+        try:
+            bookmarks = await fetch_bookmarks(access_token)
+        except Exception as e:
+            logger.warning(
+                "Beli bookmarks fetch failed for profile %s: %s", profile_id, e
+            )
+            bookmarks = []
+        for item in bookmarks:
+            biz = extract_business(item)
+            if not biz:
+                continue
+            await BeliRestaurant.update_or_create(
+                profile=profile,
+                beli_business_id=biz["beli_business_id"],
+                status=BeliStatus.WANT_TO_TRY,
+                friend_beli_user_id="",
+                beli_category="",
+                defaults={
+                    "name": biz["name"],
+                    "city": biz["city"],
+                    "neighborhood": biz["neighborhood"],
+                    "cuisine": biz["cuisine"],
+                    "price_range": biz["price_range"],
+                    "rank_index": None,
+                    "score": None,
+                    "notes": biz["notes"],
+                    "tags": biz["tags"],
+                },
+            )
+            upserted += 1
+
+        profile.last_refreshed_at = datetime.now(timezone.utc)
+        profile.last_error = None
+        await profile.save()
+
+        logger.info(
+            "Beli profile %s refreshed: %d restaurants upserted", profile_id, upserted
+        )
+        return {"ok": True, "upserted": upserted}
+
+    except Exception as e:
+        profile.last_error = str(e)
+        await profile.save()
+        logger.error("Failed to refresh Beli profile %s: %s", profile_id, e)
+        return {"error": str(e)}
+
+
+async def _refresh_after_delay(profile_id: str, delay: float) -> None:
+    await asyncio.sleep(delay)
+    profile = await BeliProfile.get_or_none(id=profile_id)
+    if not profile:
+        return
+    await refresh_profile(profile_id)
+    # Friend sampling only runs during nightly scheduled refreshes, not manual ones
+    try:
+        access_token = await _get_access_token(profile)
+        await _refresh_friend_sample(profile, access_token)
+    except Exception as e:
+        logger.warning("Friend sample failed for profile %s: %s", profile_id, e)
+
+
+async def schedule_nightly_refresh() -> dict:
+    """Pick the NIGHTLY_BATCH_SIZE stalest profiles and schedule them with random delays."""
+    profiles = (
+        await BeliProfile.filter(enabled=True)
+        .order_by("last_refreshed_at")
+        .limit(NIGHTLY_BATCH_SIZE)
+        .all()
+    )
+
+    if not profiles:
+        logger.info("No enabled Beli profiles to refresh")
+        return {"scheduled": 0}
+
+    for profile in profiles:
+        delay = random.uniform(0, NIGHTLY_WINDOW_SECONDS)
+        asyncio.create_task(_refresh_after_delay(str(profile.id), delay))
+        logger.info("Scheduled Beli refresh for profile %s in %.0fs", profile.id, delay)
+
+    return {"scheduled": len(profiles)}

blueprints/beli/models.py

@@ -0,0 +1,66 @@
+import enum
+import uuid
+
+from tortoise import fields
+from tortoise.models import Model
+
+from blueprints.email.crypto_service import EncryptedTextField
+
+
+class BeliStatus(str, enum.Enum):
+    BEEN = "been"
+    WANT_TO_TRY = "want_to_try"
+
+
+class BeliProfile(Model):
+    id = fields.UUIDField(primary_key=True, default=uuid.uuid4)
+    user = fields.ForeignKeyField("models.User", related_name="beli_profiles")
+    beli_email = fields.CharField(max_length=255)
+    beli_password = EncryptedTextField()
+    beli_user_id = fields.CharField(max_length=255, null=True)
+    # refresh token lasts 7 days; we store it encrypted to avoid re-authenticating each run
+    beli_refresh_token = EncryptedTextField(null=True)
+    last_refreshed_at = fields.DatetimeField(null=True)
+    last_error = fields.TextField(null=True)
+    enabled = fields.BooleanField(default=True)
+    created_at = fields.DatetimeField(auto_now_add=True)
+    updated_at = fields.DatetimeField(auto_now=True)
+
+    class Meta:
+        table = "beli_profiles"
+        unique_together = (("user", "beli_email"),)
+
+
+class BeliRestaurant(Model):
+    id = fields.UUIDField(primary_key=True, default=uuid.uuid4)
+    profile = fields.ForeignKeyField("models.BeliProfile", related_name="restaurants")
+    beli_business_id = fields.CharField(max_length=255)
+    # Empty string = profile owner's own ranking; UUID string = a followed user's ranking
+    friend_beli_user_id = fields.CharField(max_length=255, default="")
+    friend_name = fields.CharField(max_length=255, null=True)
+    # Beli category code: RES / DES / BAR / BAK; empty for bookmarks
+    beli_category = fields.CharField(max_length=10, default="")
+    name = fields.CharField(max_length=500)
+    city = fields.CharField(max_length=255, null=True)
+    neighborhood = fields.CharField(max_length=255, null=True)
+    cuisine = fields.JSONField(default=list)
+    price_range = fields.CharField(max_length=10, null=True)
+    status = fields.CharEnumField(enum_type=BeliStatus, max_length=20)
+    rank_index = fields.IntField(null=True)
+    score = fields.DecimalField(max_digits=5, decimal_places=2, null=True)
+    notes = fields.TextField(null=True)
+    tags = fields.JSONField(default=list)
+    fetched_at = fields.DatetimeField(auto_now=True)
+    created_at = fields.DatetimeField(auto_now_add=True)
+
+    class Meta:
+        table = "beli_restaurants"
+        unique_together = (
+            (
+                "profile",
+                "beli_business_id",
+                "status",
+                "friend_beli_user_id",
+                "beli_category",
+            ),
+        )

blueprints/conversation/__init__.py

@@ -1,78 +1,143 @@
-import datetime
+import asyncio
 import json
 import logging
+import os
+import re
+import time
 import uuid
 
 from quart import Blueprint, jsonify, make_response, request
-from quart_jwt_extended import (
-    get_jwt_identity,
-    jwt_refresh_token_required,
-)
+from quart_jwt_extended import get_jwt_identity
 
 import blueprints.users.models
-from utils.image_process import analyze_user_image
+from blueprints.artifacts.logic import artifact_ref, create_artifact_from_output
+from blueprints.artifacts.models import Artifact
+from blueprints.users.decorators import jwt_access_required
+from metrics import count_result, observe_response, time_response
+from utils.image_process import image_content_block
+from utils.strip_markdown import extract_agent_text
 from utils.image_upload import ImageValidationError, process_image
 from utils.s3_client import generate_presigned_url as s3_presigned_url
 from utils.s3_client import get_image as s3_get_image
 from utils.s3_client import upload_image as s3_upload_image
 
-from .agents import main_agent
 from .logic import (
     add_message_to_conversation,
-    get_conversation_by_id,
-    rename_conversation,
+    get_agent_for,
+    persist_agent_tool_messages,
+    tool_result_text,
 )
+from .memory import build_system_prompt_with_memories
 from .models import (
     Conversation,
     PydConversation,
     PydListConversation,
+    Speaker,
 )
-from .prompts import SIMBA_SYSTEM_PROMPT
+from .tool_events import tool_end_payload, tool_name_from_message, tool_start_payload
+from .tool_labels import tool_label
+
+TTFT_TIMEOUT = float(os.getenv("TTFT_TIMEOUT_SECONDS", "30"))
+
+_THINK_OPEN = "<think>"
+_THINK_CLOSE = "</think>"
+_THINK_RE = re.compile(r"<think>.*?</think>", re.DOTALL)
+
+
+def _route_content(
+    buf: str, text: str, in_thinking: bool
+) -> tuple[str, str, bool, str]:
+    """Split a streaming content chunk into (thinking_text, content_text).
+
+    Handles tags split across chunk boundaries by keeping a small trailing
+    buffer. Returns the updated in_thinking state and any leftover buffer.
+    """
+    combined = buf + text
+    thinking_parts: list[str] = []
+    content_parts: list[str] = []
+
+    while combined:
+        tag, hold = (
+            (_THINK_CLOSE, len(_THINK_CLOSE) - 1)
+            if in_thinking
+            else (_THINK_OPEN, len(_THINK_OPEN) - 1)
+        )
+        idx = combined.find(tag)
+        if idx == -1:
+            # Tag not yet complete — hold back enough bytes to catch a split.
+            if len(combined) <= hold:
+                return (
+                    "".join(thinking_parts),
+                    "".join(content_parts),
+                    in_thinking,
+                    combined,
+                )
+            safe, leftover = combined[:-hold], combined[-hold:]
+            (thinking_parts if in_thinking else content_parts).append(safe)
+            return (
+                "".join(thinking_parts),
+                "".join(content_parts),
+                in_thinking,
+                leftover,
+            )
+        (thinking_parts if in_thinking else content_parts).append(combined[:idx])
+        combined = combined[idx + len(tag) :]
+        in_thinking = not in_thinking
+
+    return "".join(thinking_parts), "".join(content_parts), in_thinking, ""
+
 
 conversation_blueprint = Blueprint(
     "conversation_api", __name__, url_prefix="/api/conversation"
 )
 
-_SYSTEM_PROMPT = SIMBA_SYSTEM_PROMPT
+# Detached persistence tasks. A strong reference keeps them from being garbage
+# collected mid-flight when the SSE stream is cancelled by a client disconnect.
+_persist_tasks: set[asyncio.Task] = set()
 
 
-def _build_messages_payload(
-    conversation, query_text: str, image_description: str | None = None
-) -> list:
-    recent_messages = (
-        conversation.messages[-10:]
-        if len(conversation.messages) > 10
-        else conversation.messages
-    )
-    messages_payload = [{"role": "system", "content": _SYSTEM_PROMPT}]
-    for msg in recent_messages[:-1]:  # Exclude the message we just added
-        role = "user" if msg.speaker == "user" else "assistant"
-        text = msg.text
-        if msg.image_key and role == "user":
-            text = f"[User sent an image]\n{text}"
-        messages_payload.append({"role": role, "content": text})
+def _persist_in_background(coro) -> asyncio.Task:
+    task = asyncio.create_task(coro)
+    _persist_tasks.add(task)
+    task.add_done_callback(_persist_tasks.discard)
+    return task
 
-    # Build the current user message with optional image description
-    if image_description:
-        content = f"[Image analysis: {image_description}]"
-        if query_text:
-            content = f"{query_text}\n\n{content}"
+
+async def _get_owned_conversation(conversation_id, user_id) -> Conversation | None:
+    """Fetch a conversation only if it belongs to the given user."""
+    return await Conversation.get_or_none(id=conversation_id, user_id=user_id)
+
+
+def _build_user_message(
+    query_text: str,
+    image_block: dict | None = None,
+) -> dict:
+    """Build the single new user message for this turn.
+
+    History is restored by the LangGraph checkpointer; only the current
+    message is passed to avoid duplicating prior turns in checkpoint state.
+    """
+    if image_block:
+        content = [
+            {"type": "text", "text": query_text or "The user sent this image."},
+            image_block,
+        ]
     else:
         content = query_text
-    messages_payload.append({"role": "user", "content": content})
-    return messages_payload
+    return {"role": "user", "content": content}
 
 
 @conversation_blueprint.post("/query")
-@jwt_refresh_token_required
+@jwt_access_required
 async def query():
     current_user_uuid = get_jwt_identity()
     user = await blueprints.users.models.User.get(id=current_user_uuid)
     data = await request.get_json()
     query = data.get("query")
     conversation_id = data.get("conversation_id")
-    conversation = await get_conversation_by_id(conversation_id)
-    await conversation.fetch_related("messages")
+    conversation = await _get_owned_conversation(conversation_id, current_user_uuid)
+    if conversation is None:
+        return jsonify({"error": "conversation not found"}), 404
     await add_message_to_conversation(
         conversation=conversation,
         message=query,
@@ -80,22 +145,34 @@ async def query():
         user=user,
     )
 
-    messages_payload = _build_messages_payload(conversation, query)
-    payload = {"messages": messages_payload}
+    with time_response(stream=False):
+        system_prompt = await build_system_prompt_with_memories(str(user.id))
+        payload = {"messages": [_build_user_message(query)]}
+        agent_config = {
+            "configurable": {
+                "user_id": str(user.id),
+                "is_admin": user.is_admin(),
+                "thread_id": str(conversation.id),
+                "system_prompt": system_prompt,
+            }
+        }
 
-    response = await main_agent.ainvoke(payload)
-    message = response.get("messages", [])[-1].content
-    await add_message_to_conversation(
-        conversation=conversation,
-        message=message,
-        speaker="simba",
-        user=user,
-    )
-    return jsonify({"response": message})
+        response = await get_agent_for(user).ainvoke(payload, config=agent_config)
+        message = extract_agent_text(response.get("messages", [])[-1].content)
+        await persist_agent_tool_messages(
+            conversation, user, response.get("messages", [])
+        )
+        await add_message_to_conversation(
+            conversation=conversation,
+            message=message,
+            speaker="simba",
+            user=user,
+        )
+        return jsonify({"response": message})
 
 
 @conversation_blueprint.post("/upload-image")
-@jwt_refresh_token_required
+@jwt_access_required
 async def upload_image():
     current_user_uuid = get_jwt_identity()
     await blueprints.users.models.User.get(id=current_user_uuid)
@@ -127,14 +204,14 @@ async def upload_image():
 
 
 @conversation_blueprint.get("/image/<path:image_key>")
-@jwt_refresh_token_required
+@jwt_access_required
 async def serve_image(image_key: str):
     url = await s3_presigned_url(image_key)
     return jsonify({"url": url})
 
 
 @conversation_blueprint.post("/stream-query")
-@jwt_refresh_token_required
+@jwt_access_required
 async def stream_query():
     current_user_uuid = get_jwt_identity()
     user = await blueprints.users.models.User.get(id=current_user_uuid)
@@ -142,8 +219,9 @@ async def stream_query():
     query_text = data.get("query")
     conversation_id = data.get("conversation_id")
     image_key = data.get("image_key")
-    conversation = await get_conversation_by_id(conversation_id)
-    await conversation.fetch_related("messages")
+    conversation = await _get_owned_conversation(conversation_id, current_user_uuid)
+    if conversation is None:
+        return jsonify({"error": "conversation not found"}), 404
     await add_message_to_conversation(
         conversation=conversation,
         message=query_text or "",
@@ -152,33 +230,194 @@ async def stream_query():
         image_key=image_key,
     )
 
-    # If an image was uploaded, analyze it with the vision model
-    image_description = None
+    # If an image was uploaded, attach it to the agent request directly
+    image_block = None
     if image_key:
         try:
             image_bytes, _ = await s3_get_image(image_key)
-            image_description = await analyze_user_image(image_bytes)
-            logging.info(f"Image analysis complete for {image_key}")
+            image_block = image_content_block(image_bytes)
         except Exception as e:
-            logging.error(f"Failed to analyze image: {e}")
-            image_description = "[Image could not be analyzed]"
+            logging.error(f"Failed to load image {image_key}: {e}")
+            query_text = f"{query_text or ''}\n\n[An image was sent but could not be loaded.]".strip()
 
-    messages_payload = _build_messages_payload(
-        conversation, query_text or "", image_description
-    )
-    payload = {"messages": messages_payload}
+    system_prompt = await build_system_prompt_with_memories(str(user.id))
+    payload = {"messages": [_build_user_message(query_text or "", image_block)]}
+    agent_config = {
+        "configurable": {
+            "user_id": str(user.id),
+            "is_admin": user.is_admin(),
+            "thread_id": str(conversation.id),
+            "system_prompt": system_prompt,
+        }
+    }
+    # Capture the agent reference while the request/app context is still active.
+    # Quart exits the app context before iterating the SSE response body, so
+    # current_app cannot be accessed inside event_generator().
+    main_agent = get_agent_for(user)
 
     async def event_generator():
         final_message = None
+        streamed = ""
+        # Tag-routing state for <think>…</think> blocks.
+        in_thinking = False
+        tag_buf = ""
+        # Fallback heartbeat for models that emit empty chunks before thinking text.
+        last_thinking = 0.0
+        turn_has_content = False
+
+        # Timing / observability
+        t0 = time.monotonic()
+        llm_start_at: float | None = None
+        first_content_at: float | None = None
+        tool_timers: dict[str, float] = {}  # run_id -> start time
+        tool_spans: list[dict] = []
+        n_tokens = 0
+        model_name: str | None = None
+        cancelled = False
+
+        async def persist(text: str) -> None:
+            await add_message_to_conversation(
+                conversation=conversation,
+                message=text,
+                speaker="simba",
+                user=user,
+            )
+
+        def _log_summary(*, error: str | None = None) -> None:
+            now = time.monotonic()
+            thinking_ms = (
+                round((first_content_at - llm_start_at) * 1000)
+                if llm_start_at and first_content_at
+                else None
+            )
+            ttft_ms = (
+                round((first_content_at - t0) * 1000) if first_content_at else None
+            )
+            logging.info(
+                json.dumps(
+                    {
+                        "event": "stream_request",
+                        "conv": str(conversation.id),
+                        "user": user.username,
+                        "total_ms": round((now - t0) * 1000),
+                        "thinking_ms": thinking_ms,
+                        "ttft_ms": ttft_ms,
+                        "tokens": n_tokens,
+                        "tools": tool_spans,
+                        "model": model_name,
+                        "cancelled": cancelled,
+                        **({"error": error} if error else {}),
+                    }
+                )
+            )
+
         try:
-            async for event in main_agent.astream_events(payload, version="v2"):
+            aiter = main_agent.astream_events(
+                payload, version="v2", config=agent_config
+            ).__aiter__()
+            while True:
+                # Apply a short TTFT timeout only during the window between
+                # on_chat_model_start and the first content token. Before the
+                # LLM call starts (tool phase) and after the first token, let
+                # the httpx read timeout handle stalls instead.
+                if llm_start_at is not None and first_content_at is None:
+                    ttft_wait = TTFT_TIMEOUT - (time.monotonic() - llm_start_at)
+                    timeout = max(ttft_wait, 1.0)
+                else:
+                    timeout = None
+
+                try:
+                    if timeout is not None:
+                        event = await asyncio.wait_for(
+                            aiter.__anext__(), timeout=timeout
+                        )
+                    else:
+                        event = await aiter.__anext__()
+                except StopAsyncIteration:
+                    break
+                except asyncio.TimeoutError:
+                    _log_summary(error=f"TTFT timeout after {TTFT_TIMEOUT:.0f}s")
+                    yield f"data: {json.dumps({'type': 'error', 'message': 'Simba took too long to respond. Please try again.', 'stalled': True})}\n\n"
+                    return
+
                 event_type = event.get("event")
 
                 if event_type == "on_tool_start":
-                    yield f"data: {json.dumps({'type': 'tool_start', 'tool': event['name']})}\n\n"
+                    tool_timers[event["run_id"]] = time.monotonic()
+                    yield f"data: {json.dumps(tool_start_payload(event))}\n\n"
 
-                elif event_type == "on_tool_end":
-                    yield f"data: {json.dumps({'type': 'tool_end', 'tool': event['name']})}\n\n"
+                elif event_type in ("on_tool_end", "on_tool_error"):
+                    now = time.monotonic()
+                    start = tool_timers.pop(event["run_id"], None)
+                    tool_spans.append(
+                        {
+                            "tool": event["name"],
+                            "ms": round((now - start) * 1000) if start else None,
+                        }
+                    )
+                    ref = None
+                    # Persist tool output so later turns keep the fetched context
+                    output = event.get("data", {}).get("output")
+                    if event_type == "on_tool_end" and output is not None:
+                        tool_message = await add_message_to_conversation(
+                            conversation=conversation,
+                            message=tool_result_text(event["name"], output),
+                            speaker="tool",
+                            user=user,
+                        )
+                        try:
+                            artifact = await create_artifact_from_output(
+                                output=output,
+                                tool=event["name"],
+                                user=user,
+                                conversation=conversation,
+                                message=tool_message,
+                            )
+                        except Exception as e:
+                            logging.error(
+                                f"Failed to save artifact from {event['name']}: {e}"
+                            )
+                            artifact = None
+                        if artifact is not None:
+                            ref = artifact_ref(artifact)
+                    status = "error" if event_type == "on_tool_error" else "ok"
+                    end_payload = tool_end_payload(
+                        event, start, ref, now=now, status=status
+                    )
+                    yield f"data: {json.dumps(end_payload)}\n\n"
+
+                elif event_type == "on_chat_model_start":
+                    turn_has_content = False
+                    if llm_start_at is None:
+                        llm_start_at = time.monotonic()
+                    if model_name is None:
+                        model_name = event.get("metadata", {}).get(
+                            "ls_model_name"
+                        ) or event.get("name")
+
+                elif event_type == "on_chat_model_stream":
+                    chunk = event.get("data", {}).get("chunk")
+                    raw = getattr(chunk, "content", None)
+                    if isinstance(raw, str) and raw:
+                        think_text, content_text, in_thinking, tag_buf = _route_content(
+                            tag_buf, raw, in_thinking
+                        )
+                        if think_text:
+                            yield f"data: {json.dumps({'type': 'thinking_delta', 'delta': think_text})}\n\n"
+                        if content_text:
+                            if first_content_at is None:
+                                first_content_at = time.monotonic()
+                            turn_has_content = True
+                            n_tokens += 1
+                            streamed += content_text
+                            yield f"data: {json.dumps({'type': 'content', 'delta': content_text})}\n\n"
+                    elif not turn_has_content:
+                        # Empty chunk before any content — heartbeat for models
+                        # that don't emit <think> tags at all.
+                        now = time.monotonic()
+                        if now - last_thinking >= 1.0:
+                            last_thinking = now
+                            yield f"data: {json.dumps({'type': 'thinking'})}\n\n"
 
                 elif event_type == "on_chain_end":
                     output = event.get("data", {}).get("output")
@@ -188,22 +427,34 @@ async def stream_query():
                             last_msg = msgs[-1]
                             content = getattr(last_msg, "content", None)
                             if isinstance(content, str) and content:
-                                final_message = content
+                                final_message = _THINK_RE.sub("", content).strip()
 
+        except asyncio.CancelledError:
+            cancelled = True
+            _log_summary()
+            text = final_message or streamed
+            if text:
+                _persist_in_background(persist(text))
+            raise
         except Exception as e:
+            count_result(stream=True, result="error")
+            _log_summary(error=str(e))
             yield f"data: {json.dumps({'type': 'error', 'message': str(e)})}\n\n"
+            return
 
+        final_message = final_message or streamed
         if final_message:
-            await add_message_to_conversation(
-                conversation=conversation,
-                message=final_message,
-                speaker="simba",
-                user=user,
-            )
+            # Persist via a detached, shielded task so a disconnect at this
+            # point (after generation completes) still commits the answer.
+            task = _persist_in_background(persist(final_message))
+            await asyncio.shield(task)
             yield f"data: {json.dumps({'type': 'response', 'message': final_message})}\n\n"
         else:
             yield f"data: {json.dumps({'type': 'error', 'message': 'No response generated'})}\n\n"
 
+        observe_response(stream=True, seconds=time.monotonic() - t0)
+        count_result(stream=True, result="success")
+        _log_summary()
         yield "data: [DONE]\n\n"
 
     return await make_response(
@@ -218,37 +469,45 @@ async def stream_query():
 
 
 @conversation_blueprint.route("/<conversation_id>")
-@jwt_refresh_token_required
+@jwt_access_required
 async def get_conversation(conversation_id: str):
-    conversation = await Conversation.get(id=conversation_id)
-    current_user_uuid = get_jwt_identity()
-    user = await blueprints.users.models.User.get(id=current_user_uuid)
+    user_uuid = get_jwt_identity()
+    conversation = await _get_owned_conversation(conversation_id, user_uuid)
+    if conversation is None:
+        return jsonify({"error": "conversation not found"}), 404
     await conversation.fetch_related("messages")
+    # Keyed by str so the match doesn't depend on the driver's UUID types.
+    artifacts_by_message = {
+        str(a.message_id): a
+        for a in await Artifact.filter(
+            conversation_id=conversation.id, message_id__isnull=False
+        ).order_by("created_at")
+    }
 
     # Manually serialize the conversation with messages
     messages = []
     for msg in conversation.messages:
-        messages.append(
-            {
-                "id": str(msg.id),
-                "text": msg.text,
-                "speaker": msg.speaker.value,
-                "created_at": msg.created_at.isoformat(),
-                "image_key": msg.image_key,
-            }
-        )
-    name = conversation.name
-    if len(messages) > 8 and "datetime" in name.lower():
-        name = await rename_conversation(
-            user=user,
-            conversation=conversation,
-        )
-        print(name)
-
+        item = {
+            "id": str(msg.id),
+            "text": msg.text,
+            "speaker": msg.speaker.value,
+            "created_at": msg.created_at.isoformat(),
+            "image_key": msg.image_key,
+        }
+        if msg.speaker == Speaker.TOOL:
+            # Tool messages hold raw fetched context for the LLM; only surface
+            # their header line (e.g. "[web_search result]") in the UI.
+            item["text"] = msg.text.split("\n", 1)[0]
+            tool = tool_name_from_message(msg.text)
+            artifact = artifacts_by_message.get(str(msg.id))
+            item["tool"] = tool
+            item["label"] = tool_label(tool)
+            item["artifact"] = artifact_ref(artifact) if artifact else None
+        messages.append(item)
     return jsonify(
         {
             "id": str(conversation.id),
-            "name": name,
+            "name": conversation.name,
             "messages": messages,
             "created_at": conversation.created_at.isoformat(),
             "updated_at": conversation.updated_at.isoformat(),
@@ -257,12 +516,12 @@ async def get_conversation(conversation_id: str):
 
 
 @conversation_blueprint.post("/")
-@jwt_refresh_token_required
+@jwt_access_required
 async def create_conversation():
     user_uuid = get_jwt_identity()
     user = await blueprints.users.models.User.get(id=user_uuid)
     conversation = await Conversation.create(
-        name=f"{user.username} {datetime.datetime.now().timestamp}",
+        name="New Conversation",
         user=user,
     )
 
@@ -271,11 +530,58 @@ async def create_conversation():
 
 
 @conversation_blueprint.get("/")
-@jwt_refresh_token_required
+@jwt_access_required
 async def get_all_conversations():
     user_uuid = get_jwt_identity()
     user = await blueprints.users.models.User.get(id=user_uuid)
-    conversations = Conversation.filter(user=user)
-    serialized_conversations = await PydListConversation.from_queryset(conversations)
+
+    query = Conversation.filter(user=user)
+
+    search = request.args.get("search", "").strip()
+    if search:
+        query = query.filter(name__icontains=search)
+
+    query = query.order_by("-updated_at")
+
+    # `limit` is optional: when omitted we return the full list (backward
+    # compatible with any non-frontend callers). `offset` only applies with it.
+    limit = request.args.get("limit", type=int)
+    if limit is not None:
+        offset = request.args.get("offset", default=0, type=int)
+        query = query.offset(offset).limit(limit)
+
+    serialized_conversations = await PydListConversation.from_queryset(query)
 
     return jsonify(serialized_conversations.model_dump())
+
+
+@conversation_blueprint.patch("/<conversation_id>")
+@jwt_access_required
+async def rename_conversation(conversation_id: str):
+    user_uuid = get_jwt_identity()
+    body = await request.get_json()
+    name = (body or {}).get("name", "").strip()
+    if not name:
+        return jsonify({"error": "name is required"}), 400
+
+    conversation = await _get_owned_conversation(conversation_id, user_uuid)
+    if conversation is None:
+        return jsonify({"error": "conversation not found"}), 404
+
+    conversation.name = name[:255]
+    await conversation.save()
+
+    serialized_conversation = await PydConversation.from_tortoise_orm(conversation)
+    return jsonify(serialized_conversation.model_dump())
+
+
+@conversation_blueprint.delete("/<conversation_id>")
+@jwt_access_required
+async def delete_conversation(conversation_id: str):
+    user_uuid = get_jwt_identity()
+    conversation = await _get_owned_conversation(conversation_id, user_uuid)
+    if conversation is None:
+        return jsonify({"error": "conversation not found"}), 404
+
+    await conversation.delete()
+    return jsonify({"success": True})

blueprints/conversation/artifacts_util.py

@@ -0,0 +1,178 @@
+"""Helpers for building ToolArtifact dicts returned by agent tools.
+
+See docs/cowork-ui-plan.md ("Artifacts") for the contract. Artifacts must be
+plain JSON-serialisable dicts: they ride along in ToolMessage.artifact and are
+stored in the LangGraph checkpoint.
+"""
+
+import os
+from datetime import date, datetime
+from decimal import Decimal
+from pathlib import Path
+from urllib.parse import quote, urlencode
+
+SNIPPET_MAX_CHARS = 400
+NOTE_MAX_CHARS = 50_000
+ELLIPSIS = "…"
+
+
+def make_artifact(
+    kind: str, title: str, data: dict, source_ref: dict | None = None
+) -> dict:
+    artifact = {"kind": kind, "title": title, "data": data}
+    if source_ref:
+        artifact["source_ref"] = source_ref
+    return artifact
+
+
+def truncate(text: str, limit: int) -> str:
+    """Cap text at `limit` chars, ending in an ellipsis when cut."""
+    if len(text) <= limit:
+        return text
+    return text[: limit - len(ELLIPSIS)].rstrip() + ELLIPSIS
+
+
+def snippet(text: str, limit: int = SNIPPET_MAX_CHARS) -> str:
+    """Collapse whitespace and cap at the snippet limit."""
+    return truncate(" ".join((text or "").split()), limit)
+
+
+def json_safe(value):
+    """Convert a value (e.g. parsed YAML frontmatter) to JSON-safe types."""
+    if isinstance(value, (str, int, float, bool, type(None))):
+        return value
+    if isinstance(value, Decimal):
+        return float(value)
+    if isinstance(value, (datetime, date)):
+        return value.isoformat()
+    if isinstance(value, (list, tuple, set)):
+        return [json_safe(v) for v in value]
+    if isinstance(value, dict):
+        return {str(k): json_safe(v) for k, v in value.items()}
+    return str(value)
+
+
+def unique(items) -> list:
+    """Deduplicate while keeping first-seen order."""
+    return list(dict.fromkeys(items))
+
+
+def _parse_date(value: str) -> date | None:
+    try:
+        return datetime.strptime(value, "%Y-%m-%d").date()
+    except (TypeError, ValueError):
+        return None
+
+
+def format_day(value: str) -> str:
+    """'2026-10-12' -> 'Oct 12'. Unparseable input is returned unchanged."""
+    d = _parse_date(value)
+    return f"{d:%b} {d.day}" if d else str(value)
+
+
+def format_month(value: str) -> str:
+    """'2026-10' or '2026-10-01' -> 'October 2026'. Unparseable input is returned unchanged."""
+    d = _parse_date(str(value)[:7] + "-01")
+    return f"{d:%B %Y}" if d else str(value)
+
+
+def format_date_range(start: str, end: str) -> str:
+    """Human date range: 'Oct 12–19', 'Oct 28–Nov 3', 'Dec 28, 2026–Jan 3, 2027'."""
+    s, e = _parse_date(start), _parse_date(end)
+    if not s or not e:
+        return f"{start}–{end}"
+    if s == e:
+        return f"{s:%b} {s.day}"
+    if s.year != e.year:
+        return f"{s:%b} {s.day}, {s.year}–{e:%b} {e.day}, {e.year}"
+    if s.month == e.month:
+        return f"{s:%b} {s.day}–{e.day}"
+    return f"{s:%b} {s.day}–{e:%b} {e.day}"
+
+
+def epoch_to_date(value) -> str | None:
+    """Epoch seconds -> 'YYYY-MM-DD' (None if not a number)."""
+    try:
+        return datetime.fromtimestamp(float(value)).strftime("%Y-%m-%d")
+    except (TypeError, ValueError, OverflowError, OSError):
+        return None
+
+
+def mealie_recipe_url(slug: str) -> str | None:
+    """Recipe page URL for Mealie v2 (`/g/<group-slug>/r/<slug>`)."""
+    base_url = os.getenv("MEALIE_BASE_URL", "").rstrip("/")
+    if not base_url:
+        return None
+    group = os.getenv("MEALIE_GROUP_SLUG", "") or "home"
+    return f"{base_url}/g/{quote(group)}/r/{quote(slug)}"
+
+
+def mealie_source_ref(slug: str) -> dict:
+    ref = {"system": "mealie", "id": slug}
+    url = mealie_recipe_url(slug)
+    if url:
+        ref["url"] = url
+    return ref
+
+
+def obsidian_source_ref(path: str) -> dict:
+    """Obsidian ref; the obsidian:// URL needs OBSIDIAN_VAULT_NAME."""
+    ref = {"system": "obsidian", "path": path}
+    vault = os.getenv("OBSIDIAN_VAULT_NAME", "")
+    if vault:
+        ref["url"] = "obsidian://open?" + urlencode(
+            {"vault": vault, "file": path}, quote_via=quote
+        )
+    return ref
+
+
+def note_title(path: str, frontmatter: dict | None = None) -> str:
+    """Frontmatter `title` if present, else the filename without extension."""
+    title = (frontmatter or {}).get("title")
+    if isinstance(title, str) and title.strip():
+        return title.strip()
+    return Path(path).stem or path
+
+
+def vault_relative_path(filepath: str) -> str:
+    """Strip OBSIDIAN_VAULT_PATH from an absolute indexed filepath."""
+    vault = os.getenv("OBSIDIAN_VAULT_PATH", "/app/data/obsidian")
+    try:
+        return str(Path(filepath).relative_to(vault))
+    except ValueError:
+        return filepath
+
+
+def search_documents_artifact(query: str, source: str, docs) -> dict | None:
+    """Build a `search.documents` artifact from vector-store Documents."""
+    if not docs:
+        return None
+    results = []
+    for doc in docs:
+        meta = doc.metadata or {}
+        result = {"snippet": snippet(doc.page_content)}
+        if source == "obsidian":
+            filepath = meta.get("filepath") or ""
+            path = vault_relative_path(filepath) if filepath else ""
+            result["title"] = note_title(path, meta) if path else "Untitled note"
+            if path:
+                result["path"] = path
+            created = meta.get("created_at")
+            if isinstance(created, str) and created:
+                result["date"] = created[:10]
+        else:
+            filename = meta.get("filename") or ""
+            result["title"] = Path(filename).stem or filename or "Document"
+            if filename:
+                result["filename"] = filename
+            if meta.get("document_type"):
+                result["document_type"] = str(meta["document_type"])
+            created = epoch_to_date(meta.get("created_date"))
+            if created:
+                result["date"] = created
+        results.append(result)
+    return make_artifact(
+        "search.documents",
+        f"Search: {query}",
+        {"query": query, "source": source, "results": results},
+    )

blueprints/conversation/logic.py

@@ -1,9 +1,54 @@
+from datetime import datetime, timezone
+
 import tortoise.exceptions
-from langchain_openai import ChatOpenAI
+from langchain_core.messages import ToolMessage
+from quart import current_app
 
 import blueprints.users.models
 
-from .models import Conversation, ConversationMessage, RenameConversationOutputSchema
+from .models import Conversation, ConversationMessage
+
+# Cap persisted tool output so replayed history stays within the LLM context
+# budget (llama-server slots are 32k tokens; base prompt + tools already use ~6k).
+TOOL_RESULT_MAX_CHARS = 4000
+
+
+def tool_result_text(tool_name: str, output) -> str:
+    """Format a tool's output for persistence as a conversation message."""
+    content = getattr(output, "content", output)
+    if isinstance(content, (list, tuple)):
+        content = "\n".join(str(item) for item in content)
+    text = str(content)
+    if len(text) > TOOL_RESULT_MAX_CHARS:
+        text = text[:TOOL_RESULT_MAX_CHARS] + "\n[truncated]"
+    return f"[{tool_name} result]\n{text}"
+
+
+def get_agent_for(user: blueprints.users.models.User):
+    """Admins get the agent with admin-only tools (Homebox, BookStack); everyone else the main one."""
+    if user.is_admin():
+        return getattr(current_app, "admin_agent", current_app.main_agent)
+    return current_app.main_agent
+
+
+async def persist_agent_tool_messages(
+    conversation: Conversation,
+    user: blueprints.users.models.User,
+    response_messages: list,
+) -> None:
+    """Persist ToolMessages from an agent response as 'tool' conversation messages.
+
+    Keeps fetched context (web searches, RAG chunks, etc.) available to later
+    turns, which otherwise only see the final text answers.
+    """
+    for msg in response_messages:
+        if isinstance(msg, ToolMessage):
+            await add_message_to_conversation(
+                conversation=conversation,
+                message=tool_result_text(msg.name or "tool", msg),
+                speaker="tool",
+                user=user,
+            )
 
 
 async def create_conversation(name: str = "") -> Conversation:
@@ -17,13 +62,26 @@ async def add_message_to_conversation(
     speaker: str,
     user: blueprints.users.models.User,
     image_key: str | None = None,
+    message_handle: str | None = None,
 ) -> ConversationMessage:
-    print(conversation, message, speaker)
+    # Bump updated_at on every message so conversations sort by last activity.
+    # `update_fields` bypasses the auto_now recompute, so set it explicitly.
+    update_fields = ["updated_at"]
+    conversation.updated_at = datetime.now(timezone.utc)
+
+    # Name the conversation after the first user message
+    if speaker == "user" and not await conversation.messages.all().exists():
+        conversation.name = message[:100]
+        update_fields.append("name")
+
+    await conversation.save(update_fields=update_fields)
+
     message = await ConversationMessage.create(
         text=message,
         speaker=speaker,
         conversation=conversation,
         image_key=image_key,
+        message_handle=message_handle,
     )
 
     return message
@@ -42,11 +100,29 @@ async def get_the_only_conversation() -> Conversation:
 
 async def get_conversation_for_user(user: blueprints.users.models.User) -> Conversation:
     try:
-        return await Conversation.get(user=user)
+        conversation = await Conversation.get(user=user)
+    except tortoise.exceptions.MultipleObjectsReturned:
+        conversation = (
+            await Conversation.filter(user=user).order_by("created_at").first()
+        )
     except tortoise.exceptions.DoesNotExist:
-        await Conversation.get_or_create(name=f"{user.username}'s chat", user=user)
+        conversation = await Conversation.create(
+            name=f"{user.username}'s chat", user=user
+        )
+    return conversation
 
-        return await Conversation.get(user=user)
+
+async def get_conversation_for_channel(
+    user: blueprints.users.models.User, channel: str
+) -> Conversation:
+    conversation = await (
+        Conversation.filter(user=user, channel=channel).order_by("-updated_at").first()
+    )
+    if conversation is None:
+        conversation = await Conversation.create(
+            name=f"{user.username}'s {channel} chat", user=user, channel=channel
+        )
+    return conversation
 
 
 async def get_conversation_by_id(id: str) -> Conversation:
@@ -61,22 +137,3 @@ async def get_conversation_transcript(
         messages.append(f"{message.speaker} at {message.created_at}: {message.text}")
 
     return "\n".join(messages)
-
-
-async def rename_conversation(
-    user: blueprints.users.models.User,
-    conversation: Conversation,
-) -> str:
-    messages: str = await get_conversation_transcript(
-        user=user, conversation=conversation
-    )
-
-    llm = ChatOpenAI(model="gpt-4o-mini")
-    structured_llm = llm.with_structured_output(RenameConversationOutputSchema)
-
-    prompt = f"Summarize the following conversation into a sassy one-liner title:\n\n{messages}"
-    response = structured_llm.invoke(prompt)
-    new_name: str = response.get("title", "")
-    conversation.name = new_name
-    await conversation.save()
-    return new_name

blueprints/conversation/memory.py

@@ -0,0 +1,28 @@
+from .models import UserMemory
+from .prompts import SIMBA_SYSTEM_PROMPT
+
+
+async def get_memories_for_user(user_id: str) -> list[str]:
+    """Return all memory content strings for a user, ordered by most recently updated."""
+    memories = await UserMemory.filter(user_id=user_id).order_by("-updated_at")
+    return [m.content for m in memories]
+
+
+async def build_system_prompt_with_memories(user_id: str) -> str:
+    memories = await get_memories_for_user(user_id)
+    if not memories:
+        return SIMBA_SYSTEM_PROMPT
+    block = "\n".join(f"- {m}" for m in memories)
+    return f"{SIMBA_SYSTEM_PROMPT}\n\nUSER MEMORIES (facts the user has asked you to remember):\n{block}"
+
+
+async def save_memory(user_id: str, content: str) -> str:
+    """Save a new memory or touch an existing one (exact-match dedup)."""
+    existing = await UserMemory.filter(user_id=user_id, content=content).first()
+    if existing:
+        existing.updated_at = None  # auto_now=True will refresh it on save
+        await existing.save(update_fields=["updated_at"])
+        return "Memory already exists (refreshed)."
+
+    await UserMemory.create(user_id=user_id, content=content)
+    return "Memory saved."

blueprints/conversation/models.py

@@ -1,5 +1,4 @@
 import enum
-from dataclasses import dataclass
 
 from tortoise import fields
 from tortoise.contrib.pydantic import (
@@ -9,15 +8,10 @@ from tortoise.contrib.pydantic import (
 from tortoise.models import Model
 
 
-@dataclass
-class RenameConversationOutputSchema:
-    title: str
-    justification: str
-
-
 class Speaker(enum.Enum):
     USER = "user"
     SIMBA = "simba"
+    TOOL = "tool"
 
 
 class Conversation(Model):
@@ -28,6 +22,7 @@ class Conversation(Model):
     user: fields.ForeignKeyRelation = fields.ForeignKeyField(
         "models.User", related_name="conversations", null=True
     )
+    channel = fields.CharField(max_length=20, default="web", null=True)
 
     class Meta:
         table = "conversations"
@@ -42,11 +37,23 @@ class ConversationMessage(Model):
     created_at = fields.DatetimeField(auto_now_add=True)
     speaker = fields.CharEnumField(enum_type=Speaker, max_length=10)
     image_key = fields.CharField(max_length=512, null=True, default=None)
+    message_handle = fields.CharField(max_length=255, null=True, default=None)
 
     class Meta:
         table = "conversation_messages"
 
 
+class UserMemory(Model):
+    id = fields.UUIDField(primary_key=True)
+    user = fields.ForeignKeyField("models.User", related_name="memories")
+    content = fields.TextField()
+    created_at = fields.DatetimeField(auto_now_add=True)
+    updated_at = fields.DatetimeField(auto_now=True)
+
+    class Meta:
+        table = "user_memories"
+
+
 PydConversationMessage = pydantic_model_creator(ConversationMessage)
 PydConversation = pydantic_model_creator(
     Conversation, name="Conversation", allow_cycles=True, exclude=("user",)

blueprints/conversation/prompts.py

@@ -1,4 +1,4 @@
-SIMBA_SYSTEM_PROMPT = """You are a helpful cat assistant named Simba that understands veterinary terms. When there are questions to you specifically, they are referring to Simba the cat. Answer the user in as if you were a cat named Simba. Don't act too catlike. Be assertive.
+SIMBA_SYSTEM_PROMPT = """You are Simba, Ryan's helpful personal assistant. You're named after his orange cat. You have a warm, friendly personality with a light cat-themed touch, but your priority is always being genuinely useful — give thorough, detailed answers and think things through carefully. When asked about Simba the cat, you speak as him in first person. For everything else, you're just a great assistant who happens to have a cat's name.
 
 SIMBA FACTS (as of January 2026):
 - Name: Simba
@@ -34,12 +34,29 @@ IMPORTANT: When users ask factual questions about Simba's health, medical histor
 
 BUDGET & FINANCE (YNAB Integration):
 You have access to Ryan's budget data through YNAB (You Need A Budget). When users ask about financial matters, use the appropriate YNAB tools:
-- Use ynab_budget_summary for overall budget health and status questions
+- Use ynab_budget_summary for a month's overview (Ready to Assign, income, spent, overspending, net worth)
+- Use ynab_account_balances for account and credit card balances
 - Use ynab_search_transactions to find specific purchases or spending at particular stores
-- Use ynab_category_spending to analyze spending by category for a month
-- Use ynab_insights to provide spending trends, patterns, and recommendations
+- Use ynab_spending_report for totals by category, payee, or account, and group_by='month' for trends
+- Use ynab_category_budget for what's assigned/available per category in a month
+- Use ynab_recent_changes for what was added, edited, or re-assigned recently
 Always use these tools when asked about budgets, spending, transactions, or financial health.
 
+MEAL PLANNING (Mealie Integration):
+You have access to Ryan's meal plans, recipes, and shopping lists through Mealie. When users ask about food or meal planning, use the appropriate Mealie tools:
+- Use mealie_todays_meals to check what's planned for today
+- Use mealie_meal_plans to see the week's meal schedule or a custom date range
+- Use mealie_get_recipe to get full recipe details (ingredients, instructions)
+- Use mealie_shopping_lists to check what groceries are needed
+- Use mealie_create_meal_plan to add meals to the plan
+Always use these tools when asked about meals, recipes, what's for dinner, or shopping lists.
+
+HOME INVENTORY (Homebox Integration):
+If homebox_* tools are available, use them for questions about household items: where something is stored, what's in a location, warranties, and maintenance. Search before creating items to avoid duplicates, and use homebox_set_item to edit an existing item (name, description, notes, quantity, purchase info, custom fields) instead of creating a new one.
+
+WIKI (BookStack Integration):
+If bookstack_* tools are available, use them to look up and write household documentation in the BookStack wiki. Search before creating books, chapters, or pages to avoid duplicates, and prefer updating an existing page over creating a near-copy. Write page content as markdown.
+
 NOTES & RESEARCH (Obsidian Integration):
 You have access to Ryan's Obsidian vault through the Obsidian integration. When users ask about research, personal notes, or information that might be stored in markdown files, use the appropriate Obsidian tools:
 - Use obsidian_search_notes to search through your vault for relevant information
@@ -49,9 +66,12 @@ You have access to Ryan's Obsidian vault through the Obsidian integration. When
 Always use these tools when users ask about notes, research, ideas, tasks, or when you want to save information for future reference.
 
 DAILY JOURNAL (Task Tracking):
-You have access to Ryan's daily journal notes. Each note lives at journal/YYYY/YYYY-MM-DD.md and has two sections: tasks and log.
+You have access to Ryan's daily journal notes. Each note lives at 50 - Journal/YYYY/MM/YYYY-MM-DD.md and has two sections: tasks and log.
 - Use journal_get_today to read today's full daily note (tasks + log)
 - Use journal_get_tasks to list tasks (done/pending) for today or a specific date
 - Use journal_add_task to add a new task to today's (or a given date's) note
 - Use journal_complete_task to check off a task as done
-Use these tools when Ryan asks about today's tasks, wants to add something to his list, or wants to mark a task complete."""
+Use these tools when Ryan asks about today's tasks, wants to add something to his list, or wants to mark a task complete.
+
+USER MEMORY:
+You can remember facts about the user across conversations using the save_user_memory tool. When a user explicitly asks you to remember something, or shares a meaningful preference or personal fact, save it. Saved memories will automatically appear at the end of this prompt in future conversations under "USER MEMORIES"."""

blueprints/conversation/tool_events.py

@@ -0,0 +1,77 @@
+"""Pure shaping of LangChain tool events into SSE `tool_start` / `tool_end` payloads."""
+
+import json
+import re
+
+from .tool_labels import tool_label
+
+INPUT_VALUE_MAX_CHARS = 200
+# Injected by LangChain rather than chosen by the model; never shown to the client.
+_HIDDEN_INPUT_KEYS = frozenset({"config", "callbacks", "run_manager"})
+
+_TOOL_HEADER_RE = re.compile(r"^\[(\S+) result\]")
+
+
+def _truncate(text: str) -> str:
+    if len(text) > INPUT_VALUE_MAX_CHARS:
+        return text[: INPUT_VALUE_MAX_CHARS - 1] + "…"
+    return text
+
+
+def summarize_tool_input(raw) -> dict[str, str | int | float | bool]:
+    """Reduce a tool's input to flat, display-safe scalars."""
+    if raw is None:
+        return {}
+    if not isinstance(raw, dict):
+        return {"input": _truncate(str(raw))}
+    summary: dict[str, str | int | float | bool] = {}
+    for key, value in raw.items():
+        if key in _HIDDEN_INPUT_KEYS or value is None:
+            continue
+        if isinstance(value, (bool, int, float)):
+            summary[key] = value
+        elif isinstance(value, str):
+            summary[key] = _truncate(value)
+        else:
+            try:
+                summary[key] = _truncate(json.dumps(value, default=str))
+            except (TypeError, ValueError):
+                summary[key] = _truncate(str(value))
+    return summary
+
+
+def tool_start_payload(event: dict) -> dict:
+    name = event["name"]
+    return {
+        "type": "tool_start",
+        "run_id": event["run_id"],
+        "tool": name,
+        "label": tool_label(name),
+        "input": summarize_tool_input(event.get("data", {}).get("input")),
+    }
+
+
+def tool_end_payload(
+    event: dict,
+    started_at: float | None,
+    artifact_ref: dict | None,
+    *,
+    now: float,
+    status: str = "ok",
+) -> dict:
+    name = event["name"]
+    return {
+        "type": "tool_end",
+        "run_id": event["run_id"],
+        "tool": name,
+        "label": tool_label(name),
+        "status": status,
+        "ms": round((now - started_at) * 1000) if started_at is not None else 0,
+        "artifact": artifact_ref,
+    }
+
+
+def tool_name_from_message(text: str) -> str:
+    """Recover the tool name from a persisted `[tool_name result]` header."""
+    match = _TOOL_HEADER_RE.match(text)
+    return match.group(1) if match else "tool"

blueprints/conversation/tool_labels.py

@@ -0,0 +1,64 @@
+"""Friendly, user-facing labels for agent tool calls (shown in the activity timeline)."""
+
+TOOL_LABELS: dict[str, str] = {
+    "get_current_date": "Checking the date…",
+    "web_search": "Searching the web…",
+    "simba_search": "Searching household documents…",
+    "save_user_memory": "Saving to memory…",
+    # YNAB (current names)
+    "ynab_budget_summary": "Checking budget…",
+    "ynab_search_transactions": "Searching transactions…",
+    "ynab_category_spending": "Reviewing category spending…",
+    "ynab_category_allocations": "Reviewing category budgets…",
+    "ynab_insights": "Analyzing spending trends…",
+    # YNAB (names after the #55 mirror)
+    "ynab_account_balances": "Checking account balances…",
+    "ynab_spending_report": "Building spending report…",
+    "ynab_category_budget": "Reviewing category budgets…",
+    "ynab_recent_changes": "Checking recent budget changes…",
+    "ynab_sql": "Querying budget data…",
+    # Mealie
+    "mealie_todays_meals": "Checking today's meals…",
+    "mealie_meal_plans": "Checking the meal plan…",
+    "mealie_get_recipe": "Fetching recipe…",
+    "mealie_shopping_lists": "Checking shopping lists…",
+    "mealie_create_meal_plan": "Adding to the meal plan…",
+    # Obsidian / journal
+    "obsidian_search_notes": "Searching notes…",
+    "obsidian_read_note": "Reading note…",
+    "obsidian_create_note": "Creating note…",
+    "obsidian_create_task": "Creating task…",
+    "journal_get_today": "Reading today's journal…",
+    "journal_get_tasks": "Checking tasks…",
+    "journal_add_task": "Adding task…",
+    "journal_complete_task": "Completing task…",
+    # Google
+    "get_calendar_events": "Checking calendar…",
+    "create_calendar_event": "Creating calendar event…",
+    "gmail_search_emails": "Searching email…",
+    "gmail_get_email": "Reading email…",
+    # SimbaKit
+    "simbakit_device_status": "Checking Simba's devices…",
+    "simbakit_weight_history": "Checking Simba's weight…",
+    "simbakit_litter_activity": "Checking litter box activity…",
+    "simbakit_drinking_activity": "Checking water fountain activity…",
+    # Beli
+    "beli_search_restaurants": "Searching restaurants…",
+}
+
+# MCP tools are discovered at runtime, so they match by name prefix.
+TOOL_PREFIX_LABELS: tuple[tuple[str, str], ...] = (
+    ("homebox_", "Checking home inventory…"),
+    ("bookstack_", "Checking the wiki…"),
+)
+
+
+def tool_label(tool_name: str) -> str:
+    """Return the friendly label for a tool, falling back to "Using <tool>…"."""
+    label = TOOL_LABELS.get(tool_name)
+    if label:
+        return label
+    for prefix, prefix_label in TOOL_PREFIX_LABELS:
+        if tool_name.startswith(prefix):
+            return prefix_label
+    return f"Using {tool_name}…"

blueprints/cron/__init__.py

@@ -0,0 +1,176 @@
+import hmac
+import logging
+import os
+from datetime import datetime, timezone
+
+from quart import Blueprint, current_app, jsonify, request
+
+from blueprints.users.decorators import admin_required
+from blueprints.scheduled_messages.models import MessageChannel
+from .models import CronJob
+
+cron_blueprint = Blueprint("cron_api", __name__, url_prefix="/api/cron")
+
+logger = logging.getLogger(__name__)
+
+
+def _serialize(job: CronJob) -> dict:
+    return {
+        "id": str(job.id),
+        "name": job.name,
+        "description": job.description,
+        "prompt": job.prompt,
+        "recipient": job.recipient,
+        "channel": job.channel.value,
+        "enabled": job.enabled,
+        "last_run_at": job.last_run_at.isoformat() if job.last_run_at else None,
+        "last_status": job.last_status,
+        "last_error": job.last_error,
+        "created_at": job.created_at.isoformat(),
+        "updated_at": job.updated_at.isoformat(),
+    }
+
+
+def _check_cron_secret() -> bool:
+    expected = os.environ.get("CRON_SECRET", "")
+    if not expected:
+        return False
+    provided = request.headers.get("X-Cron-Secret", "")
+    return hmac.compare_digest(provided.encode(), expected.encode())
+
+
+@cron_blueprint.route("/", methods=["GET"])
+@admin_required
+async def list_jobs():
+    jobs = await CronJob.all().order_by("name")
+    return jsonify([_serialize(j) for j in jobs])
+
+
+@cron_blueprint.route("/", methods=["POST"])
+@admin_required
+async def create_job():
+    data = await request.get_json()
+    if not data:
+        return jsonify({"error": "Invalid payload"}), 400
+
+    name = (data.get("name") or "").strip()
+    prompt = (data.get("prompt") or "").strip()
+    recipient = (data.get("recipient") or "").strip()
+    channel_str = data.get("channel")
+    description = (data.get("description") or "").strip() or None
+
+    if not name or not prompt or not recipient or not channel_str:
+        return jsonify(
+            {"error": "name, prompt, recipient, and channel are required"}
+        ), 400
+
+    try:
+        channel = MessageChannel(channel_str)
+    except ValueError:
+        return jsonify(
+            {"error": f"Invalid channel: {channel_str}. Must be 'imessage' or 'email'"}
+        ), 400
+
+    job = await CronJob.create(
+        name=name,
+        description=description,
+        prompt=prompt,
+        recipient=recipient,
+        channel=channel,
+        enabled=bool(data.get("enabled", True)),
+    )
+    return jsonify(_serialize(job)), 201
+
+
+@cron_blueprint.route("/<job_id>", methods=["PUT"])
+@admin_required
+async def update_job(job_id: str):
+    job = await CronJob.get_or_none(id=job_id)
+    if not job:
+        return jsonify({"error": "Not found"}), 404
+
+    data = await request.get_json()
+    if not data:
+        return jsonify({"error": "Invalid payload"}), 400
+
+    if "name" in data:
+        job.name = data["name"].strip()
+    if "description" in data:
+        job.description = (data["description"] or "").strip() or None
+    if "prompt" in data:
+        job.prompt = data["prompt"].strip()
+    if "recipient" in data:
+        job.recipient = data["recipient"].strip()
+    if "channel" in data:
+        try:
+            job.channel = MessageChannel(data["channel"])
+        except ValueError:
+            return jsonify({"error": f"Invalid channel: {data['channel']}"}), 400
+    if "enabled" in data:
+        job.enabled = bool(data["enabled"])
+
+    await job.save()
+    return jsonify(_serialize(job))
+
+
+@cron_blueprint.route("/<job_id>", methods=["DELETE"])
+@admin_required
+async def delete_job(job_id: str):
+    job = await CronJob.get_or_none(id=job_id)
+    if not job:
+        return jsonify({"error": "Not found"}), 404
+
+    await job.delete()
+    return jsonify({"status": "deleted"})
+
+
+@cron_blueprint.route("/<job_id>/trigger", methods=["POST"])
+async def trigger_job(job_id: str):
+    if not _check_cron_secret():
+        return jsonify({"error": "Unauthorized"}), 401
+
+    job = await CronJob.get_or_none(id=job_id)
+    if not job:
+        return jsonify({"error": "Not found"}), 404
+
+    if not job.enabled:
+        return jsonify({"skipped": True}), 200
+
+    try:
+        import uuid
+
+        response = await current_app.main_agent.ainvoke(
+            {"messages": [{"role": "user", "content": job.prompt}]},
+            config={"configurable": {"thread_id": f"cron-{uuid.uuid4()}"}},
+        )
+        result = response.get("messages", [])[-1].content
+
+        if job.channel == MessageChannel.IMESSAGE:
+            from blueprints.imessage import send_imessage
+            from utils.strip_markdown import strip_markdown
+
+            await send_imessage(job.recipient, strip_markdown(result))
+
+        elif job.channel == MessageChannel.EMAIL:
+            from blueprints.email import send_email_reply
+
+            await send_email_reply(
+                to=job.recipient,
+                subject=job.name,
+                body=result,
+            )
+
+        job.last_run_at = datetime.now(timezone.utc)
+        job.last_status = "success"
+        job.last_error = None
+        await job.save()
+        logger.info(f"Cron job {job.id} ({job.name}) executed successfully")
+        return jsonify({"ok": True})
+
+    except Exception as e:
+        job.last_run_at = datetime.now(timezone.utc)
+        job.last_status = "failed"
+        job.last_error = str(e)
+        await job.save()
+        logger.error(f"Cron job {job.id} ({job.name}) failed: {e}")
+        return jsonify({"error": str(e)}), 500

blueprints/cron/models.py

@@ -0,0 +1,22 @@
+from tortoise import fields
+from tortoise.models import Model
+
+from blueprints.scheduled_messages.models import MessageChannel
+
+
+class CronJob(Model):
+    id = fields.UUIDField(primary_key=True)
+    name = fields.CharField(max_length=255)
+    description = fields.TextField(null=True)
+    prompt = fields.TextField()
+    recipient = fields.CharField(max_length=255)
+    channel = fields.CharEnumField(enum_type=MessageChannel, max_length=20)
+    enabled = fields.BooleanField(default=True)
+    last_run_at = fields.DatetimeField(null=True)
+    last_status = fields.CharField(max_length=50, null=True)
+    last_error = fields.TextField(null=True)
+    created_at = fields.DatetimeField(auto_now_add=True)
+    updated_at = fields.DatetimeField(auto_now=True)
+
+    class Meta:
+        table = "cron_jobs"

blueprints/email/__init__.py

@@ -7,14 +7,15 @@ import time
 from collections import defaultdict
 
 import httpx
-from quart import Blueprint, request
+from quart import Blueprint, current_app, request
 
 from blueprints.users.models import User
 from blueprints.conversation.logic import (
-    get_conversation_for_user,
+    get_conversation_for_channel,
     add_message_to_conversation,
+    persist_agent_tool_messages,
 )
-from blueprints.conversation.agents import main_agent
+from blueprints.conversation.models import Speaker
 from blueprints.conversation.prompts import SIMBA_SYSTEM_PROMPT
 from . import models  # noqa: F401 — register Tortoise ORM models
 from .helpers import generate_email_token, get_user_email_address  # noqa: F401
@@ -176,7 +177,7 @@ async def webhook():
 
     # Get or create conversation
     try:
-        conversation = await get_conversation_for_user(user=user)
+        conversation = await get_conversation_for_channel(user=user, channel="email")
         await conversation.fetch_related("messages")
     except Exception as e:
         logger.error(f"Failed to get conversation for user {user.username}: {e}")
@@ -193,17 +194,20 @@ async def webhook():
     # Build messages payload
     try:
         messages = await conversation.messages.all()
-        recent_messages = list(messages)[-10:]
+        recent_messages = list(messages)[-20:]
 
         messages_payload = [{"role": "system", "content": SIMBA_SYSTEM_PROMPT}]
         for msg in recent_messages[:-1]:
-            role = "user" if msg.speaker == "user" else "assistant"
+            role = "user" if msg.speaker == Speaker.USER else "assistant"
             messages_payload.append({"role": role, "content": msg.text})
         messages_payload.append({"role": "user", "content": body})
 
         logger.info(f"Invoking LangChain agent with {len(messages_payload)} messages")
-        response = await main_agent.ainvoke({"messages": messages_payload})
+        response = await current_app.main_agent.ainvoke({"messages": messages_payload})
         response_text = response.get("messages", [])[-1].content
+        await persist_agent_tool_messages(
+            conversation, user, response.get("messages", [])
+        )
     except Exception as e:
         logger.error(f"Error invoking agent for email: {e}")
         response_text = "Sorry, I'm having trouble thinking right now."

blueprints/email/crypto_service.py

@@ -4,11 +4,27 @@ Encryption service for email credentials.
 Provides transparent Fernet encryption for sensitive fields in the database.
 """
 
+import base64
 import os
 from cryptography.fernet import Fernet
 from tortoise import fields
 
 
+def _is_fernet_token(value: str) -> bool:
+    """Return True if value looks like a Fernet token.
+
+    Fernet tokens are URL-safe base64 and decode to at least 73 bytes
+    (1 version + 8 timestamp + 16 IV + 16 min-ciphertext + 32 HMAC).
+    The first decoded byte is always 0x80 (the Fernet version byte).
+    """
+    try:
+        padded = value + "=" * (-len(value) % 4)
+        raw = base64.urlsafe_b64decode(padded.encode())
+        return len(raw) >= 73 and raw[0] == 0x80
+    except Exception:
+        return False
+
+
 class EncryptedTextField(fields.TextField):
     """
     Custom Tortoise ORM field that transparently encrypts/decrypts text values.
@@ -38,10 +54,16 @@ class EncryptedTextField(fields.TextField):
         return self.fernet.encrypt(value.encode()).decode()
 
     def to_python_value(self, value: str) -> str:
-        """Decrypt value when loading from database."""
+        """Decrypt value when loading from database.
+
+        Plaintext values (e.g. freshly-set before the first DB round-trip) are
+        returned as-is. Values that look like Fernet tokens are decrypted — a
+        wrong key still raises InvalidToken, preserving the security guarantee.
+        """
         if value is None:
             return None
-        # Decrypt Fernet token
+        if not _is_fernet_token(value):
+            return value
         return self.fernet.decrypt(value.encode()).decode()
 
 

blueprints/imessage/__init__.py

@@ -0,0 +1,389 @@
+import asyncio
+import os
+import hmac
+import logging
+import functools
+import time
+from collections import defaultdict
+
+import httpx
+from quart import Blueprint, request, jsonify
+
+from blueprints.users.models import User
+from blueprints.conversation.logic import (
+    get_agent_for,
+    get_conversation_for_channel,
+    add_message_to_conversation,
+    persist_agent_tool_messages,
+)
+from blueprints.conversation.models import Conversation, ConversationMessage
+from blueprints.conversation.memory import build_system_prompt_with_memories
+from utils.strip_markdown import extract_agent_text, strip_markdown
+
+imessage_blueprint = Blueprint("imessage_api", __name__, url_prefix="/api/imessage")
+
+logger = logging.getLogger(__name__)
+
+# Rate limiting: per-number message timestamps
+_rate_limit_store: dict[str, list[float]] = defaultdict(list)
+
+RATE_LIMIT_MAX = int(os.getenv("IMESSAGE_RATE_LIMIT_MAX", "10"))
+RATE_LIMIT_WINDOW = int(os.getenv("IMESSAGE_RATE_LIMIT_WINDOW", "60"))
+
+MAX_MESSAGE_LENGTH = 2000
+
+SENDBLUE_API_BASE = "https://api.sendblue.co"
+
+
+def _get_sendblue_headers() -> dict[str, str]:
+    return {
+        "sb-api-key-id": os.getenv("SENDBLUE_API_KEY", ""),
+        "sb-api-secret-key": os.getenv("SENDBLUE_API_SECRET", ""),
+        "Content-Type": "application/json",
+    }
+
+
+def _check_rate_limit(phone_number: str) -> bool:
+    """Check if a phone number has exceeded the rate limit.
+
+    Returns True if the request is allowed, False if rate-limited.
+    """
+    now = time.monotonic()
+    cutoff = now - RATE_LIMIT_WINDOW
+
+    timestamps = _rate_limit_store[phone_number]
+    _rate_limit_store[phone_number] = [t for t in timestamps if t > cutoff]
+
+    if len(_rate_limit_store[phone_number]) >= RATE_LIMIT_MAX:
+        return False
+
+    _rate_limit_store[phone_number].append(now)
+    return True
+
+
+async def send_imessage(
+    to_number: str,
+    content: str,
+    reply_to_handle: str | None = None,
+) -> dict:
+    """Send an iMessage via SendBlue API."""
+    from_number = os.getenv("SENDBLUE_FROM_NUMBER", "")
+
+    payload: dict = {
+        "number": to_number,
+        "from_number": from_number,
+        "content": content,
+    }
+    if reply_to_handle:
+        payload["reply_to"] = {"message_handle": reply_to_handle}
+
+    async with httpx.AsyncClient() as client:
+        resp = await client.post(
+            f"{SENDBLUE_API_BASE}/api/send-message",
+            headers=_get_sendblue_headers(),
+            json=payload,
+            timeout=30,
+        )
+        resp.raise_for_status()
+        return resp.json()
+
+
+async def send_typing_indicator(
+    to_number: str,
+    state: str = "start",
+    max_duration_ms: int | None = None,
+) -> None:
+    """Send or stop a typing indicator. Errors are logged and swallowed."""
+    from_number = os.getenv("SENDBLUE_FROM_NUMBER", "")
+    payload: dict = {
+        "number": to_number,
+        "from_number": from_number,
+        "state": state,
+    }
+    if max_duration_ms is not None:
+        payload["max_duration_ms"] = max_duration_ms
+
+    try:
+        async with httpx.AsyncClient() as client:
+            await client.post(
+                f"{SENDBLUE_API_BASE}/api/send-typing-indicator",
+                headers=_get_sendblue_headers(),
+                json=payload,
+                timeout=10,
+            )
+    except Exception as e:
+        logger.warning(f"Failed to send typing indicator ({state}): {e}")
+
+
+def validate_sendblue_signature(f):
+    """Decorator to validate the SendBlue webhook signing secret."""
+
+    @functools.wraps(f)
+    async def decorated_function(*args, **kwargs):
+        if os.getenv("SENDBLUE_SIGNATURE_VALIDATION", "true").lower() == "false":
+            return await f(*args, **kwargs)
+
+        secret = os.getenv("SENDBLUE_WEBHOOK_SECRET")
+        if not secret:
+            logger.error("SENDBLUE_WEBHOOK_SECRET not set — rejecting request")
+            return jsonify({"error": "Server misconfigured"}), 500
+
+        sig = request.headers.get("sb-signing-secret", "")
+        if not hmac.compare_digest(sig, secret):
+            logger.warning("Invalid SendBlue signing secret")
+            return jsonify({"error": "Unauthorized"}), 403
+
+        return await f(*args, **kwargs)
+
+    return decorated_function
+
+
+@imessage_blueprint.route("/webhook", methods=["POST"])
+@validate_sendblue_signature
+async def webhook():
+    """Handle incoming iMessages from SendBlue."""
+    data = await request.get_json()
+    if not data:
+        return jsonify({"error": "Invalid payload"}), 400
+
+    from_number = data.get("from_number")
+    content = data.get("content") or ""
+    media_url = data.get("media_url")
+    is_outbound = data.get("is_outbound", False)
+
+    # Threading fields from SendBlue
+    inbound_handle = data.get("message_handle")
+    reply_to_handle = (data.get("reply_to") or {}).get("message_handle")
+    originator_handle = (data.get("thread_originator") or {}).get("message_handle")
+
+    # Ignore outbound messages (our own replies echoed back)
+    if is_outbound:
+        return jsonify({"status": "ignored"}), 200
+
+    if not from_number:
+        return jsonify({"error": "Missing from_number"}), 400
+
+    if not content and not media_url:
+        return jsonify({"error": "Missing content and media_url"}), 400
+
+    content = content.strip()
+    if not content and not media_url:
+        await send_imessage(
+            from_number,
+            "I received an empty message. Please send some text or an image!",
+        )
+        return jsonify({"status": "ok"}), 200
+
+    # Rate limiting
+    if not _check_rate_limit(from_number):
+        logger.warning(f"Rate limit exceeded for {from_number}")
+        await send_imessage(
+            from_number,
+            "You're sending messages too quickly. Please wait a moment and try again.",
+        )
+        return jsonify({"status": "rate_limited"}), 200
+
+    # Truncate overly long messages
+    if len(content) > MAX_MESSAGE_LENGTH:
+        content = content[:MAX_MESSAGE_LENGTH]
+        logger.info(
+            f"Truncated long message from {from_number} to {MAX_MESSAGE_LENGTH} chars"
+        )
+
+    logger.info(f"Received iMessage from {from_number}: {content[:100]}")
+
+    # Identify or create user
+    user = await User.filter(imessage_number=from_number).first()
+
+    if not user:
+        allowed_numbers = os.getenv("ALLOWED_IMESSAGE_NUMBERS", "").split(",")
+        if from_number not in allowed_numbers and "*" not in allowed_numbers:
+            await send_imessage(
+                from_number, "Sorry, you are not authorized to use this service."
+            )
+            return jsonify({"status": "unauthorized"}), 200
+
+        username = f"im_{from_number.lstrip('+')}"
+        try:
+            user = await User.create(
+                username=username,
+                email=f"{username}@imessage.simbarag.local",
+                imessage_number=from_number,
+                auth_provider="imessage",
+            )
+            logger.info(f"Created new user for iMessage: {username}")
+        except Exception as e:
+            logger.error(f"Failed to create user for {from_number}: {e}")
+            await send_imessage(
+                from_number, "Sorry, something went wrong setting up your account."
+            )
+            return jsonify({"status": "error"}), 200
+
+    # iMessage is restricted to admins
+    if not user.is_admin():
+        logger.warning(f"Non-admin user {user.username} attempted iMessage access")
+        await send_imessage(from_number, "Sorry, this feature is restricted to admins.")
+        return jsonify({"status": "forbidden"}), 200
+
+    # /threads command — list recent iMessage conversations
+    if content.strip().lower() == "/threads":
+        threads = (
+            await Conversation.filter(user=user, channel="imessage")
+            .order_by("-updated_at")
+            .limit(5)
+        )
+        if not threads:
+            await send_imessage(from_number, "No threads found.")
+        else:
+            lines = ["Your recent threads (most recent first):"]
+            for i, t in enumerate(threads, 1):
+                updated = t.updated_at.strftime("%b %-d")
+                lines.append(f"{i}. {t.name} ({updated})")
+            lines.append("\nReply to any message to continue its thread.")
+            await send_imessage(from_number, "\n".join(lines))
+        return jsonify({"status": "ok"}), 200
+
+    # Determine conversation based on iMessage reply threading:
+    # - Reply to an existing message → continue that conversation
+    # - New standalone message → start a fresh conversation
+    try:
+        if reply_to_handle:
+            lookup_handle = originator_handle or reply_to_handle
+            parent_msg = await ConversationMessage.get_or_none(
+                message_handle=lookup_handle,
+                conversation__user=user,
+                conversation__channel="imessage",
+            )
+            if parent_msg:
+                conversation = await Conversation.get(id=parent_msg.conversation_id)
+                logger.info(
+                    f"Continuing conversation {conversation.id} via reply to {lookup_handle!r}"
+                )
+            else:
+                # Handle not found (pre-migration messages) — fall back to most recent
+                logger.warning(
+                    f"Reply handle {lookup_handle!r} not in DB; falling back to most recent conversation"
+                )
+                conversation = await get_conversation_for_channel(
+                    user=user, channel="imessage"
+                )
+        else:
+            conversation = await Conversation.create(
+                name="New iMessage",
+                user=user,
+                channel="imessage",
+            )
+            logger.info(
+                f"New iMessage conversation {conversation.id} for {user.username}"
+            )
+
+    except Exception as e:
+        logger.error(f"Failed to get/create conversation for {user.username}: {e}")
+        await send_imessage(
+            from_number, "Sorry, something went wrong. Please try again later."
+        )
+        return jsonify({"status": "error"}), 200
+
+    # Save the inbound message now so it's persisted before we ack
+    await add_message_to_conversation(
+        conversation=conversation,
+        message=content,
+        speaker="user",
+        user=user,
+        message_handle=inbound_handle,
+    )
+
+    # Fire LLM processing in the background so we can ack SendBlue immediately.
+    # SendBlue retries if it doesn't receive a 200 within its timeout (~5s).
+    asyncio.ensure_future(
+        _process_and_reply(
+            from_number=from_number,
+            inbound_handle=inbound_handle,
+            conversation=conversation,
+            user=user,
+            content=content,
+            media_url=media_url,
+        )
+    )
+
+    return jsonify({"status": "ok"}), 200
+
+
+async def _process_and_reply(
+    from_number: str,
+    inbound_handle: str | None,
+    conversation: Conversation,
+    user,
+    content: str,
+    media_url: str | None,
+) -> None:
+    """Run the LLM agent and send the reply. Called as a background task."""
+    # Attach image if present
+    image_block = None
+    if media_url:
+        try:
+            from utils.image_process import image_content_block
+
+            async with httpx.AsyncClient() as client:
+                resp = await client.get(media_url, timeout=30)
+                resp.raise_for_status()
+            image_block = image_content_block(resp.content)
+        except Exception as e:
+            logger.error(f"Failed to load iMessage image: {e}")
+            content = f"{content or ''}\n\n[An image was sent but could not be loaded.]".strip()
+
+    await send_typing_indicator(from_number, state="start", max_duration_ms=120_000)
+
+    response_text = "Sorry, I'm having trouble thinking right now."
+    try:
+        if image_block:
+            user_content = [
+                {"type": "text", "text": content or "The user sent this image."},
+                image_block,
+            ]
+        else:
+            user_content = content
+
+        system_prompt = await build_system_prompt_with_memories(str(user.id))
+        system_prompt += (
+            "\n\nIMPORTANT: You are replying via iMessage. Use plain text only. "
+            "Do not use markdown tables, headers, bullet points, bold, italics, "
+            "or any other markdown formatting. Write in natural prose."
+        )
+        agent_config = {
+            "configurable": {
+                "user_id": str(user.id),
+                "is_admin": user.is_admin(),
+                "thread_id": str(conversation.id),
+                "system_prompt": system_prompt,
+            }
+        }
+        logger.info(f"Invoking LangChain agent for conversation {conversation.id}")
+        response = await get_agent_for(user).ainvoke(
+            {"messages": [{"role": "user", "content": user_content}]},
+            config=agent_config,
+        )
+        response_text = extract_agent_text(response.get("messages", [])[-1].content)
+        await persist_agent_tool_messages(
+            conversation, user, response.get("messages", [])
+        )
+
+    except Exception as e:
+        logger.error(f"Error invoking agent: {e}")
+    finally:
+        await send_typing_indicator(from_number, state="stop")
+
+    send_resp = await send_imessage(
+        from_number,
+        strip_markdown(response_text),
+        reply_to_handle=inbound_handle,
+    )
+    outbound_handle = (send_resp or {}).get("message_handle")
+
+    await add_message_to_conversation(
+        conversation=conversation,
+        message=response_text,
+        speaker="simba",
+        user=user,
+        message_handle=outbound_handle,
+    )

blueprints/rag/__init__.py

@@ -1,14 +1,18 @@
 from quart import Blueprint, jsonify
-from quart_jwt_extended import jwt_refresh_token_required
 
-from .logic import fetch_obsidian_documents, get_vector_store_stats, index_documents, index_obsidian_documents, vector_store
-from blueprints.users.decorators import admin_required
+from .logic import (
+    delete_all_documents,
+    get_vector_store_stats,
+    index_documents,
+    sync_obsidian_documents,
+)
+from blueprints.users.decorators import admin_required, jwt_access_required
 
 rag_blueprint = Blueprint("rag_api", __name__, url_prefix="/api/rag")
 
 
 @rag_blueprint.get("/stats")
-@jwt_refresh_token_required
+@jwt_access_required
 async def get_stats():
     """Get vector store statistics."""
     stats = get_vector_store_stats()
@@ -32,14 +36,7 @@ async def trigger_index():
 async def trigger_reindex():
     """Clear and reindex all documents. Admin only."""
     try:
-        # Clear existing documents
-        collection = vector_store._collection
-        all_docs = collection.get()
-
-        if all_docs["ids"]:
-            collection.delete(ids=all_docs["ids"])
-
-        # Reindex
+        delete_all_documents()
         await index_documents()
         stats = get_vector_store_stats()
         return jsonify({"status": "success", "stats": stats})
@@ -50,9 +47,9 @@ async def trigger_reindex():
 @rag_blueprint.post("/index-obsidian")
 @admin_required
 async def trigger_obsidian_index():
-    """Index all Obsidian markdown documents into vector store. Admin only."""
+    """Incrementally sync Obsidian documents into vector store. Admin only."""
     try:
-        result = await index_obsidian_documents()
+        result = await sync_obsidian_documents()
         stats = get_vector_store_stats()
         return jsonify({"status": "success", "result": result, "stats": stats})
     except Exception as e:

blueprints/rag/logic.py

@@ -1,11 +1,19 @@
 import datetime
+import logging
 import os
+import re
+import time
+from pathlib import Path
 
 from dotenv import load_dotenv
-from langchain_chroma import Chroma
 from langchain_core.documents import Document
 from langchain_openai import OpenAIEmbeddings
-from langchain_text_splitters import RecursiveCharacterTextSplitter
+from langchain_postgres import PGVector
+from langchain_text_splitters import (
+    MarkdownHeaderTextSplitter,
+    RecursiveCharacterTextSplitter,
+)
+from sqlalchemy import create_engine, text
 
 from .fetchers import PaperlessNGXService
 from utils.obsidian_service import ObsidianService
@@ -13,13 +21,51 @@ from utils.obsidian_service import ObsidianService
 # Load environment variables
 load_dotenv()
 
-embeddings = OpenAIEmbeddings(model="text-embedding-3-small")
+logger = logging.getLogger(__name__)
 
-vector_store = Chroma(
-    collection_name="simba_docs",
-    embedding_function=embeddings,
-    persist_directory=os.getenv("CHROMADB_PATH", ""),
+_embedding_server_url = os.getenv("EMBEDDING_SERVER_URL")
+_embedding_model = os.getenv("EMBEDDING_MODEL_NAME", "text-embedding-3-small")
+
+if _embedding_server_url:
+    embeddings = OpenAIEmbeddings(
+        model=_embedding_model,
+        base_url=_embedding_server_url,
+        api_key="not-needed",
+        check_embedding_ctx_length=False,
+    )
+else:
+    embeddings = OpenAIEmbeddings(model=_embedding_model)
+
+# Convert Tortoise-style postgres:// URL to SQLAlchemy-style postgresql+psycopg://
+_db_url = os.getenv(
+    "DATABASE_URL", "postgres://raggr:raggr_dev_password@localhost:5432/raggr"
 )
+_pgvector_url = _db_url.replace("postgres://", "postgresql+psycopg://")
+
+# Lazy-initialized vector store (defers DB connection to first use)
+_vector_store = None
+
+
+def _get_vector_store() -> PGVector:
+    global _vector_store
+    if _vector_store is None:
+        _vector_store = PGVector(
+            embeddings=embeddings,
+            collection_name="simba_docs",
+            connection=_pgvector_url,
+            use_jsonb=True,
+            create_extension=False,  # created by docker init script
+            async_mode=True,
+        )
+    return _vector_store
+
+
+def _get_engine():
+    """Get a SQLAlchemy engine for direct queries."""
+    if not hasattr(_get_engine, "_engine"):
+        _get_engine._engine = create_engine(_pgvector_url)
+    return _get_engine._engine
+
 
 text_splitter = RecursiveCharacterTextSplitter(
     chunk_size=1000,  # chunk size (characters)
@@ -27,6 +73,62 @@ text_splitter = RecursiveCharacterTextSplitter(
     add_start_index=True,  # track index in original document
 )
 
+md_header_splitter = MarkdownHeaderTextSplitter(
+    headers_to_split_on=[("#", "h1"), ("##", "h2"), ("###", "h3")],
+    strip_headers=False,
+)
+
+md_chunk_splitter = RecursiveCharacterTextSplitter(
+    chunk_size=1000,
+    chunk_overlap=200,
+    add_start_index=True,
+)
+
+
+def _split_markdown_document(doc: Document) -> list[Document]:
+    """Split a markdown document by headers first, then by size.
+
+    Prepends the note filename to each chunk so chunks are self-contained.
+    """
+    note_name = (
+        Path(doc.metadata.get("filepath", "")).stem
+        if doc.metadata.get("filepath")
+        else ""
+    )
+
+    # Split by markdown headers
+    header_splits = md_header_splitter.split_text(doc.page_content)
+
+    # Carry over original document metadata to each header split
+    for split in header_splits:
+        split.metadata.update(doc.metadata)
+
+    # Then apply size-based splitting on large sections
+    sized_splits = md_chunk_splitter.split_documents(header_splits)
+
+    # Prepend note name for self-contained context
+    if note_name:
+        for split in sized_splits:
+            split.page_content = f"[Note: {note_name}]\n{split.page_content}"
+
+    return sized_splits
+
+
+def _get_collection_id():
+    """Get the UUID of our collection from the langchain_pg_collection table."""
+    engine = _get_engine()
+    try:
+        with engine.connect() as conn:
+            result = conn.execute(
+                text("SELECT uuid FROM langchain_pg_collection WHERE name = :name"),
+                {"name": "simba_docs"},
+            )
+            row = result.fetchone()
+            return row[0] if row else None
+    except Exception:
+        # Table doesn't exist yet (first run before any indexing)
+        return None
+
 
 def date_to_epoch(date_str: str) -> float:
     split_date = date_str.split("-")
@@ -49,6 +151,7 @@ async def fetch_documents_from_paperless_ngx() -> list[Document]:
     documents = []
     for doc in data:
         metadata = {
+            "source": "paperless",
             "created_date": date_to_epoch(doc["created_date"]),
             "filename": doc["original_file_name"],
             "document_type": doctypes.get(doc["document_type"], ""),
@@ -58,12 +161,54 @@ async def fetch_documents_from_paperless_ngx() -> list[Document]:
     return documents
 
 
+def _make_serializable(value):
+    """Convert a value to a JSON-serializable type."""
+    if isinstance(value, (str, int, float, bool, type(None))):
+        return value
+    if isinstance(value, (list, tuple)):
+        return [_make_serializable(v) for v in value]
+    if isinstance(value, dict):
+        return {k: _make_serializable(v) for k, v in value.items()}
+    return str(value)
+
+
+def _sanitize_text(text_content: str) -> str:
+    """Strip non-printable and invalid characters that break embedding tokenizers."""
+    # Remove null bytes and control characters (keep newlines and tabs)
+    text_content = re.sub(r"[\x00-\x08\x0b\x0c\x0e-\x1f\x7f-\x9f]", "", text_content)
+    # Remove Unicode surrogates and other problematic Unicode
+    text_content = re.sub(r"[\ud800-\udfff\ufffe\uffff]", "", text_content)
+    # Remove replacement character clusters
+    text_content = text_content.replace("\ufffd", "")
+    # Collapse excessive whitespace
+    text_content = re.sub(r" {3,}", "  ", text_content)
+    return text_content.strip()
+
+
+def _sanitize_documents(documents: list[Document]) -> list[Document]:
+    """Sanitize page_content of all documents for embedding compatibility."""
+    for doc in documents:
+        doc.page_content = _sanitize_text(doc.page_content)
+    return [doc for doc in documents if doc.page_content]
+
+
 async def index_documents():
     """Index Paperless-NGX documents into vector store."""
     documents = await fetch_documents_from_paperless_ngx()
 
     splits = text_splitter.split_documents(documents)
-    await vector_store.aadd_documents(documents=splits)
+    splits = _sanitize_documents(splits)
+    logger.info(f"Indexing {len(splits)} chunks from {len(documents)} documents")
+    vector_store = _get_vector_store()
+    for i, split in enumerate(splits):
+        try:
+            await vector_store.aadd_documents(documents=[split])
+        except Exception as e:
+            logger.error(
+                f"Failed to embed chunk {i} from {split.metadata.get('filename', 'unknown')}: {e}"
+            )
+            logger.debug(f"Chunk content preview: {split.page_content[:200]!r}")
+            raise
 
 
 async def fetch_obsidian_documents() -> list[Document]:
@@ -85,20 +230,29 @@ async def fetch_obsidian_documents() -> list[Document]:
             parsed = obsidian_service.parse_markdown(content, md_path)
 
             # Create LangChain Document with obsidian source
+            metadata = {
+                "source": "obsidian",
+                "filepath": parsed["filepath"],
+                "folder": str(Path(parsed["filepath"]).parent)
+                if parsed["filepath"]
+                else "",
+                "tags": parsed["tags"],
+                "created_at": parsed["metadata"].get("created_at"),
+                "indexed_at": time.time(),
+                **{
+                    k: v
+                    for k, v in parsed["metadata"].items()
+                    if k not in ["created_at", "created_by"]
+                },
+            }
             document = Document(
                 page_content=parsed["content"],
-                metadata={
-                    "source": "obsidian",
-                    "filepath": parsed["filepath"],
-                    "tags": parsed["tags"],
-                    "created_at": parsed["metadata"].get("created_at"),
-                    **{k: v for k, v in parsed["metadata"].items() if k not in ["created_at", "created_by"]},
-                },
+                metadata=_make_serializable(metadata),
             )
             documents.append(document)
 
         except Exception as e:
-            print(f"Error reading {md_path}: {e}")
+            logger.warning(f"Error reading {md_path}: {e}")
             continue
 
     return documents
@@ -109,27 +263,168 @@ async def index_obsidian_documents():
 
     Deletes existing obsidian source chunks before re-indexing.
     """
-    obsidian_service = ObsidianService()
     documents = await fetch_obsidian_documents()
 
     if not documents:
-        print("No Obsidian documents found to index")
+        logger.info("No Obsidian documents found to index")
         return {"indexed": 0}
 
     # Delete existing obsidian chunks
-    existing_results = vector_store.get(where={"source": "obsidian"})
-    if existing_results.get("ids"):
-        await vector_store.adelete(existing_results["ids"])
+    delete_documents_by_metadata("source", "obsidian")
 
-    # Split and index documents
-    splits = text_splitter.split_documents(documents)
+    # Split using markdown-aware chunking, sanitize, and index
+    splits = []
+    for doc in documents:
+        splits.extend(_split_markdown_document(doc))
+    splits = _sanitize_documents(splits)
+    vector_store = _get_vector_store()
     await vector_store.aadd_documents(documents=splits)
 
     return {"indexed": len(documents)}
 
 
-async def query_vector_store(query: str):
-    retrieved_docs = await vector_store.asimilarity_search(query, k=2)
+# In-memory cache of indexed obsidian files: {filepath: indexed_at}
+_obsidian_index_cache: dict[str, float] = {}
+
+
+def _load_obsidian_index_cache() -> dict[str, float]:
+    """Load indexed obsidian files from DB into cache (cold start only)."""
+    collection_id = _get_collection_id()
+    if not collection_id:
+        return {}
+    engine = _get_engine()
+    with engine.connect() as conn:
+        result = conn.execute(
+            text(
+                "SELECT DISTINCT cmetadata->>'filepath' AS filepath, "
+                "MAX((cmetadata->>'indexed_at')::float) AS indexed_at "
+                "FROM langchain_pg_embedding "
+                "WHERE collection_id = :cid AND cmetadata->>'source' = 'obsidian' "
+                "GROUP BY cmetadata->>'filepath'"
+            ),
+            {"cid": collection_id},
+        )
+        return {row[0]: row[1] for row in result if row[0] is not None}
+
+
+async def sync_obsidian_documents() -> dict[str, int]:
+    """Incrementally sync Obsidian documents to pgvector.
+
+    Compares file mtimes against stored indexed_at timestamps to only
+    re-index changed/new files and remove deleted ones.
+
+    Returns:
+        Dict with counts of added, updated, and deleted files.
+    """
+    global _obsidian_index_cache
+
+    obsidian_service = ObsidianService()
+
+    # Load cache from DB on first run
+    if not _obsidian_index_cache:
+        _obsidian_index_cache = _load_obsidian_index_cache()
+
+    # Build map of current vault files -> mtime
+    vault_files: dict[str, float] = {}
+    for md_path in obsidian_service.walk_vault():
+        vault_files[str(md_path)] = md_path.stat().st_mtime
+
+    added = 0
+    updated = 0
+    deleted = 0
+
+    # Find files to add or update
+    files_to_index: list[str] = []
+    for filepath, mtime in vault_files.items():
+        indexed_at = _obsidian_index_cache.get(filepath)
+        if indexed_at is None:
+            files_to_index.append(filepath)
+            added += 1
+        elif mtime > indexed_at:
+            # Delete old chunks first
+            delete_documents_by_metadata("filepath", filepath)
+            files_to_index.append(filepath)
+            updated += 1
+
+    # Find deleted files (in cache but not on disk)
+    for filepath in list(_obsidian_index_cache):
+        if filepath not in vault_files:
+            delete_documents_by_metadata("filepath", filepath)
+            del _obsidian_index_cache[filepath]
+            deleted += 1
+
+    # Index new/changed files
+    if files_to_index:
+        now = time.time()
+        documents = []
+        for filepath in files_to_index:
+            try:
+                with open(filepath, "r", encoding="utf-8") as f:
+                    content = f.read()
+                parsed = obsidian_service.parse_markdown(content, filepath)
+                metadata = {
+                    "source": "obsidian",
+                    "filepath": parsed["filepath"],
+                    "folder": str(Path(parsed["filepath"]).parent)
+                    if parsed["filepath"]
+                    else "",
+                    "tags": parsed["tags"],
+                    "created_at": parsed["metadata"].get("created_at"),
+                    "indexed_at": now,
+                    **{
+                        k: v
+                        for k, v in parsed["metadata"].items()
+                        if k not in ["created_at", "created_by"]
+                    },
+                }
+                document = Document(
+                    page_content=parsed["content"],
+                    metadata=_make_serializable(metadata),
+                )
+                documents.append(document)
+            except Exception as e:
+                logger.warning(f"Error reading {filepath}: {e}")
+                continue
+
+        if documents:
+            splits = []
+            for doc in documents:
+                splits.extend(_split_markdown_document(doc))
+            splits = _sanitize_documents(splits)
+            if splits:
+                vector_store = _get_vector_store()
+                await vector_store.aadd_documents(documents=splits)
+
+        # Update cache for successfully processed files
+        for filepath in files_to_index:
+            _obsidian_index_cache[filepath] = now
+
+    logger.info(
+        f"Obsidian sync complete: {added} added, {updated} updated, {deleted} deleted"
+    )
+    return {"added": added, "updated": updated, "deleted": deleted}
+
+
+async def query_vector_store(
+    query: str,
+    source: str | None = None,
+    k: int = 8,
+):
+    """Query the vector store with optional source filtering and MMR.
+
+    Args:
+        query: Search query text
+        source: Filter by source metadata (e.g., "obsidian", "paperless")
+        k: Number of results to return
+    """
+    vector_store = _get_vector_store()
+    filter_dict = {"source": source} if source else None
+    retrieved_docs = await vector_store.amax_marginal_relevance_search(
+        query,
+        k=k,
+        fetch_k=k * 3,
+        filter=filter_dict,
+    )
     serialized = "\n\n".join(
         (f"Source: {doc.metadata}\nContent: {doc.page_content}")
         for doc in retrieved_docs
@@ -137,33 +432,80 @@ async def query_vector_store(query: str):
     return serialized, retrieved_docs
 
 
+def delete_all_documents():
+    """Delete all documents from the vector store collection."""
+    collection_id = _get_collection_id()
+    if not collection_id:
+        return
+    engine = _get_engine()
+    with engine.connect() as conn:
+        conn.execute(
+            text("DELETE FROM langchain_pg_embedding WHERE collection_id = :cid"),
+            {"cid": collection_id},
+        )
+        conn.commit()
+
+
+def delete_documents_by_metadata(key: str, value: str):
+    """Delete documents matching a metadata key/value pair."""
+    collection_id = _get_collection_id()
+    if not collection_id:
+        return
+    engine = _get_engine()
+    with engine.connect() as conn:
+        conn.execute(
+            text(
+                "DELETE FROM langchain_pg_embedding "
+                "WHERE collection_id = :cid AND cmetadata->>:key = :value"
+            ),
+            {"cid": collection_id, "key": key, "value": value},
+        )
+        conn.commit()
+
+
 def get_vector_store_stats():
     """Get statistics about the vector store."""
-    collection = vector_store._collection
-    count = collection.count()
+    collection_id = _get_collection_id()
+    count = 0
+    if collection_id:
+        engine = _get_engine()
+        with engine.connect() as conn:
+            result = conn.execute(
+                text(
+                    "SELECT COUNT(*) FROM langchain_pg_embedding WHERE collection_id = :cid"
+                ),
+                {"cid": collection_id},
+            )
+            count = result.scalar()
     return {
         "total_documents": count,
-        "collection_name": collection.name,
+        "collection_name": "simba_docs",
     }
 
 
 def list_all_documents(limit: int = 10):
     """List documents in the vector store with their metadata."""
-    collection = vector_store._collection
-    results = collection.get(limit=limit, include=["metadatas", "documents"])
+    collection_id = _get_collection_id()
+    if not collection_id:
+        return []
 
-    documents = []
-    for i, doc_id in enumerate(results["ids"]):
-        documents.append(
-            {
-                "id": doc_id,
-                "metadata": results["metadatas"][i]
-                if results.get("metadatas")
-                else None,
-                "content_preview": results["documents"][i][:200]
-                if results.get("documents")
-                else None,
-            }
+    engine = _get_engine()
+    with engine.connect() as conn:
+        result = conn.execute(
+            text(
+                "SELECT id, document, cmetadata FROM langchain_pg_embedding "
+                "WHERE collection_id = :cid LIMIT :limit"
+            ),
+            {"cid": collection_id, "limit": limit},
         )
+        documents = []
+        for row in result:
+            documents.append(
+                {
+                    "id": str(row[0]),
+                    "metadata": row[2],
+                    "content_preview": row[1][:200] if row[1] else None,
+                }
+            )
 
     return documents

blueprints/scheduled_messages/__init__.py

@@ -0,0 +1,208 @@
+import hmac
+import logging
+import os
+from datetime import datetime, timezone
+
+from quart import Blueprint, request, jsonify
+
+from blueprints.users.decorators import admin_required
+from .models import ScheduledMessage, MessageChannel, MessageStatus, Recurrence
+
+scheduled_messages_blueprint = Blueprint(
+    "scheduled_messages_api", __name__, url_prefix="/api/scheduled-messages"
+)
+
+logger = logging.getLogger(__name__)
+
+
+def _serialize(msg: ScheduledMessage) -> dict:
+    return {
+        "id": str(msg.id),
+        "recipient": msg.recipient,
+        "channel": msg.channel.value,
+        "content": msg.content,
+        "subject": msg.subject,
+        "scheduled_at": msg.scheduled_at.isoformat(),
+        "status": msg.status.value,
+        "recurrence": msg.recurrence.value,
+        "use_agent": msg.use_agent,
+        "error_message": msg.error_message,
+        "created_at": msg.created_at.isoformat(),
+        "updated_at": msg.updated_at.isoformat(),
+    }
+
+
+@scheduled_messages_blueprint.route("/", methods=["GET"])
+@admin_required
+async def list_messages():
+    messages = await ScheduledMessage.all().order_by("-scheduled_at")
+    return jsonify([_serialize(m) for m in messages])
+
+
+@scheduled_messages_blueprint.route("/", methods=["POST"])
+@admin_required
+async def create_message():
+    data = await request.get_json()
+    if not data:
+        return jsonify({"error": "Invalid payload"}), 400
+
+    recipient = (data.get("recipient") or "").strip()
+    channel = data.get("channel")
+    content = (data.get("content") or "").strip()
+    subject = (data.get("subject") or "").strip() or None
+    scheduled_at_str = data.get("scheduled_at")
+
+    recurrence_str = data.get("recurrence", "none")
+
+    if not recipient or not channel or not content or not scheduled_at_str:
+        return jsonify(
+            {"error": "recipient, channel, content, and scheduled_at are required"}
+        ), 400
+
+    try:
+        channel_enum = MessageChannel(channel)
+    except ValueError:
+        return jsonify(
+            {"error": f"Invalid channel: {channel}. Must be 'imessage' or 'email'"}
+        ), 400
+
+    try:
+        recurrence_enum = Recurrence(recurrence_str)
+    except ValueError:
+        return jsonify(
+            {
+                "error": f"Invalid recurrence: {recurrence_str}. Must be 'none', 'daily', 'weekly', or 'monthly'"
+            }
+        ), 400
+
+    if channel_enum == MessageChannel.EMAIL and not subject:
+        return jsonify({"error": "subject is required for email messages"}), 400
+
+    try:
+        scheduled_at = datetime.fromisoformat(scheduled_at_str)
+        if scheduled_at.tzinfo is None:
+            scheduled_at = scheduled_at.replace(tzinfo=timezone.utc)
+    except ValueError:
+        return jsonify({"error": "Invalid scheduled_at format"}), 400
+
+    if scheduled_at <= datetime.now(timezone.utc):
+        return jsonify({"error": "scheduled_at must be in the future"}), 400
+
+    from quart_jwt_extended import get_jwt_identity
+
+    user_id = get_jwt_identity()
+
+    use_agent = bool(data.get("use_agent", False))
+
+    msg = await ScheduledMessage.create(
+        recipient=recipient,
+        channel=channel_enum,
+        content=content,
+        subject=subject,
+        scheduled_at=scheduled_at,
+        recurrence=recurrence_enum,
+        use_agent=use_agent,
+        created_by_id=user_id,
+    )
+
+    from utils.cronicle import create_message_event
+
+    await create_message_event(str(msg.id), msg.scheduled_at, recurrence_enum.value)
+
+    return jsonify(_serialize(msg)), 201
+
+
+@scheduled_messages_blueprint.route("/<msg_id>", methods=["PUT"])
+@admin_required
+async def update_message(msg_id: str):
+    msg = await ScheduledMessage.get_or_none(id=msg_id)
+    if not msg:
+        return jsonify({"error": "Not found"}), 404
+
+    if msg.status not in (MessageStatus.PENDING, MessageStatus.FAILED):
+        return jsonify({"error": "Can only update pending or failed messages"}), 400
+
+    data = await request.get_json()
+    if not data:
+        return jsonify({"error": "Invalid payload"}), 400
+
+    rescheduled = False
+    if "recipient" in data:
+        msg.recipient = data["recipient"].strip()
+    if "channel" in data:
+        try:
+            msg.channel = MessageChannel(data["channel"])
+        except ValueError:
+            return jsonify({"error": f"Invalid channel: {data['channel']}"}), 400
+    if "content" in data:
+        msg.content = data["content"].strip()
+    if "subject" in data:
+        msg.subject = data["subject"].strip() or None
+    if "recurrence" in data:
+        try:
+            msg.recurrence = Recurrence(data["recurrence"])
+        except ValueError:
+            return jsonify({"error": f"Invalid recurrence: {data['recurrence']}"}), 400
+    if "use_agent" in data:
+        msg.use_agent = bool(data["use_agent"])
+    if "scheduled_at" in data:
+        try:
+            scheduled_at = datetime.fromisoformat(data["scheduled_at"])
+            if scheduled_at.tzinfo is None:
+                scheduled_at = scheduled_at.replace(tzinfo=timezone.utc)
+            if scheduled_at <= datetime.now(timezone.utc):
+                return jsonify({"error": "scheduled_at must be in the future"}), 400
+            msg.scheduled_at = scheduled_at
+            rescheduled = True
+        except ValueError:
+            return jsonify({"error": "Invalid scheduled_at format"}), 400
+    if "status" in data and data["status"] == "cancelled":
+        msg.status = MessageStatus.CANCELLED
+    elif rescheduled:
+        msg.status = MessageStatus.PENDING
+        msg.error_message = None
+
+    if msg.channel == MessageChannel.EMAIL and not msg.subject:
+        return jsonify({"error": "subject is required for email messages"}), 400
+
+    await msg.save()
+
+    if rescheduled and msg.status == MessageStatus.PENDING:
+        from utils.cronicle import create_message_event
+
+        await create_message_event(str(msg.id), msg.scheduled_at, msg.recurrence.value)
+
+    return jsonify(_serialize(msg))
+
+
+def _check_cron_secret() -> bool:
+    expected = os.environ.get("CRON_SECRET", "")
+    if not expected:
+        return False
+    provided = request.headers.get("X-Cron-Secret", "")
+    return hmac.compare_digest(provided.encode(), expected.encode())
+
+
+@scheduled_messages_blueprint.route("/trigger", methods=["POST"])
+async def trigger_due_messages():
+    if not _check_cron_secret():
+        return jsonify({"error": "Unauthorized"}), 401
+
+    from .scheduler import process_due_messages
+
+    result = await process_due_messages()
+    return jsonify(result)
+
+
+@scheduled_messages_blueprint.route("/<msg_id>", methods=["DELETE"])
+@admin_required
+async def delete_message(msg_id: str):
+    msg = await ScheduledMessage.get_or_none(id=msg_id)
+    if not msg:
+        return jsonify({"error": "Not found"}), 404
+
+    if msg.status not in (MessageStatus.PENDING, MessageStatus.CANCELLED):
+        return jsonify({"error": "Can only delete pending or cancelled messages"}), 400
+
+    await msg.delete()
+    return jsonify({"status": "deleted"})

blueprints/scheduled_messages/models.py

@@ -0,0 +1,48 @@
+import enum
+
+from tortoise import fields
+from tortoise.models import Model
+
+
+class MessageChannel(enum.Enum):
+    IMESSAGE = "imessage"
+    EMAIL = "email"
+
+
+class MessageStatus(enum.Enum):
+    PENDING = "pending"
+    SENT = "sent"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
+
+
+class Recurrence(enum.Enum):
+    NONE = "none"
+    DAILY = "daily"
+    WEEKLY = "weekly"
+    MONTHLY = "monthly"
+
+
+class ScheduledMessage(Model):
+    id = fields.UUIDField(primary_key=True)
+    recipient = fields.CharField(max_length=255)
+    channel = fields.CharEnumField(enum_type=MessageChannel, max_length=20)
+    content = fields.TextField()
+    subject = fields.CharField(max_length=255, null=True)
+    scheduled_at = fields.DatetimeField()
+    status = fields.CharEnumField(
+        enum_type=MessageStatus, max_length=20, default=MessageStatus.PENDING
+    )
+    recurrence = fields.CharEnumField(
+        enum_type=Recurrence, max_length=20, default=Recurrence.NONE
+    )
+    use_agent = fields.BooleanField(default=False)
+    error_message = fields.TextField(null=True)
+    created_by = fields.ForeignKeyField(
+        "models.User", related_name="scheduled_messages"
+    )
+    created_at = fields.DatetimeField(auto_now_add=True)
+    updated_at = fields.DatetimeField(auto_now=True)
+
+    class Meta:
+        table = "scheduled_messages"

blueprints/scheduled_messages/scheduler.py

@@ -0,0 +1,102 @@
+import logging
+import uuid
+from datetime import datetime, timezone
+from dateutil.relativedelta import relativedelta
+from quart import current_app
+
+from .models import ScheduledMessage, MessageChannel, MessageStatus, Recurrence
+
+logger = logging.getLogger(__name__)
+
+RECURRENCE_DELTAS = {
+    Recurrence.DAILY: relativedelta(days=1),
+    Recurrence.WEEKLY: relativedelta(weeks=1),
+    Recurrence.MONTHLY: relativedelta(months=1),
+}
+
+
+async def _run_agent(prompt: str, thread_id: str) -> str:
+    response = await current_app.main_agent.ainvoke(
+        {"messages": [{"role": "user", "content": prompt}]},
+        config={"configurable": {"thread_id": thread_id}},
+    )
+    return response.get("messages", [])[-1].content
+
+
+async def _schedule_next_occurrence(msg: ScheduledMessage):
+    delta = RECURRENCE_DELTAS.get(msg.recurrence)
+    if not delta:
+        return
+
+    next_at = msg.scheduled_at + delta
+    now = datetime.now(timezone.utc)
+    while next_at <= now:
+        next_at += delta
+
+    await ScheduledMessage.create(
+        recipient=msg.recipient,
+        channel=msg.channel,
+        content=msg.content,
+        subject=msg.subject,
+        scheduled_at=next_at,
+        recurrence=msg.recurrence,
+        use_agent=msg.use_agent,
+        created_by_id=msg.created_by_id,
+    )
+    logger.info(
+        f"Scheduled next {msg.recurrence.value} occurrence for {msg.id} at {next_at.isoformat()}"
+    )
+
+
+async def process_due_messages() -> dict:
+    """Process all currently due pending messages. Returns a result summary."""
+    now = datetime.now(timezone.utc)
+    due = await ScheduledMessage.filter(
+        status=MessageStatus.PENDING,
+        scheduled_at__lte=now,
+    ).all()
+
+    sent, failed = 0, 0
+    for msg in due:
+        try:
+            send_content = msg.content
+
+            if msg.use_agent:
+                send_content = await _run_agent(
+                    msg.content, f"scheduled-{uuid.uuid4()}"
+                )
+
+            if msg.channel == MessageChannel.IMESSAGE:
+                from blueprints.imessage import send_imessage
+                from utils.strip_markdown import strip_markdown
+
+                await send_imessage(msg.recipient, strip_markdown(send_content))
+
+            elif msg.channel == MessageChannel.EMAIL:
+                from blueprints.email import send_email_reply
+
+                await send_email_reply(
+                    to=msg.recipient,
+                    subject=msg.subject or "(no subject)",
+                    body=send_content,
+                )
+
+            msg.status = MessageStatus.SENT
+            msg.error_message = None
+            await msg.save()
+            logger.info(
+                f"Sent scheduled {msg.channel.value} message {msg.id} to {msg.recipient}"
+            )
+            sent += 1
+
+            if msg.recurrence != Recurrence.NONE:
+                await _schedule_next_occurrence(msg)
+
+        except Exception as e:
+            msg.status = MessageStatus.FAILED
+            msg.error_message = str(e)
+            await msg.save()
+            logger.error(f"Failed to send scheduled message {msg.id}: {e}")
+            failed += 1
+
+    return {"sent": sent, "failed": failed}

blueprints/users/__init__.py

@@ -7,7 +7,8 @@ from quart_jwt_extended import (
 )
 from .models import User
 from .oidc_service import OIDCUserService
-from .decorators import admin_required
+from .oidc_state import consume_oidc_state, save_oidc_state
+from .decorators import admin_required, jwt_access_required
 from config.oidc_config import oidc_config
 import os
 import secrets
@@ -19,10 +20,6 @@ import base64
 
 user_blueprint = Blueprint("user_api", __name__, url_prefix="/api/user")
 
-# In-memory storage for OIDC state/PKCE (production: use Redis or database)
-# Format: {state: {"pkce_verifier": str, "redirect_after_login": str}}
-_oidc_sessions = {}
-
 
 @user_blueprint.route("/oidc/login", methods=["GET"])
 async def oidc_login():
@@ -47,11 +44,8 @@ async def oidc_login():
         # Generate state for CSRF protection
         state = secrets.token_urlsafe(32)
 
-        # Store PKCE verifier and state for callback validation
-        _oidc_sessions[state] = {
-            "pkce_verifier": code_verifier,
-            "redirect_after_login": request.args.get("redirect", "/"),
-        }
+        # Persist PKCE verifier keyed by state for callback validation
+        await save_oidc_state(state, code_verifier)
 
         # Get authorization endpoint from discovery
         discovery = await oidc_config.get_discovery_document()
@@ -93,12 +87,10 @@ async def oidc_callback():
         return jsonify({"error": "Missing code or state"}), 400
 
     # Validate state and retrieve PKCE verifier
-    session = _oidc_sessions.pop(state, None)
-    if not session:
+    pkce_verifier = await consume_oidc_state(state)
+    if not pkce_verifier:
         return jsonify({"error": "Invalid or expired state"}), 400
 
-    pkce_verifier = session["pkce_verifier"]
-
     # Exchange authorization code for tokens
     discovery = await oidc_config.get_discovery_document()
     token_endpoint = discovery.get("token_endpoint")
@@ -206,38 +198,48 @@ async def login():
 
 
 @user_blueprint.route("/me", methods=["GET"])
-@jwt_refresh_token_required
+@jwt_access_required
 async def me():
     user_id = get_jwt_identity()
     user = await User.get_or_none(id=user_id)
     if not user:
         return jsonify({"error": "User not found"}), 404
-    return jsonify({
-        "id": str(user.id),
-        "username": user.username,
-        "email": user.email,
-        "is_admin": user.is_admin(),
-    })
+    return jsonify(
+        {
+            "id": str(user.id),
+            "username": user.username,
+            "email": user.email,
+            "is_admin": user.is_admin(),
+        }
+    )
 
 
 @user_blueprint.route("/admin/users", methods=["GET"])
 @admin_required
 async def list_users():
     from blueprints.email.helpers import get_user_email_address
+
     users = await User.all().order_by("username")
     mailgun_domain = os.getenv("MAILGUN_DOMAIN", "")
-    return jsonify([
-        {
-            "id": str(u.id),
-            "username": u.username,
-            "email": u.email,
-            "whatsapp_number": u.whatsapp_number,
-            "auth_provider": u.auth_provider,
-            "email_enabled": u.email_enabled,
-            "email_address": get_user_email_address(u.email_hmac_token, mailgun_domain) if u.email_hmac_token and u.email_enabled else None,
-        }
-        for u in users
-    ])
+    return jsonify(
+        [
+            {
+                "id": str(u.id),
+                "username": u.username,
+                "email": u.email,
+                "whatsapp_number": u.whatsapp_number,
+                "imessage_number": u.imessage_number,
+                "auth_provider": u.auth_provider,
+                "email_enabled": u.email_enabled,
+                "email_address": get_user_email_address(
+                    u.email_hmac_token, mailgun_domain
+                )
+                if u.email_hmac_token and u.email_enabled
+                else None,
+            }
+            for u in users
+        ]
+    )
 
 
 @user_blueprint.route("/admin/users/<user_id>/whatsapp", methods=["PUT"])
@@ -254,17 +256,21 @@ async def set_whatsapp(user_id):
 
     conflict = await User.filter(whatsapp_number=number).exclude(id=user_id).first()
     if conflict:
-        return jsonify({"error": "That WhatsApp number is already linked to another account"}), 409
+        return jsonify(
+            {"error": "That WhatsApp number is already linked to another account"}
+        ), 409
 
     user.whatsapp_number = number
     await user.save()
-    return jsonify({
-        "id": str(user.id),
-        "username": user.username,
-        "email": user.email,
-        "whatsapp_number": user.whatsapp_number,
-        "auth_provider": user.auth_provider,
-    })
+    return jsonify(
+        {
+            "id": str(user.id),
+            "username": user.username,
+            "email": user.email,
+            "whatsapp_number": user.whatsapp_number,
+            "auth_provider": user.auth_provider,
+        }
+    )
 
 
 @user_blueprint.route("/admin/users/<user_id>/whatsapp", methods=["DELETE"])
@@ -279,11 +285,55 @@ async def unlink_whatsapp(user_id):
     return jsonify({"ok": True})
 
 
+@user_blueprint.route("/admin/users/<user_id>/imessage", methods=["PUT"])
+@admin_required
+async def set_imessage(user_id):
+    data = await request.get_json()
+    number = (data or {}).get("imessage_number", "").strip()
+    if not number:
+        return jsonify({"error": "imessage_number is required"}), 400
+
+    user = await User.get_or_none(id=user_id)
+    if not user:
+        return jsonify({"error": "User not found"}), 404
+
+    conflict = await User.filter(imessage_number=number).exclude(id=user_id).first()
+    if conflict:
+        return jsonify(
+            {"error": "That iMessage number is already linked to another account"}
+        ), 409
+
+    user.imessage_number = number
+    await user.save()
+    return jsonify(
+        {
+            "id": str(user.id),
+            "username": user.username,
+            "email": user.email,
+            "imessage_number": user.imessage_number,
+            "auth_provider": user.auth_provider,
+        }
+    )
+
+
+@user_blueprint.route("/admin/users/<user_id>/imessage", methods=["DELETE"])
+@admin_required
+async def unlink_imessage(user_id):
+    user = await User.get_or_none(id=user_id)
+    if not user:
+        return jsonify({"error": "User not found"}), 404
+
+    user.imessage_number = None
+    await user.save()
+    return jsonify({"ok": True})
+
+
 @user_blueprint.route("/admin/users/<user_id>/email", methods=["PUT"])
 @admin_required
 async def toggle_email(user_id):
     """Enable email channel for a user, generating an HMAC token."""
     from blueprints.email.helpers import generate_email_token, get_user_email_address
+
     user = await User.get_or_none(id=user_id)
     if not user:
         return jsonify({"error": "User not found"}), 404
@@ -299,15 +349,19 @@ async def toggle_email(user_id):
     user.email_enabled = True
     await user.save()
 
-    return jsonify({
-        "id": str(user.id),
-        "username": user.username,
-        "email": user.email,
-        "whatsapp_number": user.whatsapp_number,
-        "auth_provider": user.auth_provider,
-        "email_enabled": user.email_enabled,
-        "email_address": get_user_email_address(user.email_hmac_token, mailgun_domain),
-    })
+    return jsonify(
+        {
+            "id": str(user.id),
+            "username": user.username,
+            "email": user.email,
+            "whatsapp_number": user.whatsapp_number,
+            "auth_provider": user.auth_provider,
+            "email_enabled": user.email_enabled,
+            "email_address": get_user_email_address(
+                user.email_hmac_token, mailgun_domain
+            ),
+        }
+    )
 
 
 @user_blueprint.route("/admin/users/<user_id>/email", methods=["DELETE"])

blueprints/users/decorators.py

@@ -4,10 +4,47 @@ Authentication decorators for role-based access control.
 
 from functools import wraps
 from quart import jsonify
-from quart_jwt_extended import jwt_refresh_token_required, get_jwt_identity
+from quart_jwt_extended import get_jwt_identity
+from quart_jwt_extended.exceptions import WrongTokenError
+from quart_jwt_extended.view_decorators import (
+    verify_jwt_in_request,
+    verify_jwt_refresh_token_in_request,
+)
 from .models import User
 
 
+def jwt_access_required(fn):
+    """
+    Protect an endpoint with the (1h) access token.
+
+    TRANSITIONAL: this also accepts the refresh token, so an old frontend
+    (which sends the refresh token on every call) keeps working against this
+    backend, including tabs that stay open across deploys.
+
+    It does NOT make a new frontend work against an older backend: routes
+    still on `@jwt_refresh_token_required` answer an access token with 422,
+    which the frontend does not retry. So this backend must be live on both
+    colors before the access-token frontend ships (deploy in two releases).
+
+    TODO: once the access-token frontend has been live for a while, replace
+    the body with `await verify_jwt_in_request()` (i.e. plain `@jwt_required`)
+    and map WrongTokenError to 401, so a stale tab still sending the refresh
+    token refreshes and retries instead of failing with 422.
+    """
+
+    @wraps(fn)
+    async def wrapper(*args, **kwargs):
+        try:
+            await verify_jwt_in_request()
+        except WrongTokenError:
+            # Legacy client sent the refresh token. Expired/invalid tokens
+            # still raise from verify_jwt_in_request and are not retried here.
+            await verify_jwt_refresh_token_in_request()
+        return await fn(*args, **kwargs)
+
+    return wrapper
+
+
 def admin_required(fn):
     """
     Decorator that requires the user to be an admin (member of lldap_admin group).
@@ -15,7 +52,7 @@ def admin_required(fn):
     """
 
     @wraps(fn)
-    @jwt_refresh_token_required
+    @jwt_access_required
     async def wrapper(*args, **kwargs):
         user_id = get_jwt_identity()
         user = await User.get_or_none(id=user_id)

blueprints/users/models.py

@@ -10,11 +10,18 @@ class User(Model):
     username = fields.CharField(max_length=255)
     password = fields.BinaryField(null=True)  # Hashed - nullable for OIDC users
     email = fields.CharField(max_length=100, unique=True)
-    whatsapp_number = fields.CharField(max_length=30, unique=True, null=True, index=True)
+    whatsapp_number = fields.CharField(
+        max_length=30, unique=True, null=True, index=True
+    )
+    imessage_number = fields.CharField(
+        max_length=30, unique=True, null=True, index=True
+    )
 
     # Email channel fields
     email_enabled = fields.BooleanField(default=False)
-    email_hmac_token = fields.CharField(max_length=16, unique=True, null=True, index=True)
+    email_hmac_token = fields.CharField(
+        max_length=16, unique=True, null=True, index=True
+    )
 
     # OIDC fields
     oidc_subject = fields.CharField(
@@ -49,3 +56,19 @@ class User(Model):
         if not self.password:
             return False
         return bcrypt.checkpw(plain_password.encode("utf-8"), self.password)
+
+
+class OIDCState(Model):
+    """Pending OIDC login: maps the `state` param to its PKCE verifier.
+
+    Stored in Postgres (not process memory) so a login that starts on one
+    blue/green color and finishes on the other still validates.
+    """
+
+    state = fields.CharField(max_length=128, primary_key=True)
+    pkce_verifier = fields.CharField(max_length=128)
+    expires_at = fields.DatetimeField(index=True)
+    created_at = fields.DatetimeField(auto_now_add=True)
+
+    class Meta:
+        table = "oidc_states"

blueprints/users/oidc_state.py

@@ -0,0 +1,36 @@
+"""
+Persistent, single-use store for pending OIDC logins (state -> PKCE verifier).
+
+Lives in Postgres so a login started on one blue/green color can finish on
+the other.
+"""
+
+from datetime import datetime, timedelta, timezone
+
+from .models import OIDCState
+
+OIDC_STATE_TTL = timedelta(minutes=10)
+
+
+async def save_oidc_state(
+    state: str, pkce_verifier: str, ttl: timedelta = OIDC_STATE_TTL
+) -> None:
+    now = datetime.now(timezone.utc)
+    # Opportunistic cleanup of abandoned logins
+    await OIDCState.filter(expires_at__lte=now).delete()
+    await OIDCState.create(
+        state=state, pkce_verifier=pkce_verifier, expires_at=now + ttl
+    )
+
+
+async def consume_oidc_state(state: str) -> str | None:
+    """Return the PKCE verifier for `state` and delete it, or None if the
+    state is unknown, expired, or was already consumed."""
+    row = await OIDCState.get_or_none(state=state)
+    if row is None:
+        return None
+    # The delete is the single-use guard: only one concurrent caller wins.
+    deleted = await OIDCState.filter(state=state).delete()
+    if not deleted or row.expires_at <= datetime.now(timezone.utc):
+        return None
+    return row.pkce_verifier

blueprints/whatsapp/__init__.py

@@ -1,21 +1,20 @@
 import os
 import logging
-import asyncio
 import functools
 import time
 from collections import defaultdict
-from quart import Blueprint, request, jsonify, abort
+from quart import Blueprint, request, abort
 from twilio.request_validator import RequestValidator
 from twilio.twiml.messaging_response import MessagingResponse
 
 from blueprints.users.models import User
 from blueprints.conversation.logic import (
-    get_conversation_for_user,
+    get_agent_for,
+    get_conversation_for_channel,
     add_message_to_conversation,
-    get_conversation_transcript,
+    persist_agent_tool_messages,
 )
-from blueprints.conversation.agents import main_agent
-from blueprints.conversation.prompts import SIMBA_SYSTEM_PROMPT
+from utils.strip_markdown import extract_agent_text
 
 whatsapp_blueprint = Blueprint("whatsapp_api", __name__, url_prefix="/api/whatsapp")
 
@@ -69,6 +68,7 @@ def validate_twilio_request(f):
     so the validated URL matches what Twilio signed against.
     Set TWILIO_SIGNATURE_VALIDATION=false to disable in development.
     """
+
     @functools.wraps(f)
     async def decorated_function(*args, **kwargs):
         if os.getenv("TWILIO_SIGNATURE_VALIDATION", "true").lower() == "false":
@@ -94,6 +94,7 @@ def validate_twilio_request(f):
             abort(403)
 
         return await f(*args, **kwargs)
+
     return decorated_function
 
 
@@ -104,11 +105,15 @@ async def webhook():
     Handle incoming WhatsApp messages from Twilio.
     """
     form_data = await request.form
-    from_number = form_data.get("From") # e.g., "whatsapp:+1234567890"
+    from_number = form_data.get("From")  # e.g., "whatsapp:+1234567890"
     body = form_data.get("Body")
 
     if not from_number or not body:
-        return _twiml_response("Invalid message received.") if from_number else ("Missing From or Body", 400)
+        return (
+            _twiml_response("Invalid message received.")
+            if from_number
+            else ("Missing From or Body", 400)
+        )
 
     # Strip whitespace and check for empty body
     body = body.strip()
@@ -118,12 +123,16 @@ async def webhook():
     # Rate limiting
     if not _check_rate_limit(from_number):
         logger.warning(f"Rate limit exceeded for {from_number}")
-        return _twiml_response("You're sending messages too quickly. Please wait a moment and try again.")
+        return _twiml_response(
+            "You're sending messages too quickly. Please wait a moment and try again."
+        )
 
     # Truncate overly long messages
     if len(body) > MAX_MESSAGE_LENGTH:
         body = body[:MAX_MESSAGE_LENGTH]
-        logger.info(f"Truncated long message from {from_number} to {MAX_MESSAGE_LENGTH} chars")
+        logger.info(
+            f"Truncated long message from {from_number} to {MAX_MESSAGE_LENGTH} chars"
+        )
 
     logger.info(f"Received WhatsApp message from {from_number}: {body[:100]}")
 
@@ -143,17 +152,18 @@ async def webhook():
                 username=username,
                 email=f"{username}@whatsapp.simbarag.local",
                 whatsapp_number=from_number,
-                auth_provider="whatsapp"
+                auth_provider="whatsapp",
             )
             logger.info(f"Created new user for WhatsApp: {username}")
         except Exception as e:
             logger.error(f"Failed to create user for {from_number}: {e}")
-            return _twiml_response("Sorry, something went wrong setting up your account. Please try again later.")
+            return _twiml_response(
+                "Sorry, something went wrong setting up your account. Please try again later."
+            )
 
     # Get or create a conversation for this user
     try:
-        conversation = await get_conversation_for_user(user=user)
-        await conversation.fetch_related("messages")
+        conversation = await get_conversation_for_channel(user=user, channel="whatsapp")
     except Exception as e:
         logger.error(f"Failed to get conversation for user {user.username}: {e}")
         return _twiml_response("Sorry, something went wrong. Please try again later.")
@@ -166,30 +176,23 @@ async def webhook():
         user=user,
     )
 
-    # Get transcript for context
-    transcript = await get_conversation_transcript(user=user, conversation=conversation)
-
-    # Build messages payload for LangChain agent with system prompt and conversation history
     try:
-        # Get last 10 messages for conversation history
-        messages = await conversation.messages.all()
-        recent_messages = list(messages)[-10:]
-
-        # Build messages payload
-        messages_payload = [{"role": "system", "content": SIMBA_SYSTEM_PROMPT}]
-
-        # Add recent conversation history (exclude the message we just added)
-        for msg in recent_messages[:-1]:
-            role = "user" if msg.speaker == "user" else "assistant"
-            messages_payload.append({"role": role, "content": msg.text})
-
-        # Add current query
-        messages_payload.append({"role": "user", "content": body})
-
-        # Invoke LangChain agent
-        logger.info(f"Invoking LangChain agent with {len(messages_payload)} messages")
-        response = await main_agent.ainvoke({"messages": messages_payload})
-        response_text = response.get("messages", [])[-1].content
+        agent_config = {
+            "configurable": {
+                "user_id": str(user.id),
+                "is_admin": user.is_admin(),
+                "thread_id": str(conversation.id),
+            }
+        }
+        logger.info(f"Invoking LangChain agent for conversation {conversation.id}")
+        response = await get_agent_for(user).ainvoke(
+            {"messages": [{"role": "user", "content": body}]},
+            config=agent_config,
+        )
+        response_text = extract_agent_text(response.get("messages", [])[-1].content)
+        await persist_agent_tool_messages(
+            conversation, user, response.get("messages", [])
+        )
 
         # Log YNAB availability
         if os.getenv("YNAB_ACCESS_TOKEN"):

blueprints/ynab/__init__.py

@@ -0,0 +1 @@
+"""YNAB budget mirror: Postgres models, delta sync, and agent tools."""

blueprints/ynab/__main__.py

@@ -0,0 +1,22 @@
+"""Run one YNAB sync: ``python -m blueprints.ynab [--full]``."""
+
+import asyncio
+import sys
+
+from tortoise import Tortoise
+
+from config.db import TORTOISE_CONFIG
+
+from .sync import sync_ynab
+
+
+async def main(full: bool) -> None:
+    await Tortoise.init(config=TORTOISE_CONFIG)
+    try:
+        print(await sync_ynab(full=full))
+    finally:
+        await Tortoise.close_connections()
+
+
+if __name__ == "__main__":
+    asyncio.run(main(full="--full" in sys.argv))

blueprints/ynab/models.py

@@ -0,0 +1,173 @@
+"""Local Postgres mirror of the YNAB budget.
+
+Rows are keyed by YNAB's own ids and kept current by ``blueprints.ynab.sync``
+using YNAB delta requests. Money is stored in dollars with 3 decimal places,
+which is exactly YNAB's milliunits. Deleted YNAB entities are kept with
+``deleted=True`` rather than removed.
+"""
+
+from tortoise import fields
+from tortoise.models import Model
+
+
+def money(**kwargs):
+    return fields.DecimalField(max_digits=15, decimal_places=3, **kwargs)
+
+
+class YnabAccount(Model):
+    id = fields.CharField(max_length=36, primary_key=True)
+    name = fields.CharField(max_length=255)
+    type = fields.CharField(max_length=50)
+    on_budget = fields.BooleanField()
+    closed = fields.BooleanField()
+    note = fields.TextField(null=True)
+    balance = money()
+    cleared_balance = money()
+    uncleared_balance = money()
+    last_reconciled_at = fields.DatetimeField(null=True)
+    deleted = fields.BooleanField(default=False)
+
+    class Meta:
+        table = "ynab_accounts"
+
+
+class YnabPayee(Model):
+    id = fields.CharField(max_length=36, primary_key=True)
+    name = fields.CharField(max_length=500)
+    transfer_account_id = fields.CharField(max_length=36, null=True)
+    deleted = fields.BooleanField(default=False)
+
+    class Meta:
+        table = "ynab_payees"
+
+
+class YnabCategoryGroup(Model):
+    id = fields.CharField(max_length=36, primary_key=True)
+    name = fields.CharField(max_length=255)
+    hidden = fields.BooleanField()
+    internal = fields.BooleanField(default=False)
+    deleted = fields.BooleanField(default=False)
+
+    class Meta:
+        table = "ynab_category_groups"
+
+
+class YnabCategory(Model):
+    id = fields.CharField(max_length=36, primary_key=True)
+    category_group_id = fields.CharField(max_length=36, db_index=True)
+    name = fields.CharField(max_length=255)
+    hidden = fields.BooleanField()
+    internal = fields.BooleanField(default=False)
+    note = fields.TextField(null=True)
+    goal_type = fields.CharField(max_length=20, null=True)
+    goal_target = money(null=True)
+    goal_target_month = fields.DateField(null=True)
+    deleted = fields.BooleanField(default=False)
+
+    class Meta:
+        table = "ynab_categories"
+
+
+class YnabMonth(Model):
+    # ISO month start, e.g. "2026-10-01"
+    id = fields.CharField(max_length=10, primary_key=True)
+    month = fields.DateField(db_index=True)
+    note = fields.TextField(null=True)
+    income = money()
+    budgeted = money()
+    activity = money()
+    to_be_budgeted = money()
+    age_of_money = fields.IntField(null=True)
+    deleted = fields.BooleanField(default=False)
+
+    class Meta:
+        table = "ynab_months"
+
+
+class YnabMonthCategory(Model):
+    """Per-month category amounts. ``budgeted`` is what YNAB calls "Assigned"."""
+
+    # "<month>:<category_id>"
+    id = fields.CharField(max_length=47, primary_key=True)
+    month = fields.DateField(db_index=True)
+    category_id = fields.CharField(max_length=36, db_index=True)
+    budgeted = money()
+    activity = money()
+    balance = money()
+    deleted = fields.BooleanField(default=False)
+
+    class Meta:
+        table = "ynab_month_categories"
+
+
+class YnabTransaction(Model):
+    id = fields.CharField(max_length=64, primary_key=True)
+    date = fields.DateField(db_index=True)
+    amount = money()
+    memo = fields.TextField(null=True)
+    cleared = fields.CharField(max_length=20)
+    approved = fields.BooleanField()
+    flag_color = fields.CharField(max_length=20, null=True)
+    account_id = fields.CharField(max_length=36, db_index=True)
+    payee_id = fields.CharField(max_length=36, null=True, db_index=True)
+    category_id = fields.CharField(max_length=36, null=True, db_index=True)
+    transfer_account_id = fields.CharField(max_length=36, null=True)
+    import_payee_name = fields.CharField(max_length=500, null=True)
+    # Denormalized from payees/categories/accounts after each sync for easy querying
+    account_name = fields.CharField(max_length=255, null=True)
+    payee_name = fields.CharField(max_length=500, null=True)
+    category_name = fields.CharField(max_length=255, null=True)
+    deleted = fields.BooleanField(default=False)
+
+    class Meta:
+        table = "ynab_transactions"
+
+
+class YnabSubtransaction(Model):
+    """Lines of a split transaction; the parent's category is "Split"."""
+
+    id = fields.CharField(max_length=64, primary_key=True)
+    transaction_id = fields.CharField(max_length=64, db_index=True)
+    amount = money()
+    memo = fields.TextField(null=True)
+    payee_id = fields.CharField(max_length=36, null=True)
+    category_id = fields.CharField(max_length=36, null=True, db_index=True)
+    transfer_account_id = fields.CharField(max_length=36, null=True)
+    deleted = fields.BooleanField(default=False)
+
+    class Meta:
+        table = "ynab_subtransactions"
+
+
+class YnabChange(Model):
+    """Append-only log of what each sync changed, built by diffing against the mirror.
+
+    YNAB's API has no history, so this is the only record of edits (e.g. an
+    assignment going from $400 to $500). It starts at the first sync.
+    """
+
+    id = fields.BigIntField(primary_key=True)
+    synced_at = fields.DatetimeField(auto_now_add=True, db_index=True)
+    server_knowledge = fields.BigIntField()
+    entity_type = fields.CharField(max_length=30, db_index=True)
+    entity_id = fields.CharField(max_length=64, db_index=True)
+    # created / updated / deleted
+    action = fields.CharField(max_length=10)
+    label = fields.CharField(max_length=500)
+    # {field: [old, new]}; for "created", old is null
+    changes = fields.JSONField()
+
+    class Meta:
+        table = "ynab_changes"
+
+
+class YnabSyncState(Model):
+    budget_id = fields.CharField(max_length=64, primary_key=True)
+    budget_name = fields.CharField(max_length=255, null=True)
+    server_knowledge = fields.BigIntField(null=True)
+    last_synced_at = fields.DatetimeField(null=True)
+    last_full_sync_at = fields.DatetimeField(null=True)
+    last_error = fields.TextField(null=True)
+
+    class Meta:
+        table = "ynab_sync_state"

blueprints/ynab/sql_tool.py

@@ -0,0 +1,172 @@
+"""Admin-only read-only SQL over the YNAB mirror tables.
+
+Defense in depth: the query is parsed and must be a single SELECT touching
+only ``ynab_*`` tables with no dangerous functions, then runs in a READ ONLY
+transaction with a statement timeout and a row cap.
+"""
+
+import re
+from decimal import Decimal
+
+import sqlglot
+from langchain_core.runnables import RunnableConfig
+from langchain.tools import tool
+from sqlglot import exp
+from sqlglot.optimizer.scope import traverse_scope
+from tortoise.transactions import in_transaction
+
+from utils.mcp_tools import admin_only_message
+
+from . import models
+from .sync import ensure_fresh
+from .tools import NOT_SYNCED, ynab_tool_errors
+
+MAX_ROWS = 100
+# Tool results are cut at 4000 chars in blueprints/conversation/logic.py
+MAX_OUTPUT_CHARS = 3800
+STATEMENT_TIMEOUT = "10s"
+
+ALLOWED_TABLES = frozenset(
+    m._meta.db_table
+    for m in vars(models).values()
+    if isinstance(m, type) and issubclass(m, models.Model) and m is not models.Model
+)
+
+FORBIDDEN_NODES = (
+    exp.Insert,
+    exp.Update,
+    exp.Delete,
+    exp.Merge,
+    exp.Create,
+    exp.Drop,
+    exp.Alter,
+    exp.Command,
+    exp.Into,
+)
+
+FORBIDDEN_FUNCTIONS = re.compile(
+    r"^(pg_|lo_|dblink|set_config|current_setting|"
+    r"(query|table|cursor|schema|database)_to_xml|txid_|nextval|setval)",
+    re.IGNORECASE,
+)
+
+
+def validate_sql(query: str) -> str | None:
+    """Return an error message if ``query`` isn't allowed, else None."""
+    return _check(query)[0]
+
+
+def _check(query: str) -> tuple[str | None, str | None]:
+    """Validate ``query``; return ``(error, sql_to_run)``.
+
+    The SQL that runs is regenerated from the validated parse tree (minus
+    comments), so Postgres executes exactly what was checked.
+    """
+    try:
+        statements = [
+            s
+            for s in sqlglot.parse(query, read="postgres")
+            # a trailing "; -- comment" parses as a bare Semicolon
+            if s and not isinstance(s, exp.Semicolon)
+        ]
+    except sqlglot.errors.SqlglotError as e:
+        return f"Could not parse SQL: {e}", None
+    if len(statements) != 1:
+        return "Exactly one SQL statement is allowed.", None
+    root = statements[0]
+    if not isinstance(root, exp.Query):
+        return "Only SELECT queries are allowed.", None
+    if root.find(*FORBIDDEN_NODES) or any(
+        s.args.get("locks") for s in root.find_all(exp.Select)
+    ):
+        return "Only read-only SELECT queries are allowed.", None
+
+    # A name matching a CTE isn't necessarily a CTE reference (e.g. inside the
+    # CTE's own body, or outside the scope that defines it), so resolve each
+    # FROM source through sqlglot's scopes. Any table node that isn't a CTE
+    # name at all is checked too, in case scope analysis misses a construct.
+    try:
+        scopes = traverse_scope(root)
+    except Exception as e:
+        return f"Could not analyze SQL: {e}", None
+    cte_names = {cte.alias_or_name for cte in root.find_all(exp.CTE)}
+    tables = [
+        source
+        for scope in scopes
+        for source in scope.sources.values()
+        if isinstance(source, exp.Table)
+    ]
+    tables += [t for t in root.find_all(exp.Table) if t.name not in cte_names]
+    for table in tables:
+        if isinstance(table.this, exp.Func):  # e.g. generate_series(...)
+            continue
+        if table.catalog or table.db not in ("", "public"):
+            return f"Schema-qualified table '{table.sql()}' is not allowed.", None
+        if table.name not in ALLOWED_TABLES:
+            return (
+                f"Table '{table.name}' is not allowed. "
+                f"Available: {', '.join(sorted(ALLOWED_TABLES))}",
+                None,
+            )
+
+    for func in root.find_all(exp.Func):
+        name = func.name if isinstance(func, exp.Anonymous) else func.sql_name()
+        if FORBIDDEN_FUNCTIONS.match(name or ""):
+            return f"Function '{name}' is not allowed.", None
+    return None, root.sql(dialect="postgres", comments=False).rstrip("; ")
+
+
+def _format_value(value) -> str:
+    if value is None:
+        return ""
+    if isinstance(value, Decimal):
+        value = (
+            format(value.normalize(), "f") if value == value.to_integral() else value
+        )
+    return str(value).replace("\t", " ").replace("\n", " ")
+
+
+def format_rows(columns: list[str], rows: list[tuple]) -> str:
+    if not rows:
+        return "Query returned no rows."
+    lines = ["\t".join(columns)]
+    lines += ["\t".join(_format_value(v) for v in row) for row in rows]
+    text = "\n".join(lines)
+    if len(text) > MAX_OUTPUT_CHARS:
+        text = text[:MAX_OUTPUT_CHARS] + "\n...(output truncated; aggregate more)"
+    elif len(rows) == MAX_ROWS:
+        text += f"\n(capped at {MAX_ROWS} rows; aggregate or add LIMIT)"
+    return text
+
+
+@tool
+@ynab_tool_errors
+async def ynab_sql(query: str, config: RunnableConfig) -> str:
+    """Run a read-only Postgres SELECT over the YNAB mirror for questions the other YNAB tools can't answer. Tables: ynab_transactions (date, amount, payee_name, category_name, account_name, memo, transfer_account_id, deleted), ynab_subtransactions (split lines), ynab_accounts, ynab_categories, ynab_category_groups, ynab_payees, ynab_months, ynab_month_categories (month, category_id, budgeted=assigned, activity, balance=available), ynab_changes (edit history: synced_at, entity_type, action, label, changes JSON). Amounts are dollars; outflows negative. Filter NOT deleted.
+
+    Args:
+        query: A single PostgreSQL SELECT statement
+    """
+    if not (config or {}).get("configurable", {}).get("is_admin"):
+        return admin_only_message("YNAB SQL")
+    error, sql = _check(query)
+    if error:
+        return error
+    if await ensure_fresh() is None:
+        return NOT_SYNCED
+
+    try:
+        async with in_transaction() as conn:
+            await conn.execute_query("SET TRANSACTION READ ONLY")
+            await conn.execute_query(
+                f"SET LOCAL statement_timeout = '{STATEMENT_TIMEOUT}'"
+            )
+            # Raw records rather than dicts, which would merge same-named
+            # columns (e.g. c.name and g.name)
+            _, records = await conn.execute_query(
+                f"SELECT * FROM ({sql}) AS q LIMIT {MAX_ROWS}"
+            )
+    except Exception as e:
+        return f"SQL error: {e}"
+    columns = list(records[0].keys()) if records else []
+    return format_rows(columns, [tuple(r.values()) for r in records])

blueprints/ynab/sync.py

@@ -0,0 +1,640 @@
+"""Sync the YNAB budget into the local Postgres mirror.
+
+YNAB has no event feed, but every budget response carries a
+``server_knowledge`` counter; passing it back as ``last_knowledge_of_server``
+returns only entities changed since then. The first sync downloads the whole
+budget, later syncs are deltas, and a full resync runs once a day as a safety
+net (deltas can't express things like month rollovers).
+
+Each sync diffs incoming entities against the mirror and appends what changed
+to ``ynab_changes``, which is the only history of edits we get.
+"""
+
+import asyncio
+import logging
+import os
+import time
+from dataclasses import dataclass
+from datetime import date, datetime, timedelta, timezone
+from decimal import Decimal
+from typing import Any, Callable
+
+from tortoise.models import Model
+from tortoise.transactions import in_transaction
+
+from utils.ynab_service import YNABService
+
+from .models import (
+    YnabAccount,
+    YnabCategory,
+    YnabCategoryGroup,
+    YnabChange,
+    YnabMonth,
+    YnabMonthCategory,
+    YnabPayee,
+    YnabSubtransaction,
+    YnabSyncState,
+    YnabTransaction,
+)
+
+logger = logging.getLogger(__name__)
+
+FULL_RESYNC_INTERVAL = timedelta(hours=24)
+# After a failed sync, tools answer from the mirror without retrying YNAB
+FAILURE_BACKOFF_SECONDS = 60
+# Cap on rows passed to a single ``id IN (...)`` lookup
+LOOKUP_CHUNK = 2000
+
+_sync_lock = asyncio.Lock()
+_last_failure = float("-inf")
+
+
+def ynab_configured() -> bool:
+    return bool(os.getenv("YNAB_ACCESS_TOKEN"))
+
+
+# YNAB accepts these in place of a budget id; they can point at different
+# budgets over time, so the mirror resolves them once and keeps the real id
+BUDGET_ID_ALIASES = ("last-used", "default")
+
+
+def _configured_budget_id() -> str | None:
+    """YNAB_BUDGET_ID if it names a specific budget, else None."""
+    budget_id = os.getenv("YNAB_BUDGET_ID", "").strip()
+    return None if budget_id in ("", *BUDGET_ID_ALIASES) else budget_id
+
+
+def _money(milliunits: int | None) -> Decimal | None:
+    return None if milliunits is None else Decimal(milliunits).scaleb(-3)
+
+
+def _date(value: str | None) -> date | None:
+    return date.fromisoformat(value) if value else None
+
+
+def _datetime(value: str | None) -> datetime | None:
+    if not value:
+        return None
+    return datetime.fromisoformat(value.replace("Z", "+00:00"))
+
+
+def _norm(value: Any) -> Any:
+    """Normalize values so DB rows and freshly mapped rows compare equal."""
+    if isinstance(value, datetime) and value.tzinfo is None:
+        return value.replace(tzinfo=timezone.utc)
+    return value
+
+
+def _jsonable(value: Any) -> Any:
+    if isinstance(value, Decimal):
+        return float(value)
+    if isinstance(value, (date, datetime)):
+        return value.isoformat()
+    return value
+
+
+def _map_account(a: dict) -> dict:
+    return {
+        "id": a["id"],
+        "name": a["name"],
+        "type": a["type"],
+        "on_budget": a["on_budget"],
+        "closed": a["closed"],
+        "note": a.get("note"),
+        "balance": _money(a["balance"]),
+        "cleared_balance": _money(a["cleared_balance"]),
+        "uncleared_balance": _money(a["uncleared_balance"]),
+        "last_reconciled_at": _datetime(a.get("last_reconciled_at")),
+        "deleted": a["deleted"],
+    }
+
+
+def _map_payee(p: dict) -> dict:
+    return {
+        "id": p["id"],
+        "name": p["name"],
+        "transfer_account_id": p.get("transfer_account_id"),
+        "deleted": p["deleted"],
+    }
+
+
+def _map_category_group(g: dict) -> dict:
+    return {
+        "id": g["id"],
+        "name": g["name"],
+        "hidden": g["hidden"],
+        "internal": g.get("internal") or False,
+        "deleted": g["deleted"],
+    }
+
+
+def _map_category(c: dict) -> dict:
+    return {
+        "id": c["id"],
+        "category_group_id": c["category_group_id"],
+        "name": c["name"],
+        "hidden": c["hidden"],
+        "internal": c.get("internal") or False,
+        "note": c.get("note"),
+        "goal_type": c.get("goal_type"),
+        "goal_target": _money(c.get("goal_target")),
+        "goal_target_month": _date(c.get("goal_target_month")),
+        "deleted": c["deleted"],
+    }
+
+
+def _map_month(m: dict) -> dict:
+    return {
+        "id": m["month"],
+        "month": _date(m["month"]),
+        "note": m.get("note"),
+        "income": _money(m["income"]),
+        "budgeted": _money(m["budgeted"]),
+        "activity": _money(m["activity"]),
+        "to_be_budgeted": _money(m["to_be_budgeted"]),
+        "age_of_money": m.get("age_of_money"),
+        "deleted": m["deleted"],
+    }
+
+
+def _map_month_category(c: dict) -> dict:
+    return {
+        "id": f"{c['month']}:{c['id']}",
+        "month": _date(c["month"]),
+        "category_id": c["id"],
+        "budgeted": _money(c["budgeted"]),
+        "activity": _money(c["activity"]),
+        "balance": _money(c["balance"]),
+        "deleted": c["deleted"],
+    }
+
+
+def _map_transaction(t: dict) -> dict:
+    return {
+        "id": t["id"],
+        "date": _date(t["date"]),
+        "amount": _money(t["amount"]),
+        "memo": t.get("memo"),
+        "cleared": t["cleared"],
+        "approved": t["approved"],
+        "flag_color": t.get("flag_color"),
+        "account_id": t["account_id"],
+        "payee_id": t.get("payee_id"),
+        "category_id": t.get("category_id"),
+        "transfer_account_id": t.get("transfer_account_id"),
+        "import_payee_name": t.get("import_payee_name"),
+        "deleted": t["deleted"],
+    }
+
+
+def _map_subtransaction(s: dict) -> dict:
+    return {
+        "id": s["id"],
+        "transaction_id": s["transaction_id"],
+        "amount": _money(s["amount"]),
+        "memo": s.get("memo"),
+        "payee_id": s.get("payee_id"),
+        "category_id": s.get("category_id"),
+        "transfer_account_id": s.get("transfer_account_id"),
+        "deleted": s["deleted"],
+    }
+
+
+# Filled in from payees/categories/accounts after each sync, not from YNAB
+DENORMALIZED_FIELDS = ("account_name", "payee_name", "category_name")
+
+
+@dataclass
+class EntitySpec:
+    entity_type: str
+    model: type[Model]
+    mapper: Callable[[dict], dict]
+    # Fields worth recording in the change log. Derived fields (balances,
+    # activity) change with every transaction and would drown out real edits.
+    logged_fields: tuple[str, ...]
+
+
+def _fields(model: type[Model], exclude: tuple[str, ...] = ()) -> tuple[str, ...]:
+    return tuple(f for f in model._meta.fields_map if f != "id" and f not in exclude)
+
+
+SPECS = {
+    "accounts": EntitySpec(
+        "account",
+        YnabAccount,
+        _map_account,
+        ("name", "type", "on_budget", "closed", "note", "deleted"),
+    ),
+    "payees": EntitySpec("payee", YnabPayee, _map_payee, ("name", "deleted")),
+    "category_groups": EntitySpec(
+        "category_group",
+        YnabCategoryGroup,
+        _map_category_group,
+        ("name", "hidden", "deleted"),
+    ),
+    "categories": EntitySpec(
+        "category", YnabCategory, _map_category, _fields(YnabCategory)
+    ),
+    "months": EntitySpec("month", YnabMonth, _map_month, ("note",)),
+    "month_categories": EntitySpec(
+        "month_category", YnabMonthCategory, _map_month_category, ("budgeted",)
+    ),
+    "transactions": EntitySpec(
+        "transaction",
+        YnabTransaction,
+        _map_transaction,
+        _fields(YnabTransaction, exclude=DENORMALIZED_FIELDS),
+    ),
+    "subtransactions": EntitySpec(
+        "subtransaction",
+        YnabSubtransaction,
+        _map_subtransaction,
+        _fields(YnabSubtransaction),
+    ),
+}
+
+
+def _budget_entities(budget: dict) -> dict[str, list[dict]]:
+    """Split a budget payload into raw entity lists keyed like ``SPECS``."""
+    month_categories = [
+        {**c, "month": m["month"]}
+        for m in budget.get("months") or []
+        for c in m.get("categories") or []
+    ]
+    return {
+        "accounts": budget.get("accounts") or [],
+        "payees": budget.get("payees") or [],
+        "category_groups": budget.get("category_groups") or [],
+        "categories": budget.get("categories") or [],
+        "months": budget.get("months") or [],
+        "month_categories": month_categories,
+        "transactions": budget.get("transactions") or [],
+        "subtransactions": budget.get("subtransactions") or [],
+    }
+
+
+# Id fields that reference a named entity (account, payee, category, group);
+# the change log records these by name
+NAMED_ID_FIELDS = (
+    "account_id",
+    "payee_id",
+    "category_id",
+    "category_group_id",
+    "transfer_account_id",
+)
+
+
+class _Labeler:
+    """Resolves ids to names for change log labels and diffs."""
+
+    def __init__(self, names: dict[str, str]):
+        self.names = names
+
+    def name(self, entity_id: str | None) -> str | None:
+        return None if entity_id is None else self.names.get(entity_id, entity_id)
+
+    def __call__(self, entity_type: str, row: dict) -> str:
+        if entity_type == "transaction":
+            payee = self.name(row.get("payee_id")) or row.get("import_payee_name") or ""
+            return f"{row['date']} {payee} {row['amount']:+.2f}"
+        if entity_type == "subtransaction":
+            category = self.name(row.get("category_id")) or ""
+            return f"split line {category} {row['amount']:+.2f}"
+        if entity_type == "month_category":
+            return f"{self.name(row['category_id'])} {row['month']:%Y-%m}"
+        if entity_type == "month":
+            return row["id"][:7]
+        return row.get("name") or row["id"]
+
+    def diff_entry(self, field: str, old: Any, new: Any) -> tuple[str, list]:
+        """Log e.g. ``category_id`` changes as ``category`` names, not ids."""
+        if field in NAMED_ID_FIELDS:
+            return field.removesuffix("_id"), [self.name(old), self.name(new)]
+        return field, [_jsonable(old), _jsonable(new)]
+
+
+async def _load_names(conn) -> dict[str, str]:
+    names: dict[str, str] = {}
+    for model in (YnabAccount, YnabPayee, YnabCategory, YnabCategoryGroup):
+        for row in await model.all().using_db(conn).values("id", "name"):
+            names[row["id"]] = row["name"]
+    return names
+
+
+async def _fetch_existing(spec: EntitySpec, ids: list[str], conn, fields) -> dict:
+    existing: dict[str, dict] = {}
+    for i in range(0, len(ids), LOOKUP_CHUNK):
+        rows = (
+            await spec.model.filter(id__in=ids[i : i + LOOKUP_CHUNK])
+            .using_db(conn)
+            .values("id", *fields)
+        )
+        existing.update({row["id"]: row for row in rows})
+    return existing
+
+
+async def _apply(
+    spec: EntitySpec,
+    raw_rows: list[dict],
+    conn,
+    server_knowledge: int,
+    log_changes: bool,
+    labeler: _Labeler,
+    complete: bool = False,
+) -> int:
+    """Upsert rows that differ from the mirror; return how many changed.
+
+    ``complete`` means ``raw_rows`` is every live entity of this type (a full
+    download). Full downloads omit deleted entities, so mirror rows missing
+    from it are marked deleted here; otherwise deletions that happened right
+    before a full sync would never reach the mirror.
+    """
+    incoming = {row["id"]: row for row in map(spec.mapper, raw_rows)}
+    # Only YNAB-sourced columns; denormalized names are filled in afterwards
+    field_names = tuple(f for f in _fields(spec.model) if f not in DENORMALIZED_FIELDS)
+    existing = await _fetch_existing(spec, list(incoming), conn, field_names)
+
+    to_write: list[Model] = []
+    changes: list[YnabChange] = []
+
+    def log(entity_id: str, action: str, diff: dict, row: dict) -> None:
+        changes.append(
+            YnabChange(
+                server_knowledge=server_knowledge,
+                entity_type=spec.entity_type,
+                entity_id=entity_id,
+                action=action,
+                label=labeler(spec.entity_type, row)[:500],
+                changes=diff,
+            )
+        )
+
+    for entity_id, new in incoming.items():
+        old = existing.get(entity_id)
+        if old is not None and all(_norm(old[f]) == _norm(new[f]) for f in field_names):
+            continue
+        to_write.append(spec.model(**new))
+
+        if not log_changes or not spec.logged_fields:
+            continue
+        if old is None:
+            # Created and deleted between two syncs: nothing worth logging
+            if new.get("deleted"):
+                continue
+            diff = dict(
+                labeler.diff_entry(f, None, new[f])
+                for f in spec.logged_fields
+                if new[f] is not None
+            )
+            # e.g. a month rollover creates every category's month row with
+            # nothing assigned; that's not an edit anyone made
+            if not any(values[1] for values in diff.values()):
+                continue
+            log(entity_id, "created", diff, new)
+        else:
+            diff = dict(
+                labeler.diff_entry(f, old[f], new[f])
+                for f in spec.logged_fields
+                if _norm(old[f]) != _norm(new[f])
+            )
+            if diff:
+                deleted = diff.get("deleted") == [False, True]
+                log(entity_id, "deleted" if deleted else "updated", diff, new)
+
+    removed = 0
+    if complete:
+        live_ids = (
+            await spec.model.filter(deleted=False)
+            .using_db(conn)
+            .values_list("id", flat=True)
+        )
+        missing = [i for i in live_ids if i not in incoming]
+        if missing:
+            if log_changes and "deleted" in spec.logged_fields:
+                gone = await _fetch_existing(spec, missing, conn, field_names)
+                for entity_id, row in gone.items():
+                    log(entity_id, "deleted", {"deleted": [False, True]}, row)
+            for i in range(0, len(missing), LOOKUP_CHUNK):
+                removed += (
+                    await spec.model.filter(id__in=missing[i : i + LOOKUP_CHUNK])
+                    .using_db(conn)
+                    .update(deleted=True)
+                )
+
+    if to_write:
+        await spec.model.bulk_create(
+            to_write,
+            batch_size=500,
+            on_conflict=["id"],
+            update_fields=list(field_names),
+            using_db=conn,
+        )
+    if changes:
+        await YnabChange.bulk_create(changes, batch_size=500, using_db=conn)
+    return len(to_write) + removed
+
+
+DENORMALIZE_SQL = (
+    """UPDATE ynab_transactions AS t SET payee_name = p.name FROM ynab_payees p
+       WHERE t.payee_id = p.id AND t.payee_name IS DISTINCT FROM p.name""",
+    """UPDATE ynab_transactions AS t SET category_name = c.name FROM ynab_categories c
+       WHERE t.category_id = c.id AND t.category_name IS DISTINCT FROM c.name""",
+    """UPDATE ynab_transactions AS t SET account_name = a.name FROM ynab_accounts a
+       WHERE t.account_id = a.id AND t.account_name IS DISTINCT FROM a.name""",
+    """UPDATE ynab_transactions SET payee_name = NULL
+       WHERE payee_id IS NULL AND payee_name IS NOT NULL""",
+    """UPDATE ynab_transactions SET category_name = NULL
+       WHERE category_id IS NULL AND category_name IS NOT NULL""",
+)
+# Entity types whose changes can affect the denormalized name columns
+NAME_SOURCES = ("accounts", "payees", "categories", "transactions")
+
+REFERENCE_KEYS = ("accounts", "payees", "category_groups", "categories")
+DATA_KEYS = ("months", "month_categories", "transactions", "subtransactions")
+
+
+async def apply_budget(
+    budget: dict,
+    server_knowledge: int,
+    conn,
+    log_changes: bool,
+    full: bool = False,
+) -> dict[str, int]:
+    """Write a full or delta budget payload into the mirror.
+
+    With ``full``, entity types present in the payload are treated as
+    complete and anything missing from them is marked deleted.
+    """
+    entities = _budget_entities(budget)
+    present = {key for key in SPECS if budget.get(key) is not None}
+    if budget.get("months") is not None:
+        present.add("month_categories")
+
+    labeler = _Labeler({})
+    if log_changes and any(entities.values()):
+        labeler.names = await _load_names(conn)
+
+    counts: dict[str, int] = {}
+    for key in REFERENCE_KEYS + DATA_KEYS:
+        counts[key] = await _apply(
+            SPECS[key],
+            entities[key],
+            conn,
+            server_knowledge,
+            log_changes,
+            labeler,
+            complete=full and key in present,
+        )
+        if key in REFERENCE_KEYS:
+            # Later labels (e.g. a new payee on a new transaction) need these
+            labeler.names.update({row["id"]: row["name"] for row in entities[key]})
+
+    if any(counts[key] for key in NAME_SOURCES):
+        for sql in DENORMALIZE_SQL:
+            await conn.execute_query(sql)
+    return counts
+
+
+async def _current_state() -> YnabSyncState | None:
+    """The sync state for the mirrored budget.
+
+    The mirror holds a single budget, keyed by its real YNAB id. With
+    ``YNAB_BUDGET_ID`` unset or an alias, the first sync resolves "last-used"
+    and the mirror stays pinned to that budget, so switching budgets in YNAB
+    can't mix two budgets' rows.
+    """
+    configured = _configured_budget_id()
+    states = await YnabSyncState.all().order_by("budget_id")
+    ids = [s.budget_id for s in states]
+    if len(ids) > 1 or (configured and ids and ids[0] != configured):
+        raise ValueError(
+            f"YNAB mirror holds budget(s) {', '.join(ids)} but YNAB_BUDGET_ID "
+            f"is {configured or 'unset'}; clear the ynab_* tables to switch budgets"
+        )
+    return states[0] if states else None
+
+
+def _backing_off() -> bool:
+    return time.monotonic() - _last_failure < FAILURE_BACKOFF_SECONDS
+
+
+def _is_fresh(state: YnabSyncState | None, max_age_seconds: int) -> bool:
+    return (
+        state is not None
+        and state.last_synced_at is not None
+        and datetime.now(timezone.utc) - _norm(state.last_synced_at)
+        <= timedelta(seconds=max_age_seconds)
+    )
+
+
+async def sync_ynab(full: bool = False, max_age_seconds: int | None = None) -> dict:
+    """Sync YNAB into Postgres. Returns per-entity counts of changed rows.
+
+    ``max_age_seconds`` (on-demand syncs from tools) skips the sync if the
+    mirror is already that fresh or YNAB failed recently. Both are checked
+    under the lock, so parallel tool calls share one sync or one failure.
+
+    The YNAB request runs before the DB transaction. An asyncio lock
+    serializes syncs in this process; a Postgres advisory lock plus a
+    server_knowledge check discards a payload if the other blue/green
+    container synced in the meantime.
+    """
+    global _last_failure
+    async with _sync_lock:
+        state = await _current_state()
+        if max_age_seconds is not None and (
+            _is_fresh(state, max_age_seconds) or _backing_off()
+        ):
+            return {"skipped": True}
+
+        now = datetime.now(timezone.utc)
+        base_knowledge = state.server_knowledge if state else None
+        first_sync = base_knowledge is None
+        full = (
+            full
+            or first_sync
+            or state.last_full_sync_at is None
+            or now - _norm(state.last_full_sync_at) > FULL_RESYNC_INTERVAL
+        )
+        budget_id = state.budget_id if state else _configured_budget_id()
+        budget_id = budget_id or "last-used"
+
+        try:
+            data = await YNABService().fetch_budget(
+                budget_id, None if full else base_knowledge
+            )
+            budget = data["budget"]
+            knowledge = data["server_knowledge"]
+            if state is not None and budget["id"] != state.budget_id:
+                raise ValueError(
+                    f"YNAB returned budget {budget['id']} for {state.budget_id}"
+                )
+            async with in_transaction() as conn:
+                await conn.execute_query(
+                    "SELECT pg_advisory_xact_lock(hashtext('ynab_sync'))"
+                )
+                latest = await YnabSyncState.get_or_none(
+                    budget_id=budget["id"]
+                ).using_db(conn)
+                if (latest.server_knowledge if latest else None) != base_knowledge:
+                    logger.info("YNAB sync skipped: mirror changed during fetch")
+                    return {"skipped": True}
+
+                counts = await apply_budget(
+                    budget, knowledge, conn, log_changes=not first_sync, full=full
+                )
+                await YnabSyncState.update_or_create(
+                    budget_id=budget["id"],
+                    defaults={
+                        "budget_name": budget.get("name"),
+                        "server_knowledge": knowledge,
+                        "last_synced_at": now,
+                        "last_error": None,
+                        **({"last_full_sync_at": now} if full else {}),
+                    },
+                    using_db=conn,
+                )
+        except Exception as e:
+            _last_failure = time.monotonic()
+            if state is not None:
+                await YnabSyncState.filter(budget_id=state.budget_id).update(
+                    last_error=f"{type(e).__name__}: {e}"[:2000]
+                )
+            raise
+
+    changed = {k: v for k, v in counts.items() if v}
+    if changed:
+        logger.info(f"YNAB {'full' if full else 'delta'} sync @{knowledge}: {changed}")
+    return {"full": full, "server_knowledge": knowledge, "changed": changed}
+
+
+async def ensure_fresh(max_age_seconds: int = 120) -> YnabSyncState | None:
+    """Sync if the mirror is older than ``max_age_seconds``.
+
+    Used by agent tools before answering. A failed sync is logged and the
+    (possibly stale) mirror is used anyway, and YNAB isn't retried for
+    ``FAILURE_BACKOFF_SECONDS``. Returns None only if the mirror has never
+    been populated.
+    """
+    state = await _current_state()
+    if not _is_fresh(state, max_age_seconds) and not _backing_off():
+        try:
+            await sync_ynab(max_age_seconds=max_age_seconds)
+        except Exception:
+            logger.exception("YNAB sync failed; answering from existing mirror")
+        state = await _current_state()
+    if state is None or state.server_knowledge is None:
+        return None
+    return state
+
+
+async def ynab_sync_loop() -> None:
+    """Background task: delta-sync YNAB every ``YNAB_SYNC_INTERVAL`` seconds."""
+    interval = int(os.getenv("YNAB_SYNC_INTERVAL", "900"))
+    logger.info(f"YNAB sync loop started (interval={interval}s)")
+    while True:
+        try:
+            await sync_ynab()
+        except Exception:
+            logger.exception("YNAB sync error")
+        await asyncio.sleep(interval)

blueprints/ynab/tools.py

@@ -0,0 +1,615 @@
+"""LangChain agent tools that answer YNAB questions from the local mirror.
+
+Every tool calls ``ensure_fresh`` first, which runs a cheap delta sync when
+the mirror is more than a couple of minutes old.
+"""
+
+import functools
+import json
+import logging
+from datetime import date, datetime, timedelta
+from decimal import Decimal
+from zoneinfo import ZoneInfo
+
+from langchain.tools import tool
+from tortoise import connections
+
+from blueprints.conversation.artifacts_util import (
+    format_date_range,
+    format_month,
+    json_safe,
+    make_artifact,
+)
+
+from .sync import ensure_fresh
+
+logger = logging.getLogger(__name__)
+
+NOT_SYNCED = "YNAB data is unavailable: the budget has not been synced yet."
+
+# Keep in step with TOOL_RESULT_MAX_CHARS in blueprints/conversation/logic.py;
+# longer results get truncated there anyway and crowd the 32k context.
+MAX_TRANSACTIONS = 40
+# Rows in the ynab.transactions artifact (the side panel, not the LLM)
+ARTIFACT_MAX_TRANSACTIONS = 500
+
+# ynab_recent_changes accepts the names it prints as well as stored types
+ENTITY_TYPE_ALIASES = {
+    "assignment": "month_category",
+    "transfer": "transaction",
+    "split": "subtransaction",
+    "group": "category_group",
+}
+ENTITY_TYPES = (
+    "transaction",
+    "month",
+    "subtransaction",
+    "month_category",
+    "category",
+    "category_group",
+    "payee",
+    "account",
+)
+
+
+def _singular(word: str) -> str:
+    if word.endswith("ies"):
+        return word[:-3] + "y"  # categories -> category
+    return word.removesuffix("s")
+
+
+def ynab_tool_errors(fn):
+    """Return errors to the model as text: LangGraph's ToolNode re-raises
+    anything else, which would fail the whole chat turn."""
+
+    @functools.wraps(fn)
+    async def wrapper(*args, **kwargs):
+        try:
+            return await fn(*args, **kwargs)
+        except Exception as e:
+            logger.exception(f"{fn.__name__} failed")
+            return f"YNAB error in {fn.__name__}: {type(e).__name__}: {e}"
+
+    return wrapper
+
+
+def ynab_artifact_tool(fn):
+    """For content_and_artifact tools: errors become (text, None), and bare
+    strings (not-synced, bad input, empty results) get no artifact."""
+    wrapped = ynab_tool_errors(fn)
+
+    @functools.wraps(fn)
+    async def wrapper(*args, **kwargs):
+        result = await wrapped(*args, **kwargs)
+        return (result, None) if isinstance(result, str) else result
+
+    return wrapper
+
+
+# Every transaction line, with split transactions expanded into their
+# subtransactions so category/payee filters see the real allocation.
+LINES_CTE = """
+WITH lines AS (
+    SELECT t.id, t.date, t.amount, t.memo, t.cleared, t.approved,
+           t.account_id, t.account_name, t.payee_name, t.category_id,
+           t.category_name, t.transfer_account_id
+    FROM ynab_transactions t
+    WHERE NOT t.deleted AND NOT EXISTS (
+        SELECT 1 FROM ynab_subtransactions s
+        WHERE s.transaction_id = t.id AND NOT s.deleted
+    )
+    UNION ALL
+    SELECT s.id, t.date, s.amount, COALESCE(s.memo, t.memo), t.cleared, t.approved,
+           t.account_id, t.account_name, COALESCE(sp.name, t.payee_name),
+           s.category_id, sc.name, s.transfer_account_id
+    FROM ynab_subtransactions s
+    JOIN ynab_transactions t ON t.id = s.transaction_id
+    LEFT JOIN ynab_payees sp ON sp.id = s.payee_id
+    LEFT JOIN ynab_categories sc ON sc.id = s.category_id
+    WHERE NOT s.deleted AND NOT t.deleted
+)
+"""
+
+# Spending = outflows (net of refunds) on budget accounts, excluding transfers
+# (credit card payments, moves to savings) and income.
+SPENDING_FILTER = """
+    a.on_budget AND l.transfer_account_id IS NULL
+    AND NOT COALESCE(c.internal, false)
+"""
+
+GROUP_BY_EXPR = {
+    "category": "COALESCE(l.category_name, 'Uncategorized')",
+    "category_group": "COALESCE(g.name, 'Uncategorized')",
+    "payee": "COALESCE(l.payee_name, 'Unknown payee')",
+    "account": "l.account_name",
+    "month": "to_char(l.date, 'YYYY-MM')",
+}
+
+
+def _today() -> date:
+    return datetime.now(ZoneInfo("America/New_York")).date()
+
+
+def _usd(value: Decimal | float | None) -> str:
+    value = Decimal(value or 0)
+    sign = "-" if value < 0 else ""
+    return f"{sign}${abs(value):,.2f}"
+
+
+def _amount(value: Decimal | float | None) -> float:
+    """Dollar amount for artifacts (JSON has no Decimal)."""
+    return float(value or 0)
+
+
+def _parse_date(value: str, default: date | None) -> date | None:
+    return date.fromisoformat(value) if value else default
+
+
+def _month_start(month: str) -> date:
+    if not month:
+        return _today().replace(day=1)
+    return date.fromisoformat(month[:7] + "-01")
+
+
+async def _query(sql: str, *params) -> list[dict]:
+    return await connections.get("default").execute_query_dict(sql, list(params))
+
+
+@tool(response_format="content_and_artifact")
+@ynab_artifact_tool
+async def ynab_budget_summary(month: str = ""):
+    """Get YNAB budget overview for a month: Ready to Assign, income, assigned, spent, age of money, overspent categories, and net worth.
+
+    Args:
+        month: YYYY-MM (default: current month)
+    """
+    state = await ensure_fresh()
+    if state is None:
+        return NOT_SYNCED
+    try:
+        start = _month_start(month)
+    except ValueError:
+        return "Month must be YYYY-MM."
+
+    months = await _query("SELECT * FROM ynab_months WHERE month = $1", start)
+    if not months:
+        return f"No YNAB budget data for {start:%Y-%m}."
+    m = months[0]
+
+    overspent = await _query(
+        """SELECT c.name, mc.balance FROM ynab_month_categories mc
+           JOIN ynab_categories c ON c.id = mc.category_id
+           WHERE mc.month = $1 AND mc.balance < 0 AND NOT mc.deleted
+             AND NOT c.deleted AND NOT c.internal
+           ORDER BY mc.balance""",
+        start,
+    )
+    # YNAB's month "activity" nets in credit card payment categories, which
+    # go up whenever a card is used, so compute spending from transactions.
+    next_month = (start.replace(day=28) + timedelta(days=4)).replace(day=1)
+    spent = await _query(
+        f"""{LINES_CTE}
+            SELECT COALESCE(-SUM(l.amount), 0) AS spent FROM lines l
+            JOIN ynab_accounts a ON a.id = l.account_id
+            LEFT JOIN ynab_categories c ON c.id = l.category_id
+            WHERE {SPENDING_FILTER} AND l.date >= $1 AND l.date < $2""",
+        start,
+        next_month,
+    )
+    accounts = await _query(
+        """SELECT on_budget, SUM(balance) AS total FROM ynab_accounts
+           WHERE NOT deleted AND NOT closed GROUP BY on_budget"""
+    )
+    by_budget = {r["on_budget"]: r["total"] for r in accounts}
+
+    lines = [
+        f"YNAB budget '{state.budget_name}' for {start:%Y-%m}:",
+        f"Ready to Assign: {_usd(m['to_be_budgeted'])}",
+        f"Income: {_usd(m['income'])}",
+        f"Assigned: {_usd(m['budgeted'])}",
+        f"Spent: {_usd(spent[0]['spent'])}",
+    ]
+    if m["age_of_money"] is not None:
+        lines.append(f"Age of money: {m['age_of_money']} days")
+    if overspent:
+        lines.append(
+            "Overspent: "
+            + ", ".join(f"{r['name']} ({_usd(r['balance'])})" for r in overspent)
+        )
+    else:
+        lines.append("No overspent categories.")
+    net_worth = sum(by_budget.values(), Decimal(0))
+    lines.append(
+        f"Net worth: {_usd(net_worth)} "
+        f"(budget accounts {_usd(by_budget.get(True))}, "
+        f"tracking accounts {_usd(by_budget.get(False))})"
+    )
+    data = {
+        "month": f"{start:%Y-%m}",
+        "ready_to_assign": _amount(m["to_be_budgeted"]),
+        "income": _amount(m["income"]),
+        "assigned": _amount(m["budgeted"]),
+        "spent": _amount(spent[0]["spent"]),
+        "net_worth": _amount(net_worth),
+        "overspent": [
+            {"name": r["name"], "available": _amount(r["balance"])} for r in overspent
+        ],
+    }
+    if m["age_of_money"] is not None:
+        data["age_of_money"] = m["age_of_money"]
+    artifact = make_artifact(
+        "ynab.summary", f"Budget · {format_month(data['month'])}", json_safe(data)
+    )
+    return "\n".join(lines), artifact
+
+
+@tool
+@ynab_tool_errors
+async def ynab_account_balances(include_closed: bool = False) -> str:
+    """List YNAB accounts (checking, savings, credit cards, investments) with current balances.
+
+    Args:
+        include_closed: Also list closed accounts
+    """
+    if await ensure_fresh() is None:
+        return NOT_SYNCED
+    rows = await _query(
+        """SELECT name, type, on_budget, closed, balance, cleared_balance
+           FROM ynab_accounts WHERE NOT deleted AND (NOT closed OR $1)
+           ORDER BY on_budget DESC, type, name""",
+        include_closed,
+    )
+    if not rows:
+        return "No YNAB accounts found."
+    lines = []
+    for r in rows:
+        tags = [r["type"]] + ([] if r["on_budget"] else ["tracking"])
+        if r["closed"]:
+            tags.append("closed")
+        line = f"- {r['name']} [{', '.join(tags)}]: {_usd(r['balance'])}"
+        if r["cleared_balance"] != r["balance"]:
+            line += f" (cleared {_usd(r['cleared_balance'])})"
+        lines.append(line)
+    total = sum((r["balance"] for r in rows if not r["closed"]), Decimal(0))
+    return "\n".join(lines) + f"\n\nNet worth (open accounts): {_usd(total)}"
+
+
+@tool(response_format="content_and_artifact")
+@ynab_artifact_tool
+async def ynab_search_transactions(
+    start_date: str = "",
+    end_date: str = "",
+    payee: str = "",
+    category: str = "",
+    account: str = "",
+    memo: str = "",
+    min_amount: float = 0,
+    max_amount: float = 0,
+    limit: int = 20,
+):
+    """Search YNAB transactions. Split transactions are expanded into their category lines.
+
+    Args:
+        start_date: YYYY-MM-DD (default: 30 days ago if no other filter, else all time)
+        end_date: YYYY-MM-DD (default: today)
+        payee: Partial match on payee/store name
+        category: Partial match on category name
+        account: Partial match on account name
+        memo: Partial match on memo
+        min_amount: Minimum absolute dollar amount
+        max_amount: Maximum absolute dollar amount
+        limit: Max transactions to list (default 20, max 40)
+    """
+    if await ensure_fresh() is None:
+        return NOT_SYNCED
+
+    has_filter = any([payee, category, account, memo, min_amount, max_amount])
+    try:
+        default_start = (
+            None if has_filter else date.fromordinal(_today().toordinal() - 30)
+        )
+        start = _parse_date(start_date, default_start)
+        end = _parse_date(end_date, _today())
+    except ValueError:
+        return "Dates must be YYYY-MM-DD."
+
+    conditions, params = ["l.date <= $1"], [end]
+
+    def add(condition: str, value) -> None:
+        params.append(value)
+        conditions.append(condition.replace("?", f"${len(params)}"))
+
+    if start:
+        add("l.date >= ?", start)
+    if payee:
+        add("l.payee_name ILIKE ?", f"%{payee}%")
+    if category:
+        add("l.category_name ILIKE ?", f"%{category}%")
+    if account:
+        add("l.account_name ILIKE ?", f"%{account}%")
+    if memo:
+        add("l.memo ILIKE ?", f"%{memo}%")
+    if min_amount:
+        add("abs(l.amount) >= ?", Decimal(str(min_amount)))
+    if max_amount:
+        add("abs(l.amount) <= ?", Decimal(str(max_amount)))
+
+    where = " AND ".join(conditions)
+    totals = await _query(
+        f"""{LINES_CTE}
+            SELECT count(*) AS n,
+                   COALESCE(SUM(amount) FILTER (WHERE amount < 0), 0) AS outflow,
+                   COALESCE(SUM(amount) FILTER (WHERE amount > 0), 0) AS inflow
+            FROM lines l WHERE {where}""",
+        *params,
+    )
+    count = totals[0]["n"]
+    range_text = f"{start or 'the beginning'} to {end}"
+    if not count:
+        return f"No transactions found from {range_text}."
+
+    limit = min(max(1, limit), MAX_TRANSACTIONS)
+    # One query feeds both the text (first `limit` rows) and the artifact; the
+    # id tie-break keeps the order stable regardless of LIMIT.
+    all_rows = await _query(
+        f"""{LINES_CTE}
+            SELECT * FROM lines l WHERE {where}
+            ORDER BY l.date DESC, abs(l.amount) DESC, l.id
+            LIMIT {ARTIFACT_MAX_TRANSACTIONS}""",
+        *params,
+    )
+    rows = all_rows[:limit]
+    lines = [
+        f"Found {count} transactions from {range_text}. "
+        f"Outflows {_usd(totals[0]['outflow'])}, inflows {_usd(totals[0]['inflow'])}."
+    ]
+    for r in rows:
+        line = (
+            f"- {r['date']}: {r['payee_name'] or 'Unknown payee'} {_usd(r['amount'])} "
+            f"({r['category_name'] or 'Uncategorized'}; {r['account_name']})"
+        )
+        if r["memo"]:
+            line += f" — {r['memo']}"
+        if not r["approved"]:
+            line += " [unapproved]"
+        lines.append(line)
+    if count > len(rows):
+        lines.append(f"(Showing {len(rows)} most recent of {count})")
+
+    transactions = []
+    for r in all_rows:
+        txn = {
+            "date": r["date"],
+            "payee": r["payee_name"] or "Unknown payee",
+            "category": r["category_name"] or "Uncategorized",
+            "account": r["account_name"],
+            "amount": _amount(r["amount"]),
+        }
+        if r["memo"]:
+            txn["memo"] = r["memo"]
+        transactions.append(txn)
+    title_range = format_date_range(str(start), str(end)) if start else f"through {end}"
+    artifact = make_artifact(
+        "ynab.transactions",
+        f"Transactions · {title_range}",
+        json_safe(
+            {
+                "start_date": start,
+                "end_date": end,
+                "count": count,
+                "total": _amount(totals[0]["outflow"] + totals[0]["inflow"]),
+                "transactions": transactions,
+            }
+        ),
+    )
+    return "\n".join(lines), artifact
+
+
+@tool(response_format="content_and_artifact")
+@ynab_artifact_tool
+async def ynab_spending_report(
+    group_by: str = "category",
+    start_date: str = "",
+    end_date: str = "",
+    category: str = "",
+    payee: str = "",
+    top: int = 15,
+):
+    """Total YNAB spending grouped by category, category_group, payee, account, or month. Use group_by='month' for trends over time.
+
+    Args:
+        group_by: category, category_group, payee, account, or month
+        start_date: YYYY-MM-DD (default: first of current month)
+        end_date: YYYY-MM-DD (default: today)
+        category: Partial match on category name
+        payee: Partial match on payee name
+        top: Max groups to list (default 15)
+    """
+    if await ensure_fresh() is None:
+        return NOT_SYNCED
+    key = GROUP_BY_EXPR.get(group_by)
+    if key is None:
+        return f"group_by must be one of: {', '.join(GROUP_BY_EXPR)}."
+    try:
+        start = _parse_date(start_date, _today().replace(day=1))
+        end = _parse_date(end_date, _today())
+    except ValueError:
+        return "Dates must be YYYY-MM-DD."
+
+    conditions, params = [SPENDING_FILTER, "l.date >= $1", "l.date <= $2"], [start, end]
+    if category:
+        params.append(f"%{category}%")
+        conditions.append(f"l.category_name ILIKE ${len(params)}")
+    if payee:
+        params.append(f"%{payee}%")
+        conditions.append(f"l.payee_name ILIKE ${len(params)}")
+
+    order = "key" if group_by == "month" else "spent DESC"
+    rows = await _query(
+        f"""{LINES_CTE}
+            SELECT {key} AS key, -SUM(l.amount) AS spent, count(*) AS n
+            FROM lines l
+            JOIN ynab_accounts a ON a.id = l.account_id
+            LEFT JOIN ynab_categories c ON c.id = l.category_id
+            LEFT JOIN ynab_category_groups g ON g.id = c.category_group_id
+            WHERE {" AND ".join(conditions)}
+            GROUP BY 1 ORDER BY {order}""",
+        *params,
+    )
+    if not rows:
+        return f"No spending found from {start} to {end}."
+
+    total = sum((r["spent"] for r in rows), Decimal(0))
+    top = max(1, top)
+    shown = rows if group_by == "month" else rows[:top]
+    lines = [f"Spending by {group_by} from {start} to {end}: total {_usd(total)}"]
+    lines += [f"- {r['key']}: {_usd(r['spent'])} ({r['n']} txns)" for r in shown]
+    if len(rows) > len(shown):
+        rest = sum((r["spent"] for r in rows[len(shown) :]), Decimal(0))
+        lines.append(f"- {len(rows) - len(shown)} others: {_usd(rest)}")
+    if group_by == "month" and len(rows) > 1:
+        lines.append(f"Monthly average: {_usd(total / len(rows))}")
+    artifact = make_artifact(
+        "ynab.spending_report",
+        f"Spending by {group_by.replace('_', ' ')} · "
+        f"{format_date_range(str(start), str(end))}",
+        json_safe(
+            {
+                "start_date": start,
+                "end_date": end,
+                "group_by": group_by,
+                "rows": [
+                    {"key": r["key"], "amount": _amount(r["spent"]), "count": r["n"]}
+                    for r in rows
+                ],
+                "total": _amount(total),
+            }
+        ),
+    )
+    return "\n".join(lines), artifact
+
+
+@tool(response_format="content_and_artifact")
+@ynab_artifact_tool
+async def ynab_category_budget(month: str = "", category_group: str = ""):
+    """Get YNAB categories for a month grouped by category group: assigned, activity (negative = spent), available, and goal target. Flags overspending.
+
+    Args:
+        month: YYYY-MM (default: current month)
+        category_group: Partial match to show only one group
+    """
+    if await ensure_fresh() is None:
+        return NOT_SYNCED
+    try:
+        start = _month_start(month)
+    except ValueError:
+        return "Month must be YYYY-MM."
+
+    rows = await _query(
+        """SELECT g.name AS group_name, c.name, c.goal_target,
+                  mc.budgeted, mc.activity, mc.balance
+           FROM ynab_month_categories mc
+           JOIN ynab_categories c ON c.id = mc.category_id
+           JOIN ynab_category_groups g ON g.id = c.category_group_id
+           WHERE mc.month = $1 AND NOT mc.deleted
+             AND NOT c.deleted AND NOT c.hidden AND NOT c.internal
+             AND NOT g.deleted AND NOT g.hidden
+             AND g.name ILIKE $2
+           ORDER BY g.name, c.name""",
+        start,
+        f"%{category_group}%",
+    )
+    if not rows:
+        return f"No YNAB category data for {start:%Y-%m}."
+
+    lines = [f"Categories for {start:%Y-%m}:"]
+    current = None
+    groups = []
+    for r in rows:
+        if not (r["budgeted"] or r["activity"] or r["balance"]):
+            continue
+        if r["group_name"] != current:
+            current = r["group_name"]
+            lines.append(f"\n{current}")
+            groups.append({"name": current, "categories": []})
+        category = {
+            "name": r["name"],
+            "assigned": _amount(r["budgeted"]),
+            "activity": _amount(r["activity"]),
+            "available": _amount(r["balance"]),
+        }
+        if r["goal_target"]:
+            category["goal_target"] = _amount(r["goal_target"])
+        groups[-1]["categories"].append(category)
+        line = (
+            f"  {r['name']}: assigned {_usd(r['budgeted'])}, "
+            f"activity {_usd(r['activity'])}, available {_usd(r['balance'])}"
+        )
+        if r["goal_target"]:
+            line += f", goal {_usd(r['goal_target'])}"
+        if r["balance"] < 0:
+            line += " [OVERSPENT]"
+        lines.append(line)
+    artifact = None
+    if groups:
+        artifact = make_artifact(
+            "ynab.category_budget",
+            f"Category budget · {format_month(f'{start:%Y-%m}')}",
+            json_safe({"month": f"{start:%Y-%m}", "groups": groups}),
+        )
+    return "\n".join(lines), artifact
+
+
+@tool
+@ynab_tool_errors
+async def ynab_recent_changes(days: int = 7, entity_type: str = "") -> str:
+    """Show what changed in YNAB recently: new/edited/deleted transactions, assignment changes, renamed categories or payees.
+
+    Args:
+        days: Look back this many days (default 7)
+        entity_type: Optional filter: transaction, assignment, category, payee, account, month
+    """
+    if await ensure_fresh() is None:
+        return NOT_SYNCED
+    entity_type = _singular(entity_type.strip().lower().replace(" ", "_"))
+    entity_type = ENTITY_TYPE_ALIASES.get(entity_type, entity_type)
+    if entity_type and entity_type not in ENTITY_TYPES:
+        return f"Unknown entity_type '{entity_type}'. Use one of: transaction, assignment, category, category_group, payee, account, month."
+    rows = await _query(
+        """SELECT synced_at, entity_type, action, label, changes FROM ynab_changes
+           WHERE synced_at >= now() - make_interval(days => $1)
+             AND ($2 = '' OR entity_type = $2)
+           ORDER BY id DESC LIMIT 40""",
+        max(1, days),
+        entity_type,
+    )
+    if not rows:
+        return f"No YNAB changes recorded in the last {days} days."
+
+    lines = []
+    for r in rows:
+        when = r["synced_at"].astimezone(ZoneInfo("America/New_York"))
+        changes = r["changes"]
+        if isinstance(changes, str):
+            changes = json.loads(changes)
+        if r["action"] == "updated":
+            detail = "; ".join(
+                f"{field}: {old} → {new}" for field, (old, new) in changes.items()
+            )
+        else:
+            detail = ""
+        entity = r["entity_type"].replace("month_category", "assignment")
+        line = f"- {when:%Y-%m-%d %H:%M} {r['action']} {entity} '{r['label']}'"
+        lines.append(line + (f": {detail}" if detail else ""))
+    note = " (newest 40)" if len(rows) == 40 else ""
+    return f"YNAB changes in the last {days} days{note}:\n" + "\n".join(lines)
+
+
+YNAB_TOOLS = [
+    ynab_budget_summary,
+    ynab_account_balances,
+    ynab_search_transactions,
+    ynab_spending_report,
+    ynab_category_budget,
+    ynab_recent_changes,
+]

config/db.py

@@ -16,6 +16,11 @@ TORTOISE_CONFIG = {
                 "blueprints.conversation.models",
                 "blueprints.users.models",
                 "blueprints.email.models",
+                "blueprints.scheduled_messages.models",
+                "blueprints.cron.models",
+                "blueprints.beli.models",
+                "blueprints.artifacts.models",
+                "blueprints.ynab.models",
                 "aerich.models",
             ],
             "default_connection": "default",

desktop/.gitignore

@@ -0,0 +1,3 @@
+node_modules/
+src-tauri/target/
+src-tauri/gen/

desktop/package-lock.json

@@ -0,0 +1,232 @@
+{
+  "name": "simba-desktop",
+  "version": "0.1.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "simba-desktop",
+      "version": "0.1.0",
+      "devDependencies": {
+        "@tauri-apps/cli": "^2.12.2"
+      }
+    },
+    "node_modules/@tauri-apps/cli": {
+      "version": "2.12.2",
+      "resolved": "https://registry.npmjs.org/@tauri-apps/cli/-/cli-2.12.2.tgz",
+      "integrity": "sha512-PMSppzAnlT+BvZtRKuidxjRSm2r5t8kDpJ/czmmQUa0AtDNTwrjLE8vApK3phCWGg7isfnYL46Dl1jB4ArI0hA==",
+      "dev": true,
+      "license": "Apache-2.0 OR MIT",
+      "bin": {
+        "tauri": "tauri.js"
+      },
+      "engines": {
+        "node": ">= 10"
+      },
+      "funding": {
+        "type": "opencollective",
+        "url": "https://opencollective.com/tauri"
+      },
+      "optionalDependencies": {
+        "@tauri-apps/cli-darwin-arm64": "2.12.2",
+        "@tauri-apps/cli-darwin-x64": "2.12.2",
+        "@tauri-apps/cli-linux-arm-gnueabihf": "2.12.2",
+        "@tauri-apps/cli-linux-arm64-gnu": "2.12.2",
+        "@tauri-apps/cli-linux-arm64-musl": "2.12.2",
+        "@tauri-apps/cli-linux-riscv64-gnu": "2.12.2",
+        "@tauri-apps/cli-linux-x64-gnu": "2.12.2",
+        "@tauri-apps/cli-linux-x64-musl": "2.12.2",
+        "@tauri-apps/cli-win32-arm64-msvc": "2.12.2",
+        "@tauri-apps/cli-win32-ia32-msvc": "2.12.2",
+        "@tauri-apps/cli-win32-x64-msvc": "2.12.2"
+      }
+    },
+    "node_modules/@tauri-apps/cli-darwin-arm64": {
+      "version": "2.12.2",
+      "resolved": "https://registry.npmjs.org/@tauri-apps/cli-darwin-arm64/-/cli-darwin-arm64-2.12.2.tgz",
+      "integrity": "sha512-Lk3zaBTfzNvA7670Al5PNgo2M/95uaDPe1yp+ILJeDOmol87XiYuK5E5+FUbK5e6U6OORx9qpZdOo2U+5tETtQ==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "Apache-2.0 OR MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">= 10"
+      }
+    },
+    "node_modules/@tauri-apps/cli-darwin-x64": {
+      "version": "2.12.2",
+      "resolved": "https://registry.npmjs.org/@tauri-apps/cli-darwin-x64/-/cli-darwin-x64-2.12.2.tgz",
+      "integrity": "sha512-2CyYjJ833JB3sKRz4B0W/Tv4oOVC16ws1bxdSCWj1XvrmanWwvZi99e5tNIoCHwHhcOm0jh+sh0PCGQyls6Z+w==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "Apache-2.0 OR MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">= 10"
+      }
+    },
+    "node_modules/@tauri-apps/cli-linux-arm-gnueabihf": {
+      "version": "2.12.2",
+      "resolved": "https://registry.npmjs.org/@tauri-apps/cli-linux-arm-gnueabihf/-/cli-linux-arm-gnueabihf-2.12.2.tgz",
+      "integrity": "sha512-uvt2xbone4JftKarelssi86Kqnl7JiG1Smh5+Ae+nZmtM+JUhTGmqkcqfUPXRW8Ygwog92POZvd4oGDN9j8eXQ==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "Apache-2.0 OR MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">= 10"
+      }
+    },
+    "node_modules/@tauri-apps/cli-linux-arm64-gnu": {
+      "version": "2.12.2",
+      "resolved": "https://registry.npmjs.org/@tauri-apps/cli-linux-arm64-gnu/-/cli-linux-arm64-gnu-2.12.2.tgz",
+      "integrity": "sha512-DZlDJ24u3tlocKOYqzR+b2M+Qr+5WFcoMBZ7EfdhHN5j3ZXwBBpms4G4gyNvPCrak5vMzmdZ65ecBXPJcC+5sA==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "Apache-2.0 OR MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">= 10"
+      }
+    },
+    "node_modules/@tauri-apps/cli-linux-arm64-musl": {
+      "version": "2.12.2",
+      "resolved": "https://registry.npmjs.org/@tauri-apps/cli-linux-arm64-musl/-/cli-linux-arm64-musl-2.12.2.tgz",
+      "integrity": "sha512-pb+RTZUYH/p0gR4j4ecCCq+FNfz3W3eKuUQvVEBn7MQZx6DzfLO7FaYzt2NyDKWpdNN3lP10mdzOvw3R5P5aAQ==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "Apache-2.0 OR MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">= 10"
+      }
+    },
+    "node_modules/@tauri-apps/cli-linux-riscv64-gnu": {
+      "version": "2.12.2",
+      "resolved": "https://registry.npmjs.org/@tauri-apps/cli-linux-riscv64-gnu/-/cli-linux-riscv64-gnu-2.12.2.tgz",
+      "integrity": "sha512-nidEvDUJyHYNbIv9MUk6KiEix8IXfRh4Wj2G2SA5g8nFmgbBCwazUNWYiG/LhNeNbfZpBMLerRBUtoQ5K0GidA==",
+      "cpu": [
+        "riscv64"
+      ],
+      "dev": true,
+      "license": "Apache-2.0 OR MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">= 10"
+      }
+    },
+    "node_modules/@tauri-apps/cli-linux-x64-gnu": {
+      "version": "2.12.2",
+      "resolved": "https://registry.npmjs.org/@tauri-apps/cli-linux-x64-gnu/-/cli-linux-x64-gnu-2.12.2.tgz",
+      "integrity": "sha512-gkXyYn3w+Xfc8nz/DleEbkm1M7bBuU2cejqUXNmI98cA2P5kp+oPmS4ALTorb1FaNWjpsKoYZBWsbS9BXxYFkQ==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "Apache-2.0 OR MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">= 10"
+      }
+    },
+    "node_modules/@tauri-apps/cli-linux-x64-musl": {
+      "version": "2.12.2",
+      "resolved": "https://registry.npmjs.org/@tauri-apps/cli-linux-x64-musl/-/cli-linux-x64-musl-2.12.2.tgz",
+      "integrity": "sha512-MrjgoZ09s8Hsn99XvxSNvK8NQTZxi7XiyK3FxxytzfHgz2jb3qUT69CZtsokRkN/zdi9rCgrMtq+w9XNICjcfQ==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "Apache-2.0 OR MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">= 10"
+      }
+    },
+    "node_modules/@tauri-apps/cli-win32-arm64-msvc": {
+      "version": "2.12.2",
+      "resolved": "https://registry.npmjs.org/@tauri-apps/cli-win32-arm64-msvc/-/cli-win32-arm64-msvc-2.12.2.tgz",
+      "integrity": "sha512-BR+CYM7iF3lkfyTtVkwMQU/s9hwegLpj3UqDjaxKCPmixQCa1csBBPy3C75V+FhLtOjIXNna4Gt6Vm9oxbV+qA==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "Apache-2.0 OR MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">= 10"
+      }
+    },
+    "node_modules/@tauri-apps/cli-win32-ia32-msvc": {
+      "version": "2.12.2",
+      "resolved": "https://registry.npmjs.org/@tauri-apps/cli-win32-ia32-msvc/-/cli-win32-ia32-msvc-2.12.2.tgz",
+      "integrity": "sha512-zODJo9l3TbNBM+GrO/yPqGeELNMK5cjIc+QHh1WQc3l8tD+jDZGTQyYuAxViCsM6Uh5uWJ//RnCZG9LXrvsXww==",
+      "cpu": [
+        "ia32"
+      ],
+      "dev": true,
+      "license": "Apache-2.0 OR MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">= 10"
+      }
+    },
+    "node_modules/@tauri-apps/cli-win32-x64-msvc": {
+      "version": "2.12.2",
+      "resolved": "https://registry.npmjs.org/@tauri-apps/cli-win32-x64-msvc/-/cli-win32-x64-msvc-2.12.2.tgz",
+      "integrity": "sha512-cQXI2ZaZmwBDt0XATCqASVanYizxkEE3ceQVlVHXaQ51HzsQUWA04c9Nz7LrrY2lgAu3jFMyat+8Yz3Z2R2qBA==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "Apache-2.0 OR MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">= 10"
+      }
+    }
+  }
+}

desktop/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "simba-desktop",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "tauri": "tauri",
+    "dev": "tauri dev",
+    "build": "tauri build --bundles app"
+  },
+  "devDependencies": {
+    "@tauri-apps/cli": "^2.12.2"
+  }
+}

desktop/src-tauri/Cargo.toml

@@ -0,0 +1,17 @@
+[package]
+name = "simba-desktop"
+version = "0.1.0"
+edition = "2021"
+
+[lib]
+name = "simba_desktop_lib"
+crate-type = ["staticlib", "cdylib", "rlib"]
+
+[build-dependencies]
+tauri-build = { version = "2", features = [] }
+
+[dependencies]
+tauri = { version = "2", features = ["tray-icon", "image-png"] }
+tauri-plugin-global-shortcut = "2"
+tauri-plugin-single-instance = "2"
+url = "2"

desktop/src-tauri/build.rs

@@ -0,0 +1,3 @@
+fn main() {
+    tauri_build::build()
+}

desktop/src-tauri/capabilities/default.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "../gen/schemas/desktop-schema.json",
+  "identifier": "default",
+  "description": "Bundled pages only (offline/connect screen). The remote SimbaRAG origin gets no IPC.",
+  "windows": ["main"],
+  "permissions": ["core:default"]
+}

desktop/src-tauri/rust-toolchain.toml

@@ -0,0 +1,3 @@
+[toolchain]
+channel = "1.90.0"
+profile = "minimal"

desktop/src-tauri/src/lib.rs

@@ -0,0 +1,171 @@
+//! Simba desktop shell.
+//!
+//! A thin native wrapper around the deployed SimbaRAG web app: the main window
+//! starts on a bundled connect page (`ui/index.html`) that checks the server is
+//! reachable and then navigates to it. The Rust side owns everything the web
+//! app can't do: the menu-bar icon, the global hotkey, and keeping the app
+//! alive when the window is closed.
+
+use tauri::{
+    menu::{Menu, MenuItem, PredefinedMenuItem},
+    tray::{MouseButton, MouseButtonState, TrayIconBuilder, TrayIconEvent},
+    AppHandle, Manager, RunEvent, WebviewUrl, WebviewWindow, WebviewWindowBuilder, WindowEvent,
+};
+use tauri_plugin_global_shortcut::{Code, GlobalShortcutExt, Modifiers, Shortcut, ShortcutState};
+
+const MAIN: &str = "main";
+const DEFAULT_SERVER_URL: &str = "http://localhost:8080";
+
+/// Server URL: `SIMBA_URL` at runtime, else at build time, else localhost.
+fn server_url() -> String {
+    std::env::var("SIMBA_URL")
+        .ok()
+        .or_else(|| option_env!("SIMBA_URL").map(str::to_owned))
+        .unwrap_or_else(|| DEFAULT_SERVER_URL.to_owned())
+        .trim_end_matches('/')
+        .to_owned()
+}
+
+/// Bundled connect page, told which server to probe and open.
+fn connect_url() -> WebviewUrl {
+    let mut url = url::Url::parse("tauri://localhost/index.html").expect("static url");
+    url.query_pairs_mut().append_pair("server", &server_url());
+    WebviewUrl::App(format!("index.html?{}", url.query().unwrap_or_default()).into())
+}
+
+fn main_window(app: &AppHandle) -> Option<WebviewWindow> {
+    app.get_webview_window(MAIN)
+}
+
+fn show(app: &AppHandle) {
+    if let Some(window) = main_window(app) {
+        let _ = window.unminimize();
+        let _ = window.show();
+        let _ = window.set_focus();
+    }
+}
+
+fn toggle(app: &AppHandle) {
+    let Some(window) = main_window(app) else { return };
+    let focused = window.is_visible().unwrap_or(false) && window.is_focused().unwrap_or(false);
+    if focused {
+        let _ = window.hide();
+    } else {
+        show(app);
+    }
+}
+
+/// Re-run the connect page (server probe + redirect), e.g. after an outage.
+fn reconnect(app: &AppHandle) {
+    if let Some(window) = main_window(app) {
+        let WebviewUrl::App(path) = connect_url() else { return };
+        if let Ok(url) = url::Url::parse(&format!("tauri://localhost/{}", path.display())) {
+            let _ = window.navigate(url);
+        }
+        show(app);
+    }
+}
+
+fn new_chat(app: &AppHandle) {
+    if let Some(window) = main_window(app) {
+        if let Ok(url) = url::Url::parse(&format!("{}/", server_url())) {
+            let _ = window.navigate(url);
+        }
+        show(app);
+    }
+}
+
+fn build_tray(app: &AppHandle) -> tauri::Result<()> {
+    let show_item = MenuItem::with_id(app, "show", "Show Simba", true, Some("Alt+Space"))?;
+    let new_chat_item = MenuItem::with_id(app, "new_chat", "New Chat", true, None::<&str>)?;
+    let reconnect_item = MenuItem::with_id(app, "reconnect", "Reconnect", true, None::<&str>)?;
+    let quit_item = MenuItem::with_id(app, "quit", "Quit Simba", true, Some("Cmd+Q"))?;
+    let menu = Menu::with_items(
+        app,
+        &[
+            &show_item,
+            &new_chat_item,
+            &PredefinedMenuItem::separator(app)?,
+            &reconnect_item,
+            &PredefinedMenuItem::separator(app)?,
+            &quit_item,
+        ],
+    )?;
+
+    let mut tray = TrayIconBuilder::with_id("simba")
+        .tooltip("Simba")
+        .menu(&menu)
+        .show_menu_on_left_click(false)
+        .on_menu_event(|app, event| match event.id.as_ref() {
+            "show" => show(app),
+            "new_chat" => new_chat(app),
+            "reconnect" => reconnect(app),
+            "quit" => app.exit(0),
+            _ => {}
+        })
+        .on_tray_icon_event(|tray, event| {
+            if let TrayIconEvent::Click {
+                button: MouseButton::Left,
+                button_state: MouseButtonState::Up,
+                ..
+            } = event
+            {
+                toggle(tray.app_handle());
+            }
+        });
+    if let Some(icon) = app.default_window_icon() {
+        tray = tray.icon(icon.clone());
+    }
+    tray.build(app)?;
+    Ok(())
+}
+
+fn register_hotkey(app: &AppHandle) -> tauri::Result<()> {
+    let hotkey = Shortcut::new(Some(Modifiers::ALT), Code::Space);
+    app.plugin(
+        tauri_plugin_global_shortcut::Builder::new()
+            .with_handler(move |app, shortcut, event| {
+                if shortcut == &hotkey && event.state() == ShortcutState::Pressed {
+                    toggle(app);
+                }
+            })
+            .build(),
+    )?;
+    // Another app may already own ⌥Space; the tray still works without it.
+    if let Err(e) = app.global_shortcut().register(hotkey) {
+        eprintln!("simba: could not register Alt+Space: {e}");
+    }
+    Ok(())
+}
+
+pub fn run() {
+    tauri::Builder::default()
+        .plugin(tauri_plugin_single_instance::init(|app, _args, _cwd| show(app)))
+        .setup(|app| {
+            WebviewWindowBuilder::new(app, MAIN, connect_url())
+                .title("Simba")
+                .inner_size(1200.0, 820.0)
+                .min_inner_size(420.0, 520.0)
+                .build()?;
+            build_tray(app.handle())?;
+            register_hotkey(app.handle())?;
+            Ok(())
+        })
+        .on_window_event(|window, event| {
+            // Closing the window hides it; Simba lives on in the menu bar.
+            if let WindowEvent::CloseRequested { api, .. } = event {
+                if window.label() == MAIN {
+                    api.prevent_close();
+                    let _ = window.hide();
+                }
+            }
+        })
+        .build(tauri::generate_context!())
+        .expect("error while building Simba")
+        .run(|app, event| {
+            // Clicking the Dock icon brings the hidden window back.
+            if let RunEvent::Reopen { .. } = event {
+                show(app);
+            }
+        });
+}

desktop/src-tauri/src/main.rs

@@ -0,0 +1,6 @@
+// Prevents an extra console window on Windows in release builds.
+#![cfg_attr(not(debug_assertions), windows_subsystem = "windows")]
+
+fn main() {
+    simba_desktop_lib::run()
+}

desktop/src-tauri/tauri.conf.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "https://schema.tauri.app/config/2",
+  "productName": "Simba",
+  "version": "0.1.0",
+  "identifier": "co.torrtle.simba",
+  "build": {
+    "frontendDist": "../ui"
+  },
+  "app": {
+    "windows": [],
+    "security": {
+      "csp": null
+    }
+  },
+  "bundle": {
+    "active": true,
+    "targets": ["app"],
+    "icon": [
+      "icons/32x32.png",
+      "icons/128x128.png",
+      "icons/128x128@2x.png",
+      "icons/icon.icns",
+      "icons/icon.png"
+    ]
+  }
+}

desktop/ui/index.html

@@ -0,0 +1,88 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>Simba</title>
+  <style>
+    :root {
+      --cream: #FAF8F2;
+      --leaf: #2A4D38;
+      --muted: #7a7266;
+      --card: #ffffff;
+      --border: #e6e0d4;
+    }
+    @media (prefers-color-scheme: dark) {
+      :root { --cream: #1b1d1a; --leaf: #8fc4a1; --muted: #a39d92; --card: #24271f; --border: #34382f; }
+    }
+    * { box-sizing: border-box; }
+    body {
+      margin: 0; min-height: 100vh; display: grid; place-items: center;
+      background: var(--cream); color: var(--leaf);
+      font: 15px/1.5 -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+      -webkit-user-select: none; user-select: none;
+    }
+    main { text-align: center; padding: 16px; max-width: 360px; }
+    .cat { font-size: 48px; display: inline-block; animation: bob 1.2s ease-in-out infinite; }
+    .offline .cat { animation: none; filter: grayscale(1); }
+    @keyframes bob { 50% { transform: translateY(-6px); } }
+    h1 { font-size: 17px; margin: 12px 0 4px; }
+    p { margin: 0; color: var(--muted); font-size: 13px; }
+    code { font-size: 12px; background: var(--card); border: 1px solid var(--border); border-radius: 6px; padding: 1px 6px; }
+    button {
+      margin-top: 16px; padding: 6px 16px; border-radius: 999px; cursor: pointer;
+      border: 1px solid var(--border); background: var(--card); color: var(--leaf); font: inherit;
+    }
+    .online-only { display: block; }
+    .offline-only { display: none; }
+    .offline .online-only { display: none; }
+    .offline .offline-only { display: block; }
+  </style>
+</head>
+<body>
+  <main id="root">
+    <div class="cat">🐈</div>
+    <div class="online-only">
+      <h1>waking up simba…</h1>
+      <p>connecting to <code id="server-a"></code></p>
+    </div>
+    <div class="offline-only">
+      <h1>Can't reach Simba</h1>
+      <p><code id="server-b"></code> isn't responding. Retrying every few seconds.</p>
+      <button id="retry" type="button">Try now</button>
+    </div>
+  </main>
+  <script>
+    // The Rust shell passes the server in ?server=. Probe it, then hand the
+    // whole window over to the real web app.
+    const server = (new URLSearchParams(location.search).get("server") || "http://localhost:8080").replace(/\/+$/, "");
+    const root = document.getElementById("root");
+    document.getElementById("server-a").textContent = server;
+    document.getElementById("server-b").textContent = server;
+
+    let timer = null;
+
+    async function probe() {
+      clearTimeout(timer);
+      const ctrl = new AbortController();
+      const abort = setTimeout(() => ctrl.abort(), 5000);
+      try {
+        // no-cors: we only care that the server answered, not what it said.
+        await fetch(`${server}/api/health`, { mode: "no-cors", cache: "no-store", signal: ctrl.signal });
+        location.replace(`${server}/`);
+      } catch {
+        root.classList.add("offline");
+        timer = setTimeout(probe, 5000);
+      } finally {
+        clearTimeout(abort);
+      }
+    }
+
+    document.getElementById("retry").addEventListener("click", () => {
+      root.classList.remove("offline");
+      probe();
+    });
+    probe();
+  </script>
+</body>
+</html>

docker-compose.yml

@@ -1,8 +1,94 @@
 version: "3.8"
 
+x-raggr-common: &raggr-common
+  build:
+    context: .
+    dockerfile: Dockerfile
+  image: torrtle/simbarag:latest
+  environment:
+    - PAPERLESS_TOKEN=${PAPERLESS_TOKEN}
+    - BASE_URL=${BASE_URL}
+    - OLLAMA_URL=${OLLAMA_URL:-http://localhost:11434}
+    - OPENAI_API_KEY=${OPENAI_API_KEY}
+    - EMBEDDING_SERVER_URL=${EMBEDDING_SERVER_URL}
+    - EMBEDDING_MODEL_NAME=${EMBEDDING_MODEL_NAME}
+    - JWT_SECRET_KEY=${JWT_SECRET_KEY}
+    - LLAMA_SERVER_URL=${LLAMA_SERVER_URL}
+    - LLAMA_MODEL_NAME=${LLAMA_MODEL_NAME}
+    - OIDC_ISSUER=${OIDC_ISSUER}
+    - OIDC_CLIENT_ID=${OIDC_CLIENT_ID}
+    - OIDC_CLIENT_SECRET=${OIDC_CLIENT_SECRET}
+    - OIDC_REDIRECT_URI=${OIDC_REDIRECT_URI}
+    - OIDC_USE_DISCOVERY=${OIDC_USE_DISCOVERY:-true}
+    - DATABASE_URL=${DATABASE_URL:-postgres://raggr:changeme@postgres:5432/raggr}
+    - TAVILY_API_KEY=${TAVILIY_API_KEY}
+    - YNAB_ACCESS_TOKEN=${YNAB_ACCESS_TOKEN}
+    - YNAB_BUDGET_ID=${YNAB_BUDGET_ID}
+    - YNAB_SYNC_INTERVAL=${YNAB_SYNC_INTERVAL:-900}
+    - MEALIE_BASE_URL=${MEALIE_BASE_URL}
+    - MEALIE_API_TOKEN=${MEALIE_API_TOKEN}
+    - MEALIE_GROUP_SLUG=${MEALIE_GROUP_SLUG:-home}
+    - TWILIO_ACCOUNT_SID=${TWILIO_ACCOUNT_SID}
+    - TWILIO_AUTH_TOKEN=${TWILIO_AUTH_TOKEN}
+    - TWILIO_WHATSAPP_NUMBER=${TWILIO_WHATSAPP_NUMBER}
+    - ALLOWED_WHATSAPP_NUMBERS=${ALLOWED_WHATSAPP_NUMBERS}
+    - TWILIO_SIGNATURE_VALIDATION=${TWILIO_SIGNATURE_VALIDATION:-true}
+    - TWILIO_WEBHOOK_URL=${TWILIO_WEBHOOK_URL:-}
+    - OBSIDIAN_EMAIL=${OBSIDIAN_EMAIL}
+    - OBSIDIAN_PASSWORD=${OBSIDIAN_PASSWORD}
+    - OBSIDIAN_VAULT_ID=${OBSIDIAN_VAULT_ID}
+    - OBSIDIAN_E2E_PASSWORD=${OBSIDIAN_E2E_PASSWORD}
+    - OBSIDIAN_DEVICE_NAME=${OBSIDIAN_DEVICE_NAME}
+    - OBSIDIAN_CONTINUOUS_SYNC=${OBSIDIAN_CONTINUOUS_SYNC:-false}
+    - OBSIDIAN_VAULT_PATH=${OBSIDIAN_VAULT_PATH:-/app/data/obsidian}
+    - OBSIDIAN_VAULT_NAME=${OBSIDIAN_VAULT_NAME:-}
+    - S3_ENDPOINT_URL=${S3_ENDPOINT_URL}
+    - S3_ACCESS_KEY_ID=${S3_ACCESS_KEY_ID}
+    - S3_SECRET_ACCESS_KEY=${S3_SECRET_ACCESS_KEY}
+    - S3_BUCKET_NAME=${S3_BUCKET_NAME:-asksimba-images}
+    - S3_REGION=${S3_REGION:-garage}
+    - OLLAMA_HOST=${OLLAMA_HOST:-http://localhost:11434}
+    - FERNET_KEY=${FERNET_KEY}
+    - GOOGLE_TOKEN_FILE=${GOOGLE_TOKEN_FILE:-/app/config/google-token.json}
+    - MAILGUN_API_KEY=${MAILGUN_API_KEY}
+    - MAILGUN_DOMAIN=${MAILGUN_DOMAIN}
+    - MAILGUN_WEBHOOK_SIGNING_KEY=${MAILGUN_WEBHOOK_SIGNING_KEY}
+    - MAILGUN_SIGNATURE_VALIDATION=${MAILGUN_SIGNATURE_VALIDATION:-true}
+    - EMAIL_RATE_LIMIT_MAX=${EMAIL_RATE_LIMIT_MAX:-5}
+    - EMAIL_RATE_LIMIT_WINDOW=${EMAIL_RATE_LIMIT_WINDOW:-300}
+    - SENDBLUE_API_KEY=${SENDBLUE_API_KEY}
+    - SENDBLUE_API_SECRET=${SENDBLUE_API_SECRET}
+    - SENDBLUE_FROM_NUMBER=${SENDBLUE_FROM_NUMBER}
+    - SENDBLUE_WEBHOOK_SECRET=${SENDBLUE_WEBHOOK_SECRET}
+    - SENDBLUE_SIGNATURE_VALIDATION=${SENDBLUE_SIGNATURE_VALIDATION:-true}
+    - ALLOWED_IMESSAGE_NUMBERS=${ALLOWED_IMESSAGE_NUMBERS}
+    - SIMBAKIT_URL=${SIMBAKIT_URL:-http://simbakit:8585}
+    - CRON_SECRET=${CRON_SECRET}
+    - CRONICLE_URL=${CRONICLE_URL:-http://cronicle:3012}
+    - CRONICLE_API_KEY=${CRONICLE_API_KEY}
+    - HOMEBOX_URL=${HOMEBOX_URL}
+    - HOMEBOX_TOKEN=${HOMEBOX_TOKEN}
+    - BOOKSTACK_BASE_URL=${BOOKSTACK_BASE_URL}
+    - BOOKSTACK_TOKEN_ID=${BOOKSTACK_TOKEN_ID}
+    - BOOKSTACK_TOKEN_SECRET=${BOOKSTACK_TOKEN_SECRET}
+  depends_on:
+    postgres:
+      condition: service_healthy
+  volumes:
+    - ./obvault:/app/data/obsidian
+    - ./token.json:/app/config/google-token.json:ro
+    - raggr-checkpoints:/app/checkpoints
+  healthcheck:
+    test: ["CMD", "curl", "-f", "http://localhost:8080/api/health"]
+    interval: 5s
+    timeout: 5s
+    retries: 3
+    start_period: 60s
+  restart: unless-stopped
+
 services:
   postgres:
-    image: postgres:16-alpine
+    image: pgvector/pgvector:pg16
     ports:
       - "5432:5432"
     environment:
@@ -11,6 +97,7 @@ services:
       - POSTGRES_DB=${POSTGRES_DB:-raggr}
     volumes:
       - postgres_data:/var/lib/postgresql/data
+      - ./docker/init-pgvector.sql:/docker-entrypoint-initdb.d/init-pgvector.sql
     healthcheck:
       test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-raggr}"]
       interval: 10s
@@ -18,58 +105,34 @@ services:
       retries: 5
     restart: unless-stopped
 
-  raggr:
-    build:
-      context: .
-      dockerfile: Dockerfile
-    image: torrtle/simbarag:latest
+  # Blue-green deployment: exactly one of raggr-blue/raggr-green serves at a
+  # time; Caddy health-checks both ports and routes to the healthy one.
+  # Use scripts/deploy.sh (make redeploy) to swap colors with zero downtime.
+  raggr-blue:
+    <<: *raggr-common
+    profiles: ["blue"]
     ports:
       - "8080:8080"
-    environment:
-      - PAPERLESS_TOKEN=${PAPERLESS_TOKEN}
-      - BASE_URL=${BASE_URL}
-      - OLLAMA_URL=${OLLAMA_URL:-http://localhost:11434}
-      - CHROMADB_PATH=/app/data/chromadb
-      - OPENAI_API_KEY=${OPENAI_API_KEY}
-      - JWT_SECRET_KEY=${JWT_SECRET_KEY}
-      - LLAMA_SERVER_URL=${LLAMA_SERVER_URL}
-      - LLAMA_MODEL_NAME=${LLAMA_MODEL_NAME}
-      - OIDC_ISSUER=${OIDC_ISSUER}
-      - OIDC_CLIENT_ID=${OIDC_CLIENT_ID}
-      - OIDC_CLIENT_SECRET=${OIDC_CLIENT_SECRET}
-      - OIDC_REDIRECT_URI=${OIDC_REDIRECT_URI}
-      - OIDC_USE_DISCOVERY=${OIDC_USE_DISCOVERY:-true}
-      - DATABASE_URL=${DATABASE_URL:-postgres://raggr:changeme@postgres:5432/raggr}
-      - TAVILY_API_KEY=${TAVILIY_API_KEY}
-      - YNAB_ACCESS_TOKEN=${YNAB_ACCESS_TOKEN}
-      - YNAB_BUDGET_ID=${YNAB_BUDGET_ID}
-      - TWILIO_ACCOUNT_SID=${TWILIO_ACCOUNT_SID}
-      - TWILIO_AUTH_TOKEN=${TWILIO_AUTH_TOKEN}
-      - TWILIO_WHATSAPP_NUMBER=${TWILIO_WHATSAPP_NUMBER}
-      - ALLOWED_WHATSAPP_NUMBERS=${ALLOWED_WHATSAPP_NUMBERS}
-      - TWILIO_SIGNATURE_VALIDATION=${TWILIO_SIGNATURE_VALIDATION:-true}
-      - TWILIO_WEBHOOK_URL=${TWILIO_WEBHOOK_URL:-}
-      - OBSIDIAN_AUTH_TOKEN=${OBSIDIAN_AUTH_TOKEN}
-      - OBSIDIAN_VAULT_ID=${OBSIDIAN_VAULT_ID}
-      - OBSIDIAN_E2E_PASSWORD=${OBSIDIAN_E2E_PASSWORD}
-      - OBSIDIAN_DEVICE_NAME=${OBSIDIAN_DEVICE_NAME}
-      - OBSIDIAN_CONTINUOUS_SYNC=${OBSIDIAN_CONTINUOUS_SYNC:-false}
-      - OBSIDIAN_VAULT_PATH=${OBSIDIAN_VAULT_PATH:-/app/data/obsidian}
-      - S3_ENDPOINT_URL=${S3_ENDPOINT_URL}
-      - S3_ACCESS_KEY_ID=${S3_ACCESS_KEY_ID}
-      - S3_SECRET_ACCESS_KEY=${S3_SECRET_ACCESS_KEY}
-      - S3_BUCKET_NAME=${S3_BUCKET_NAME:-asksimba-images}
-      - S3_REGION=${S3_REGION:-garage}
-      - OLLAMA_HOST=${OLLAMA_HOST:-http://localhost:11434}
-      - FERNET_KEY=${FERNET_KEY}
-    depends_on:
-      postgres:
-        condition: service_healthy
-    volumes:
-      - chromadb_data:/app/data/chromadb
-      - ./obvault:/app/data/obsidian
+
+  raggr-green:
+    <<: *raggr-common
+    profiles: ["green"]
+    ports:
+      - "8081:8080"
+
+  simbakit:
+    build:
+      context: ./simbakit
     restart: unless-stopped
+    volumes:
+      - simbakit-data:/app/data
+    environment:
+      - PETKIT_USERNAME=${PETKIT_USERNAME}
+      - PETKIT_PASSWORD=${PETKIT_PASSWORD}
+      - PETKIT_REGION=${PETKIT_REGION:-US}
+      - PETKIT_TIMEZONE=${PETKIT_TIMEZONE:-America/New_York}
 
 volumes:
-  chromadb_data:
   postgres_data:
+  simbakit-data:
+  raggr-checkpoints:

docker/init-pgvector.sql

@@ -0,0 +1 @@
+CREATE EXTENSION IF NOT EXISTS vector;

docs/TASKS.md

@@ -36,11 +36,11 @@
 
 ## Backlog
 
-- [ ] YNAB API client module
-- [ ] YNAB data models (Budget, Transaction, Category, Account)
-- [ ] Database schema for financial data
-- [ ] YNAB sync background job/scheduler
-- [ ] Financial insights LangChain tools
+- [x] YNAB API client module
+- [x] YNAB data models (Budget, Transaction, Category, Account)
+- [x] Database schema for financial data
+- [x] YNAB sync background job/scheduler
+- [x] Financial insights LangChain tools
 - [ ] Admin UI for YNAB configuration
 - [ ] Frontend components for money insights display
 

docs/cowork-ui-plan.md

@@ -0,0 +1,229 @@
+# Cowork UI (phase 2) plan
+
+Status: **proposal, awaiting approval.** Parent doc: [desktop-client.md](desktop-client.md).
+
+Goal: make the agent's work visible and useful. Tool calls appear as a live
+activity timeline. Results that are more than text (budget breakdowns, recipes,
+notes, documents) open in a side panel. Files can be dropped into the
+conversation. This is all built in `raggr-frontend` and the Quart backend, so
+the web app gets it too; the Tauri shell needs only a one-line drag-drop
+setting.
+
+## Where we are
+
+- `stream-query` SSE sends `tool_start {tool}` and `tool_end {tool}` and nothing
+  else: no id, inputs, duration or result. The UI shows a one-line pill whose
+  label comes from a stale `TOOL_MESSAGES` map in `useChat.ts`.
+- Tools return formatted strings. `on_tool_end` saves them as `speaker="tool"`
+  messages, and `GET /conversation/<id>` returns only their first line
+  (`[tool result]`).
+- Only `simba_search` uses `response_format="content_and_artifact"`, and its
+  artifact is a list of LangChain `Document`s that nothing reads.
+- Auth: the backend accepting access tokens is merged (#57). The frontend
+  half (`fix/access-token-auth`) is waiting on a deploy.
+- **#55 (YNAB mirror) is open.** It replaces every YNAB tool (new
+  `blueprints/ynab/tools.py`: `ynab_budget_summary`, `ynab_account_balances`,
+  `ynab_search_transactions`, `ynab_spending_report`, `ynab_category_budget`,
+  `ynab_recent_changes`). ⚠️ Its migration is numbered `16_…`, which clashes
+  with #57's `16_…_add_oidc_states` already on main, so it must be
+  regenerated before #55 merges.
+
+## Contract
+
+Every task codes against this. It lands on main with this doc before any
+worker starts, so all workers share it.
+
+### SSE events (additive; old clients ignore new fields)
+
+```ts
+// tool_start
+{ type: "tool_start", run_id: string, tool: string, label: string,
+  input: Record<string, string | number | boolean> }   // values truncated to 200 chars, `config` dropped
+// tool_end
+{ type: "tool_end", run_id: string, tool: string, label: string,
+  status: "ok" | "error", ms: number,
+  artifact: ArtifactRef | null }
+// unchanged: thinking, thinking_delta, content, response, error, [DONE]
+```
+
+- `label` comes from a server-side registry
+  (`blueprints/conversation/tool_labels.py`): `{tool_name: "Checking budget…"}`,
+  with the fallback `"Using <tool>…"`. MCP tools match by prefix (`homebox_`,
+  `bookstack_`). `TOOL_MESSAGES` in `useChat.ts` is deleted.
+- `status="error"` comes from `on_tool_error`. Most tools catch exceptions and
+  return an error string, so they report `ok`; that's acceptable.
+- Parallel tool calls are paired by `run_id`.
+
+### Artifacts
+
+A tool opts in by returning `(text, artifact)` with
+`@tool(response_format="content_and_artifact")`. The LLM sees only `text`. The
+artifact is a plain JSON-serialisable dict:
+
+```ts
+type ToolArtifact = {            // what a tool returns
+  kind: ArtifactKind;
+  title: string;                 // "October spending by category"
+  data: object;                  // per-kind shape below; ≤ 256 KB serialised or it is dropped
+  source_ref?: { system: "mealie" | "obsidian" | "paperless" | "ynab" | "web";
+                 id?: string; path?: string; url?: string };
+};
+type ArtifactRef = { id: string; kind: ArtifactKind; title: string };   // in tool_end + conversation payload
+type Artifact = ArtifactRef & { data: object; source_ref: object | null; tool: string;
+                                conversation_id: string; message_id: string | null; created_at: string };
+```
+
+V1 kinds and their `data` shapes:
+
+| kind | produced by | data |
+|---|---|---|
+| `mealie.recipe` | `mealie_get_recipe` | `{slug, name, description, servings, prep_time, cook_time, total_time, ingredients: string[], instructions: {title?, text}[], tags: string[], image_url?}` |
+| `mealie.meal_plan` | `mealie_meal_plans`, `mealie_todays_meals` | `{start_date, end_date, days: {date, meals: {entry_type, name, recipe_slug?, note?}[]}[]}` |
+| `mealie.shopping_lists` | `mealie_shopping_lists` | `{lists: {name, items: {name, quantity, checked}[]}[]}` |
+| `obsidian.note` | `obsidian_read_note`, `journal_get_today` | `{path, title, markdown (≤ 50k chars), tags: string[], frontmatter: object}` |
+| `search.documents` | `simba_search`, `obsidian_search_notes` | `{query, source, results: {title, snippet (≤ 400), filename?, path?, document_type?, date?}[]}` |
+| `ynab.summary` | `ynab_budget_summary` | `{month, ready_to_assign, income, assigned, spent, age_of_money?, net_worth, overspent: {name, available}[]}` |
+| `ynab.transactions` | `ynab_search_transactions` | `{start_date, end_date, count, total, transactions: {date, payee, category, account, memo?, amount}[]}` (≤ 500 rows) |
+| `ynab.spending_report` | `ynab_spending_report` | `{start_date, end_date, group_by, rows: {key, amount, count?}[], total}` |
+| `ynab.category_budget` | `ynab_category_budget` | `{month, groups: {name, categories: {name, assigned, activity, available, goal_target?}[]}[]}` |
+
+YNAB kinds are built against #55's tools, so they wait for #55.
+`source_ref.url` is filled where the backend knows it (Mealie base URL plus the
+recipe path). Obsidian gets `obsidian://open?vault=<OBSIDIAN_VAULT_NAME>&file=<path>`
+only if that env var is set; it's added to `.env`, `.env.example` and
+`docker-compose.yml`.
+
+### Storage and API
+
+- New Tortoise model `Artifact` (`blueprints/artifacts/models.py`, table
+  `artifacts`): `id UUID, user FK, conversation FK (cascade), message FK →
+  conversation_messages (nullable, set null), tool, kind, title, data JSON,
+  source_ref JSON null, version int default 1, created_at, updated_at`.
+  Migration generated with `make migrate-new` / aerich, adds a table only.
+- Created in `stream_query`'s `on_tool_end` when `output.artifact` is a dict
+  with a `kind`, right after the tool message is saved and linked to it.
+  Non-web channels (iMessage, WhatsApp, `/query`) don't create artifacts.
+- `GET /api/artifacts?conversation_id=…` returns `ArtifactRef[]` plus
+  `{tool, message_id, created_at}`, without `data`.
+  `GET /api/artifacts/<id>` returns the full `Artifact`. Both require an access
+  token and are scoped to the owner (404 otherwise).
+- `GET /api/conversation/<id>`: tool messages gain
+  `tool: string, label: string, artifact: ArtifactRef | null`. `text` keeps
+  the header line, for older clients.
+- Write-back (`PATCH`) is **out of scope** for phase 2.
+
+### Uploads
+
+- `POST /api/conversation/upload` (multipart `file`, `conversation_id`):
+  - images go through the existing `process_image` and return
+    `{kind: "image", image_key}`
+  - `application/pdf`, `text/plain`, `text/markdown`, `text/csv` (by MIME type
+    or extension) are stored at `conversations/<id>/files/<uuid>.<ext>` and
+    return `{kind: "file", file_key, name, chars}`. PDF text is extracted with
+    PyMuPDF (`fitz`, already a dependency).
+  - max 10 MB; anything else gets a 415
+  - `upload-image` stays as is
+- `stream-query` accepts an optional `file_key`. The extracted text (capped at
+  12k chars, with a `[truncated]` marker) is appended to the user turn as
+  `<attached file "name">…</attached>`. The saved user message gets
+  `📎 name` appended. Saved user messages get no new column.
+
+## Tasks
+
+Each task has its own branch off main (after the contract lands), its own herdr
+worktree and pane, and its own Claude session started from a brief.
+
+| # | Branch / pane | Scope | Owns (files) | Depends on |
+|---|---|---|---|---|
+| **A** | `feat/cowork-stream` | SSE v2 events + label registry; `Artifact` model, migration, API, creation in `on_tool_end`; conversation payload fields | `blueprints/conversation/__init__.py`, new `tool_labels.py`, new `blueprints/artifacts/`, `config/db.py`, `app.py` (register), a migration | contract on main. **Migration last, after rebasing** (see sequencing) |
+| **B** | `feat/cowork-tool-artifacts` | `content_and_artifact` for the Mealie, Obsidian and search tools; then a second commit for the YNAB tools once #55 merges | `blueprints/conversation/agents.py`, `blueprints/ynab/tools.py` (2nd commit), tests | contract; #55 for the YNAB part |
+| **C** | `feat/cowork-timeline` | Activity timeline replaces `ToolBubble`: grouped "Simba worked · N steps · 4.2 s" block per turn, rows with icon, label, input summary, spinner/✓/✗, duration and an "Open" chip that calls an `onOpenArtifact(ref)` prop; restored from conversation payload on reload | `useChat.ts`, new `ActivityTimeline.tsx`, `ToolBubble.tsx` (delete), `conversationService.ts` types, `ChatScreen.tsx` (message list only) | frontend auth PR merged |
+| **D** | `feat/cowork-artifact-panel` | Right-side artifact panel: tabs for opened artifacts, `artifactService.ts`, a renderer per kind (CSS bars, no chart library), "Open in Mealie/Obsidian", a sheet below `lg`; auto-opens the newest artifact of a turn when the window is ≥ 1280 px wide, otherwise just the chip | new `components/artifacts/*`, `api/artifactService.ts`, `ChatScreen.tsx` (layout + wiring `onOpenArtifact`) | C merged first (wires its prop) |
+| **E** | `feat/cowork-file-drop` | Upload endpoint + `file_key` in `stream-query`; drop overlay over the whole window, attachment chip in `MessageInput`; Tauri `disable_drag_drop_handler()` so HTML5 drops reach the webview | `blueprints/conversation/__init__.py` (new route + small `stream_query` hunk), new `utils/file_extract.py`, `MessageInput.tsx`, `ChatScreen.tsx` (overlay), `useChat.ts` (pending file), `desktop/src-tauri/src/lib.rs` | rebase after A and C (shared files) |
+
+### Parallelism and sequencing
+
+```
+now ──► contract PR (this doc) merged
+        frontend-auth PR merged   (after your deploy)
+            │
+            ├── A  feat/cowork-stream ─────────────┐ (merges 1st)
+            ├── B  feat/cowork-tool-artifacts ─────┤ (Mealie/Obsidian/search: merges anytime; YNAB commit after #55)
+            ├── C  feat/cowork-timeline ───────────┤ (merges after A)
+            ├── D  feat/cowork-artifact-panel ─────┤ (merges after C)
+            └── E  feat/cowork-file-drop ──────────┘ (merges last)
+```
+
+- **All five start in parallel.** A and B are pure backend. C and D build
+  against a mock `/api` server that speaks the contract, so they don't wait for
+  A.
+- **Migration order.** #55's migration needs regenerating (it clashes with
+  #57). A's migration must be generated *after* whatever lands before it. A
+  writes the model and code first, then rebases onto the latest main and runs
+  `make migrate-new` as its final step. If #55 merges while A is in review, A
+  rebases and regenerates.
+- **Shared-file conflicts** (`ChatScreen.tsx`, `useChat.ts`,
+  `conversation/__init__.py`) are resolved by the merge order A → C → D → E. Each
+  later branch rebases onto main before its review.
+- B's Mealie/Obsidian/search commit is safe to merge before A: without A,
+  artifacts ride along in `ToolMessage.artifact` and are ignored.
+
+### Verification per task
+
+- **Backend (A, B, E):** unit tests in `tests/unit/`, run with
+  `TAVILY_API_KEY=dummy .venv/bin/pytest tests/ -q` (create the venv with
+  `uv sync --all-extras`).
+  - A: event shaping becomes pure functions (`tool_start_payload(event)`,
+    `tool_end_payload(event, started_at, artifact_ref)`), which are tested,
+    along with the 256 KB cap and owner scoping.
+  - B: each converted tool, with its service mocked, returns `(str, dict)`
+    matching the kind's shape.
+  - E: extraction and the 415 case.
+- **Migrations:** a throwaway Postgres container + aerich, the same approach
+  the auth fix used.
+- **Frontend (C, D, E):** `yarn build`, plus the mock-server + Playwright recipe
+  (Node `http` mock serving `dist/` and SSE fixtures, Playwright on installed
+  Chrome, `addInitScript` to seed tokens). Screenshots are checked by eye.
+  Fixtures live in `raggr-frontend/test-fixtures/cowork/*.json`, and D owns one
+  per kind. Don't commit the Playwright devDep or a rewritten
+  `package-lock.json`.
+
+## Process
+
+1. Approve this plan. I commit it on `plan/cowork-ui`, open the PR and merge it
+   so the contract is on main.
+2. Wait for the frontend-auth PR to merge after your deploy. A and B can start
+   right away; C, D and E start once it's in, so they use the new fetch helper.
+3. For each task: `herdr worktree create … --base origin/main`, a
+   `.claude-brief.md` with that task's slice of this doc, and
+   `herdr agent start cowork-<x> … -- claude "Read .claude-brief.md…"`.
+   Workers commit locally and never push.
+4. When a worker goes idle with its task done, I review:
+   - **pass 1:** I read the diff against the contract, run the tests and
+     build, and send numbered findings to the worker.
+   - **pass 2:** same again after its fixes.
+   - Then I push the branch and open the PR (`tea pr create`).
+   - I don't merge; you merge, or tell me to.
+5. Before each review, the branch rebases on main per the merge order.
+
+## Decisions I made (say if you disagree)
+
+- **No write-back in phase 2.** Editing a recipe or note in the panel and
+  saving it to Mealie/Obsidian is phase 2.5.
+- **No chart library.** CSS bars and tables are enough for budgets. Revisit if
+  trends need real line charts.
+- **The panel auto-opens on wide windows**, otherwise shows a chip.
+- **One attached file per message** (like images today). Dropped PDFs aren't
+  filed into Paperless yet.
+- **Out of scope for now:** the bridge, notifications, the Keychain, and
+  detached runs. They're phases 3–4 in the parent doc.
+
+## Open questions
+
+1. Is **#55** close to merging? It decides when the YNAB artifacts happen, and
+   its migration needs regenerating against main either way.
+2. What's the **Obsidian vault name** (for `obsidian://` links), or is the
+   link not worth having?
+3. What's the **Mealie recipe URL** format on your instance
+   (`/g/home/r/<slug>` or `/recipe/<slug>`)? Worker B can check against the
+   API otherwise.

docs/deployment.md

@@ -96,20 +96,88 @@ The dev environment:
 - Rebuilds frontend on changes
 - Auto-applies migrations on startup
 
-### Production
+### Production (zero-downtime blue-green)
+
+The app runs as one of two identical compose services: `raggr-blue`
+(host port 8080) or `raggr-green` (host port 8081), gated behind compose
+profiles so only one color runs at a time. Caddy health-checks both ports and
+routes traffic to whichever is healthy.
 
 ```bash
-# Build and deploy
-docker compose build raggr
-docker compose up -d
+# Pull latest and swap colors with zero downtime
+make redeploy
 
-# View logs
-docker compose logs -f raggr
+# Or run the swap directly
+./scripts/deploy.sh
 
-# Verify migrations applied
-docker compose exec raggr aerich history
+# View logs / exec into the active color (Makefile resolves the color)
+make logs
+make migrate-history
 ```
 
+`scripts/deploy.sh` does the following:
+
+1. Detects the running color via `docker compose ps`.
+2. Builds the inactive color.
+3. Starts it with `docker compose up -d --wait`, which blocks until the
+   container healthcheck (`GET /api/health`) passes.
+4. If the new color never becomes healthy, it is stopped and the old color
+   keeps serving (the script exits non-zero).
+5. Otherwise the old color is stopped with a 30s grace period so in-flight
+   SSE streams can finish, then removed.
+
+To target a color manually, enable its profile:
+
+```bash
+docker compose --profile blue up -d raggr-blue
+docker compose --profile blue --profile green ps
+```
+
+#### Caddy configuration
+
+Caddy needs both upstreams with active health checks:
+
+```caddyfile
+ask.torrtle.co {
+  reverse_proxy host.docker.internal:8080 host.docker.internal:8081 {
+    lb_policy first          # prefer blue when both are healthy
+    lb_try_duration 5s       # retry on the other upstream during the swap
+    lb_try_interval 250ms
+    health_uri /api/health
+    health_interval 2s
+    health_timeout 2s
+    fail_duration 10s
+  }
+}
+```
+
+#### One-time cutover from the old `raggr` service
+
+The first deploy after this change lands needs manual steps, because the old
+`raggr` container still holds port 8080 and the deploy script doesn't know
+about it:
+
+```bash
+# 1. Update the Caddy config to the two-upstream block below and reload Caddy
+# 2. On the server:
+git pull
+docker compose --profile green up -d --build --wait raggr-green   # port 8081, no conflict
+docker stop -t 30 $(docker ps -q --filter name=raggr-1)           # old raggr container
+docker rm $(docker ps -aq --filter name=raggr-1)
+# From here on, `make redeploy` handles swaps (green is now the active color)
+```
+
+#### Blue-green caveats
+
+- **Migrations must be backward-compatible.** The new color runs
+  `aerich upgrade` on startup while the old color is still serving the
+  previous code. Additive changes (new tables/columns) are safe; destructive
+  changes (drop/rename a column the old code reads) need a two-step deploy:
+  ship code that stops using the column first, then drop it in a later deploy.
+- **Obsidian sync overlap.** During the ~30s swap window both containers run
+  pull-only `ob sync` against the shared `./obvault` mount. Both are
+  read-only pulls, so this is low risk, but avoid deploying mid-reindex.
+
 ### Fresh Deploy (New Database)
 
 On first deploy with an empty database, `startup-dev.sh` runs `aerich init-db` instead of `aerich upgrade`. This creates all tables from the current models.

docs/desktop-client.md

@@ -0,0 +1,351 @@
+# Desktop Client (exploration)
+
+Status: **proposal**, no app code yet. Branch `explore/desktop-client`.
+
+Goal: a persistent, native-feeling macOS app where Simba works *alongside* the
+user rather than a chat box in a browser tab. "Cowork-like" means:
+
+- visible tool activity and progress while the agent works
+- side panels for artifacts: budget reports, recipes, notes, documents
+- drag files into the agent
+- desktop notifications (scheduled messages, cron jobs, finished runs)
+- a menu-bar icon and a global hotkey to summon the window
+
+## Decisions (2026-10-12)
+
+| Question | Decision | Consequence |
+|---|---|---|
+| Reachable off-LAN? | Yes, publicly via Caddy | Loading the remote origin works anywhere; `offline.html` only covers "no network / server down" |
+| Who uses it? | Just the admin (Ryan) | Every desktop-only endpoint is `@admin_required`; no multi-user notification fan-out, no distribution story |
+| Act on the Mac (local tools)? | **Yes** | Adds a *local tool bridge* (below). Tauri is still the pick: the bridge lives in the Rust core and can spawn local MCP servers as child processes |
+| Artifact storage | Own `artifacts` table | Artifacts can be listed, reopened, edited and written back |
+| Stop sending the refresh token on every request? | Yes, for web too | Becomes phase 0 (see "Auth fix") |
+| Apple Developer account? | No; a local dev build is fine | No notarization or updater. `make desktop` builds an ad-hoc-signed `.app` locally |
+
+## What exists today
+
+| Area | Current state | Desktop implication |
+|---|---|---|
+| Frontend | React 19 + Rsbuild + Tailwind, `BrowserRouter`, all API calls use relative `/api/...` | Reusable as-is if the shell loads it from the server origin; a bundled copy needs an API base URL and CORS |
+| PWA | `manifest.json` + `sw.js` (static cache, network-only `/api`) | "Install app" already works in Chrome / Safari "Add to Dock" |
+| Streaming | `POST /api/conversation/stream-query` → SSE over `fetch` with events `thinking`, `thinking_delta`, `tool_start {tool}`, `tool_end {tool}`, `content`, `response`, `error` | Too thin for Cowork: tool events have no run id, no args, no output, no structured payload |
+| Run lifecycle | The agent runs *inside* the HTTP response generator. A client disconnect cancels it (`CancelledError`, partial answer persisted) | You can't close the window and let Simba keep working |
+| Tool output | Tools return strings; output is persisted as `speaker="tool"` text (capped at 4000 chars) and the UI only shows the first line. `simba_search` already uses `response_format="content_and_artifact"` | Natural hook for structured artifacts |
+| Tool labels | `TOOL_MESSAGES` map in `useChat.ts` is hand-maintained and stale (no Mealie, SimbaKit, Homebox, BookStack, Beli…) | Labels should come from the server |
+| Uploads | `POST /api/conversation/upload-image`: images only, 10 MB, stored in S3, attached as an image block | Need generic file upload (PDF, text, markdown, CSV) |
+| Auth | Backend is the confidential OIDC client. `/oidc/login` returns an Authelia URL; Authelia redirects to `OIDC_REDIRECT_URI` (the web root); the SPA posts `code`+`state` to `/oidc/callback` and stores JWTs in `localStorage` | In-webview login works unchanged if the shell loads the real origin. A system-browser login needs a handoff (see below) |
+| Auth quirks | `_oidc_sessions` is an in-process dict (a login that spans a blue/green flip fails with "Invalid or expired state"); `redirect_after_login` is stored but never used; every API call sends the **30-day refresh token** as the bearer (`@jwt_refresh_token_required` everywhere) | Desktop must keep that token in the Keychain, not plain storage |
+| Notifications | Scheduled messages and cron jobs deliver to iMessage / email only (admin-only APIs) | No in-app notification channel exists |
+| CORS | None configured | Only matters for a bundled frontend |
+
+## Shell options
+
+### A. PWA ("Install app" / "Add to Dock")
+
+- **Reuse:** 100%. Already shipped.
+- **Size:** 0.
+- **macOS integration:** own window and Dock icon; Web Push and the Badging API
+  work for installed PWAs. **No** menu-bar icon, **no** global hotkey, no
+  quick-ask panel, no Keychain, file access only through the picker/drop.
+- **OIDC:** unchanged.
+- **Verdict:** a free baseline and the fallback. It can't deliver the
+  menu-bar or hotkey parts, which are most of what makes it feel like a
+  desktop app.
+
+### B. Tauri v2 (recommended)
+
+- **Reuse:** high. Either load the deployed frontend from the server origin
+  (no fork), or bundle `raggr-frontend/dist` (needs an API base URL plus CORS).
+- **Size:** ~5–15 MB `.app`, low idle memory (system WKWebView). Rust and
+  cargo are already installed on this machine.
+- **macOS integration:** first-party plugins for tray/menu-bar (core
+  `TrayIcon`), `global-shortcut`, `notification`, `deep-link`,
+  `single-instance`, `window-state`, `autostart`, `updater`, `positioner`
+  (anchor the quick-ask panel under the tray icon), keychain storage, and
+  window file drag-drop events with real paths. `ActivationPolicy::Accessory`
+  gives a menu-bar-only mode.
+- **Costs:** Safari/WebKit engine (the PWA already targets Safari, so low
+  risk). Service workers don't run in WKWebView here (the `sw.js` register
+  call already fails soft). Native code is Rust, but the native layer stays
+  small: tray, hotkey, notifications, keychain, deep link.
+- **Security:** remote content can reach Tauri IPC only through an explicit
+  `remote.urls` capability. Grant the remote origin only notification and
+  window commands; register shortcut and tray from Rust, not JS.
+
+### C. Electron
+
+- **Reuse:** same as Tauri.
+- **Size:** ~100 MB+ download, ~200 MB+ on disk, 150–300 MB RAM idle.
+- **macOS integration:** everything Tauri has, more mature (`menubar`
+  package, `globalShortcut`, `Notification`, `safeStorage`), plus Node in the
+  main process. That would matter if the client ran local tools or MCP
+  servers on the user's machine (see open questions).
+- **Verdict:** the better choice only if we want heavy client-side tool
+  execution in JS/Node. For a thin client to a self-hosted agent, the size
+  and memory cost buys nothing. Local tools are wanted, but the bridge design
+  below runs local MCP servers as child processes (Node is already installed),
+  so Electron's in-process Node isn't needed.
+
+### Decision matrix
+
+| | PWA | Tauri v2 | Electron |
+|---|---|---|---|
+| Reuse raggr-frontend | ✅ as-is | ✅ remote or bundled | ✅ remote or bundled |
+| Bundle / RAM | none | ~10 MB / low | ~100 MB+ / high |
+| Menu bar + quick-ask | ❌ | ✅ | ✅ |
+| Global hotkey | ❌ | ✅ | ✅ |
+| Notifications | Web Push (VAPID) | ✅ native | ✅ native |
+| File drag-drop w/ paths | browser `File` only | ✅ | ✅ |
+| Secure token storage | ❌ localStorage | ✅ Keychain | ✅ safeStorage |
+| Auto-update | free (server) | `updater` plugin, or free with a remote UI | `electron-updater` |
+| Local tool execution | ❌ | Rust | Node (easiest) |
+
+## Recommended architecture
+
+**A Tauri v2 shell that loads the deployed SimbaRAG origin, plus a tiny bundled
+"offline/connect" page. Cowork features are built in `raggr-frontend` behind
+feature detection, so the web app gets them too.**
+
+```
+┌──────────────────────── Simba.app (Tauri v2) ─────────────────────────┐
+│ Rust core (small)                                                      │
+│  • tray icon + menu (Ask…, New chat, recent convos, Quit)              │
+│  • global shortcut ⌥Space → show/hide main window                      │
+│  • notifications (plugin-notification)                                 │
+│  • keychain token store, deep-link `simba://`, single-instance         │
+│  • window-state, autostart                                             │
+│                                                                        │
+│  Main window  ──loads──▶  https://<simba-host>/        (full UI)       │
+│  Fallback     ──bundled─▶ offline.html (server unreachable / retry)    │
+└───────────────────────────────┬────────────────────────────────────────┘
+                                │ HTTPS: REST + SSE (same origin, no CORS)
+┌───────────────────────────────▼────────────────────────────────────────┐
+│ Caddy → raggr-blue / raggr-green (Quart)                               │
+│  /api/conversation/*  (+ structured tool/artifact events)              │
+│  /api/runs/*          (detached agent runs, resumable SSE)  [phase 3]  │
+│  /api/files           (generic upload)                                 │
+│  /api/notifications/stream (per-user SSE feed)                         │
+└────────────────────────────────────────────────────────────────────────┘
+```
+
+Why load the remote origin rather than bundle:
+
+- **One codebase, one deploy.** `make redeploy` updates web, PWA and desktop
+  together. No version skew between the desktop UI and the SSE protocol, and
+  no desktop release for UI changes.
+- **No CORS, no API-base refactor, and the current OIDC flow works unchanged**
+  inside the webview (redirect back to the web root on the same origin).
+- The agent needs the server anyway, so offline-first buys little. The bundled
+  `offline.html` covers "server down / not on VPN".
+
+The frontend detects the shell with `window.__TAURI_INTERNALS__` (or a
+`?shell=desktop` query param) and turns on the native bits: notifications
+and drag-drop paths. Everything else renders
+the same in a browser.
+
+### Cowork UI (in raggr-frontend, shared by web and desktop)
+
+- **Three panes:** conversations | chat | **artifact panel** (collapsible, a
+  tab per artifact). On mobile/web the artifact panel becomes a sheet.
+- **Activity timeline** in place of single-line `ToolBubble` pills: one row per
+  tool call with a server-provided label, args summary, a spinner, duration,
+  and an expandable result. Clicking a row with an artifact opens it in the
+  panel.
+- **Artifact renderers:** `budget` (YNAB summary/category table + chart),
+  `transactions` (table), `recipe` (Mealie: ingredients/steps, "add to meal
+  plan"), `note` (Obsidian markdown, "open in Obsidian" via
+  `obsidian://` deep link), `document` (Paperless hit: title, snippet, link to
+  Paperless), `photo` (Immich), `device` (SimbaKit status/weight chart).
+- **Drop zone** over the whole window: images go to the existing vision path;
+  PDFs and text go to the new upload endpoint (below).
+
+### Local tool bridge (Simba acts on the Mac)
+
+The backend can't reach the Mac (it's behind NAT), so the desktop app dials
+out and the backend calls tools back over that connection.
+
+```
+Mac                                              Server
+┌─ Simba.app Rust core ────────────┐   wss    ┌─ Quart ────────────────────────┐
+│ bridge client ───────────────────┼─────────▶│ /api/desktop/bridge (websocket)│
+│   │ JSON-RPC (MCP messages)      │          │   │                            │
+│   ▼                              │          │   ▼                            │
+│ local MCP servers (child procs)  │          │ MCP ClientSession over the ws  │
+│  • filesystem (scoped folders)   │          │  → langchain-mcp-adapters tools│
+│  • later: screenshot, clipboard, │          │  → mcp_tools.select_tools(     │
+│    open app/URL, Shortcuts       │          │      prefix="mac", admin-only) │
+│ confirm dialog for write tools   │          │  → injected per run only while │
+└──────────────────────────────────┘          │    the bridge is connected     │
+                                              └────────────────────────────────┘
+```
+
+- **The protocol is MCP**, so the backend reuses the existing pattern in
+  `utils/mcp_tools.py` (allowlist, `prefix_` rename, admin re-check). Only the
+  transport is new: an MCP `ClientSession` over the websocket's read/write
+  streams instead of stdio.
+- **The bridge runs in Rust, not in the webview.** The webview loads remote
+  content, so giving page JS file access would turn any XSS into local file
+  access. The Rust core owns the socket, the child processes, and the
+  allowlist of exposed folders (picked in a native settings window).
+- **Writes need consent:** tools tagged as writes (save file, move, run a
+  Shortcut) show a native confirm dialog before running. Reads inside the
+  scoped folders are allowed without asking.
+- **Availability:** the agent is compiled once at startup, so `mac_*` tools are
+  added per run, e.g. via `get_agent_for(user)` returning a variant with
+  bridge tools when a bridge session is connected. If the bridge drops
+  mid-call, the tool returns "Mac is offline" rather than hanging.
+- **Auth:** the websocket authenticates with the same JWT, so this depends on
+  the auth fix landing first. A blue/green flip drops the socket and the app
+  reconnects to the new color.
+- **Open spike question:** do the `mcp` Python SDK and `langchain-mcp-adapters`
+  accept a custom transport cleanly? Fallback: a small hand-rolled JSON-RPC
+  tool-call protocol with tools defined server-side.
+
+## Auth fix (web + desktop)
+
+Today the frontend sends the **refresh** token as the bearer on every call,
+and 20 routes use `@jwt_refresh_token_required` (conversation ×9, beli ×6,
+users ×2 incl. `/refresh`, rag ×1, app ×1, plus `admin_required` in
+`blueprints/users/decorators.py`).
+
+Change:
+
+1. Backend: every route except `/api/user/refresh` uses `@jwt_required`
+   (access token, 1h). The same goes for the inner decorator of
+   `admin_required`.
+2. Frontend: collapse `fetchWithRefreshToken` and `fetchWithAuth` into one
+   function that sends the access token and, on 401, refreshes once and
+   retries. `validateToken` keeps using the refresh token.
+3. Desktop: the refresh token lives in the Keychain. The webview keeps only
+   the access token (memory or `localStorage`).
+
+This is blue/green-safe in both directions. An *old* frontend talking to the
+new backend sends the refresh token, gets a 401, calls `/refresh`, and retries
+with an access token, so it works. A *new* frontend talking to the old backend
+sends an access token where a refresh token is required, gets a 401, and the
+retry with a fresh access token also fails. That window lasts only as long as
+the deploy flip. To avoid it, deploy the backend change first: for one release,
+accept either token type on the protected routes (a small custom decorator),
+then flip the frontend.
+
+SSE streams are authenticated once at request start, so a stream running past
+the 1h access-token expiry is fine.
+
+Also in scope: move `_oidc_sessions` into Postgres (or signed, stateless
+`state`) so a login spanning a deploy doesn't fail, and either honour or
+delete the unused `redirect_after_login`.
+
+## Backend changes
+
+Ordered by how much the client depends on them. All are additive, so
+blue/green stays safe: the old frontend ignores the new fields.
+
+1. **Richer SSE events** (`blueprints/conversation/__init__.py`):
+   - `tool_start {run_id, tool, label, input}`: `input` comes from
+     `event["data"]["input"]`, trimmed/redacted; `label` comes from a
+     server-side map that replaces `TOOL_MESSAGES`.
+   - `tool_end {run_id, tool, ms, summary, artifact?}`: `run_id` lets parallel
+     tool calls pair up correctly.
+   - optional `event: id` lines so a client can resume (needed for phase 3).
+2. **Structured artifacts.** Move high-value tools to
+   `response_format="content_and_artifact"` (as `simba_search` already does): the
+   LLM still sees compact text, and the UI gets
+   `{kind, title, data}`. Persist them in an **`artifacts` table**:
+   `id, user_id, conversation_id, message_id (nullable FK to the tool row),
+   kind, title, data JSON, source_ref (e.g. Mealie slug, Obsidian path,
+   Paperless id), version, created_at, updated_at`. Generate the migration with
+   `make migrate-new` (never hand-written); a new table is backward-compatible.
+   Endpoints: `GET /api/artifacts?conversation_id=` and
+   `GET/PATCH /api/artifacts/<id>`. `PATCH` writes back to the source
+   integration where one exists (edit a recipe → Mealie, edit a note →
+   Obsidian) and bumps `version`. `GET /api/conversation/<id>` includes artifact
+   ids on tool messages.
+3. **Generic file upload** `POST /api/conversation/upload` (supersedes
+   `upload-image`, which stays for compatibility): accept images, PDF, md/txt,
+   CSV. Store in S3 under `conversations/<id>/`, extract text (reuse
+   `utils/cleaner.py` for PDFs), and attach it as a document block capped to the
+   context budget (32k slots). Possible extra: a "file it in Paperless" action
+   that pushes the PDF into Paperless so it gets indexed. Revisit
+   `MAX_CONTENT_LENGTH` (10 MB).
+4. **Notifications feed.** A `notifications` table (user, kind, title, body,
+   link, created_at, read_at) written by the scheduler (`process_due_messages`),
+   cron runs, and completed detached runs. Add
+   `GET /api/notifications/stream` (per-user SSE with `Last-Event-ID` replay
+   from the table, so a blue/green flip only causes a reconnect) and
+   `POST /api/notifications/<id>/read`. Also consider a `desktop` value on
+   `MessageChannel` so a scheduled message can target the app instead of
+   iMessage.
+5. **Detached agent runs** (phase 3): `POST /api/runs` starts the agent in a
+   background task and returns `run_id`; `GET /api/runs/<id>/events` streams
+   with replay. This decouples work from the window. Constraint: an in-process
+   run dies on a blue/green stop. Either persist events (Postgres) and mark
+   runs `interrupted` on startup, or have `deploy.sh` drain active runs before
+   stopping the old color.
+6. **Native auth handoff** (phase 3, optional): sign in through the system
+   browser (password manager, passkeys, existing Authelia session) without
+   changing Authelia config:
+   1. The app generates a PKCE verifier and opens
+      `https://<simba-host>/api/user/oidc/login?client=desktop&challenge=…` in
+      the default browser.
+   2. The normal web OIDC round-trip runs against the existing redirect URI.
+   3. The backend sees `client=desktop` on the stored session and, instead of
+      returning JWTs to the page, issues a one-time 60-second handoff code and
+      redirects to `simba://auth?code=…`.
+   4. The app exchanges `code + verifier` at `POST /api/user/desktop/token` for
+      JWTs and stores them in the Keychain.
+
+   This also requires moving `_oidc_sessions` into Postgres or signed state so
+   it survives blue/green. The alternative, registering a loopback or
+   custom-scheme redirect URI in Authelia, depends on Authelia's redirect
+   matching rules (exact match, ports?). That needs checking, and the client
+   secret would have to stay on the server anyway.
+7. **Local tool bridge:** `/api/desktop/bridge` websocket, an MCP-over-websocket
+   client, and per-run injection of `mac_*` tools (see above). Admin-only.
+8. **CORS:** only needed if we ever bundle the frontend (`quart-cors`
+   allowing `tauri://localhost` / `http://tauri.localhost`). Not needed
+   with the recommendation.
+
+## Phased plan
+
+| Phase | Scope | Backend | Exit criteria |
+|---|---|---|---|
+| **0a. Auth fix** (own PR) | access token on every call, single fetch helper, OIDC state in Postgres | auth fix (+ migration if state goes in a table) | Web works through a blue/green flip; the refresh token is only ever sent to `/refresh` |
+| **0b. Spike** (½ day) | `desktop/` Tauri v2 app: one window loading `<simba-host>`, tray icon with Show/Quit, ⌥Space toggles the window, `offline.html` fallback | none | Log in through Authelia inside the webview, stream an answer, survive a `make redeploy` |
+| **1. Native shell** | notifications, window-state, autostart, refresh token in the Keychain (no quick-ask window: dropped 2026-10-12) | none | A scheduled-message notification arrives; the login survives an app restart |
+| **2. Cowork UI** ([plan](cowork-ui-plan.md)) | activity timeline, artifact panel + renderers (budget, recipe, note, document first), whole-window drop zone | items 1–3 (`artifacts` table) | Ask "how's the grocery budget" → YNAB artifact opens in the side panel; drop a PDF → summarised |
+| **3. Local tools** | Rust bridge client, filesystem MCP scoped to chosen folders, write-confirm dialog, folder picker | item 7 | "Summarise the PDFs in ~/Downloads/taxes" works; a write prompts first; quitting the app removes the tools |
+| **4. Background agent** | detached runs, notifications feed, desktop channel for scheduled messages, system-browser auth handoff | items 4–6 | Close the window mid-run → notification when done → reopen shows the full timeline |
+
+**0b status:** scaffolded in `desktop/`. It has a bundled connect page that
+probes `/api/health` and hands off to `$SIMBA_URL`, a menu-bar icon
+(Show / New Chat / Reconnect / Quit), ⌥Space to toggle, close-to-hide,
+single-instance, and Dock-click reopen. The remote origin gets no IPC.
+`desktop/src-tauri/rust-toolchain.toml` pins Rust 1.90, the minimum
+Tauri 2.12 accepts, so the global toolchain is untouched. Run it with
+`make desktop-dev SIMBA_URL=…` or `make desktop`.
+Verified 2026-10-12: Authelia login inside the webview works, and the
+conversation list loads.
+
+Phases 1–3 are independent once 0a/0b land. Phase 2 also improves the web
+UI. There's no distribution phase: `make desktop` runs `tauri build` and
+copies the ad-hoc-signed `.app` to `/Applications`. A locally built app isn't
+quarantined, so Gatekeeper won't complain. Because the UI loads from the
+server, rebuilds are only needed when the Rust shell changes.
+
+## Open questions
+
+1. **Keychain and ad-hoc signing:** the ad-hoc signature changes on every
+   rebuild, so macOS may ask again for Keychain access after each
+   `make desktop`. Acceptable, or use a self-signed local code-signing
+   certificate to keep the identity stable?
+2. **Local tool scope for v1:** filesystem (read + confirmed writes) only, or
+   also screenshot, clipboard, "open URL/app", and running Shortcuts?
+3. **MCP over websocket:** does `langchain-mcp-adapters` take a custom session
+   or transport cleanly? Settle this in a short spike before phase 3;
+   otherwise fall back to a hand-rolled tool-call protocol.
+4. **Engine risk:** does anything in the UI rely on Chromium-only behaviour?
+   The spike should check markdown rendering, streaming `fetch`, and the
+   image picker in WKWebView.
+5. **Artifact write-back conflicts:** if a recipe or note changed in
+   Mealie/Obsidian after the artifact was captured, should we refuse, show a
+   diff, or let the last write win?

llm.py

@@ -1,6 +1,7 @@
 import os
 import logging
 
+import httpx
 from openai import OpenAI
 from dotenv import load_dotenv
 
@@ -13,7 +14,15 @@ class LLMClient:
     def __init__(self):
         llama_url = os.getenv("LLAMA_SERVER_URL")
         if llama_url:
-            self.client = OpenAI(base_url=llama_url, api_key="not-needed")
+            # Tight read timeout so a wedged llama-server fails fast instead
+            # of hanging for the OpenAI client's 600s default.
+            read_timeout = float(os.getenv("LLAMA_TIMEOUT_SECONDS", "120"))
+            self.client = OpenAI(
+                base_url=llama_url,
+                api_key="not-needed",
+                timeout=httpx.Timeout(read_timeout, connect=10.0),
+                max_retries=1,
+            )
             self.model = os.getenv("LLAMA_MODEL_NAME", "llama-3.1-8b-instruct")
             self.PROVIDER = "llama_server"
             logging.info("Using llama_server as LLM backend")

main.py

@@ -1,278 +0,0 @@
-import argparse
-import datetime
-import logging
-import os
-import sqlite3
-import time
-
-from dotenv import load_dotenv
-
-import chromadb
-from utils.chunker import Chunker
-from utils.cleaner import pdf_to_image, summarize_pdf_image
-from llm import LLMClient
-from scripts.query import QueryGenerator
-from utils.request import PaperlessNGXService
-
-_dotenv_loaded = load_dotenv()
-
-client = chromadb.PersistentClient(path=os.getenv("CHROMADB_PATH", ""))
-simba_docs = client.get_or_create_collection(name="simba_docs2")
-feline_vet_lookup = client.get_or_create_collection(name="feline_vet_lookup")
-
-parser = argparse.ArgumentParser(
-    description="An LLM tool to query information about Simba <3"
-)
-
-parser.add_argument("query", type=str, help="questions about simba's health")
-parser.add_argument(
-    "--reindex", action="store_true", help="re-index the simba documents"
-)
-parser.add_argument("--classify", action="store_true", help="test classification")
-parser.add_argument("--index", help="index a file")
-
-ppngx = PaperlessNGXService()
-
-llm_client = LLMClient()
-
-
-def index_using_pdf_llm(doctypes):
-    logging.info("reindex data...")
-    files = ppngx.get_data()
-    for file in files:
-        document_id: int = file["id"]
-        pdf_path = ppngx.download_pdf_from_id(id=document_id)
-        image_paths = pdf_to_image(filepath=pdf_path)
-        logging.info(f"summarizing {file}")
-        generated_summary = summarize_pdf_image(filepaths=image_paths)
-        file["content"] = generated_summary
-
-    chunk_data(files, simba_docs, doctypes=doctypes)
-
-
-def date_to_epoch(date_str: str) -> float:
-    split_date = date_str.split("-")
-    date = datetime.datetime(
-        int(split_date[0]),
-        int(split_date[1]),
-        int(split_date[2]),
-        0,
-        0,
-        0,
-    )
-
-    return date.timestamp()
-
-
-def chunk_data(docs, collection, doctypes):
-    # Step 2: Create chunks
-    chunker = Chunker(collection)
-
-    logging.info(f"chunking {len(docs)} documents")
-    texts: list[str] = [doc["content"] for doc in docs]
-    with sqlite3.connect("database/visited.db") as conn:
-        to_insert = []
-        c = conn.cursor()
-        for index, text in enumerate(texts):
-            metadata = {
-                "created_date": date_to_epoch(docs[index]["created_date"]),
-                "filename": docs[index]["original_file_name"],
-                "document_type": doctypes.get(docs[index]["document_type"], ""),
-            }
-
-            if doctypes:
-                metadata["type"] = doctypes.get(docs[index]["document_type"])
-
-            chunker.chunk_document(
-                document=text,
-                metadata=metadata,
-            )
-            to_insert.append((docs[index]["id"],))
-
-        c.executemany(
-            "INSERT INTO indexed_documents (paperless_id) values (?)", to_insert
-        )
-        conn.commit()
-
-
-def chunk_text(texts: list[str], collection):
-    chunker = Chunker(collection)
-
-    for index, text in enumerate(texts):
-        metadata = {}
-        chunker.chunk_document(
-            document=text,
-            metadata=metadata,
-        )
-
-
-def classify_query(query: str, transcript: str) -> bool:
-    logging.info("Starting query generation")
-    qg_start = time.time()
-    qg = QueryGenerator()
-    query_type = qg.get_query_type(input=query, transcript=transcript)
-    logging.info(query_type)
-    qg_end = time.time()
-    logging.info(f"Query generation took {qg_end - qg_start:.2f} seconds")
-    return query_type == "Simba"
-
-
-def consult_oracle(
-    input: str,
-    collection,
-    transcript: str = "",
-):
-    chunker = Chunker(collection)
-
-    start_time = time.time()
-
-    # Ask
-    logging.info("Starting query generation")
-    qg_start = time.time()
-    qg = QueryGenerator()
-    doctype_query = qg.get_doctype_query(input=input)
-    # metadata_filter = qg.get_query(input)
-    metadata_filter = {**doctype_query}
-    logging.info(metadata_filter)
-    qg_end = time.time()
-    logging.info(f"Query generation took {qg_end - qg_start:.2f} seconds")
-
-    logging.info("Starting embedding generation")
-    embedding_start = time.time()
-    embeddings = chunker.embedding_fx(inputs=[input])
-    embedding_end = time.time()
-    logging.info(
-        f"Embedding generation took {embedding_end - embedding_start:.2f} seconds"
-    )
-
-    logging.info("Starting collection query")
-    query_start = time.time()
-    results = collection.query(
-        query_texts=[input],
-        query_embeddings=embeddings,
-        where=metadata_filter,
-    )
-    query_end = time.time()
-    logging.info(f"Collection query took {query_end - query_start:.2f} seconds")
-
-    # Generate
-    logging.info("Starting LLM generation")
-    llm_start = time.time()
-    system_prompt = "You are a helpful assistant that understands veterinary terms."
-    transcript_prompt = f"Here is the message transcript thus far {transcript}."
-    prompt = f"""Using the following data, help answer the user's query by providing as many details as possible.
-    Using this data: {results}. {transcript_prompt if len(transcript) > 0 else ""}
-    Respond to this prompt: {input}"""
-    output = llm_client.chat(prompt=prompt, system_prompt=system_prompt)
-    llm_end = time.time()
-    logging.info(f"LLM generation took {llm_end - llm_start:.2f} seconds")
-
-    total_time = time.time() - start_time
-    logging.info(f"Total consult_oracle execution took {total_time:.2f} seconds")
-
-    return output
-
-
-def llm_chat(input: str, transcript: str = "") -> str:
-    system_prompt = "You are a helpful assistant that understands veterinary terms."
-    transcript_prompt = f"Here is the message transcript thus far {transcript}."
-    prompt = f"""Answer the user in as if you were a cat named Simba. Don't act too catlike. Be assertive.
-    {transcript_prompt if len(transcript) > 0 else ""}
-    Respond to this prompt: {input}"""
-    output = llm_client.chat(prompt=prompt, system_prompt=system_prompt)
-    return output
-
-
-def paperless_workflow(input):
-    # Step 1: Get the text
-    ppngx = PaperlessNGXService()
-    docs = ppngx.get_data()
-
-    chunk_data(docs, collection=simba_docs)
-    consult_oracle(input, simba_docs)
-
-
-def consult_simba_oracle(input: str, transcript: str = ""):
-    is_simba_related = classify_query(query=input, transcript=transcript)
-
-    if is_simba_related:
-        logging.info("Query is related to simba")
-        return consult_oracle(
-            input=input,
-            collection=simba_docs,
-            transcript=transcript,
-        )
-
-    logging.info("Query is NOT related to simba")
-
-    return llm_chat(input=input, transcript=transcript)
-
-
-def filter_indexed_files(docs):
-    with sqlite3.connect("database/visited.db") as conn:
-        c = conn.cursor()
-        c.execute(
-            "CREATE TABLE IF NOT EXISTS indexed_documents (id INTEGER PRIMARY KEY AUTOINCREMENT, paperless_id INTEGER)"
-        )
-        c.execute("SELECT paperless_id FROM indexed_documents")
-        rows = c.fetchall()
-        conn.commit()
-
-    visited = {row[0] for row in rows}
-    return [doc for doc in docs if doc["id"] not in visited]
-
-
-def reindex():
-    with sqlite3.connect("database/visited.db") as conn:
-        c = conn.cursor()
-        # Ensure the table exists before trying to delete from it
-        c.execute(
-            "CREATE TABLE IF NOT EXISTS indexed_documents (id INTEGER PRIMARY KEY AUTOINCREMENT, paperless_id INTEGER)"
-        )
-        c.execute("DELETE FROM indexed_documents")
-        conn.commit()
-
-    # Delete all documents from the collection
-    all_docs = simba_docs.get()
-    if all_docs["ids"]:
-        simba_docs.delete(ids=all_docs["ids"])
-
-    logging.info("Fetching documents from Paperless-NGX")
-    ppngx = PaperlessNGXService()
-    docs = ppngx.get_data()
-    docs = filter_indexed_files(docs)
-    logging.info(f"Fetched {len(docs)} documents")
-
-    # Delete all chromadb data
-    ids = simba_docs.get(ids=None, limit=None, offset=0)
-    all_ids = ids["ids"]
-    if len(all_ids) > 0:
-        simba_docs.delete(ids=all_ids)
-
-    # Chunk documents
-    logging.info("Chunking documents now ...")
-    doctype_lookup = ppngx.get_doctypes()
-    chunk_data(docs, collection=simba_docs, doctypes=doctype_lookup)
-    logging.info("Done chunking documents")
-
-
-if __name__ == "__main__":
-    args = parser.parse_args()
-    if args.reindex:
-        reindex()
-
-    if args.classify:
-        consult_simba_oracle(input="yohohoho testing")
-        consult_simba_oracle(input="write an email")
-        consult_simba_oracle(input="how much does simba weigh")
-
-    if args.query:
-        logging.info("Consulting oracle ...")
-        print(
-            consult_oracle(
-                input=args.query,
-                collection=simba_docs,
-            )
-        )
-    else:
-        logging.info("please provide a query")

metrics.py

@@ -0,0 +1,55 @@
+import time
+from contextlib import contextmanager
+from prometheus_client import (
+    CollectorRegistry,
+    Counter,
+    Histogram,
+    generate_latest,
+)
+
+REGISTRY = CollectorRegistry(auto_describe=True)
+
+CHAT_RESPONSE_SECONDS = Histogram(
+    "raggr_chat_response_seconds",
+    "End-to-end chat response time in seconds.",
+    labelnames=("stream",),
+    buckets=(0.5, 1, 2, 5, 10, 30, 60, 120, 300),
+    registry=REGISTRY,
+)
+
+CHAT_REQUESTS_TOTAL = Counter(
+    "raggr_chat_requests_total",
+    "Total chat requests by stream mode and result.",
+    labelnames=("stream", "result"),
+    registry=REGISTRY,
+)
+
+
+def _s(stream: bool) -> str:
+    return "true" if stream else "false"
+
+
+@contextmanager
+def time_response(stream: bool):
+    t0 = time.monotonic()
+    result = "success"
+    try:
+        yield
+    except Exception:
+        result = "error"
+        raise
+    finally:
+        CHAT_RESPONSE_SECONDS.labels(stream=_s(stream)).observe(time.monotonic() - t0)
+        CHAT_REQUESTS_TOTAL.labels(stream=_s(stream), result=result).inc()
+
+
+def observe_response(stream: bool, seconds: float) -> None:
+    CHAT_RESPONSE_SECONDS.labels(stream=_s(stream)).observe(seconds)
+
+
+def count_result(stream: bool, result: str) -> None:
+    CHAT_REQUESTS_TOTAL.labels(stream=_s(stream), result=result).inc()
+
+
+def render_metrics() -> bytes:
+    return generate_latest(REGISTRY)

migrations/models/11_20260916031522_add_message_handle_to_conversation_messages.py

@@ -0,0 +1,71 @@
+from tortoise import BaseDBAsyncClient
+
+RUN_IN_TRANSACTION = True
+
+
+async def upgrade(db: BaseDBAsyncClient) -> str:
+    return """
+        ALTER TABLE "conversation_messages" ADD "message_handle" VARCHAR(255);
+        COMMENT ON COLUMN "conversation_messages"."speaker" IS 'USER: user\nSIMBA: simba\nTOOL: tool';"""
+
+
+async def downgrade(db: BaseDBAsyncClient) -> str:
+    return """
+        ALTER TABLE "conversation_messages" DROP COLUMN "message_handle";
+        COMMENT ON COLUMN "conversation_messages"."speaker" IS 'USER: user\nSIMBA: simba';"""
+
+
+MODELS_STATE = (
+    "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"
+)

migrations/models/12_20260916223332_add_cron_jobs.py

@@ -0,0 +1,86 @@
+from tortoise import BaseDBAsyncClient
+
+RUN_IN_TRANSACTION = True
+
+
+async def upgrade(db: BaseDBAsyncClient) -> str:
+    return """
+        CREATE TABLE IF NOT EXISTS "cron_jobs" (
+    "id" UUID NOT NULL PRIMARY KEY,
+    "name" VARCHAR(255) NOT NULL,
+    "description" TEXT,
+    "prompt" TEXT NOT NULL,
+    "recipient" VARCHAR(255) NOT NULL,
+    "channel" VARCHAR(20) NOT NULL,
+    "enabled" BOOL NOT NULL DEFAULT True,
+    "last_run_at" TIMESTAMPTZ,
+    "last_status" VARCHAR(50),
+    "last_error" TEXT,
+    "created_at" TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updated_at" TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+COMMENT ON COLUMN "cron_jobs"."channel" IS 'IMESSAGE: imessage\nEMAIL: email';"""
+
+
+async def downgrade(db: BaseDBAsyncClient) -> str:
+    return """
+        DROP TABLE IF EXISTS "cron_jobs";"""
+
+
+MODELS_STATE = (
+    "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"
+    "XV6+/x9WSMI2"
+)

migrations/models/13_20260917193429_add_beli_profiles_restaurants.py

@@ -0,0 +1,131 @@
+from tortoise import BaseDBAsyncClient
+
+RUN_IN_TRANSACTION = True
+
+
+async def upgrade(db: BaseDBAsyncClient) -> str:
+    return """
+        CREATE TABLE IF NOT EXISTS "cron_jobs" (
+    "id" UUID NOT NULL PRIMARY KEY,
+    "name" VARCHAR(255) NOT NULL,
+    "description" TEXT,
+    "prompt" TEXT NOT NULL,
+    "recipient" VARCHAR(255) NOT NULL,
+    "channel" VARCHAR(20) NOT NULL,
+    "enabled" BOOL NOT NULL DEFAULT True,
+    "last_run_at" TIMESTAMPTZ,
+    "last_status" VARCHAR(50),
+    "last_error" TEXT,
+    "created_at" TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updated_at" TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+COMMENT ON COLUMN "cron_jobs"."channel" IS 'IMESSAGE: imessage\nEMAIL: email';
+        CREATE TABLE IF NOT EXISTS "beli_profiles" (
+    "id" UUID NOT NULL PRIMARY KEY,
+    "beli_email" VARCHAR(255) NOT NULL,
+    "beli_password" TEXT NOT NULL,
+    "beli_user_id" VARCHAR(255),
+    "beli_refresh_token" TEXT,
+    "last_refreshed_at" TIMESTAMPTZ,
+    "last_error" TEXT,
+    "enabled" BOOL NOT NULL DEFAULT True,
+    "created_at" TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updated_at" TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "user_id" UUID NOT NULL REFERENCES "users" ("id") ON DELETE CASCADE,
+    CONSTRAINT "uid_beli_profil_user_id_f4bba0" UNIQUE ("user_id", "beli_email")
+);
+        CREATE TABLE IF NOT EXISTS "beli_restaurants" (
+    "id" UUID NOT NULL PRIMARY KEY,
+    "beli_business_id" VARCHAR(255) NOT NULL,
+    "name" VARCHAR(500) NOT NULL,
+    "city" VARCHAR(255),
+    "neighborhood" VARCHAR(255),
+    "cuisine" JSONB NOT NULL,
+    "price_range" VARCHAR(10),
+    "status" VARCHAR(20) NOT NULL,
+    "rank_index" INT,
+    "score" DECIMAL(5,2),
+    "notes" TEXT,
+    "tags" JSONB NOT NULL,
+    "fetched_at" TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "created_at" TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "profile_id" UUID NOT NULL REFERENCES "beli_profiles" ("id") ON DELETE CASCADE,
+    CONSTRAINT "uid_beli_restau_profile_921fe6" UNIQUE ("profile_id", "beli_business_id", "status")
+);
+COMMENT ON COLUMN "beli_restaurants"."status" IS 'BEEN: been\nWANT_TO_TRY: want_to_try';"""
+
+
+async def downgrade(db: BaseDBAsyncClient) -> str:
+    return """
+        DROP TABLE IF EXISTS "beli_profiles";
+        DROP TABLE IF EXISTS "cron_jobs";
+        DROP TABLE IF EXISTS "beli_restaurants";"""
+
+
+MODELS_STATE = (
+    "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"
+)

migrations/models/14_20260917205441_beli-update.py

@@ -0,0 +1,89 @@
+from tortoise import BaseDBAsyncClient
+
+RUN_IN_TRANSACTION = True
+
+
+async def upgrade(db: BaseDBAsyncClient) -> str:
+    return """
+        ALTER TABLE "beli_restaurants" DROP CONSTRAINT IF EXISTS "uid_beli_restau_profile_921fe6";
+        ALTER TABLE "beli_restaurants" ADD "friend_name" VARCHAR(255);
+        ALTER TABLE "beli_restaurants" ADD "friend_beli_user_id" VARCHAR(255) NOT NULL DEFAULT '';
+        CREATE UNIQUE INDEX IF NOT EXISTS "uid_beli_restau_profile_1e4068" ON "beli_restaurants" ("profile_id", "beli_business_id", "status", "friend_beli_user_id");"""
+
+
+async def downgrade(db: BaseDBAsyncClient) -> str:
+    return """
+        DROP INDEX IF EXISTS "uid_beli_restau_profile_1e4068";
+        ALTER TABLE "beli_restaurants" DROP COLUMN "friend_name";
+        ALTER TABLE "beli_restaurants" DROP COLUMN "friend_beli_user_id";
+        CREATE UNIQUE INDEX IF NOT EXISTS "uid_beli_restau_profile_921fe6" ON "beli_restaurants" ("profile_id", "beli_business_id", "status");"""
+
+
+MODELS_STATE = (
+    "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"
+)

migrations/models/15_20260917220930_beli_add_beli_category_09172026.py

@@ -0,0 +1,87 @@
+from tortoise import BaseDBAsyncClient
+
+RUN_IN_TRANSACTION = True
+
+
+async def upgrade(db: BaseDBAsyncClient) -> str:
+    return """
+        DROP INDEX IF EXISTS "uid_beli_restau_profile_1e4068";
+        ALTER TABLE "beli_restaurants" ADD "beli_category" VARCHAR(10) NOT NULL DEFAULT '';
+        CREATE UNIQUE INDEX IF NOT EXISTS "uid_beli_restau_profile_93dc73" ON "beli_restaurants" ("profile_id", "beli_business_id", "status", "friend_beli_user_id", "beli_category");"""
+
+
+async def downgrade(db: BaseDBAsyncClient) -> str:
+    return """
+        DROP INDEX IF EXISTS "uid_beli_restau_profile_93dc73";
+        ALTER TABLE "beli_restaurants" DROP COLUMN "beli_category";
+        CREATE UNIQUE INDEX IF NOT EXISTS "uid_beli_restau_profile_1e4068" ON "beli_restaurants" ("profile_id", "beli_business_id", "status", "friend_beli_user_id");"""
+
+
+MODELS_STATE = (
+    "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"
+)

migrations/models/16_20261012173826_add_oidc_states.py

@@ -0,0 +1,101 @@
+from tortoise import BaseDBAsyncClient
+
+RUN_IN_TRANSACTION = True
+
+
+async def upgrade(db: BaseDBAsyncClient) -> str:
+    return """
+        CREATE TABLE IF NOT EXISTS "oidc_states" (
+    "state" VARCHAR(128) NOT NULL PRIMARY KEY,
+    "pkce_verifier" VARCHAR(128) NOT NULL,
+    "expires_at" TIMESTAMPTZ NOT NULL,
+    "created_at" TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+CREATE INDEX IF NOT EXISTS "idx_oidc_states_expires_c461d9" ON "oidc_states" ("expires_at");
+COMMENT ON TABLE "oidc_states" IS 'Pending OIDC login: maps the `state` param to its PKCE verifier.';
+        ALTER TABLE "users" ALTER COLUMN "ldap_groups" TYPE JSONB USING "ldap_groups"::JSONB;
+        ALTER TABLE "beli_restaurants" ALTER COLUMN "cuisine" TYPE JSONB USING "cuisine"::JSONB;
+        ALTER TABLE "beli_restaurants" ALTER COLUMN "tags" TYPE JSONB USING "tags"::JSONB;"""
+
+
+async def downgrade(db: BaseDBAsyncClient) -> str:
+    return """
+        ALTER TABLE "users" ALTER COLUMN "ldap_groups" TYPE JSONB USING "ldap_groups"::JSONB;
+        ALTER TABLE "beli_restaurants" ALTER COLUMN "cuisine" TYPE JSONB USING "cuisine"::JSONB;
+        ALTER TABLE "beli_restaurants" ALTER COLUMN "tags" TYPE JSONB USING "tags"::JSONB;
+        DROP TABLE IF EXISTS "oidc_states";"""
+
+
+MODELS_STATE = (
+    "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"
+    "wS81"
+)

migrations/models/17_20261012175338_add_artifacts.py

@@ -0,0 +1,108 @@
+from tortoise import BaseDBAsyncClient
+
+RUN_IN_TRANSACTION = True
+
+
+async def upgrade(db: BaseDBAsyncClient) -> str:
+    return """
+        CREATE TABLE IF NOT EXISTS "artifacts" (
+    "id" UUID NOT NULL PRIMARY KEY,
+    "tool" VARCHAR(255) NOT NULL,
+    "kind" VARCHAR(64) NOT NULL,
+    "title" VARCHAR(255) NOT NULL,
+    "data" JSONB NOT NULL,
+    "source_ref" JSONB,
+    "version" INT NOT NULL DEFAULT 1,
+    "created_at" TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updated_at" TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "conversation_id" UUID NOT NULL REFERENCES "conversations" ("id") ON DELETE CASCADE,
+    "message_id" UUID REFERENCES "conversation_messages" ("id") ON DELETE SET NULL,
+    "user_id" UUID NOT NULL REFERENCES "users" ("id") ON DELETE CASCADE
+);
+COMMENT ON TABLE "artifacts" IS 'A structured tool result (recipe, budget, note…) rendered in the artifact panel.';"""
+
+
+async def downgrade(db: BaseDBAsyncClient) -> str:
+    return """
+        DROP TABLE IF EXISTS "artifacts";"""
+
+
+MODELS_STATE = (
+    "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"
+    "D1XXXUg="
+)

migrations/models/18_20261012180707_add_ynab_mirror.py

@@ -0,0 +1,259 @@
+from tortoise import BaseDBAsyncClient
+
+RUN_IN_TRANSACTION = True
+
+
+async def upgrade(db: BaseDBAsyncClient) -> str:
+    return """
+        CREATE TABLE IF NOT EXISTS "ynab_accounts" (
+    "id" VARCHAR(36) NOT NULL PRIMARY KEY,
+    "name" VARCHAR(255) NOT NULL,
+    "type" VARCHAR(50) NOT NULL,
+    "on_budget" BOOL NOT NULL,
+    "closed" BOOL NOT NULL,
+    "note" TEXT,
+    "balance" DECIMAL(15,3) NOT NULL,
+    "cleared_balance" DECIMAL(15,3) NOT NULL,
+    "uncleared_balance" DECIMAL(15,3) NOT NULL,
+    "last_reconciled_at" TIMESTAMPTZ,
+    "deleted" BOOL NOT NULL DEFAULT False
+);
+        CREATE TABLE IF NOT EXISTS "ynab_categories" (
+    "id" VARCHAR(36) NOT NULL PRIMARY KEY,
+    "category_group_id" VARCHAR(36) NOT NULL,
+    "name" VARCHAR(255) NOT NULL,
+    "hidden" BOOL NOT NULL,
+    "internal" BOOL NOT NULL DEFAULT False,
+    "note" TEXT,
+    "goal_type" VARCHAR(20),
+    "goal_target" DECIMAL(15,3),
+    "goal_target_month" DATE,
+    "deleted" BOOL NOT NULL DEFAULT False
+);
+CREATE INDEX IF NOT EXISTS "idx_ynab_catego_categor_2fc4cc" ON "ynab_categories" ("category_group_id");
+        CREATE TABLE IF NOT EXISTS "ynab_category_groups" (
+    "id" VARCHAR(36) NOT NULL PRIMARY KEY,
+    "name" VARCHAR(255) NOT NULL,
+    "hidden" BOOL NOT NULL,
+    "internal" BOOL NOT NULL DEFAULT False,
+    "deleted" BOOL NOT NULL DEFAULT False
+);
+        CREATE TABLE IF NOT EXISTS "ynab_changes" (
+    "id" BIGSERIAL NOT NULL PRIMARY KEY,
+    "synced_at" TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "server_knowledge" BIGINT NOT NULL,
+    "entity_type" VARCHAR(30) NOT NULL,
+    "entity_id" VARCHAR(64) NOT NULL,
+    "action" VARCHAR(10) NOT NULL,
+    "label" VARCHAR(500) NOT NULL,
+    "changes" JSONB NOT NULL
+);
+CREATE INDEX IF NOT EXISTS "idx_ynab_change_synced__77ae75" ON "ynab_changes" ("synced_at");
+CREATE INDEX IF NOT EXISTS "idx_ynab_change_entity__c12b5b" ON "ynab_changes" ("entity_type");
+CREATE INDEX IF NOT EXISTS "idx_ynab_change_entity__9fb442" ON "ynab_changes" ("entity_id");
+COMMENT ON TABLE "ynab_changes" IS 'Append-only log of what each sync changed, built by diffing against the mirror.';
+        CREATE TABLE IF NOT EXISTS "ynab_months" (
+    "id" VARCHAR(10) NOT NULL PRIMARY KEY,
+    "month" DATE NOT NULL,
+    "note" TEXT,
+    "income" DECIMAL(15,3) NOT NULL,
+    "budgeted" DECIMAL(15,3) NOT NULL,
+    "activity" DECIMAL(15,3) NOT NULL,
+    "to_be_budgeted" DECIMAL(15,3) NOT NULL,
+    "age_of_money" INT,
+    "deleted" BOOL NOT NULL DEFAULT False
+);
+CREATE INDEX IF NOT EXISTS "idx_ynab_months_month_483dcb" ON "ynab_months" ("month");
+        CREATE TABLE IF NOT EXISTS "ynab_month_categories" (
+    "id" VARCHAR(47) NOT NULL PRIMARY KEY,
+    "month" DATE NOT NULL,
+    "category_id" VARCHAR(36) NOT NULL,
+    "budgeted" DECIMAL(15,3) NOT NULL,
+    "activity" DECIMAL(15,3) NOT NULL,
+    "balance" DECIMAL(15,3) NOT NULL,
+    "deleted" BOOL NOT NULL DEFAULT False
+);
+CREATE INDEX IF NOT EXISTS "idx_ynab_month__month_f13a79" ON "ynab_month_categories" ("month");
+CREATE INDEX IF NOT EXISTS "idx_ynab_month__categor_a62299" ON "ynab_month_categories" ("category_id");
+COMMENT ON TABLE "ynab_month_categories" IS 'Per-month category amounts. ``budgeted`` is what YNAB calls \"Assigned\".';
+        CREATE TABLE IF NOT EXISTS "ynab_payees" (
+    "id" VARCHAR(36) NOT NULL PRIMARY KEY,
+    "name" VARCHAR(500) NOT NULL,
+    "transfer_account_id" VARCHAR(36),
+    "deleted" BOOL NOT NULL DEFAULT False
+);
+        CREATE TABLE IF NOT EXISTS "ynab_subtransactions" (
+    "id" VARCHAR(64) NOT NULL PRIMARY KEY,
+    "transaction_id" VARCHAR(64) NOT NULL,
+    "amount" DECIMAL(15,3) NOT NULL,
+    "memo" TEXT,
+    "payee_id" VARCHAR(36),
+    "category_id" VARCHAR(36),
+    "transfer_account_id" VARCHAR(36),
+    "deleted" BOOL NOT NULL DEFAULT False
+);
+CREATE INDEX IF NOT EXISTS "idx_ynab_subtra_transac_0571ba" ON "ynab_subtransactions" ("transaction_id");
+CREATE INDEX IF NOT EXISTS "idx_ynab_subtra_categor_c16c94" ON "ynab_subtransactions" ("category_id");
+COMMENT ON TABLE "ynab_subtransactions" IS 'Lines of a split transaction; the parent''s category is \"Split\".';
+        CREATE TABLE IF NOT EXISTS "ynab_sync_state" (
+    "budget_id" VARCHAR(64) NOT NULL PRIMARY KEY,
+    "budget_name" VARCHAR(255),
+    "server_knowledge" BIGINT,
+    "last_synced_at" TIMESTAMPTZ,
+    "last_full_sync_at" TIMESTAMPTZ,
+    "last_error" TEXT
+);
+        CREATE TABLE IF NOT EXISTS "ynab_transactions" (
+    "id" VARCHAR(64) NOT NULL PRIMARY KEY,
+    "date" DATE NOT NULL,
+    "amount" DECIMAL(15,3) NOT NULL,
+    "memo" TEXT,
+    "cleared" VARCHAR(20) NOT NULL,
+    "approved" BOOL NOT NULL,
+    "flag_color" VARCHAR(20),
+    "account_id" VARCHAR(36) NOT NULL,
+    "payee_id" VARCHAR(36),
+    "category_id" VARCHAR(36),
+    "transfer_account_id" VARCHAR(36),
+    "import_payee_name" VARCHAR(500),
+    "account_name" VARCHAR(255),
+    "payee_name" VARCHAR(500),
+    "category_name" VARCHAR(255),
+    "deleted" BOOL NOT NULL DEFAULT False
+);
+CREATE INDEX IF NOT EXISTS "idx_ynab_transa_date_a71ead" ON "ynab_transactions" ("date");
+CREATE INDEX IF NOT EXISTS "idx_ynab_transa_account_414dfe" ON "ynab_transactions" ("account_id");
+CREATE INDEX IF NOT EXISTS "idx_ynab_transa_payee_i_4146bc" ON "ynab_transactions" ("payee_id");
+CREATE INDEX IF NOT EXISTS "idx_ynab_transa_categor_232d47" ON "ynab_transactions" ("category_id");
+        ALTER TABLE "users" ALTER COLUMN "ldap_groups" TYPE JSONB USING "ldap_groups"::JSONB;
+        ALTER TABLE "beli_restaurants" ALTER COLUMN "tags" TYPE JSONB USING "tags"::JSONB;
+        ALTER TABLE "beli_restaurants" ALTER COLUMN "cuisine" TYPE JSONB USING "cuisine"::JSONB;
+        ALTER TABLE "artifacts" ALTER COLUMN "data" TYPE JSONB USING "data"::JSONB;
+        ALTER TABLE "artifacts" ALTER COLUMN "source_ref" TYPE JSONB USING "source_ref"::JSONB;"""
+
+
+async def downgrade(db: BaseDBAsyncClient) -> str:
+    return """
+        ALTER TABLE "users" ALTER COLUMN "ldap_groups" TYPE JSONB USING "ldap_groups"::JSONB;
+        ALTER TABLE "artifacts" ALTER COLUMN "data" TYPE JSONB USING "data"::JSONB;
+        ALTER TABLE "artifacts" ALTER COLUMN "source_ref" TYPE JSONB USING "source_ref"::JSONB;
+        ALTER TABLE "beli_restaurants" ALTER COLUMN "tags" TYPE JSONB USING "tags"::JSONB;
+        ALTER TABLE "beli_restaurants" ALTER COLUMN "cuisine" TYPE JSONB USING "cuisine"::JSONB;
+        DROP TABLE IF EXISTS "ynab_category_groups";
+        DROP TABLE IF EXISTS "ynab_month_categories";
+        DROP TABLE IF EXISTS "ynab_accounts";
+        DROP TABLE IF EXISTS "ynab_sync_state";
+        DROP TABLE IF EXISTS "ynab_categories";
+        DROP TABLE IF EXISTS "ynab_months";
+        DROP TABLE IF EXISTS "ynab_subtransactions";
+        DROP TABLE IF EXISTS "ynab_changes";
+        DROP TABLE IF EXISTS "ynab_payees";
+        DROP TABLE IF EXISTS "ynab_transactions";"""
+
+
+MODELS_STATE = (
+    "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"
+)

migrations/models/5_20260409215154_add_user_memories.py

@@ -0,0 +1,112 @@
+from tortoise import BaseDBAsyncClient
+
+RUN_IN_TRANSACTION = True
+
+
+async def upgrade(db: BaseDBAsyncClient) -> str:
+    return """
+        CREATE TABLE IF NOT EXISTS "user_memories" (
+    "id" UUID NOT NULL PRIMARY KEY,
+    "content" TEXT NOT NULL,
+    "created_at" TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updated_at" TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "user_id" UUID NOT NULL REFERENCES "users" ("id") ON DELETE CASCADE
+);
+        CREATE TABLE IF NOT EXISTS "email_accounts" (
+    "id" UUID NOT NULL PRIMARY KEY,
+    "email_address" VARCHAR(255) NOT NULL UNIQUE,
+    "display_name" VARCHAR(255),
+    "imap_host" VARCHAR(255) NOT NULL,
+    "imap_port" INT NOT NULL DEFAULT 993,
+    "imap_username" VARCHAR(255) NOT NULL,
+    "imap_password" TEXT NOT NULL,
+    "is_active" BOOL NOT NULL DEFAULT True,
+    "last_error" TEXT,
+    "created_at" TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updated_at" TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "user_id" UUID NOT NULL REFERENCES "users" ("id") ON DELETE CASCADE
+);
+COMMENT ON TABLE "email_accounts" IS 'Email account configuration for IMAP connections.';
+        CREATE TABLE IF NOT EXISTS "emails" (
+    "id" UUID NOT NULL PRIMARY KEY,
+    "message_id" VARCHAR(255) NOT NULL UNIQUE,
+    "subject" VARCHAR(500) NOT NULL,
+    "from_address" VARCHAR(255) NOT NULL,
+    "to_address" TEXT NOT NULL,
+    "date" TIMESTAMPTZ NOT NULL,
+    "body_text" TEXT,
+    "body_html" TEXT,
+    "chromadb_doc_id" VARCHAR(255),
+    "created_at" TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "expires_at" TIMESTAMPTZ NOT NULL,
+    "account_id" UUID NOT NULL REFERENCES "email_accounts" ("id") ON DELETE CASCADE
+);
+CREATE INDEX IF NOT EXISTS "idx_emails_message_981ddd" ON "emails" ("message_id");
+COMMENT ON TABLE "emails" IS 'Email message metadata and content.';
+        CREATE TABLE IF NOT EXISTS "email_sync_status" (
+    "id" UUID NOT NULL PRIMARY KEY,
+    "last_sync_date" TIMESTAMPTZ,
+    "last_message_uid" INT NOT NULL DEFAULT 0,
+    "message_count" INT NOT NULL DEFAULT 0,
+    "consecutive_failures" INT NOT NULL DEFAULT 0,
+    "last_failure_date" TIMESTAMPTZ,
+    "updated_at" TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "account_id" UUID NOT NULL REFERENCES "email_accounts" ("id") ON DELETE CASCADE
+);
+COMMENT ON TABLE "email_sync_status" IS 'Tracks sync progress and state per email account.';"""
+
+
+async def downgrade(db: BaseDBAsyncClient) -> str:
+    return """
+        DROP TABLE IF EXISTS "user_memories";
+        DROP TABLE IF EXISTS "email_accounts";
+        DROP TABLE IF EXISTS "emails";
+        DROP TABLE IF EXISTS "email_sync_status";"""
+
+
+MODELS_STATE = (
+    "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"
+)

mkdocs.yml

@@ -23,3 +23,5 @@ nav:
   - Home: index.md
   - Architecture:
       - Authentication: authentication.md
+      - Desktop Client (proposal): desktop-client.md
+      - Cowork UI plan: cowork-ui-plan.md

pyproject.toml

@@ -5,7 +5,8 @@ description = "Add your description here"
 readme = "README.md"
 requires-python = ">=3.13"
 dependencies = [
-    "chromadb>=1.1.0",
+    "langchain-postgres>=0.0.13",
+    "psycopg[binary]>=3.1.0",
     "python-dotenv>=1.0.0",
     "flask>=3.1.2",
     "httpx>=0.28.1",
@@ -30,16 +31,22 @@ dependencies = [
     "asyncpg>=0.30.0",
     "langchain-openai>=1.1.6",
     "langchain>=1.2.0",
-    "langchain-chroma>=1.0.0",
     "langchain-community>=0.4.1",
+    "langgraph-checkpoint-sqlite>=2.0.0",
+    "aiosqlite>=0.20.0",
     "jq>=1.10.0",
     "tavily-python>=0.7.17",
-    "ynab>=1.3.0",
     "aioimaplib>=2.0.1",
     "html2text>=2025.4.15",
     "ollama>=0.6.1",
     "twilio>=9.10.2",
     "aioboto3>=13.0.0",
+    "prometheus-client>=0.26.0",
+    "google-api-python-client>=2.0.0",
+    "google-auth-oauthlib>=1.0.0",
+    "google-auth-httplib2>=0.2.0",
+    "langchain-mcp-adapters>=0.3.2",
+    "sqlglot>=30.22.0",
 ]
 
 [project.optional-dependencies]

raggr-frontend/package.json

@@ -20,6 +20,8 @@
     "react": "^19.1.1",
     "react-dom": "^19.1.1",
     "react-markdown": "^10.1.0",
+    "react-router-dom": "^7.18.3",
+    "remark-gfm": "^4.0.1",
     "tailwind-merge": "^3.5.0",
     "watch": "^1.0.2"
   },

raggr-frontend/src/App.css

@@ -60,7 +60,7 @@ body {
 ::-webkit-scrollbar-thumb { background: var(--color-sand); border-radius: 99px; }
 ::-webkit-scrollbar-thumb:hover { background: var(--color-warm-gray); }
 
-/* ── Markdown in answer bubbles ─────────────────────── */
+/* ── Markdown in assistant answers ──────────────────── */
 .markdown-content p { margin: 0.5em 0; line-height: 1.7; }
 .markdown-content p:first-child { margin-top: 0; }
 .markdown-content p:last-child { margin-bottom: 0; }
@@ -117,6 +117,29 @@ body {
 .markdown-content strong { font-weight: 700; }
 .markdown-content em { font-style: italic; }
 
+.markdown-content table {
+  width: 100%;
+  border-collapse: collapse;
+  margin: 0.75em 0;
+  font-size: 0.9em;
+  display: block;
+  overflow-x: auto;
+}
+.markdown-content th,
+.markdown-content td {
+  border: 1px solid var(--color-sand-light);
+  padding: 0.4em 0.6em;
+  text-align: left;
+  vertical-align: top;
+}
+.markdown-content thead th {
+  background: var(--color-sand-light);
+  font-weight: 700;
+}
+.markdown-content tbody tr:nth-child(even) {
+  background: color-mix(in srgb, var(--color-sand-light) 35%, transparent);
+}
+
 /* ── Animations ─────────────────────────────────────── */
 @keyframes fadeSlideUp {
   from { opacity: 0; transform: translateY(10px); }
@@ -126,6 +149,14 @@ body {
   animation: fadeSlideUp 0.3s ease-out forwards;
 }
 
+@keyframes drawer-in {
+  from { transform: translateX(-100%); }
+  to   { transform: translateX(0); }
+}
+.animate-drawer-in {
+  animation: drawer-in 0.25s ease-out;
+}
+
 @keyframes catPulse {
   0%, 80%, 100% { opacity: 0.25; transform: scale(0.75); }
   40%           { opacity: 1;    transform: scale(1); }

raggr-frontend/src/App.tsx

@@ -1,48 +1,15 @@
-import { useState, useEffect } from "react";
-
+import { Route, Routes } from "react-router-dom";
 import "./App.css";
 import { AuthProvider } from "./contexts/AuthContext";
 import { ChatScreen } from "./components/ChatScreen";
+import { ConversationsPage } from "./components/ConversationsPage";
 import { LoginScreen } from "./components/LoginScreen";
-import { conversationService } from "./api/conversationService";
+import { useAuthCheck } from "./hooks/useAuthCheck";
 import catIcon from "./assets/cat.png";
 
 const AppContainer = () => {
-  const [isAuthenticated, setAuthenticated] = useState<boolean>(false);
-  const [isChecking, setIsChecking] = useState<boolean>(true);
+  const { isAuthenticated, isChecking, isAdmin, setAuthenticated } = useAuthCheck();
 
-  useEffect(() => {
-    const checkAuth = async () => {
-      const accessToken = localStorage.getItem("access_token");
-      const refreshToken = localStorage.getItem("refresh_token");
-
-      // No tokens at all, not authenticated
-      if (!accessToken && !refreshToken) {
-        setIsChecking(false);
-        setAuthenticated(false);
-        return;
-      }
-
-      // Try to verify token by making a request
-      try {
-        await conversationService.getAllConversations();
-        // If successful, user is authenticated
-        setAuthenticated(true);
-      } catch (error) {
-        // Token is invalid or expired
-        console.error("Authentication check failed:", error);
-        localStorage.removeItem("access_token");
-        localStorage.removeItem("refresh_token");
-        setAuthenticated(false);
-      } finally {
-        setIsChecking(false);
-      }
-    };
-
-    checkAuth();
-  }, []);
-
-  // Show loading state while checking authentication
   if (isChecking) {
     return (
       <div className="h-screen flex flex-col items-center justify-center bg-cream gap-4">
@@ -58,14 +25,23 @@ const AppContainer = () => {
     );
   }
 
+  if (!isAuthenticated) {
+    return <LoginScreen setAuthenticated={setAuthenticated} />;
+  }
+
   return (
-    <>
-      {isAuthenticated ? (
-        <ChatScreen setAuthenticated={setAuthenticated} />
-      ) : (
-        <LoginScreen setAuthenticated={setAuthenticated} />
-      )}
-    </>
+    <Routes>
+      <Route path="/conversations" element={<ConversationsPage />} />
+      {/* One ChatScreen instance serves both the home ("/") and per-conversation
+          ("/c/:id") routes. Using a single catch-all route keeps that instance
+          mounted across the navigate() that fires when the first message creates
+          a conversation — a remount here would abort the in-flight SSE stream
+          (and drop the answer before it's persisted). */}
+      <Route
+        path="*"
+        element={<ChatScreen setAuthenticated={setAuthenticated} isAdmin={isAdmin} />}
+      />
+    </Routes>
   );
 };
 

raggr-frontend/src/api/conversationService.ts

@@ -1,17 +1,20 @@
 import { userService } from "./userService";
 
 export type SSEEvent =
+  | { type: "thinking" }
+  | { type: "thinking_delta"; delta: string }
   | { type: "tool_start"; tool: string }
   | { type: "tool_end"; tool: string }
+  | { type: "content"; delta: string }
   | { type: "response"; message: string }
-  | { type: "error"; message: string };
+  | { type: "error"; message: string; stalled?: boolean };
 
 export type SSEEventCallback = (event: SSEEvent) => void;
 
 interface Message {
   id: string;
   text: string;
-  speaker: "user" | "simba";
+  speaker: "user" | "simba" | "tool";
   created_at: string;
   image_key?: string | null;
 }
@@ -25,18 +28,10 @@ interface Conversation {
   user_id?: string;
 }
 
-interface QueryRequest {
-  query: string;
-}
-
 interface QueryResponse {
   response: string;
 }
 
-interface CreateConversationRequest {
-  user_id: string;
-}
-
 class ConversationService {
   private baseUrl = "/api";
   private conversationBaseUrl = "/api/conversation";
@@ -46,7 +41,7 @@ class ConversationService {
     conversation_id: string,
     signal?: AbortSignal,
   ): Promise<QueryResponse> {
-    const response = await userService.fetchWithRefreshToken(
+    const response = await userService.fetchWithAuth(
       `${this.conversationBaseUrl}/query`,
       {
         method: "POST",
@@ -63,7 +58,7 @@ class ConversationService {
   }
 
   async getMessages(): Promise<Conversation> {
-    const response = await userService.fetchWithRefreshToken(
+    const response = await userService.fetchWithAuth(
       `${this.baseUrl}/messages`,
       {
         method: "GET",
@@ -78,7 +73,7 @@ class ConversationService {
   }
 
   async getConversation(conversationId: string): Promise<Conversation> {
-    const response = await userService.fetchWithRefreshToken(
+    const response = await userService.fetchWithAuth(
       `${this.conversationBaseUrl}/${conversationId}`,
       {
         method: "GET",
@@ -93,7 +88,7 @@ class ConversationService {
   }
 
   async createConversation(): Promise<Conversation> {
-    const response = await userService.fetchWithRefreshToken(
+    const response = await userService.fetchWithAuth(
       `${this.conversationBaseUrl}/`,
       {
         method: "POST",
@@ -107,9 +102,51 @@ class ConversationService {
     return await response.json();
   }
 
-  async getAllConversations(): Promise<Conversation[]> {
-    const response = await userService.fetchWithRefreshToken(
-      `${this.conversationBaseUrl}/`,
+  async renameConversation(
+    conversationId: string,
+    name: string,
+  ): Promise<Conversation> {
+    const response = await userService.fetchWithAuth(
+      `${this.conversationBaseUrl}/${conversationId}`,
+      {
+        method: "PATCH",
+        body: JSON.stringify({ name }),
+      },
+    );
+
+    if (!response.ok) {
+      throw new Error("Failed to rename conversation");
+    }
+
+    return await response.json();
+  }
+
+  async deleteConversation(conversationId: string): Promise<void> {
+    const response = await userService.fetchWithAuth(
+      `${this.conversationBaseUrl}/${conversationId}`,
+      {
+        method: "DELETE",
+      },
+    );
+
+    if (!response.ok) {
+      throw new Error("Failed to delete conversation");
+    }
+  }
+
+  async getAllConversations(params?: {
+    limit?: number;
+    offset?: number;
+    search?: string;
+  }): Promise<Conversation[]> {
+    const search = new URLSearchParams();
+    if (params?.limit != null) search.set("limit", String(params.limit));
+    if (params?.offset != null) search.set("offset", String(params.offset));
+    if (params?.search) search.set("search", params.search);
+    const qs = search.toString();
+
+    const response = await userService.fetchWithAuth(
+      `${this.conversationBaseUrl}/${qs ? `?${qs}` : ""}`,
       {
         method: "GET",
       },
@@ -130,7 +167,7 @@ class ConversationService {
     formData.append("file", file);
     formData.append("conversation_id", conversationId);
 
-    const response = await userService.fetchWithRefreshToken(
+    const response = await userService.fetchWithAuth(
       `${this.conversationBaseUrl}/upload-image`,
       {
         method: "POST",
@@ -148,7 +185,7 @@ class ConversationService {
   }
 
   async getPresignedImageUrl(imageKey: string): Promise<string> {
-    const response = await userService.fetchWithRefreshToken(
+    const response = await userService.fetchWithAuth(
       `${this.conversationBaseUrl}/image/${imageKey}`,
     );
     if (!response.ok) {
@@ -170,7 +207,7 @@ class ConversationService {
       body.image_key = imageKey;
     }
 
-    const response = await userService.fetchWithRefreshToken(
+    const response = await userService.fetchWithAuth(
       `${this.conversationBaseUrl}/stream-query`,
       {
         method: "POST",

raggr-frontend/src/api/oidcService.ts

@@ -24,14 +24,11 @@ class OIDCService {
    * Initiate OIDC login flow
    * Returns authorization URL to redirect user to
    */
-  async initiateLogin(redirectAfterLogin: string = "/"): Promise<string> {
-    const response = await fetch(
-      `${this.baseUrl}/login?redirect=${encodeURIComponent(redirectAfterLogin)}`,
-      {
-        method: "GET",
-        headers: { "Content-Type": "application/json" },
-      }
-    );
+  async initiateLogin(): Promise<string> {
+    const response = await fetch(`${this.baseUrl}/login`, {
+      method: "GET",
+      headers: { "Content-Type": "application/json" },
+    });
 
     if (!response.ok) {
       throw new Error("Failed to initiate OIDC login");

raggr-frontend/src/api/scheduledMessageService.ts

@@ -0,0 +1,72 @@
+import { userService } from "./userService";
+
+export interface ScheduledMessage {
+  id: string;
+  recipient: string;
+  channel: "imessage" | "email";
+  content: string;
+  subject: string | null;
+  scheduled_at: string;
+  status: "pending" | "sent" | "failed" | "cancelled";
+  recurrence: "none" | "daily" | "weekly" | "monthly";
+  use_agent: boolean;
+  error_message: string | null;
+  created_at: string;
+  updated_at: string;
+}
+
+export interface CreateScheduledMessage {
+  recipient: string;
+  channel: "imessage" | "email";
+  content: string;
+  subject?: string;
+  scheduled_at: string;
+  recurrence?: "none" | "daily" | "weekly" | "monthly";
+  use_agent?: boolean;
+}
+
+class ScheduledMessageService {
+  private baseUrl = "/api/scheduled-messages";
+
+  async list(): Promise<ScheduledMessage[]> {
+    const response = await userService.fetchWithAuth(`${this.baseUrl}/`);
+    if (!response.ok) throw new Error("Failed to list scheduled messages");
+    return response.json();
+  }
+
+  async create(data: CreateScheduledMessage): Promise<ScheduledMessage> {
+    const response = await userService.fetchWithAuth(`${this.baseUrl}/`, {
+      method: "POST",
+      body: JSON.stringify(data),
+    });
+    if (!response.ok) {
+      const err = await response.json();
+      throw new Error(err.error ?? "Failed to create scheduled message");
+    }
+    return response.json();
+  }
+
+  async update(id: string, data: Partial<CreateScheduledMessage> & { status?: string }): Promise<ScheduledMessage> {
+    const response = await userService.fetchWithAuth(`${this.baseUrl}/${id}`, {
+      method: "PUT",
+      body: JSON.stringify(data),
+    });
+    if (!response.ok) {
+      const err = await response.json();
+      throw new Error(err.error ?? "Failed to update scheduled message");
+    }
+    return response.json();
+  }
+
+  async remove(id: string): Promise<void> {
+    const response = await userService.fetchWithAuth(`${this.baseUrl}/${id}`, {
+      method: "DELETE",
+    });
+    if (!response.ok) {
+      const err = await response.json();
+      throw new Error(err.error ?? "Failed to delete scheduled message");
+    }
+  }
+}
+
+export const scheduledMessageService = new ScheduledMessageService();

raggr-frontend/src/api/userService.ts

@@ -29,7 +29,22 @@ class UserService {
     return await response.json();
   }
 
+  private refreshInFlight: Promise<string> | null = null;
+
+  /**
+   * Exchange the refresh token for a new access token. The refresh token is
+   * only ever sent here. Concurrent callers share one in-flight request.
+   */
   async refreshToken(): Promise<string> {
+    if (!this.refreshInFlight) {
+      this.refreshInFlight = this.doRefresh().finally(() => {
+        this.refreshInFlight = null;
+      });
+    }
+    return this.refreshInFlight;
+  }
+
+  private async doRefresh(): Promise<string> {
     const refreshToken = localStorage.getItem("refresh_token");
 
     if (!refreshToken) {
@@ -71,85 +86,65 @@ class UserService {
     }
   }
 
+  /**
+   * Authenticated fetch: sends the access token and, on a 401 (expired or
+   * missing access token), refreshes once and retries. With no stored access
+   * token it refreshes up front instead of making a doomed request.
+   */
   async fetchWithAuth(
     url: string,
     options: RequestInit = {},
-  ): Promise<Response> {
-    const accessToken = localStorage.getItem("access_token");
-
-    // Add authorization header
-    const headers = {
-      "Content-Type": "application/json",
-      ...(options.headers || {}),
-      ...(accessToken && { Authorization: `Bearer ${accessToken}` }),
-    };
-
-    let response = await fetch(url, { ...options, headers });
-
-    // If unauthorized, try refreshing the token
-    if (response.status === 401) {
-      try {
-        const newAccessToken = await this.refreshToken();
-
-        // Retry the request with new token
-        headers.Authorization = `Bearer ${newAccessToken}`;
-        response = await fetch(url, { ...options, headers });
-      } catch (error) {
-        // Refresh failed, redirect to login or throw error
-        throw new Error("Session expired. Please log in again.");
-      }
-    }
-
-    return response;
-  }
-
-  async fetchWithRefreshToken(
-    url: string,
-    options: RequestInit = {},
     { skipContentType = false }: { skipContentType?: boolean } = {},
   ): Promise<Response> {
-    const refreshToken = localStorage.getItem("refresh_token");
-
-    // Add authorization header
-    const headers: Record<string, string> = {
+    const buildHeaders = (token: string | null): Record<string, string> => ({
       ...(skipContentType ? {} : { "Content-Type": "application/json" }),
       ...((options.headers as Record<string, string>) || {}),
-      ...(refreshToken ? { Authorization: `Bearer ${refreshToken}` } : {}),
-    };
+      ...(token ? { Authorization: `Bearer ${token}` } : {}),
+    });
 
-    let response = await fetch(url, { ...options, headers });
-
-    // If unauthorized, try refreshing the token
-    if (response.status === 401) {
+    const refreshOrExpire = async (): Promise<string> => {
       try {
-        const newAccessToken = await this.refreshToken();
-
-        // Retry the request with new token
-        headers.Authorization = `Bearer ${newAccessToken}`;
-        response = await fetch(url, { ...options, headers });
-      } catch (error) {
-        // Refresh failed, redirect to login or throw error
+        return await this.refreshToken();
+      } catch {
         throw new Error("Session expired. Please log in again.");
       }
+    };
+
+    let accessToken = localStorage.getItem("access_token");
+    if (!accessToken) {
+      accessToken = await refreshOrExpire();
+    }
+
+    let response = await fetch(url, {
+      ...options,
+      headers: buildHeaders(accessToken),
+    });
+
+    if (response.status === 401) {
+      accessToken = await refreshOrExpire();
+      response = await fetch(url, {
+        ...options,
+        headers: buildHeaders(accessToken),
+      });
     }
 
     return response;
   }
 
   async getMe(): Promise<{ id: string; username: string; email: string; is_admin: boolean }> {
-    const response = await this.fetchWithRefreshToken(`${this.baseUrl}/me`);
+    const response = await this.fetchWithAuth(`${this.baseUrl}/me`);
     if (!response.ok) throw new Error("Failed to fetch user profile");
     return response.json();
   }
 
   async adminListUsers(): Promise<AdminUserRecord[]> {
-    const response = await this.fetchWithRefreshToken(`${this.baseUrl}/admin/users`);
+    const response = await this.fetchWithAuth(`${this.baseUrl}/admin/users`);
     if (!response.ok) throw new Error("Failed to list users");
     return response.json();
   }
 
   async adminSetWhatsapp(userId: string, number: string): Promise<AdminUserRecord> {
-    const response = await this.fetchWithRefreshToken(
+    const response = await this.fetchWithAuth(
       `${this.baseUrl}/admin/users/${userId}/whatsapp`,
       { method: "PUT", body: JSON.stringify({ whatsapp_number: number }) },
     );
@@ -162,7 +157,7 @@ class UserService {
   }
 
   async adminUnlinkWhatsapp(userId: string): Promise<void> {
-    const response = await this.fetchWithRefreshToken(
+    const response = await this.fetchWithAuth(
       `${this.baseUrl}/admin/users/${userId}/whatsapp`,
       { method: "DELETE" },
     );
@@ -170,7 +165,7 @@ class UserService {
   }
 
   async adminToggleEmail(userId: string): Promise<AdminUserRecord> {
-    const response = await this.fetchWithRefreshToken(
+    const response = await this.fetchWithAuth(
       `${this.baseUrl}/admin/users/${userId}/email`,
       { method: "PUT" },
     );
@@ -179,7 +174,7 @@ class UserService {
   }
 
   async adminDisableEmail(userId: string): Promise<void> {
-    const response = await this.fetchWithRefreshToken(
+    const response = await this.fetchWithAuth(
       `${this.baseUrl}/admin/users/${userId}/email`,
       { method: "DELETE" },
     );

raggr-frontend/src/components/AdminPanel.tsx

@@ -1,4 +1,4 @@
-import { useEffect, useState } from "react";
+import { useState } from "react";
 import { X, Phone, PhoneOff, Pencil, Check, Mail, Copy } from "lucide-react";
 import { userService, type AdminUserRecord } from "../api/userService";
 import { cn } from "../lib/utils";
@@ -12,27 +12,19 @@ import {
   TableHeader,
   TableRow,
 } from "./ui/table";
+import { useAdminUsers } from "../hooks/useAdminUsers";
 
 type Props = {
   onClose: () => void;
 };
 
 export const AdminPanel = ({ onClose }: Props) => {
-  const [users, setUsers] = useState<AdminUserRecord[]>([]);
-  const [loading, setLoading] = useState(true);
+  const { users, loading, updateUser } = useAdminUsers();
   const [editingId, setEditingId] = useState<string | null>(null);
   const [editValue, setEditValue] = useState("");
   const [rowError, setRowError] = useState<Record<string, string>>({});
   const [rowSuccess, setRowSuccess] = useState<Record<string, string>>({});
 
-  useEffect(() => {
-    userService
-      .adminListUsers()
-      .then(setUsers)
-      .catch(() => {})
-      .finally(() => setLoading(false));
-  }, []);
-
   const startEdit = (user: AdminUserRecord) => {
     setEditingId(user.id);
     setEditValue(user.whatsapp_number ?? "");
@@ -49,8 +41,8 @@ export const AdminPanel = ({ onClose }: Props) => {
     setRowError((p) => ({ ...p, [userId]: "" }));
     try {
       const updated = await userService.adminSetWhatsapp(userId, editValue);
-      setUsers((p) => p.map((u) => (u.id === userId ? updated : u)));
-      setRowSuccess((p) => ({ ...p, [userId]: "Saved ✓" }));
+      updateUser(userId, () => updated);
+      setRowSuccess((p) => ({ ...p, [userId]: "Saved" }));
       setEditingId(null);
       setTimeout(() => setRowSuccess((p) => ({ ...p, [userId]: "" })), 2000);
     } catch (err) {
@@ -65,10 +57,8 @@ export const AdminPanel = ({ onClose }: Props) => {
     setRowError((p) => ({ ...p, [userId]: "" }));
     try {
       await userService.adminUnlinkWhatsapp(userId);
-      setUsers((p) =>
-        p.map((u) => (u.id === userId ? { ...u, whatsapp_number: null } : u)),
-      );
-      setRowSuccess((p) => ({ ...p, [userId]: "Unlinked ✓" }));
+      updateUser(userId, (u) => ({ ...u, whatsapp_number: null }));
+      setRowSuccess((p) => ({ ...p, [userId]: "Unlinked" }));
       setTimeout(() => setRowSuccess((p) => ({ ...p, [userId]: "" })), 2000);
     } catch (err) {
       setRowError((p) => ({
@@ -82,8 +72,8 @@ export const AdminPanel = ({ onClose }: Props) => {
     setRowError((p) => ({ ...p, [userId]: "" }));
     try {
       const updated = await userService.adminToggleEmail(userId);
-      setUsers((p) => p.map((u) => (u.id === userId ? updated : u)));
-      setRowSuccess((p) => ({ ...p, [userId]: "Email enabled ✓" }));
+      updateUser(userId, () => updated);
+      setRowSuccess((p) => ({ ...p, [userId]: "Email enabled" }));
       setTimeout(() => setRowSuccess((p) => ({ ...p, [userId]: "" })), 2000);
     } catch (err) {
       setRowError((p) => ({
@@ -97,10 +87,8 @@ export const AdminPanel = ({ onClose }: Props) => {
     setRowError((p) => ({ ...p, [userId]: "" }));
     try {
       await userService.adminDisableEmail(userId);
-      setUsers((p) =>
-        p.map((u) => (u.id === userId ? { ...u, email_enabled: false, email_address: null } : u)),
-      );
-      setRowSuccess((p) => ({ ...p, [userId]: "Email disabled ✓" }));
+      updateUser(userId, (u) => ({ ...u, email_enabled: false, email_address: null }));
+      setRowSuccess((p) => ({ ...p, [userId]: "Email disabled" }));
       setTimeout(() => setRowSuccess((p) => ({ ...p, [userId]: "" })), 2000);
     } catch (err) {
       setRowError((p) => ({
@@ -112,7 +100,7 @@ export const AdminPanel = ({ onClose }: Props) => {
 
   const copyToClipboard = (text: string, userId: string) => {
     navigator.clipboard.writeText(text);
-    setRowSuccess((p) => ({ ...p, [userId]: "Copied ✓" }));
+    setRowSuccess((p) => ({ ...p, [userId]: "Copied" }));
     setTimeout(() => setRowSuccess((p) => ({ ...p, [userId]: "" })), 2000);
   };
 
@@ -128,7 +116,6 @@ export const AdminPanel = ({ onClose }: Props) => {
           "border border-sand-light/60",
         )}
       >
-        {/* Header */}
         <div className="flex items-center justify-between px-6 py-4 border-b border-sand-light/60">
           <div className="flex items-center gap-2.5">
             <div className="w-8 h-8 rounded-xl bg-leaf-pale flex items-center justify-center">
@@ -146,7 +133,6 @@ export const AdminPanel = ({ onClose }: Props) => {
           </button>
         </div>
 
-        {/* Body */}
         <div className="overflow-y-auto flex-1 rounded-b-3xl">
           {loading ? (
             <div className="px-6 py-12 text-center text-warm-gray text-sm">
@@ -155,7 +141,7 @@ export const AdminPanel = ({ onClose }: Props) => {
                 <span className="loading-dot w-2 h-2 rounded-full bg-amber-soft inline-block" />
                 <span className="loading-dot w-2 h-2 rounded-full bg-amber-soft inline-block" />
               </div>
-              Loading users…
+              Loading users...
             </div>
           ) : (
             <Table>
@@ -204,7 +190,7 @@ export const AdminPanel = ({ onClose }: Props) => {
                                 : "text-warm-gray/40 italic",
                             )}
                           >
-                            {user.whatsapp_number ?? "—"}
+                            {user.whatsapp_number ?? "\u2014"}
                           </span>
                           {rowSuccess[user.id] && (
                             <span className="text-xs text-leaf-dark">
@@ -235,7 +221,7 @@ export const AdminPanel = ({ onClose }: Props) => {
                             </button>
                           </div>
                         ) : (
-                          <span className="text-sm text-warm-gray/40 italic">—</span>
+                          <span className="text-sm text-warm-gray/40 italic">\u2014</span>
                         )}
                       </div>
                     </TableCell>

raggr-frontend/src/components/AnswerBubble.tsx

@@ -1,39 +1,49 @@
+import React, { useState } from "react";
 import ReactMarkdown from "react-markdown";
-import { cn } from "../lib/utils";
+import remarkGfm from "remark-gfm";
+import { Copy, Check } from "lucide-react";
 
 type AnswerBubbleProps = {
   text: string;
   loading?: boolean;
 };
 
-export const AnswerBubble = ({ text, loading }: AnswerBubbleProps) => {
-  return (
-    <div className="flex justify-start message-enter">
-      <div
-        className={cn(
-          "max-w-[78%] rounded-3xl rounded-bl-md",
-          "bg-warm-white border border-sand-light/70",
-          "shadow-sm shadow-sand/30",
-          "overflow-hidden",
-        )}
-      >
-        {/* amber accent bar */}
-        <div className="h-0.5 w-full bg-gradient-to-r from-amber-soft via-amber-glow/50 to-transparent" />
+export const AnswerBubble = React.memo(({ text, loading }: AnswerBubbleProps) => {
+  const [copied, setCopied] = useState(false);
 
-        <div className="px-4 py-3">
-          {loading ? (
-            <div className="flex items-center gap-1.5 py-1 px-1">
-              <span className="loading-dot w-2 h-2 rounded-full bg-amber-soft inline-block" />
-              <span className="loading-dot w-2 h-2 rounded-full bg-amber-soft inline-block" />
-              <span className="loading-dot w-2 h-2 rounded-full bg-amber-soft inline-block" />
-            </div>
-          ) : (
-            <div className="markdown-content text-sm leading-relaxed text-charcoal">
-              <ReactMarkdown>{text}</ReactMarkdown>
-            </div>
-          )}
+  const handleCopy = async (event: React.MouseEvent) => {
+    event.stopPropagation();
+    try {
+      await navigator.clipboard.writeText(text);
+      setCopied(true);
+      setTimeout(() => setCopied(false), 2000);
+    } catch {
+      // Clipboard unavailable (e.g. insecure context) — ignore
+    }
+  };
+
+  return (
+    <div className="message-enter">
+      {loading ? (
+        <div className="flex items-center gap-1.5 py-1">
+          <span className="loading-dot w-2 h-2 rounded-full bg-amber-soft inline-block" />
+          <span className="loading-dot w-2 h-2 rounded-full bg-amber-soft inline-block" />
+          <span className="loading-dot w-2 h-2 rounded-full bg-amber-soft inline-block" />
         </div>
-      </div>
+      ) : (
+        <div className="group relative -mx-3 -my-2 rounded-xl px-3 py-2 transition-colors duration-150 hover:bg-amber-soft/10">
+          <div className="markdown-content text-[15px] leading-relaxed text-charcoal">
+            <ReactMarkdown remarkPlugins={[remarkGfm]}>{text}</ReactMarkdown>
+          </div>
+          <button
+            onClick={handleCopy}
+            aria-label={copied ? "Copied" : "Copy message"}
+            className="absolute top-0 right-0 flex h-7 w-7 items-center justify-center rounded-lg border border-sand-light/60 bg-warm-white text-warm-gray shadow-sm opacity-0 transition-opacity duration-150 group-hover:opacity-100 hover:text-charcoal hover:bg-cream-dark focus:opacity-100 focus:outline-none cursor-pointer"
+          >
+            {copied ? <Check size={14} className="text-green-600" /> : <Copy size={14} />}
+          </button>
+        </div>
+      )}
     </div>
   );
-};
+});

raggr-frontend/src/components/ChatScreen.tsx

@@ -1,239 +1,119 @@
-import { useCallback, useEffect, useState, useRef } from "react";
-import { LogOut, Shield, PanelLeftClose, PanelLeftOpen, Menu, X } from "lucide-react";
-import { conversationService } from "../api/conversationService";
-import { userService } from "../api/userService";
+import React, { useCallback, useState, useRef } from "react";
+import { useNavigate } from "react-router-dom";
+import { PanelLeftOpen, Menu, X } from "lucide-react";
 import { QuestionBubble } from "./QuestionBubble";
 import { AnswerBubble } from "./AnswerBubble";
 import { ToolBubble } from "./ToolBubble";
+import { ThinkingBubble } from "./ThinkingBubble";
 import { MessageInput } from "./MessageInput";
-import { ConversationList } from "./ConversationList";
+import { SidebarContent } from "./SidebarContent";
 import { AdminPanel } from "./AdminPanel";
+import { ScheduledMessagesPanel } from "./ScheduledMessagesPanel";
 import { cn } from "../lib/utils";
+import { useConversations } from "../hooks/useConversations";
+import { useChat } from "../hooks/useChat";
 import catIcon from "../assets/cat.png";
 
-type Message = {
-  text: string;
-  speaker: "simba" | "user" | "tool";
-  image_key?: string | null;
-};
-
-type Conversation = {
-  title: string;
-  id: string;
-};
-
 type ChatScreenProps = {
   setAuthenticated: (isAuth: boolean) => void;
+  isAdmin: boolean;
 };
 
-const TOOL_MESSAGES: Record<string, string> = {
-  simba_search: "🔍 Searching Simba's records...",
-  web_search: "🌐 Searching the web...",
-  get_current_date: "📅 Checking today's date...",
-  ynab_budget_summary: "💰 Checking budget summary...",
-  ynab_search_transactions: "💳 Looking up transactions...",
-  ynab_category_spending: "📊 Analyzing category spending...",
-  ynab_insights: "📈 Generating budget insights...",
-  obsidian_search_notes: "📝 Searching notes...",
-  obsidian_read_note: "📖 Reading note...",
-  obsidian_create_note: "✏️ Saving note...",
-  obsidian_create_task: "✅ Creating task...",
-  journal_get_today: "📔 Reading today's journal...",
-  journal_get_tasks: "📋 Getting tasks...",
-  journal_add_task: "➕ Adding task...",
-  journal_complete_task: "✔️ Completing task...",
-};
-
-export const ChatScreen = ({ setAuthenticated }: ChatScreenProps) => {
-  const [query, setQuery] = useState<string>("");
-  const [simbaMode, setSimbaMode] = useState<boolean>(false);
-  const [messages, setMessages] = useState<Message[]>([]);
-  const [conversations, setConversations] = useState<Conversation[]>([]);
-  const [showConversations, setShowConversations] = useState<boolean>(false);
-  const [selectedConversation, setSelectedConversation] =
-    useState<Conversation | null>(null);
-  const [sidebarCollapsed, setSidebarCollapsed] = useState<boolean>(false);
-  const [isLoading, setIsLoading] = useState<boolean>(false);
-  const [isAdmin, setIsAdmin] = useState<boolean>(false);
-  const [showAdminPanel, setShowAdminPanel] = useState<boolean>(false);
-  const [pendingImage, setPendingImage] = useState<File | null>(null);
+export const ChatScreen = ({ setAuthenticated, isAdmin }: ChatScreenProps) => {
+  const navigate = useNavigate();
+  const [query, setQuery] = useState("");
+  const [simbaMode, setSimbaMode] = useState(false);
+  const [showConversations, setShowConversations] = useState(false);
+  const [sidebarCollapsed, setSidebarCollapsed] = useState(false);
+  const [showAdminPanel, setShowAdminPanel] = useState(false);
+  const [showScheduler, setShowScheduler] = useState(false);
 
   const messagesEndRef = useRef<HTMLDivElement>(null);
-  const isMountedRef = useRef<boolean>(true);
-  const abortControllerRef = useRef<AbortController | null>(null);
-  const simbaAnswers = ["meow.", "hiss...", "purrrrrr", "yowOWROWWowowr"];
+  const isLoadingRef = useRef(false);
 
   const scrollToBottom = useCallback(() => {
     requestAnimationFrame(() => {
       messagesEndRef.current?.scrollIntoView({
-        behavior: isLoading ? "instant" : "smooth",
+        behavior: isLoadingRef.current ? "instant" : "smooth",
       });
     });
-  }, [isLoading]);
-
-  useEffect(() => {
-    isMountedRef.current = true;
-    return () => {
-      isMountedRef.current = false;
-      abortControllerRef.current?.abort();
-    };
   }, []);
 
-  const handleSelectConversation = (conversation: Conversation) => {
+  const {
+    conversations,
+    selectedConversation,
+    createConversation,
+    renameConversation,
+    deleteConversation,
+    refreshConversations,
+  } = useConversations();
+
+  const onSessionExpired = useCallback(() => setAuthenticated(false), [setAuthenticated]);
+
+  const {
+    messages,
+    isLoading,
+    streaming,
+    thinking,
+    messagesLoading,
+    pendingImage,
+    setPendingImage,
+    sendMessage,
+    stopGeneration,
+    error,
+    clearError,
+    stalled,
+    retryStalled,
+    thinkingText,
+    thinkingDurationMs,
+  } = useChat({
+    createConversation,
+    refreshConversations,
+    onSessionExpired,
+    scrollToBottom,
+  });
+
+  // Keep ref in sync for scrollToBottom behavior
+  isLoadingRef.current = isLoading;
+
+  const handleSelectConversation = useCallback(
+    (conversation: { title: string; id: string }) => {
+      setShowConversations(false);
+      navigate(`/c/${conversation.id}`);
+    },
+    [navigate],
+  );
+
+  const handleCreateNewConversation = useCallback(() => {
     setShowConversations(false);
-    setSelectedConversation(conversation);
-    const load = async () => {
-      try {
-        const fetched = await conversationService.getConversation(conversation.id);
-        setMessages(
-          fetched.messages.map((m) => ({ text: m.text, speaker: m.speaker, image_key: m.image_key })),
-        );
-      } catch (err) {
-        console.error("Failed to load messages:", err);
-      }
-    };
-    load();
-  };
+    navigate("/");
+  }, [navigate]);
 
-  const loadConversations = async () => {
-    try {
-      const fetched = await conversationService.getAllConversations();
-      const parsed = fetched.map((c) => ({ id: c.id, title: c.name }));
-      setConversations(parsed);
-    } catch (err) {
-      console.error("Failed to load conversations:", err);
-    }
-  };
-
-  const handleCreateNewConversation = async () => {
-    const newConv = await conversationService.createConversation();
-    await loadConversations();
-    setSelectedConversation({ title: newConv.name, id: newConv.id });
-  };
-
-  useEffect(() => {
-    loadConversations();
-    userService.getMe().then((me) => setIsAdmin(me.is_admin)).catch(() => {});
-  }, []);
-
-  useEffect(() => {
-    scrollToBottom();
-  }, [messages]);
-
-  useEffect(() => {
-    const load = async () => {
-      if (!selectedConversation) return;
-      try {
-        const conv = await conversationService.getConversation(selectedConversation.id);
-        setSelectedConversation({ id: conv.id, title: conv.name });
-        setMessages(conv.messages.map((m) => ({ text: m.text, speaker: m.speaker, image_key: m.image_key })));
-      } catch (err) {
-        console.error("Failed to load messages:", err);
-      }
-    };
-    load();
-  }, [selectedConversation?.id]);
-
-  const handleQuestionSubmit = useCallback(async () => {
-    if ((!query.trim() && !pendingImage) || isLoading) return;
-
-    let activeConversation = selectedConversation;
-    if (!activeConversation) {
-      const newConv = await conversationService.createConversation();
-      activeConversation = { title: newConv.name, id: newConv.id };
-      setSelectedConversation(activeConversation);
-      setConversations((prev) => [activeConversation!, ...prev]);
-    }
-
-    // Capture pending image before clearing state
-    const imageFile = pendingImage;
-
-    const currMessages = messages.concat([{ text: query, speaker: "user" }]);
-    setMessages(currMessages);
+  const handleQuestionSubmit = useCallback(() => {
+    sendMessage(query, simbaMode);
     setQuery("");
-    setPendingImage(null);
-    setIsLoading(true);
-
-    if (simbaMode) {
-      const randomElement = simbaAnswers[Math.floor(Math.random() * simbaAnswers.length)];
-      setMessages((prev) => prev.concat([{ text: randomElement, speaker: "simba" }]));
-      setIsLoading(false);
-      return;
-    }
-
-    const abortController = new AbortController();
-    abortControllerRef.current = abortController;
-
-    try {
-      // Upload image first if present
-      let imageKey: string | undefined;
-      if (imageFile) {
-        const uploadResult = await conversationService.uploadImage(
-          imageFile,
-          activeConversation.id,
-        );
-        imageKey = uploadResult.image_key;
-
-        // Update the user message with the image key
-        setMessages((prev) => {
-          const updated = [...prev];
-          // Find the last user message we just added
-          for (let i = updated.length - 1; i >= 0; i--) {
-            if (updated[i].speaker === "user") {
-              updated[i] = { ...updated[i], image_key: imageKey };
-              break;
-            }
-          }
-          return updated;
-        });
-      }
-
-      await conversationService.streamQuery(
-        query,
-        activeConversation.id,
-        (event) => {
-          if (!isMountedRef.current) return;
-          if (event.type === "tool_start") {
-            const friendly = TOOL_MESSAGES[event.tool] ?? `🔧 Using ${event.tool}...`;
-            setMessages((prev) => prev.concat([{ text: friendly, speaker: "tool" }]));
-          } else if (event.type === "response") {
-            setMessages((prev) => prev.concat([{ text: event.message, speaker: "simba" }]));
-          } else if (event.type === "error") {
-            console.error("Stream error:", event.message);
-          }
-        },
-        abortController.signal,
-        imageKey,
-      );
-    } catch (error) {
-      if (error instanceof Error && error.name === "AbortError") {
-        console.log("Request was aborted");
-      } else {
-        console.error("Failed to send query:", error);
-        if (error instanceof Error && error.message.includes("Session expired")) {
-          setAuthenticated(false);
-        }
-      }
-    } finally {
-      if (isMountedRef.current) setIsLoading(false);
-      abortControllerRef.current = null;
-    }
-  }, [query, pendingImage, isLoading, selectedConversation, simbaMode, messages, setAuthenticated]);
+  }, [query, simbaMode, sendMessage]);
 
   const handleQueryChange = useCallback((event: React.ChangeEvent<HTMLTextAreaElement>) => {
     setQuery(event.target.value);
   }, []);
 
-  const handleKeyDown = useCallback((event: React.ChangeEvent<HTMLTextAreaElement>) => {
-    const kev = event as unknown as React.KeyboardEvent<HTMLTextAreaElement>;
-    if (kev.key === "Enter" && !kev.shiftKey) {
-      kev.preventDefault();
+  const handleKeyDown = useCallback((event: React.KeyboardEvent<HTMLTextAreaElement>) => {
+    if (event.key === "Enter" && !event.shiftKey) {
+      event.preventDefault();
       handleQuestionSubmit();
     }
   }, [handleQuestionSubmit]);
 
-  const handleImageSelect = useCallback((file: File) => setPendingImage(file), []);
-  const handleClearImage = useCallback(() => setPendingImage(null), []);
+  const handleToggleSimbaMode = useCallback(() => setSimbaMode((v) => !v), []);
+
+  const handleDeleteConversation = useCallback(
+    (id: string) => deleteConversation(id),
+    [deleteConversation],
+  );
+
+  const handleImageSelect = useCallback((file: File) => setPendingImage(file), [setPendingImage]);
+  const handleClearImage = useCallback(() => setPendingImage(null), [setPendingImage]);
 
   const handleLogout = () => {
     localStorage.removeItem("access_token");
@@ -241,9 +121,19 @@ export const ChatScreen = ({ setAuthenticated }: ChatScreenProps) => {
     setAuthenticated(false);
   };
 
+  const sidebarProps = {
+    conversations,
+    onCreateNewConversation: handleCreateNewConversation,
+    onSelectConversation: handleSelectConversation,
+    onRenameConversation: renameConversation,
+    onDeleteConversation: handleDeleteConversation,
+    selectedId: selectedConversation?.id,
+    isAdmin,
+  };
+
   return (
     <div className="h-screen h-[100dvh] flex flex-row bg-cream overflow-hidden">
-      {/* ── Desktop Sidebar ─────────────────────────────── */}
+      {/* Desktop Sidebar */}
       <aside
         className={cn(
           "hidden md:flex md:flex-col",
@@ -252,7 +142,6 @@ export const ChatScreen = ({ setAuthenticated }: ChatScreenProps) => {
         )}
       >
         {sidebarCollapsed ? (
-          /* Collapsed state */
           <div className="flex flex-col items-center py-4 gap-4 h-full">
             <button
               onClick={() => setSidebarCollapsed(false)}
@@ -267,66 +156,45 @@ export const ChatScreen = ({ setAuthenticated }: ChatScreenProps) => {
             />
           </div>
         ) : (
-          /* Expanded state */
-          <div className="flex flex-col h-full">
-            {/* Header */}
-            <div className="flex items-center justify-between px-4 py-4 border-b border-white/8">
-              <div className="flex items-center gap-2.5">
-                <img src={catIcon} alt="Simba" className="w-12 h-12" />
-                <h2
-                  className="text-lg font-bold text-cream tracking-tight"
-                  style={{ fontFamily: "var(--font-display)" }}
-                >
-                  asksimba
-                </h2>
-              </div>
-              <button
-                onClick={() => setSidebarCollapsed(true)}
-                className="w-7 h-7 rounded-lg flex items-center justify-center text-cream/40 hover:text-cream hover:bg-white/10 transition-all cursor-pointer"
-              >
-                <PanelLeftClose size={15} />
-              </button>
-            </div>
-
-            {/* Conversations */}
-            <div className="flex-1 overflow-y-auto px-2 py-3">
-              <ConversationList
-                conversations={conversations}
-                onCreateNewConversation={handleCreateNewConversation}
-                onSelectConversation={handleSelectConversation}
-                selectedId={selectedConversation?.id}
-              />
-            </div>
-
-            {/* Footer */}
-            <div className="px-2 pb-3 pt-2 border-t border-white/8 flex flex-col gap-0.5">
-              {isAdmin && (
-                <button
-                  onClick={() => setShowAdminPanel(true)}
-                  className="flex items-center gap-2 w-full px-3 py-2 rounded-xl text-sm text-cream/50 hover:text-cream hover:bg-white/8 transition-all cursor-pointer"
-                >
-                  <Shield size={14} />
-                  <span>Admin</span>
-                </button>
-              )}
-              <button
-                onClick={handleLogout}
-                className="flex items-center gap-2 w-full px-3 py-2 rounded-xl text-sm text-cream/50 hover:text-cream hover:bg-white/8 transition-all cursor-pointer"
-              >
-                <LogOut size={14} />
-                <span>Sign out</span>
-              </button>
-            </div>
-          </div>
+          <SidebarContent
+            {...sidebarProps}
+            onShowAdmin={() => setShowAdminPanel(true)}
+            onShowScheduler={() => setShowScheduler(true)}
+            onLogout={handleLogout}
+            onCollapse={() => setSidebarCollapsed(true)}
+          />
         )}
       </aside>
 
-      {/* Admin Panel modal */}
-      {showAdminPanel && <AdminPanel onClose={() => setShowAdminPanel(false)} />}
+      {/* Mobile drawer */}
+      {showConversations && (
+        <div className="md:hidden fixed inset-0 z-50 flex">
+          <aside className="w-72 max-w-[80%] h-full bg-sidebar-bg shadow-xl animate-drawer-in">
+            <SidebarContent
+              {...sidebarProps}
+              onShowAdmin={() => {
+                setShowConversations(false);
+                setShowAdminPanel(true);
+              }}
+              onShowScheduler={() => {
+                setShowConversations(false);
+                setShowScheduler(true);
+              }}
+              onLogout={handleLogout}
+              onCloseDrawer={() => setShowConversations(false)}
+            />
+          </aside>
+          <div
+            className="flex-1 bg-charcoal/40 backdrop-blur-sm"
+            onClick={() => setShowConversations(false)}
+          />
+        </div>
+      )}
+
+      {showAdminPanel && <AdminPanel onClose={() => setShowAdminPanel(false)} />}
+      {showScheduler && <ScheduledMessagesPanel onClose={() => setShowScheduler(false)} />}
 
-      {/* ── Main chat area ──────────────────────────────── */}
       <div className="flex-1 flex flex-col h-full overflow-hidden min-w-0">
-        {/* Mobile header */}
         <header className="md:hidden flex items-center justify-between px-4 py-3 bg-warm-white border-b border-sand-light/60">
           <div className="flex items-center gap-2">
             <img src={catIcon} alt="Simba" className="w-12 h-12" />
@@ -337,37 +205,17 @@ export const ChatScreen = ({ setAuthenticated }: ChatScreenProps) => {
               asksimba
             </h1>
           </div>
-          <div className="flex items-center gap-2">
-            <button
-              className="w-8 h-8 rounded-xl flex items-center justify-center text-warm-gray hover:text-charcoal hover:bg-cream-dark transition-all cursor-pointer"
-              onClick={() => setShowConversations((v) => !v)}
-            >
-              {showConversations ? <X size={16} /> : <Menu size={16} />}
-            </button>
-            <button
-              className="w-8 h-8 rounded-xl flex items-center justify-center text-warm-gray hover:text-charcoal hover:bg-cream-dark transition-all cursor-pointer"
-              onClick={handleLogout}
-            >
-              <LogOut size={15} />
-            </button>
-          </div>
+          <button
+            className="w-8 h-8 rounded-xl flex items-center justify-center text-warm-gray hover:text-charcoal hover:bg-cream-dark transition-all cursor-pointer"
+            onClick={() => setShowConversations(true)}
+            aria-label="Open menu"
+          >
+            <Menu size={16} />
+          </button>
         </header>
 
-        {messages.length === 0 ? (
-          /* ── Empty / homepage state ── */
+        {messages.length === 0 && !messagesLoading ? (
           <div className="flex-1 flex flex-col items-center justify-center px-4 gap-6">
-            {/* Mobile conversation drawer */}
-            {showConversations && (
-              <div className="md:hidden w-full max-w-2xl bg-warm-white rounded-2xl border border-sand-light p-3 shadow-sm">
-                <ConversationList
-                  conversations={conversations}
-                  onCreateNewConversation={handleCreateNewConversation}
-                  onSelectConversation={handleSelectConversation}
-                  selectedId={selectedConversation?.id}
-                  variant="light"
-                />
-              </div>
-            )}
             <div className="relative">
               <div className="absolute -inset-6 bg-amber-soft/20 rounded-full blur-3xl" />
               <img src={catIcon} alt="Simba" className="relative w-36 h-36" />
@@ -384,57 +232,116 @@ export const ChatScreen = ({ setAuthenticated }: ChatScreenProps) => {
                 handleQueryChange={handleQueryChange}
                 handleKeyDown={handleKeyDown}
                 handleQuestionSubmit={handleQuestionSubmit}
-                setSimbaMode={setSimbaMode}
+                simbaMode={simbaMode}
+                onToggleSimbaMode={handleToggleSimbaMode}
                 isLoading={isLoading}
+                onStop={stopGeneration}
                 pendingImage={pendingImage}
                 onImageSelect={handleImageSelect}
                 onClearImage={handleClearImage}
+                autoFocus
               />
             </div>
           </div>
         ) : (
-          /* ── Active chat state ── */
           <>
             <div className="flex-1 overflow-y-auto px-4 py-6">
-              <div className="max-w-2xl mx-auto flex flex-col gap-3">
-                {/* Mobile conversation drawer */}
-                {showConversations && (
-                  <div className="md:hidden mb-3 bg-warm-white rounded-2xl border border-sand-light p-3 shadow-sm">
-                    <ConversationList
-                      conversations={conversations}
-                      onCreateNewConversation={handleCreateNewConversation}
-                      onSelectConversation={handleSelectConversation}
-                      selectedId={selectedConversation?.id}
-                      variant="light"
-                    />
+              <div className="max-w-3xl mx-auto flex flex-col gap-6">
+                {messages.map((msg, index) => {
+                  // When the model has been thinking and content is now streaming,
+                  // render ThinkingBubble just before the streaming simba message
+                  // so it appears above the answer rather than below it.
+                  const showThinkingHere =
+                    streaming &&
+                    isLoading &&
+                    (thinking || thinkingText || thinkingDurationMs !== null) &&
+                    index === messages.length - 1 &&
+                    msg.speaker === "simba";
+
+                  const bubble =
+                    msg.speaker === "tool" ? (
+                      <ToolBubble key={index} text={msg.text} />
+                    ) : msg.speaker === "simba" ? (
+                      <AnswerBubble key={index} text={msg.text} />
+                    ) : (
+                      <QuestionBubble key={index} text={msg.text} image_key={msg.image_key} />
+                    );
+
+                  if (showThinkingHere) {
+                    return (
+                      <React.Fragment key={index}>
+                        <ThinkingBubble
+                          text={thinkingText}
+                          durationMs={thinkingDurationMs}
+                          active={thinking}
+                        />
+                        {bubble}
+                      </React.Fragment>
+                    );
+                  }
+                  return bubble;
+                })}
+
+                {/* ThinkingBubble before content arrives (no streaming message yet) */}
+                {isLoading && !streaming && (thinking || thinkingText || thinkingDurationMs !== null) && (
+                  <ThinkingBubble
+                    text={thinkingText}
+                    durationMs={thinkingDurationMs}
+                    active={thinking}
+                  />
+                )}
+
+                {((isLoading && !streaming && !thinking) || messagesLoading) && (
+                  <AnswerBubble text="" loading={true} />
+                )}
+
+                {error && (
+                  <div className="flex justify-center message-enter">
+                    <div className="inline-flex items-center gap-2 px-3 py-1.5 rounded-full bg-red-50 border border-red-200 text-xs text-red-600">
+                      <span>{error}</span>
+                      <button
+                        onClick={clearError}
+                        className="text-red-400 hover:text-red-600 transition-colors cursor-pointer"
+                        aria-label="Dismiss error"
+                      >
+                        <X size={13} />
+                      </button>
+                    </div>
                   </div>
                 )}
 
-                {messages.map((msg, index) => {
-                  if (msg.speaker === "tool")
-                    return <ToolBubble key={index} text={msg.text} />;
-                  if (msg.speaker === "simba")
-                    return <AnswerBubble key={index} text={msg.text} />;
-                  return <QuestionBubble key={index} text={msg.text} image_key={msg.image_key} />;
-                })}
+                {stalled && (
+                  <div className="flex justify-center message-enter">
+                    <div className="inline-flex items-center gap-2 px-3 py-1.5 rounded-full bg-red-50 border border-red-200 text-xs text-red-600">
+                      <span>Simba didn&apos;t respond in time.</span>
+                      <button
+                        onClick={retryStalled}
+                        className="font-medium underline underline-offset-2 hover:text-red-800 transition-colors cursor-pointer"
+                      >
+                        Retry
+                      </button>
+                    </div>
+                  </div>
+                )}
 
-                {isLoading && <AnswerBubble text="" loading={true} />}
                 <div ref={messagesEndRef} />
               </div>
             </div>
 
             <footer className="border-t border-sand-light/40 bg-cream">
-              <div className="max-w-2xl mx-auto px-4 py-3">
+              <div className="max-w-3xl mx-auto px-4 py-3">
                 <MessageInput
                   query={query}
                   handleQueryChange={handleQueryChange}
                   handleKeyDown={handleKeyDown}
                   handleQuestionSubmit={handleQuestionSubmit}
-                  setSimbaMode={setSimbaMode}
+                  simbaMode={simbaMode}
+                  onToggleSimbaMode={handleToggleSimbaMode}
                   isLoading={isLoading}
+                  onStop={stopGeneration}
                   pendingImage={pendingImage}
-                  onImageSelect={(file) => setPendingImage(file)}
-                  onClearImage={() => setPendingImage(null)}
+                  onImageSelect={handleImageSelect}
+                  onClearImage={handleClearImage}
                 />
               </div>
             </footer>

raggr-frontend/src/components/ConversationList.tsx

@@ -1,7 +1,6 @@
-import { useState, useEffect } from "react";
-import { Plus } from "lucide-react";
+import { useEffect, useRef, useState } from "react";
+import { Check, MoreHorizontal, Pencil, Plus, Trash2, X } from "lucide-react";
 import { cn } from "../lib/utils";
-import { conversationService } from "../api/conversationService";
 
 type Conversation = {
   title: string;
@@ -12,6 +11,8 @@ type ConversationProps = {
   conversations: Conversation[];
   onSelectConversation: (conversation: Conversation) => void;
   onCreateNewConversation: () => void;
+  onRenameConversation?: (id: string, title: string) => void;
+  onDeleteConversation?: (id: string) => void;
   selectedId?: string;
   variant?: "dark" | "light";
 };
@@ -20,41 +21,57 @@ export const ConversationList = ({
   conversations,
   onSelectConversation,
   onCreateNewConversation,
+  onRenameConversation,
+  onDeleteConversation,
   selectedId,
   variant = "dark",
 }: ConversationProps) => {
-  const [items, setItems] = useState(conversations);
+  const [menuOpenId, setMenuOpenId] = useState<string | null>(null);
+  const [editingId, setEditingId] = useState<string | null>(null);
+  const [editValue, setEditValue] = useState("");
+  const [confirmDeleteId, setConfirmDeleteId] = useState<string | null>(null);
+  const inputRef = useRef<HTMLInputElement>(null);
 
+  const isDark = variant === "dark";
+
+  // Close any open row menu when clicking elsewhere.
   useEffect(() => {
-    const load = async () => {
-      try {
-        let fetched = await conversationService.getAllConversations();
-        if (fetched.length === 0) {
-          await conversationService.createConversation();
-          fetched = await conversationService.getAllConversations();
-        }
-        setItems(fetched.map((c) => ({ id: c.id, title: c.name })));
-      } catch (err) {
-        console.error("Failed to load conversations:", err);
-      }
+    if (!menuOpenId && !confirmDeleteId) return;
+    const close = () => {
+      setMenuOpenId(null);
+      setConfirmDeleteId(null);
     };
-    load();
-  }, []);
+    window.addEventListener("click", close);
+    return () => window.removeEventListener("click", close);
+  }, [menuOpenId, confirmDeleteId]);
 
-  // Keep in sync when parent updates conversations
   useEffect(() => {
-    setItems(conversations);
-  }, [conversations]);
+    if (editingId) inputRef.current?.focus();
+  }, [editingId]);
+
+  const startRename = (conv: Conversation) => {
+    setMenuOpenId(null);
+    setEditingId(conv.id);
+    setEditValue(conv.title);
+  };
+
+  const commitRename = () => {
+    if (editingId && editValue.trim()) {
+      onRenameConversation?.(editingId, editValue.trim());
+    }
+    setEditingId(null);
+  };
+
+  const hasActions = Boolean(onRenameConversation || onDeleteConversation);
 
   return (
     <div className="flex flex-col gap-1">
-      {/* New thread button */}
       <button
         onClick={onCreateNewConversation}
         className={cn(
           "flex items-center gap-2 w-full px-3 py-2 rounded-xl",
           "text-sm transition-all duration-150 cursor-pointer mb-1",
-          variant === "dark"
+          isDark
             ? "text-cream/60 hover:text-cream hover:bg-white/8"
             : "text-warm-gray hover:text-charcoal hover:bg-cream-dark",
         )}
@@ -63,27 +80,150 @@ export const ConversationList = ({
         <span>New thread</span>
       </button>
 
-      {/* Conversation items */}
-      {items.map((conv) => {
+      {conversations.map((conv) => {
         const isActive = conv.id === selectedId;
+        const isEditing = editingId === conv.id;
+
+        if (isEditing) {
+          return (
+            <div
+              key={conv.id}
+              className={cn(
+                "flex items-center gap-1 px-1.5 py-1 rounded-xl",
+                isDark ? "bg-white/12" : "bg-cream-dark",
+              )}
+            >
+              <input
+                ref={inputRef}
+                value={editValue}
+                onChange={(e) => setEditValue(e.target.value)}
+                onKeyDown={(e) => {
+                  if (e.key === "Enter") commitRename();
+                  if (e.key === "Escape") setEditingId(null);
+                }}
+                className={cn(
+                  "flex-1 min-w-0 bg-transparent px-1.5 py-1 text-sm rounded-lg",
+                  "focus:outline-none",
+                  isDark
+                    ? "text-cream placeholder:text-cream/40"
+                    : "text-charcoal placeholder:text-warm-gray/50",
+                )}
+              />
+              <button
+                onClick={commitRename}
+                className={cn(
+                  "w-6 h-6 rounded-lg flex items-center justify-center shrink-0 cursor-pointer transition-colors",
+                  isDark
+                    ? "text-cream/60 hover:text-cream hover:bg-white/10"
+                    : "text-warm-gray hover:text-charcoal hover:bg-sand-light",
+                )}
+              >
+                <Check size={14} />
+              </button>
+              <button
+                onClick={() => setEditingId(null)}
+                className={cn(
+                  "w-6 h-6 rounded-lg flex items-center justify-center shrink-0 cursor-pointer transition-colors",
+                  isDark
+                    ? "text-cream/60 hover:text-cream hover:bg-white/10"
+                    : "text-warm-gray hover:text-charcoal hover:bg-sand-light",
+                )}
+              >
+                <X size={14} />
+              </button>
+            </div>
+          );
+        }
+
         return (
-          <button
-            key={conv.id}
-            onClick={() => onSelectConversation(conv)}
-            className={cn(
-              "w-full px-3 py-2 rounded-xl text-left",
-              "text-sm truncate transition-all duration-150 cursor-pointer",
-              variant === "dark"
-                ? isActive
-                  ? "bg-white/12 text-cream font-medium"
-                  : "text-cream/60 hover:text-cream hover:bg-white/8"
-                : isActive
-                  ? "bg-cream-dark text-charcoal font-medium"
-                  : "text-warm-gray hover:text-charcoal hover:bg-cream-dark",
+          <div key={conv.id} className="group relative flex items-center">
+            <button
+              onClick={() => onSelectConversation(conv)}
+              className={cn(
+                "flex-1 min-w-0 px-3 py-2 rounded-xl text-left",
+                "text-sm truncate transition-all duration-150 cursor-pointer",
+                hasActions && "pr-8",
+                isDark
+                  ? isActive
+                    ? "bg-white/12 text-cream font-medium"
+                    : "text-cream/60 hover:text-cream hover:bg-white/8"
+                  : isActive
+                    ? "bg-cream-dark text-charcoal font-medium"
+                    : "text-warm-gray hover:text-charcoal hover:bg-cream-dark",
+              )}
+            >
+              {conv.title}
+            </button>
+
+            {hasActions && (
+              <button
+                onClick={(e) => {
+                  e.stopPropagation();
+                  setConfirmDeleteId(null);
+                  setMenuOpenId((prev) => (prev === conv.id ? null : conv.id));
+                }}
+                className={cn(
+                  "absolute right-1.5 w-6 h-6 rounded-lg flex items-center justify-center cursor-pointer transition-all",
+                  "opacity-0 group-hover:opacity-100 focus:opacity-100",
+                  menuOpenId === conv.id && "opacity-100",
+                  isDark
+                    ? "text-cream/50 hover:text-cream hover:bg-white/10"
+                    : "text-warm-gray hover:text-charcoal hover:bg-sand-light",
+                )}
+              >
+                <MoreHorizontal size={15} />
+              </button>
             )}
-          >
-            {conv.title}
-          </button>
+
+            {menuOpenId === conv.id && (
+              <div
+                onClick={(e) => e.stopPropagation()}
+                className={cn(
+                  "absolute right-1.5 top-9 z-20 w-36 rounded-xl p-1 shadow-lg",
+                  isDark
+                    ? "bg-sidebar-bg border border-white/10"
+                    : "bg-warm-white border border-sand-light",
+                )}
+              >
+                {onRenameConversation && (
+                  <button
+                    onClick={() => startRename(conv)}
+                    className={cn(
+                      "flex items-center gap-2 w-full px-2.5 py-1.5 rounded-lg text-sm cursor-pointer transition-colors",
+                      isDark
+                        ? "text-cream/70 hover:text-cream hover:bg-white/10"
+                        : "text-warm-gray hover:text-charcoal hover:bg-cream-dark",
+                    )}
+                  >
+                    <Pencil size={13} />
+                    <span>Rename</span>
+                  </button>
+                )}
+                {onDeleteConversation && (
+                  <button
+                    onClick={() => {
+                      if (confirmDeleteId === conv.id) {
+                        onDeleteConversation(conv.id);
+                        setMenuOpenId(null);
+                        setConfirmDeleteId(null);
+                      } else {
+                        setConfirmDeleteId(conv.id);
+                      }
+                    }}
+                    className={cn(
+                      "flex items-center gap-2 w-full px-2.5 py-1.5 rounded-lg text-sm cursor-pointer transition-colors",
+                      "text-red-400 hover:bg-red-500/10",
+                    )}
+                  >
+                    <Trash2 size={13} />
+                    <span>
+                      {confirmDeleteId === conv.id ? "Confirm delete" : "Delete"}
+                    </span>
+                  </button>
+                )}
+              </div>
+            )}
+          </div>
         );
       })}
     </div>

raggr-frontend/src/components/ConversationMenu.tsx

@@ -1,24 +0,0 @@
-type Conversation = {
-  title: string;
-  id: string;
-};
-
-type ConversationMenuProps = {
-  conversations: Conversation[];
-};
-
-export const ConversationMenu = ({ conversations }: ConversationMenuProps) => {
-  return (
-    <div className="absolute bg-white w-md rounded-md shadow-xl m-4 p-4">
-      <p className="py-2 px-4 rounded-md w-full text-xl font-bold">askSimba!</p>
-      {conversations.map((conversation) => (
-        <p
-          key={conversation.id}
-          className="py-2 px-4 rounded-md hover:bg-stone-200 w-full text-xl font-bold cursor-pointer"
-        >
-          {conversation.title}
-        </p>
-      ))}
-    </div>
-  );
-};

raggr-frontend/src/components/ConversationsPage.tsx

@@ -0,0 +1,94 @@
+import { useCallback } from "react";
+import { useNavigate } from "react-router-dom";
+import { ArrowLeft, Search } from "lucide-react";
+import { ConversationList } from "./ConversationList";
+import { useConversationBrowser } from "../hooks/useConversationBrowser";
+import type { Conversation } from "../hooks/useConversations";
+import { Input } from "./ui/input";
+import catIcon from "../assets/cat.png";
+
+export const ConversationsPage = () => {
+  const navigate = useNavigate();
+  const {
+    items,
+    search,
+    setSearch,
+    hasMore,
+    loading,
+    loadMore,
+    renameConversation,
+    deleteConversation,
+  } = useConversationBrowser();
+
+  const handleSelect = useCallback(
+    (conversation: Conversation) => navigate(`/c/${conversation.id}`),
+    [navigate],
+  );
+
+  const handleCreateNew = useCallback(() => navigate("/"), [navigate]);
+
+  return (
+    <div className="h-screen h-[100dvh] flex flex-col bg-cream overflow-hidden">
+      <header className="flex items-center gap-3 px-4 py-3 bg-warm-white border-b border-sand-light/60">
+        <button
+          onClick={() => navigate(-1)}
+          className="w-8 h-8 rounded-xl flex items-center justify-center text-warm-gray hover:text-charcoal hover:bg-cream-dark transition-all cursor-pointer"
+          aria-label="Back"
+        >
+          <ArrowLeft size={16} />
+        </button>
+        <img src={catIcon} alt="Simba" className="w-10 h-10" />
+        <h1
+          className="text-base font-bold text-charcoal"
+          style={{ fontFamily: "var(--font-display)" }}
+        >
+          All conversations
+        </h1>
+      </header>
+
+      <div className="flex-1 overflow-y-auto">
+        <div className="max-w-2xl mx-auto px-4 py-6 flex flex-col gap-4">
+          <div className="relative">
+            <Search
+              size={15}
+              className="absolute left-3 top-1/2 -translate-y-1/2 text-warm-gray/60"
+            />
+            <Input
+              value={search}
+              onChange={(e) => setSearch(e.target.value)}
+              placeholder="Search conversations..."
+              className="h-10 pl-9"
+            />
+          </div>
+
+          <div className="bg-warm-white rounded-2xl border border-sand-light p-3 shadow-sm">
+            <ConversationList
+              conversations={items}
+              onCreateNewConversation={handleCreateNew}
+              onSelectConversation={handleSelect}
+              onRenameConversation={renameConversation}
+              onDeleteConversation={deleteConversation}
+              variant="light"
+            />
+
+            {items.length === 0 && !loading && (
+              <p className="text-center text-sm text-warm-gray/70 py-6">
+                {search ? "No conversations match your search." : "No conversations yet."}
+              </p>
+            )}
+          </div>
+
+          {hasMore && (
+            <button
+              onClick={loadMore}
+              disabled={loading}
+              className="self-center px-4 py-2 rounded-xl text-sm text-warm-gray hover:text-charcoal hover:bg-cream-dark transition-all cursor-pointer disabled:opacity-50 disabled:cursor-not-allowed"
+            >
+              {loading ? "Loading..." : "Load more"}
+            </button>
+          )}
+        </div>
+      </div>
+    </div>
+  );
+};

raggr-frontend/src/components/LoginScreen.tsx

@@ -1,66 +1,19 @@
-import { useState, useEffect } from "react";
-import { userService } from "../api/userService";
-import { oidcService } from "../api/oidcService";
 import catIcon from "../assets/cat.png";
 import { cn } from "../lib/utils";
+import { useOIDCAuth } from "../hooks/useOIDCAuth";
 
 type LoginScreenProps = {
   setAuthenticated: (isAuth: boolean) => void;
 };
 
 export const LoginScreen = ({ setAuthenticated }: LoginScreenProps) => {
-  const [error, setError] = useState<string>("");
-  const [isChecking, setIsChecking] = useState<boolean>(true);
-  const [isLoggingIn, setIsLoggingIn] = useState<boolean>(false);
-
-  useEffect(() => {
-    const initAuth = async () => {
-      const callbackParams = oidcService.getCallbackParamsFromURL();
-      if (callbackParams) {
-        try {
-          setIsLoggingIn(true);
-          const result = await oidcService.handleCallback(
-            callbackParams.code,
-            callbackParams.state,
-          );
-          localStorage.setItem("access_token", result.access_token);
-          localStorage.setItem("refresh_token", result.refresh_token);
-          oidcService.clearCallbackParams();
-          setAuthenticated(true);
-          setIsChecking(false);
-          return;
-        } catch (err) {
-          console.error("OIDC callback error:", err);
-          setError("Login failed. Please try again.");
-          oidcService.clearCallbackParams();
-          setIsLoggingIn(false);
-          setIsChecking(false);
-          return;
-        }
-      }
-      const isValid = await userService.validateToken();
-      if (isValid) setAuthenticated(true);
-      setIsChecking(false);
-    };
-    initAuth();
-  }, [setAuthenticated]);
-
-  const handleOIDCLogin = async () => {
-    try {
-      setIsLoggingIn(true);
-      setError("");
-      const authUrl = await oidcService.initiateLogin();
-      window.location.href = authUrl;
-    } catch {
-      setError("Failed to initiate login. Please try again.");
-      setIsLoggingIn(false);
-    }
-  };
+  const { isChecking, isLoggingIn, error, handleLogin } = useOIDCAuth({
+    setAuthenticated,
+  });
 
   if (isChecking || isLoggingIn) {
     return (
       <div className="h-screen flex flex-col items-center justify-center bg-cream gap-4">
-        {/* Subtle dot grid */}
         <div
           className="fixed inset-0 pointer-events-none opacity-[0.035]"
           style={{
@@ -85,7 +38,6 @@ export const LoginScreen = ({ setAuthenticated }: LoginScreenProps) => {
 
   return (
     <div className="h-screen bg-cream flex items-center justify-center p-4 relative overflow-hidden">
-      {/* Background dot texture */}
       <div
         className="fixed inset-0 pointer-events-none opacity-[0.04]"
         style={{
@@ -94,12 +46,10 @@ export const LoginScreen = ({ setAuthenticated }: LoginScreenProps) => {
         }}
       />
 
-      {/* Decorative background blobs */}
       <div className="absolute top-1/4 -left-20 w-72 h-72 rounded-full bg-leaf-pale/60 blur-3xl pointer-events-none" />
       <div className="absolute bottom-1/4 -right-20 w-64 h-64 rounded-full bg-amber-pale/70 blur-3xl pointer-events-none" />
 
       <div className="relative w-full max-w-sm">
-        {/* Branding */}
         <div className="flex flex-col items-center mb-8">
           <div className="relative mb-5">
             <div className="absolute -inset-5 bg-amber-soft/30 rounded-full blur-2xl" />
@@ -120,7 +70,6 @@ export const LoginScreen = ({ setAuthenticated }: LoginScreenProps) => {
           </p>
         </div>
 
-        {/* Card */}
         <div
           className={cn(
             "bg-warm-white rounded-3xl border border-sand-light",
@@ -138,7 +87,7 @@ export const LoginScreen = ({ setAuthenticated }: LoginScreenProps) => {
           </p>
 
           <button
-            onClick={handleOIDCLogin}
+            onClick={handleLogin}
             disabled={isLoggingIn}
             className={cn(
               "w-full py-3.5 px-4 rounded-2xl text-sm font-semibold tracking-wide",
@@ -154,7 +103,7 @@ export const LoginScreen = ({ setAuthenticated }: LoginScreenProps) => {
         </div>
 
         <p className="text-center text-sand mt-5 text-xs tracking-widest select-none">
-          ✦ meow ✦
+          * meow *
         </p>
       </div>
     </div>

raggr-frontend/src/components/MessageInput.tsx

@@ -1,160 +1,204 @@
-import React, { useEffect, useMemo, useRef, useState } from "react";
-import { ArrowUp, ImagePlus, X } from "lucide-react";
+import React, { useEffect, useMemo, useRef } from "react";
+import { ArrowUp, ImagePlus, Square, X } from "lucide-react";
 import { cn } from "../lib/utils";
 import { Textarea } from "./ui/textarea";
 
 type MessageInputProps = {
   handleQueryChange: (event: React.ChangeEvent<HTMLTextAreaElement>) => void;
-  handleKeyDown: (event: React.ChangeEvent<HTMLTextAreaElement>) => void;
+  handleKeyDown: (event: React.KeyboardEvent<HTMLTextAreaElement>) => void;
   handleQuestionSubmit: () => void;
-  setSimbaMode: (val: boolean) => void;
+  simbaMode: boolean;
+  onToggleSimbaMode: () => void;
   query: string;
   isLoading: boolean;
+  onStop: () => void;
   pendingImage: File | null;
   onImageSelect: (file: File) => void;
   onClearImage: () => void;
+  autoFocus?: boolean;
 };
 
-export const MessageInput = React.memo(({
-  query,
-  handleKeyDown,
-  handleQueryChange,
-  handleQuestionSubmit,
-  setSimbaMode,
-  isLoading,
-  pendingImage,
-  onImageSelect,
-  onClearImage,
-}: MessageInputProps) => {
-  const [simbaMode, setLocalSimbaMode] = useState(false);
-  const fileInputRef = useRef<HTMLInputElement>(null);
+export const MessageInput = React.memo(
+  ({
+    query,
+    handleKeyDown,
+    handleQueryChange,
+    handleQuestionSubmit,
+    simbaMode,
+    onToggleSimbaMode,
+    isLoading,
+    onStop,
+    pendingImage,
+    onImageSelect,
+    onClearImage,
+    autoFocus,
+  }: MessageInputProps) => {
+    const fileInputRef = useRef<HTMLInputElement>(null);
+    const textareaRef = useRef<HTMLTextAreaElement>(null);
 
-  // Create blob URL once per file, revoke on cleanup
-  const previewUrl = useMemo(
-    () => (pendingImage ? URL.createObjectURL(pendingImage) : null),
-    [pendingImage],
-  );
+    // Create blob URL once per file, revoke on cleanup
+    const previewUrl = useMemo(
+      () => (pendingImage ? URL.createObjectURL(pendingImage) : null),
+      [pendingImage],
+    );
 
-  useEffect(() => {
-    return () => {
-      if (previewUrl) URL.revokeObjectURL(previewUrl);
+    useEffect(() => {
+      return () => {
+        if (previewUrl) URL.revokeObjectURL(previewUrl);
+      };
+    }, [previewUrl]);
+
+    // Auto-grow the textarea to fit its content (capped by max-height in CSS).
+    useEffect(() => {
+      const el = textareaRef.current;
+      if (!el) return;
+      el.style.height = "auto";
+      el.style.height = `${el.scrollHeight}px`;
+    }, [query]);
+
+    const handleFileChange = (e: React.ChangeEvent<HTMLInputElement>) => {
+      const file = e.target.files?.[0];
+      if (file) {
+        onImageSelect(file);
+      }
+      // Reset so the same file can be re-selected
+      e.target.value = "";
     };
-  }, [previewUrl]);
 
-  const toggleSimbaMode = () => {
-    const next = !simbaMode;
-    setLocalSimbaMode(next);
-    setSimbaMode(next);
-  };
+    const handlePaste = (e: React.ClipboardEvent<HTMLTextAreaElement>) => {
+      if (isLoading) return;
+      const items = e.clipboardData?.items;
+      if (!items) return;
+      for (const item of items) {
+        if (item.type.startsWith("image/")) {
+          const file = item.getAsFile();
+          if (file) {
+            e.preventDefault();
+            onImageSelect(file);
+            return;
+          }
+        }
+      }
+    };
 
-  const handleFileChange = (e: React.ChangeEvent<HTMLInputElement>) => {
-    const file = e.target.files?.[0];
-    if (file) {
-      onImageSelect(file);
-    }
-    // Reset so the same file can be re-selected
-    e.target.value = "";
-  };
+    const canSend = !isLoading && Boolean(query.trim() || pendingImage);
 
-  const canSend = !isLoading && (query.trim() || pendingImage);
+    return (
+      <div
+        className={cn(
+          "rounded-2xl bg-warm-white border border-sand shadow-md shadow-sand/30",
+          "transition-shadow duration-200 focus-within:shadow-lg focus-within:shadow-amber-soft/20",
+          "focus-within:border-amber-soft/60",
+        )}
+      >
+        {/* Image preview */}
+        {pendingImage && (
+          <div className="px-3 pt-3">
+            <div className="relative inline-block">
+              <img
+                src={previewUrl!}
+                alt="Pending upload"
+                className="h-20 rounded-lg object-cover border border-sand"
+              />
+              <button
+                type="button"
+                onClick={onClearImage}
+                className="absolute -top-1.5 -right-1.5 w-5 h-5 rounded-full bg-charcoal text-white flex items-center justify-center hover:bg-charcoal/80 transition-colors cursor-pointer"
+              >
+                <X size={12} />
+              </button>
+            </div>
+          </div>
+        )}
 
-  return (
-    <div
-      className={cn(
-        "rounded-2xl bg-warm-white border border-sand shadow-md shadow-sand/30",
-        "transition-shadow duration-200 focus-within:shadow-lg focus-within:shadow-amber-soft/20",
-        "focus-within:border-amber-soft/60",
-      )}
-    >
-      {/* Image preview */}
-      {pendingImage && (
-        <div className="px-3 pt-3">
-          <div className="relative inline-block">
-            <img
-              src={previewUrl!}
-              alt="Pending upload"
-              className="h-20 rounded-lg object-cover border border-sand"
-            />
+        {/* Textarea */}
+        <Textarea
+          ref={textareaRef}
+          onChange={handleQueryChange}
+          onKeyDown={handleKeyDown}
+          onPaste={handlePaste}
+          value={query}
+          rows={2}
+          placeholder="Ask Simba anything..."
+          className="min-h-[60px] max-h-40 overflow-y-auto"
+          autoFocus={autoFocus}
+        />
+
+        {/* Hidden file input */}
+        <input
+          ref={fileInputRef}
+          type="file"
+          accept="image/*"
+          onChange={handleFileChange}
+          className="hidden"
+        />
+
+        {/* Bottom toolbar */}
+        <div className="flex items-center justify-between px-3 pb-2.5 pt-1">
+          <div className="flex items-center gap-3">
+            {/* Simba mode toggle */}
             <button
               type="button"
-              onClick={onClearImage}
-              className="absolute -top-1.5 -right-1.5 w-5 h-5 rounded-full bg-charcoal text-white flex items-center justify-center hover:bg-charcoal/80 transition-colors cursor-pointer"
+              onClick={onToggleSimbaMode}
+              className="flex items-center gap-2 group cursor-pointer select-none"
             >
-              <X size={12} />
+              <div className={cn("toggle-track", simbaMode && "checked")}>
+                <div className="toggle-thumb" />
+              </div>
+              <span className="text-xs text-warm-gray group-hover:text-charcoal transition-colors">
+                simba mode
+              </span>
+            </button>
+
+            {/* Image attach button */}
+            <button
+              type="button"
+              onClick={() => fileInputRef.current?.click()}
+              disabled={isLoading}
+              className={cn(
+                "w-7 h-7 rounded-lg flex items-center justify-center transition-all cursor-pointer",
+                isLoading
+                  ? "text-warm-gray/40 cursor-not-allowed"
+                  : "text-warm-gray hover:text-charcoal hover:bg-cream-dark",
+              )}
+            >
+              <ImagePlus size={16} />
             </button>
           </div>
-        </div>
-      )}
 
-      {/* Textarea */}
-      <Textarea
-        onChange={handleQueryChange}
-        onKeyDown={handleKeyDown}
-        value={query}
-        rows={2}
-        placeholder="Ask Simba anything..."
-        className="min-h-[60px] max-h-40"
-      />
-
-      {/* Hidden file input */}
-      <input
-        ref={fileInputRef}
-        type="file"
-        accept="image/*"
-        onChange={handleFileChange}
-        className="hidden"
-      />
-
-      {/* Bottom toolbar */}
-      <div className="flex items-center justify-between px-3 pb-2.5 pt-1">
-        <div className="flex items-center gap-3">
-          {/* Simba mode toggle */}
-          <button
-            type="button"
-            onClick={toggleSimbaMode}
-            className="flex items-center gap-2 group cursor-pointer select-none"
-          >
-            <div className={cn("toggle-track", simbaMode && "checked")}>
-              <div className="toggle-thumb" />
-            </div>
-            <span className="text-xs text-warm-gray group-hover:text-charcoal transition-colors">
-              simba mode
-            </span>
-          </button>
-
-          {/* Image attach button */}
-          <button
-            type="button"
-            onClick={() => fileInputRef.current?.click()}
-            disabled={isLoading}
-            className={cn(
-              "w-7 h-7 rounded-lg flex items-center justify-center transition-all cursor-pointer",
-              isLoading
-                ? "text-warm-gray/40 cursor-not-allowed"
-                : "text-warm-gray hover:text-charcoal hover:bg-cream-dark",
-            )}
-          >
-            <ImagePlus size={16} />
-          </button>
-        </div>
-
-        {/* Send button */}
-        <button
-          type="submit"
-          onClick={handleQuestionSubmit}
-          disabled={!canSend}
-          className={cn(
-            "w-8 h-8 rounded-full flex items-center justify-center",
-            "transition-all duration-200 cursor-pointer",
-            "shadow-sm",
-            !canSend
-              ? "bg-sand text-warm-gray/50 cursor-not-allowed shadow-none"
-              : "bg-amber-glow text-white hover:bg-amber-dark hover:shadow-md hover:shadow-amber-glow/30 active:scale-95",
+          {/* Send / Stop button */}
+          {isLoading ? (
+            <button
+              type="button"
+              onClick={onStop}
+              aria-label="Stop generating"
+              className={cn(
+                "w-8 h-8 rounded-full flex items-center justify-center shadow-sm",
+                "bg-charcoal text-white transition-all duration-200 cursor-pointer",
+                "hover:bg-charcoal/85 active:scale-95",
+              )}
+            >
+              <Square size={13} strokeWidth={2.5} fill="currentColor" />
+            </button>
+          ) : (
+            <button
+              type="submit"
+              onClick={handleQuestionSubmit}
+              disabled={!canSend}
+              aria-label="Send message"
+              className={cn(
+                "w-8 h-8 rounded-full flex items-center justify-center",
+                "transition-all duration-200 cursor-pointer shadow-sm",
+                !canSend
+                  ? "bg-sand text-warm-gray/50 cursor-not-allowed shadow-none"
+                  : "bg-amber-glow text-white hover:bg-amber-dark hover:shadow-md hover:shadow-amber-glow/30 active:scale-95",
+              )}
+            >
+              <ArrowUp size={15} strokeWidth={2.5} />
+            </button>
           )}
-        >
-          <ArrowUp size={15} strokeWidth={2.5} />
-        </button>
+        </div>
       </div>
-    </div>
-  );
-});
+    );
+  },
+);

raggr-frontend/src/components/QuestionBubble.tsx

@@ -1,26 +1,14 @@
-import { useEffect, useState } from "react";
+import React from "react";
 import { cn } from "../lib/utils";
-import { conversationService } from "../api/conversationService";
+import { usePresignedUrl } from "../hooks/usePresignedUrl";
 
 type QuestionBubbleProps = {
   text: string;
   image_key?: string | null;
 };
 
-export const QuestionBubble = ({ text, image_key }: QuestionBubbleProps) => {
-  const [imageUrl, setImageUrl] = useState<string | null>(null);
-  const [imageError, setImageError] = useState(false);
-
-  useEffect(() => {
-    if (!image_key) return;
-    conversationService
-      .getPresignedImageUrl(image_key)
-      .then(setImageUrl)
-      .catch((err) => {
-        console.error("Failed to load image:", err);
-        setImageError(true);
-      });
-  }, [image_key]);
+export const QuestionBubble = React.memo(({ text, image_key }: QuestionBubbleProps) => {
+  const { imageUrl, imageError } = usePresignedUrl(image_key);
 
   return (
     <div className="flex justify-end message-enter">
@@ -34,7 +22,6 @@ export const QuestionBubble = ({ text, image_key }: QuestionBubbleProps) => {
       >
         {imageError && (
           <div className="flex items-center gap-2 text-xs text-charcoal/50 bg-charcoal/5 rounded-xl px-3 py-2 mb-2">
-            <span>🖼️</span>
             <span>Image failed to load</span>
           </div>
         )}
@@ -49,4 +36,4 @@ export const QuestionBubble = ({ text, image_key }: QuestionBubbleProps) => {
       </div>
     </div>
   );
-};
+});