Ge Demo Generator

GE Demo Generator Skill (v2.20.0)

Synthesizes production-grade, domain-tailored AI agent demo environments using Gemini 3.8 Flash for reasoning and Gemini 3.1 Flash Image for visual generation, adhering to a strict 6-step infrastructure dependency graph, rich A2UI interactive component streaming, Google Workspace OAuth authorization, external sample files staged in Cloud Storage and, when the credentials carry the Drive scope, in the deploying account's Google Drive, 7 structured demo prompts, automated browser video recording & Remotion highlight reel delivery to Google Drive, and global multilingual localization (i18n/l10n).

🌐 Multilingual Support & Localization Architecture (i18n/l10n)

The skill is implemented entirely in English at the system specification and codebase layer, while providing complete, dynamic multilingual support for any enterprise domain worldwide:

1. Automatic Language & Locale Detection:

   • From Domain TLD:
     • .co.jp, .jp, .ne.jp, .or.jp ➔ Japanese (日本語, locale: "ja", currency: "JPY", symbol: "¥")
     • .de ➔ German (Deutsch, locale: "de", currency: "EUR", symbol: "€")
     • .fr ➔ French (Français, locale: "fr", currency: "EUR", symbol: "€")
     • .es ➔ Spanish (Español, locale: "es", currency: "EUR", symbol: "€")
     • .it ➔ Italian (Italiano, locale: "it", currency: "EUR", symbol: "€")
     • .cn, .tw ➔ Chinese (中文, locale: "zh", currency: "CNY"/"TWD")
     • .kr ➔ Korean (한국어, locale: "ko", currency: "KRW", symbol: "₩")
     • .br ➔ Portuguese (Português, locale: "pt", currency: "BRL", symbol: "R$")
     • .co.uk, .com.au, .com, .io, .org, etc. ➔ English (locale: "en", currency: "USD"/"GBP")
   • From User Interaction:
     • If the user provides a prompt in Japanese, all user-facing demo assets are synthesized in Japanese. If in German, all in German.

2. Strict Language Consistency Rule (MANDATORY):

   • ALL user-facing text elements MUST strictly match the detected target language:
     • Company overview & operational challenges.
     • Table and column business descriptions (harvested into Knowledge Catalog).
     • CSV string values (product names, category names, person names, address strings, remarks).
     • External files: PDF title, body sections, audit summary tables; Excel headers, KPI cards, and notes; Scanned image prompts and handwritten ink text values.
     • System instructions (businessInstruction), Welcome Card greeting, and A2UI Button labels.
     • The 7 Structured Demo Prompts (demoGuide).
   • Technical Names Isolation: Table names, column names, and primary/foreign key ID fields (e.g. order_id, supplier_id) MUST always remain in English snake_case for database engine stability and SQL parser reliability.
   • Currency symbol: write the detected symbol to .env as CURRENCY_SYMBOL (e.g. CURRENCY_SYMBOL=¥). The A2UI few-shot examples ship with a literal [CURRENCY] placeholder instead of a hardcoded symbol; setup_and_deploy.sh substitutes it before the image is built and aborts the deploy if any occurrence survives. Defaults to $ when unset.

Complete Lifecycle & Infrastructure Dependency Graph

Phase 1: Customer Domain & Business Goal Research (Search Grounding & Language Detection)
   ↓
Phase 2: Requirements confirmed interactively ➔ Demo Architecture & Data Model Plan ➔ APPROVAL
   ↓
Phase 3: Synthetic Data & External Sample Files Generation (PDF, Excel, Images) + Google Drive Upload (Step 1/6)
   ↓
Phase 4: ADK Multi-Agent Project Scaffolding & A2UI System Prompts
   ↓
