looker-demo-cli 0.1.0__tar.gz

looker_demo_cli-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,35 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  pypi-publish:
+    name: Build and upload to PyPI
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write # Required for PyPI Trusted Publishing
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build package distributions
+        run: uv build
+
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

looker_demo_cli-0.1.0/.gitignore

@@ -0,0 +1,41 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual Environments
+.venv/
+env/
+venv/
+ENV/
+
+# Testing & Coverage
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Logs & Temporary Files
+*.log
+scratch/
+tmp/
+.temp/
+.DS_Store
+.env
+.env.local

looker_demo_cli-0.1.0/AGENTS.md

@@ -0,0 +1,36 @@
+# Agent Instructions for `demo-create`
+
+## Role & Mission
+You are the Looker Demo Architect Agent. Your mission is to assist users in designing, synthesizing, modeling, and deploying comprehensive data demos on Looker and Embedded Analytics.
+
+## Workflow Rules
+1. **Always run `pre-check` first**:
+   Execute `demo-create pre-check --fix` (or `uv run demo-create pre-check --fix`) to ensure BigQuery credentials, GCP projects, MCP servers, and intent-based skills are configured.
+
+2. **Verify GCP Authentication & Confirm Target Project**:
+   - **GCP Re-authentication Prompt**: If the pre-check report or any BigQuery operation indicates that reauthentication is required (`reauth_required: true`, token expiry, or authentication errors), the agent **MUST prompt the user** to reauthenticate by providing the exact shell commands:
+     ```bash
+     gcloud auth login
+     gcloud auth application-default login
+     ```
+     Do NOT attempt to bypass or guess invalid credentials.
+   - **Project Confirmation**: The agent **MUST prompt the user to confirm/select which Google Cloud Project to use** from the available projects returned in pre-check (or via `gcloud projects list`) BEFORE creating datasets, querying BigQuery, or running workflows.
+
+3. **Follow the deterministic decision tree**:
+   - Check if dataset exists in BigQuery for the selected project.
+   - If dataset exists: Ask user whether to Augment (generate linked tables) or Model LookML Only.
+   - If greenfield: Run iterative schema design with micro-sample validation before high-volume generation.
+   - Confirm Internal Looker Demo vs External Embedded Portal scope.
+
+4. **LookML Quality & Field Documentation Standards**:
+   - **Mandatory Labels & Descriptions**: All LookML view files (`.view.lkml`) **MUST include explicit `label:` and `description:` parameters** on every dimension, dimension group, and measure to ensure self-documenting Explores for business users.
+   - **Measures & Drill Fields**: Include formatted primary metrics (sum, average, count distinct) with `value_format_name` (e.g. `usd_0`, `percent_2`, `decimal_1`) and drill-down fields.
+
+5. **LookML Validation Gate (`lkr-dev-cli`)**:
+   - **Validate Before Deploy**: When LookML files are pushed to the Looker dev branch (`dev`), the agent **MUST execute the LookML validator** (via `lkr` CLI / `validate_project`) to catch and self-heal any syntax or join errors before committing and deploying.
+   - **Production Deployment**: Only proceed to production deployment (`lkr --dev tools lookml push ... --deploy` or `deploy_to_production`) after the LookML validator passes with 0 errors.
+
+6. **Use Intent Skills**:
+   - For schema design & synthetic data generation, reference skills in `skills/data-design/` (`data-designer`, `data-designer-architect`).
+   - For LookML views, explores, and dashboards, reference skills in `skills/lookml/` (`repo-lookml`, `lookml-model`, `lookml-dashboard`).
+   - For frontend embed configuration, reference skills in `skills/embed-portal/` (`setup-embed-demo`, `customize-frontend`).

looker_demo_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 lkrdev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

looker_demo_cli-0.1.0/PKG-INFO

