docs: deploy_products/ workspace replaces census pipeline dependency;…

… OU sharing + StackSet

docs/generalized-terraform-product-architecture.md

@@ -259,7 +259,7 @@ auditable (every template repo change is a PR in the SCT-Engineering org).
 **Adding a new product type requires only creating a new template repo with a `handler.py`.
 No Lambda code changes, no Lambda redeployment, no registry entries.**
 
-### 5. CloudFormation product template + Terraform registration
+### 5. CloudFormation product template
 
 The CFN template for a product type lives in `service-catalog/{product_type}-product-template.yaml`
 inside the `sc-lambda-ghactions` repo. It follows the same pattern as the existing EKS template:
@@ -283,48 +283,61 @@ Properties:
   tier: !Ref Tier
 ```
 
-**The template is never registered manually.** The `deploy/service_catalog.tf` workspace
-manages all SC infrastructure — S3 upload, portfolio, product, provisioning artifact,
-launch role, launch constraint, and principal associations — using `for_each` over a
-`var.sc_products` map. This is the same proven pattern as `deploy_product/main.tf` in
-`lambda-template-repo-generator`.
+### 6. `deploy_products/` — dedicated Terraform workspace for SC product management
 
-Adding a new product type requires only two steps:
+SC portfolio and product registration lives in a **dedicated `deploy_products/` workspace**,
+separate from `deploy/` (which manages the Lambda and CodeBuild engine). This mirrors the
+pattern established by `lambda-template-repo-generator`, which has `deploy/` for the
+Lambda infrastructure and `deploy_product/` for the SC product registration.
 
-1. Add an entry to `var.sc_products` in `deploy/terraform.tfvars`:
+```
+sc-lambda-ghactions/
+├── deploy/           ← Lambda, ECR, CodeBuild, IAM  (engine — rarely touched)
+└── deploy_products/  ← SC portfolio, products, S3, launch roles, OU sharing
+```
+
+The workspace is driven by two variables:
 
 ```hcl
+# deploy_products/terraform.tfvars
+
 sc_products = {
-  ekscluster = {
+  eks_cluster = {
     name        = "EKS Cluster Repository Creator"
     description = "Creates an EKS cluster account repo from template-eks-cluster."
-    template    = "service-catalog/eks-cluster-product-template.yaml"
+    template    = "${path.module}/../service-catalog/eks-cluster-product-template.yaml"
     version     = "2.0.0"
   }
-  s3bucket = {
+  s3_bucket = {
     name        = "S3 Bucket Repository Creator"
     description = "Creates an S3 bucket account repo from template-s3-bucket."
-    template    = "service-catalog/s3-bucket-product-template.yaml"
+    template    = "${path.module}/../service-catalog/s3-bucket-product-template.yaml"
     version     = "1.0.0"
   }
 }
-```
-
-2. Run `tf apply` in `deploy/` — Terraform creates (or updates) all SC resources for the new entry.
 
-No AWS Console clicks, no manual artifact uploads, no census pipeline PR required to
-test a new product type in the dev/lab environment.
+# AWS Organizations OU IDs to share the portfolio with.
+# Every account in these OUs will see the portfolio in their SC console automatically.
+share_ous = [
+  "ou-xxxx-xxxxxxxx",   # platform-engineering
+  "ou-xxxx-yyyyyyyy",   # app-teams
+]
+```
 
-### 6. Promotion to production via the census pipeline
+Terraform iterates `var.sc_products` with `for_each` to create the S3 object, SC product,
+provisioning artifact, and launch constraint for each entry. A single shared portfolio
+(`aws_servicecatalog_portfolio`) is created once and shared to the OUs listed in
+`var.share_ous` via `aws_servicecatalog_portfolio_share` — no per-account work required.
 
-The `deploy/` workspace is the **development and testing path**. Once a new product type
-has been validated end-to-end, it is promoted to production by adding the corresponding
-entry to `terraform-service-catalog-census/templates/products/{product_type}/` and opening
-a PR in `terraform-service-catalog-census`. The census pipeline applies this to all shared
-accounts via the standard portfolio-sharing mechanism.
+**Adding a new product type:**
+1. Create the template repo and CFN template (steps above)
+2. Add one entry to `var.sc_products` in `deploy_products/terraform.tfvars`
+3. Run `tf apply` in `deploy_products/`
 
-The CFN template file (`service-catalog/{product_type}-product-template.yaml`) is the
-single source of truth — both the `deploy/` workspace and the census pipeline read from it.
+No census pipeline PR, no YAML config files, no Terragrunt, no AWS Console clicks.
+The `deploy_products/` workspace replaces the `terraform-service-catalog-census` dependency
+for this system entirely. Any account in the configured OUs gets access to new products
+immediately after apply.
 
 ---
 
@@ -338,12 +351,11 @@ onboard any new Terraform workload without Lambda or CodeBuild changes:
       - flat `.tf.j2` file(s) rendered by the Proposer
       - `tf-run.data`
       - `.sc-automation.yml.j2` (optional; Proposer writes a default if absent)
-      **No files in the Lambda repository need to be created or modified.**
-- [ ] Add `service-catalog/{product_type}-product-template.yaml` CFN template to `sc-lambda-ghactions`
-- [ ] Add an entry to `var.sc_products` in `deploy/terraform.tfvars` and run `tf apply` in `deploy/` —
-      Terraform registers the SC portfolio, product, artifact, launch role, constraint, and principals
-- [ ] Validate end-to-end in the dev/lab account via `scripts/test_service_catalog.py`
-- [ ] Promote to production: add entry to `terraform-service-catalog-census/templates/products/{product_type}/` and open a PR
+- [ ] Add `service-catalog/{product_type}-product-template.yaml` to `sc-lambda-ghactions`
+- [ ] Add one entry to `var.sc_products` in `deploy_products/terraform.tfvars`
+- [ ] Run `tf apply` in `deploy_products/` — creates S3 artifact, SC product, provisioning
+      artifact, launch constraint; all OU-member accounts see the new product immediately
+- [ ] Validate end-to-end via `scripts/test_service_catalog.py`
 
 ---
 
@@ -382,6 +394,9 @@ CloudFormation stacks or SC provisioned products.
 | Secrets Manager secrets | 2 (GHE tokens) + 1 (webhook) | No change |
 | Lambda Function URL | 1 | No change |
 | ECR repositories | 1 | No change |
+| SC portfolios | 1 (EKS) | 1 (shared across all product types) |
+| SC products | 1 | +1 per new product type (S3 object + SC product resource) |
+| CFN StackSets | 0 | 1 (launch role deployed to all OU member accounts via `deploy_products/`) |
 
-There is **no additional AWS infrastructure cost** to add new product types. Each new
-product type is purely a code and configuration change.
+Each new product type adds a single SC product + S3 artifact. No new Lambda functions,
+no new CodeBuild projects, no new secrets — and no dependency on external pipeline teams.