diff --git a/README.md b/README.md
new file mode 100644
index 0000000..d2048da
--- /dev/null
+++ b/README.md
@@ -0,0 +1,25 @@
+# sc-lambda-ghactions
+
+Service Catalog → Lambda → GitHub Actions automation.
+
+## Architecture
+
+```
+SC Console (user fills product form)
+    └─> CFN Stack (Custom::* resource)
+            └─> Lambda (cross-account, centralized in csvd-dev)
+                    └─> GitHub Actions (repository_dispatch)
+                            └─> Clone target account repo
+                            └─> Operate on repo files (HCL, YAML, etc.)
+                            └─> Open PR → account repo
+```
+
+## Status
+
+Early design / scaffolding phase.
+
+## Related Repos
+
+- [`lambda-template-repo-generator`](https://github.e.it.census.gov/CSVD/lambda-template-repo-generator) — current CodeBuild-based Lambda
+- [`terraform-service-catalog-census`](https://github.e.it.census.gov/SCT-Engineering/terraform-service-catalog-census) — SC product templates
+- [`eks-automation-lambda`](https://github.e.it.census.gov/arnol377/eks-automation-lambda) — design docs
diff --git a/design-docs/README.md b/design-docs/README.md
new file mode 100644
index 0000000..7e0954f
--- /dev/null
+++ b/design-docs/README.md
@@ -0,0 +1,28 @@
+# Design Documents
+
+Architecture decisions, flow diagrams, and planning notes for the
+SC → Lambda → GitHub Actions automation.
+
+## Key Design Decisions
+
+### Why GitHub Actions instead of CodeBuild?
+
+- GHA has first-class access to repo contents without extra clone steps
+- Workflow files live in the target repo — no central runner config to maintain
+- Built-in events (`repository_dispatch`) allow Lambda to trigger specific workflows
+- Easier to test locally via `act`
+
+### Flow
+
+1. User provisions SC product → fills form (cluster name, account, VPC, etc.)
+2. CFN creates `Custom::*` resource with `ServiceToken` pointing to Lambda ARN
+3. Lambda:
+   - Validates inputs (Pydantic model)
+   - Fetches GHE token from Secrets Manager
+   - POSTs `repository_dispatch` to target account repo on GHE
+   - Polls GHA run status until complete (or Lambda deadline)
+   - Returns repo URL + PR URL to CFN
+4. GHA workflow receives `repository_dispatch` event:
+   - Clones the account repo
+   - Renders HCL/YAML files from templates
+   - Commits + opens PR (`repo-init` → `main`)