Phase 5: Ordered Cloud Provisioning & Deployment:
   ├── Step 1: BigQuery (with Knowledge Catalog Metadata) & Firestore Initial Data
   ├── Step 2: Agent Engine Sandbox (Code Execution Environment) [CRITICAL DEPENDENCY]
   ├── Step 3: Data Viewer Dashboard Cloud Run Deployment (Gets VIEWER_URL)
   ├── Step 4: Main Multi-Agent Cloud Run Deployment (Injects SANDBOX_RESOURCE_NAME & VIEWER_URL)
   └── Step 5: Background Task Pub/Sub Push Subscription (/execute_task & SELF_URL)
   ↓
Phase 6: Gemini Enterprise App Discovery, Workspace Authorization & Registration (Step 6/6)
   ↓
Phase 7: Comprehensive Results Output:
   ├── 💬 Direct Gemini Enterprise Console Chat Link
   ├── 📁 External Sample Files: Cloud Storage links, plus Drive links when the upload ran
   ├── 📊 Firestore Data Viewer Dashboard Link
   ├── 🔎 BigQuery Console Link
   └── 🎯 7 Structured Demo Prompts Playbook (Localized to Target Language)
   ↓
Phase 8: Automated Browser Demo Video Production & Drive Delivery (Optional)
   ├── Step 1: Playwright CDP Screen Recording of GE Web UI (Prompt 1, 3, 4)
   ├── Step 2: Google Cloud TTS Narration Audio & Subtitle Timecodes
   ├── Step 3: Remotion Programmatic Video Composition (Dynamic Camera, 4x Fast-Forward, Pure Voice Narration)
   └── Step 4: Google Drive Upload to Demo Folder & Sharable Link

Phase 1: Customer Domain & Business Goal Research

1. Extract Domain & Company:

   • If a domain is provided (e.g., example.com, example.co.jp, example.de), determine company name, primary industry, and regional language from the domain itself — never from a list baked into this skill.
   • If a business goal or company name is provided, identify the corresponding corporate entity and language.

2. Grounded Deep Research (via search_web):

   • Search for the company's latest corporate profile, business units, IR reports, and known operational challenges.
   • Identify:
     • 3-5 Key Business Challenges (e.g., "yield rate drop in semiconductor fabrication", "supply chain lead-time anomalies").
     • 5-8 Operational Workflows and evaluate which ones are automatable with AI agents.
     • Authentic Domain Entities & Nomenclature (e.g., real facility names like "Kumamoto Technology Center", actual product codes, industry status codes).

3. Interactive Use Case Selection (Customer Domain Selection Flow):

   • Present the research findings to the user in their language:
     • 🏢 Company Profile: Official name, summary, primary industry.
     • ⚠️ Key Business Challenges: 3-5 detected operational pain points.
     • 🎯 Candidate Workflows: 3-5 top automatable workflows with automation feasibility ratings.
   • Prompt the user to select or customize the use case:
     • Use ask_question or present a structured choice so the user can pick the target scenario or write in specific requirements.

Phase 2: Requirements Alignment & Demo Architecture Plan (Approval Gate)

Phase 2 has two steps, in this order and never merged into one:

Step 2.1 — ask the handful of questions the design genuinely depends on, interactively. Step 2.2 — show the finished design brief as the alignment artifact, and ask for a go.

The order is what makes the brief worth reading. A brief that still contains open questions is a questionnaire, and the user has to hold the design in their head while answering it; a brief written after the answers is a mirror — the user is checking whether what you understood matches what they meant, which is a much easier thing to do and the last cheap moment to change the entities, the narrative, the file lineage or the target project.

Until the user approves the brief, nothing is created — no CSVs, no Drive folder, no BigQuery dataset, no Cloud Run service. Everything after this point takes 15-30 minutes and spends real quota in someone's project.

Step 2.1 — Confirm the requirements interactively

Ask only what you cannot responsibly decide, and ask it before writing the brief. Keep it short — two to four questions, batched into one message (ask_question where available), each with a stated default so the user can answer "all defaults" in three words:

