feat: Genie Space AI config, three-file split, and README cleanup

- Add AI-generated Genie Space config (sample questions, instructions,
  benchmarks, title, description) via serialized_space API
- Split auth.auto.tfvars into auth (secrets, gitignored) and env
  (tables/warehouse/genie, checked in) for safe git tracking
- Rebuild genie_space.sh with Python-based JSON builder for proper
  serialized_space construction (version 2, sorted IDs, 32-char hex)
- Simplify README: remove reference tables, trim troubleshooting,
  clean up Advanced Usage, update flowchart with two-box layout
- Improve generate_abac.py output with clickable file paths and
  clearer next-step guidance
- Update all docs and examples for three-file config pattern

Made-with: Cursor

Author: louiscsq

uc-quickstart/utils/genie/aws/ABAC_PROMPT.md

@@ -228,6 +228,42 @@ Violating any of these causes validation failures. Double-check consistency acro
 6. Select masking functions from the library above (or create new ones)
 7. Generate both output files. For entity names in tag_assignments, always use **fully qualified** names (`catalog.schema.table` or `catalog.schema.table.column`). For function_name in fgac_policies, use relative names only (e.g. `mask_pii`). Every fgac_policy MUST include `catalog`, `function_catalog`, and `function_schema`. **CRITICAL**: set `function_schema` to the schema where the tagged columns actually live — do NOT default all policies to the first schema. In `masking_functions.sql`, group the `CREATE FUNCTION` statements by schema with separate `USE SCHEMA` blocks. Only create each function in the schema where it is needed
 8. Every `match_condition` and `when_condition` MUST only use `hasTagValue()` and/or `hasTag()` — no other functions or operators
+9. Generate Genie Space config — all five fields below. Tailor everything to the user's actual tables, domain, and business context:
+   - `genie_space_title` — a concise, descriptive title (e.g., "Financial Compliance Analytics", "Clinical Data Explorer")
+   - `genie_space_description` — 1–2 sentence summary of what the space covers and who it's for
+   - `genie_sample_questions` — 5–10 natural-language questions a business user would ask (shown as conversation starters in the UI)
+   - `genie_instructions` — domain-specific guidance for the Genie LLM (e.g., how to calculate metrics, date conventions, terminology, masking behaviour awareness)
+   - `genie_benchmarks` — 3–5 benchmark questions with ground-truth SQL for evaluating accuracy
+
+### Output Format — Genie Space Config (in `abac.auto.tfvars`)
+
+Include these variables alongside groups, tag_policies, etc.:
+
+```hcl
+genie_space_title       = "Financial & Clinical Analytics"
+genie_space_description = "Explore transaction data, patient encounters, and compliance metrics. Designed for analysts, compliance officers, and clinical staff."
+
+genie_sample_questions = [
+  "What is the total revenue by region for last quarter?",
+  "Show the top 10 customers by transaction volume",
+  "Which accounts have been flagged for AML review?",
+  "How many patient encounters occurred last month?",
+  "What is the average transaction amount by account type?",
+]
+
+genie_instructions = "When calculating revenue, sum the Amount column. 'Last month' means the previous calendar month (not last 30 days). Round monetary values to 2 decimal places. Patient names are masked for non-clinical roles — queries about patient counts or encounter dates are always allowed."
+
+genie_benchmarks = [
+  {
+    question = "What is the total transaction amount?"
+    sql      = "SELECT SUM(Amount) as total_amount FROM catalog.schema.transactions"
+  },
+  {
+    question = "How many patients were seen last month?"
+    sql      = "SELECT COUNT(*) FROM catalog.schema.encounters WHERE EncounterDate >= DATE_TRUNC('month', CURRENT_DATE - INTERVAL 1 MONTH) AND EncounterDate < DATE_TRUNC('month', CURRENT_DATE)"
+  },
+]
+```
 
 ---
 

uc-quickstart/utils/genie/aws/GENIE_SPACE_PERMISSIONS.md

