From f254776ba6887c047fb27c2249163676384e9a73 Mon Sep 17 00:00:00 2001
From: Adam Moussa <adam@seahavenind.com>
Date: Mon, 13 Apr 2026 00:00:39 -0400
Subject: [PATCH] docs: update README for Notion KB sync

Documents the notion-sync Lambda, daily EventBridge schedule, Notion
secret setup, and updated project structure.

Refs #4
---
 README.md | 48 +++++++++++++++++++++++++++++++++++++++---------
 1 file changed, 39 insertions(+), 9 deletions(-)

diff --git a/README.md b/README.md
index a6b3726..f9db1bb 100644
--- a/README.md
+++ b/README.md
@@ -18,9 +18,14 @@ slack-processor Lambda        ← calls Bedrock Agent, logs to DynamoDB, posts r
    │
    ▼
 Bedrock Agent (Claude Sonnet 4.5)
-   ├── Knowledge Base (AOSS + S3)    ← SA8000 docs, SOPs, employee handbook
+   ├── Knowledge Base (AOSS + S3)    ← SA8000 docs, SOPs, employee handbook, Notion pages
    ├── QBO_Lookup action group       ← QuickBooks vendor search
    └── Google_Maps_Lookup action group ← fallback vendor search
+
+EventBridge (daily 02:00 UTC)
+   │
+   ▼
+notion-sync Lambda            ← exports Office Operations Notion pages → S3 → KB ingestion
 ```
 
 ### Vendor Query Priority
@@ -49,13 +54,14 @@ Bedrock Agent (Claude Sonnet 4.5)
 
 ## Secrets Manager
 
-These three secrets must exist before deploying. Create them via the AWS Console or CLI:
+These secrets must exist before deploying. The Slack, QBO, and Maps secrets must be created manually before first deploy. The Notion secret is created automatically by CDK with a placeholder — update it after deploy.
 
-| Secret Name | Structure |
-|---|---|
-| `seahaven/slack/credentials` | `{ "botToken": "xoxb-...", "signingSecret": "..." }` |
-| `seahaven/qbo/oauth` | `{ "clientId": "", "clientSecret": "", "refreshToken": "", "realmId": "" }` |
-| `seahaven/google/maps-api-key` | `{ "apiKey": "" }` |
+| Secret Name | Created | Structure |
+|---|---|---|
+| `seahaven/slack/credentials` | Manual (pre-deploy) | `{ "botToken": "xoxb-...", "signingSecret": "..." }` |
+| `seahaven/qbo/oauth` | Manual (pre-deploy) | `{ "clientId": "", "clientSecret": "", "refreshToken": "", "realmId": "" }` |
+| `seahaven/google/maps-api-key` | Manual (pre-deploy) | `{ "apiKey": "" }` |
+| `seahaven/notion/api-key` | Auto (CDK) | `{ "apiKey": "secret_..." }` |
 
 ## Deployment
 
@@ -71,6 +77,7 @@ Stack outputs after deploy:
 - `KBDocsBucketName` — S3 bucket to upload knowledge base documents
 - `AgentId` — Bedrock Agent ID
 - `SlackWebhookUrl` — URL to register in Slack app settings
+- `NotionSecretName` — Secrets Manager secret to populate with your Notion integration token
 
 ## Post-Deployment Setup
 
@@ -93,7 +100,27 @@ aws bedrock-agent start-ingestion-job \
 
 Or trigger from the Bedrock console: **Knowledge Bases → seahaven-kb → Sync**.
 
-### 3. Configure Slack app
+### 3. Configure Notion sync
+
+1. Create a Notion internal integration at **Settings → Connections → Develop or manage integrations**
+2. Name it `seahaven-office-ops` and associate it with the **Office Operations** teamspace
+3. Copy the integration token (`secret_...`)
+4. In AWS Console: **Secrets Manager → `seahaven/notion/api-key` → Edit** — set `apiKey` to your token
+5. Run a manual test:
+
+```bash
+aws lambda invoke \
+  --function-name seahaven-notion-sync \
+  --region us-east-1 \
+  --log-type Tail \
+  --query 'LogResult' \
+  --output text \
+  /dev/null | base64 -d
+```
+
+The sync runs automatically every day at 02:00 UTC via EventBridge.
+
+### 4. Configure Slack app
 
 In the [Slack API dashboard](https://api.slack.com/apps):
 
@@ -115,11 +142,13 @@ lib/
     bedrock-agent.ts          Bedrock Agent + QBO/Maps action groups
     slack-handler.ts          API Gateway + webhook/processor Lambdas
     conversation-log.ts       DynamoDB table
+    notion-sync.ts            EventBridge daily cron + notion-sync Lambda + Secrets Manager
 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
+  notion-sync/                Daily Notion → S3 export, triggers KB ingestion
 scripts/
   create-aoss-index.ts        Manual fallback for AOSS index creation (not needed in normal deploy)
 ```
@@ -127,4 +156,5 @@ scripts/
 ## 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.
+- **Notion sync** runs daily at 02:00 UTC automatically. To trigger an immediate sync, invoke `seahaven-notion-sync` manually via the Lambda console or CLI.
+- **KB sync for manual S3 uploads** (non-Notion docs) must still be triggered manually after uploading new documents to the S3 bucket.