1. Anchor persona — who is the primary user of this agent (job title, and a sentence of context if useful)? That persona becomes the demo's protagonist: the agent is framed as their process operator, prompt 1 opens from their daily situation, approval gates are decisions they or their manager own, and every other persona appears only as a hand-off counterpart. If the user declines, rotate personas freely instead.
2. Scope of the narrative — which single process instance the demo follows, if Phase 1 left more than one plausible reading of the chosen scenario.
3. Advanced settings — ask about the two or three the demo is a plausible candidate for (Workspace OAuth when the scenario touches Gmail/Drive/Calendar, rag when it turns on documents rather than numbers, dataScale when the narrative claims enterprise volume), and say the rest keep their defaults. Keep the question short — brief section 6 lists every option with its resolved value, so nothing is hidden by asking about a few. Add a warm Cloud Run instance (MIN_INSTANCES=1) to that question whenever the user has named a date, an audience or a live session: it is the one option that is about the presentation rather than the demo, and the only thing that removes the cold start — and the occasional cold-start error — from the first message. Offer it with its price in the same breath (see brief section 6).
4. Target environment — only if what gcloud reports (read it now, see below) is not obviously the project the user means.

Anything the user has already stated — in the original request or in Phase 1 — is decided. Re-asking it reads as not having listened.

Zero-Touch Environment, Project & IAM Pre-flight Probe:

Read and verify the target environment before writing the brief, ensuring zero-touch deployment readiness so the brief's section 5 states verified facts rather than unvalidated assumptions:

# 1. Target Project Synchronization: align project if specified by user
TARGET_PROJECT="${TARGET_PROJECT:-}"
CURRENT_PROJECT=$(gcloud config get-value project 2>/dev/null || echo "")
if [ -n "$TARGET_PROJECT" ] && [ "$CURRENT_PROJECT" != "$TARGET_PROJECT" ]; then
  gcloud config set project "$TARGET_PROJECT" >/dev/null 2>&1 || true
fi
PROJECT_ID=$(gcloud config get-value project 2>/dev/null || echo "")

# 2. Account Verification & Auto-Discovery: probe project access; auto-switch if active account lacks access
GCP_ACCOUNT=$(gcloud config get-value account 2>/dev/null || echo "Unknown")
if ! gcloud projects describe "$PROJECT_ID" >/dev/null 2>&1; then
  for acc in $(gcloud auth list --format="value(account)" 2>/dev/null); do
    if gcloud projects describe "$PROJECT_ID" --account="$acc" >/dev/null 2>&1; then
      gcloud config set account "$acc" >/dev/null 2>&1 || true
      GCP_ACCOUNT="$acc"
      break
    fi
  done
fi

PROJECT_NUMBER=$(gcloud projects describe "$PROJECT_ID" --format="value(projectNumber)" 2>/dev/null || echo "")
REGION=${CLOUD_RUN_REGION:-"asia-northeast1"}

# 3. Google Drive Scope Pre-flight
DRIVE_OK=$(curl -s -o /dev/null -w '%{http_code}' \
  -H "Authorization: Bearer $(gcloud auth print-access-token 2>/dev/null)" \
  'https://www.googleapis.com/drive/v3/about?fields=user')

DRIVE_OK is 200 when the Drive copy will happen, and the owner is ${GCP_ACCOUNT} — the same account, because the upload uses this token. Anything else (usually 403, a token carrying no Drive scope, which is what a plain gcloud auth login gives you) means this demo will have no Google Drive copy of the sample documents at all. That is a fact the brief has to state, not discover at deploy time — see brief sections 3 and 5. It is also one command to fix, so say it now: gcloud auth login --enable-gdrive-access --no-launch-browser (using --no-launch-browser since an agentic IDE terminal usually has no local browser), then re-read.

Multi-OS Google Cloud Authentication & Setup Protocol

Before proceeding with deployment, verify both user CLI authentication (gcloud auth print-access-token) and Application Default Credentials (gcloud auth application-default print-access-token). If missing or expired:

• Interactive TTY Mode ([ -t 0 ]): The script automatically detects the host OS environment, prints the tailored authentication commands, and pauses (read -p), allowing the user to authenticate in a separate terminal or browser window and resume seamlessly by pressing Enter.

