diff --git a/README.md b/README.md
index 7440242..0d8c678 100644
--- a/README.md
+++ b/README.md
@@ -2,11 +2,47 @@
 
 Make any microservice have a GraphQL implementation.
 
+[![CI](https://github.com/charles2ke/GraphQL/actions/workflows/ci.yml/badge.svg)](https://github.com/charles2ke/GraphQL/actions/workflows/ci.yml)
+[![Deploy website to GitHub Pages](https://github.com/charles2ke/GraphQL/actions/workflows/deploy-pages.yml/badge.svg)](https://github.com/charles2ke/GraphQL/actions/workflows/deploy-pages.yml)
+[![Node.js 20+](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](https://nodejs.org/)
+[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
+
 **Live website: <https://charles2ke.github.io/GraphQL/>**
 
 This repository contains a minimal, working backend service that exposes a GraphQL
-API for a small `User` / `Post` domain. It uses in-memory storage, so it runs from a
-clean checkout without any database or other external dependency.
+API for a small `User` / `Post` domain, plus an optional finance surface that
+aggregates three upstream domains. It uses in-memory storage and mock connectors,
+so it runs from a clean checkout without any database or other external
+dependency.
+
+## Quick start
+
+```bash
+git clone https://github.com/charles2ke/GraphQL.git
+cd GraphQL
+npm install
+npm start          # http://localhost:4000/graphql
+npm test           # node:test suite
+```
+
+Open <http://localhost:4000/graphql> in a browser to explore the schema in the
+Apollo Sandbox, or jump to [Example queries](#example-queries).
+
+## Contents
+
+- [Stack](#stack)
+- [Project structure](#project-structure)
+- [Installation and running locally](#installation-and-running-locally)
+- [Learning website](#learning-website)
+- [Tests](#tests)
+- [Continuous integration](#continuous-integration)
+- [API](#api)
+- [Streaming](#streaming)
+- [CORS](#cors)
+- [Excel export](#excel-export)
+- [Finance cluster integration](#finance-cluster-integration)
+- [Notes](#notes)
+- [Security and license](#security-and-license)
 
 ## Stack
 
@@ -19,21 +55,29 @@ clean checkout without any database or other external dependency.
 
 ```
 src/
-  index.js         # HTTP bootstrap: Express app + /graphql endpoint
+  index.js         # HTTP bootstrap: Express app + /graphql, /export, /graphql/stream
   server.js        # Apollo Server factory (reused by the tests)
   schema.js        # GraphQL type definitions and executable schema factory
   resolvers.js     # Query / Mutation / Subscription / field resolvers
-  config/finance.js # Environment-driven finance connector config
-  connectors/      # Replaceable OpenTrading, Portfolio-Watcher, tax-break adapters
+  cache/index.js   # Pluggable TTL cache (memory, file, shared provider)
+  config/          # Environment-driven finance and CORS configuration
+  connectors/      # OpenTrading, Portfolio-Watcher, tax-break adapters + HTTP client
   data/store.js    # In-memory data store with seed data
   domain/finance.js # Canonical finance models and normalization helpers
   export/          # Excel (.xlsx) writer, dataset registry, and /export routes
+  observability/   # Structured logging, metrics, error classification, Apollo plugin
   services/financeService.js # Finance aggregation, caching, and error handling
   streaming/       # In-process pub/sub and the SSE streaming endpoint
+  validation/financeArgs.js  # Shared finance argument validation
 test/
-  graphql.test.js  # API tests executed against the schema
-  export.test.js   # Excel export writer, dataset, and route tests
-  streaming.test.js # Pub/sub and Server-Sent Events streaming tests
+  graphql.test.js      # API tests executed against the schema
+  finance.test.js      # Finance service, filtering, and pagination tests
+  connectors.test.js   # Connector selection and HTTP client tests
+  cors.test.js         # CORS allow-list tests
+  export.test.js       # Excel export writer, dataset, and route tests
+  observability.test.js # Logging, metrics, and error classification tests
+  resilience.test.js   # Timeout, retry, and partial-failure tests
+  streaming.test.js    # Pub/sub and Server-Sent Events streaming tests
 website/
   src/App.jsx      # Learning site: primer, tips, API Explorer
   src/backendSamples.js  # GraphQL server samples in 10 backend languages
@@ -43,17 +87,12 @@ website/
   deploy-pages.yml # Builds website/ and publishes it to GitHub Pages
 ```
 
-## Installation
+## Installation and running locally
 
 ```bash
 git clone https://github.com/charles2ke/GraphQL.git
 cd GraphQL
 npm install
-```
-
-## Running locally
-
-```bash
 npm start          # or: npm run dev  (restarts on file changes)
 ```
 
@@ -124,9 +163,210 @@ every pull request, and on demand from the Actions tab. It has two jobs:
 
 Runs are grouped per branch and superseded runs are cancelled automatically.
 
-## Finance Cluster Integration (Priority 1)
+## API
+
+| Type | Operation | Description |
+| --- | --- | --- |
+| Query | `users` | List all users |
+| Query | `user(id: ID!)` | Fetch a single user, `null` when unknown |
+| Query | `posts` | List all posts |
+| Query | `post(id: ID!)` | Fetch a single post, `null` when unknown |
+| Query | `portfolioOverview(accountId, from, to, limit, offset)` | Fetch finance accounts, positions, snapshots, and P/L |
+| Query | `tradeHistory(accountId, symbol, side, status, from, to, limit, offset)` | Fetch trades/orders enriched with tax events |
+| Query | `taxEstimate(taxYear, accountId, symbol, from, to, limit, offset)` | Estimate tax from tax-relevant trading activity |
+| Mutation | `createUser(name, email)` | Create a user |
+| Mutation | `createPost(title, content, authorId)` | Create a post for an existing user |
+| Subscription | `userCreated` | Streams every newly created user |
+| Subscription | `postCreated(authorId)` | Streams new posts, optionally for one author |
+
+The finance operations are documented in detail under
+[Finance cluster integration](#finance-cluster-integration); subscriptions are
+delivered over SSE, see [Streaming](#streaming).
+
+### Example queries
+
+List users with their posts:
+
+```graphql
+query Users {
+  users {
+    id
+    name
+    email
+    posts {
+      id
+      title
+    }
+  }
+}
+```
+
+Fetch one user:
+
+```graphql
+query User {
+  user(id: "1") {
+    name
+    email
+  }
+}
+```
+
+List posts with their author:
+
+```graphql
+query Posts {
+  posts {
+    id
+    title
+    content
+    author {
+      id
+      name
+    }
+  }
+}
+```
+
+### Example mutations
+
+```graphql
+mutation CreateUser {
+  createUser(name: "Grace Hopper", email: "grace@example.com") {
+    id
+    name
+  }
+}
+```
+
+```graphql
+mutation CreatePost {
+  createPost(title: "Nanoseconds", content: "A talk about wire lengths.", authorId: "1") {
+    id
+    title
+    author {
+      name
+    }
+  }
+}
+```
+
+Creating a post for an unknown `authorId` returns a `BAD_USER_INPUT` error.
+
+### With curl
+
+```bash
+curl http://localhost:4000/graphql \
+  -H 'Content-Type: application/json' \
+  -d '{"query":"{ users { id name posts { title } } }"}'
+```
+
+## Streaming
+
+Subscriptions can be streamed over Server-Sent Events at `POST /graphql/stream`
+or `GET /graphql/stream`. **`GET` is read-only streaming**: it only accepts `query`
+and `subscription` operations, taken from plain `query`/`variables`/
+`operationName` query-string parameters, and is therefore safe to treat as a
+"simple" cross-origin request. This is *not* the same payload contract as
+`/graphql` — **mutations sent with `GET` are rejected with `405 Method Not
+Allowed`** so a mutating operation can never be triggered from a plain
+cross-site navigation or `<img>`/`<script>` style request.
+
+**Mutations must be sent with `POST`**, using a request shape that a simple
+cross-origin form or link cannot forge: a `Content-Type` such as
+`application/json` (which is not a CORS "simple" content type) and/or a
+custom header (e.g. `X-Requested-With`), matching the CSRF-prevention shape
+that Apollo Server enforces by default on `/graphql`. Requests that omit
+this shape should be rejected before they reach resolvers.
+
+SSE keeps the transport plain HTTP — no WebSocket upgrade or extra service is
+required.
+
+```bash
+# Stream new users as they are created (query/subscription only over GET)
+curl -N -H 'Accept: text/event-stream' \
+  --get http://localhost:4000/graphql/stream \
+  --data-urlencode 'query=subscription { userCreated { id name email } }'
+
+# Mutations must go to /graphql over POST with a non-simple Content-Type
+curl -X POST http://localhost:4000/graphql \
+  -H 'Content-Type: application/json' \
+  -d '{"query":"mutation { createUser(name: \"Grace\", email: \"grace@example.com\") { id } }"}'
+```
+
+Each emitted result arrives as an `event: next` frame carrying the usual
+GraphQL response body, and the stream finishes with `event: complete`.
+Queries sent to `/graphql/stream` produce exactly one `next` frame followed
+by `complete`. Comment frames (`: ping`) act as heartbeats so idle
+connections survive proxies, and a subscription is torn down as soon as the
+client disconnects.
+
+Events are dispatched by an in-process pub/sub (`src/streaming/pubsub.js`).
+It is intentionally dependency-free, which means subscribers only see events
+published by their own instance; swap that module for a Redis/NATS-backed
+implementation with the same `publish`/`subscribe` contract to run more than
+one replica.
+
+## CORS
+
+`/graphql`, `/graphql/stream`, and `/export` are served behind an **explicit
+origin allow-list** — a wildcard (`*`) `Access-Control-Allow-Origin` is never
+emitted — so that only trusted front-ends can read responses cross-origin.
+
+The allow-list is built in `src/config/cors.js` from the
+`CORS_ALLOWED_ORIGINS` environment variable and applied by `src/index.js`:
+
+```bash
+CORS_ALLOWED_ORIGINS='https://app.example.com,https://admin.example.com' npm start
+```
+
+```js
+import { loadCorsOptions } from './config/cors.js';
+
+const corsOptions = loadCorsOptions();
+app.use('/graphql', cors(corsOptions), /* ... */);
+```
+
+An allowed `Origin` is echoed back verbatim; any other origin receives **no**
+CORS headers, so the browser blocks the response. When
+`CORS_ALLOWED_ORIGINS` is unset every cross-origin read is denied — this is
+the secure default, so the variable must be set for browser front-ends that
+live on a different origin. Requests without an `Origin` header (curl,
+server-to-server calls) are unaffected.
+
+## Excel export
+
+Any dataset the API serves can be downloaded as an Excel workbook (`.xlsx`) —
+useful for sharing a portfolio snapshot or trade history with a spreadsheet.
+The files are generated in-process, so no extra dependency or service is needed.
+
+```bash
+curl http://localhost:4000/export                       # list datasets
+curl -O -J http://localhost:4000/export/trades.xlsx     # download a workbook
+```
+
+| Dataset | Path | Sheets |
+| --- | --- | --- |
+| `users` | `/export/users.xlsx` | Users (with post counts) |
+| `posts` | `/export/posts.xlsx` | Posts (with author names) |
+| `portfolio` | `/export/portfolio.xlsx` | Accounts, Positions, Performance |
+| `trades` | `/export/trades.xlsx` | Trades, Orders, Tax Events |
+| `tax-estimate` | `/export/tax-estimate.xlsx?taxYear=2024` | Summary, Tax Events |
+
+Finance exports accept the same query parameters as their GraphQL counterparts
+(`accountId`, `symbol`, `side`, `status`, `from`, `to`, `limit`, `offset`, and
+`taxYear`, which is required for `tax-estimate`):
+
+```bash
+curl -O -J 'http://localhost:4000/export/trades.xlsx?accountId=acct-1&symbol=AAPL&limit=50'
+```
 
-This service now exposes a unified finance GraphQL surface over three upstream
+When upstream connectors return partial data, the workbook gains an extra
+`Errors` sheet describing each failure instead of hiding the gap.
+
+## Finance cluster integration
+
+This service exposes a unified finance GraphQL surface over three upstream
 domains:
 
 - **OpenTrading**: accounts, orders, trades, and fills
@@ -141,10 +381,12 @@ without changing the GraphQL schema.
 ### Configuration
 
 The running server loads connector settings from the environment via
-`src/config/finance.js`:
+`src/config/finance.js` (the last three rows are read elsewhere but listed here
+for a single view of the service configuration):
 
 | Variable | Description | Default |
 | --- | --- | --- |
+| `PORT` | HTTP port the service listens on | `4000` |
 | `OPENTRADING_ENDPOINT` | OpenTrading endpoint placeholder | `mock://opentrading` |
 | `OPENTRADING_API_KEY` | OpenTrading credential placeholder | empty |
 | `PORTFOLIO_WATCHER_ENDPOINT` | Portfolio-Watcher endpoint placeholder | `mock://portfolio-watcher` |
@@ -233,13 +475,6 @@ query TaxEstimate {
 }
 ```
 
-Run the API and tests with the existing commands:
-
-```bash
-npm start
-npm test
-```
-
 ### Filtering and pagination
 
 Finance queries accept optional filters and offset pagination:
@@ -313,206 +548,14 @@ Follow-up production tasks:
 - Move from offset pagination to cursor pagination if upstream APIs expose
   stable cursors.
 
-## API
-
-| Operation | Description |
-| --- | --- |
-| `users` | List all users |
-| `user(id: ID!)` | Fetch a single user, `null` when unknown |
-| `posts` | List all posts |
-| `post(id: ID!)` | Fetch a single post, `null` when unknown |
-| `portfolioOverview(accountId, from, to, limit, offset)` | Fetch finance accounts, positions, snapshots, and P/L |
-| `tradeHistory(accountId, symbol, side, status, from, to, limit, offset)` | Fetch trades/orders enriched with tax events |
-| `taxEstimate(taxYear, accountId, symbol, from, to, limit, offset)` | Estimate tax from tax-relevant trading activity |
-| `createUser(name, email)` | Create a user |
-| `createPost(title, content, authorId)` | Create a post for an existing user |
-| `userCreated` | Subscription: streams every newly created user |
-| `postCreated(authorId)` | Subscription: streams new posts, optionally for one author |
-
-### Example queries
-
-List users with their posts:
-
-```graphql
-query Users {
-  users {
-    id
-    name
-    email
-    posts {
-      id
-      title
-    }
-  }
-}
-```
-
-Fetch one user:
-
-```graphql
-query User {
-  user(id: "1") {
-    name
-    email
-  }
-}
-```
-
-List posts with their author:
-
-```graphql
-query Posts {
-  posts {
-    id
-    title
-    content
-    author {
-      id
-      name
-    }
-  }
-}
-```
-
-### Example mutations
-
-```graphql
-mutation CreateUser {
-  createUser(name: "Grace Hopper", email: "grace@example.com") {
-    id
-    name
-  }
-}
-```
-
-```graphql
-mutation CreatePost {
-  createPost(title: "Nanoseconds", content: "A talk about wire lengths.", authorId: "1") {
-    id
-    title
-    author {
-      name
-    }
-  }
-}
-```
-
-Creating a post for an unknown `authorId` returns a `BAD_USER_INPUT` error.
-
-### With curl
-
-```bash
-curl http://localhost:4000/graphql \
-  -H 'Content-Type: application/json' \
-  -d '{"query":"{ users { id name posts { title } } }"}'
-```
-
-## Streaming
-
-Subscriptions can be streamed over Server-Sent Events at `POST|GET
-/graphql/stream`. **`GET` is read-only streaming**: it only accepts `query`
-and `subscription` operations, taken from plain `query`/`variables`/
-`operationName` query-string parameters, and is therefore safe to treat as a
-"simple" cross-origin request. This is *not* the same payload contract as
-`/graphql` — **mutations sent with `GET` are rejected with `405 Method Not
-Allowed`** so a mutating operation can never be triggered from a plain
-cross-site navigation or `<img>`/`<script>` style request.
-
-**Mutations must be sent with `POST`**, using a request shape that a simple
-cross-origin form or link cannot forge: a `Content-Type` such as
-`application/json` (which is not a CORS "simple" content type) and/or a
-custom header (e.g. `X-Requested-With`), matching the CSRF-prevention shape
-that Apollo Server enforces by default on `/graphql`. Requests that omit
-this shape should be rejected before they reach resolvers.
-
-SSE keeps the transport plain HTTP — no WebSocket upgrade or extra service is
-required.
-
-```bash
-# Stream new users as they are created (query/subscription only over GET)
-curl -N -H 'Accept: text/event-stream' \
-  --get http://localhost:4000/graphql/stream \
-  --data-urlencode 'query=subscription { userCreated { id name email } }'
-
-# Mutations must go to /graphql over POST with a non-simple Content-Type
-curl -X POST http://localhost:4000/graphql \
-  -H 'Content-Type: application/json' \
-  -d '{"query":"mutation { createUser(name: \"Grace\", email: \"grace@example.com\") { id } }"}'
-```
-
-Each emitted result arrives as an `event: next` frame carrying the usual
-GraphQL response body, and the stream finishes with `event: complete`.
-Queries sent to `/graphql/stream` produce exactly one `next` frame followed
-by `complete`. Comment frames (`: ping`) act as heartbeats so idle
-connections survive proxies, and a subscription is torn down as soon as the
-client disconnects.
-
-### CORS
-
-`/graphql`, `/graphql/stream`, and `/export` are served behind an **explicit
-origin allow-list** — a wildcard (`*`) `Access-Control-Allow-Origin` is never
-emitted — so that only trusted front-ends can read responses cross-origin.
-
-The allow-list is built in `src/config/cors.js` from the
-`CORS_ALLOWED_ORIGINS` environment variable and applied by `src/index.js`:
-
-```bash
-CORS_ALLOWED_ORIGINS='https://app.example.com,https://admin.example.com' npm start
-```
-
-```js
-import { loadCorsOptions } from './config/cors.js';
-
-const corsOptions = loadCorsOptions();
-app.use('/graphql', cors(corsOptions), /* ... */);
-```
-
-An allowed `Origin` is echoed back verbatim; any other origin receives **no**
-CORS headers, so the browser blocks the response. When
-`CORS_ALLOWED_ORIGINS` is unset every cross-origin read is denied — this is
-the secure default, so the variable must be set for browser front-ends that
-live on a different origin. Requests without an `Origin` header (curl,
-server-to-server calls) are unaffected.
-
-Events are dispatched by an in-process pub/sub (`src/streaming/pubsub.js`).
-It is intentionally dependency-free, which means subscribers only see events
-published by their own instance; swap that module for a Redis/NATS-backed
-implementation with the same `publish`/`subscribe` contract to run more than
-one replica.
-
-## Excel export
-
-Any dataset the API serves can be downloaded as an Excel workbook (`.xlsx`) —
-useful for sharing a portfolio snapshot or trade history with a spreadsheet.
-The files are generated in-process, so no extra dependency or service is needed.
-
-```bash
-curl http://localhost:4000/export                       # list datasets
-curl -O -J http://localhost:4000/export/trades.xlsx     # download a workbook
-```
-
-| Dataset | Path | Sheets |
-| --- | --- | --- |
-| `users` | `/export/users.xlsx` | Users (with post counts) |
-| `posts` | `/export/posts.xlsx` | Posts (with author names) |
-| `portfolio` | `/export/portfolio.xlsx` | Accounts, Positions, Performance |
-| `trades` | `/export/trades.xlsx` | Trades, Orders, Tax Events |
-| `tax-estimate` | `/export/tax-estimate.xlsx?taxYear=2024` | Summary, Tax Events |
-
-Finance exports accept the same query parameters as their GraphQL counterparts
-(`accountId`, `symbol`, `side`, `status`, `from`, `to`, `limit`, `offset`, and
-`taxYear`, which is required for `tax-estimate`):
-
-```bash
-curl -O -J 'http://localhost:4000/export/trades.xlsx?accountId=acct-1&symbol=AAPL&limit=50'
-```
-
-When upstream connectors return partial data, the workbook gains an extra
-`Errors` sheet describing each failure instead of hiding the gap.
-
 ## Notes
 
 Data lives in memory only, so every restart resets the service to its seed data
 (two users and two posts). Swapping `src/data/store.js` for a database-backed
 implementation is enough to persist data — the resolvers receive the store through
 the GraphQL context.
+
+## Security and license
+
+Report vulnerabilities as described in [SECURITY.md](SECURITY.md). This project
+is licensed under the [Apache License 2.0](LICENSE).