@@ -0,0 +1,168 @@
+Metadata-Version: 2.5
+Name: looker-demo-cli
+Version: 0.1.0
+Summary: Deterministic Looker Demo Orchestrator CLI for synthetic data generation, BigQuery upload, LookML modeling, and Embedded Portal scaffolding.
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: faker>=24.0.0
+Requires-Dist: google-auth>=2.29.0
+Requires-Dist: google-cloud-bigquery>=3.20.0
+Requires-Dist: lkr-dev-cli>=0.0.50
+Requires-Dist: looker-sdk>=24.4.0
+Requires-Dist: numpy>=1.26.0
+Requires-Dist: pandas>=2.2.0
+Requires-Dist: pyarrow>=15.0.0
+Requires-Dist: pydantic>=2.7.0
+Requires-Dist: python-dotenv>=1.0.1
+Requires-Dist: questionary>=2.0.1
+Requires-Dist: rich>=13.7.0
+Requires-Dist: typer>=0.12.0
+Description-Content-Type: text/markdown
+
+# Looker Demo Creator (`demo-create`)
+
+> **Automated, deterministic orchestrator for creating end-to-end Looker demos, synthetic BigQuery datasets, LookML semantic models, and Embedded Analytics portals.**
+
+---
+
+## Overview
+
+`demo-create` is a developer and AI agent tool that unifies the end-to-end Looker demo creation lifecycle into a single workflow:
+1. **Pre-flight & Environment Audit (`pre-check`)**: Verifies active GCP/ADC accounts, installs/patches global MCP tools (`data-designer`, `bigquery`, `lkr_codemode`), and organizes agent skills into intent-based subfolders.
+2. **Dataset Decision & Synthesis**: Automatically checks for existing BigQuery datasets, enables data augmentation or green-field relational schema generation, and validates referential integrity.
+3. **BigQuery Loading**: Creates datasets and partitioned/clustered tables in BigQuery.
+4. **LookML Generation & Deployment**: Autogenerates production-ready views, explores, and executive dashboards, provisioning and deploying them directly to the Looker instance using `lkr-dev-cli`.
+5. **Embedded Portal Scaffolding**: Clones and configures a clean, dedicated `looker-embed-demo` workspace for external client demos.
+
+---
+
+## Quickstart & Execution
+
+### 1. Run Instantly with `uvx` (No Installation Required)
+
+Once published to PyPI or your package index, you can execute the CLI on-demand in an ephemeral, isolated environment without creating a virtual environment or pre-installing dependencies:
+
+```bash
+# Run directly from the package name
+uvx looker-demo-cli pre-check --fix
+
+# Or invoke the `demo-create` binary explicitly
+uvx --from looker-demo-cli demo-create pre-check --fix
+```
+
+#### Run with Options & Flags:
+```bash
+# Run pre-flight audit and auto-fix MCP / skills
+uvx looker-demo-cli pre-check --fix
+
+# Run end-to-end interactive demo creator
+uvx looker-demo-cli run --project=retail_analytics --scope=internal
+```
+
+---
+
+### 2. Install as a Persistent CLI Tool (`uv tool`)
+
+To make `demo-create` / `looker-demo-cli` globally available on your shell's `PATH`:
+
+```bash
+# Install the published package globally in an isolated environment
+uv tool install looker-demo-cli
+
+# Now you can run it directly anywhere:
+demo-create pre-check --fix
+# or
+looker-demo-cli pre-check --fix
+```
+
+To update to the latest version at any time:
+```bash
+uv tool upgrade looker-demo-cli
+```
+
+---
+
+### 3. Running from Local Source or Git (Development)
+
+If you are developing locally or testing before publishing:
+
+#### Run directly from local source directory:
+```bash
+# Run from repository root
+uvx --from . demo-create pre-check --fix
+
+# Or run from anywhere by pointing to the repository path
+uvx --from /path/to/looker-demo-cli demo-create pre-check --fix
+```
+
+#### Run directly from a Git repository:
+```bash
+uvx --from git+https://github.com/lkrdev/looker-demo-cli.git demo-create pre-check --fix
+```
+
+#### Local Editable Installation:
+```bash
+cd ~/looker-demo-cli
+uv venv
+uv pip install -e .
+```
+
+---
+
+## Commands & Usage
+
+### 1. Environment & Skill Audit (`pre-check`)
+```bash
+# Run visual audit of GCP credentials, MCP tools, and intent skills
+demo-create pre-check
+
+# Automatically install missing MCP configs and symlink skills into intent subfolders
+demo-create pre-check --fix
+
+# Emit raw JSON report for programmatic agent consumption
+demo-create pre-check --json
+```
+
+### 2. End-to-End Demo Creation (`run`)
+```bash
+# Interactive wizard
+demo-create run --project=retail_insights --scope=internal
+
+# Non-interactive / Agent Mode
+demo-create run \
+  --project=logistics_analytics \
+  --scope=external \
+  --gcp-project=my-analytics-project \
+  --gcp-account=user@example.com \
+  --agent-mode
+```
+
+---
+
+## Intent-Based Skill Organization
+
+When you run `demo-create pre-check --fix`, skills are organized into `~/.gemini/config/skills/`:
+
+```
+~/.gemini/config/skills/
+├── data-design/
+│   ├── data-designer/
+│   ├── data-designer-architect/
+│   ├── data-designer-engineer/
+│   └── data-designer-evaluator/
+├── lookml/
+│   ├── repo-lookml/
+│   ├── lookml-model/
+│   ├── lookml-explore/
+│   ├── lookml-view/
+│   ├── lookml-dashboard/
+│   └── embed-themes/
+└── embed-portal/
+    ├── setup-embed-demo/
+    ├── customize-frontend/
+    ├── customize-frontend-branding/
+    ├── customize-frontend-theme/
+    └── sso-embed/
+```
+
+This guarantees that any Jetski agent in any directory can discover and execute Looker demo workflows.