• Non-Interactive / CI Mode: Strictly fail-fast (Exit 1) with descriptive error logs and the single command to resume.

• Host OS Detection & Authentication Matrix:

  Host OS / Environment	Detection Signal	Authentication Commands	Notes
  Linux / Remote VM (Headless)	No $DISPLAY, SSH, or Cloud Shell	gcloud auth login --enable-gdrive-access --no-launch-browsergcloud auth application-default login --no-launch-browsergcloud auth application-default set-quota-project $PROJECT_ID	Copy verification URL to local browser, sign in, and paste auth code back.
  macOS (Terminal / iTerm)	uname -s == Darwin	gcloud auth login --enable-gdrive-accessgcloud auth application-default logingcloud auth application-default set-quota-project $PROJECT_ID	Browser opens automatically for OAuth consent.
  Windows (WSL / WSL2)	/proc/version contains microsoft or wsl	gcloud auth login --enable-gdrive-accessgcloud auth application-default logingcloud auth application-default set-quota-project $PROJECT_ID	If browser interop is disabled, append --no-launch-browser.
  Linux Desktop (GUI)	Linux with active $DISPLAY	gcloud auth login --enable-gdrive-accessgcloud auth application-default logingcloud auth application-default set-quota-project $PROJECT_ID	Browser opens automatically for OAuth consent.

• Quota Project Auto-Configuration: The deployment script and self-healing engine automatically execute gcloud auth application-default set-quota-project $PROJECT_ID to prevent HTTP 403 PERMISSION_DENIED: The discoveryengine.googleapis.com API requires a quota project.

Deployer IAM Audit & Autonomous Self-Healing Protocol

To guarantee a seamless zero-touch deployment, probe whether the deploying account ${GCP_ACCOUNT} possesses the necessary permissions on ${PROJECT_ID}:

1. Owner / IAM Admin Auto-Healing:
   • Check if ${GCP_ACCOUNT} is Project Owner, Editor, or has Project IAM Admin on ${PROJECT_ID}.
   • If ${GCP_ACCOUNT} has IAM administrative privileges but lacks specific service roles (or if granular roles are in use), automatically grant missing deployment roles before starting deployment:

gcloud projects add-iam-policy-binding "$PROJECT_ID" \
  --member="user:$GCP_ACCOUNT" \
  --role="roles/run.admin" --condition=None

gcloud projects add-iam-policy-binding "$PROJECT_ID" \
  --member="user:$GCP_ACCOUNT" \
  --role="roles/discoveryengine.admin" --condition=None

gcloud projects add-iam-policy-binding "$PROJECT_ID" \
  --member="user:$GCP_ACCOUNT" \
  --role="roles/bigquery.admin" --condition=None

gcloud projects add-iam-policy-binding "$PROJECT_ID" \
  --member="user:$GCP_ACCOUNT" \
  --role="roles/iam.serviceAccountUser" --condition=None

2. Non-Admin Permission Denial Handling (Zero-Touch Guidance):

   • If ${GCP_ACCOUNT} lacks roles/resourcemanager.projectIamAdmin or roles/owner and gcloud projects describe or service checks return PERMISSION_DENIED:
   • DO NOT stop with a vague error or ask the user to manually run setup scripts in their terminal.
   • Present the exact, copy-pasteable command for their Google Cloud Project Administrator:

     gcloud projects add-iam-policy-binding "$PROJECT_ID" \
       --member="user:$GCP_ACCOUNT" \
       --role="roles/owner"
     

   • Prompt the user interactively (using ask_question if available) to notify their administrator or switch accounts (gcloud config set account <admin-account>), then cleanly re-test and proceed with automated deployment.

3. Capsule / Sandbox Policy Detection:

   • If ${PROJECT_ID} starts with cpl-* or mpl-* (Google Cloud Capsule or restricted sandbox), inspect whether organizational policy constraints (such as constraints/run.allowedIngress or Service Directory restrictions) are active. Warn the user before data generation so expectations match sandbox capabilities.

