Add CLAUDE.md for Claude Code: context, commands, SaaS-Fusion, task backlog

CLAUDE.md

@@ -0,0 +1,91 @@
+# CLAUDE.md
+
+Guidance for Claude Code working in this repo. Read this first.
+
+## What this is
+A **demo** (not production) of a reversible PII de-identification round trip for
+HNCB: advisor query with a real name → tokenized before it leaves for the cloud →
+Amazon Bedrock AgentCore agent reasons on tokens only → identity restored on-prem
+before the advisor sees the answer. Everything runs in **one AWS account**;
+"on-prem" is a logical, tag-labelled zone standing in for the branch data centre.
+The demo proves data-flow behaviour, not physical residency.
+
+## Critical context
+- **Fusion is a shared SaaS instance. DO NOT build, host, or Terraform it.** It is
+  configured in the Amplify AI Gateway console (see `fusion/POLICY_SETUP.md`).
+  Because it is SaaS, anything it calls must be a **public HTTPS endpoint with
+  auth** — it cannot reach private VPC resources or use local AWS creds.
+- This means the AWS side's job is to expose two endpoints Fusion will call:
+  **`/tokenize`** (ingress) and **`/restore`** (egress), plus host the detector,
+  vault, RAG tool, and agent. See the task backlog below.
+- **Detection ≠ redaction.** The detector returns typed findings; our code owns
+  minting tokens, writing the vault, and restoring. Never redact-and-discard.
+- Tokens must be **random per request** and stored in the vault keyed by session.
+
+## Architecture (maps to the customer's 8 steps)
+Advisor UI → **Fusion SaaS** → [`/tokenize`: detect (Presidio) + mint + vault-write]
+→ AgentCore Runtime (Bedrock model) → tool call via AgentCore Gateway → RAG Lambda
+(resolve token → de-identified evidence) → agent talking points → **Fusion SaaS**
+→ [`/restore`: vault lookup] → Advisor UI.
+
+## Repo map
+```
+terraform/       DynamoDB (vault + customers), RAG Lambda, IAM, Presidio hosting
+lambda_rag/      RAG tool (real): token resolve -> evidence package
+gateway_api/     TODO: /tokenize and /restore HTTPS endpoints Fusion calls  (T1, T2)
+agent/           Strands agent for AgentCore Runtime + tool schema
+presidio/        detector service (typed findings) + Dockerfile
+seed/            fake customer (Wang Xiaoming) + seed script
+ui/              advisor UI (restored-vs-tokenized split view)
+scripts/         deploy.sh, agentcore_setup.sh, teardown.sh
+fusion/          POLICY_SETUP.md (SaaS console config — human does this, not you)
+```
+
+## Commands
+- Deploy core infra: `bash scripts/deploy.sh` (review first)
+- Seed data: `VAULT_TABLE=... CUSTOMERS_TABLE=... python seed/seed.py --with-demo-token`
+- AgentCore: `bash scripts/agentcore_setup.sh` (verify against `agentcore --help`)
+- Teardown (do this to stop spend): `bash scripts/teardown.sh`
+- Terraform: run all `terraform` commands with `-chdir=terraform`.
+
+## Conventions & guardrails
+- Region default `us-east-1` (best Bedrock/AgentCore quotas). Keep it a variable.
+- **Never commit AWS creds, tokens, or real PII.** Seed data is synthetic only.
+- Python: standard library + boto3; keep handlers small and dependency-light.
+- Pin `bedrock-agentcore` / `strands-agents` versions before `agentcore launch` —
+  these SDKs move fast; verify signatures against installed versions, don't assume.
+- Prefer Lambda Function URLs (with auth) or API Gateway for the public endpoints.
+- After any infra change, remind the human to `teardown` when done recording.
+
+## Task backlog (pick these up)
+Each task: keep it demo-grade, add a note in the file, and update this list.
+
+- **T1 — `/tokenize` endpoint** (`gateway_api/tokenize/`). HTTPS endpoint Fusion
+  calls with `{query}`. Steps: POST query to Presidio `/analyze`; for each finding
+  mint a random token (`CUST_<rand>` for PERSON→customer, `TW_<rand>` for TW_ROC_ID);
+  write vault items `{token, type, value, session_id, expires_at}`; splice tokens
+  into the text. Return `{deidentified_prompt, session_id}`.
+  *Accept:* real name in → tokenized text + session_id out; vault rows written;
+  same input yields different tokens on repeat calls.
+- **T2 — `/restore` endpoint** (`gateway_api/restore/`). Input `{session_id, text}`.
+  Look up this session's tokens in the vault, re-attach identity (envelope-level:
+  prepend the real name; also swap any inline tokens). Return `{final}`.
+  *Accept:* tokenized answer + session_id → answer with `王小明` restored.
+- **T3 — reachability from SaaS.** Make Presidio (or fold detection into T1 so only
+  `/tokenize` + `/restore` are public) reachable from Fusion SaaS with auth.
+  *Accept:* Fusion SaaS can call the endpoints over HTTPS; nothing else is public.
+- **T4 — AgentCore Gateway target.** Wire the RAG Lambda as the MCP tool; confirm
+  the agent can call `get_customer_activity_summary(CUST_000123)` and get the package.
+  *Accept:* a manual `agentcore` invoke returns the evidence package.
+- **T5 — Agent runtime.** Pin deps, `agentcore launch`, capture the Runtime ARN.
+  *Accept:* invoking the runtime with a tokenized prompt returns talking points.
+- **T6 — UI wiring.** Point `ui/index.html` GATEWAY_URL at the Fusion SaaS entry
+  (or `/tokenize` for a Fusion-less dry run); host on S3+CloudFront.
+  *Accept:* the split view renders restored vs tokenized.
+- **T7 — E2E rehearsal.** Run the full script in README; confirm the Bedrock/
+  AgentCore trace shows only tokens. Then verify `teardown.sh` leaves nothing paid-for.
+
+## Known caveats (don't "fix" these silently)
+- zh-TW detection is demo-narrow (tuned to the scripted entities), not production recall.
+- The agentic token-resolution loop (T4) is custom orchestration by design.
+- If you touch `fusion/`, it's documentation for a human — do not try to automate SaaS config.