looker_demo_cli-0.1.0/README.md

@@ -0,0 +1,147 @@
+# Looker Demo Creator (`demo-create`)
+
+> **Automated, deterministic orchestrator for creating end-to-end Looker demos, synthetic BigQuery datasets, LookML semantic models, and Embedded Analytics portals.**
+
+---
+
+## Overview
+
+`demo-create` is a developer and AI agent tool that unifies the end-to-end Looker demo creation lifecycle into a single workflow:
+1. **Pre-flight & Environment Audit (`pre-check`)**: Verifies active GCP/ADC accounts, installs/patches global MCP tools (`data-designer`, `bigquery`, `lkr_codemode`), and organizes agent skills into intent-based subfolders.
+2. **Dataset Decision & Synthesis**: Automatically checks for existing BigQuery datasets, enables data augmentation or green-field relational schema generation, and validates referential integrity.
+3. **BigQuery Loading**: Creates datasets and partitioned/clustered tables in BigQuery.
+4. **LookML Generation & Deployment**: Autogenerates production-ready views, explores, and executive dashboards, provisioning and deploying them directly to the Looker instance using `lkr-dev-cli`.
+5. **Embedded Portal Scaffolding**: Clones and configures a clean, dedicated `looker-embed-demo` workspace for external client demos.
+
+---
+
+## Quickstart & Execution
+
+### 1. Run Instantly with `uvx` (No Installation Required)
+
+Once published to PyPI or your package index, you can execute the CLI on-demand in an ephemeral, isolated environment without creating a virtual environment or pre-installing dependencies:
+
+```bash
+# Run directly from the package name
+uvx looker-demo-cli pre-check --fix
+
+# Or invoke the `demo-create` binary explicitly
+uvx --from looker-demo-cli demo-create pre-check --fix
+```
+
+#### Run with Options & Flags:
+```bash
+# Run pre-flight audit and auto-fix MCP / skills
+uvx looker-demo-cli pre-check --fix
+
+# Run end-to-end interactive demo creator
+uvx looker-demo-cli run --project=retail_analytics --scope=internal
+```
+
+---
+
+### 2. Install as a Persistent CLI Tool (`uv tool`)
+
+To make `demo-create` / `looker-demo-cli` globally available on your shell's `PATH`:
+
+```bash
+# Install the published package globally in an isolated environment
+uv tool install looker-demo-cli
+
+# Now you can run it directly anywhere:
+demo-create pre-check --fix
+# or
+looker-demo-cli pre-check --fix
+```
+
+To update to the latest version at any time:
+```bash
+uv tool upgrade looker-demo-cli
+```
+
+---
+
+### 3. Running from Local Source or Git (Development)
+
+If you are developing locally or testing before publishing:
+
+#### Run directly from local source directory:
+```bash
+# Run from repository root
+uvx --from . demo-create pre-check --fix
+
+# Or run from anywhere by pointing to the repository path
+uvx --from /path/to/looker-demo-cli demo-create pre-check --fix
+```
+
+#### Run directly from a Git repository:
+```bash
+uvx --from git+https://github.com/lkrdev/looker-demo-cli.git demo-create pre-check --fix
+```
+
+#### Local Editable Installation:
+```bash
+cd ~/looker-demo-cli
+uv venv
+uv pip install -e .
+```
+
+---
+
+## Commands & Usage
+
+### 1. Environment & Skill Audit (`pre-check`)
+```bash
+# Run visual audit of GCP credentials, MCP tools, and intent skills
+demo-create pre-check
+
+# Automatically install missing MCP configs and symlink skills into intent subfolders
+demo-create pre-check --fix
+
+# Emit raw JSON report for programmatic agent consumption
+demo-create pre-check --json
+```
+
+### 2. End-to-End Demo Creation (`run`)
+```bash
+# Interactive wizard
+demo-create run --project=retail_insights --scope=internal
+
+# Non-interactive / Agent Mode
+demo-create run \
+  --project=logistics_analytics \
+  --scope=external \
+  --gcp-project=my-analytics-project \
+  --gcp-account=user@example.com \
+  --agent-mode
+```
+
+---
+
+## Intent-Based Skill Organization
+
+When you run `demo-create pre-check --fix`, skills are organized into `~/.gemini/config/skills/`:
+
+```
+~/.gemini/config/skills/
+├── data-design/
+│   ├── data-designer/
+│   ├── data-designer-architect/
+│   ├── data-designer-engineer/
+│   └── data-designer-evaluator/
+├── lookml/
+│   ├── repo-lookml/
+│   ├── lookml-model/
+│   ├── lookml-explore/
+│   ├── lookml-view/
+│   ├── lookml-dashboard/
+│   └── embed-themes/
+└── embed-portal/
+    ├── setup-embed-demo/
+    ├── customize-frontend/
+    ├── customize-frontend-branding/
+    ├── customize-frontend-theme/
+    └── sso-embed/
+```
+
+This guarantees that any Jetski agent in any directory can discover and execute Looker demo workflows.