Step 2.2 — Present the Demo Architecture & Data Model Plan

One message, six sections, in this order, then the gate. Every answer from Step 2.1 is already folded in — the brief states decisions, it does not ask for them, and it contains no "tell me which…" or "TBD" anywhere.

Write it in the demo's language (§ i18n above) — headings, table headers and prose alike. Only the technical identifiers stay English snake_case: table names, column names and .env keys.

Open with a title line naming the company and the selected scenario, so the brief is self-contained when it is pasted into a chat with a colleague:

🏗️ <Company> — Demo Architecture & Data Model Plan

Based on the selected scenario "<scenario>", here is the data layer design, the Mermaid ER diagram and the cross-source reconciliation lineage.

§ Brief section 1 — 🏢 Target Company & Demo Overview

• Company / group: official name, and the group entity the demo actually models.
• Industry: the specific one, in the company's own vocabulary.
• Demo narrative: 2-3 sentences following one business process instance (one problematic order, one flagged application) end to end, naming the departments it passes through. All 7 demo prompts later trace this same instance; see references/demo_prompts_guide.md §1.1-§1.2.
• Anchor persona: the persona confirmed in Step 2.1, stated as a fact ("the agent is operated by the production control manager of the main works"). If the user declined to name one, say that personas rotate instead — do not re-ask here.

§ Brief section 2 — 📊 Data Layer Design & Mermaid ER Diagram