@@ -17,7 +17,7 @@ This document lists everything that must be in place for business users (the gro
 
 - **SQL warehouse:** A single SQL warehouse is used for both masking function deployment and the Genie Space. Genie embeds on this warehouse; end users do **not** need explicit **CAN USE** on the warehouse.
 - **Terraform:** `warehouse.tf` handles warehouse resolution:
-  - `sql_warehouse_id` set in `auth.auto.tfvars` -> reuses the existing warehouse (dev)
+  - `sql_warehouse_id` set in `env.auto.tfvars` -> reuses the existing warehouse (dev)
   - `sql_warehouse_id` empty or omitted -> auto-creates a serverless warehouse (prod)
 
 ## 4. Data access
@@ -27,18 +27,18 @@ This document lists everything that must be in place for business users (the gro
 
 ## 5. Genie Space (create + ACLs)
 
-- **Genie Space:** Create a Genie Space with the tables from `uc_tables` (in `auth.auto.tfvars`) and grant at least **CAN VIEW** and **CAN RUN** to all groups.
+- **Genie Space:** Create a Genie Space with the tables from `uc_tables` (in `env.auto.tfvars`) and grant at least **CAN VIEW** and **CAN RUN** to all groups.
 - **Automation:** Terraform manages Genie Space lifecycle via `genie_space.tf`:
   - **`genie_space_id` empty** (greenfield): `terraform apply` auto-creates a Genie Space from `uc_tables`, sets ACLs, and trashes the space on `terraform destroy`.
   - **`genie_space_id` set** (existing): `terraform apply` only applies CAN_RUN ACLs to the existing space.
 
 ### Auto-create mode
 
-Set `genie_space_id = ""` in `auth.auto.tfvars` and ensure `uc_tables` is non-empty. Terraform runs `genie_space.sh create` automatically during apply. Wildcards (`catalog.schema.*`) are expanded via the UC Tables API.
+Set `genie_space_id = ""` in `env.auto.tfvars` and ensure `uc_tables` is non-empty. Terraform runs `genie_space.sh create` automatically during apply. Wildcards (`catalog.schema.*`) are expanded via the UC Tables API.
 
 ### Existing space mode
 
-Set `genie_space_id` to your Genie Space ID in `auth.auto.tfvars`. Terraform runs `genie_space.sh set-acls` to grant CAN_RUN to all configured groups.
+Set `genie_space_id` to your Genie Space ID in `env.auto.tfvars`. Terraform runs `genie_space.sh set-acls` to grant CAN_RUN to all configured groups.
 
 ### Manual script usage
 

uc-quickstart/utils/genie/aws/IMPORT_EXISTING.md

@@ -6,7 +6,7 @@ If the warehouse, groups, or tag policies **already exist**, Terraform will fail
 
 Before running the import script, ensure:
 
-1. `auth.auto.tfvars` is configured with valid credentials.
+1. `auth.auto.tfvars` is configured with valid credentials and `env.auto.tfvars` with your environment.
 2. `abac.auto.tfvars` is configured with the groups and tag policies you want to import.
 3. `terraform init` has been run.
 
@@ -32,7 +32,7 @@ The script reads group names from `abac.auto.tfvars` and tag policy keys from th
 
 ## Optional: reuse an existing warehouse
 
-To use an existing warehouse instead of auto-creating one, set in **auth.auto.tfvars**:
+To use an existing warehouse instead of auto-creating one, set in **env.auto.tfvars**:
 
 ```hcl
 sql_warehouse_id = "<WAREHOUSE_ID>"

uc-quickstart/utils/genie/aws/Makefile

@@ -13,6 +13,12 @@ setup: ## Copy example files and prompt for credentials
 	else \
 		echo "auth.auto.tfvars already exists — skipping."; \
 	fi
+	@if [ ! -f env.auto.tfvars ]; then \
+		cp env.auto.tfvars.example env.auto.tfvars; \
+		echo "Created env.auto.tfvars — edit it with your tables and environment config."; \
+	else \
+		echo "env.auto.tfvars already exists — skipping."; \
+	fi
 	@if [ ! -f abac.auto.tfvars ]; then \
 		cp abac.auto.tfvars.example abac.auto.tfvars; \
 		echo "Created abac.auto.tfvars — edit it with your ABAC config."; \
@@ -22,7 +28,10 @@ setup: ## Copy example files and prompt for credentials
 	@mkdir -p ddl generated
 	@echo "Created ddl/ and generated/ directories."
 	@echo ""
-	@echo "Next: edit auth.auto.tfvars, then run 'make generate' or 'make plan'."
+	@echo "Next steps:"
+	@echo "  1. Edit credentials (gitignored):  $$(pwd)/auth.auto.tfvars"
+	@echo "  2. Edit tables & environment:       $$(pwd)/env.auto.tfvars"
+	@echo "  3. Run:  make generate"
 
 generate: ## Run generate_abac.py to produce masking SQL + tfvars
 	@echo "=== Generate ABAC Config ==="
@@ -86,4 +95,4 @@ clean: ## Remove generated files, Terraform state, and .terraform/
 	rm -rf generated/abac.auto.tfvars generated/masking_functions.sql generated/generated_response.md
 	rm -rf .terraform *.tfstate *.tfstate.backup .terraform.lock.hcl
 	@echo "Cleaned generated files and Terraform state."
-	@echo "NOTE: auth.auto.tfvars and abac.auto.tfvars were NOT removed."
+	@echo "NOTE: auth.auto.tfvars, env.auto.tfvars, and abac.auto.tfvars were NOT removed."