looker_demo_cli-0.1.0/looker_demo_cli/__init__.py

@@ -0,0 +1,3 @@
+"""Looker Demo Orchestrator CLI (`demo-create`)."""
+
+__version__ = "0.1.0"

looker_demo_cli-0.1.0/looker_demo_cli/cli.py

@@ -0,0 +1,209 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Annotated, Optional
+import typer
+from rich.table import Table
+
+from looker_demo_cli.config import (
+    DEFAULT_GCP_PROJECT,
+    DEFAULT_LOOKER_INSTANCE_URL,
+    GEMINI_MCP_CONFIG,
+    GEMINI_SKILLS_DIR,
+)
+from looker_demo_cli.precheck.gcp_auth import inspect_gcp_accounts, list_available_gcp_projects
+from looker_demo_cli.precheck.looker_auth import check_looker_auth
+from looker_demo_cli.precheck.mcp_checker import check_mcp_servers, patch_mcp_config
+from looker_demo_cli.precheck.skills_organizer import audit_and_organize_skills
+from looker_demo_cli.utils.console import (
+    console,
+    print_banner,
+    print_error,
+    print_info,
+    print_step_header,
+    print_success,
+    print_warning,
+)
+from looker_demo_cli.workflow.runner import FlowRunner
+from looker_demo_cli.workflow.state import FlowState
+
+app = typer.Typer(
+    name="demo-create",
+    help="End-to-end Looker demo creation orchestrator CLI for AI agents and developers.",
+    no_args_is_help=True,
+)
+
+
+@app.command(name="pre-check")
+def pre_check(
+    fix: Annotated[bool, typer.Option("--fix", help="Automatically install missing MCP configs and organize global skills")] = False,
+    output_json: Annotated[bool, typer.Option("--json", help="Emit raw JSON status report for agent programmatic consumption")] = False,
+    gcp_project: Annotated[str, typer.Option("--gcp-project", help="Target Google Cloud Project ID")] = DEFAULT_GCP_PROJECT,
+):
+    """Inspect and configure GCP/ADC accounts, MCP server definitions, and intent-based skill subfolders."""
+    if not output_json:
+        print_banner("PRE-CHECK: ENVIRONMENT, MCP & SKILL AUDIT", f"Target GCP Project: {gcp_project}")
+
+    # 1. Inspect GCP & ADC
+    gcp_accounts = inspect_gcp_accounts(target_project=gcp_project)
+    
+    # 2. Query available GCP projects
+    available_projects = list_available_gcp_projects()
+
+    # 3. Check MCP Servers
+    mcp_statuses = check_mcp_servers()
+    if fix:
+        patch_mcp_config()
+        mcp_statuses = check_mcp_servers()
+
+    # 4. Organize Skills
+    skill_statuses = audit_and_organize_skills(fix=fix)
+
+    # 5. Check Looker Auth
+    looker_status = check_looker_auth()
+
+    # Determine if re-auth is needed
+    reauth_required = any(
+        (a.is_active and not a.has_bigquery_access) or ("reauth" in (a.error_message or "").lower())
+        for a in gcp_accounts
+    )
+
+    if output_json:
+        report = {
+            "gcp_accounts": [a.model_dump() for a in gcp_accounts],
+            "available_gcp_projects": available_projects,
+            "reauth_required": reauth_required,
+            "mcp_servers": [m.model_dump() for m in mcp_statuses],
+            "skills": [s.model_dump() for s in skill_statuses],
+            "looker_auth": looker_status.model_dump(),
+            "agent_instructions": {
+                "reauth_action": "If reauth_required is true, prompt the user to run 'gcloud auth login' and 'gcloud auth application-default login'.",
+                "project_confirmation": "Prompt the user to select or confirm their target GCP project from available_gcp_projects before proceeding.",
+            },
+        }
+        typer.echo(json.dumps(report, indent=2))
+        return
+
+    # Render Visual Summary
+    console.print("\n[bold cyan]1. GCP & ADC Credentials[/bold cyan]")
+    t_gcp = Table(show_header=True, header_style="bold blue")
+    t_gcp.add_column("Account", style="dim")
+    t_gcp.add_column("Active in gcloud")
+    t_gcp.add_column("BigQuery Access")
+    t_gcp.add_column("Notes")
+
+    for acc in gcp_accounts:
+        bq_label = "[green]YES[/green]" if acc.has_bigquery_access else "[red]NO[/red]"
+        active_label = "[green]ACTIVE[/green]" if acc.is_active else "[dim]INACTIVE[/dim]"
+        t_gcp.add_row(acc.account_id, active_label, bq_label, acc.error_message or "Valid")
+    console.print(t_gcp)
+
+    if reauth_required:
+        console.print("\n[bold red]⚠️  GCP Reauthentication Required[/bold red]")
+        console.print("[yellow]Agent & User Instruction:[/yellow] One or more active GCP accounts require reauthentication.")
+        console.print("Please prompt the user to run the following in their terminal:")
+        console.print("  [bold white]$ gcloud auth login[/bold white]")
+        console.print("  [bold white]$ gcloud auth application-default login[/bold white]")
+
+    console.print("\n[bold cyan]2. Available Google Cloud Projects[/bold cyan]")
+    if available_projects:
+        t_proj = Table(show_header=True, header_style="bold blue")
+        t_proj.add_column("Project ID", style="bold")
+        t_proj.add_column("Name")
+        t_proj.add_column("Project Number", style="dim")
+        for p in available_projects:
+            t_proj.add_row(p["project_id"], p["name"], p["project_number"])
+        console.print(t_proj)
+        print_info("Agent Instruction: Confirm with the user which of the available GCP projects above to use for demo synthesis and BigQuery datasets.")
+    else:
+        print_warning("No Google Cloud projects found or `gcloud projects list` returned empty.")
+
+    console.print("\n[bold cyan]3. Global MCP Tool Configurations[/bold cyan]")
+    t_mcp = Table(show_header=True, header_style="bold blue")
+    t_mcp.add_column("MCP Server")
+    t_mcp.add_column("Status")
+    t_mcp.add_column("Details")
+
+    for m in mcp_statuses:
+        status_label = "[green]CONFIGURED[/green]" if m.is_configured else "[red]MISSING[/red]"
+        details = ", ".join(m.issues) if m.issues else "Ready"
+        t_mcp.add_row(m.server_name, status_label, details)
+    console.print(t_mcp)
+
+    console.print("\n[bold cyan]4. Intent-Organized Agent Skills (~/.gemini/config/skills/)[/bold cyan]")
+    t_skills = Table(show_header=True, header_style="bold blue")
+    t_skills.add_column("Intent Category")
+    t_skills.add_column("Skill Name")
+    t_skills.add_column("Installed")
+    t_skills.add_column("Source Found")
+
+    for s in skill_statuses:
+        inst_label = "[green]YES[/green]" if s.is_installed else "[yellow]NO[/yellow]"
+        src_label = "[green]YES[/green]" if s.is_valid else "[red]NOT FOUND[/red]"
+        t_skills.add_row(s.category, s.skill_name, inst_label, src_label)
+    console.print(t_skills)
+
+    console.print("\n[bold cyan]5. Looker Instance Authentication[/bold cyan]")
+    if looker_status.is_authenticated:
+        print_success(f"Connected to {looker_status.instance_url} as {looker_status.user_name} ({looker_status.user_email})")
+        if looker_status.has_default_bigquery_conn:
+            print_success("Database connection `default_bigquery_connection` is configured.")
+        else:
+            print_warning("Connection `default_bigquery_connection` not found in available connections.")
+    else:
+        print_error(f"Failed to connect to Looker: {looker_status.error_message}")
+
+    if not fix and any(not m.is_configured for m in mcp_statuses):
+        print_info("\nTip: Run `demo-create pre-check --fix` to automatically repair missing MCP configs and organize skills.")
+
+
+@app.command(name="run")
+def run_flow(
+    project_name: Annotated[str, typer.Option("--project", help="Looker project and dataset name")] = "logistics_analytics",
+    dataset_name: Annotated[Optional[str], typer.Option("--dataset", help="Target BigQuery dataset ID")] = None,
+    scope: Annotated[str, typer.Option("--scope", help="Demo scope: internal or external")] = "internal",
+    gcp_project: Annotated[str, typer.Option("--gcp-project", help="Target GCP Project ID")] = DEFAULT_GCP_PROJECT,
+    gcp_account: Annotated[Optional[str], typer.Option("--gcp-account", help="Specific authenticated GCP user account")] = None,
+    scratch_dir: Annotated[Path, typer.Option("--scratch-dir", help="Local scratch work directory")] = Path.home() / "scratch" / "demo_create",
+    agent_mode: Annotated[bool, typer.Option("--agent-mode", help="Non-interactive execution mode for AI agents")] = False,
+):
+    """Execute the full deterministic demo creation workflow."""
+    ds_name = dataset_name or project_name
+    demo_scope_val = "external_embed" if "ext" in scope.lower() else "internal_looker"
+
+    state = FlowState(
+        gcp_project_id=gcp_project,
+        gcp_account=gcp_account,
+        looker_project_name=project_name,
+        lookml_model_name=project_name,
+        bq_dataset_id=ds_name,
+        demo_scope=demo_scope_val,
+    )
+
+    runner = FlowRunner(
+        state=state,
+        scratch_dir=scratch_dir,
+        target_base_dir=Path.home(),
+    )
+
+    final_state = runner.run()
+    if final_state.status == "completed":
+        print_success("\nDemo creation finished successfully!")
+        if final_state.deployed_dashboard_url:
+            print_info(f"Dashboard URL: {final_state.deployed_dashboard_url}")
+        if final_state.embed_workspace_dir:
+            print_info(f"Embed Workspace: {final_state.embed_workspace_dir}")
+
+
+@app.command(name="skills")
+def list_skills(
+    fix: Annotated[bool, typer.Option("--fix", help="Symlink and organize skills into intent subfolders")] = False,
+):
+    """View and manage intent-based global agent skills."""
+    statuses = audit_and_organize_skills(fix=fix)
+    print_success(f"Organized {len(statuses)} skills across intent categories into {GEMINI_SKILLS_DIR}")
+
+
+if __name__ == "__main__":
+    app()