• Render a Mermaid erDiagram in a ```mermaid fenced block: every table, every column with its type, PK/FK markers, cardinality labels on each relationship, and a short business gloss in quotes after each column (string order_id PK "order number (ORD-2026-XXXX)"). The gloss is the same sentence that later becomes the column description in the Knowledge Catalog, so writing it here is not duplicated work.
• Include the Firestore task collection as an entity too — it is part of the model the demo reasons over, even though it is not in BigQuery.
• Shared core-system model: design the tables as a slice of the company's system of record, not one team's dataset — a transactional table two departments both write, a rules/threshold table owned by one department that another's workflow must consult, and an audit seed visible only when the departments' views are joined. Details and the single-department escape hatch: references/data_generation.md §1.3.

§ Brief section 3 — 📁 External Sample Files & Cross-Source Lineage

Title this section after where the files will actually be, not after where people assume they go. Cloud Storage is the only guaranteed destination (below), so a heading that says "Google Drive" is wrong in every run whose token lacks the Drive scope — and it was, in most of them.

A table with one row per external file — type, filename, and what binds it to BigQuery:

State the join key explicitly. A lineage row that says "related to orders" is not a design — the whole point of the external files is that a question can only be answered by reading a document and querying a table, and that only works if the keys line up (70%+ FK match, 5-15% audit variance). See references/external_files_and_drive.md.

Close the section with where the files will actually live, in one line, because it is the part users assume wrongly. Write the line that matches the DRIVE_OK read above:

The Cloud Storage staging happens in both mcp and rag mode; the deploy-time upload is the only path into any Drive. The deployed agent has no way to put them in anyone's Drive — v2.11.0 removed the in-conversation import, deliberately. If the user wants them in Drive and DRIVE_OK is not 200, say so here, while it can still be sorted out (gcloud auth login --enable-gdrive-access --no-launch-browser and re-run, or upload ./external_files/ by hand afterwards).

§ Brief section 4 — 🤖 Agent Profile & Runtime

• Agent Name (DEMO_DISPLAY_NAME): Concise 2–4 word domain role (e.g. TWG Tea Retail Operations Director, Mercari Trust & Safety Specialist). Registered in Gemini Enterprise as ${DEMO_DISPLAY_NAME} (${SERVICE_NAME}), matching the Web UI (GAS) version.
• Description (DEMO_DESCRIPTION): Concrete, professional 1–2 sentence mission summary specifying the business domain, core datasets, and operational goals (e.g. Orchestrates boutique inventory balancing, central commissary replenishment, and plantation harvest orders across Singapore.). Matches oneSentenceSummary in the Web UI (GAS).
• Reasoning / orchestration: gemini-3.8-flash for all agent instances (Root Coordinator, Deep Analysis Sub-Agent, Background Worker).
• Image generation: gemini-3.1-flash-image (with localized prompt reinforcement and GCS artifact persistence).
• Code execution: Agent Engine Sandbox (us-central1 — fixed, not $REGION).
• UI: Gemini Enterprise A2UI v0.9 composite catalog (name the components this demo will actually lean on — MaterialTable, VegaChart, MaterialCard).

§ Brief section 5 — ⚙️ Deployment Target Environment

Show what the commands above returned, verbatim, in a fenced block:

👤 Active User Account : ${GCP_ACCOUNT}
🏢 Target Project      : ${PROJECT_ID} (${PROJECT_NUMBER})
🌐 Target Region       : ${REGION}
🛡️ Deployer IAM Status  : Verified (Owner/Admin) / Auto-healed
🗂️ Sample File Storage : gs://${PROJECT_ID}-<domain>-<suffix>-docs/
📁 Google Drive Copy   : <the DRIVE_OK line, below>

This is the section users most often stop on, because the answer is frequently "wrong project". Do not paraphrase the values and do not print a project the user named unless gcloud agrees — the deploy will use what gcloud says, not what the brief claims.

Both storage lines are mandatory, and neither is optional wording: the Cloud Storage bucket is created in every mode, and the Drive line is the one users read as a promise. Write it from DRIVE_OK, never from intent:

Never print a Drive destination the deploy cannot reach, and never describe the copy as something the agent will do later — nothing after the deploy writes to a Drive. See references/external_files_and_drive.md §5.

§ Brief section 6 — 🎛️ Advanced Settings & Integrations

State the settings this demo will deploy with — the answers from Step 2.1, plus the defaults for everything the user did not touch. These names are the .env keys, upper-snake-cased: enableManagedAgent is ENABLE_MANAGED_AGENT. Every one of them is a real switch in the deployed container, so an option discussed here but not written to .env is a feature the demo will not have.

List all eleven, every time, in this order, with the value this deploy will use in the second column — ✅ true / ❌ false / the literal value / — (unset). An option the brief leaves out is an option the user cannot ask for: they do not know it exists, and by the time the deploy banner mentions it the 15-30 minutes are already spent. The gate is the last cheap moment to turn one on, so the gate has to show the whole board. Keep the third column as written here — it is what makes a false decidable rather than merely visible — and reword only where this demo's scenario changes what an option would buy.

Only list the options that are on, plus the two or three the demo is a plausible candidate for. A user reading eight defaults they did not ask about is a user who skims the whole brief.

One more switch, and it is deliberately not in that table — it is not an .env key and it changes nothing inside the container. Cloud Run scales this demo to zero when nobody is talking to it, which is why an idle demo costs nothing, and why the first message after an idle gap waits ~20-25s for a cold start and can come back as an error instead: Cloud Run sometimes refuses a request outright while the container is still starting. Deploying with MIN_INSTANCES=1 — the environment variable setup_and_deploy.sh reads in Step 4/6, exported before the deploy runs — keeps one instance always up and removes both.

State it as a line under the table when you offer it, with the price attached rather than in a footnote:

🔥 Warm instance — MIN_INSTANCES=1 · default 0 (scale-to-zero). No cold start and no cold-start error on the first message. Cost: one 8 GiB / 2 vCPU instance is then billed continuously for as long as the demo exists — not just during the presentation.

The honest default is 0: for a demo deployed now and shown next week, sending the first message twice is far cheaper than a week of idle billing. It is also not a decision that has to be made now — it is read at deploy time, so re-running the deploy with the variable set (or unset) flips an existing demo either way.

§ The gate — ask once, then stop

Close the message by triggering an interactive approval and option selection modal using the ask_question tool (with plain text fallback only if ask_question is not supported in the active environment). This allows the user to review all capabilities and toggle any extra features directly:

• Call ask_question with is_multi_select: true:

  • question: "Do you approve this architecture and deployment plan? Select '(Recommended) Proceed with default configuration' to start deployment immediately, or check any additional options you want enabled:" (in the demo's language)
  • options:
    1. "(Recommended) Proceed with default configuration (Managed Agent: Enabled, Cloud Trace Telemetry: Enabled, other options: default)"
    2. "🛡️ Enable Model Armor Guardrails (Auto-provisions and binds ge-demo-default-armor in us-central1 for jailbreak defense and PII masking)"
    3. "🔑 Enable Google Workspace OAuth (Drive/Slides/Docs export as signed-in user)"
    4. "🔎 Enable RAG Data Exploration Mode (Build Discovery Engine search index for document & table reads)"
    5. "📁 Enable Firestore DataStore (Semantic search over historical tickets & SOPs in RAG mode)"
    6. "🔥 Enable Warm Instance (Cloud Run min-instances=1 to eliminate cold-start delay)"
    7. "🖥️ Enable Computer Use (Gemini 3.8 Flash Chromium browser automation)"
    8. "📈 Enable Enterprise Data Scale (Grow fact tables to thousands of rows via amplify_data.py)"
    9. "📡 Disable Cloud Trace Telemetry (Opt-out from OpenTelemetry token & latency tracking)"

• In non-interactive or headless environments where ask_question is unavailable, output the equivalent choices in chat text and pause for user reply.

• When the user selects options, update .env (ENABLE_MODEL_ARMOR=1, ENABLE_WORKSPACE_AUTH=1, ENABLE_CLOUD_TELEMETRY=0, DATA_EXPLORATION_MODE=rag, etc.) and deployment flags accordingly before proceeding to Phase 3.

Then stop and wait. Do not start Phase 3 in the same turn, and do not treat "looks good" on a previous message — the scenario choice in Phase 1 or an answer in Step 2.1 — as approval of this brief.

When the user changes something, re-render the affected sections and ask again; an approved brief is the specification the rest of the run is built from, so it has to be the version the user actually said yes to.

Phase 3: Synthetic Data & External Sample Files Generation + Google Drive Upload

Entry condition: the Phase 2 brief was presented in full and the user approved it. If you arrive here without that, go back and present it.

1. Derive the demo's identifiers, concrete name, and description:

   SUFFIX=$(date +%s | tail -c 5)
   DEMO_ID="${DOMAIN_SLUG}-${SUFFIX}"
   SERVICE_NAME="ge-demo-${DOMAIN_SLUG}-${SUFFIX}"
   DATASET_ID="demo_${DOMAIN_SLUG}_${SUFFIX}"
   FIRESTORE_COLLECTION="demo-${DOMAIN_SLUG}-${SUFFIX}-tasks"
   
   # Set concrete, domain-specific display name & description (matching Web UI / GAS version)
   DEMO_DISPLAY_NAME="${COMPANY_NAME} ${AGENT_ROLE:-Operations Specialist}"
   DEMO_DESCRIPTION="Orchestrates ${SCENARIO_SUMMARY:-operations and intelligent data analytics} across ${COMPANY_NAME}."
   

   Always write DEMO_DISPLAY_NAME and DEMO_DESCRIPTION into .env so setup_and_deploy.sh and register_agent.py register the agent with concrete domain details.

2. Generate Real-World Synthetic Data & Display Previews:

   • Generate CSV files with realistic addresses, valid foreign keys across tables, and varied statuses in data/<table_name>.csv.
   • Ensure all string data is generated in the detected target language.
   • Run validation script: python3 scripts/validate_csv.py data/*.csv.
   • Render Dataset Preview & Record Counts: Output a Dataset Summary Table with total generated record counts for each BigQuery table, Firestore collection, and external Drive file, followed by 3–5 representative sample rows per table in clean Markdown preview tables (or <carousel> sliders) clearly indicating the total row count in each table title.
   • Write one line of grain per table into data/<table_name>_description.txt ("one row per POS transaction line", "one row per store"). The deploy folds it, the column descriptions from data/<table_name>_schema.json, the row counts and the real date range of every date column into adk_agent/app/data_assets.md — the DATA ASSET CATALOG the agent's prompt is written around. Skipping the grain line costs only that line; skipping the column descriptions costs the agent its schema.

2b. Amplify to Demo Volume (only when dataScale was agreed in Phase 2):

• Do not try to write thousands of rows yourself. Write the 50-200 hero rows as above — the ones the demo prompts name by id — and let the amplifier expand the tables around them. It resamples each column from what the hero rows already show, draws foreign keys from the parent table's amplified key set, and keeps the hero rows verbatim at the top of every file, so every id a prompt refers to still resolves.
• Write data/data_scale_spec.json with a per-table target_rows map. Describe a column only where the hero rows misrepresent it — in practice that means date columns, because hand-written rows cluster into one week while the narrative spans a fiscal year. Everything you leave out is inferred. See the module docstring of scripts/amplify_data.py for the format and for the two things the spec will not do.

  python3 scripts/amplify_data.py --data-dir ./data --spec ./data/data_scale_spec.json
  for f in data/*.csv; do case "$f" in *.hero.csv) ;; *) python3 scripts/validate_csv.py "$f" ;; esac; done
  

• Alternatively set DATA_SCALE=<rows> in .env and let the deploy run it: the step is idempotent and deterministic, so doing it in both places is harmless.
• Report the amplified counts in the Dataset Summary Table, and say which tables were left at hero size — master data that the narrative describes as small must stay small.
• python3 scripts/amplify_data.py --data-dir ./data --restore puts the hero CSVs back.

3. Generate External Sample Files & Upload Directly to Google Drive:
   • Synthesize external demo files in ./external_files/:
     1. PDF Audit Report (<domain>_audit_report.pdf): Multi-section structured document in target language with summary, details, and intentional 5-15% variance from BigQuery to trigger cross-source reasoning.
     2. Excel Spreadsheet Ledger (<domain>_external_ledger.xlsx): Semi-structured workbook with localized KPI headers, units, and 40-80 transaction rows with FK references matching BigQuery tables.
     3. Simulated Operational Document Images (handwritten_order_1.jpg, handwritten_order_2.jpg): Realistic scanned forms generated via gemini-3.1-flash-image with localized text.
   • Upload to Google Drive:

     uv run --no-project \
       --with "openpyxl>=3.1.0,<4.0.0" \
       --with "reportlab>=4.0.0,<6.0.0" \
       --with "pillow>=10.0.0,<13.0.0" \
       python3 scripts/generate_and_upload_external_files.py \
       --domain "$DOMAIN_SLUG" \
       --company "$COMPANY_NAME" \
       --suffix "$SUFFIX" \
       --outdir "./external_files" \
       --spec-file "./data/external_files_spec.json"
     

     • --spec-file carries THIS demo's content (titles, sections, table rows, and the style wording for the scanned forms), written in the demo's own language and domain. Without it the script emits generic placeholder documents - it holds no built-in industry content by design.
     • Creates dedicated Drive folder: GE Demo - <Company Name> (<Suffix>), reusing one of that name if a previous run already made it.
     • Uploads .pdf, .xlsx, and .jpg files.
     • Saves links to external_files/drive_upload_summary.json and creates .url.json artifacts.
     • The folder is owned by ${GCP_ACCOUNT} — the upload is a Drive v3 REST call carrying this machine's own gcloud access token, so the account deploying the demo owns what it creates and nothing has to be shared with it. Report that owner and the folder URL. The script also asks for "anyone with the link (Reader)" as a convenience; plenty of organizations refuse it, in which case the summary carries share_error and the banner notes ℹ️ LINK SHARING OFF — the owner can still open everything, so this is a footnote, not a failure.
     • When the token has n

…(truncated)