diff --git a/README.md b/README.md
new file mode 100644
index 0000000..3489394
--- /dev/null
+++ b/README.md
@@ -0,0 +1,130 @@
+# Seahaven Slack Bot
+
+Internal Slack DM assistant for Sea Haven Industries, powered by AWS Bedrock. Employees can ask questions about vendors, company policies, SOPs, and SA8000 compliance via direct message.
+
+## Architecture
+
+```
+Slack DM
+   │
+   ▼
+API Gateway (bot.seahaven.com)
+   │
+   ▼
+slack-webhook Lambda          ← verifies Slack signature, returns 200 immediately
+   │ (async invoke)
+   ▼
+slack-processor Lambda        ← calls Bedrock Agent, logs to DynamoDB, posts reply
+   │
+   ▼
+Bedrock Agent (Claude 3.5 Sonnet)
+   ├── Knowledge Base (AOSS + S3)    ← SA8000 docs, SOPs, employee handbook
+   ├── QBO_Lookup action group       ← QuickBooks vendor search
+   └── Google_Maps_Lookup action group ← fallback vendor search
+```
+
+### Vendor Query Priority
+1. **QBO** — existing vetted vendors in QuickBooks Online
+2. **Knowledge Base** — approved vendor lists in internal docs
+3. **Google Maps** — fallback for net-new vendor discovery
+
+## Stack
+
+| Resource | Details |
+|---|---|
+| AWS Account | 328440206208, us-east-1 |
+| CDK | TypeScript, v2 |
+| LLM | Claude 3.5 Sonnet v2 (`anthropic.claude-3-5-sonnet-20241022-v2:0`) |
+| Embeddings | Amazon Titan Embed Text V2 (1024 dimensions) |
+| Vector Store | OpenSearch Serverless (VECTORSEARCH) |
+| Conversation Log | DynamoDB `seahaven-conversations` (90-day TTL) |
+| Webhook URL | `https://bot.seahaven.com/slack/events` |
+
+## Prerequisites
+
+- Node.js 22+
+- AWS CDK (`npm install -g aws-cdk`)
+- Docker Desktop (required by `@cdklabs/generative-ai-cdk-constructs` for Lambda bundling)
+- AWS credentials configured locally
+
+## Secrets Manager
+
+These three secrets must exist before deploying. Create them via the AWS Console or CLI:
+
+| Secret Name | Structure |
+|---|---|
+| `seahaven/slack/credentials` | `{ "botToken": "xoxb-...", "signingSecret": "..." }` |
+| `seahaven/qbo/oauth` | `{ "clientId": "", "clientSecret": "", "refreshToken": "", "realmId": "" }` |
+| `seahaven/google/maps-api-key` | `{ "apiKey": "" }` |
+
+## Deployment
+
+```bash
+npm install
+npx cdk bootstrap aws://328440206208/us-east-1   # first time only
+npx cdk deploy
+```
+
+The deploy takes ~15 minutes on first run. The AOSS collection and vector index creation are the slow steps — both handled automatically.
+
+Stack outputs after deploy:
+- `KBDocsBucketName` — S3 bucket to upload knowledge base documents
+- `AgentId` — Bedrock Agent ID
+- `SlackWebhookUrl` — URL to register in Slack app settings
+
+## Post-Deployment Setup
+
+### 1. Upload knowledge base documents
+
+Upload SA8000 compliance docs, SOPs, and the employee handbook to the S3 bucket printed in stack outputs. Supported formats: PDF, DOCX, TXT, HTML, CSV, XLSX.
+
+```bash
+aws s3 cp ./your-docs/ s3://<KBDocsBucketName>/ --recursive
+```
+
+### 2. Trigger KB sync
+
+```bash
+aws bedrock-agent start-ingestion-job \
+  --knowledge-base-id <AgentId from outputs> \
+  --data-source-id <DataSourceId> \
+  --region us-east-1
+```
+
+Or trigger from the Bedrock console: **Knowledge Bases → seahaven-kb → Sync**.
+
+### 3. Configure Slack app
+
+In the [Slack API dashboard](https://api.slack.com/apps):
+
+1. **Event Subscriptions** → enable → set Request URL to `https://bot.seahaven.com/slack/events`
+2. Subscribe to bot event: `message.im`
+3. **OAuth & Permissions** → Bot Token Scopes: `chat:write`, `im:history`
+4. **App Home** → Messages Tab → enable, allow users to send messages
+5. Reinstall to workspace if prompted
+
+## Project Structure
+
+```
+bin/
+  seahaven-slack-bot.ts       CDK app entry point
+lib/
+  seahaven-slack-bot-stack.ts Main stack
+  constructs/
+    knowledge-base.ts         Bedrock KB + AOSS + S3 (via @cdklabs L2 construct)
+    bedrock-agent.ts          Bedrock Agent + QBO/Maps action groups
+    slack-handler.ts          API Gateway + webhook/processor Lambdas
+    conversation-log.ts       DynamoDB table
+lambda/
+  slack-webhook/              Verifies Slack signature, fires processor async
+  slack-processor/            Calls agent, writes DynamoDB, posts Slack reply
+  qbo-lookup/                 Bedrock action group — QuickBooks vendor search
+  maps-lookup/                Bedrock action group — Google Maps Places search
+scripts/
+  create-aoss-index.ts        Manual fallback for AOSS index creation (not needed in normal deploy)
+```
+
+## Known Maintenance Items
+
+- **QBO refresh token** expires after 100 days of inactivity. Rotate via the [Intuit OAuth Playground](https://developer.intuit.com/app/developer/playground) and update the `seahaven/qbo/oauth` secret.
+- **KB sync** must be triggered manually after uploading new documents. Consider adding a scheduled EventBridge rule for automatic nightly syncs.